@tangle-network/agent-interface 5.3.1 → 5.5.0

package/dist/environment-runtime.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type ProxySecretBinding, type ProxySecretCapabilities, type ProxySecretReceipt } from "./proxy-secrets.js";
+import { type ProxySecretBinding, type ProxySecretCapabilities, type ProxySecretReceipt, type ProxySecretParents } from "./proxy-secrets.js";
 import type { AgentRuntimeAttachments } from "./runtime-attachments.js";
 export { AgentRuntimeAttachmentsSchema, type AgentRuntimeAttachments } from "./runtime-attachments.js";
 import type { AgentCandidateArtifactPort, Sha256Digest } from "./agent-candidate.js";
@@ -1321,6 +1321,8 @@ export interface AgentEnvironment {
     readonly contextTransferReceipt?: ContextTransferReceipt;
     /** Trusted metadata only; dispatch requires an installed receipt, never proxy-installed. */
     readonly proxySecretReceipt?: ProxySecretReceipt;
+    /** API-verified effective parent pins read from current custody. */
+    readonly proxySecretParents?: ProxySecretParents;
     /**
      * Detached metadata returned by the provider.
      * It can contain caller-authored annotations and is not authorization evidence.
@@ -1738,6 +1740,8 @@ export interface CreateAgentEnvironmentInput {
     /** Same declaration as AgentProfile. Empty selections remain explicit wire values.
      * Trusted issuer authorization is required before resolving any reference. */
     proxySecrets?: readonly ProxySecretBinding[];
+    /** Host-only total destination-to-parent selection; null means explicit independent root. */
+    proxySecretParents?: ProxySecretParents;
     /**
      * Outbound network policy for this environment.
      *
@@ -1812,16 +1816,22 @@ export declare function createAgentEnvironmentWithIdempotency<T extends object>(
 /** Reconstruct an existing environment; never allocates a replacement. */
 export interface AgentEnvironmentGetOptions {
     signal?: AbortSignal;
+    /** Side-effect-free custody discovery on a qualified provider. Never resumes, installs or
+     * rebinds; the returned snapshot cannot execute. Unsupported providers must reject this mode.
+     * Expired installed custody may be returned as metadata, never as dispatch authority. */
+    readOnly?: true;
     /** Explicit custody attachment through the existing egress lifecycle. Omission reads current
      * custody; [] revokes custom bindings. A get never allocates a replacement environment. */
     proxySecrets?: readonly ProxySecretBinding[];
+    /** Host-only total destination-to-parent selection; null means explicit independent root. */
+    proxySecretParents?: ProxySecretParents;
     expectedProxySecretGeneration?: number;
     requireInPlace?: boolean;
     /**
      * Authorize the first turn of an accepted portable transfer. The provider looks up the exact
      * durable operation and returns its dispatch-capable environment with contextTransferReceipt.
      * A missing, uncertain, conflicting or unsupported receipt refuses attachment. The request's
-     * exact profile, workspace and resources remain authoritative; ordinary get remains read-only.
+     * exact profile, workspace and resources remain authoritative; use readOnly for discovery without reconnect side effects.
      */
     contextTransfer?: ContextTransferRequest;
 }
@@ -1856,6 +1866,7 @@ export declare const AgentEnvironmentGetOptionsSchema: z.ZodObject<{
         }>>;
         ttlSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
+    proxySecretParents: z.ZodOptional<z.ZodType<Record<string, string | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | null>, unknown>>>;
     contextTransfer: z.ZodOptional<z.ZodObject<{
         operationId: z.ZodString;
         requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -2316,6 +2327,11 @@ export declare const AgentEnvironmentGetOptionsSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** Explicit opt-in for providers implementing side-effect-free, non-executable discovery. */
+export declare const AgentEnvironmentReadOnlyGetOptionsSchema: z.ZodObject<{
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    readOnly: z.ZodLiteral<true>;
+}, z.core.$strict>;
 export interface AgentEnvironmentProvider {
     readonly name: string;
     readonly exactProcess?: AgentExactProcessProvider;

package/dist/environment-runtime.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ProxySecretCapabilitiesSchema, ProxySecretsSchema, ProxySecretUpdateControlsSchema } from "./proxy-secrets.js";
+import { ProxySecretCapabilitiesSchema, ProxySecretParentsSchema, isProxySecretParentsTotal, ProxySecretsSchema, ProxySecretUpdateControlsSchema } from "./proxy-secrets.js";
 export { AgentRuntimeAttachmentsSchema } from "./runtime-attachments.js";
 import { canonicalCandidateDigest, canonicalCandidateJson, } from "./agent-candidate-schema-common.js";
 import { agentProfileSchema } from "./profile-schema.js";
@@ -526,12 +526,20 @@ export async function createAgentEnvironmentWithIdempotency(records, input, crea
         throw error;
     }
 }
+// Keep the existing parser strict: published providers that import it must not silently
+// accept readOnly and then perform their ordinary reconnect side effects.
+const environmentGetSignalSchema = z.custom().optional();
 export const AgentEnvironmentGetOptionsSchema = z.strictObject({
-    signal: z.custom().optional(),
+    signal: environmentGetSignalSchema,
     proxySecrets: ProxySecretsSchema.optional(),
+    proxySecretParents: ProxySecretParentsSchema.optional(),
     ...ProxySecretUpdateControlsSchema.shape,
     contextTransfer: ContextTransferRequestSchema.optional(),
 }).superRefine((options, ctx) => {
+    if (options.proxySecretParents !== undefined &&
+        (options.proxySecrets === undefined || !isProxySecretParentsTotal(options.proxySecrets, options.proxySecretParents))) {
+        ctx.addIssue({ code: "custom", path: ["proxySecretParents"], message: "parent map requires an explicit total proxySecrets selection" });
+    }
     if (options.proxySecrets !== undefined && options.contextTransfer !== undefined) {
         ctx.addIssue({ code: "custom", path: ["proxySecrets"], message: "context-transfer attachment cannot also change proxy custody" });
     }
@@ -540,3 +548,8 @@ export const AgentEnvironmentGetOptionsSchema = z.strictObject({
         ctx.addIssue({ code: "custom", path: ["proxySecrets"], message: "proxy update controls require an explicit proxySecrets selection" });
     }
 });
+/** Explicit opt-in for providers implementing side-effect-free, non-executable discovery. */
+export const AgentEnvironmentReadOnlyGetOptionsSchema = z.strictObject({
+    signal: environmentGetSignalSchema,
+    readOnly: z.literal(true),
+});

package/dist/own-property-record.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+/**
+ * Zod records currently assign parsed values onto an ordinary object. The
+ * special own key `__proto__` therefore invokes the legacy prototype setter
+ * and disappears instead of being validated. Encode every own key before Zod
+ * sees it, then restore the exact UTF-16 key with defineProperty so all string
+ * keys allowed by `Record<string, ...>` remain data rather than object syntax.
+ */
+export declare function ownPropertyRecordSchema<ValueSchema extends z.ZodType>(valueSchema: ValueSchema): z.ZodType<Record<string, z.output<ValueSchema>>>;

package/dist/own-property-record.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { isWellFormedUnicode } from "./agent-candidate-schema-common.js";
+/**
+ * Zod records currently assign parsed values onto an ordinary object. The
+ * special own key `__proto__` therefore invokes the legacy prototype setter
+ * and disappears instead of being validated. Encode every own key before Zod
+ * sees it, then restore the exact UTF-16 key with defineProperty so all string
+ * keys allowed by `Record<string, ...>` remain data rather than object syntax.
+ */
+export function ownPropertyRecordSchema(valueSchema) {
+    return z.preprocess(encodeOwnRecordKeys, z.record(z
+        .string()
+        .regex(/^u(?:[0-9a-f]{4})*$/, "record keys must contain valid Unicode"), valueSchema).transform((record) => {
+        const restored = {};
+        for (const [encodedKey, value] of Object.entries(record)) {
+            Object.defineProperty(restored, decodeRecordKey(encodedKey), {
+                value,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return restored;
+    }));
+}
+function encodeOwnRecordKeys(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return value;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return [];
+    const encoded = Object.create(null);
+    for (const [key, entry] of Object.entries(value)) {
+        encoded[encodeRecordKey(key)] = entry;
+    }
+    return encoded;
+}
+function encodeRecordKey(value) {
+    let encoded = isWellFormedUnicode(value) ? "u" : "i";
+    for (let index = 0; index < value.length; index += 1) {
+        encoded += value.charCodeAt(index).toString(16).padStart(4, "0");
+    }
+    return encoded;
+}
+function decodeRecordKey(value) {
+    let decoded = "";
+    for (let index = 1; index < value.length; index += 4) {
+        decoded += String.fromCharCode(Number.parseInt(value.slice(index, index + 4), 16));
+    }
+    return decoded;
+}

package/dist/profile-schema.js

@@ -1,5 +1,6 @@
 import { agentCandidateSecretRefSchema } from "./agent-candidate-schema-common.js";
 import { z } from "zod";
+import { ownPropertyRecordSchema } from "./own-property-record.js";
 import { ProxySecretsSchema } from "./proxy-secrets.js";
 import { agentProfileKnowledgeRefsSchema } from "./profile-knowledge.js";
 export { agentProfileKnowledgeRefSchema, agentProfileKnowledgeRefsSchema, } from "./profile-knowledge.js";
@@ -9,53 +10,6 @@ import { harnessTypeSchema } from "./harness.js";
 import { canonicalAgentProfileJson } from "./agent-profile-canonical.js";
 import { harnessHonorsEffort, harnessHonorsModel, harnessModelSupport, harnessReasoningEfforts, harnessSystemPromptIntents, resolveModelProvider, } from "./harness-capabilities.js";
 import { SANDBOX_SIZE_PRESET_NAMES, } from "./sandbox-size.js";
-/**
- * Zod records currently assign parsed values onto an ordinary object. The
- * special own key `__proto__` therefore invokes the legacy prototype setter
- * and disappears instead of being validated. Encode every own key before Zod
- * sees it, then restore the exact UTF-16 key with defineProperty so all string
- * keys allowed by `Record<string, ...>` remain data rather than object syntax.
- */
-function ownPropertyRecordSchema(valueSchema) {
-    return z.preprocess(encodeOwnRecordKeys, z.record(z
-        .string()
-        .regex(/^u(?:[0-9a-f]{4})*$/, "record keys must contain valid Unicode"), valueSchema).transform((record) => {
-        const restored = {};
-        for (const [encodedKey, value] of Object.entries(record)) {
-            Object.defineProperty(restored, decodeRecordKey(encodedKey), {
-                value,
-                enumerable: true,
-                configurable: true,
-                writable: true,
-            });
-        }
-        return restored;
-    }));
-}
-function encodeOwnRecordKeys(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return value;
-    }
-    const encoded = Object.create(null);
-    for (const [key, entry] of Object.entries(value)) {
-        encoded[encodeRecordKey(key)] = entry;
-    }
-    return encoded;
-}
-function encodeRecordKey(value) {
-    let encoded = isWellFormedUnicode(value) ? "u" : "i";
-    for (let index = 0; index < value.length; index += 1) {
-        encoded += value.charCodeAt(index).toString(16).padStart(4, "0");
-    }
-    return encoded;
-}
-function decodeRecordKey(value) {
-    let decoded = "";
-    for (let index = 1; index < value.length; index += 4) {
-        decoded += String.fromCharCode(Number.parseInt(value.slice(index, index + 4), 16));
-    }
-    return decoded;
-}
 export const agentProfilePermissionValueSchema = z.enum([
     "allow",
     "deny",

package/dist/proxy-secrets.d.ts

@@ -81,6 +81,16 @@ export declare const ProxySecretsSchema: z.ZodArray<z.ZodObject<{
     }>>;
     ttlSeconds: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>>;
+/** Host execution control, never part of an authored declaration or profile identity.
+ * Strings select an API-verified parent sandbox; null explicitly selects independent issuance.
+ * When present, every destination in the final effective selection must have exactly one key.
+ */
+export declare const ProxySecretParentsSchema: z.ZodType<Record<string, string | null>, unknown, z.core.$ZodTypeInternals<Record<string, string | null>, unknown>>;
+export type ProxySecretParents = z.infer<typeof ProxySecretParentsSchema>;
+/** Shape and totality only; the API verifies issuer authority and durable immutable pins. */
+export declare function isProxySecretParentsTotal(bindings: readonly ProxySecretBinding[], parents: unknown): parents is ProxySecretParents;
+/** API control-plane support; intentionally separate from the engine capability contract. */
+export declare const ProxySecretDelegationCapabilitySchema: z.ZodLiteral<1>;
 export declare const ProxySecretResolvedIdentitySchema: z.ZodObject<{
     tenantId: z.ZodString;
     issuerId: z.ZodString;

package/dist/proxy-secrets.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ownPropertyRecordSchema } from "./own-property-record.js";
 import { agentCandidateSecretRefSchema } from "./agent-candidate-schema-common.js";
 import { boundedIdentifierSchema, CONTRACT_MAX_ARRAY_LENGTH } from "./contract-limits.js";
 /**
@@ -52,6 +53,22 @@ export const ProxySecretBindingSchema = ProxySecretScopeSchema.extend({
 });
 export const ProxySecretsSchema = z.array(ProxySecretBindingSchema).max(CONTRACT_MAX_ARRAY_LENGTH)
     .refine((bindings) => unique(bindings.map((binding) => binding.envName)), "proxy secret env names must be unique");
+/** Host execution control, never part of an authored declaration or profile identity.
+ * Strings select an API-verified parent sandbox; null explicitly selects independent issuance.
+ * When present, every destination in the final effective selection must have exactly one key.
+ */
+export const ProxySecretParentsSchema = ownPropertyRecordSchema(boundedIdentifierSchema.nullable())
+    .refine((parents) => Object.keys(parents).length <= CONTRACT_MAX_ARRAY_LENGTH &&
+    Object.keys(parents).every((name) => envNameSchema.safeParse(name).success), "invalid parent selection keys");
+/** Shape and totality only; the API verifies issuer authority and durable immutable pins. */
+export function isProxySecretParentsTotal(bindings, parents) {
+    const selection = ProxySecretsSchema.safeParse(bindings);
+    const parsed = ProxySecretParentsSchema.safeParse(parents);
+    return selection.success && parsed.success && Object.keys(parsed.data).length === selection.data.length &&
+        selection.data.every((binding) => Object.hasOwn(parsed.data, binding.envName));
+}
+/** API control-plane support; intentionally separate from the engine capability contract. */
+export const ProxySecretDelegationCapabilitySchema = z.literal(1);
 export const ProxySecretResolvedIdentitySchema = z.strictObject({
     tenantId: boundedIdentifierSchema, issuerId: boundedIdentifierSchema,
     secretId: boundedIdentifierSchema, revision: boundedIdentifierSchema,

package/fixtures/proxy-secret-wire-v1.json

@@ -1169,5 +1169,72 @@
     "placeholder": "synthetic non-secret bytes, scoped only to this case",
     "authority": "SNI and authority must identify declared FQDN; omitted port and explicit :443 equivalent",
     "paths": "all percent-encoded request paths refused in v1"
-  }
+  },
+  "parents": [
+    {
+      "name": "mixed-authority",
+      "envNames": [
+        "RENAMED_TOKEN",
+        "COORD"
+      ],
+      "value": {
+        "RENAMED_TOKEN": "parent-sandbox",
+        "COORD": null
+      },
+      "valid": true
+    },
+    {
+      "name": "missing-destination",
+      "envNames": [
+        "RENAMED_TOKEN",
+        "COORD"
+      ],
+      "value": {
+        "RENAMED_TOKEN": "parent-sandbox"
+      },
+      "valid": false
+    },
+    {
+      "name": "extra-destination",
+      "envNames": [
+        "RENAMED_TOKEN"
+      ],
+      "value": {
+        "RENAMED_TOKEN": "parent-sandbox",
+        "COORD": null
+      },
+      "valid": false
+    },
+    {
+      "name": "forbidden-env-selector",
+      "envNames": [
+        "RENAMED_TOKEN"
+      ],
+      "value": {
+        "RENAMED_TOKEN": {
+          "sandboxId": "parent-sandbox",
+          "envName": "ORIGINAL_TOKEN"
+        }
+      },
+      "valid": false
+    },
+    {
+      "name": "forbidden-grant-id",
+      "envNames": [
+        "RENAMED_TOKEN"
+      ],
+      "value": {
+        "RENAMED_TOKEN": {
+          "grantId": "grant-parent"
+        }
+      },
+      "valid": false
+    },
+    {
+      "name": "empty-revoke",
+      "envNames": [],
+      "value": {},
+      "valid": true
+    }
+  ]
 }

package/package.json

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