Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

Use the private package's public software-factory/provider-guidance-tools entry in Node 26.8.1 or later. There are no runtime npm dependencies. This two-tool handler, accepted locally on 1 October 2026, works over the actual Guidance receiver, with original proposal ownership. It is not a listener, SDK or authentication default.

Your host must qualify the exact actual Journal, ownership reader, registry, clock and common physical authority fence described by the receiver guide. Supply those public receiver Options once. Construction captures their one commission and makes no read or write. This importable example deliberately takes the caller's qualified ports and current authenticated context:

import {ProviderGuidanceTools} from 'software-factory/provider-guidance-tools';
export function guidanceTools(receiverOptions) {
  const adapter = new ProviderGuidanceTools({receiverOptions});
  return {
    definitions: adapter.tools(),
    call(name, argumentsFromClient, authenticatedContext) {
      return adapter.call(name, argumentsFromClient, authenticatedContext);
    },
  };
}

Route only factory_inspect_guidance_offer and factory_apply_guidance_offer. Arguments are exactly {identity:{logicalOperationId,generation,commandId,payloadDigest}}, matching the commissioned original generation. Separately derive {actorId,productId} from validated current credentials; never copy that context from model arguments or request metadata. Extra fields refuse. The caller owns MCP negotiation, duplicate-aware raw JSON, valid UTF-8, bounded request bytes, nonbatch routing, request IDs, session validity and response delivery. _meta, progress tokens, task augmentation and arbitrary tool dispatch are unsupported by this binding.

A handled result has one canonical JSON text block and identical structuredContent. Preserve both without rewriting witness fields. receiver-outcome keeps the receiver's complete recorded, not-recorded, refused or unknown outcome. Apply cannot yield not-recorded. Recorded is historical domain evidence, not current desired state or authority for further work; even a refusal can retain a current-read-authorised historicalWitness. Not-recorded does not exclude an old future write. Every outcome forbids replacement.

adapter-refused means this invocation did not start the receiver; it says nothing about earlier effects. receiver-result-unobserved means the invoked receiver's result was unavailable: apply may have recorded its original effect, while inspect was read-only. Reconcile using only the original identity under current read authority. Never manufacture a new command, expected revision, allowance or deadline from isError. Cancellation, timeout, disconnect and lost acknowledgement do not roll back Guidance or release proposal ownership.

Keep actor mapping/current authority and the receiver's locked checks intact. A known original receipt may replay after write permission expires, under current read permission; a new write also needs current write/source admission, original time, offered state and expected revision. Admission time is not a physical commit deadline. Native synchronous store waits have the receiver's qualified bounds; this adapter cannot pre-empt them. Ignore a late response from an abandoned session rather than attaching it to a reused request ID.

One active invocation is permitted; re-entry refuses busy without queueing. Limits are 1,024 bytes of arguments, 512 of context, 2,048 of commission, depth 24, 4,096 of canonical structured result and 20,480 of complete handler output. Malformed/oversized output is refused as unobserved without truncation. Plain own JSON is required. Bounded traversal observes native Promises in own data-descriptor values, including symbols, without accepting asynchronous permission or invoking generic thenables. Descriptor operations can invoke Proxy traps; native Promise.prototype.then can read constructor and Symbol.species and run host code. Fixed output never includes private Guidance values, raw exceptions, URLs or credentials.

Inspect advertises readOnlyHint true, destructiveHint false; apply advertises false/true. Both advertise idempotentHint true, openWorldHint false and taskSupport forbidden. These describe the original-command semantics and confer no permission. Qualify the actual host's Tools response, session and authentication separately; publication and live model acceptance remain separate gates. No delivery, notification, new inbox, model invocation, ownership mutation or release is implemented.

Fulfilment values and rejection reasons share the original observation allowance, including depth and tracker. Native Promise own properties are skipped after attaching reactions. Later-settlement faults are contained; synchronous traversal faults reach the owning refusal classifier. Fulfilment is never awaited as permission, cannot change a returned refusal or possible-effect classification, and cannot trigger another receiver call. Strict tests distinguish direct public input/options boundaries from instrumented malformed result controls.

Source: docs/how-to/adopt-provider-guidance-tools.md