@agenticprimitives/orchestration 0.0.0-alpha.1 → 0.0.0-alpha.3

package/dist/trace-context.d.ts

@@ -0,0 +1,26 @@
+/** The parsed `traceparent`. Ids are lowercase hex, W3C-sized (16-byte trace, 8-byte span). */
+export interface TraceContextV1 {
+    traceId: string;
+    parentSpanId: string;
+    /** The `traceparent` flags byte (`01` = sampled). Carried, never acted on. */
+    flags: string;
+    /** The `tracestate` header verbatim, when one arrived. Opaque to this substrate except its own `ap` member. */
+    tracestate?: string;
+}
+/** Parse a `traceparent` header per W3C Trace Context level 2: version `00` (a higher version is read with
+ *  the same first four fields), non-zero trace and span ids. Anything else is `null` — never a partial. */
+export declare function parseTraceparent(header: string | null | undefined): Omit<TraceContextV1, 'tracestate'> | null;
+/** The `traceparent` this run puts on an OUTBOUND hop: our trace, the current span as the parent. */
+export declare function formatTraceparent(traceId: string, spanId: string, opts?: {
+    sampled?: boolean;
+}): string;
+/** `tracestate` with this substrate's member set (`ap=<value>`) at the front — W3C: a vendor updating its
+ *  member moves it to the left, the list is capped at 32 members, and foreign members are kept verbatim. */
+export declare function withTracestateMember(existing: string | null | undefined, key: string, value: string): string;
+/** This substrate's member of a `tracestate`, when present. */
+export declare function tracestateMember(state: string | null | undefined, key: string): string | null;
+/** What an inbound request carried, as the run records it — or `null` when it carried nothing usable. */
+export declare function traceContextOf(headers: {
+    get(name: string): string | null;
+}): TraceContextV1 | null;
+//# sourceMappingURL=trace-context.d.ts.map

package/dist/trace-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.d.ts","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"AAUA,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,+GAA+G;IAC/G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;2GAC2G;AAC3G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG,IAAI,CAU7G;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAG3G;AAED;4GAC4G;AAC5G,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK5G;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM7F;AAED,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,cAAc,GAAG,IAAI,CAKnG"}

package/dist/trace-context.js

@@ -0,0 +1,59 @@
+// W3C TRACE CONTEXT — spec 390 W2. The wire form of "these hops are one causal operation": `traceparent`
+// (version-traceId-parentSpanId-flags) and `tracestate` (vendor members). Pure; nothing here touches a
+// header object, a fetch or a store — the app reads and writes the headers and hands strings in.
+//
+// CORRELATION, NEVER TRUST. A `traceparent` that arrives with a request joins the run's spans to the
+// caller's trace. That is all it does. Admission does not read it, a verdict does not read it, and a
+// forged one can at most mis-file a trace — the authority twin in `trace-context.test.ts` proves the
+// verdicts of a run are identical with and without one. An absent or malformed header means the run's
+// ids DERIVE from its references (spec 381 W2): a fact about the input, not an escalation (ADR-0013).
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+/** Parse a `traceparent` header per W3C Trace Context level 2: version `00` (a higher version is read with
+ *  the same first four fields), non-zero trace and span ids. Anything else is `null` — never a partial. */
+export function parseTraceparent(header) {
+    const raw = (header ?? '').trim().toLowerCase();
+    // A future version may append fields after the flags; read the first four and ignore the rest.
+    const head = raw.startsWith('00-') ? raw : raw.replace(/^([0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}).*$/, '$1');
+    const m = TRACEPARENT.exec(head);
+    if (!m)
+        return null;
+    const [, version, traceId, parentSpanId, flags] = m;
+    if (version === 'ff')
+        return null; // reserved
+    if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+        return null;
+    return { traceId: traceId, parentSpanId: parentSpanId, flags: flags };
+}
+/** The `traceparent` this run puts on an OUTBOUND hop: our trace, the current span as the parent. */
+export function formatTraceparent(traceId, spanId, opts = {}) {
+    if (!/^[0-9a-f]{32}$/.test(traceId) || !/^[0-9a-f]{16}$/.test(spanId))
+        throw new Error(`traceparent needs a 32-hex trace id and a 16-hex span id, got ${traceId}/${spanId}`);
+    return `00-${traceId}-${spanId}-${opts.sampled === false ? '00' : '01'}`;
+}
+/** `tracestate` with this substrate's member set (`ap=<value>`) at the front — W3C: a vendor updating its
+ *  member moves it to the left, the list is capped at 32 members, and foreign members are kept verbatim. */
+export function withTracestateMember(existing, key, value) {
+    if (!/^[a-z][a-z0-9_\-*/]{0,255}$/.test(key))
+        throw new Error(`tracestate key must be a W3C key, got ${JSON.stringify(key)}`);
+    const v = value.replace(/[^\x20-\x7e]/g, '').replace(/[,=]/g, '_').trim();
+    const others = (existing ?? '').split(',').map((s) => s.trim()).filter((s) => s && !s.startsWith(`${key}=`));
+    return [`${key}=${v}`, ...others].slice(0, 32).join(',');
+}
+/** This substrate's member of a `tracestate`, when present. */
+export function tracestateMember(state, key) {
+    for (const m of (state ?? '').split(',')) {
+        const t = m.trim();
+        if (t.startsWith(`${key}=`))
+            return t.slice(key.length + 1);
+    }
+    return null;
+}
+/** What an inbound request carried, as the run records it — or `null` when it carried nothing usable. */
+export function traceContextOf(headers) {
+    const parent = parseTraceparent(headers.get('traceparent'));
+    if (!parent)
+        return null;
+    const state = (headers.get('tracestate') ?? '').trim();
+    return { ...parent, ...(state ? { tracestate: state.slice(0, 512) } : {}) };
+}
+//# sourceMappingURL=trace-context.js.map

package/dist/trace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,uGAAuG;AACvG,iGAAiG;AACjG,EAAE;AACF,qGAAqG;AACrG,qGAAqG;AACrG,qGAAqG;AACrG,sGAAsG;AACtG,sGAAsG;AAYtG,MAAM,WAAW,GAAG,6DAA6D,CAAC;AAElF;2GAC2G;AAC3G,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAChE,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAChD,+FAA+F;IAC/F,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,yDAAyD,EAAE,IAAI,CAAC,CAAC;IACxH,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,CAAC,WAAW;IAC9C,IAAI,MAAM,CAAC,IAAI,CAAC,OAAQ,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,YAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,OAAO,EAAE,OAAQ,EAAE,YAAY,EAAE,YAAa,EAAE,KAAK,EAAE,KAAM,EAAE,CAAC;AAC3E,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,MAAc,EAAE,OAA8B,EAAE;IACjG,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iEAAiE,OAAO,IAAI,MAAM,EAAE,CAAC,CAAC;IAC7K,OAAO,MAAM,OAAO,IAAI,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3E,CAAC;AAED;4GAC4G;AAC5G,MAAM,UAAU,oBAAoB,CAAC,QAAmC,EAAE,GAAW,EAAE,KAAa;IAClG,IAAI,CAAC,6BAA6B,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9H,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1E,MAAM,MAAM,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;IAC7G,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,gBAAgB,CAAC,KAAgC,EAAE,GAAW;IAC5E,KAAK,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACnB,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,cAAc,CAAC,OAA6C;IAC1E,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC"}

package/dist/types.d.ts

@@ -11,6 +11,7 @@ export interface Intent {
     context?: Record<string, unknown>;
 }
 /** A capability the agent MAY compose. The planner picks from these; the loop refuses any other tool id. */
+export type OutcomeClass = 'lookup' | 'submission' | 'authoritative';
 export interface ToolSpec {
     /** Stable tool id (matches the invoker's dispatch key, e.g. an MCP tool name). */
     id: string;
@@ -18,6 +19,114 @@ export interface ToolSpec {
     description: string;
     /** Optional JSON-Schema for the tool's args (the LLM planner uses it as the tool-use input schema). */
     inputSchema?: Record<string, unknown>;
+    /**
+     * Spec 350 §3.1 — the capability this tool EXERCISES (ADR-0051 id). Declared on the TOOL, never on the
+     * plan: a planner that emits a step for this tool cannot describe its way out of needing authority.
+     * Absent ⇒ informational, no mandate needed. `resourceArg` names the arg that holds the resource the
+     * step acts on (the org, the token) so the verifier can bound it.
+     *
+     * `authorityArg` names the arg holding the party whose AUTHORITY the step needs — which is not always
+     * the resource. Chartering a team acts on the workspace and needs the workspace's authority (the same
+     * address); paying acts on a TOKEN and needs the PAYER's authority (a different one). Absent ⇒ the
+     * resource, then whoever was addressed. Getting this wrong asks a person to grant authority as an
+     * ERC-20 contract, which nothing can sign.
+     */
+    capability?: {
+        id: string;
+        action: string;
+        resourceArg?: string;
+        authorityArg?: string;
+    };
+    /**
+     * Spec 366 — the argument naming the agent this act is ABOUT and is ANSWERED BY. When it resolves to an
+     * agent other than the one addressed, the step is not run here: it is routed to that agent's own
+     * harness, which verifies the asker's standing itself and answers under its own playbook. Declared on
+     * the tool (from the contract), never inferred from the sentence. Absent ⇒ the addressee answers.
+     */
+    subject?: string;
+    /**
+     * Spec 367 W1 — the IMPERATIVES that name this act ("send", "pay", "create a team"). A sentence that opens
+     * with one is an instruction, and plan admission refuses a plan for it that contains no act. Declared
+     * beside the capability (from the contract's utterances when compiled). A READ may claim a verb too ("ask
+     * <agent> …", spec 379): an instruction opening with a verb a lookup in the plan claims is discharged by
+     * that lookup — the verb names a consultation, not an act.
+     */
+    verbs?: string[];
+    /** Spec 371 — the FACT WORDS a question uses to name what this read answers ("balance", "how much").
+     *  A read's twin of an act's `verbs`: question admission requires the plan to include the tool that
+     *  answers a fact the sentence names. Behaviour, never authority. */
+    answers?: string[];
+    /** Spec 371 — the domain author's sentence for this read's result (`{{field}}`; once per `items[]`
+     *  element when the result carries a list). Rendered instead of composed: the person's unit. */
+    answer?: string;
+    /**
+     * Spec 367 §6 — WHAT A SUCCESSFUL STEP OF THIS TOOL ESTABLISHES about the requested outcome:
+     *   lookup         who or what was meant (a roster, a relationship) — never that anything was done
+     *   submission     acceptance or pending execution (an invitation recorded, a request asked) — not the outcome
+     *   authoritative  the outcome itself, with its evidence (a mined transfer, a written record)
+     * Admission asks whether some step's class CAN discharge an instruction; fulfillment asks what the
+     * evidence DID establish, and the reply may claim only that. Absent ⇒ lookup for a tool with no
+     * capability, authoritative for one with. Declared on the contract; never lowered by a plan.
+     */
+    establishes?: OutcomeClass;
+    /** The tool's risk tier (`tool-policy.RiskTier`). Meaningful only with `capability`; defaults to `low`. */
+    risk?: import('@agenticprimitives/tool-policy').RiskTier;
+    /**
+     * SELF-ACTING: this capability touches ONLY the run's own principal's records, so the SESSION that
+     * proved who is asking is the authority and no mandate is verified.
+     *
+     * WHY THE MODEL NEEDED THIS. Until now every capability step required a presented mandate, so the
+     * only way to express "change your own email" was to demand a signature the Home's own form does not
+     * ask for — teaching people that talking to their agent is the expensive way to do the same thing.
+     * The alternative was worse: declaring such a tool informational, which would have hidden a WRITE
+     * from the authority plane entirely.
+     *
+     * WHAT IT IS NOT. It is not "low risk", and it is not a way to skip a gate. It is a claim about the
+     * TARGET — that there is no second party whose authority could be needed, because the actor, the
+     * owner and the beneficiary are the same principal. An invoker for such a tool MUST take its subject
+     * from the run's principal and never from an argument; the moment it can be pointed at someone else's
+     * record, this flag is a lie and the capability needs a mandate like everything else.
+     *
+     * It is declared on the BUILT-IN tool and never merged from a contract (a contract may describe an
+     * act, never weaken its gate — spec 361 §3), and the receipt records `self` as the basis so a reader
+     * can tell an act authorized by a session from one authorized by a signature.
+     */
+    selfAuthorized?: true;
+    /**
+     * Spec 363 W5 — the DECISION POINTS this capability consults, by id.
+     *
+     * Behaviour, never authority: consulting one lets the substrate answer a question ("which of your
+     * accounts pays?") from a modelled fact instead of interrupting, and every answer cites the rule that
+     * gave it. A capability that names none asks, which is the default and the safe one.
+     *
+     * The loop does not read this — normalisation does, where decisions are made. It rides the ToolSpec
+     * because that is where a CONTRACT's declaration lands (`mergeContractTool`), and a decision a domain
+     * author did not ask for should not happen because some app-side branch remembered a capability id.
+     */
+    decisions?: readonly string[];
+    /** Compensation for a run that fails AFTER this tool executed: the tool to invoke, with args derived
+     *  from the original args (+ the result under `$result`). Declared, never improvised. */
+    compensation?: {
+        toolId: string;
+        args: Record<string, unknown>;
+    };
+    /** An irreversible action: imposes `fresh-authorization` whatever the tier. */
+    irreversible?: boolean;
+    /** Spec 358 W4 — this tool's result ENUMERATES the objects of a domain relation (an ontology IRI,
+     *  e.g. aporg:memberAgent). Declaring it is what makes the result fan-out-able: a `forEach` over a
+     *  result whose tool declares nothing is refused, because an array being array-shaped says nothing
+     *  about whether iterating it is meaningful — a search page is not a payee list. */
+    enumerates?: {
+        relation: string;
+    };
+    /** Spec 361 — the interaction binding a playbook contract declared (editor/review/result names + a
+     *  navigation route key). DATA carried for surfaces to resolve; the loop never reads it. */
+    interaction?: {
+        editor?: string;
+        review?: string;
+        result?: string;
+        navigationTarget?: string;
+    };
 }
 /** One step of a plan: invoke `toolId` with `args`; optionally bind the result under `ref` for later steps. */
 export interface PlanStep {
@@ -25,6 +134,37 @@ export interface PlanStep {
     args: Record<string, unknown>;
     /** Name to store this step's result under; later steps reference it via `{ $ref: name }` in their args. */
     ref?: string;
+    /** Spec 350 — optional stable id (defaults to `s<index>`); the receipt and the idempotency key carry it. */
+    id?: string;
+    /** Spec 376 — the AGENT that runs this step, when it is not this harness: a hand-off. The step runs
+     *  there under a CHILD mandate attenuated from the one this run presented; this run records the
+     *  hand-off and resumes on what comes back. Absent ⇒ this harness. */
+    executor?: string;
+    /** Caller-supplied idempotency key for a retry of THIS step; defaults to `${runRef}:${stepId}`. */
+    idempotencyKey?: string;
+    /** Spec 358 W4 — fan this step out over an ARRAY a prior step produced (`ref` is a `name.path` into
+     *  that step's result). Each element becomes its OWN step — its own receipt, its own idempotency key,
+     *  and its own pass through the verifier: a mandate per item, never one verdict stretched over N.
+     *  `$item` / `{ $item: 'path' }` placeholders in `args` are substituted per element. Fail-closed: the
+     *  producing step's tool must declare `enumerates`, and the relation must be bound fan-out-able. */
+    forEach?: {
+        ref: string;
+    };
+    /** Spec 370 P3 — run only AFTER these steps (by id) have completed. Steps with no edge between them and
+     *  no `$ref` into each other's results are independent; the loop runs independent INFORMATIONAL steps
+     *  concurrently, each through its own gates. A step that exercises a capability never runs beside
+     *  another: two userOps from one account race on its nonce, and one verdict is one step's. */
+    after?: string[];
+    /** Spec 370 P3 — a DECLARED branch: run this step only when a prior result satisfies the condition.
+     *  `ref` is a `name.path` into a prior step's result; `exists` = present and, for an array, non-empty;
+     *  `equals` = deep-equal to the value. A step whose condition fails is SKIPPED, with a receipt saying so —
+     *  the plan does not need a second planner call to take a branch. Undecidable at admission (a ref no
+     *  earlier step produces) is refused, never guessed. */
+    when?: {
+        ref: string;
+        exists?: boolean;
+        equals?: unknown;
+    };
 }
 /** The ordered tool composition the planner produced for an intent. */
 export interface Plan {
@@ -38,8 +178,21 @@ export interface StepObservation {
     ok: boolean;
     result?: unknown;
     error?: string;
+    /** Spec 370 P1 — the step's stable reference (`id` or `s<index>`), so a checkpoint can name what ran. */
+    stepRef?: string;
+    /** Spec 370 P1 — this observation was REPLAYED from a checkpoint on a resume: nothing was invoked and
+     *  nothing re-verified, because there was no new attempt (spec 362 §0.1, gate 4). */
+    replayed?: boolean;
+    /** Spec 370 P3 — the step's `when` did not hold: nothing ran, and the receipt says so. */
+    skipped?: boolean;
 }
-export type RunOutcome = 'completed' | 'failed';
+/** `denied`: an authority decision refused a step (never re-planned around — a denial is not a tool
+ *  failure). `suspended`: an approval is pending OR a tool asked the person for an input (`prompt`);
+ *  resume later, through the verifier again. `authority-required`: the plan needs a mandate the caller did
+ *  not present — nothing was verified, nothing ran; the caller may come back WITH one (opt-in via
+ *  `onMissingMandate: 'report'`; the default is still to throw). It is 401, never 403: no authority was
+ *  judged, so this is not a denial and must never be reported as one. */
+export type RunOutcome = 'completed' | 'failed' | 'denied' | 'suspended' | 'authority-required';
 /** The result of running an intent to completion (or fail-closed). */
 export interface RunResult {
     outcome: RunOutcome;
@@ -49,11 +202,35 @@ export interface RunResult {
     steps: StepObservation[];
     /** The last successful step's result — the composed answer returned to the caller. */
     result?: unknown;
-    /** Set when `outcome === 'failed'`. */
+    /** Set when `outcome === 'failed'` or `'denied'`. */
     error?: string;
+    /** Spec 350 — the run's reference (the A2A taskId when run inside `A2aTaskDO`). */
+    runRef: string;
+    /** Every step's receipt, informational ones included. The sink (if any) has the same list. */
+    receipts: import('./authority.js').StepReceipt[];
+    /** Set when `outcome === 'suspended'`: what to hand back to resume. */
+    resumeToken?: string;
+    /** Set when `outcome === 'suspended'` because a tool asked the person for something (spec 350 §3.4).
+     *  The surface renders it; the answers come back as `RunIntentOpts.supplied` on the resume. */
+    prompt?: import('./input.js').InputRequestV1;
+    /** Set when `outcome === 'authority-required'`: the step the plan reached that needs a mandate. The
+     *  caller turns it into a requirement in ITS vocabulary (`harness.mandateRequirementForStep`) — this
+     *  layer names the step, never the grant. */
+    required?: {
+        stepRef: string;
+        toolId: string;
+        capability: {
+            id: string;
+            action: string;
+            resource?: string;
+            authority?: string;
+        };
+        risk: import('./authority.js').ResolvedStep['risk'];
+        args: Record<string, unknown>;
+    };
 }
 /** Stable error codes the loop / planners raise (fail-closed; never a silent empty success). */
-export type OrchestrationErrorCode = 'no_plan' | 'unknown_tool' | 'empty_plan' | 'max_steps' | 'planner_failed';
+export type OrchestrationErrorCode = 'no_plan' | 'unknown_tool' | 'empty_plan' | 'max_steps' | 'planner_failed' | 'no_authority_port' | 'no_approval_port' | 'no_mandate_presented' | 'keyring_needs_selector' | 'fan_out_unbound' | 'fan_out_not_array' | 'fan_out_refused' | 'fan_out_over_limit';
 export declare class OrchestrationError extends Error {
     readonly code: OrchestrationErrorCode;
     constructor(code: OrchestrationErrorCode, message: string);

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,YAAY,EAAG,kCAA2C,CAAC;AACxE,eAAO,MAAM,cAAc,EAAG,SAAkB,CAAC;AACjD,eAAO,MAAM,QAAQ,EAAG,gCAAyC,CAAC;AAElE,sGAAsG;AACtG,MAAM,WAAW,MAAM;IACrB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,4GAA4G;AAC5G,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,uGAAuG;IACvG,WAAW,EAAE,MAAM,CAAC;IACpB,uGAAuG;IACvG,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,+GAA+G;AAC/G,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2GAA2G;IAC3G,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,uEAAuE;AACvE,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,UAAU,CAAC;IACpB,mEAAmE;IACnE,IAAI,EAAE,IAAI,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gGAAgG;AAChG,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,cAAc,GACd,YAAY,GACZ,WAAW,GACX,gBAAgB,CAAC;AAErB,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,sBAAsB;gBAA5B,IAAI,EAAE,sBAAsB,EAC5C,OAAO,EAAE,MAAM;CAKlB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,EAAE;AACF,+FAA+F;AAC/F,2GAA2G;AAC3G,6GAA6G;AAC7G,6GAA6G;AAC7G,+GAA+G;AAE/G,MAAM,CAAC,MAAM,YAAY,GAAG,kCAA2C,CAAC;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,SAAkB,CAAC;AACjD,MAAM,CAAC,MAAM,QAAQ,GAAG,gCAAyC,CAAC;AAoElE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IADlB,YACkB,IAA4B,EAC5C,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAwB;QAI5C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,EAAE;AACF,+FAA+F;AAC/F,2GAA2G;AAC3G,6GAA6G;AAC7G,6GAA6G;AAC7G,+GAA+G;AAE/G,MAAM,CAAC,MAAM,YAAY,GAAG,kCAA2C,CAAC;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,SAAkB,CAAC;AACjD,MAAM,CAAC,MAAM,QAAQ,GAAG,gCAAyC,CAAC;AAoOlE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IADlB,YACkB,IAA4B,EAC5C,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAwB;QAI5C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/orchestration",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.3",
   "description": "The Ring-0 agentic orchestration core (ADR-0044): the intent→plan→execute→observe loop, the Planner + ToolInvoker ports, and a deterministic rule-based planner. A first-party app expresses a goal; the loop plans which tools compose to satisfy it and runs them through an injected invoker. Pure leaf — no transport, no LLM SDK, no chain; the concrete LLM binding lives behind the Planner port in orchestration-anthropic.",
   "license": "MIT",
   "repository": {
@@ -41,6 +41,9 @@
     "intent",
     "agentic-loop"
   ],
+  "dependencies": {
+    "@agenticprimitives/tool-policy": "1.0.0-alpha.24"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",