@tangle-network/agent-interface 2.2.0 → 2.3.1

package/dist/environment-runtime.d.ts

@@ -827,6 +827,8 @@ export interface AgentEnvironmentCapabilities {
     branching: {
         checkpoint: boolean;
         fork: boolean;
+        /** True only when a fork can preserve and prove confidential requirements. */
+        confidential?: boolean;
         /** True only when key + canonical request digest semantics are implemented. */
         retrySafe?: boolean;
         /** True only when operations can be recovered by idempotency key. */
@@ -984,6 +986,7 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
     branching: z.ZodObject<{
         checkpoint: z.ZodBoolean;
         fork: z.ZodBoolean;
+        confidential: z.ZodOptional<z.ZodBoolean>;
         retrySafe: z.ZodOptional<z.ZodBoolean>;
         lookup: z.ZodOptional<z.ZodBoolean>;
         cleanup: z.ZodOptional<z.ZodBoolean>;
@@ -1084,6 +1087,8 @@ export interface CreateAgentEnvironmentInput {
  * The operation key names the request and the abort signal controls one
  * attempt, so neither belongs in the input identity. Every other field is
  * canonicalized with the shared RFC 8785 JSON representation.
+ * A keyed create therefore accepts only canonical JSON material.
+ * Unkeyed creates can retain opaque provider-native mapper values.
  * @internal
  */
 export declare function agentEnvironmentCreateInputDigest(input: CreateAgentEnvironmentInput): Sha256Digest;
@@ -1115,9 +1120,15 @@ export declare function replayedAgentEnvironmentView<T extends object>(environme
  * with the creation verdict the provider could prove. Every same-key call
  * after it, including one that awaited the same pending create, receives
  * {@link replayedAgentEnvironmentView} of that environment.
+ *
+ * A keyed create callback receives one immutable canonical JSON snapshot.
+ * Its digest and provider therefore read identical request bytes even when
+ * the caller mutates its original object after this function returns.
+ * An unkeyed create retains its original input so opaque provider-native
+ * mapper values retain their public identity.
  * @internal
  */
-export declare function createAgentEnvironmentWithIdempotency<T extends object>(records: Map<string, AgentEnvironmentCreateIdempotencyRecord<T>>, input: CreateAgentEnvironmentInput, create: () => Promise<T>): Promise<T>;
+export declare function createAgentEnvironmentWithIdempotency<T extends object>(records: Map<string, AgentEnvironmentCreateIdempotencyRecord<T>>, input: CreateAgentEnvironmentInput, create: (input: CreateAgentEnvironmentInput) => Promise<T>): Promise<T>;
 export interface AgentEnvironmentProvider {
     readonly name: string;
     readonly exactProcess?: AgentExactProcessProvider;

package/dist/environment-runtime.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
-import { canonicalCandidateDigest } from "./agent-candidate-schema-common.js";
+import { canonicalCandidateDigest, canonicalCandidateJson, } from "./agent-candidate-schema-common.js";
 import { InteractionCapabilitiesSchema, RequestedInteractionsSchema } from "./interaction.js";
 import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextBoundaryProofSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
 import { AgentExactRunControlRefSchema, AgentRunControlRefSchema, CanonicalStreamEventSchema } from "./runtime-control.js";
 import { AgentProfileCapabilitiesSchema } from "./environment-profile-capabilities.js";
 import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedJsonSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH } from "./contract-limits.js";
 import { InputPartSchema } from "./portable-context-shared.js";
+import { deepFreeze } from "./deep-freeze.js";
 export const AgentTurnInputSchema = z.strictObject({
     prompt: boundedStringSchema.optional(),
     parts: z.array(InputPartSchema).max(CONTRACT_MAX_ARRAY_LENGTH).optional(),
@@ -215,6 +216,7 @@ export const AgentEnvironmentCapabilitiesSchema = z
     branching: z.strictObject({
         checkpoint: z.boolean(),
         fork: z.boolean(),
+        confidential: z.boolean().optional(),
         retrySafe: z.boolean().optional(),
         lookup: z.boolean().optional(),
         cleanup: z.boolean().optional(),
@@ -422,6 +424,8 @@ export const AgentEnvironmentCapabilitiesSchema = z
  * The operation key names the request and the abort signal controls one
  * attempt, so neither belongs in the input identity. Every other field is
  * canonicalized with the shared RFC 8785 JSON representation.
+ * A keyed create therefore accepts only canonical JSON material.
+ * Unkeyed creates can retain opaque provider-native mapper values.
  * @internal
  */
 export function agentEnvironmentCreateInputDigest(input) {
@@ -459,14 +463,26 @@ export function replayedAgentEnvironmentView(environment) {
  * with the creation verdict the provider could prove. Every same-key call
  * after it, including one that awaited the same pending create, receives
  * {@link replayedAgentEnvironmentView} of that environment.
+ *
+ * A keyed create callback receives one immutable canonical JSON snapshot.
+ * Its digest and provider therefore read identical request bytes even when
+ * the caller mutates its original object after this function returns.
+ * An unkeyed create retains its original input so opaque provider-native
+ * mapper values retain their public identity.
  * @internal
  */
 export async function createAgentEnvironmentWithIdempotency(records, input, create) {
-    input.signal?.throwIfAborted();
-    const key = input.idempotencyKey;
+    const { idempotencyKey: key, signal, ...material } = input;
+    signal?.throwIfAborted();
     if (key === undefined)
-        return create();
-    const digest = agentEnvironmentCreateInputDigest(input);
+        return create(input);
+    const snapshot = deepFreeze(JSON.parse(canonicalCandidateJson(material)));
+    const acceptedInput = Object.freeze({
+        ...snapshot,
+        idempotencyKey: key,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    const digest = agentEnvironmentCreateInputDigest(acceptedInput);
     const existing = records.get(key);
     if (existing !== undefined) {
         if (existing.digest !== digest) {
@@ -474,7 +490,7 @@ export async function createAgentEnvironmentWithIdempotency(records, input, crea
         }
         return replayedAgentEnvironmentView(existing.environment ?? (await existing.pending));
     }
-    const pending = Promise.resolve().then(create);
+    const pending = Promise.resolve().then(() => create(acceptedInput));
     const record = {
         digest,
         pending,

package/dist/workspace-confidentiality.d.ts

@@ -9,6 +9,8 @@ import { type AgentExactRunControlRef } from "./runtime-control.js";
 export declare const ConfidentialAttestationSchema: z.ZodObject<{
     provider: z.ZodString;
     requested: z.ZodLiteral<true>;
+    tee: z.ZodOptional<z.ZodString>;
+    sealed: z.ZodOptional<z.ZodBoolean>;
     nonce: z.ZodString;
     measurement: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     environmentId: z.ZodString;
@@ -32,11 +34,15 @@ export type ConfidentialAttestation = z.infer<typeof ConfidentialAttestationSche
 /** What the caller asked for, separate from what the provider proved. */
 export declare const ConfidentialExecutionRequestSchema: z.ZodObject<{
     requested: z.ZodBoolean;
+    tee: z.ZodOptional<z.ZodString>;
+    sealed: z.ZodOptional<z.ZodBoolean>;
     nonce: z.ZodOptional<z.ZodString>;
     policy: z.ZodOptional<z.ZodString>;
     profileDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
 }, z.core.$strict>;
 export type ConfidentialExecutionRequest = z.infer<typeof ConfidentialExecutionRequestSchema>;
+/** Match one requested TEE against a provider-reported TEE identifier. */
+export declare function confidentialTeeMatchesRequest(requested: string | undefined, attested: string | undefined): boolean;
 export interface ConfidentialExecutionEnvironment {
     provider: string;
     environmentId: string;

package/dist/workspace-confidentiality.js

@@ -11,6 +11,10 @@ export const ConfidentialAttestationSchema = z
     .strictObject({
     provider: idSchema,
     requested: z.literal(true),
+    /** Provider-reported TEE type after external evidence verification. */
+    tee: idSchema.optional(),
+    /** Verified no-persistence posture, when the provider can prove it. */
+    sealed: z.boolean().optional(),
     nonce: idSchema,
     measurement: sha256DigestSchema,
     environmentId: idSchema,
@@ -43,11 +47,18 @@ export const ConfidentialAttestationSchema = z
 export const ConfidentialExecutionRequestSchema = z
     .strictObject({
     requested: z.boolean(),
+    /** Requested TEE. Omit it to accept any provider-supported TEE. */
+    tee: idSchema.optional(),
+    /** Require the provider to avoid persistence after the environment ends. */
+    sealed: z.boolean().optional(),
     nonce: idSchema.optional(),
     policy: idSchema.optional(),
     profileDigest: sha256DigestSchema.optional(),
 })
     .superRefine((request, refinement) => {
+    const carriesAdmissionField = request.nonce !== undefined ||
+        request.policy !== undefined ||
+        request.profileDigest !== undefined;
     const complete = request.nonce !== undefined &&
         request.policy !== undefined &&
         request.profileDigest !== undefined;
@@ -58,14 +69,48 @@ export const ConfidentialExecutionRequestSchema = z
             message: "a confidential execution request must bind nonce, policy, and profile digest",
         });
     }
-    if (!request.requested && complete) {
+    if (!request.requested &&
+        (carriesAdmissionField ||
+            request.tee !== undefined ||
+            request.sealed !== undefined)) {
         refinement.addIssue({
             code: "custom",
             path: ["requested"],
-            message: "a non-confidential execution request cannot carry confidential admission fields",
+            message: "a non-confidential execution request cannot carry confidential requirements or admission fields",
         });
     }
 });
+function normalizedTeeId(value) {
+    const normalized = value.trim().toLowerCase().replaceAll("_", "-");
+    switch (normalized) {
+        case "aws-nitro":
+        case "aws-nitro-enclave":
+        case "aws-nitro-enclaves":
+            return "nitro";
+        case "intel-tdx":
+            return "tdx";
+        case "amd-sev":
+        case "amd-sev-snp":
+        case "sev":
+            return "sev-snp";
+        case "dstack":
+        case "phala":
+            return "phala-dstack";
+        default:
+            return normalized;
+    }
+}
+/** Match one requested TEE against a provider-reported TEE identifier. */
+export function confidentialTeeMatchesRequest(requested, attested) {
+    if (attested === undefined)
+        return requested === undefined;
+    const normalizedAttested = normalizedTeeId(attested);
+    if (normalizedAttested === "none")
+        return false;
+    if (requested === undefined || normalizedTeeId(requested) === "any")
+        return true;
+    return (normalizedAttested === normalizedTeeId(requested));
+}
 /**
  * Verify every request/result binding and require an external provider-key
  * check before exposing a positive confidentiality result.
@@ -104,6 +149,8 @@ export function confidentialExecutionVerified(input) {
         attestation.nonce !== request.nonce ||
         attestation.policy !== request.policy ||
         attestation.profileDigest !== request.profileDigest ||
+        !confidentialTeeMatchesRequest(request.tee, attestation.tee) ||
+        (request.sealed === true && attestation.sealed !== true) ||
         environment.confidentialRequested !== request.requested) {
         return false;
     }
@@ -114,6 +161,8 @@ export function confidentialExecutionRequestDigest(request) {
     const parsed = ConfidentialExecutionRequestSchema.parse(request);
     return wireDigest({
         requested: parsed.requested,
+        ...(parsed.tee === undefined ? {} : { tee: parsed.tee }),
+        ...(parsed.sealed === undefined ? {} : { sealed: parsed.sealed }),
         ...(parsed.nonce === undefined ? {} : { nonce: parsed.nonce }),
         ...(parsed.policy === undefined ? {} : { policy: parsed.policy }),
         ...(parsed.profileDigest === undefined

package/dist/workspace-fork.d.ts

@@ -52,6 +52,8 @@ export declare const WorkspaceForkRequestSchema: z.ZodObject<{
     }, z.core.$strict>;
     confidential: z.ZodOptional<z.ZodObject<{
         requested: z.ZodBoolean;
+        tee: z.ZodOptional<z.ZodString>;
+        sealed: z.ZodOptional<z.ZodBoolean>;
         nonce: z.ZodOptional<z.ZodString>;
         policy: z.ZodOptional<z.ZodString>;
         profileDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
@@ -115,6 +117,8 @@ export declare const ForkedEnvironmentRefSchema: z.ZodObject<{
     confidentialAttestation: z.ZodOptional<z.ZodObject<{
         provider: z.ZodString;
         requested: z.ZodLiteral<true>;
+        tee: z.ZodOptional<z.ZodString>;
+        sealed: z.ZodOptional<z.ZodBoolean>;
         nonce: z.ZodString;
         measurement: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         environmentId: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -88,7 +88,7 @@
     "zod": "4.5.4"
   },
   "devDependencies": {
-    "@types/node": "26.4.0",
+    "@types/node": "26.4.1",
     "@types/spdx-expression-parse": "4.0.0",
     "typescript": "7.0.2",
     "vitest": "4.1.11"