@nylorun/runtime 0.48.0-beta → 0.49.0-beta

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.49.0-beta
+
+### Minor Changes
+
+- c4758c0: Pods on Agent Substrate (preview): keys now reach commands through Substrate's own egress ([ADR-142](https://github.com/nylorun/factory/blob/main/decisions/platform/2026-11-13-substrate-egress-adds-keys.md)). A command sends its stand-in, with no proxy, and Substrate's egress replaces the header on each request to a host the Agent has a key for, so `curl`, `gh` and SDKs work against keyed hosts, over HTTP/2 too. A removed key now fails closed with 403 instead of sending the stand-in.
+
+  - Each host the Agent has an `environment_secret` or slot for, and each host its owner connected through the outside credential source, becomes an `https` rule in the actor's egress policy that names a reference, never a value.
+  - The keys provider (`sandboxes provider`, from the sandboxes image) runs beside Substrate's egress. For every keyed request it asks egress-gate's new decide route (`POST /nylorun/v1/egress/decide`, token `NYLORUN_EGRESS_KEYS_TOKEN`), which checks that the actor is the sandbox's current incarnation and returns the vault's header value. For a person's key it returns only who owns it, and the provider fetches the value from the outside source's new `/v1/fetch`.
+  - The outside credential source's `/v1/hosts` may name each host's header (`{ host, header }`); a plain host name still means `Authorization`.
+  - The engine on Substrate writes a trust bundle with Substrate's egress CA and names it in `SSL_CERT_FILE` and the other trust variables.
+  - `nylorun local sandbox enable --backend substrate` deploys the keys provider in `ate-system`, publishes the edge's keys port (8795 by default), and checks that Substrate's egress was installed asking it (`--credential-provider='[{"name":"keys.nylorun.dev","address":"nylorun-keys-provider.ate-system.svc:50051"}]'`). When it wasn't, keys stay off and `enable` says how to turn them on. `sandbox status` shows whether keys are on.
+
+## 0.48.1-beta
+
+### Patch Changes
+
+- f581772: An Agent created again under a deleted Agent's id no longer takes that Agent's state. Before, it read `failing` or `input_required` from sessions whose last turn ran on the deleted Agent, before it existed. Its `state` and `attention` now count a session only once that session takes a turn on the new Agent. The sessions still keep the id and can go on with the new Agent, as before, and they still appear in its `sessions`.
+
 ## 0.48.0-beta
 
 ### Minor Changes

package/dist/gates/credential-provider.d.ts

@@ -12,6 +12,11 @@ export declare const PROVIDER_HEADERS: {
 };
 /** Every header of this prefix a sandbox sends is dropped before the engine sets its own. */
 export declare const PROVIDER_HEADER_PREFIX = "nylorun-provider-";
+/** A host an owner's key is bound to, and the header the key goes in. */
+export interface ProviderHost {
+    readonly host: string;
+    readonly header: string;
+}
 /** One variable a pod Agent's segments set: its name and the value the sandbox sees. */
 export interface ProviderVariable {
     readonly name: string;
@@ -38,6 +43,11 @@ export interface CredentialProvider {
      * match as `network.allow`'s do (`egressAllows`); none without an owner.
      */
     hosts(agentId: string, owner: string | undefined): Promise<readonly string[]>;
+    /**
+     * The same hosts, each with the header its key goes in (contract v2, ADR-142). Optional for a
+     * provider an embedder supplies: without it every host's key goes in `Authorization`.
+     */
+    keyedHosts?(agentId: string, owner: string | undefined): Promise<readonly ProviderHost[]>;
     /** Where one request to `path` (origin form, `/v2/projects?x=1`) is handed. */
     forwardUrl(path: string): URL;
     /** The headers that go with it, the provider's token among them. */

package/dist/gates/credential-provider.js

@@ -6,9 +6,9 @@
  * here runs.
  *
  * Three calls, each with `Authorization: Bearer <token>`:
- * - `POST <url>/v1/hosts` `{ agentId, owner }` → `{ hosts: string[] }`: the hosts the owner's keys
- *   are bound to, each an exact host name or a `*.<suffix>` pattern (`*.googleapis.com`, v0.26
- *   TM-E1). A pattern matches as `network.allow`'s do: `run.googleapis.com` and
+ * - `POST <url>/v1/hosts` `{ agentId, owner }` → `{ hosts: (string | { host, header?, format? })[] }`:
+ *   the hosts the owner's keys are bound to, each an exact host name or a `*.<suffix>` pattern
+ *   (`*.googleapis.com`, v0.26 TM-E1), with the header the key goes in (v2, ADR-142). A pattern matches as `network.allow`'s do: `run.googleapis.com` and
  *   `a.b.googleapis.com`, never `googleapis.com` itself. An IP literal or a malformed entry is
  *   dropped. egress-gate lets a pod Agent's sandbox reach them (inside the Tenant's egress
  *   ceiling), terminates TLS for them on 443 and hands each request on;
@@ -23,7 +23,11 @@
  *   sent them (its own `Authorization` or inject header included, which the provider replaces),
  *   plus `nylorun-provider-host`, `-agent`, `-owner` and, in place of a bearer the sandbox's own
  *   `Authorization` would clash with, `nylorun-provider-token`. The provider sends it on to
- *   `https://<host>/<path>` and streams the answer back (`egress-credentials.ts`).
+ *   `https://<host>/<path>` and streams the answer back (`egress-credentials.ts`). Retires with
+ *   egress-gate (ADR-142);
+ * - `POST <url>/v1/fetch` `{ agentId, owner, host }` → `{ value }` (v2, ADR-142): the whole header
+ *   value of the owner's key for `host`, asked by the keys provider beside Agent Substrate's
+ *   egress after the Tenant allowed it, never by the Runtime. `404` when there is no such key.
  *
  * Only an Agent with an owner (its owner guard) is asked about; one without gets nothing and no
  * call. An answer is kept per Agent and owner for `credentialProvider.cacheMs` (15 s). A call
@@ -131,7 +135,8 @@ export function createCredentialProvider(settings, options) {
     return {
         url,
         environment: (agentId, owner) => answer("environment", agentId, owner),
-        hosts: (agentId, owner) => answer("hosts", agentId, owner),
+        hosts: async (agentId, owner) => (await answer("hosts", agentId, owner)).map((entry) => entry.host),
+        keyedHosts: (agentId, owner) => answer("hosts", agentId, owner),
         forwardUrl: (path) => new URL(`${url}/v1/forward${path.startsWith("/") ? path : `/${path}`}`),
         forwardHeaders: ({ host, agentId, owner }) => ({
             [PROVIDER_HEADERS.host]: host,
@@ -141,13 +146,35 @@ export function createCredentialProvider(settings, options) {
         }),
     };
 }
+/** An HTTP header name (RFC 9110 token). */
+const HEADER = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
 /**
- * The hosts of a `/v1/hosts` answer: exact host names and `*.<suffix>` patterns, lowercase, without
- * a trailing root dot, once each; an IP literal or a malformed entry is dropped.
+ * The hosts of a `/v1/hosts` answer (contract v2, ADR-142): each entry is a host name or a
+ * `*.<suffix>` pattern, or `{ host, header?, format? }` naming the header the key goes in
+ * (`Authorization` by default; `format` is the source's own business). Lowercase, without a
+ * trailing root dot, once each, the first entry for a host winning; an IP literal or a malformed
+ * entry is dropped.
  */
 function hostsOf(list) {
-    const items = list.filter((item) => typeof item === "string").slice(0, ANSWER_MAX);
-    return [...new Set(items.map((host) => host.toLowerCase().replace(/\.$/, "")).filter(isSandboxHostPattern))];
+    const hosts = new Map();
+    for (const item of list) {
+        if (hosts.size >= ANSWER_MAX)
+            break;
+        const entry = typeof item === "string"
+            ? { host: item, header: undefined }
+            : item !== null && typeof item === "object" && typeof item.host === "string"
+                ? { host: item.host, header: item.header }
+                : undefined;
+        if (!entry)
+            continue;
+        const host = entry.host.toLowerCase().replace(/\.$/, "");
+        if (!isSandboxHostPattern(host) || hosts.has(host))
+            continue;
+        if (entry.header !== undefined && (typeof entry.header !== "string" || !HEADER.test(entry.header)))
+            continue;
+        hosts.set(host, { host, header: entry.header ?? "Authorization" });
+    }
+    return [...hosts.values()];
 }
 /**
  * The variables of a `/v1/environment` answer, each with the value the sandbox sees: a bare name is

package/dist/gates/egress-decide.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Logger } from "../tenant/types.js";
+import type { CredentialProvider } from "./credential-provider.js";
+import type { EgressCredentialRelease } from "./egress-credentials.js";
+/** The route's path. */
+export declare const EGRESS_DECIDE_PATH = "/nylorun/v1/egress/decide";
+/** What the route reads of a sandbox: its incarnation, owner and the Tenant's egress ceiling. */
+export interface DecideSandboxes {
+    live(sandboxId: string): Promise<{
+        /** The current incarnation's name: the actor's name on Agent Substrate. */
+        readonly name?: string;
+        readonly owner?: string;
+        readonly ceiling?: readonly string[];
+    } | undefined>;
+}
+export interface EgressDecideOptions {
+    /** NYLORUN_EGRESS_KEYS_TOKEN; none: the route is off. */
+    readonly token?: string;
+    readonly sandboxes: DecideSandboxes;
+    /** The vault's release of an `environment_secret` bound to a host (as egress-gate's). */
+    release(sandboxId: string, host: string): Promise<EgressCredentialRelease>;
+    /** The outside credential source, for a person's keys. */
+    readonly provider?: CredentialProvider;
+    readonly logger: Logger;
+}
+export type Decision = {
+    readonly status: 200;
+    readonly body: {
+        readonly value: string;
+    } | {
+        readonly fetch: {
+            readonly agentId: string;
+            readonly owner: string;
+            readonly host: string;
+        };
+    };
+    readonly outcome: string;
+    readonly credentialId?: string;
+} | {
+    readonly status: 400 | 403 | 404 | 503;
+    readonly code: string;
+    readonly outcome: string;
+};
+/** The decision for one keyed request (steps 1–4 above). */
+export declare function decide(options: Omit<EgressDecideOptions, "token" | "logger">, input: {
+    readonly actor: string;
+    readonly sandboxId: string;
+    readonly host: string;
+}): Promise<Decision>;
+/**
+ * The route's handler: `true` when it answered `req`, `false` for any other request, which the
+ * caller answers as before.
+ */
+export declare function egressDecideHandler(options: EgressDecideOptions): (req: IncomingMessage, res: ServerResponse) => boolean;

package/dist/gates/egress-decide.js

@@ -0,0 +1,148 @@
+/**
+ * The keys provider's decide route (ADR-142): on Agent Substrate, Substrate's egress adds a
+ * sandbox's keys, and the keys provider beside it asks the Tenant here, for every keyed request,
+ * what to add. It is served on egress-gate's listener (the gateway's `--service egress`, 4200),
+ * which the sandboxes service's edge forwards its keys port to; no actor's egress policy allows
+ * that port.
+ *
+ * `POST /nylorun/v1/egress/decide` with `Authorization: Bearer <NYLORUN_EGRESS_KEYS_TOKEN>` and
+ * `{ actor, sandboxId, host }`, where `actor` is the actor's name as Substrate's egress verified it
+ * and `sandboxId` and `host` come from the reference in the actor's rule
+ * (`ate-secret://keys.nylorun.dev/<sandboxId>/<host>`). In order:
+ *
+ * 1. the sandbox is a live pod whose current incarnation is `actor` (its `k8sName`), else 403:
+ *    one actor can never use another sandbox's reference;
+ * 2. an `environment_secret` of its Environment bound to `host` wins, as on egress-gate: the vault
+ *    releases it (one read, audited, unsealed by keys) and `200 { value }` carries the whole header
+ *    value; a refusal is 403;
+ * 3. a host the outside credential source lists for the Agent's owner, inside the Tenant's egress
+ *    ceiling, is allowed: `200 { fetch: { agentId, owner, host } }`, and the keys provider asks the
+ *    source for the value. The Runtime never sees a person's key (ADR-82 §3, D49);
+ * 4. else `404 not_found`.
+ *
+ * Without the token setting the route is off (404). Every decision is logged, never a value.
+ */
+import { timingSafeEqual, createHash } from "node:crypto";
+import { isSandboxHostPattern } from "@nylorun/core/define";
+import { withinCeiling } from "../sandbox/resolve.js";
+import { egressAllows } from "./egress.js";
+/** The route's path. */
+export const EGRESS_DECIDE_PATH = "/nylorun/v1/egress/decide";
+/** The largest body the route reads. */
+const MAX_BODY = 4096;
+function digest(value) {
+    return createHash("sha256").update(value).digest();
+}
+/** The decision for one keyed request (steps 1–4 above). */
+export async function decide(options, input) {
+    const sandbox = await options.sandboxes.live(input.sandboxId);
+    if (!sandbox || sandbox.name === undefined || sandbox.name !== input.actor)
+        return { status: 403, code: "permission_denied", outcome: "not_this_sandbox" };
+    const released = await options.release(input.sandboxId, input.host);
+    if (released.status === "released")
+        return { status: 200, body: { value: released.value }, outcome: "vault", credentialId: released.credentialId };
+    if (released.status === "refused")
+        return { status: 403, code: "permission_denied", outcome: `vault_${released.reason}` };
+    const { provider } = options;
+    if (provider && sandbox.owner !== undefined) {
+        const hosts = await provider.hosts(input.sandboxId, sandbox.owner);
+        const listed = hosts.includes(input.host) || egressAllows(input.host, hosts);
+        if (listed && sandbox.ceiling && !withinCeiling(input.host, sandbox.ceiling))
+            return { status: 403, code: "permission_denied", outcome: "outside_ceiling" };
+        if (listed)
+            return {
+                status: 200,
+                body: { fetch: { agentId: input.sandboxId, owner: sandbox.owner, host: input.host } },
+                outcome: "outside",
+            };
+    }
+    return { status: 404, code: "not_found", outcome: "no_key" };
+}
+/**
+ * The route's handler: `true` when it answered `req`, `false` for any other request, which the
+ * caller answers as before.
+ */
+export function egressDecideHandler(options) {
+    const want = options.token ? digest(options.token) : undefined;
+    const send = (res, status, body) => {
+        res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+        res.end(JSON.stringify(body));
+    };
+    return (req, res) => {
+        const path = (req.url ?? "").split("?")[0];
+        if (path !== EGRESS_DECIDE_PATH)
+            return false;
+        if (!want) {
+            send(res, 404, { error: { code: "not_found", message: "keys at Substrate's egress are off" } });
+            return true;
+        }
+        if (req.method !== "POST") {
+            send(res, 405, { error: { code: "method_not_allowed", message: "POST only" } });
+            return true;
+        }
+        const presented = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization ?? "")?.[1];
+        if (!presented || !timingSafeEqual(digest(presented), want)) {
+            options.logger.warn("egress_decide_refused", { reason: "token" });
+            send(res, 401, { error: { code: "unauthorized", message: "missing or wrong token" } });
+            return true;
+        }
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size <= MAX_BODY)
+                chunks.push(chunk);
+        });
+        req.on("end", () => {
+            void (async () => {
+                let input;
+                try {
+                    const body = size <= MAX_BODY ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : undefined;
+                    if (body &&
+                        typeof body.actor === "string" &&
+                        typeof body.sandboxId === "string" &&
+                        typeof body.host === "string" &&
+                        body.actor !== "" &&
+                        body.sandboxId !== "" &&
+                        isSandboxHostPattern(body.host))
+                        input = { actor: body.actor, sandboxId: body.sandboxId, host: body.host.toLowerCase() };
+                }
+                catch {
+                    input = undefined;
+                }
+                if (!input) {
+                    send(res, 400, { error: { code: "invalid_request", message: "the body is {actor, sandboxId, host}" } });
+                    return;
+                }
+                let decision;
+                try {
+                    decision = await decide(options, input);
+                }
+                catch (error) {
+                    options.logger.warn("egress_decide_failed", {
+                        sandboxId: input.sandboxId,
+                        host: input.host,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    send(res, 503, { error: { code: "unavailable", message: "the decision failed; retry" } });
+                    return;
+                }
+                const fields = {
+                    sandboxId: input.sandboxId,
+                    host: input.host,
+                    outcome: decision.outcome,
+                    ...("credentialId" in decision && decision.credentialId ? { credentialId: decision.credentialId } : {}),
+                };
+                if (decision.status === 200) {
+                    options.logger.info("egress_decided", fields);
+                    send(res, 200, decision.body);
+                }
+                else {
+                    options.logger.warn("egress_decide_refused", fields);
+                    send(res, decision.status, { error: { code: decision.code, message: decision.outcome } });
+                }
+            })();
+        });
+        return true;
+    };
+}

package/dist/gates/egress.d.ts

@@ -17,6 +17,8 @@ export interface EgressSandboxes {
     live(sandboxId: string): Promise<{
         readonly epoch: number;
         readonly podUid?: string;
+        /** The incarnation's name (`k8sName`): the actor's name on Agent Substrate. */
+        readonly name?: string;
         readonly allow: readonly string[];
         readonly owner?: string;
         readonly ceiling?: readonly string[];
@@ -76,6 +78,11 @@ export interface StartEgressGateOptions {
      * Agent's owner pass on 443 and are handed to it. Needs `credentials` (the leaf). None: off.
      */
     readonly provider?: CredentialProvider;
+    /**
+     * NYLORUN_EGRESS_KEYS_TOKEN: the keys provider's token for the decide route (ADR-142,
+     * `egress-decide.ts`). None: the route is off.
+     */
+    readonly keysToken?: string;
 }
 export interface EgressGate {
     /** Where the gate listens, e.g. `http://0.0.0.0:4200`. */

package/dist/gates/egress.js

@@ -51,6 +51,7 @@ import { isSandboxHostPattern } from "@nylorun/core/define";
 import { isPrivateAddress } from "../tenant/outbound.js";
 import { readSandboxConfig } from "../sandbox/tenant-config.js";
 import { withinCeiling } from "../sandbox/resolve.js";
+import { egressDecideHandler } from "./egress-decide.js";
 import { bindListener } from "../host/http.js";
 import { MAX_HELLO_BYTES, readClientHello } from "./client-hello.js";
 import { hostTuning } from "../tuning.js";
@@ -448,7 +449,17 @@ export async function startEgressGate(options) {
         }
         return undefined;
     }
+    // Agent Substrate's keys provider asks here what to add to a keyed request (ADR-142).
+    const decideRoute = egressDecideHandler({
+        ...(options.keysToken ? { token: options.keysToken } : {}),
+        sandboxes: { live: (sandboxId) => sandboxes.live(sandboxId) },
+        release: (sandboxId, host) => options.credentials ? options.credentials.release(sandboxId, host) : Promise.resolve({ status: "none" }),
+        ...(options.provider ? { provider: options.provider } : {}),
+        logger,
+    });
     const server = createServer((req, res) => {
+        if (decideRoute(req, res))
+            return;
         logger.warn("egress_refused", { status: 405, reason: "not_connect", method: req.method });
         res.writeHead(405, { allow: "CONNECT", "content-type": "text/plain; charset=utf-8", connection: "close" });
         res.end("egress-gate: only CONNECT is served; set HTTPS_PROXY and HTTP_PROXY to this address\n");
@@ -511,6 +522,7 @@ export function storeEgressSandboxes(store) {
                 return {
                     epoch: pod.hostEpoch,
                     ...(pod.podUid ? { podUid: pod.podUid } : {}),
+                    name: pod.k8sName,
                     // The applied allowlist: a recipe change writes it at once (Q8).
                     allow: sandbox.applied.network?.allowedHosts ?? [],
                     ...(owner === undefined ? {} : { owner }),

package/dist/harness/main.js

@@ -55,6 +55,7 @@ export async function runHarness(stack, baseline) {
         pod = podHost(config.pod, logger, {
             volumeFile: join(config.root, "volume-id"),
             caBundleFile: join(config.root, "egress-ca-bundle.pem"),
+            ...(config.pod.egressCaFile ? { extraCaFile: config.pod.egressCaFile } : {}),
         });
         // Join, then make the disk ready (R2d step 2) before taking any turn.
         await pod.token();

package/dist/harness/pod.d.ts

@@ -62,6 +62,11 @@ export declare function podHost(config: PodHostConfig, logger: {
     volumeFile?: string;
     /** Where the engine writes the trust bundle: the public roots and the egress CA (R2c). */
     caBundleFile?: string;
+    /**
+     * Agent Substrate's egress CA (`NYLORUN_SANDBOX_EGRESS_CA_FILE`, ADR-142): Substrate's egress
+     * ends TLS for the hosts whose keys it adds, so commands trust it with no proxy in between.
+     */
+    extraCaFile?: string;
     /** Whether this engine runs from the workload image (default: from where its code is). */
     imageEngine?: boolean;
 }): PodHost;

package/dist/harness/pod.js

@@ -57,8 +57,8 @@ export function podHost(config, logger, options = {}) {
         if (!response.ok)
             throw new Error(`host/${path} answered ${response.status}`);
         const body = JSON.parse(text);
-        if (typeof body.caCertificate === "string")
-            await writeBundle(body.caCertificate);
+        if (typeof body.caCertificate === "string" || options.extraCaFile)
+            await writeBundle(body.caCertificate ?? "");
         if (path === "join") {
             setup = body.setup;
             seeded = body.seeded === true;
@@ -74,14 +74,24 @@ export function podHost(config, logger, options = {}) {
     };
     const writeBundle = async (ca) => {
         const file = options.caBundleFile;
-        if (!file || ca === bundled)
+        let extra = "";
+        if (options.extraCaFile) {
+            try {
+                extra = (await readFile(options.extraCaFile, "utf8")).trim();
+            }
+            catch {
+                // Not mounted (yet): the bundle holds the roots and the join's CA.
+            }
+        }
+        const content = [ca.trim(), extra].filter((part) => part !== "").join("\n");
+        if (!file || content === bundled)
             return;
         await mkdir(dirname(file), { recursive: true });
         // Written beside it and renamed, so a command never reads half a bundle.
         const next = `${file}.${randomUUID()}`;
-        await writeFile(next, `${rootCertificates.join("\n")}\n${ca.trim()}\n`, { mode: 0o644 });
+        await writeFile(next, `${rootCertificates.join("\n")}\n${content}\n`, { mode: 0o644 });
         await rename(next, file);
-        bundled = ca;
+        bundled = content;
     };
     /** The volume's id, created on a volume that has none. */
     const volumeId = async () => {
@@ -149,8 +159,15 @@ export function podHost(config, logger, options = {}) {
             return current.hostToken;
         },
         proxyEnv() {
-            if (!config.egressProxy || !held)
+            if (!held)
                 return {};
+            const trustOnly = bundled !== undefined && options.caBundleFile
+                ? Object.fromEntries(TRUST_VARIABLES.map((name) => [name, options.caBundleFile]))
+                : {};
+            // On Agent Substrate there is no proxy: Substrate's egress adds keys on its own (ADR-142),
+            // and commands only need to trust its CA.
+            if (!config.egressProxy)
+                return options.extraCaFile ? trustOnly : {};
             const url = new URL(config.egressProxy);
             url.username = "nylorun";
             url.password = held.egressToken;

package/dist/host/gates.js

@@ -199,6 +199,7 @@ export async function startEgress(options) {
         ...(options.credentialProvider
             ? { provider: createCredentialProvider(options.credentialProvider, { logger: options.logger }) }
             : {}),
+        ...(options.egress.keysToken ? { keysToken: options.egress.keysToken } : {}),
         ...options.gate,
     });
 }

package/dist/host/stack-config.d.ts

@@ -118,6 +118,11 @@ export interface EgressConfig {
         host: string;
         port: number;
     };
+    /**
+     * NYLORUN_EGRESS_KEYS_TOKEN: the token Agent Substrate's keys provider presents to the decide
+     * route on this listener (ADR-142); none: the route is off. 32 bytes or more as hex.
+     */
+    keysToken?: string;
 }
 /** Where the loop reaches the gates service (`NYLORUN_GATES_URL`, `NYLORUN_GATES_TOKEN`). */
 export interface ModelGateEndpoint {
@@ -159,6 +164,11 @@ export interface PodHostConfig {
     httpUrl: string;
     /** `NYLORUN_EGRESS_PROXY`: egress-gate's address, or undefined while it is not published. */
     egressProxy?: string;
+    /**
+     * `NYLORUN_SANDBOX_EGRESS_CA_FILE`: Agent Substrate's egress CA (ADR-142), which commands trust
+     * for the hosts whose keys Substrate's egress adds.
+     */
+    egressCaFile?: string;
     /** Addresses the pod's NetworkPolicy must block, probed before the engine starts. */
     blocked: BlockedAddress[];
 }

package/dist/host/stack-config.js

@@ -637,6 +637,7 @@ function parsePodHost(env, url) {
     const secure = base.protocol === "https:" || base.protocol === "wss:";
     const origin = `${secure ? "https" : "http"}://${base.host}`;
     const egress = read(env, "NYLORUN_EGRESS_PROXY");
+    const egressCa = read(env, "NYLORUN_SANDBOX_EGRESS_CA_FILE");
     return {
         wsUrl: `${secure ? "wss" : "ws"}://${base.host}/nylorun/harness/v1`,
         config: {
@@ -645,6 +646,7 @@ function parsePodHost(env, url) {
             joinFile: need("NYLORUN_SANDBOX_JOIN_FILE"),
             httpUrl: origin,
             ...(egress ? { egressProxy: egress.replace(/\/+$/, "") } : {}),
+            ...(egressCa ? { egressCaFile: egressCa } : {}),
             blocked: blockedAddresses(env),
         },
     };
@@ -666,7 +668,13 @@ function parseGates(env) {
 const REMOVED_RESOLVER_PREFIX = "NYLORUN_RESOLVER_";
 /** `StackConfig.egress` from `NYLORUN_EGRESS_LISTEN_*`. CONNECT has no Host header to check. */
 function parseEgress(env) {
-    return { listen: parseListener(env, "NYLORUN_EGRESS_", DEFAULT_EGRESS_LISTEN_PORT) };
+    const keysToken = read(env, "NYLORUN_EGRESS_KEYS_TOKEN");
+    if (keysToken !== undefined && !/^[0-9a-f]{64,}$/i.test(keysToken))
+        throw new StackConfigError("NYLORUN_EGRESS_KEYS_TOKEN must be 32 bytes or more as hex (nylorun local sandbox enable makes it)");
+    return {
+        listen: parseListener(env, "NYLORUN_EGRESS_", DEFAULT_EGRESS_LISTEN_PORT),
+        ...(keysToken === undefined ? {} : { keysToken }),
+    };
 }
 /** `StackConfig.modelGate` from `NYLORUN_GATES_URL` and `NYLORUN_GATES_TOKEN`. */
 function parseModelGate(env) {

package/dist/management-openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Management API",
-    "version": "0.48.0-beta",
+    "version": "0.49.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Runtime API",
-    "version": "0.48.0-beta",
+    "version": "0.49.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,

package/dist/sandbox/pods/client.d.ts

@@ -33,6 +33,17 @@ export interface PodSpec {
         readonly hosts: readonly string[];
         readonly suffixes: readonly string[];
     };
+    /**
+     * The hosts the sandbox has a key for, each with its header (ADR-142, `keys.ts`). agent-sandbox
+     * ignores them; on Agent Substrate each becomes an https rule the keys provider fills.
+     */
+    readonly keys?: {
+        readonly sandbox: string;
+        readonly hosts: readonly {
+            readonly host: string;
+            readonly header: string;
+        }[];
+    };
 }
 /** A Sandbox as the service's informers see it (`driver.Status` in Go). */
 export interface PodStatus {

package/dist/sandbox/pods/keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The hosts a pod sandbox has a key for (ADR-142), as the sandboxes service renders them on Agent
+ * Substrate: an https rule per host whose header Substrate's egress asks the keys provider for.
+ * agent-sandbox ignores them (egress-gate adds keys there).
+ *
+ * The hosts of the Environment's `environment_secret`s and slots (read from the clear binding,
+ * no value), then the hosts the outside credential source lists for the Agent's owner, inside the
+ * Tenant's egress ceiling; the vault's header wins for a host both name, as on egress-gate. A
+ * source that fails names none (it logs once), so its hosts are passed through until the next
+ * apply. Values are never read here: the keys provider asks for them per request.
+ */
+import type { TenantContext } from "../../tenant/context.js";
+import type { PodSpec } from "./client.js";
+/** The most keyed hosts one sandbox's policy holds (the sandboxes service's bound). */
+export declare const MAX_KEY_HOSTS = 200;
+export declare function podKeysOf(ctx: Pick<TenantContext, "store" | "credentialProvider">, input: {
+    readonly sandboxId: string;
+    readonly owner?: string;
+    readonly ceiling?: readonly string[];
+}): Promise<NonNullable<PodSpec["keys"]>>;

package/dist/sandbox/pods/keys.js

@@ -0,0 +1,27 @@
+import { environmentSecretHosts } from "../../vault/service.js";
+import { withinCeiling } from "../resolve.js";
+/** The most keyed hosts one sandbox's policy holds (the sandboxes service's bound). */
+export const MAX_KEY_HOSTS = 200;
+export async function podKeysOf(ctx, input) {
+    const hosts = new Map();
+    for (const entry of await ctx.store.tx((t) => environmentSecretHosts(t, input.sandboxId)))
+        hosts.set(entry.host, entry.header);
+    if (ctx.credentialProvider && input.owner !== undefined) {
+        const provider = ctx.credentialProvider;
+        const listed = provider.keyedHosts
+            ? await provider.keyedHosts(input.sandboxId, input.owner)
+            : (await provider.hosts(input.sandboxId, input.owner)).map((host) => ({ host, header: "Authorization" }));
+        for (const entry of listed) {
+            if (hosts.has(entry.host))
+                continue;
+            if (input.ceiling && !withinCeiling(entry.host, input.ceiling))
+                continue;
+            hosts.set(entry.host, entry.header);
+        }
+    }
+    const list = [...hosts.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .slice(0, MAX_KEY_HOSTS)
+        .map(([host, header]) => ({ host, header }));
+    return { sandbox: input.sandboxId, hosts: list };
+}

package/dist/sandbox/pods/reconcile.js

@@ -22,6 +22,7 @@ import { sha256Hex } from "../join.js";
 import { recoverLostVolume } from "../../artifacts/disk.js";
 import { decide } from "./lifecycle.js";
 import { podLifecycleConfig, podSpecOf } from "./spec.js";
+import { podKeysOf } from "./keys.js";
 import { hostTuning } from "../../tuning.js";
 import { idleMsOf, revertStart } from "../../tenant/agent-versions.js";
 export async function reconcileSandbox(ctx, sandboxId, trigger) {
@@ -69,6 +70,25 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         current.rev === row.pod.rev &&
         current.k8sName === row.pod.k8sName &&
         current.desired === row.pod.desired;
+    let keys;
+    if (decision.apply) {
+        // The keyed hosts are read at every apply (ADR-142): a host bound or connected later reaches
+        // the sandbox's rules on its next start, resume or reset.
+        try {
+            keys = await podKeysOf(ctx, {
+                sandboxId,
+                ...(row.ownerUserId === undefined ? {} : { owner: row.ownerUserId }),
+                ...(config.limits?.network === undefined ? {} : { ceiling: config.limits.network }),
+            });
+        }
+        catch (error) {
+            ctx.config.logger.warn("sandbox keys unread", {
+                sandboxId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return { retryAfterMs: decision.retryAfterMs ?? hostTuning().pods.reconcileRetryMs };
+        }
+    }
     // A new join token is recorded before the service writes it to the Sandbox's Secret.
     let joinToken;
     let rev = patch.rev ?? row.pod.rev;
@@ -110,6 +130,7 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
             harnessImage: pods.harnessImage,
             harness: row.applied.harness,
             ...(joinToken ? { joinToken } : {}),
+            keys,
         });
         try {
             await pods.client.put(row.pod.k8sName, spec);

package/dist/sandbox/pods/spec.d.ts

@@ -43,5 +43,7 @@ export interface PodSpecInput {
     readonly harness?: string;
     /** The join token, when this apply rotates it. */
     readonly joinToken?: string;
+    /** The keyed hosts (`keys.ts`), for Agent Substrate's egress. */
+    readonly keys?: PodSpec["keys"];
 }
 export declare function podSpecOf(input: PodSpecInput): PodSpec;

package/dist/sandbox/pods/spec.js

@@ -72,6 +72,7 @@ export function podSpecOf(input) {
         },
         ...(input.joinToken ? { joinToken: input.joinToken } : {}),
         network: networkOf(spec),
+        ...(input.keys ? { keys: input.keys } : {}),
     };
 }
 /** The spec's network as the sandboxes service reads it. */

package/dist/tenant/agents.d.ts

@@ -25,6 +25,14 @@ export declare function stateOf(agent: Pick<Environment, "desiredState" | "pod">
     state: AgentState;
     attention: AgentAttention[];
 };
+/**
+ * The sessions whose latest turn ran on this Agent. A deleted Agent's sessions keep its id
+ * (`deleteAgent`), so an Agent created again under that id would otherwise read `failing` or
+ * `input_required` from turns it never ran. A session whose latest turn started before this Agent
+ * was created is left out of its state until it takes a turn here; one with no turn in the turn
+ * index (Host feature `turns`) is kept.
+ */
+export declare function ranOnThisAgent<T extends Pick<Session, "id" | "activeTurnId" | "lastTurnId">>(t: Tx, environment: Pick<Environment, "createdAt">, sessions: readonly T[]): Promise<T[]>;
 /** How an Agent names its manifest: `name` when it tracks it, `name@n` when pinned. */
 export declare function manifestRefOf(agent: Pick<Environment, "manifestName" | "manifestVersion" | "manifestRef">): string;
 /**
@@ -141,7 +149,8 @@ export declare function refuseDiskCopy(environment: Environment): void;
 /**
  * `DELETE /v1/agents/{id}`: deletes the Environment, its vault and its workspace. Refused
  * while a session that names it has an active turn. Sessions keep its id: their next turn is
- * refused (`agent_unavailable`) unless an Environment with this id exists again.
+ * refused (`agent_unavailable`) unless an Environment with this id exists again. An Agent created
+ * again under the id does not take their state until they take a turn on it (`ranOnThisAgent`).
  */
 export declare function deleteAgent(ctx: TenantContext, id: string, scope: AuthScope): Promise<{
     id: string;

package/dist/tenant/agents.js

@@ -150,6 +150,24 @@ export function stateOf(agent, sessions, unsetSecrets = []) {
     attention.sort((a, b) => STATE_RANK.indexOf(a.state) - STATE_RANK.indexOf(b.state));
     return { state: attention[0]?.state ?? "sleeping", attention };
 }
+/**
+ * The sessions whose latest turn ran on this Agent. A deleted Agent's sessions keep its id
+ * (`deleteAgent`), so an Agent created again under that id would otherwise read `failing` or
+ * `input_required` from turns it never ran. A session whose latest turn started before this Agent
+ * was created is left out of its state until it takes a turn here; one with no turn in the turn
+ * index (Host feature `turns`) is kept.
+ */
+export async function ranOnThisAgent(t, environment, sessions) {
+    const kept = [];
+    for (const session of sessions) {
+        const turnId = session.activeTurnId ?? session.lastTurnId;
+        const turn = turnId ? await t.turn(session.id, turnId) : undefined;
+        if (turn !== undefined && Date.parse(turn.startedAt) < Date.parse(environment.createdAt))
+            continue;
+        kept.push(session);
+    }
+    return kept;
+}
 /** How an Agent names its manifest: `name` when it tracks it, `name@n` when pinned. */
 export function manifestRefOf(agent) {
     return agent.manifestRef === "tracking" ? agent.manifestName : `${agent.manifestName}@${agent.manifestVersion}`;
@@ -161,7 +179,7 @@ async function viewOf(ctx, t, environment, owner) {
         : undefined;
     const pod = environment.pod;
     const visible = sessions.filter((session) => owner === undefined || session.ownerUserId === owner);
-    const { state, attention } = stateOf(environment, visible, await unsetRequiredSecrets(t, environment));
+    const { state, attention } = stateOf(environment, await ranOnThisAgent(t, environment, visible), await unsetRequiredSecrets(t, environment));
     return {
         id: environment.id,
         manifest: manifestRefOf(environment),
@@ -898,7 +916,8 @@ async function deleteKeys(ctx, keys) {
 /**
  * `DELETE /v1/agents/{id}`: deletes the Environment, its vault and its workspace. Refused
  * while a session that names it has an active turn. Sessions keep its id: their next turn is
- * refused (`agent_unavailable`) unless an Environment with this id exists again.
+ * refused (`agent_unavailable`) unless an Environment with this id exists again. An Agent created
+ * again under the id does not take their state until they take a turn on it (`ranOnThisAgent`).
  */
 export async function deleteAgent(ctx, id, scope) {
     reachable(agentGrantsOf(scope), id);

package/dist/vault/service.d.ts

@@ -273,4 +273,14 @@ export declare function routingOf(binding: Pick<CredentialBinding, "via" | "viaF
     via?: string;
     toolPrefix?: string;
 };
+/**
+ * The hosts Environment `environmentId`'s sandbox has a key for (ADR-142), each with the header
+ * the key goes in: the hosts of its live `environment_secret`s and of its applied
+ * `environment_secret` slots, filled or not, so a slot whose value is removed still has its rule
+ * and fails closed. Read in `t` from the clear binding: no value is read and no key is needed.
+ */
+export declare function environmentSecretHosts(t: Tx, environmentId: string): Promise<{
+    host: string;
+    header: string;
+}[]>;
 export {};

package/dist/vault/service.js

@@ -1195,3 +1195,35 @@ export function routingOf(binding, slot) {
     const toolPrefix = routed?.toolPrefix ?? binding.toolPrefix;
     return toolPrefix === undefined ? { via } : { via, toolPrefix };
 }
+/**
+ * The hosts Environment `environmentId`'s sandbox has a key for (ADR-142), each with the header
+ * the key goes in: the hosts of its live `environment_secret`s and of its applied
+ * `environment_secret` slots, filled or not, so a slot whose value is removed still has its rule
+ * and fails closed. Read in `t` from the clear binding: no value is read and no key is needed.
+ */
+export async function environmentSecretHosts(t, environmentId) {
+    const hosts = new Map();
+    const add = (list, header) => {
+        for (const host of list ?? []) {
+            const name = host.toLowerCase();
+            if (!hosts.has(name))
+                hosts.set(name, header ?? ENVIRONMENT_SECRET_DEFAULT_INJECT.header);
+        }
+    };
+    const slots = await appliedSlots(t, environmentId);
+    const vault = await t.vaultOfEnvironment(environmentId);
+    if (vault) {
+        const live = liveFilterOf(slots);
+        for (const row of await t.credentialsForVault(vault.id)) {
+            if (row.type !== "environment_secret" || !live(row))
+                continue;
+            const binding = credentialBinding(row);
+            add(binding.allowedHosts, binding.inject?.header);
+        }
+    }
+    for (const slot of Object.values(slots ?? {})) {
+        if (slot.type === "environment_secret")
+            add(slot.allowedHosts, slot.inject?.header);
+    }
+    return [...hosts.entries()].map(([host, header]) => ({ host, header }));
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.48.0-beta";
+export declare const RUNTIME_VERSION = "0.49.0-beta";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in step with package.json by runtime/server/scripts/check-package.mjs, which runs in npm run check.
 // release:prepare also rewrites this when it bumps @nylorun/runtime.
-export const RUNTIME_VERSION = "0.48.0-beta";
+export const RUNTIME_VERSION = "0.49.0-beta";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.48.0-beta",
+  "version": "0.49.0-beta",
   "description": "Nylorun Runtime: the agent execution Host on Postgres, Restate and S2, and model providers.",
   "type": "module",
   "license": "Apache-2.0",