@tangle-network/agent-interface 0.26.1 → 0.27.1

package/dist/agent-candidate-compat.js

@@ -0,0 +1,340 @@
+/**
+ * Backward-compatibility surface for the candidate outcome and receipt exports
+ * that were renamed or collapsed when the candidate contract was unified.
+ *
+ * Every symbol here is deprecated and exists only so published consumers that
+ * still import the pre-unification names keep resolving at ESM import time.
+ * Prefer the current names; these will be removed in a future major.
+ *
+ * Two shapes of compat live in this module:
+ *  - Pure renames (shape-identical to a current export) are re-exported as
+ *    deprecated aliases and remain reference-equal to their new counterpart.
+ *  - Symbols whose shape changed (a different `schemaVersion` literal, a
+ *    restructured field, or a union that no longer exists) are re-declared here
+ *    verbatim from the last release that published them, so old data still
+ *    parses against the old name instead of silently binding to a newer shape.
+ */
+import { z } from "zod";
+import { agentCandidateModelSettlementCallSchema, agentCandidateModelSettlementEvidenceSchema, agentCandidateModelSettlementMaterialSchema, agentCandidateBenchmarkResultEvidenceSchema, agentCandidateFixedSpendSchema, agentCandidateTaskOutcomeEvidenceSchema, } from "./agent-candidate-outcome-schema.js";
+import { agentCandidateResolvedModelSchema } from "./agent-candidate-execution-plan-schema.js";
+import { agentCandidateSpendSchema } from "./agent-candidate-lineage-schema.js";
+import { agentCandidateMemoryReceiptSchema, agentCandidateTerminationSchema, agentCandidateTraceEvidenceSchema, } from "./agent-candidate-receipt-schema.js";
+import { isCanonicalJsonValue, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+/**
+ * @deprecated Renamed to {@link agentCandidateModelSettlementCallSchema}.
+ * Reference-equal to the current export.
+ */
+export const agentCandidateModelSettlementCallV2Schema = agentCandidateModelSettlementCallSchema;
+/**
+ * @deprecated Renamed to {@link agentCandidateModelSettlementMaterialSchema}.
+ * Reference-equal to the current export.
+ */
+export const agentCandidateModelSettlementMaterialV2Schema = agentCandidateModelSettlementMaterialSchema;
+// -----------------------------------------------------------------------------
+// Re-added schemas.
+// -----------------------------------------------------------------------------
+const safeCountSchema = z
+    .number()
+    .int()
+    .nonnegative()
+    .refine(Number.isSafeInteger, "value must be a nonnegative safe integer");
+const boundedIdentifierSchema = z.string().min(1).max(256);
+/**
+ * @deprecated The run receipt no longer carries a standalone model-usage block.
+ * Restored `resolved`/`usage` schema for consumers of the V1/V2 run receipt.
+ */
+export const agentCandidateModelUsageSchema = z
+    .object({
+    resolved: agentCandidateResolvedModelSchema,
+    usage: agentCandidateSpendSchema,
+})
+    .strict();
+/**
+ * Restored per-call aggregate and canonical-value checks shared by the V1
+ * settlement material. Mirrors the current internal refinement but tolerates
+ * the pre-router call shape that omits `generationId`.
+ */
+function refineLegacyModelSettlementMaterial(material, ctx) {
+    const callIds = new Set();
+    const traceSpanIds = new Set();
+    const totals = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedInputTokens: 0,
+        reasoningTokens: 0,
+        modelCalls: material.calls.length,
+        costUsdNanos: 0,
+    };
+    for (const [index, call] of material.calls.entries()) {
+        if (callIds.has(call.callId)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["calls", index, "callId"],
+                message: "model settlement call ids must be unique",
+            });
+        }
+        callIds.add(call.callId);
+        if (traceSpanIds.has(call.traceSpanId)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["calls", index, "traceSpanId"],
+                message: "model settlement trace span ids must be unique",
+            });
+        }
+        traceSpanIds.add(call.traceSpanId);
+        if (call.model !== material.resolved.model) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["calls", index, "model"],
+                message: "settled call model must match the resolved single model",
+            });
+        }
+        for (const field of [
+            "inputTokens",
+            "outputTokens",
+            "cachedInputTokens",
+            "reasoningTokens",
+            "costUsdNanos",
+        ]) {
+            const sum = totals[field] + call[field];
+            if (!Number.isSafeInteger(sum)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["calls", index, field],
+                    message: `model settlement ${field} total exceeds safe integer range`,
+                });
+            }
+            else {
+                totals[field] = sum;
+            }
+        }
+    }
+    if (!sameFixedSpend(totals, material.usage)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["usage"],
+            message: "model settlement usage must equal the exact per-call aggregate",
+        });
+    }
+    if (!isCanonicalJsonValue(material)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "model settlement material must contain only RFC 8785 JSON values",
+        });
+    }
+}
+const legacyModelSettlementCallV1Schema = z
+    .object({
+    callId: boundedIdentifierSchema,
+    traceSpanId: boundedIdentifierSchema,
+    model: boundedIdentifierSchema,
+    inputTokens: safeCountSchema,
+    outputTokens: safeCountSchema,
+    cachedInputTokens: safeCountSchema,
+    reasoningTokens: safeCountSchema,
+    costUsdNanos: safeCountSchema,
+})
+    .strict();
+/**
+ * @deprecated The settlement material collapsed to
+ * {@link agentCandidateModelSettlementMaterialSchema} (`schemaVersion: 2`).
+ * Restored `schemaVersion: 1` parser for the pre-router base call shape.
+ */
+export const agentCandidateModelSettlementMaterialV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-model-settlement-material"),
+    executionPlanDigest: sha256DigestSchema,
+    preparationId: boundedIdentifierSchema,
+    grantDigest: sha256DigestSchema,
+    closed: z.literal(true),
+    resolved: agentCandidateResolvedModelSchema,
+    usage: agentCandidateFixedSpendSchema,
+    calls: z.array(legacyModelSettlementCallV1Schema),
+})
+    .strict()
+    .superRefine(refineLegacyModelSettlementMaterial);
+/**
+ * @deprecated The run receipt collapsed to
+ * {@link agentCandidateRunReceiptSchema} (`schemaVersion: 3`). Restored
+ * `schemaVersion: 1` parser with aggregate usage accounting.
+ */
+export const agentCandidateRunReceiptV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-run"),
+    digestAlgorithm: z.literal("rfc8785-sha256"),
+    bundleDigest: sha256DigestSchema,
+    materializationReceiptDigest: sha256DigestSchema,
+    executionPlanDigest: sha256DigestSchema,
+    memory: agentCandidateMemoryReceiptSchema,
+    usage: agentCandidateSpendSchema,
+    modelUsage: agentCandidateModelUsageSchema,
+    trace: agentCandidateTraceEvidenceSchema,
+    termination: agentCandidateTerminationSchema,
+    digest: sha256DigestSchema,
+})
+    .strict()
+    .superRefine((receipt, ctx) => {
+    const usageMatchesModel = receipt.usage.costUsd === receipt.modelUsage.usage.costUsd &&
+        receipt.usage.inputTokens === receipt.modelUsage.usage.inputTokens &&
+        receipt.usage.outputTokens === receipt.modelUsage.usage.outputTokens &&
+        receipt.usage.cachedInputTokens ===
+            receipt.modelUsage.usage.cachedInputTokens &&
+        receipt.usage.modelCalls === receipt.modelUsage.usage.modelCalls;
+    if (!usageMatchesModel) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelUsage", "usage"],
+            message: "single-model usage must equal aggregate protected usage",
+        });
+    }
+    if (receipt.trace.modelCallCount !== receipt.modelUsage.usage.modelCalls) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["trace", "modelCallCount"],
+            message: "trace model-call count must match protected single-model usage",
+        });
+    }
+    if (!isCanonicalJsonValue(receipt)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "run receipt must contain only RFC 8785 JSON values",
+        });
+    }
+});
+function legacyUsageMatchesFixed(legacy, fixed) {
+    return (legacy.costUsd === fixed.costUsdNanos / 1_000_000_000 &&
+        legacy.inputTokens === fixed.inputTokens &&
+        legacy.outputTokens === fixed.outputTokens &&
+        (legacy.cachedInputTokens ?? 0) === fixed.cachedInputTokens &&
+        legacy.modelCalls === fixed.modelCalls);
+}
+/**
+ * @deprecated The run receipt collapsed to
+ * {@link agentCandidateRunReceiptSchema} (`schemaVersion: 3`). Restored
+ * `schemaVersion: 2` parser. Its evidence members bind the current settlement,
+ * task-outcome, and benchmark-result schemas.
+ */
+export const agentCandidateRunReceiptV2Schema = z
+    .object({
+    schemaVersion: z.literal(2),
+    kind: z.literal("agent-candidate-run"),
+    digestAlgorithm: z.literal("rfc8785-sha256"),
+    bundleDigest: sha256DigestSchema,
+    materializationReceiptDigest: sha256DigestSchema,
+    executionPlanDigest: sha256DigestSchema,
+    memory: agentCandidateMemoryReceiptSchema,
+    usage: agentCandidateSpendSchema,
+    modelUsage: agentCandidateModelUsageSchema,
+    trace: agentCandidateTraceEvidenceSchema,
+    termination: agentCandidateTerminationSchema,
+    fixedUsage: agentCandidateFixedSpendSchema,
+    modelSettlement: agentCandidateModelSettlementEvidenceSchema,
+    taskOutcome: agentCandidateTaskOutcomeEvidenceSchema,
+    benchmarkResult: agentCandidateBenchmarkResultEvidenceSchema,
+    digest: sha256DigestSchema,
+})
+    .strict()
+    .superRefine((receipt, ctx) => {
+    const legacyUsageMatchesModel = receipt.usage.costUsd === receipt.modelUsage.usage.costUsd &&
+        receipt.usage.inputTokens === receipt.modelUsage.usage.inputTokens &&
+        receipt.usage.outputTokens === receipt.modelUsage.usage.outputTokens &&
+        receipt.usage.cachedInputTokens ===
+            receipt.modelUsage.usage.cachedInputTokens &&
+        receipt.usage.modelCalls === receipt.modelUsage.usage.modelCalls;
+    if (!legacyUsageMatchesModel) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelUsage", "usage"],
+            message: "single-model usage must equal aggregate protected usage",
+        });
+    }
+    if (!legacyUsageMatchesFixed(receipt.usage, receipt.fixedUsage)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fixedUsage"],
+            message: "fixed usage must exactly preserve the legacy usage totals",
+        });
+    }
+    if (!sameFixedSpend(receipt.fixedUsage, receipt.modelSettlement.material.usage)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelSettlement", "material", "usage"],
+            message: "model settlement aggregate must equal fixed run usage",
+        });
+    }
+    if (JSON.stringify(receipt.modelUsage.resolved) !==
+        JSON.stringify(receipt.modelSettlement.material.resolved)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelSettlement", "material", "resolved"],
+            message: "model settlement must bind the run's resolved model",
+        });
+    }
+    if (receipt.modelSettlement.material.executionPlanDigest !==
+        receipt.executionPlanDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["modelSettlement", "material", "executionPlanDigest"],
+            message: "model settlement must bind the executed plan",
+        });
+    }
+    if (receipt.trace.modelCallCount !== receipt.fixedUsage.modelCalls) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["trace", "modelCallCount"],
+            message: "trace model-call count must match fixed run usage",
+        });
+    }
+    if (receipt.taskOutcome.material.executionPlanDigest !==
+        receipt.executionPlanDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["taskOutcome", "material", "executionPlanDigest"],
+            message: "task outcome must bind the executed plan",
+        });
+    }
+    if (receipt.benchmarkResult.material.executionPlanDigest !==
+        receipt.executionPlanDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["benchmarkResult", "material", "executionPlanDigest"],
+            message: "benchmark result must bind the executed plan",
+        });
+    }
+    if (receipt.benchmarkResult.material.taskOutcomeDigest !==
+        receipt.taskOutcome.digest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["benchmarkResult", "material", "taskOutcomeDigest"],
+            message: "benchmark result must bind the exact task outcome",
+        });
+    }
+    if (!isCanonicalJsonValue(receipt)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "run receipt must contain only RFC 8785 JSON values",
+        });
+    }
+});
+/**
+ * @deprecated The run receipt generations collapsed into a single current
+ * schema. Restored union parser for consumers that accepted both generations.
+ */
+export const agentCandidateRunReceiptAnyVersionSchema = z.union([
+    agentCandidateRunReceiptV1Schema,
+    agentCandidateRunReceiptV2Schema,
+]);
+/**
+ * @deprecated No longer exported from the outcome module. Restored spend-equality
+ * helper for consumers that compared fixed-point usage totals.
+ */
+export function sameFixedSpend(left, right) {
+    return (left.inputTokens === right.inputTokens &&
+        left.outputTokens === right.outputTokens &&
+        left.cachedInputTokens === right.cachedInputTokens &&
+        left.reasoningTokens === right.reasoningTokens &&
+        left.modelCalls === right.modelCalls &&
+        left.costUsdNanos === right.costUsdNanos);
+}

package/dist/index.d.ts

@@ -5,7 +5,9 @@
  * This package defines the contract between the sidecar and provider implementations.
  */
 import type { InteractionRequest, InteractionResponse } from "./interaction.js";
+import type { AgentExecutionOutcome, DurablePlan, PlanContinuation, SdkPlanHost } from "./plan.js";
 export type * from "./environment-provider.js";
+export * from "./plan.js";
 export type BackendCapabilities = {
     streaming: boolean;
     toolUse: boolean;
@@ -218,6 +220,11 @@ export type StreamEvent = MessagePartUpdatedEvent | {
     type: "interaction.cancel";
     id: string;
     reason?: string;
+}
+/** A durable plan was committed. This event is observational, not a live ask. */
+ | {
+    type: "plan.submitted";
+    plan: DurablePlan;
 };
 export type ToolInvocation = {
     toolName: string;
@@ -267,8 +274,11 @@ export type AgentExecutionInput = {
      * client-initiated retries of the same intent.
      */
     turnId?: string;
+    /** Server-owned continuation of a previously committed plan decision. */
+    planContinuation?: PlanContinuation;
 };
 export type AgentExecutionResult = {
+    outcome: AgentExecutionOutcome;
     text: string;
     toolInvocations: ToolInvocation[];
     reasoning?: string[];
@@ -491,6 +501,7 @@ export interface SdkTraceContext {
 export type SdkHostServices = {
     memoryHost: SdkMemoryHost;
     toolHost: SdkToolHost;
+    planHost: SdkPlanHost;
     recorder: SdkRecorder;
     providerConfig: ProviderConfig;
     traceContext?: SdkTraceContext;
@@ -603,6 +614,7 @@ export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";
 export * from "./agent-candidate-promotion-schema.js";
+export * from "./agent-candidate-compat.js";
 export * from "./agent-profile.js";
 export * from "./profile-diff.js";
 export * from "./harness.js";

package/dist/index.js

@@ -4,6 +4,7 @@
  * Shared types and interfaces for SDK provider adapters.
  * This package defines the contract between the sidecar and provider implementations.
  */
+export * from "./plan.js";
 /** Helper to check part type */
 export function isTextPart(part) {
     return part.type === "text";
@@ -126,6 +127,7 @@ export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";
 export * from "./agent-candidate-promotion-schema.js";
+export * from "./agent-candidate-compat.js";
 export * from "./agent-profile.js";
 export * from "./profile-diff.js";
 export * from "./harness.js";

package/dist/plan.d.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+/** Harnesses with an enforceable durable-plan continuation contract. */
+export declare const PlanProviderKindSchema: z.ZodEnum<{
+    "claude-code": "claude-code";
+    codex: "codex";
+    opencode: "opencode";
+}>;
+export type PlanProviderKind = z.infer<typeof PlanProviderKindSchema>;
+/**
+ * Credential-free provider correlation committed with the plan. This union is
+ * deliberately closed: adding plan support for another harness requires an
+ * explicit resume contract instead of smuggling opaque metadata through.
+ */
+export declare const PlanProviderStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"claude-code">;
+    version: z.ZodLiteral<1>;
+    nativeSessionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"codex">;
+    version: z.ZodLiteral<1>;
+    threadId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"opencode">;
+    version: z.ZodLiteral<1>;
+}, z.core.$strict>], "kind">;
+export type PlanProviderState = z.infer<typeof PlanProviderStateSchema>;
+/**
+ * A plan committed by the runtime before the planning turn is allowed to end.
+ * The full body is part of the contract so consumers never reconstruct it from
+ * rendered chat text.
+ */
+export declare const DurablePlanSchema: z.ZodObject<{
+    id: z.ZodString;
+    revision: z.ZodNumber;
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodString;
+    submittedAt: z.ZodString;
+}, z.core.$strict>;
+export type DurablePlan = z.infer<typeof DurablePlanSchema>;
+/** Provider-originated data required to commit a plan exactly once. */
+export declare const PlanSubmissionSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodString;
+    sourceToolCallId: z.ZodString;
+    providerState: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"claude-code">;
+        version: z.ZodLiteral<1>;
+        nativeSessionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"codex">;
+        version: z.ZodLiteral<1>;
+        threadId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"opencode">;
+        version: z.ZodLiteral<1>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type PlanSubmission = z.infer<typeof PlanSubmissionSchema>;
+/** The human verdict that starts the next turn. */
+export declare const PlanDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"approved">;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"rejected">;
+    feedback: z.ZodString;
+}, z.core.$strict>], "outcome">;
+export type PlanDecision = z.infer<typeof PlanDecisionSchema>;
+/**
+ * Typed server-originated continuation. Adapters consume this instead of
+ * inferring approval from a free-form user message.
+ */
+export declare const PlanContinuationSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    plan: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodNumber;
+        title: z.ZodOptional<z.ZodString>;
+        body: z.ZodString;
+        submittedAt: z.ZodString;
+    }, z.core.$strict>;
+    sourceToolCallId: z.ZodString;
+    decision: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"approved">;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"rejected">;
+        feedback: z.ZodString;
+    }, z.core.$strict>], "outcome">;
+    providerState: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"claude-code">;
+        version: z.ZodLiteral<1>;
+        nativeSessionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"codex">;
+        version: z.ZodLiteral<1>;
+        threadId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"opencode">;
+        version: z.ZodLiteral<1>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type PlanContinuation = z.infer<typeof PlanContinuationSchema>;
+/** Terminal meaning of a successfully completed adapter invocation. */
+export declare const AgentExecutionOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"completed">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"awaiting_plan_decision">;
+    plan: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodNumber;
+        title: z.ZodOptional<z.ZodString>;
+        body: z.ZodString;
+        submittedAt: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+export type AgentExecutionOutcome = z.infer<typeof AgentExecutionOutcomeSchema>;
+/**
+ * Per-turn host command used by providers to commit a plan. Implementations
+ * bind project, host-session, and turn identity outside provider-controlled
+ * input and must resolve only after the durable write commits.
+ */
+export interface SdkPlanHost {
+    submit(submission: PlanSubmission): Promise<DurablePlan>;
+    /** Publish a committed plan only after the provider turn has terminalized. */
+    confirm(planId: string): Promise<void>;
+    /** Compensate a committed plan when provider terminalization cannot be proven. */
+    withdraw(planId: string, reason: string): Promise<void>;
+}

package/dist/plan.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/** Harnesses with an enforceable durable-plan continuation contract. */
+export const PlanProviderKindSchema = z.enum([
+    "claude-code",
+    "codex",
+    "opencode",
+]);
+/**
+ * Credential-free provider correlation committed with the plan. This union is
+ * deliberately closed: adding plan support for another harness requires an
+ * explicit resume contract instead of smuggling opaque metadata through.
+ */
+export const PlanProviderStateSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("claude-code"),
+        version: z.literal(1),
+        nativeSessionId: z.string().min(1),
+    }).strict(),
+    z.object({
+        kind: z.literal("codex"),
+        version: z.literal(1),
+        threadId: z.string().min(1),
+    }).strict(),
+    z.object({
+        kind: z.literal("opencode"),
+        version: z.literal(1),
+    }).strict(),
+]);
+/**
+ * A plan committed by the runtime before the planning turn is allowed to end.
+ * The full body is part of the contract so consumers never reconstruct it from
+ * rendered chat text.
+ */
+export const DurablePlanSchema = z.object({
+    id: z.string().min(1),
+    revision: z.number().int().positive(),
+    title: z.string().trim().min(1).optional(),
+    body: z.string().trim().min(1),
+    submittedAt: z.string().datetime({ offset: true }),
+}).strict();
+/** Provider-originated data required to commit a plan exactly once. */
+export const PlanSubmissionSchema = z.object({
+    title: z.string().trim().min(1).optional(),
+    body: z.string().trim().min(1),
+    /** Stable provider tool-call identity reused when a lost acknowledgement retries. */
+    sourceToolCallId: z.string().min(1),
+    /** Credential-free correlation required to resume the deferred turn. */
+    providerState: PlanProviderStateSchema,
+}).strict();
+/** The human verdict that starts the next turn. */
+export const PlanDecisionSchema = z.discriminatedUnion("outcome", [
+    z.object({ outcome: z.literal("approved") }).strict(),
+    z.object({
+        outcome: z.literal("rejected"),
+        feedback: z.string().trim().min(1),
+    }).strict(),
+]);
+/**
+ * Typed server-originated continuation. Adapters consume this instead of
+ * inferring approval from a free-form user message.
+ */
+export const PlanContinuationSchema = z.object({
+    version: z.literal(1),
+    plan: DurablePlanSchema,
+    sourceToolCallId: z.string().min(1),
+    decision: PlanDecisionSchema,
+    /** Exact payload previously committed with the plan submission. */
+    providerState: PlanProviderStateSchema,
+}).strict();
+/** Terminal meaning of a successfully completed adapter invocation. */
+export const AgentExecutionOutcomeSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("completed") }).strict(),
+    z.object({
+        type: z.literal("awaiting_plan_decision"),
+        plan: DurablePlanSchema,
+    }).strict(),
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",