@tangle-network/agent-interface 4.0.0 → 5.1.0

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

@@ -3,6 +3,7 @@ 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";
+import { type PortableContextTransferPlan } from "./portable-context-plan-wire.js";
 export declare const ContextPlanAcceptanceSchema: z.ZodObject<{
     planDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     acceptedAt: z.ZodISODateTime;
@@ -15,18 +16,22 @@ export declare const ContextPlanAcceptanceSchema: z.ZodObject<{
 export type ContextPlanAcceptance = z.infer<typeof ContextPlanAcceptanceSchema>;
 export interface ContextTransferRequestMaterial {
     operationId: string;
-    plan: PortableContextPlan;
+    plan: PortableContextPlan | PortableContextTransferPlan;
     acceptance: ContextPlanAcceptance;
     profile?: AgentProfile;
     workspace?: WorkspaceRequest;
     resources?: ResourceRequest;
 }
 export declare function contextTransferRequestDigest(request: ContextTransferRequestMaterial): Sha256Digest;
+/** Validate the complete local plan, then create the selected-content destination request. */
+export declare function createContextTransferRequest(material: ContextTransferRequestMaterial): ContextTransferRequest;
 export declare const ContextTransferRequestSchema: z.ZodObject<{
     operationId: z.ZodString;
     requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     plan: z.ZodObject<{
+        kind: z.ZodLiteral<"portable-context-transfer-plan">;
         planId: z.ZodString;
+        reviewDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         source: z.ZodObject<{
             source: z.ZodObject<{
                 runId: z.ZodString;
@@ -38,29 +43,21 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
                 requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                 branchId: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             completeness: z.ZodEnum<{
                 complete: "complete";
                 partial: "partial";
             }>;
             messages: z.ZodArray<z.ZodObject<{
-                id: z.ZodString;
-                role: z.ZodEnum<{
-                    assistant: "assistant";
-                    system: "system";
-                    user: "user";
-                }>;
-                parts: z.ZodArray<z.ZodCustom<unknown, unknown>>;
-                timestamp: z.ZodISODateTime;
-                metadata: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+                messageId: z.ZodString;
+                metadataDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+                parts: z.ZodArray<z.ZodNullable<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>>;
             }, z.core.$strict>>;
             attachments: z.ZodArray<z.ZodObject<{
                 messageId: z.ZodString;
                 partIndex: z.ZodNumber;
                 digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
-                name: z.ZodOptional<z.ZodString>;
-                mediaType: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
-            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         }, z.core.$strict>;
         destination: z.ZodObject<{
             runner: z.ZodString;
@@ -71,6 +68,7 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
             executionId: z.ZodString;
             model: z.ZodOptional<z.ZodString>;
             profileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            workspaceSnapshotDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
         }, z.core.$strict>;
         messages: z.ZodArray<z.ZodObject<{
             messageId: z.ZodString;
@@ -85,26 +83,8 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
                     omit: "omit";
                     transform: "transform";
                 }>;
-                output: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-                    type: z.ZodLiteral<"text">;
-                    text: z.ZodString;
-                }, z.core.$strict>, z.ZodObject<{
-                    type: z.ZodLiteral<"file">;
-                    filename: z.ZodOptional<z.ZodString>;
-                    mediaType: z.ZodOptional<z.ZodString>;
-                    url: z.ZodOptional<z.ZodString>;
-                    path: z.ZodOptional<z.ZodString>;
-                    content: z.ZodOptional<z.ZodString>;
-                }, z.core.$strict>, z.ZodObject<{
-                    type: z.ZodLiteral<"image">;
-                    filename: z.ZodOptional<z.ZodString>;
-                    mediaType: z.ZodOptional<z.ZodString>;
-                    url: z.ZodOptional<z.ZodString>;
-                    path: z.ZodOptional<z.ZodString>;
-                }, z.core.$strict>], "type">>;
-                reason: z.ZodOptional<z.ZodString>;
+                outputDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
             }, z.core.$strict>>;
-            reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
         context: z.ZodObject<{
             source: z.ZodObject<{
@@ -407,6 +387,62 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
             createdAt: z.ZodISODateTime;
             metadata: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
         }, z.core.$strict>>;
+        snapshot: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            manifest: z.ZodObject<{
+                locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"s3">;
+                    bucket: z.ZodString;
+                    key: z.ZodString;
+                    region: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"ipfs">;
+                    cid: z.ZodString;
+                    path: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"private-cas">;
+                    namespace: z.ZodString;
+                    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                }, z.core.$strict>], "kind">;
+                sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                byteLength: z.ZodNumber;
+            }, z.core.$strict>;
+            archive: z.ZodObject<{
+                locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"s3">;
+                    bucket: z.ZodString;
+                    key: z.ZodString;
+                    region: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"ipfs">;
+                    cid: z.ZodString;
+                    path: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"private-cas">;
+                    namespace: z.ZodString;
+                    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                }, z.core.$strict>], "kind">;
+                sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                byteLength: z.ZodNumber;
+            }, z.core.$strict>;
+            source: z.ZodObject<{
+                leaseId: z.ZodString;
+                leaseRecordDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                workspace: z.ZodObject<{
+                    provider: z.ZodString;
+                    root: z.ZodString;
+                    identityDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                }, z.core.$strict>;
+                sourceSnapshotDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                sourceSnapshotPolicy: z.ZodObject<{
+                    kind: z.ZodLiteral<"provider-declared">;
+                    name: z.ZodString;
+                    version: z.ZodNumber;
+                    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
         providerOptions: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
     }, z.core.$strict>>;
     resources: z.ZodOptional<z.ZodObject<{
@@ -443,6 +479,7 @@ export declare const ContextTransferReceiptSchema: z.ZodDiscriminatedUnion<[z.Zo
         executionId: z.ZodString;
         model: z.ZodOptional<z.ZodString>;
         profileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        workspaceSnapshotDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     provider: z.ZodString;
     environmentId: z.ZodString;
@@ -479,6 +516,7 @@ export declare const ContextTransferReceiptSchema: z.ZodDiscriminatedUnion<[z.Zo
         executionId: z.ZodString;
         model: z.ZodOptional<z.ZodString>;
         profileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        workspaceSnapshotDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     provider: z.ZodString;
     environmentId: z.ZodString;
@@ -519,6 +557,7 @@ export declare const ContextTransferResultSchema: z.ZodDiscriminatedUnion<[z.Zod
         executionId: z.ZodString;
         model: z.ZodOptional<z.ZodString>;
         profileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        workspaceSnapshotDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     provider: z.ZodString;
     environmentId: z.ZodString;
@@ -555,6 +594,7 @@ export declare const ContextTransferResultSchema: z.ZodDiscriminatedUnion<[z.Zod
         executionId: z.ZodString;
         model: z.ZodOptional<z.ZodString>;
         profileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        workspaceSnapshotDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     provider: z.ZodString;
     environmentId: z.ZodString;

package/dist/portable-context-transfer.js

@@ -5,7 +5,9 @@ import { ResourceRequestSchema, WorkspaceRequestSchema } from "./environment-req
 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";
+import { PortableContextTransferPlanSchema, projectPortableContextPlan } from "./portable-context-plan-wire.js";
 import { idSchema, sha256DigestSchema, wireDigest } from "./portable-context-shared.js";
+import { agentWorkspaceSnapshotRefDigest } from "./workspace-snapshot.js";
 export const ContextPlanAcceptanceSchema = z.strictObject({
     planDigest: sha256DigestSchema,
     acceptedAt: z.iso.datetime().max(64),
@@ -13,7 +15,7 @@ export const ContextPlanAcceptanceSchema = z.strictObject({
 });
 const ContextTransferRequestMaterialSchema = z.strictObject({
     operationId: idSchema,
-    plan: PortableContextPlanSchema,
+    plan: z.union([PortableContextTransferPlanSchema, PortableContextPlanSchema]),
     acceptance: ContextPlanAcceptanceSchema,
     profile: agentProfileSchema.optional(),
     workspace: WorkspaceRequestSchema.optional(),
@@ -30,17 +32,28 @@ export function contextTransferRequestDigest(request) {
         ...(parsed.resources === undefined ? {} : { resources: parsed.resources }),
     });
 }
+/** Validate the complete local plan, then create the selected-content destination request. */
+export function createContextTransferRequest(material) {
+    const exact = ContextTransferRequestMaterialSchema.parse(material);
+    const plan = "kind" in exact.plan ? exact.plan : projectPortableContextPlan(exact.plan);
+    return ContextTransferRequestSchema.parse({ ...exact, plan, requestDigest: contextTransferRequestDigest(exact) });
+}
 export const ContextTransferRequestSchema = z
     .strictObject({
     operationId: idSchema,
     requestDigest: sha256DigestSchema,
-    plan: PortableContextPlanSchema,
+    plan: PortableContextTransferPlanSchema,
     acceptance: ContextPlanAcceptanceSchema,
     profile: agentProfileSchema.optional(),
     workspace: WorkspaceRequestSchema.optional(),
     resources: ResourceRequestSchema.optional(),
 })
     .superRefine((request, refinement) => {
+    const snapshot = request.workspace?.snapshot;
+    if (snapshot === undefined ? request.plan.destination.workspaceSnapshotDigest !== undefined :
+        request.plan.destination.workspaceSnapshotDigest !== agentWorkspaceSnapshotRefDigest(snapshot)) {
+        refinement.addIssue({ code: "custom", path: ["plan", "destination", "workspaceSnapshotDigest"], message: "accepted workspace snapshot digest must match the exact transfer snapshot" });
+    }
     if (request.plan.destination.environmentId === undefined && request.profile === undefined) {
         refinement.addIssue({ code: "custom", path: ["profile"], message: "an unbound destination requires its exact profile" });
     }

package/dist/portable-context.d.ts

@@ -1,5 +1,6 @@
 export * from "./portable-context-base.js";
 export * from "./portable-context-plan.js";
+export * from "./portable-context-plan-wire.js";
 export * from "./portable-context-plan-request.js";
 export * from "./portable-context-transfer.js";
 export * from "./portable-context-continuation.js";

package/dist/portable-context.js

@@ -1,5 +1,6 @@
 export * from "./portable-context-base.js";
 export * from "./portable-context-plan.js";
+export * from "./portable-context-plan-wire.js";
 export * from "./portable-context-plan-request.js";
 export * from "./portable-context-transfer.js";
 export * from "./portable-context-continuation.js";

package/dist/workspace-snapshot.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import type { AgentCandidateArtifactRef, Sha256Digest } from "./agent-candidate.js";
+import { type AgentWorkspaceLeaseRecord } from "./agent-workspace-lease.js";
+/** Public source binding. A lease identifier or artifact locator grants no authority. */
+export type AgentWorkspaceSnapshotSource = Pick<AgentWorkspaceLeaseRecord, "leaseId" | "workspace" | "sourceSnapshotDigest" | "sourceSnapshotPolicy"> & {
+    leaseRecordDigest: Sha256Digest;
+};
+/**
+ * Reference-only projection of the canonical candidate workspace archive.
+ * Runtime resolves and verifies the canonical manifest and archive before restore. The manifest
+ * digest binds file bytes and modes; the archive hash additionally binds Git HEAD and index state.
+ * Capture requires the source owner's private lease. Acceptance binds this complete value, not
+ * only `digest`. Receivers authorize each closed artifact reference for the accepted operation.
+ */
+export interface AgentWorkspaceSnapshotRef {
+    kind: "agent-candidate-workspace-snapshot";
+    digest: Sha256Digest;
+    manifest: AgentCandidateArtifactRef;
+    archive: AgentCandidateArtifactRef;
+    source: AgentWorkspaceSnapshotSource;
+}
+export declare const AgentWorkspaceSnapshotRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    manifest: z.ZodObject<{
+        locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"s3">;
+            bucket: z.ZodString;
+            key: z.ZodString;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"ipfs">;
+            cid: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"private-cas">;
+            namespace: z.ZodString;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], "kind">;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>;
+    archive: z.ZodObject<{
+        locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"s3">;
+            bucket: z.ZodString;
+            key: z.ZodString;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"ipfs">;
+            cid: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"private-cas">;
+            namespace: z.ZodString;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], "kind">;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>;
+    source: z.ZodObject<{
+        leaseId: z.ZodString;
+        leaseRecordDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        workspace: z.ZodObject<{
+            provider: z.ZodString;
+            root: z.ZodString;
+            identityDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+        sourceSnapshotDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        sourceSnapshotPolicy: z.ZodObject<{
+            kind: z.ZodLiteral<"provider-declared">;
+            name: z.ZodString;
+            version: z.ZodNumber;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Acceptance identity of the complete reference, including Git archive and source binding. */
+export declare function agentWorkspaceSnapshotRefDigest(snapshot: AgentWorkspaceSnapshotRef): Sha256Digest;

package/dist/workspace-snapshot.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { agentCandidateArtifactRefSchema } from "./agent-candidate-artifact-schema.js";
+import { canonicalCandidateDigest, sha256DigestSchema } from "./agent-candidate-schema-common.js";
+import { agentWorkspaceAllocationIdentitySchema, } from "./agent-workspace-lease.js";
+import { agentWorkspacePublicIdentifierSchema, agentWorkspaceSourceSnapshotPolicySchema, } from "./agent-workspace-source-snapshot.js";
+const nonemptyArtifactRefSchema = agentCandidateArtifactRefSchema.superRefine((ref, ctx) => {
+    if (!Number.isSafeInteger(ref.byteLength) || ref.byteLength < 1) {
+        ctx.addIssue({ code: "custom", path: ["byteLength"], message: "workspace artifact length must be a positive safe integer" });
+    }
+});
+export const AgentWorkspaceSnapshotRefSchema = z.strictObject({
+    kind: z.literal("agent-candidate-workspace-snapshot"),
+    digest: sha256DigestSchema,
+    manifest: nonemptyArtifactRefSchema,
+    archive: nonemptyArtifactRefSchema,
+    source: z.strictObject({
+        leaseId: agentWorkspacePublicIdentifierSchema,
+        leaseRecordDigest: sha256DigestSchema,
+        workspace: agentWorkspaceAllocationIdentitySchema,
+        sourceSnapshotDigest: sha256DigestSchema,
+        sourceSnapshotPolicy: agentWorkspaceSourceSnapshotPolicySchema,
+    }),
+}).superRefine((snapshot, ctx) => {
+    if (snapshot.digest !== snapshot.manifest.sha256) {
+        ctx.addIssue({ code: "custom", path: ["manifest", "sha256"], message: "workspace digest must equal the canonical manifest hash" });
+    }
+});
+/** Acceptance identity of the complete reference, including Git archive and source binding. */
+export function agentWorkspaceSnapshotRefDigest(snapshot) {
+    return canonicalCandidateDigest(AgentWorkspaceSnapshotRefSchema.parse(snapshot));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",