@tangle-network/agent-interface 4.0.0 → 5.1.0

package/README.md

@@ -45,6 +45,10 @@ A capability declaration is not evidence that it was delivered, opened, or appli
 
 ## Workspace paths
 
+`WorkspaceRequest.snapshot` restores a portable workspace through closed content-addressed manifest and archive references. It includes the source lease and policy identities, and carries no inline file bytes. The accepted request binds both artifact hashes, because the archive also identifies Git HEAD and staged state. A snapshot cannot be combined with `repoUrl`, `gitRef` or a provider-native `checkpoint`; its `cwd` uses the repository base.
+
+Only a qualified deployed receiver advertises `create.workspaceSnapshot`. It authorizes and verifies artifacts, enforces archive limits, and finishes restoration into a fresh owned destination before accepting a turn. An unsupported adapter refuses before credentials, provisioning or native admission. Hashes and public lease identities do not grant artifact access or workspace control.
+
 `WorkspaceRequest.cwd` is an explicitly based path reference.
 Use `base: "repository"` for a portable repository-relative POSIX path.
 Use `base: "host"` for a provider-owned native host path.
@@ -95,11 +99,14 @@ An omitted permission scope permits only a one-time response; session and persis
 The legacy `SdkProviderAdapter.respondToInteraction(response)` remains source-compatible, while new adapters use `respondToInteractionCommand(command)` for exact binding and durable acknowledgement.
 
 Portable conversation transfer reuses `BackendMessage` and `InputPart` rather than defining another message format.
-Planning is represented separately from execution: a plan embeds the immutable source, lists every message and part decision, names the destination runner, contains the exact derived context, and carries a canonical digest.
+Planning is represented separately from execution. A local `PortableContextPlan` embeds the immutable source, lists every message and part decision, names the destination runner, contains the exact derived context, and carries a canonical digest. Keep this complete plan local.
 Every plan request has a canonical request digest, and every ready, over-limit, or unsupported result repeats the request identifier and digest.
 `portableContextPlanResultMatchesRequest()` verifies that the result belongs to the exact request, the returned source and destination match, and a ready plan stays within its requested token limit.
 Partial input or output always requires explicit user or policy acceptance, even when no individual message was transformed.
-`ContextTransferRequest` binds an operation identifier to that accepted plan, while `ContextTransferResult` distinguishes first admission, exact replay, changed-input conflict, and unknown transport outcome.
+`createContextTransferRequest()` validates a local plan and projects it into a `PortableContextTransferPlan` containing only selected typed content and hash commitments. Omitted messages, omitted parts, and human decision explanations do not travel to the destination. The destination verifies the same accepted plan digest using these commitments. Selected attachments use indexes in the selected output, even when earlier parts were omitted.
+Individual commitments cover selected source metadata, parts, and attachments. Omitted parts and explanation text have no individual hashes; a combined review digest binds the full local source and decisions. Digests bind content and do not encrypt it.
+`ContextTransferRequestSchema` accepts only this destination representation. The Interface 5 plan digest algorithm and transfer request shape require coordinated consumer and receiver upgrades. Preserve or settle legacy operation records through an explicit versioned recovery path before upgrading a receiver.
+`ContextTransferRequest` binds an operation identifier to the accepted transfer plan, while `ContextTransferResult` distinguishes first admission, exact replay, changed-input conflict, and unknown transport outcome.
 `contextTransferResultMatchesRequest()` checks the operation identifier and request digest for every outcome before a caller accepts, retries, or reports it.
 Its successful receipt repeats the exact destination and carries the provider's session-creation operation and timestamp, identifying the one fresh provider session that admitted the context.
 An accepted destination may omit `environmentId` when the provider allocates that identity. The receipt preserves the original destination and binds its actual fresh `environmentId`; a prebound destination still requires exact equality. Unbound creation requires the inline `profile` with its accepted canonical digest. Optional `workspace` and `resources` inputs are frozen into the transfer request digest, so changed retries conflict.

package/dist/agent-candidate.d.ts

@@ -37,6 +37,18 @@ export interface AgentCandidateArtifactRef {
     sha256: Sha256Digest;
     byteLength: number;
 }
+/** Reads one content-addressed object through an authorized closed-locator resolver. */
+export interface AgentCandidateArtifactPort {
+    read(ref: AgentCandidateArtifactRef): Promise<Uint8Array>;
+    /** Stream an artifact without materializing its complete contents. */
+    readStream?(ref: AgentCandidateArtifactRef, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array>;
+    /** Find an already stored object by its exact content digest and length. */
+    locate?(object: Pick<AgentCandidateArtifactRef, "sha256" | "byteLength">, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentCandidateArtifactRef | undefined>;
+}
 /** Bytes embedded directly in a candidate manifest. */
 export interface AgentCandidateEmbeddedArtifact {
     encoding: "base64";

package/dist/environment-provider.d.ts

@@ -8,3 +8,4 @@ export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";
 export * from "./environment-command-turn.js";
 export * from "./workspace-cwd.js";
+export * from "./workspace-snapshot.js";

package/dist/environment-provider.js

@@ -8,3 +8,4 @@ export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";
 export * from "./environment-command-turn.js";
 export * from "./workspace-cwd.js";
+export * from "./workspace-snapshot.js";

package/dist/environment-requests.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { WorkspaceCwd } from "./workspace-cwd.js";
 import { type WorkspaceCheckpointRef } from "./workspace-checkpoint.js";
 import type { AgentProfile } from "./agent-profile.js";
+import { type AgentWorkspaceSnapshotRef } from "./workspace-snapshot.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";
@@ -63,6 +64,13 @@ export interface WorkspaceRequest {
      * checkpoint another provider took.
      */
     checkpoint?: WorkspaceCheckpointRef;
+    /**
+     * Restore an accepted portable workspace from authorized immutable artifact references before
+     * create returns. This is independent of provider-native checkpoint IDs. The receiver verifies
+     * manifest, archive, limits and source binding, and publishes into a fresh owned destination.
+     * It refuses an occupied destination without changing it. Requires create.workspaceSnapshot.
+     */
+    snapshot?: AgentWorkspaceSnapshotRef;
     /** Opaque provider-native workspace fields. */
     providerOptions?: Record<string, unknown>;
 }
@@ -95,6 +103,62 @@ export declare const WorkspaceRequestSchema: 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>;
 export interface ResourceRequest {

package/dist/environment-requests.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, } from "./contract-limits.js";
 import { workspaceCwdSchema } from "./workspace-cwd.js";
 import { WorkspaceCheckpointRefSchema } from "./workspace-checkpoint.js";
+import { AgentWorkspaceSnapshotRefSchema } from "./workspace-snapshot.js";
 /**
  * One allowed destination host.
  *
@@ -38,9 +39,16 @@ export const WorkspaceRequestSchema = z
     gitRef: boundedIdentifierSchema.optional(),
     cwd: workspaceCwdSchema.optional(),
     checkpoint: WorkspaceCheckpointRefSchema.optional(),
+    snapshot: AgentWorkspaceSnapshotRefSchema.optional(),
     providerOptions: boundedJsonRecordSchema.optional(),
 })
     .superRefine((workspace, refinement) => {
+    if (workspace.snapshot !== undefined && (workspace.repoUrl !== undefined || workspace.gitRef !== undefined || workspace.checkpoint !== undefined)) {
+        refinement.addIssue({ code: "custom", path: ["snapshot"], message: "workspace snapshot cannot be combined with another workspace source" });
+    }
+    if (workspace.snapshot !== undefined && workspace.cwd?.base === "host") {
+        refinement.addIssue({ code: "custom", path: ["cwd"], message: "workspace snapshot cwd must be relative to its restored repository" });
+    }
     if (workspace.checkpoint !== undefined && workspace.repoUrl !== undefined) {
         refinement.addIssue({
             code: "custom",