@tangle-network/agent-interface 0.26.1 → 0.27.0

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;

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";

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.0",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",