@tangle-network/agent-interface 2.1.1 → 2.2.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";
@@ -841,6 +841,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;
@@ -975,6 +997,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 +1044,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 +1135,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

@@ -230,6 +230,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 +342,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",