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

package/dist/flow-trace.js

@@ -0,0 +1,60 @@
+const FLOW_ID = /^[A-Za-z0-9_.:-]{4,64}$/;
+/** The caller's referral from the message metadata: which registry pointed it here and the receipt it cites — echoed as
+ *  said (short strings only), verified by nobody here: how a caller found an agent grants nothing. */
+export function referralOf(message) {
+    const r = message?.metadata?.referral;
+    if (!r || typeof r.registry !== 'string' || !r.registry || r.registry.length > 200)
+        return null;
+    return { registry: r.registry, ...(typeof r.receipt === 'string' && r.receipt && r.receipt.length <= 400 ? { receipt: r.receipt } : {}) };
+}
+/** The caller's flow id from the message metadata, or null — never a value we would not echo verbatim. */
+export function flowIdOf(message) {
+    const v = message?.metadata?.flowId;
+    return typeof v === 'string' && FLOW_ID.test(v) ? v : null;
+}
+/** A result's summary: numbers, flags and sources, never the rows (those are the `results` artifact's). */
+export function summarizeOutput(result) {
+    if (!result || typeof result !== 'object')
+        return typeof result === 'string' ? { text: result.slice(0, 200) } : undefined;
+    const r = result;
+    const out = {};
+    for (const k of ['count', 'total', 'found', 'error', 'refused', 'source', 'interpretation', 'filters', 'types'])
+        if (r[k] !== undefined)
+            out[k] = r[k];
+    for (const k of ['resources', 'topics', 'members', 'agents', 'rows', 'items'])
+        if (Array.isArray(r[k]))
+            out[`${k}Count`] = r[k].length;
+    if (typeof out.interpretation === 'string')
+        out.interpretation = out.interpretation.slice(0, 240);
+    return Object.keys(out).length ? out : { keys: Object.keys(r).slice(0, 12) };
+}
+export function buildFlowTrace(input) {
+    const events = input.events ?? [];
+    const byTool = new Map();
+    for (const r of input.reply.results ?? [])
+        byTool.set(r.toolId, r.result);
+    const planArgs = new Map();
+    for (const p of input.reply.plannerTrace?.plan ?? [])
+        planArgs.set(p.toolId, p.args);
+    const steps = [];
+    for (const e of events) {
+        if (e.type === 'ToolInvoked')
+            steps.push({ stepRef: e.stepRef, toolId: e.toolId, ok: e.ok, ...(planArgs.has(e.toolId) ? { args: planArgs.get(e.toolId) } : {}), ...(byTool.has(e.toolId) ? { output: summarizeOutput(byTool.get(e.toolId)) } : {}) });
+        else if (e.type === 'StepReplayed')
+            steps.push({ stepRef: e.stepRef, toolId: e.toolId, ok: true, replayed: true });
+        else if (e.type === 'StepSkipped')
+            steps.push({ stepRef: e.stepRef, toolId: e.toolId, ok: true, skipped: e.because });
+    }
+    const pt = input.reply.plannerTrace;
+    return {
+        kind: 'ap.flow-trace.v1', hop: 'agent', flowId: input.flowId, traceId: input.traceId ?? null, runRef: input.runRef, agent: input.agent, asker: input.asker,
+        playbook: pt?.playbook ?? null,
+        planner: pt ? { kind: pt.planner ?? 'unknown', ...(pt.model ? { model: pt.model } : {}), toolsExposed: pt.toolsExposed ?? [], plan: pt.plan ?? [], ...(pt.admission?.length ? { admission: pt.admission } : {}), ...(pt.route ? { route: pt.route } : {}) } : null,
+        steps,
+        reply: { kind: input.reply.kind, chars: (input.reply.text ?? '').length, artifacts: input.artifacts },
+        ...(input.referral ? { referral: input.referral } : {}), ...(input.continued ? { continued: true } : {}),
+        events: events.map((e) => ({ type: e.type, ...('stepRef' in e ? { stepRef: e.stepRef } : {}), ...('toolId' in e ? { toolId: e.toolId } : {}), ...('ok' in e ? { ok: e.ok } : {}), ...('because' in e ? { because: e.because } : {}), ...('error' in e ? { error: e.error } : {}) })),
+        ms: Date.now() - input.startedAt,
+    };
+}
+//# sourceMappingURL=flow-trace.js.map

package/dist/flow-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-trace.js","sourceRoot":"","sources":["../src/flow-trace.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,8 +1,27 @@
 export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF, OrchestrationError } from './types.js';
 export type { Intent, ToolSpec, PlanStep, Plan, StepObservation, RunOutcome, RunResult, OrchestrationErrorCode, } from './types.js';
 export { createRuleBasedPlanner } from './planner.js';
-export type { Planner, PlanInput, PlanRule } from './planner.js';
+export type { Planner, PlanInput, PlanRule, AnswerComposer, ComposeInput } from './planner.js';
+export { wireNameFor, toolNameMap, planStepFromToolArgs } from './planner-wire.js';
 export type { ToolInvoker, InvokeContext } from './tool-invoker.js';
 export { runIntent } from './loop.js';
+export { planAdmission, externalExecutorsReadOnly, instructionNeedsAct, noPlaceholders, subjectNamedInAsk, dependenciesProvided, branchesDecidable, questionAnsweredByRead, capabilitiesAvailable, outcomeClassOf, squash as squashLabel } from './admission.js';
+export type { PlanAdmission, AdmissionRule, AdmissionVerdict, AdmissionViolation, AdmissionInput, AdmissionCode } from './admission.js';
+export type { ExecutionBindingV1 } from './authority.js';
+export type { OutcomeClass } from './types.js';
 export type { RunIntentOpts } from './loop.js';
+export type { MandatePresentation, ResolvedStep, StepAuthorityRequest, Obligation, EffectSink, DecisionReason, DecisionEvidence, MandateDecision, MandateVerifier, PolicyEvaluator, ApprovalRequest, ApprovalOutcome, ApprovalPort, StepReceiptStatus, StepReceipt, ReceiptSink, RunEvent, RunEventStamp, RunEventSink, OrchestrationPorts, } from './authority.js';
+export { InputRequired, isInputRequired, inputsFor, dataFor, signatureFor, receiptPending } from './input.js';
+export type { InputRequestV1, InputFieldV1, InputFieldType, SuppliedInputV1, CommitmentRefV1 } from './input.js';
+export { TerminalDenial, type DurableStepPort, type RunExecutor, type ApprovalEventV1 } from './durable.js';
+export { recordOf, replayingInvoker, replayRun } from './record.js';
+export type { RunRecordV1, RunPlannerSummaryV1, RunExportReportV1, ReplayReport, ReplayVerdict, RunBillV1 } from './record.js';
+export { spansOf, assertFirewalled, otlpTracesOf, receiptDigest, provenanceOf, runProvenanceRecordKey, SPAN_ATTRIBUTE_ALLOWLIST, RUN_PROVENANCE_RECORD_PREFIX, provIds, traceIdOf, spanIdOf, PROV_ID_BASE, stageSpansOf, assertMetricsFirewalled } from './spans.js';
+export { metricsOf, otlpMetricsOf, STEP_DURATION_BOUNDS_MS, type RunMetricsV1, type CounterPointV1, type HistogramPointV1, type MetricAttributes } from './metrics.js';
+export type { SpanV1, RunProvenanceV1 } from './spans.js';
+export { traceIdFor } from './spans.js';
+export { parseTraceparent, formatTraceparent, withTracestateMember, tracestateMember, traceContextOf, type TraceContextV1 } from './trace-context.js';
+export { ARTIFACT_REF_TYPE, OFFLOAD_THRESHOLD_CHARS, SUMMARY_MAX_CHARS, RUN_ARTIFACT_RECORD_PREFIX, runArtifactRecordKey, isArtifactRef, canonicalJson, summarizeResult, offloadObservations, offloadRunResult, refsReachedBy, rehydrateObservations, fitEvidence, compactObservations, resultFactsOf, RETAINED_RESULT_KEYS, type ArtifactRefV1, type RunArtifactRecordV1, type ArtifactStore, type OffloadReport, type EvidenceItemV1, type FittedEvidenceV1 } from './artifacts.js';
+export { buildFlowTrace, flowIdOf, referralOf, summarizeOutput } from './flow-trace.js';
+export type { FlowTraceV1, FlowStepV1, ReferralV1 } from './flow-trace.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACxF,YAAY,EACV,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,UAAU,EACV,SAAS,EACT,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEjE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,27 @@
 // @agenticprimitives/orchestration — public API. The Ring-0 agentic loop: the intent→plan→execute→observe
 // model, the Planner + ToolInvoker PORTS, and `runIntent`. Pure leaf — no transport, no LLM SDK, no chain.
-// The LLM binding lives in `@agenticprimitives/orchestration-anthropic` (behind the Planner port). ADR-0044.
+// The LLM bindings live in sibling adapters behind the Planner port (`orchestration-anthropic`,
+// `orchestration-openai-compat`). ADR-0044, spec 377.
 export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF, OrchestrationError } from './types.js';
 export { createRuleBasedPlanner } from './planner.js';
+// Spec 377 §2 — the plan-shape convention on a vendor's wire, shared by every LLM adapter.
+export { wireNameFor, toolNameMap, planStepFromToolArgs } from './planner-wire.js';
 export { runIntent } from './loop.js';
+export { planAdmission, externalExecutorsReadOnly, instructionNeedsAct, noPlaceholders, subjectNamedInAsk, dependenciesProvided, branchesDecidable, questionAnsweredByRead, capabilitiesAvailable, outcomeClassOf, squash as squashLabel } from './admission.js';
+// Spec 350 §3.4 — a tool may ask the person for what it lacks; the run suspends with the prompt.
+export { InputRequired, isInputRequired, inputsFor, dataFor, signatureFor, receiptPending } from './input.js';
+export { TerminalDenial } from './durable.js';
+// Spec 370 P6 — the run record and its replay (verdicts re-derived, tools never re-run).
+export { recordOf, replayingInvoker, replayRun } from './record.js';
+// Spec 381 — the run, exported: firewalled spans + the durable half for the vault. Pure projections of a record.
+export { spansOf, assertFirewalled, otlpTracesOf, receiptDigest, provenanceOf, runProvenanceRecordKey, SPAN_ATTRIBUTE_ALLOWLIST, RUN_PROVENANCE_RECORD_PREFIX, provIds, traceIdOf, spanIdOf, PROV_ID_BASE, stageSpansOf, assertMetricsFirewalled } from './spans.js';
+// Spec 390 W4 — the run as metrics: four instruments from one record, the OTLP metrics body beside the traces body.
+export { metricsOf, otlpMetricsOf, STEP_DURATION_BOUNDS_MS } from './metrics.js';
+export { traceIdFor } from './spans.js';
+// Spec 390 W2 — W3C Trace Context on the wire: parse, format, tracestate members. Correlation, never trust.
+export { parseTraceparent, formatTraceparent, withTracestateMember, tracestateMember, traceContextOf } from './trace-context.js';
+// Spec 391 — offloaded artifacts and fitted evidence: what outlives a turn is a reference; nothing is cut silently.
+export { ARTIFACT_REF_TYPE, OFFLOAD_THRESHOLD_CHARS, SUMMARY_MAX_CHARS, RUN_ARTIFACT_RECORD_PREFIX, runArtifactRecordKey, isArtifactRef, canonicalJson, summarizeResult, offloadObservations, offloadRunResult, refsReachedBy, rehydrateObservations, fitEvidence, compactObservations, resultFactsOf, RETAINED_RESULT_KEYS } from './artifacts.js';
+// Spec 387 W2 / spec 399 §4 — the flow trace: a run's story on its task, folded from RunEvents + the planner summary. Evidence, never authority.
+export { buildFlowTrace, flowIdOf, referralOf, summarizeOutput } from './flow-trace.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,2GAA2G;AAC3G,6GAA6G;AAE7G,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAYxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAKtD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,2GAA2G;AAC3G,gGAAgG;AAChG,sDAAsD;AAEtD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAYxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD,2FAA2F;AAC3F,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAInF,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,cAAc,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA4BjQ,iGAAiG;AACjG,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG9G,OAAO,EAAE,cAAc,EAAgE,MAAM,cAAc,CAAC;AAC5G,yFAAyF;AACzF,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpE,iHAAiH;AACjH,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrQ,oHAAoH;AACpH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,uBAAuB,EAAwF,MAAM,cAAc,CAAC;AAEvK,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,4GAA4G;AAC5G,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AACtJ,oHAAoH;AACpH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,qBAAqB,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,oBAAoB,EAAoI,MAAM,gBAAgB,CAAC;AACtd,iJAAiJ;AACjJ,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/input.d.ts

@@ -0,0 +1,165 @@
+import type { StepReceipt } from './authority.js';
+export type InputFieldType = 'text' | 'address' | 'number' | 'boolean' | 'choice' | 'credential';
+export interface InputFieldV1 {
+    name: string;
+    label: string;
+    type: InputFieldType;
+    required?: boolean;
+    /** For `choice`. `hint` is what a person needs to tell two candidates APART — a label alone
+     *  ("Nathan") is not a choice, it is the same word four times. */
+    choices?: Array<{
+        value: string;
+        label: string;
+        hint?: string;
+    }>;
+    /** For `choice`: the listed candidates are not the only possible answers, so the surface MUST also let
+     *  the person type one. Set whenever the question itself admits that what they want may not be listed —
+     *  a prompt saying "give it in full" beside a radio list with no text box is a dead end with
+     *  instructions. */
+    allowOther?: boolean;
+    /** For `text`: a regular-expression source the surface may validate against before submitting. */
+    pattern?: string;
+    hint?: string;
+}
+/** A follow-up the surface may offer when a question has no good answer among what is on hand — "ask
+ *  them for a way to reach it". The surface PREFILLS it; it never sends it. A question that leads
+ *  nowhere is a dead end, and the way out is usually another ask the person did not know to phrase. */
+export interface InputSuggestionV1 {
+    label: string;
+    /** The ask to prefill, in the person's own voice. */
+    message: string;
+}
+/**
+ * Spec 374 — WHAT ANOTHER AGENT OWES THIS RUN. A step whose subject is another agent was sent there (spec
+ * 366); that agent could not finish it for this asker and parked it for its own steward. This run holds
+ * the record — a `Commitment` in spec 340's sense: debtor, creditor, content, conditions, its own
+ * lifecycle — and waits. Evidence of where the act stands; never authority for it: no gate reads it.
+ */
+export interface CommitmentRefV1 {
+    /** The debtor's operation identity for this request — the correlation the answer will name. */
+    id: string;
+    /** Who owes the act (the subject's agent). */
+    debtor: string;
+    /** Who is owed it (the asker's agent). */
+    creditor: string;
+    content: {
+        capability: string;
+        args: Record<string, unknown>;
+        goal: string;
+    };
+    /** In words: "a steward of missio-nexus.org finishes it". */
+    conditions: string;
+    /** Spec 340 `CommitmentState`, the four this record can observe. `proposed` = asked and parked. */
+    state: 'proposed' | 'active' | 'discharged' | 'void';
+    /** The debtor's run, where the act actually waits. */
+    at: {
+        agent: string;
+        name?: string;
+        runRef: string;
+    };
+}
+export type InputRequestV1 = {
+    kind: 'data';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    fields: InputFieldV1[];
+    suggest?: InputSuggestionV1;
+    /** Spec 385 — when this is an AMBIGUITY choice, the scope the answer confirms (word + capability + arg),
+     *  so the trusted resume that supplies it can be remembered as a scoped preference. Display/memory only. */
+    scope?: {
+        word: string;
+        capability: string;
+        arg: string;
+    };
+    /** Spec 397 — the question is ANOTHER agent's (a routed step's target asked it): where it waits, and the step
+     *  there the answer is for. The resume continues THAT run with the answer; this run only relays. */
+    at?: {
+        agent: string;
+        name?: string;
+        runRef: string;
+        stepRef?: string;
+    };
+}
+/** Spec 374 — the run waits on another agent's steward; only the debtor's answer resumes it. */
+ | {
+    kind: 'commitment';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    commitment: CommitmentRefV1;
+}
+/** Spec 374 W2 — THE SUBJECT'S AUTHORITY REQUEST, RELAYED: the step was routed to another agent, which
+ *  asked for a mandate the ASKER can grant (they steward it). The asker's surface mints it exactly as it
+ *  would for a local step; on resume the mandate travels to the subject's parked run. `authority` is
+ *  the receiver's own request, carried whole; `at` is where the step waits. */
+ | {
+    kind: 'authority';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    authority: Record<string, unknown>;
+    at: {
+        agent: string;
+        name?: string;
+        runRef: string;
+    };
+} | {
+    kind: 'signature';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    /** The digest to sign, and who must sign it (the connected credential's address, or the SA it custodies). */
+    digest: string;
+    signer: string;
+    /** What is being signed, in the open — the surface shows it; the tool re-derives it on resume. */
+    payload?: unknown;
+} | {
+    kind: 'confirmation';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    summary: unknown;
+};
+/** What comes back. Keyed by the step that asked; a tool reads its own via `inputsFor`. */
+export interface SuppliedInputV1 {
+    stepRef: string;
+    /** Answers to a `data` request, by field name. A `credential` field's value is the surface's own
+     *  description of the connected credential, in whatever shape the tool documented. */
+    data?: Record<string, unknown>;
+    /** The answer to a `signature` request. `payload` echoes what was signed when the tool needs it back. */
+    signature?: {
+        digest: string;
+        signer: string;
+        signature: string;
+        payload?: unknown;
+    };
+    /** The answer to a `confirmation` request. */
+    confirmed?: boolean;
+    /** Spec 374 — the answer to a `commitment` request: what the debtor's agent delivered when its parked
+     *  run finished. `outcome` is the debtor's word; `result` is the step's result when it answered. */
+    delivered?: {
+        outcome: 'answer' | 'refused' | 'error';
+        result?: unknown;
+        said?: string;
+        receipts?: unknown[];
+        runRef?: string;
+    };
+}
+/** Thrown by a tool invoker to suspend the run with a prompt. The loop recognises this class and ONLY this
+ *  class — any other throw is a step failure. */
+export declare class InputRequired extends Error {
+    readonly request: InputRequestV1;
+    constructor(request: InputRequestV1);
+}
+export declare function isInputRequired(e: unknown): e is InputRequired;
+/** The inputs supplied for one step (a resume may answer several steps at once). */
+export declare function inputsFor(supplied: readonly SuppliedInputV1[] | undefined, stepRef: string): SuppliedInputV1[];
+/** The merged `data` answers for a step (later entries win). */
+export declare function dataFor(supplied: readonly SuppliedInputV1[] | undefined, stepRef: string): Record<string, unknown>;
+/** The supplied signature over `digest` for a step, if any. Case-insensitive on the digest. */
+export declare function signatureFor(supplied: readonly SuppliedInputV1[] | undefined, stepRef: string, digest?: string): SuppliedInputV1['signature'] | undefined;
+/** What a `suspended` receipt carries about the prompt — the kind and, for a signature, the digest; never
+ *  the answers (those are the person's, and they arrive on the resume). */
+export declare function receiptPending(req: InputRequestV1): NonNullable<StepReceipt['pendingInput']>;
+//# sourceMappingURL=input.d.ts.map

package/dist/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"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"}

package/dist/input.js

@@ -0,0 +1,33 @@
+/** Thrown by a tool invoker to suspend the run with a prompt. The loop recognises this class and ONLY this
+ *  class — any other throw is a step failure. */
+export class InputRequired extends Error {
+    request;
+    constructor(request) {
+        super(`input required: ${request.kind} for ${request.toolId} (${request.stepRef})`);
+        this.name = 'InputRequired';
+        this.request = request;
+    }
+}
+export function isInputRequired(e) {
+    return e instanceof InputRequired || (typeof e === 'object' && e !== null && e.name === 'InputRequired' && 'request' in e);
+}
+/** The inputs supplied for one step (a resume may answer several steps at once). */
+export function inputsFor(supplied, stepRef) {
+    return (supplied ?? []).filter((s) => s.stepRef === stepRef);
+}
+/** The merged `data` answers for a step (later entries win). */
+export function dataFor(supplied, stepRef) {
+    return Object.assign({}, ...inputsFor(supplied, stepRef).map((s) => s.data ?? {}));
+}
+/** The supplied signature over `digest` for a step, if any. Case-insensitive on the digest. */
+export function signatureFor(supplied, stepRef, digest) {
+    return inputsFor(supplied, stepRef)
+        .map((s) => s.signature)
+        .find((s) => !!s && (digest === undefined || s.digest.toLowerCase() === digest.toLowerCase()));
+}
+/** What a `suspended` receipt carries about the prompt — the kind and, for a signature, the digest; never
+ *  the answers (those are the person's, and they arrive on the resume). */
+export function receiptPending(req) {
+    return { kind: req.kind, ...(req.kind === 'signature' ? { digest: req.digest, signer: req.signer } : {}), ...(req.kind === 'data' ? { fields: req.fields.map((f) => f.name) } : {}) };
+}
+//# sourceMappingURL=input.js.map

package/dist/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAyHA;iDACiD;AACjD,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,OAAO,CAAiB;IACjC,YAAY,OAAuB;QACjC,KAAK,CAAC,mBAAmB,OAAO,CAAC,IAAI,QAAQ,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,CAAU;IACxC,OAAO,CAAC,YAAY,aAAa,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAuB,CAAC,IAAI,KAAK,eAAe,IAAI,SAAS,IAAI,CAAC,CAAC,CAAC;AACpJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,QAAgD,EAAE,OAAe;IACzF,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,QAAgD,EAAE,OAAe;IACvF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,QAAgD,EAAE,OAAe,EAAE,MAAe;IAC7G,OAAO,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;SACvB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACnG,CAAC;AAED;2EAC2E;AAC3E,MAAM,UAAU,cAAc,CAAC,GAAmB;IAChD,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACxL,CAAC"}

package/dist/loop.d.ts

@@ -1,6 +1,8 @@
-import type { Intent, RunResult, StepObservation, ToolSpec } from './types.js';
+import type { Intent, Plan, PlanStep, RunResult, StepObservation, ToolSpec } from './types.js';
 import type { Planner } from './planner.js';
 import type { ToolInvoker } from './tool-invoker.js';
+import { type SuppliedInputV1 } from './input.js';
+import type { MandatePresentation, OrchestrationPorts, ResolvedStep, StepReceipt } from './authority.js';
 export interface RunIntentOpts {
     /** The injected planning port (deterministic default or the LLM adapter). */
     planner: Planner;
@@ -14,12 +16,122 @@ export interface RunIntentOpts {
     maxReplans?: number;
     /** Optional observer for each executed step (telemetry; never authority). */
     onObserve?: (obs: StepObservation) => void;
+    /** Spec 374 §1 — WHICH STEPS ARE JUDGED ELSEWHERE. Returns the agent a step is routed to when its
+     *  resolved subject is another agent (spec 366 R1), else null. Such a step presents no mandate HERE:
+     *  the subject's agent judges it, and this run records the step as routed and holds what it answers. */
+    authorityJudgedElsewhere?: (step: ResolvedStep) => string | null;
+    /** Spec 350 — the authority ports. Required once any tool declares a capability. */
+    ports?: OrchestrationPorts;
+    /** Spec 350 — what the caller presented as its authority. Opaque here; the verifier reads it.
+     *  Spec 358 W4 — MAY be a list (a keyring): a fanned-out plan needs a mandate per item, and a caller
+     *  that has gathered several presents them together. With more than one, `selectPresentation` is
+     *  REQUIRED — the loop never tries mandates against a step until one sticks (ADR-0013: selection is
+     *  deterministic and separate from verification, which still judges exactly one mandate). */
+    presented?: MandatePresentation | MandatePresentation[] | null;
+    /** Choose WHICH presented mandate this step is judged under (match by payee, resource…). `null` means
+     *  none fits — the step reports authority-required naming its own args, exactly as if nothing had been
+     *  presented for it. Ignored when zero or one mandate is presented. */
+    selectPresentation?: (step: ResolvedStep, all: MandatePresentation[]) => MandatePresentation | null;
+    /** Spec 358 W4 — is this relation fan-out-able, and over at most how many items? The binding lives in
+     *  the ontology package; injecting it keeps this loop domain-free. Absent ⇒ every forEach is refused. */
+    fanOut?: (relation: string) => {
+        maxItems: number;
+    } | null;
+    /** The run's reference — the A2A taskId when run inside `A2aTaskDO`. Defaults to a random id. */
+    runRef?: string;
+    /**
+     * Spec 370 P1 — RESUME FROM A CHECKPOINT. `plan` is the plan the run was admitted with (the planner is
+     * not asked again — the intent is the same intent, and a second plan for it would be a second run);
+     * `completed` are the steps that already ran, by stepRef, with what they returned and the receipt
+     * that recorded them.
+     *
+     * A completed step REPLAYS: its observation is taken as recorded, its result feeds `$ref`s exactly as
+     * it did, its receipt is carried, and neither the invoker nor the verifier is called — there is no new
+     * attempt to authorize (spec 362 §0.1, gate 4). Every step that has NOT run goes through the verifier
+     * as if for the first time: the checkpoint carries what happened, never permission for what has not.
+     * The plan is re-admitted regardless (admission is deterministic and reads only declarations).
+     */
+    resume?: {
+        plan: Plan;
+        completed: ReadonlyArray<{
+            stepRef: string;
+            result?: unknown;
+            receipt?: StepReceipt;
+        }>;
+    };
+    /** Spec 367 §5 — the execution binding for a resolved step, recorded on its receipt. */
+    bindingFor?: (step: ResolvedStep) => import('./authority.js').ExecutionBindingV1 | undefined;
+    /**
+     * Spec 360 — the playbook's declared consequences. A map keyed by capability id, OR a RESOLVER called
+     * per step.
+     *
+     * The resolver exists because an effect follows THE ACT, and the agent whose authority an act spends is
+     * not known until the step is resolved: a payment's receipt belongs to the treasury whose funds moved,
+     * not to whichever agent the person happened to be talking to. Passing a static map would tie every
+     * consequence to the addressee, which is the wrong agent for exactly the case the feature exists for.
+     *
+     * Either way the loop never reads INSIDE an effect — it obtains them and hands them to the sink.
+     */
+    declaredEffects?: Record<string, unknown[]> | ((capabilityId: string, step: ResolvedStep) => unknown[] | Promise<unknown[]>);
+    /** Spec 354 §4.5 — the playbook that admitted this run (canonical id + version + definition digest).
+     *  Stamped onto every receipt so a run's receipt names WHICH procedure shaped it. Injected — the loop
+     *  stays domain-free and never reads a vault. Absent ⇒ the bare harness; receipts carry no skillRef. */
+    skillRef?: {
+        skillId: string;
+        version: string;
+        commitment: string;
+    };
+    /** Unix-seconds clock, injected so receipts are deterministic in tests. */
+    now?: () => number;
+    /** What to do when a step needs a mandate and none was presented. `'throw'` (the default, unchanged)
+     *  fails closed with `no_mandate_presented`. `'report'` returns `outcome: 'authority-required'` naming
+     *  the step, so an Ask surface can tell the person what authority it would need instead of refusing —
+     *  it grants nothing: the caller must come back with a mandate, which is then verified as always. */
+    onMissingMandate?: 'throw' | 'report';
+    /**
+     * Normalise a step's args before ANYTHING judges them — spec 350 §3.1.
+     *
+     * A planner writes what the person said: `payee: "alice2.treasury"`, `asset: "usdc"`. Those are correct
+     * English and cannot be verified against anything: an allowlist holds addresses. Normalising later (when
+     * a mandate is minted, say) fixes the display and leaves the RUN judging the words — which denied a
+     * payment whose mandate was correct, for a target that was never really wrong.
+     *
+     * So the substrate gets one place to turn the person's language into its own, ahead of the capability
+     * extraction, the verifier and the invoker alike. It may not change WHICH tool runs or WHAT it is
+     * allowed to do: resolving a name is reading an argument, not widening a grant.
+     */
+    normalizeArgs?: (input: {
+        toolId: string;
+        tool: ToolSpec;
+        args: Record<string, unknown>;
+    }) => Promise<Record<string, unknown>>;
+    /** Spec 376 W2 — a step's `executor` as the plan named it (a person's words, "runtime-c3s0.svc") turned into
+     *  the agent's address in the asker's own tier, or a question when several answer to it. `undefined` ⇒ the
+     *  step runs here. Called for every step that names one; may throw `InputRequired` like `normalizeArgs`. */
+    resolveExecutor?: (input: {
+        step: PlanStep;
+        tool: ToolSpec;
+    }) => Promise<string | undefined>;
+    /**
+     * Spec 363 W6 — the DECISIONS made while normalising this step, for its receipt.
+     *
+     * The loop does not decide anything: normalisation is where words become canonical values, and where a
+     * decision point answers instead of asking. So the caller that ran it is the one that knows, and this
+     * is how it says — a port, like every other thing the loop does not own.
+     */
+    decisionsFor?: (toolId: string, args: Record<string, unknown>) => ReadonlyArray<NonNullable<StepReceipt['decisions']>[number]>;
+    /** Spec 350 §3.4 — answers to prompts an earlier run of THIS intent raised (a resume). Handed to each
+     *  tool by stepRef. A resume is a full re-run: every step passes the verifier again, and a step that
+     *  already executed is re-invoked under the same idempotency key (an invoker makes it a no-op). */
+    supplied?: SuppliedInputV1[];
 }
 /**
  * Run an intent to a terminal result. Plans, executes the steps in order (threading `ref` results into later
  * args), observes, and re-plans (bounded) when a step throws. Returns `completed` with the last successful
- * step's result, or `failed` with the error. Fail-closed throughout: an unknown tool, an empty plan, no plan,
- * or an exhausted step budget all produce a `failed` RunResult (never a misleading empty success).
+ * step's result, `failed` with the error, `denied` when authority refused a step, or `suspended` when an
+ * approval is pending. Fail-closed throughout: an unknown tool, an empty plan, no plan, an exhausted step
+ * budget, a capability step with no verifier, or a denial all produce a non-completed RunResult — never a
+ * misleading empty success.
  */
 export declare function runIntent(intent: Intent, opts: RunIntentOpts): Promise<RunResult>;
 //# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAkB,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,kFAAkF;IAClF,MAAM,EAAE,WAAW,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;CAC5C;AAiDD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CA6DvF"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"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"}