@tangle-network/agent-provider-tangle 0.13.3 → 0.14.0

package/dist/tangle-types.d.ts

@@ -1,5 +1,5 @@
 import type { BackendRegistryEntry, BackendRegistryResponse, BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, AgentExecutionPreparationReceipt, AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentProfile, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
+import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, AgentExecutionPreparationReceipt, AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentProfile, ConfidentialAttestation, ConfidentialExecutionEnvironment, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 /**
  * The platform verdict for the create call that returned a sandbox.
@@ -170,6 +170,86 @@ export interface SandboxProcessManagerLike {
 export interface SandboxConnectionLike {
     runtimeUrl?: string;
 }
+/**
+ * The keyed snapshot acknowledgement exposed by the Sandbox SDK.
+ *
+ * Every structural type below declares only the fields this adapter reads. A
+ * newer SDK may return more, and an unread field never becomes a contract.
+ */
+export interface SandboxSnapshotResultLike {
+    snapshotId: string;
+    createdAt: Date | string;
+    tags: string[];
+    idempotency?: {
+        outcome: "created" | "replayed";
+        requestDigest: string;
+    };
+}
+/** Snapshot metadata returned by the managed Sandbox storage service. */
+export interface SandboxSnapshotInfoLike {
+    snapshotId: string;
+    sandboxId: string;
+    createdAt: Date | string;
+    tags: string[];
+}
+/** A deletion result must state what the platform actually did. */
+export interface SandboxSnapshotDeleteAcknowledgementLike {
+    snapshotId: string;
+    outcome: "deleted" | "already_absent" | "unknown";
+}
+/** Result returned by the SDK's durable operation lookup route. */
+export interface SandboxWorkspaceOperationLookupLike {
+    outcome: "found" | "not_found" | "conflict" | "unknown";
+    kind: "checkpoint" | "fork";
+    state?: "pending" | "succeeded" | "failed";
+}
+/** Fan-out acknowledgement returned by SandboxInstance.fork(). */
+export interface SandboxForkAcknowledgementLike {
+    children: SandboxInstanceLike[];
+    requestedCount: number;
+    materializedCount: number;
+    complete: boolean;
+    idempotency?: {
+        outcome: "created" | "replayed";
+        requestDigest: string;
+    };
+}
+/** A forked Sandbox child can be destroyed with an explicit outcome. */
+export interface SandboxDeleteAcknowledgementLike {
+    sandboxId: string;
+    outcome: "destroyed" | "already_absent" | "unknown";
+}
+/** Raw TEE evidence returned by Sandbox, before provider-key verification. */
+export interface SandboxTeeAttestationReportLike {
+    tee_type: string;
+    evidence: number[];
+    measurement: number[];
+    timestamp: number;
+}
+export interface SandboxTeeAttestationResponseLike {
+    sandbox_id: string;
+    attestation: SandboxTeeAttestationReportLike;
+    attestationNonce?: string;
+}
+/**
+ * Evidence returned by an external TEE verifier after it checks the raw quote.
+ * The provider never derives these fields from request metadata or the quote.
+ */
+export interface TangleConfidentialAttestationVerification {
+    providerKeyId: string;
+    providerSignature: string;
+    /** Optional verifier-normalized measurement, checked against raw evidence. */
+    measurement?: `sha256:${string}`;
+}
+/**
+ * Provider-owned trust boundary for TEE evidence.
+ * Return `null` when the quote, nonce, key, or policy is not trusted.
+ */
+export type TangleConfidentialAttestationVerifier = (input: {
+    report: SandboxTeeAttestationReportLike;
+    expected: ConfidentialExecutionEnvironment;
+    attestation: ConfidentialAttestation;
+}) => TangleConfidentialAttestationVerification | null | Promise<TangleConfidentialAttestationVerification | null>;
 /** Live cgroup sample for one sandbox. `null` fields mean the host reported none. */
 export interface SandboxResourceUsageLike {
     memoryCurrentMb: number;
@@ -316,6 +396,8 @@ export interface SandboxInstanceLike {
     connection?: SandboxConnectionLike;
     /** When the platform retires this sandbox, when it set a lifetime. */
     expiresAt?: Date | string;
+    /** Stable platform creation time, returned by branch child descriptions. */
+    createdAt?: Date | string;
     /** GPU lease attached at create time, when one was requested. */
     gpuLease?: SandboxGpuLeaseLike;
     streamPrompt(message: string | InputPart[], options?: PromptOptions): AsyncIterable<SandboxEvent>;
@@ -383,12 +465,39 @@ export interface SandboxInstanceLike {
      * by id or when the platform reported no receipt.
      */
     createReceipt?(): SandboxCreateReceiptLike | null;
-    refresh?(options?: {
-        signal?: AbortSignal;
-    }): Promise<void>;
+    refresh?(signal?: AbortSignal): Promise<void>;
     delete?(options?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
+    /** Managed whole-workspace checkpoint operation. */
+    snapshot?(options?: {
+        tags?: string[];
+        idempotencyKey?: string;
+    }): Promise<SandboxSnapshotResultLike>;
+    /** Recover checkpoint metadata after a provider process restart. */
+    listSnapshots?(): Promise<SandboxSnapshotInfoLike[]>;
+    /** Delete one managed checkpoint. */
+    deleteSnapshot?(snapshotId: string, options?: {
+        timeoutMs?: number;
+    }): Promise<SandboxSnapshotDeleteAcknowledgementLike>;
+    /** Ask the service for the state of a keyed checkpoint operation. */
+    getSnapshotOperation?(idempotencyKey: string, options?: {
+        tags?: string[];
+    }): Promise<SandboxWorkspaceOperationLookupLike>;
+    /** Managed copy-on-write fork operation. */
+    fork?(count: number, options?: {
+        metadata?: Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<SandboxForkAcknowledgementLike>;
+    /** Recover fork state after a provider process restart. */
+    getForkOperation?(idempotencyKey: string, options: {
+        count: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<SandboxWorkspaceOperationLookupLike>;
+    /** Raw TEE quote and measurement; verification stays outside Sandbox. */
+    getTeeAttestation?(options?: {
+        attestationNonce?: string;
+    }): Promise<SandboxTeeAttestationResponseLike>;
 }
 export interface SandboxSessionLike {
     readonly id: string;
@@ -463,4 +572,6 @@ export interface TangleProviderOptions {
     validateProfile?: AgentEnvironmentProvider["validateProfile"];
     mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
     exactProcess?: TangleExactProcessOptions;
+    /** External provider-key and measurement verifier for confidential forks. */
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
 }

package/dist/tangle-workspace-branching.d.ts

@@ -0,0 +1,24 @@
+import type { AgentWorkspaceBranching } from "@tangle-network/agent-interface";
+import type { SandboxClientLike, SandboxInstanceLike, TangleConfidentialAttestationVerifier } from "./tangle-types.js";
+export interface TangleWorkspaceBranchingOptions {
+    box: SandboxInstanceLike;
+    client: SandboxClientLike;
+    provider: string;
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
+}
+/**
+ * Carry the verifier only when the caller supplied one. Every option type that
+ * accepts it is exact-optional, so an explicit `undefined` is not an absent key.
+ */
+export declare function confidentialVerifierOption(verifier: TangleConfidentialAttestationVerifier | undefined): {
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
+};
+/**
+ * Build the exact workspace contract over the managed Sandbox operations.
+ *
+ * The adapter requires list and lookup surfaces in addition to create and
+ * delete methods. Without recovery, it cannot safely claim durable branching.
+ */
+export declare function createTangleWorkspaceBranching(options: TangleWorkspaceBranchingOptions): AgentWorkspaceBranching | undefined;
+/** Capability support requires every operation used by recovery and cleanup. */
+export declare function supportsWorkspaceBranching(box: SandboxInstanceLike, client: SandboxClientLike): boolean;