@tangle-network/agent-interface 0.40.0 → 0.41.0

package/dist/environment-provider.d.ts

@@ -1,6 +1,11 @@
+import { z } from "zod";
 import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
 import type { AgentCandidateTermination } from "./agent-candidate.js";
 import type { InputPart, StreamEvent, TokenUsage } from "./index.js";
+import { type InteractionAcknowledgement, type InteractionCapabilities, type InteractionResponseCommand } from "./interaction.js";
+import type { ContextTransferReceipt, ContextTransferRequest, NativeContextBoundaryProof, NativeContextContinuationRequest } from "./portable-context.js";
+import type { AgentRunControlRef } from "./runtime-control.js";
+import type { AgentWorkspaceBranching } from "./workspace-branching.js";
 /** Portable profile reference: inline profile or provider catalog id. */
 export type AgentProfileRef = AgentProfile | string;
 export type AgentEnvironmentStatus = "pending" | "provisioning" | "running" | "stopped" | "failed" | "expired" | "unknown";
@@ -202,6 +207,12 @@ export interface AgentTurnInput {
     lastEventId?: string;
     turnId?: string;
     detach?: boolean;
+    /** Stable coordinates for a retained run when one already exists. */
+    controlRef?: AgentRunControlRef;
+    /** Approved portable history for a fresh provider session. */
+    contextTransfer?: ContextTransferRequest;
+    /** Verified same-session continuation; never carries duplicate history. */
+    nativeContinuation?: NativeContextContinuationRequest;
     context?: Record<string, unknown>;
     signal?: AbortSignal;
     providerOptions?: Record<string, unknown>;
@@ -214,10 +225,13 @@ export interface AgentTurnResult {
     usage?: TokenUsage;
     metadata?: Record<string, unknown>;
     events?: AgentEnvironmentEvent[];
+    contextTransferReceipt?: ContextTransferReceipt;
 }
 export interface AgentSessionRef {
     id: string;
     provider?: string;
+    controlRef?: AgentRunControlRef;
+    contextTransferReceipt?: ContextTransferReceipt;
     metadata?: Record<string, unknown>;
 }
 export interface AgentEnvironmentEvent {
@@ -230,13 +244,23 @@ export interface AgentEnvironmentEvent {
 }
 export interface AgentSession {
     readonly id: string;
+    readonly controlRef?: AgentRunControlRef;
     status(): Promise<AgentSessionStatus | null>;
     events(options?: {
+        /** Exclusive stable event id previously emitted by this session. */
         since?: string;
+        /** Provider execution selected by the durable control reference, when required. */
+        executionId?: string;
         signal?: AbortSignal;
     }): AsyncIterable<AgentEnvironmentEvent>;
     result(): Promise<AgentTurnResult>;
     prompt(input: AgentTurnInput): Promise<AgentTurnResult>;
+    respondToInteraction?(command: InteractionResponseCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<InteractionAcknowledgement>;
+    contextBoundary?(options?: {
+        signal?: AbortSignal;
+    }): Promise<NativeContextBoundaryProof | null>;
     cancel(): Promise<void>;
 }
 export interface AgentEnvironment {
@@ -246,7 +270,12 @@ export interface AgentEnvironment {
     status(): Promise<AgentEnvironmentStatus>;
     stream(input: AgentTurnInput): AsyncIterable<AgentEnvironmentEvent>;
     dispatch?(input: AgentTurnInput): Promise<AgentSessionRef>;
-    session?(id: string): AgentSession;
+    session?(id: string, options?: {
+        controlRef?: AgentRunControlRef;
+    }): AgentSession;
+    respondToInteraction?(command: InteractionResponseCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<InteractionAcknowledgement>;
     read?(path: string, options?: {
         sessionId?: string;
     }): Promise<string>;
@@ -256,6 +285,8 @@ export interface AgentEnvironment {
     exec?(command: string, options?: ExecRequest): Promise<ExecResult>;
     checkpoint?(options?: CheckpointRequest): Promise<CheckpointRef>;
     fork?(checkpoint: CheckpointRef, options?: ForkRequest): Promise<AgentEnvironment>;
+    /** Durable, retry-safe checkpoint and environment-fork operations. */
+    readonly workspaceBranching?: AgentWorkspaceBranching;
     placement?(): Promise<PlacementInfo>;
     refresh?(): Promise<void>;
     destroy?(): Promise<void>;
@@ -273,6 +304,8 @@ export interface AgentEnvironmentCapabilities {
         list: boolean;
         messages: boolean;
     };
+    /** Absent when the provider cannot originate or answer interactions. */
+    interactions?: InteractionCapabilities;
     workspace: {
         read: boolean;
         write: boolean;
@@ -284,6 +317,12 @@ export interface AgentEnvironmentCapabilities {
     branching: {
         checkpoint: boolean;
         fork: boolean;
+        /** True only when key + canonical request digest semantics are implemented. */
+        retrySafe?: boolean;
+        /** True only when operations can be recovered by idempotency key. */
+        lookup?: boolean;
+        /** True only when checkpoints and forked environments have confirmed cleanup. */
+        cleanup?: boolean;
     };
     placement: boolean;
     usage: boolean;
@@ -293,6 +332,85 @@ export interface AgentEnvironmentCapabilities {
         egress: readonly AgentExactProcessEgressMode[];
     };
 }
+/** Strict runtime validator for provider capability negotiation. */
+export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        namedProfiles: z.ZodBoolean;
+        systemPrompt: z.ZodBoolean;
+        instructions: z.ZodBoolean;
+        tools: z.ZodBoolean;
+        permissions: z.ZodBoolean;
+        mcp: z.ZodBoolean;
+        subagents: z.ZodBoolean;
+        resources: z.ZodObject<{
+            files: z.ZodBoolean;
+            instructions: z.ZodBoolean;
+            tools: z.ZodOptional<z.ZodBoolean>;
+            skills: z.ZodOptional<z.ZodBoolean>;
+            agents: z.ZodOptional<z.ZodBoolean>;
+            commands: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        hooks: z.ZodOptional<z.ZodBoolean>;
+        modes: z.ZodOptional<z.ZodBoolean>;
+        runtimeUpdate: z.ZodBoolean;
+        validation: z.ZodBoolean;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    streaming: z.ZodObject<{
+        live: z.ZodBoolean;
+        replay: z.ZodBoolean;
+        detach: z.ZodBoolean;
+        turnIdempotency: z.ZodBoolean;
+    }, z.core.$strict>;
+    sessions: z.ZodObject<{
+        continue: z.ZodBoolean;
+        list: z.ZodBoolean;
+        messages: z.ZodBoolean;
+    }, z.core.$strict>;
+    interactions: z.ZodOptional<z.ZodObject<{
+        kinds: z.ZodArray<z.ZodString>;
+        answerFieldTypes: z.ZodArray<z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            select: "select";
+            secret: "secret";
+        }>>;
+        responseScopes: z.ZodArray<z.ZodEnum<{
+            interaction: "interaction";
+            session: "session";
+            persistent: "persistent";
+        }>>;
+        secretAnswers: z.ZodBoolean;
+        concurrentRequests: z.ZodBoolean;
+        replay: z.ZodBoolean;
+        responseIdempotency: z.ZodBoolean;
+    }, z.core.$strict>>;
+    workspace: z.ZodObject<{
+        read: z.ZodBoolean;
+        write: z.ZodBoolean;
+        exec: z.ZodBoolean;
+        git: z.ZodBoolean;
+        upload: z.ZodBoolean;
+        download: z.ZodBoolean;
+    }, z.core.$strict>;
+    branching: z.ZodObject<{
+        checkpoint: z.ZodBoolean;
+        fork: z.ZodBoolean;
+        retrySafe: z.ZodOptional<z.ZodBoolean>;
+        lookup: z.ZodOptional<z.ZodBoolean>;
+        cleanup: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    placement: z.ZodBoolean;
+    usage: z.ZodBoolean;
+    confidential: z.ZodBoolean;
+    exactProcess: z.ZodOptional<z.ZodObject<{
+        egress: z.ZodArray<z.ZodEnum<{
+            blocked: "blocked";
+            strict: "strict";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export interface CreateAgentEnvironmentInput {
     profile: AgentProfileRef;
     /** Agent backend inside the provider, for example "opencode" or "codex". */

package/dist/environment-provider.js

@@ -1 +1,102 @@
-export {};
+import { z } from "zod";
+import { InteractionCapabilitiesSchema, } from "./interaction.js";
+/*
+ * Keep the provider contract runtime-validatable. Provider capability data is
+ * commonly read from a remote service or adapter configuration, so its static
+ * TypeScript type is not a trust boundary.
+ */
+const AgentProfileCapabilitiesSchema = z.strictObject({
+    namedProfiles: z.boolean(),
+    systemPrompt: z.boolean(),
+    instructions: z.boolean(),
+    tools: z.boolean(),
+    permissions: z.boolean(),
+    mcp: z.boolean(),
+    subagents: z.boolean(),
+    resources: z.strictObject({
+        files: z.boolean(),
+        instructions: z.boolean(),
+        tools: z.boolean().optional(),
+        skills: z.boolean().optional(),
+        agents: z.boolean().optional(),
+        commands: z.boolean().optional(),
+    }),
+    hooks: z.boolean().optional(),
+    modes: z.boolean().optional(),
+    runtimeUpdate: z.boolean(),
+    validation: z.boolean(),
+    extensions: z.array(z.string().min(1)).optional(),
+});
+/** Strict runtime validator for provider capability negotiation. */
+export const AgentEnvironmentCapabilitiesSchema = z
+    .strictObject({
+    profile: AgentProfileCapabilitiesSchema,
+    streaming: z.strictObject({
+        live: z.boolean(),
+        replay: z.boolean(),
+        detach: z.boolean(),
+        turnIdempotency: z.boolean(),
+    }),
+    sessions: z.strictObject({
+        continue: z.boolean(),
+        list: z.boolean(),
+        messages: z.boolean(),
+    }),
+    interactions: InteractionCapabilitiesSchema.optional(),
+    workspace: z.strictObject({
+        read: z.boolean(),
+        write: z.boolean(),
+        exec: z.boolean(),
+        git: z.boolean(),
+        upload: z.boolean(),
+        download: z.boolean(),
+    }),
+    branching: z.strictObject({
+        checkpoint: z.boolean(),
+        fork: z.boolean(),
+        retrySafe: z.boolean().optional(),
+        lookup: z.boolean().optional(),
+        cleanup: z.boolean().optional(),
+    }),
+    placement: z.boolean(),
+    usage: z.boolean(),
+    confidential: z.boolean(),
+    exactProcess: z
+        .strictObject({
+        egress: z.array(z.enum(["blocked", "strict"])).min(1),
+    })
+        .optional(),
+})
+    .superRefine((capabilities, refinement) => {
+    const durableBranching = [
+        capabilities.branching.retrySafe ?? false,
+        capabilities.branching.lookup ?? false,
+        capabilities.branching.cleanup ?? false,
+    ];
+    if (durableBranching.some(Boolean) &&
+        (!durableBranching.every(Boolean) ||
+            !capabilities.branching.checkpoint ||
+            !capabilities.branching.fork)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["branching"],
+            message: "retry-safe branching requires checkpoint, fork, lookup, and cleanup together",
+        });
+    }
+    const egress = capabilities.exactProcess?.egress;
+    if (egress && new Set(egress).size !== egress.length) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["exactProcess", "egress"],
+            message: "exact process egress modes must be unique",
+        });
+    }
+    const extensions = capabilities.profile.extensions;
+    if (extensions && new Set(extensions).size !== extensions.length) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["profile", "extensions"],
+            message: "profile extension namespaces must be unique",
+        });
+    }
+});

package/dist/harness.d.ts

@@ -14,8 +14,10 @@ import { z } from "zod";
  * a one-shot) with no full coding-agent harness. The rest are full agentic harnesses run in a
  * sandbox or locally via the CLI bridge.
  *
+ * `forge` (tailcallhq/forgecode) and `cursor` (cursor-agent) are multi-provider CLI harnesses with
+ * no vendor lock, so they carry no entry in the capability tables and resolve as router-backed.
  */
-export type HarnessType = "claude-code" | "nanoclaw" | "codex" | "opencode" | "kimi-code" | "pi" | "gemini" | "hermes" | "openclaw" | "amp" | "factory-droids" | "acp" | "cli-base";
+export type HarnessType = "claude-code" | "nanoclaw" | "codex" | "opencode" | "kimi-code" | "pi" | "gemini" | "hermes" | "openclaw" | "amp" | "factory-droids" | "forge" | "cursor" | "acp" | "cli-base";
 /** Runtime validator for {@link HarnessType}. Kept in lockstep with the type by the drift guard below. */
 export declare const harnessTypeSchema: z.ZodEnum<{
     "claude-code": "claude-code";
@@ -29,6 +31,8 @@ export declare const harnessTypeSchema: z.ZodEnum<{
     openclaw: "openclaw";
     amp: "amp";
     "factory-droids": "factory-droids";
+    forge: "forge";
+    cursor: "cursor";
     acp: "acp";
     "cli-base": "cli-base";
 }>;

package/dist/harness.js

@@ -12,6 +12,8 @@ export const harnessTypeSchema = z.enum([
     "openclaw",
     "amp",
     "factory-droids",
+    "forge",
+    "cursor",
     "acp",
     "cli-base",
 ]);

package/dist/index.d.ts

@@ -4,10 +4,14 @@
  * Shared types and interfaces for SDK provider adapters.
  * This package defines the contract between the sidecar and provider implementations.
  */
-import type { InteractionRequest, InteractionResponse } from "./interaction.js";
+import type { InteractionAcknowledgement, InteractionRequest, InteractionResponse, InteractionResponseCommand } from "./interaction.js";
 import type { AgentExecutionOutcome, DurablePlan, PlanContinuation, SdkPlanHost } from "./plan.js";
 export type * from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema } from "./environment-provider.js";
 export * from "./plan.js";
+export * from "./runtime-control.js";
+export * from "./portable-context.js";
+export * from "./workspace-branching.js";
 export type BackendCapabilities = {
     streaming: boolean;
     toolUse: boolean;
@@ -605,10 +609,16 @@ export interface SdkProviderAdapter {
     downloadArtifact?(sessionId: string, path: string): Promise<Uint8Array>;
     /**
      * Respond to an outstanding interaction (question, permission, …). The
-     * generalized inbound channel; the adapter translates the response into the
-     * provider's native control call to unblock the agent.
+     * original best-effort inbound channel. Kept source-compatible for existing
+     * adapters; durable callers should use `respondToInteractionCommand`.
      */
     respondToInteraction?(response: InteractionResponse): Promise<void>;
+    /**
+     * Retry-safe interaction response bound to an exact run and caller operation.
+     */
+    respondToInteractionCommand?(command: InteractionResponseCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<InteractionAcknowledgement>;
 }
 export * from "./interaction.js";
 export * from "./agent-candidate.js";

package/dist/index.js

@@ -4,7 +4,11 @@
  * Shared types and interfaces for SDK provider adapters.
  * This package defines the contract between the sidecar and provider implementations.
  */
+export { AgentEnvironmentCapabilitiesSchema } from "./environment-provider.js";
 export * from "./plan.js";
+export * from "./runtime-control.js";
+export * from "./portable-context.js";
+export * from "./workspace-branching.js";
 /** Helper to check part type */
 export function isTextPart(part) {
     return part.type === "text";