@tangle-network/agent-interface 3.1.2 → 4.0.0

package/dist/portable-context-plan.js

@@ -5,7 +5,8 @@ import { PortableConversationContextSchema } from "./portable-context-base.js";
 export const PortableContextDestinationSchema = z.strictObject({
     runner: idSchema,
     provider: idSchema,
-    environmentId: idSchema,
+    /** Omitted when the provider allocates the environment after acceptance. */
+    environmentId: idSchema.optional(),
     sessionId: idSchema,
     runId: idSchema,
     executionId: idSchema,

package/dist/portable-context-transfer.d.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import type { AgentProfile } from "./agent-profile.js";
+import { type ResourceRequest, type WorkspaceRequest } from "./environment-requests.js";
 import type { Sha256Digest } from "./agent-candidate.js";
 import { type PortableContextPlan } from "./portable-context-plan.js";
 export declare const ContextPlanAcceptanceSchema: z.ZodObject<{
@@ -15,6 +17,9 @@ export interface ContextTransferRequestMaterial {
     operationId: string;
     plan: PortableContextPlan;
     acceptance: ContextPlanAcceptance;
+    profile?: AgentProfile;
+    workspace?: WorkspaceRequest;
+    resources?: ResourceRequest;
 }
 export declare function contextTransferRequestDigest(request: ContextTransferRequestMaterial): Sha256Digest;
 export declare const ContextTransferRequestSchema: z.ZodObject<{
@@ -60,7 +65,7 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
         destination: z.ZodObject<{
             runner: z.ZodString;
             provider: z.ZodString;
-            environmentId: z.ZodString;
+            environmentId: z.ZodOptional<z.ZodString>;
             sessionId: z.ZodString;
             runId: z.ZodString;
             executionId: z.ZodString;
@@ -149,6 +154,268 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
             user: "user";
         }>;
     }, z.core.$strict>;
+    profile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        prompt: z.ZodOptional<z.ZodObject<{
+            systemPrompt: z.ZodOptional<z.ZodString>;
+            appendSystemPrompt: z.ZodOptional<z.ZodString>;
+            instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        model: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
+            small: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodString>;
+            reasoningEffort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                medium: "medium";
+                minimal: "minimal";
+                none: "none";
+                ultracode: "ultracode";
+                xhigh: "xhigh";
+            }>>;
+            maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+            maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+            maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        }, z.core.$strict>>;
+        harness: z.ZodOptional<z.ZodEnum<{
+            acp: "acp";
+            amp: "amp";
+            "claude-code": "claude-code";
+            "cli-base": "cli-base";
+            codex: "codex";
+            cursor: "cursor";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            gemini: "gemini";
+            hermes: "hermes";
+            "kimi-code": "kimi-code";
+            nanoclaw: "nanoclaw";
+            openclaw: "openclaw";
+            opencode: "opencode";
+            pi: "pi";
+            prime: "prime";
+        }>>;
+        seats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            harness: z.ZodEnum<{
+                acp: "acp";
+                amp: "amp";
+                "claude-code": "claude-code";
+                "cli-base": "cli-base";
+                codex: "codex";
+                cursor: "cursor";
+                "factory-droids": "factory-droids";
+                forge: "forge";
+                gemini: "gemini";
+                hermes: "hermes";
+                "kimi-code": "kimi-code";
+                nanoclaw: "nanoclaw";
+                openclaw: "openclaw";
+                opencode: "opencode";
+                pi: "pi";
+                prime: "prime";
+            }>;
+            provider: z.ZodString;
+            model: z.ZodString;
+            selector: z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"all-eligible">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"seat">;
+                id: z.ZodString;
+            }, z.core.$strict>]>;
+            tools: z.ZodOptional<z.ZodType<Record<string, boolean>, unknown, z.core.$ZodTypeInternals<Record<string, boolean>, unknown>>>;
+            permissions: z.ZodOptional<z.ZodType<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown, z.core.$ZodTypeInternals<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown>>>;
+        }, z.core.$strict>>>;
+        permissions: z.ZodOptional<z.ZodType<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown, z.core.$ZodTypeInternals<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown>>>;
+        tools: z.ZodOptional<z.ZodType<Record<string, boolean>, unknown, z.core.$ZodTypeInternals<Record<string, boolean>, unknown>>>;
+        mcp: z.ZodOptional<z.ZodType<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown, z.core.$ZodTypeInternals<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown>>>;
+        connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            connectionId: z.ZodString;
+            capabilities: z.ZodArray<z.ZodString>;
+            alias: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        subagents: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                resource: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"inline">;
+                    name: z.ZodString;
+                    content: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"github">;
+                    repository: z.ZodOptional<z.ZodString>;
+                    path: z.ZodString;
+                    ref: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>;
+                executable: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            skills: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            commands: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>]>>;
+            failOnError: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        hooks: z.ZodOptional<z.ZodType<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "bearer" | "raw" | undefined;
+            }> | undefined;
+        }[]>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "bearer" | "raw" | undefined;
+            }> | undefined;
+        }[]>, unknown>>>;
+        modes: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        confidential: z.ZodOptional<z.ZodObject<{
+            tee: z.ZodOptional<z.ZodString>;
+            attestationNonce: z.ZodOptional<z.ZodString>;
+            sealed: z.ZodOptional<z.ZodBoolean>;
+            attestationRefresh: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodType<import("./agent-profile.js").AgentProfileMetadata, unknown, z.core.$ZodTypeInternals<import("./agent-profile.js").AgentProfileMetadata, unknown>>>;
+        extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
+    }, z.core.$strict>>;
+    workspace: z.ZodOptional<z.ZodObject<{
+        environment: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        repoUrl: z.ZodOptional<z.ZodString>;
+        gitRef: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            base: z.ZodLiteral<"repository">;
+            path: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        }, z.core.$strict>, z.ZodObject<{
+            base: z.ZodLiteral<"host">;
+            path: z.ZodString;
+        }, z.core.$strict>], "base">>;
+        checkpoint: z.ZodOptional<z.ZodObject<{
+            checkpointId: z.ZodString;
+            provider: z.ZodString;
+            source: z.ZodObject<{
+                runId: z.ZodString;
+                provider: z.ZodString;
+                environmentId: z.ZodString;
+                sessionId: z.ZodString;
+                executionId: z.ZodString;
+                requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>;
+            idempotencyKey: z.ZodString;
+            requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            createdAt: z.ZodISODateTime;
+            metadata: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+        }, z.core.$strict>>;
+        providerOptions: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+    }, z.core.$strict>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        cpu: z.ZodOptional<z.ZodNumber>;
+        memoryMb: z.ZodOptional<z.ZodNumber>;
+        diskMb: z.ZodOptional<z.ZodNumber>;
+        gpu: z.ZodOptional<z.ZodString>;
+        providerOptions: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ContextTransferRequest = z.infer<typeof ContextTransferRequestSchema>;
 export declare const ContextTransferReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -170,7 +437,7 @@ export declare const ContextTransferReceiptSchema: z.ZodDiscriminatedUnion<[z.Zo
     destination: z.ZodObject<{
         runner: z.ZodString;
         provider: z.ZodString;
-        environmentId: z.ZodString;
+        environmentId: z.ZodOptional<z.ZodString>;
         sessionId: z.ZodString;
         runId: z.ZodString;
         executionId: z.ZodString;
@@ -206,7 +473,7 @@ export declare const ContextTransferReceiptSchema: z.ZodDiscriminatedUnion<[z.Zo
     destination: z.ZodObject<{
         runner: z.ZodString;
         provider: z.ZodString;
-        environmentId: z.ZodString;
+        environmentId: z.ZodOptional<z.ZodString>;
         sessionId: z.ZodString;
         runId: z.ZodString;
         executionId: z.ZodString;
@@ -246,7 +513,7 @@ export declare const ContextTransferResultSchema: z.ZodDiscriminatedUnion<[z.Zod
     destination: z.ZodObject<{
         runner: z.ZodString;
         provider: z.ZodString;
-        environmentId: z.ZodString;
+        environmentId: z.ZodOptional<z.ZodString>;
         sessionId: z.ZodString;
         runId: z.ZodString;
         executionId: z.ZodString;
@@ -282,7 +549,7 @@ export declare const ContextTransferResultSchema: z.ZodDiscriminatedUnion<[z.Zod
     destination: z.ZodObject<{
         runner: z.ZodString;
         provider: z.ZodString;
-        environmentId: z.ZodString;
+        environmentId: z.ZodOptional<z.ZodString>;
         sessionId: z.ZodString;
         runId: z.ZodString;
         executionId: z.ZodString;

package/dist/portable-context-transfer.js

@@ -1,4 +1,7 @@
 import { z } from "zod";
+import { agentProfileSchema } from "./profile-schema.js";
+import { canonicalAgentProfileDigest } from "./agent-execution-preparation.js";
+import { ResourceRequestSchema, WorkspaceRequestSchema } from "./environment-requests.js";
 import { boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, } from "./contract-limits.js";
 import { PortableContextSourceBoundarySchema, } from "./portable-context-base.js";
 import { PortableContextDestinationSchema, PortableContextPlanSchema, } from "./portable-context-plan.js";
@@ -12,6 +15,9 @@ const ContextTransferRequestMaterialSchema = z.strictObject({
     operationId: idSchema,
     plan: PortableContextPlanSchema,
     acceptance: ContextPlanAcceptanceSchema,
+    profile: agentProfileSchema.optional(),
+    workspace: WorkspaceRequestSchema.optional(),
+    resources: ResourceRequestSchema.optional(),
 });
 export function contextTransferRequestDigest(request) {
     const parsed = ContextTransferRequestMaterialSchema.parse(request);
@@ -19,6 +25,9 @@ export function contextTransferRequestDigest(request) {
         operationId: parsed.operationId,
         planDigest: parsed.plan.digest,
         acceptance: parsed.acceptance,
+        ...(parsed.profile === undefined ? {} : { profileDigest: canonicalAgentProfileDigest(parsed.profile) }),
+        ...(parsed.workspace === undefined ? {} : { workspace: parsed.workspace }),
+        ...(parsed.resources === undefined ? {} : { resources: parsed.resources }),
     });
 }
 export const ContextTransferRequestSchema = z
@@ -27,8 +36,20 @@ export const ContextTransferRequestSchema = z
     requestDigest: sha256DigestSchema,
     plan: PortableContextPlanSchema,
     acceptance: ContextPlanAcceptanceSchema,
+    profile: agentProfileSchema.optional(),
+    workspace: WorkspaceRequestSchema.optional(),
+    resources: ResourceRequestSchema.optional(),
 })
     .superRefine((request, refinement) => {
+    if (request.plan.destination.environmentId === undefined && request.profile === undefined) {
+        refinement.addIssue({ code: "custom", path: ["profile"], message: "an unbound destination requires its exact profile" });
+    }
+    if (request.profile !== undefined && canonicalAgentProfileDigest(request.profile) !== request.plan.destination.profileDigest) {
+        refinement.addIssue({ code: "custom", path: ["profile"], message: "profile digest must match the accepted destination" });
+    }
+    if (request.profile?.harness !== undefined && request.profile.harness !== request.plan.destination.runner) {
+        refinement.addIssue({ code: "custom", path: ["profile", "harness"], message: "profile harness must match the accepted destination runner" });
+    }
     if (request.acceptance.planDigest !== request.plan.digest) {
         refinement.addIssue({
             code: "custom",
@@ -41,6 +62,9 @@ export const ContextTransferRequestSchema = z
             operationId: request.operationId,
             plan: request.plan,
             acceptance: request.acceptance,
+            ...(request.profile === undefined ? {} : { profile: request.profile }),
+            ...(request.workspace === undefined ? {} : { workspace: request.workspace }),
+            ...(request.resources === undefined ? {} : { resources: request.resources }),
         })) {
         refinement.addIssue({
             code: "custom",
@@ -145,7 +169,7 @@ export function contextTransferReceiptMatches(request, receipt) {
         wireDigest(exactReceipt.source) === wireDigest(source.source) &&
         wireDigest(exactReceipt.destination) === wireDigest(destination) &&
         exactReceipt.provider === destination.provider &&
-        exactReceipt.environmentId === destination.environmentId &&
+        (destination.environmentId === undefined || exactReceipt.environmentId === destination.environmentId) &&
         exactReceipt.sessionId === destination.sessionId &&
         exactReceipt.runId === destination.runId &&
         exactReceipt.executionId === destination.executionId &&

package/dist/provider-adapter.d.ts

@@ -5,13 +5,19 @@ import type { SdkHostServices } from "./host-services.js";
 import type { BackendCapabilities, ProviderConfig } from "./provider-config.js";
 import type { BackendArtifact, BackendListOptions, McpConfig, McpStatusResponse } from "./mcp.js";
 import type { StreamEvent } from "./stream-events.js";
+import type { ContextTransferRequest } from "./portable-context.js";
+/** Fresh runner session creation with an accepted portable history. */
+export type SdkCreateSessionOptions = {
+    workspaceRoot?: string;
+    sessionId?: string;
+    /** Preserve the typed history and refuse every unsupported part. */
+    contextTransfer?: ContextTransferRequest;
+};
 export interface SdkProviderAdapter {
     readonly provider: string;
     getCapabilities(): BackendCapabilities;
     initialize(config: ProviderConfig): Promise<void>;
-    createSession?(options?: {
-        workspaceRoot?: string;
-    }): Promise<string>;
+    createSession?(options?: SdkCreateSessionOptions): Promise<string>;
     forkSession?(options: {
         sessionId: string;
         messageId?: string;

package/dist/provider-config.d.ts

@@ -1,3 +1,4 @@
+import type { InputPart } from "./parts.js";
 export type BackendCapabilities = {
     streaming: boolean;
     toolUse: boolean;
@@ -5,6 +6,10 @@ export type BackendCapabilities = {
     multimodal: boolean;
     contextWindow: number;
     interactions?: string[];
+    /** Native typed history import implemented by this runner. */
+    contextTransfer?: {
+        parts: Array<InputPart["type"]>;
+    };
 };
 export type ProviderCapabilities = {
     supportsVision: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "3.1.2",
+  "version": "4.0.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -61,6 +61,11 @@
       "import": "./dist/profile-kb/index.js",
       "types": "./dist/profile-kb/index.d.ts",
       "default": "./dist/profile-kb/index.js"
+    },
+    "./learning-state": {
+      "import": "./dist/learning-state.js",
+      "types": "./dist/learning-state.d.ts",
+      "default": "./dist/learning-state.js"
     }
   },
   "repository": {