@tangle-network/agent-interface 4.0.0 → 5.0.0

package/dist/environment-runtime.js

@@ -198,6 +198,7 @@ export const AgentEnvironmentCapabilitiesSchema = z
         freshSession: z.boolean(),
         requestIdempotency: z.boolean(),
         lookup: z.boolean(),
+        attach: z.boolean().optional(),
     })
         .optional(),
     interactions: InteractionCapabilitiesSchema.optional(),
@@ -245,6 +246,7 @@ export const AgentEnvironmentCapabilitiesSchema = z
         billingOwner: z.boolean().optional(),
         runtimeAttachments: z.strictObject({ mcp: z.literal(true) }).optional(),
         workspaceCheckpoint: z.boolean().optional(),
+        workspaceSnapshot: z.boolean().optional(),
     })
         .optional(),
     observation: z
@@ -355,7 +357,8 @@ export const AgentEnvironmentCapabilitiesSchema = z
             create.egress === undefined &&
             create.billingOwner === undefined &&
             create.runtimeAttachments === undefined &&
-            create.workspaceCheckpoint === undefined) {
+            create.workspaceCheckpoint === undefined &&
+            create.workspaceSnapshot === undefined) {
             refinement.addIssue({
                 code: "custom",
                 path: ["create"],
@@ -517,3 +520,7 @@ export async function createAgentEnvironmentWithIdempotency(records, input, crea
         throw error;
     }
 }
+export const AgentEnvironmentGetOptionsSchema = z.strictObject({
+    signal: z.custom().optional(),
+    contextTransfer: ContextTransferRequestSchema.optional(),
+});

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";
 export * from "./workspace-branching.js";
+export * from "./workspace-snapshot.js";
 export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";

package/dist/index.js

@@ -13,6 +13,7 @@ export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";
 export * from "./workspace-branching.js";
+export * from "./workspace-snapshot.js";
 export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";

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

@@ -0,0 +1,47 @@
+import type { BackendMessage } from "./backend-message.js";
+import type { PortableContextPlanMaterial } from "./portable-context-plan.js";
+export declare function portableContextMessageMetadataDigest(message: BackendMessage): `sha256:${string}`;
+/** Bind the full local source and decisions without sending omitted bytes or explanation text. */
+export declare function portableContextPlanCommitmentMaterial(plan: PortableContextPlanMaterial): {
+    kind: "portable-context-transfer-plan";
+    planId: string;
+    reviewDigest: `sha256:${string}`;
+    source: {
+        source: import("./portable-context-base.js").PortableContextSourceBoundary;
+        digest: `sha256:${string}`;
+        completeness: "complete" | "partial";
+        messages: {
+            messageId: string;
+            metadataDigest?: `sha256:${string}` | undefined;
+            parts: (`sha256:${string}` | null)[];
+        }[];
+        attachments: {
+            messageId: string;
+            partIndex: number;
+            digest: `sha256:${string}`;
+        }[];
+    };
+    destination: {
+        runner: string;
+        provider: string;
+        environmentId?: string | undefined;
+        sessionId: string;
+        runId: string;
+        executionId: string;
+        model?: string | undefined;
+        profileDigest: `sha256:${string}`;
+        workspaceSnapshotDigest?: `sha256:${string}` | undefined;
+    };
+    messages: {
+        messageId: string;
+        action: "include" | "omit";
+        parts: {
+            partIndex: number;
+            action: "include" | "omit" | "transform";
+            outputDigest?: `sha256:${string}` | undefined;
+        }[];
+    }[];
+    context: import("./portable-context-base.js").PortableConversationContext;
+    estimatedTokens?: number | undefined;
+    requiresAcceptance: boolean;
+};

package/dist/portable-context-commitments.js

@@ -0,0 +1,48 @@
+import { wireDigest } from "./portable-context-shared.js";
+export function portableContextMessageMetadataDigest(message) {
+    const { parts: _parts, ...metadata } = message;
+    return wireDigest(metadata);
+}
+/** Bind the full local source and decisions without sending omitted bytes or explanation text. */
+export function portableContextPlanCommitmentMaterial(plan) {
+    return {
+        kind: "portable-context-transfer-plan",
+        planId: plan.planId,
+        reviewDigest: wireDigest({ source: plan.source, messages: plan.messages }),
+        source: {
+            source: plan.source.source,
+            digest: plan.source.digest,
+            completeness: plan.source.completeness,
+            messages: plan.source.messages.map((message) => {
+                const decision = plan.messages.find((item) => item.messageId === message.id);
+                return {
+                    messageId: message.id,
+                    ...(decision?.action === "include" ? { metadataDigest: portableContextMessageMetadataDigest(message) } : {}),
+                    parts: message.parts.map((part, partIndex) => decision?.action === "include" &&
+                        decision.parts.find((item) => item.partIndex === partIndex)?.action === "include" ? wireDigest(part) : null),
+                };
+            }),
+            attachments: plan.source.attachments.filter((attachment) => {
+                const decision = plan.messages.find((item) => item.messageId === attachment.messageId);
+                return decision?.action === "include" && decision.parts.find((part) => part.partIndex === attachment.partIndex)?.action === "include";
+            }).map((attachment) => ({
+                messageId: attachment.messageId,
+                partIndex: attachment.partIndex,
+                digest: wireDigest(attachment),
+            })),
+        },
+        destination: plan.destination,
+        messages: plan.messages.map((message) => ({
+            messageId: message.messageId,
+            action: message.action,
+            parts: message.parts.map((part) => ({
+                partIndex: part.partIndex,
+                action: part.action,
+                ...(part.output === undefined ? {} : { outputDigest: wireDigest(part.output) }),
+            })),
+        })),
+        context: plan.context,
+        ...(plan.estimatedTokens === undefined ? {} : { estimatedTokens: plan.estimatedTokens }),
+        requiresAcceptance: plan.requiresAcceptance,
+    };
+}

package/dist/portable-context-plan-request.d.ts

@@ -60,6 +60,7 @@ export declare const PortableContextPlanRequestSchema: 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>;
     maxInputTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;

package/dist/portable-context-plan-wire.d.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { type PortableContextPlan } from "./portable-context-plan.js";
+/** Destination wire plan. The complete source and human explanations remain at the caller. */
+export declare const PortableContextTransferPlanSchema: 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;
+            messageId: 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>>;
+            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<{
+            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>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    destination: z.ZodObject<{
+        runner: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodString;
+        runId: z.ZodString;
+        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;
+        action: z.ZodEnum<{
+            include: "include";
+            omit: "omit";
+        }>;
+        parts: z.ZodArray<z.ZodObject<{
+            partIndex: z.ZodNumber;
+            action: z.ZodEnum<{
+                include: "include";
+                omit: "omit";
+                transform: "transform";
+            }>;
+            outputDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    context: z.ZodObject<{
+        source: z.ZodObject<{
+            runId: z.ZodString;
+            messageId: 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>>;
+            branchId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        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>>>;
+        }, 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>;
+    estimatedTokens: z.ZodOptional<z.ZodNumber>;
+    requiresAcceptance: z.ZodBoolean;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export type PortableContextTransferPlan = z.infer<typeof PortableContextTransferPlanSchema>;
+export declare function portableContextTransferPlanDigest(material: Omit<PortableContextTransferPlan, "digest">): `sha256:${string}`;
+export declare function projectPortableContextPlan(plan: PortableContextPlan): PortableContextTransferPlan;

package/dist/portable-context-plan-wire.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { CONTRACT_MAX_ARRAY_LENGTH } from "./contract-limits.js";
+import { PortableContextSourceBoundarySchema, PortableConversationContextSchema } from "./portable-context-base.js";
+import { portableContextMessageMetadataDigest, portableContextPlanCommitmentMaterial } from "./portable-context-commitments.js";
+import { PortableContextDestinationSchema, PortableContextPlanSchema } from "./portable-context-plan.js";
+import { idSchema, InputPartSchema, sameStringSet, sha256DigestSchema, wireDigest } from "./portable-context-shared.js";
+const partDecisionSchema = z.strictObject({
+    partIndex: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    action: z.enum(["include", "transform", "omit"]),
+    outputDigest: sha256DigestSchema.optional(),
+}).superRefine((part, refinement) => {
+    if ((part.action === "transform") !== (part.outputDigest !== undefined)) {
+        refinement.addIssue({ code: "custom", message: "only transformed parts require an output commitment" });
+    }
+});
+const messageDecisionSchema = z.strictObject({
+    messageId: idSchema,
+    action: z.enum(["include", "omit"]),
+    parts: z.array(partDecisionSchema).max(CONTRACT_MAX_ARRAY_LENGTH),
+}).superRefine((message, refinement) => {
+    if (message.action === "omit" && message.parts.some((part) => part.action !== "omit")) {
+        refinement.addIssue({ code: "custom", message: "omitted messages must omit every part" });
+    }
+});
+/** Destination wire plan. The complete source and human explanations remain at the caller. */
+export const PortableContextTransferPlanSchema = z.strictObject({
+    kind: z.literal("portable-context-transfer-plan"),
+    planId: idSchema,
+    reviewDigest: sha256DigestSchema,
+    source: z.strictObject({
+        source: PortableContextSourceBoundarySchema,
+        digest: sha256DigestSchema,
+        completeness: z.enum(["complete", "partial"]),
+        messages: z.array(z.strictObject({
+            messageId: idSchema,
+            metadataDigest: sha256DigestSchema.optional(),
+            parts: z.array(sha256DigestSchema.nullable()).max(CONTRACT_MAX_ARRAY_LENGTH),
+        })).max(CONTRACT_MAX_ARRAY_LENGTH),
+        attachments: z.array(z.strictObject({
+            messageId: idSchema,
+            partIndex: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+            digest: sha256DigestSchema,
+        })).max(CONTRACT_MAX_ARRAY_LENGTH),
+    }),
+    destination: PortableContextDestinationSchema,
+    messages: z.array(messageDecisionSchema).max(CONTRACT_MAX_ARRAY_LENGTH),
+    context: PortableConversationContextSchema,
+    estimatedTokens: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+    requiresAcceptance: z.boolean(),
+    digest: sha256DigestSchema,
+}).superRefine((plan, refinement) => {
+    const invalid = (message) => refinement.addIssue({ code: "custom", message });
+    const sourceIds = plan.source.messages.map((message) => message.messageId);
+    const decisionIds = plan.messages.map((message) => message.messageId);
+    if (new Set(sourceIds).size !== sourceIds.length || new Set(decisionIds).size !== decisionIds.length || !sameStringSet(sourceIds, decisionIds)) {
+        invalid("a transfer plan must decide every source message exactly once");
+        return;
+    }
+    if (wireDigest(plan.source.source) !== wireDigest(plan.context.source))
+        invalid("output context source must match the immutable source");
+    const outputIds = [];
+    const expectedAttachments = [];
+    for (const source of plan.source.messages) {
+        const decision = plan.messages.find((message) => message.messageId === source.messageId);
+        const ordered = [...decision.parts].sort((left, right) => left.partIndex - right.partIndex);
+        if (ordered.length !== source.parts.length || ordered.some((part, index) => part.partIndex !== index)) {
+            invalid("each source part requires exactly one transfer decision");
+            continue;
+        }
+        if ((decision.action === "include") !== (source.metadataDigest !== undefined) ||
+            ordered.some((part) => (decision.action === "include" && part.action === "include") !== (source.parts[part.partIndex] !== null))) {
+            invalid("only selected source parts and metadata may carry individual commitments");
+        }
+        if (decision.action === "omit")
+            continue;
+        outputIds.push(source.messageId);
+        const output = plan.context.messages.find((message) => message.id === source.messageId);
+        const retained = ordered.filter((part) => part.action !== "omit");
+        if (!output || portableContextMessageMetadataDigest(output) !== source.metadataDigest || retained.length === 0 || output.parts.length !== retained.length) {
+            invalid("selected message metadata and part count must match the source commitments");
+            continue;
+        }
+        for (const [outputIndex, part] of retained.entries()) {
+            const value = output.parts[outputIndex];
+            if (!InputPartSchema.safeParse(value).success || wireDigest(value) !== (part.action === "transform" ? part.outputDigest : source.parts[part.partIndex])) {
+                invalid("selected part bytes must match the accepted source or transform commitment");
+            }
+        }
+    }
+    if (JSON.stringify(outputIds) !== JSON.stringify(plan.context.messages.map((message) => message.id)))
+        invalid("selected messages must retain source order");
+    for (const attachment of plan.source.attachments) {
+        const message = plan.source.messages.find((item) => item.messageId === attachment.messageId);
+        if (message === undefined || attachment.partIndex >= message.parts.length) {
+            invalid("attachment commitment must reference a source part");
+            continue;
+        }
+        const decision = plan.messages.find((item) => item.messageId === attachment.messageId);
+        const retained = [...decision.parts].sort((a, b) => a.partIndex - b.partIndex).filter((part) => part.action !== "omit");
+        const outputIndex = retained.findIndex((part) => part.partIndex === attachment.partIndex);
+        if (decision.action !== "include" || retained[outputIndex]?.action !== "include") {
+            invalid("only selected source attachments may carry individual commitments");
+            continue;
+        }
+        const selected = plan.context.attachments.find((item) => item.messageId === attachment.messageId && item.partIndex === outputIndex && wireDigest({ ...item, partIndex: attachment.partIndex }) === attachment.digest);
+        if (selected === undefined)
+            invalid("selected attachment must match its source commitment");
+        else
+            expectedAttachments.push(selected);
+    }
+    if (wireDigest(expectedAttachments) !== wireDigest(plan.context.attachments))
+        invalid("output attachments must exactly match the selected source parts");
+    const changes = plan.messages.some((message) => message.action === "omit" || message.parts.some((part) => part.action !== "include"));
+    const partial = changes || plan.source.completeness === "partial";
+    if (plan.context.completeness !== (partial ? "partial" : "complete") || plan.requiresAcceptance !== partial)
+        invalid("changed or partial context requires explicit acceptance");
+    const { digest, ...material } = plan;
+    if (digest !== wireDigest(material))
+        invalid("portable transfer plan digest does not match its commitments");
+});
+export function portableContextTransferPlanDigest(material) {
+    return wireDigest(material);
+}
+export function projectPortableContextPlan(plan) {
+    const exact = PortableContextPlanSchema.parse(plan);
+    return PortableContextTransferPlanSchema.parse({ ...portableContextPlanCommitmentMaterial(exact), digest: exact.digest });
+}

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

@@ -11,6 +11,7 @@ export declare const PortableContextDestinationSchema: 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>;
 export type PortableContextDestination = z.infer<typeof PortableContextDestinationSchema>;
 export interface PortableContextPartPlan {
@@ -87,7 +88,7 @@ export declare const PortableContextMessagePlanSchema: z.ZodObject<{
 }, z.core.$strict>;
 export interface PortableContextPlan {
     planId: string;
-    /** Full immutable source so an executor can verify every decision itself. */
+    /** Full immutable local source for accepting decisions. Never serialize this plan to a destination. */
     source: PortableConversationContext;
     destination: PortableContextDestination;
     messages: PortableContextMessagePlan[];
@@ -144,6 +145,7 @@ export declare const PortableContextPlanSchema: 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;

package/dist/portable-context-plan.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { idSchema, InputPartSchema, sha256DigestSchema, sameStringSet, wireDigest, } from "./portable-context-shared.js";
 import { boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH } from "./contract-limits.js";
 import { PortableConversationContextSchema } from "./portable-context-base.js";
+import { portableContextPlanCommitmentMaterial } from "./portable-context-commitments.js";
 export const PortableContextDestinationSchema = z.strictObject({
     runner: idSchema,
     provider: idSchema,
@@ -12,6 +13,8 @@ export const PortableContextDestinationSchema = z.strictObject({
     executionId: idSchema,
     model: idSchema.optional(),
     profileDigest: sha256DigestSchema,
+    /** Complete portable workspace reference approved with this destination. */
+    workspaceSnapshotDigest: sha256DigestSchema.optional(),
 });
 export const PortableContextPartPlanSchema = z
     .strictObject({
@@ -87,17 +90,7 @@ const PortableContextPlanMaterialSchema = z.strictObject({
 });
 export function portableContextPlanDigest(plan) {
     const parsed = PortableContextPlanMaterialSchema.parse(plan);
-    return wireDigest({
-        planId: parsed.planId,
-        source: parsed.source,
-        destination: parsed.destination,
-        messages: parsed.messages,
-        context: parsed.context,
-        ...(parsed.estimatedTokens === undefined
-            ? {}
-            : { estimatedTokens: parsed.estimatedTokens }),
-        requiresAcceptance: parsed.requiresAcceptance,
-    });
+    return wireDigest(portableContextPlanCommitmentMaterial(parsed));
 }
 export const PortableContextPlanSchema = z
     .strictObject({
@@ -189,10 +182,14 @@ export const PortableContextPlanSchema = z
             message: "output messages do not exactly match the source decisions",
         });
     }
-    const expectedAttachments = plan.source.attachments.filter((attachment) => {
+    const expectedAttachments = plan.source.attachments.flatMap((attachment) => {
         const message = plan.messages.find((candidate) => candidate.messageId === attachment.messageId);
         const part = message?.parts.find((candidate) => candidate.partIndex === attachment.partIndex);
-        return message?.action === "include" && part?.action === "include";
+        if (message?.action !== "include" || part?.action !== "include")
+            return [];
+        const retained = [...message.parts].sort((left, right) => left.partIndex - right.partIndex)
+            .filter((item) => item.action !== "omit");
+        return [{ ...attachment, partIndex: retained.findIndex((item) => item.partIndex === attachment.partIndex) }];
     });
     if (wireDigest(expectedAttachments) !== wireDigest(plan.context.attachments)) {
         refinement.addIssue({