@tangle-network/agent-interface 2.1.1 → 2.3.0

package/dist/environment-provider.d.ts

@@ -1,3 +1,4 @@
+export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";
 export * from "./environment-requests.js";
 export * from "./environment-exact-process.js";
 export * from "./environment-interactive.js";

package/dist/environment-provider.js

@@ -1,3 +1,4 @@
+export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";
 export * from "./environment-requests.js";
 export * from "./environment-exact-process.js";
 export * from "./environment-interactive.js";

package/dist/environment-requests.d.ts

@@ -5,6 +5,37 @@ import type { AgentProfile } from "./agent-profile.js";
 export type AgentProfileRef = AgentProfile | string;
 export type AgentEnvironmentStatus = "pending" | "provisioning" | "running" | "stopped" | "failed" | "expired" | "unknown";
 export type AgentSessionStatus = AgentEnvironmentStatus | "completed" | "cancelled";
+/** Outbound network modes an ordinary agent environment can request. */
+export type AgentEnvironmentEgressMode = "open" | "strict" | "blocked";
+/**
+ * Outbound network policy for one agent environment.
+ *
+ * `open` permits every destination. `strict` permits only the named domains plus the model
+ * endpoints the provider itself provisioned into the environment. `blocked` denies every
+ * destination.
+ *
+ * A provider that cannot satisfy the requested mode must fail the create. It must never weaken
+ * the policy and never widen it: a policy that differs from the request is invisible from inside
+ * the environment, and the refusal it produces there reads as an authorization error that names
+ * nothing.
+ */
+export type AgentEnvironmentEgressPolicy = {
+    mode: "open";
+} | {
+    mode: "blocked";
+} | {
+    mode: "strict";
+    allowDomains?: readonly string[];
+};
+/** Runtime contract for the portable egress policy carried by providers. */
+export declare const AgentEnvironmentEgressPolicySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"open">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"blocked">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"strict">;
+    allowDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>], "mode">;
 export interface WorkspaceRequest {
     /** Provider-specific environment/template id, for example "universal". */
     environment?: string;

package/dist/environment-requests.js

@@ -1,6 +1,33 @@
 import { z } from "zod";
-import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedStringSchema, } from "./contract-limits.js";
+import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, } from "./contract-limits.js";
 import { workspaceCwdSchema } from "./workspace-cwd.js";
+/**
+ * One allowed destination host.
+ *
+ * A whitespace-only or outer-padded entry matches no host, so a policy carrying one is an
+ * allowlist the caller believes is in force and is not. That is the same silent-weakening this
+ * contract refuses everywhere else, so the entry is rejected rather than trimmed: trimming would
+ * accept a typo and change what the caller asked for.
+ */
+const egressAllowDomainSchema = boundedIdentifierSchema;
+/** Runtime contract for the portable egress policy carried by providers. */
+export const AgentEnvironmentEgressPolicySchema = z.discriminatedUnion("mode", [
+    z.strictObject({ mode: z.literal("open") }),
+    z.strictObject({ mode: z.literal("blocked") }),
+    z.strictObject({
+        mode: z.literal("strict"),
+        /**
+         * Order does not change the policy, but it does change the create identity: this value is
+         * canonicalized into {@link agentEnvironmentCreateInputDigest}, so two same-key creates whose
+         * domains differ only in order are read as different creates and the second is refused. Build
+         * the list in a stable order.
+         */
+        allowDomains: z
+            .array(egressAllowDomainSchema)
+            .max(CONTRACT_MAX_ARRAY_LENGTH)
+            .optional(),
+    }),
+]);
 /** Runtime contract for the portable workspace request carried by providers. */
 export const WorkspaceRequestSchema = z
     .strictObject({

package/dist/environment-runtime.d.ts

@@ -8,7 +8,7 @@ import { type InteractionAcknowledgement, type InteractionCapabilities, type Int
 import { type ContextTransferReceipt, type ContextTransferRequest, type ContextTransferResult, type NativeContextBoundaryProof, type NativeContextContinuationRequest, type NativeContextContinuationTurn } from "./portable-context.js";
 import { type AgentExactRunControlRef, type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest, type AgentRunControlRef } from "./runtime-control.js";
 import type { AgentWorkspaceBranching, AgentWorkspaceBranchingProvider } from "./workspace-branching.js";
-import type { AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSessionStatus, CheckpointRef, CheckpointRequest, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from "./environment-requests.js";
+import type { AgentEnvironmentEgressMode, AgentEnvironmentEgressPolicy, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSessionStatus, CheckpointRef, CheckpointRequest, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from "./environment-requests.js";
 import type { AgentExactProcessEgressMode, AgentExactProcessProvider } from "./environment-exact-process.js";
 import type { AgentEnvironmentObservation } from "./environment-observation.js";
 import type { AgentInteractiveSession, AgentInteractiveSessionRef, AgentInteractiveSessionStart } from "./environment-interactive.js";
@@ -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. */
@@ -841,6 +843,28 @@ export interface AgentEnvironmentCapabilities {
     exactProcess?: {
         egress: readonly AgentExactProcessEgressMode[];
     };
+    /**
+     * Present only when create honors {@link CreateAgentEnvironmentInput.egress} or
+     * {@link CreateAgentEnvironmentInput.billingOwner}. Absent means neither field is read, so a
+     * caller that needs either must not send it and call the result a policy.
+     *
+     * Each member is present only when that field is honored, and the block carries at least one of
+     * them. A provider that takes a billing owner but no caller-controlled egress therefore states
+     * exactly that, instead of advertising an egress mode it does not accept.
+     */
+    create?: {
+        /**
+         * Egress modes create accepts, each named once. A mode absent here is refused, never weakened
+         * or widened. Absent altogether means create does not read
+         * {@link CreateAgentEnvironmentInput.egress} at all.
+         */
+        egress?: readonly AgentEnvironmentEgressMode[];
+        /**
+         * True when create carries the billing owner to the platform unchanged. The platform still
+         * authorizes the caller for that account; this flag states only that the field is not dropped.
+         */
+        billingOwner?: boolean;
+    };
     /** Per-surface flags for the normalized environment observation. */
     observation?: {
         identity: boolean;
@@ -962,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>;
@@ -975,6 +1000,14 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
             strict: "strict";
         }>>;
     }, z.core.$strict>>;
+    create: z.ZodOptional<z.ZodObject<{
+        egress: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            blocked: "blocked";
+            open: "open";
+            strict: "strict";
+        }>>>;
+        billingOwner: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     observation: z.ZodOptional<z.ZodObject<{
         identity: z.ZodBoolean;
         lifecycle: z.ZodBoolean;
@@ -1014,6 +1047,26 @@ export interface CreateAgentEnvironmentInput {
     resources?: ResourceRequest;
     env?: Record<string, string>;
     secrets?: string[] | Record<string, string>;
+    /**
+     * Outbound network policy for this environment.
+     *
+     * When absent the provider applies its own default. That default can be a strict allowlist,
+     * and a model endpoint the environment must reach is then refused inside the environment as an
+     * authorization error that names no policy. Declare the policy whenever the destinations the
+     * environment needs are known.
+     *
+     * A provider that cannot satisfy the requested mode must fail the create rather than weaken or
+     * widen the policy. {@link AgentEnvironmentCapabilities.create} names the modes it accepts.
+     */
+    egress?: AgentEnvironmentEgressPolicy;
+    /**
+     * Platform account whose balance funds this environment's managed model usage.
+     *
+     * A trusted first-party service acting for an authenticated user sets it. The provider honors
+     * it only for a caller its platform has authorized to bill that account, and rejects the create
+     * otherwise. It never grants a caller permission to charge an arbitrary account.
+     */
+    billingOwner?: string;
     metadata?: Record<string, unknown>;
     name?: string;
     /**
@@ -1085,7 +1138,15 @@ export interface AgentEnvironmentProvider {
     capabilities(): AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>;
     validateProfile?(profile: AgentProfileRef): AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
     /**
-     * Create or reconstruct one environment.
+     * Create or reconstruct one environment that is ready to accept a turn.
+     *
+     * A returned environment answers {@link AgentEnvironment.stream} and every
+     * other operation its capability document claims. A provider whose platform
+     * starts an environment asynchronously holds this call until the environment
+     * is running, and fails the call with the platform's reason when it never
+     * gets there; it never returns a half-started environment for the caller to
+     * poll. Every runtime seam relies on this: a caller streams the first turn
+     * immediately after create, with nothing in between.
      *
      * With `input.idempotencyKey`, the provider must return the same environment
      * for the same canonical input and reject any changed input before creating.

package/dist/environment-runtime.js

@@ -215,6 +215,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(),
@@ -230,6 +231,16 @@ export const AgentEnvironmentCapabilitiesSchema = z
             .max(CONTRACT_MAX_ARRAY_LENGTH),
     })
         .optional(),
+    create: z
+        .strictObject({
+        egress: z
+            .array(z.enum(["open", "strict", "blocked"]))
+            .min(1)
+            .max(CONTRACT_MAX_ARRAY_LENGTH)
+            .optional(),
+        billingOwner: z.boolean().optional(),
+    })
+        .optional(),
     observation: z
         .strictObject({
         identity: z.boolean(),
@@ -332,6 +343,23 @@ export const AgentEnvironmentCapabilitiesSchema = z
             message: "exact process egress modes must be unique",
         });
     }
+    const create = capabilities.create;
+    if (create !== undefined) {
+        if (create.egress === undefined && create.billingOwner === undefined) {
+            refinement.addIssue({
+                code: "custom",
+                path: ["create"],
+                message: "a create capability block must state at least one honored field",
+            });
+        }
+        if (create.egress && new Set(create.egress).size !== create.egress.length) {
+            refinement.addIssue({
+                code: "custom",
+                path: ["create", "egress"],
+                message: "create egress modes must be unique",
+            });
+        }
+    }
     const terminal = capabilities.interactiveTerminal;
     if (terminal !== undefined &&
         (terminal.input || terminal.resize || terminal.reattach) &&

package/dist/index.d.ts

@@ -41,3 +41,4 @@ export * from "./profile-schema.js";
 export * from "./profile-security.js";
 export * from "./sandbox-size.js";
 export { CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, } from "./contract-limits.js";
+export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";

package/dist/index.js

@@ -39,3 +39,4 @@ export * from "./profile-schema.js";
 export * from "./profile-security.js";
 export * from "./sandbox-size.js";
 export { CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, } from "./contract-limits.js";
+export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";

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.1.1",
+  "version": "2.3.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",