@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/tenant/sessions.js

@@ -1,26 +1,25 @@
 /**
- * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create or
- * re-attach vaults), the session list and the session view. Reads use the store's typed
- * queries; `PUT /v1/sessions/:id` runs in one transaction with the vault attachment checks.
+ * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create, or
+ * find an identical one), the session list and the session view. Reads use the store's typed
+ * queries; `PUT /v1/sessions/:id` runs in one transaction with the Environment's checks.
  */
 import { DefinitionDocumentSchema, definitionFilesOf, } from "@nylorun/core/contracts";
 import { hashManifest } from "@nylorun/core/compatibility";
-import { codeToolRefusal } from "@nylorun/core/define";
+import { approvalRefusal, codeToolRefusal } from "@nylorun/core/define";
 import { aggregateWaits, isWorkflowManifest } from "../core/flow-host.js";
 import { canonical } from "../store/canonical.js";
-import { validateSandboxAttach } from "../core/sandbox-routes.js";
-import { resolveSandbox } from "../sandbox/resolve.js";
+import { sandboxSpecOf } from "../sandbox/resolve.js";
 import { withPlatformTools, withSandboxCapability } from "../sandbox/session-sandbox.js";
-import { declaredSandboxes, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
+import { declaredSandboxes } from "../sandbox/share.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
-import { checkPlacement, requirePods } from "../sandbox/placement.js";
-import { attachSandbox, recordAttachment } from "./sandboxes.js";
-import { sandboxLookup, } from "./context.js";
+import { HARNESS_ID, checkPlacement, requirePods } from "../sandbox/placement.js";
+import { openEnvironment, recordAttachment } from "./environments.js";
+import { harnessOf, } from "./context.js";
 import { fail } from "./http.js";
 import { missingDefinitionFiles } from "./definition-files.js";
-/** A session's creation identity: everything but the request id and vault attachments. */
+/** A session's creation identity: everything but the request id. */
 const sessionIdentity = (value) => {
-    const { requestId: _requestId, vaultIds: _vaultIds, credentialSelections: _selections, ...body } = value ?? {};
+    const { requestId: _requestId, ...body } = value ?? {};
     return canonical(body);
 };
 export async function listDefinitions(ctx) {
@@ -56,13 +55,17 @@ export async function putDefinition(ctx, agentId, body) {
     if (body.manifest.id !== agentId)
         fail(400, "Agent id mismatch");
     DefinitionDocumentSchema.parse(body.manifest);
-    // The Runtime runs no code of yours during a session (track R2): no tool may need it.
+    // The Runtime runs agents from their manifests alone (track R2): no tool may need it.
     const code = codeToolRefusal(body.manifest);
     if (code)
         fail(400, code);
+    // Tool approvals are the Tenant's tool policy, decided at the Tool Gate (R5 step 2).
+    const approval = approvalRefusal(body.manifest);
+    if (approval)
+        fail(400, approval);
     const declared = declaredSandboxes(body.manifest);
     if (declared.length > 0)
-        fail(400, `${declared.join(", ")} declares a sandbox. Agents no longer declare one: remove .sandbox() and open the session with it, createSession({ sandbox: { image, network: { allow }, resources } }), or set the Tenant's default sandbox. See MIGRATION.md.`);
+        fail(400, `${declared.join(", ")} declares a sandbox. Agents no longer declare one: remove .sandbox(), create an Environment with the sandbox (PUT /v1/environments/{id}) and open the session on it, createSession({ environment }). See MIGRATION.md.`);
     const definition = {
         ...body,
         manifestHash: hashManifest(body.manifest),
@@ -104,18 +107,16 @@ export async function listSessions(ctx, agentId, access) {
     };
 }
 /**
- * Create a session from its definition, or re-attach vaults to an identical one. `owner`, when
- * the request acts for a subject, must be the session's owner: another owner's session id is
- * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
- * sandboxes.
+ * Create a session from its definition, or find an identical one. `access`, when the request
+ * acts for a subject, must be the session's owner: another owner's session id is the 404 of a
+ * missing one (not the 409 of a mismatch), and so is an Environment whose owner guard names
+ * another owner.
  *
- * The session's sandbox is decided here and fixed for its life (§5 of Sandboxes v3): shared
- * with `{ session }`, none with `false`, inline, or the Tenant default when omitted. A definition
- * that declares its own sandbox (`.sandbox()`) keeps it and takes no sandbox request.
+ * The session's Environment is fixed for its life: its sandbox (kinds `virtual` and `pod`) is
+ * the session's, with the spec of the Environment's applied recipe pinned now, and its vault
+ * holds the session's credentials. Without one the session has no sandbox and no credentials.
  */
 export async function putSession(ctx, id, body, access, options = {}) {
-    const vaultIds = body.vaultIds ?? [];
-    const credentialSelections = body.credentialSelections ?? [];
     const opaque = access !== undefined;
     if (opaque && body.ownerUserId !== access.owner)
         fail(403, "ownerUserId must be the subject");
@@ -135,35 +136,34 @@ export async function putSession(ctx, id, body, access, options = {}) {
                 fail(404, "Session not found");
             return prior;
         }
-        await ctx.vault.assertAttachment(t, body.ownerUserId, vaultIds, credentialSelections, { opaque });
-        const environment = await ctx.vault.sessionEnvironment(t, vaultIds);
-        if (environment.conflict)
-            fail(409, environment.conflict, { code: "credential_conflict" });
         if (prior) {
-            if (prior.sandboxId !== undefined)
-                await assertSandboxSecrets(ctx, t, prior.sandboxId, id, body.ownerUserId, environment.secretHosts);
             if (sessionIdentity(prior.creation) !== sessionIdentity(body))
                 fail(409, "Session already exists with different creation parameters");
-            prior.vaultIds = vaultIds;
-            prior.credentialSelections = credentialSelections;
-            prior.creation = body;
-            await t.put("sessions", id, prior);
-            await ctx.vault.recordAttachment(t, id, vaultIds);
             return prior;
         }
         const definition = (await t.get("definitions", body.agentId)) ??
             fail(404, "Definition not found");
-        const sandbox = await sessionSandbox(t, body, definition, {
-            opaque,
-            ...(options.sandboxGrants === undefined ? {} : { grants: options.sandboxGrants }),
-        });
-        // Placement (D38): where this session's harness may run, decided now and kept.
-        checkPlacement(await readSandboxConfig(t), sandbox.kind);
-        if (sandbox.kind === "pod")
-            await requirePods(ctx.pods, `Sandbox ${sandbox.sandboxId}`);
-        if (sandbox.sandboxId !== undefined)
-            await assertSandboxSecrets(ctx, t, sandbox.sandboxId, id, body.ownerUserId, environment.secretHosts);
-        const pinned = sandbox.manifest === undefined ? platformTools(definition) : sandbox;
+        const environment = body.environment === undefined
+            ? undefined
+            : await openEnvironment(t, body.environment, {
+                ...(options.environmentGrants === undefined ? {} : { grants: options.environmentGrants }),
+                ownerUserId: body.ownerUserId,
+                opaque,
+            });
+        const config = await readSandboxConfig(t);
+        // The harness the session runs for its life (R4.1): its Environment's, else ours. A flow
+        // runs in core and our engine, whatever its Environment names.
+        const harness = isWorkflowManifest(definition.manifest) || environment === undefined
+            ? HARNESS_ID
+            : environment.applied.harness;
+        // Placement (D38, D52): where this session's harness may run, decided now and kept.
+        checkPlacement(config, environment?.kind, harness);
+        if (environment?.kind === "pod")
+            await requirePods(ctx.pods, `Environment ${environment.id}`);
+        const spec = environment === undefined || environment.kind === "none"
+            ? undefined
+            : sandboxSpecOf(environment.applied, effectiveSandboxConfig(config).limits.idle);
+        const pinned = spec === undefined ? platformTools(definition) : pin(definition, spec);
         const created = {
             id,
             agentId: body.agentId,
@@ -176,90 +176,18 @@ export async function putSession(ctx, id, body, access, options = {}) {
             status: "idle",
             activeTurnId: null,
             creation: body,
-            vaultIds,
-            credentialSelections,
-            ...(sandbox.sandboxOwnerId !== undefined
-                ? { sandboxOwnerId: sandbox.sandboxOwnerId }
-                : {}),
-            ...(sandbox.sandboxId !== undefined ? { sandboxId: sandbox.sandboxId } : {}),
-            ...(sandbox.spec !== undefined
-                ? { sandbox: sandbox.spec, sandboxSource: sandbox.source }
-                : {}),
+            harness,
+            ...(environment === undefined
+                ? {}
+                : { environmentId: environment.id, environmentVersion: environment.version }),
+            ...(spec === undefined ? {} : { sandbox: spec }),
         };
         await t.put("sessions", id, created);
-        await ctx.vault.recordAttachment(t, id, vaultIds);
-        if (sandbox.sandboxId !== undefined)
-            await recordAttachment(t, id, sandbox.sandboxId);
+        if (environment !== undefined)
+            await recordAttachment(t, id, environment.id);
         return created;
     });
 }
-/**
- * A sandbox's shell secrets must be unambiguous (R2c, D50): egress-gate sets the header from the
- * one `environment_secret` bound to a host among the sessions using the sandbox. So while any of
- * them has secrets, they all have one owner, and no host is bound to two credentials.
- */
-async function assertSandboxSecrets(ctx, t, sandboxId, sessionId, ownerUserId, secretHosts) {
-    const conflict = (message) => fail(409, message, { code: "credential_conflict" });
-    const mine = Object.keys(secretHosts).length > 0;
-    for (const other of await t.sessionsOnSandbox(sandboxId)) {
-        if (other.id === sessionId)
-            continue;
-        const theirs = (await ctx.vault.sessionEnvironment(t, other.vaultIds ?? [])).secretHosts;
-        if (other.ownerUserId !== ownerUserId && (mine || Object.keys(theirs).length > 0))
-            conflict(`Sandbox ${sandboxId} serves environment_secret credentials of one owner at a time`);
-        for (const [host, credentialId] of Object.entries(secretHosts))
-            if (theirs[host] !== undefined && theirs[host] !== credentialId)
-                conflict(`Two environment_secret credentials would be bound to ${host} in sandbox ${sandboxId}`);
-    }
-}
-function isShare(value) {
-    return typeof value === "object" && value !== null && "session" in value;
-}
-function isAttach(value) {
-    return typeof value === "object" && value !== null && "id" in value;
-}
-/** Decide a new session's sandbox and, for an agent, the manifest that carries its tools. */
-async function sessionSandbox(t, body, definition, options) {
-    const request = body.sandbox;
-    const declared = sandboxSpecOf(definition.manifest) !== undefined;
-    if (isAttach(request)) {
-        if (declared)
-            fail(400, `'${body.agentId}' declares its own sandbox with .sandbox(). Remove it from the agent to attach a sandbox.`);
-        const sandbox = await attachSandbox(t, request.id, options.grants);
-        // A pod's storage and lifecycle are the resource's, not the agent's sandbox manifest.
-        const { storage: _storage, lifecycle: _lifecycle, ...spec } = sandbox.spec;
-        return { ...(await pin(definition, spec, "sandbox")), sandboxId: sandbox.id, kind: sandbox.kind };
-    }
-    if (isShare(request)) {
-        const owner = await t.get("sessions", request.session);
-        if (owner?.sandboxId !== undefined && (!options.opaque || owner.ownerUserId === body.ownerUserId))
-            fail(400, `Session ${request.session} is attached to sandbox ${owner.sandboxId}: open this session with sandbox: { id: "${owner.sandboxId}" }.`);
-        const lookup = await sandboxLookup(t, request.session);
-        const sandboxOwnerId = validateSandboxAttach(body, definition.manifest, lookup, {
-            opaque: options.opaque,
-            inherit: !declared,
-        });
-        if (declared || sandboxOwnerId === undefined)
-            return { sandboxOwnerId };
-        const spec = sessionSandboxSpec(lookup(request.session));
-        return { ...(await pin(definition, spec, "shared")), sandboxOwnerId };
-    }
-    if (declared) {
-        if (request !== undefined)
-            fail(400, `'${body.agentId}' declares its own sandbox with .sandbox(). Remove it from the agent to choose the sandbox when opening the session, or omit sandbox here.`);
-        return {};
-    }
-    const resolved = resolveSandbox({
-        request,
-        config: effectiveSandboxConfig(await readSandboxConfig(t)),
-        actingForSubject: options.opaque,
-    });
-    if (resolved.kind === "none")
-        return {};
-    if (resolved.kind === "error")
-        return fail(resolved.status, resolved.errors.join(" "));
-    return pin(definition, resolved.spec, resolved.source);
-}
 /**
  * The manifest a session without a sandbox pins: its agents' `read_artifact` (R2b C11), when
  * one has a remote MCP server or an HTTP tool; nothing otherwise, and for a workflow.
@@ -274,19 +202,15 @@ function platformTools(definition) {
         return fail(400, pinned.message);
     return { manifest: pinned.manifest, manifestHash: pinned.manifestHash };
 }
-async function pin(definition, spec, source) {
+/** The manifest a session with a sandbox pins: the definition with the sandbox capability. */
+function pin(definition, spec) {
     // A workflow's manifest stays as registered: its agents inherit the sandbox when they start.
     if (isWorkflowManifest(definition.manifest))
-        return { spec, source };
+        return {};
     const sandboxed = withSandboxCapability(definition.manifest, spec);
     if (!sandboxed.ok)
         return fail(400, sandboxed.message);
-    return {
-        spec,
-        source,
-        manifest: sandboxed.manifest,
-        manifestHash: sandboxed.manifestHash,
-    };
+    return { manifest: sandboxed.manifest, manifestHash: sandboxed.manifestHash };
 }
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export async function sessionView(t, s) {
@@ -315,12 +239,11 @@ export async function sessionView(t, s) {
         implementationVersion: s.implementationVersion,
         status: s.status,
         activeTurnId: s.activeTurnId,
-        vaultIds: s.vaultIds ?? [],
-        credentialSelections: s.credentialSelections ?? [],
-        sandboxOwnerId: s.sandboxOwnerId ?? null,
-        ...(s.sandboxId === undefined ? {} : { sandboxId: s.sandboxId }),
-        sandbox: s.sandbox ?? null,
-        ...(s.sandboxSource ? { sandboxSource: s.sandboxSource } : {}),
+        environment: s.environmentId === undefined
+            ? null
+            : { id: s.environmentId, version: s.environmentVersion ?? 1 },
+        harness: harnessOf(s),
+        ...(s.closedReason === undefined ? {} : { closedReason: s.closedReason }),
         mcpSnapshot: s.mcpSnapshot ?? null,
         mcpDiagnostics: s.mcpDiagnostics ?? [],
         waits,

package/dist/tenant/signing-keys.d.ts

@@ -19,7 +19,11 @@ import type { SigningKeyRow, Tx } from "../store/types.js";
 type KeyLike = Awaited<ReturnType<typeof importJWK>>;
 export interface SigningKeysOptions {
     tenantId: string;
-    /** The vault KEK, created on first use. Resolve it before opening a transaction. */
+    /**
+     * The vault KEK. The gateway's keys service only reads the file `nylorun start` wrote
+     * (`gates/tenant-vaults.ts`); an in-process Runtime may create it on first use. Resolve it
+     * before opening a transaction.
+     */
     kek(): Buffer;
 }
 export interface CurrentKey {

package/dist/tenant/status.js

@@ -1,5 +1,5 @@
 import { FIXTURE_MODEL_SETTING, seedFixtureModel } from "./model-setting.js";
-import { SANDBOX_CONFIG_SETTING, writeSandboxConfig } from "../sandbox/tenant-config.js";
+import { ENVIRONMENTS_CONFIG_SETTING, writeSandboxConfig } from "../sandbox/tenant-config.js";
 /** The Tenant's harnesses, for its status and the Host's. */
 export function harnessStatusOf(ctx) {
     return { mode: ctx.mcp ? "in-process" : "remote", ...ctx.harness.status() };
@@ -108,12 +108,12 @@ export async function seedTenantConfig(ctx, body) {
     const sandboxConfig = body.sandbox?.config;
     if (sandboxConfig) {
         const inserted = await ctx.store.tx(async (t) => {
-            if ((await t.getSetting(SANDBOX_CONFIG_SETTING)) !== undefined)
+            if ((await t.getSetting(ENVIRONMENTS_CONFIG_SETTING)) !== undefined)
                 return false;
             await writeSandboxConfig(t, sandboxConfig);
             return true;
         });
-        (inserted ? applied : kept).push(SANDBOX_CONFIG_SETTING);
+        (inserted ? applied : kept).push(ENVIRONMENTS_CONFIG_SETTING);
     }
     if (body.fixtureModel) {
         const inserted = await ctx.store.tx((t) => seedFixtureModel(t));

package/dist/tenant/streams.js

@@ -1,6 +1,7 @@
 import { basinOf } from "../streams/basin.js";
 import { createStreamRelay, } from "../streams/relay/core.js";
-import { checkSessionStreams, currentBasin, sleep, } from "./session-streams.js";
+import { retry } from "../retry.js";
+import { checkSessionStreams, currentBasin } from "./session-streams.js";
 const RETRY_MIN_MS = 100;
 const RETRY_MAX_MS = 2000;
 /** The longest wait between two `ensureTenant` attempts while the basin is being repaired. */
@@ -92,7 +93,11 @@ export async function wireStreams(ctx, options) {
     /** Deletes a retired generation's basin, then forgets it. A failure retries on next open. */
     async function deleteRetired(generation) {
         try {
-            await withRetries(() => streams.deleteTenant(basinOf(tenantId, generation)), 5);
+            await retry(() => streams.deleteTenant(basinOf(tenantId, generation)), {
+                minMs: RETRY_MIN_MS,
+                maxMs: RETRY_MAX_MS,
+                attempts: 5,
+            });
             await store.tx((t) => t.forgetRetiredGeneration(generation));
             logger.info("retired stream basin deleted", { generation });
         }
@@ -176,21 +181,6 @@ async function probe(streams, timeoutMs) {
 export async function closeStreams(ctx) {
     await ctx.sessionStreams.wiring?.close();
 }
-// ---------------------------------------------------------------------------
-async function withRetries(task, attempts) {
-    let delay = RETRY_MIN_MS;
-    for (let attempt = 1;; attempt += 1) {
-        try {
-            return await task();
-        }
-        catch (error) {
-            if (attempt >= attempts)
-                throw error;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-            delay = Math.min(delay * 2, RETRY_MAX_MS);
-        }
-    }
-}
 function basinKeeper(streams, basinKey, signal, onError) {
     let ready = false;
     let readyFor;
@@ -230,20 +220,15 @@ function basinKeeper(streams, basinKey, signal, onError) {
             repairing = true;
             ready = false;
             void (async () => {
-                let delay = RETRY_MIN_MS;
-                while (!signal.aborted) {
-                    try {
-                        await ensure();
-                        repairedAt = Date.now();
-                        break;
-                    }
-                    catch (error) {
+                await retry(ensure, {
+                    minMs: RETRY_MIN_MS,
+                    maxMs: BASIN_RETRY_MAX_MS,
+                    signal,
+                    onError: (error) => {
                         if (failures === 1 || failures % 10 === 0)
                             onError(error);
-                    }
-                    await sleep(delay, signal);
-                    delay = Math.min(delay * 2, BASIN_RETRY_MAX_MS);
-                }
+                    },
+                }).then(() => (repairedAt = Date.now()), () => undefined);
                 repairing = false;
             })();
         },

package/dist/tenant/sweep.d.ts

@@ -1,20 +1,47 @@
+import type { PendingRequest } from "../store/types.js";
 import type { TenantContext } from "./context.js";
 /**
- * How old a wake outbox row is before the sweep delivers it: longer than a delivery after
- * commit takes, so the sweep seldom sends a wake its commit is still sending. Sending one
- * twice is harmless either way (the idempotency key).
+ * How old an outbox row is before the sweep delivers it, unless its delivery after commit
+ * already failed (then it is due at once): longer than that delivery can take with its
+ * retries, so the sweep does not send again, and double the load on, an execution that is
+ * only slow. Sending one twice is harmless either way (the idempotency key).
+ */
+export declare const OUTBOX_GRACE_MS = 30000;
+/**
+ * How often the orphan scan, and the stale pod sandbox check, run after the first pass of a
+ * Tenant opened on this process.
  */
-export declare const WAKE_GRACE_MS = 2000;
-/** How often the orphan scan runs after the first pass of a Tenant opened on this process. */
 export declare const ORPHAN_SCAN_MS = 60000;
+/**
+ * How long one pass may spend draining the outbox, and paging through orphaned sessions.
+ * A backlog is worked off over several passes rather than holding one (and with it the
+ * Tenant's sweep object in the execution) for long.
+ */
+export declare const DRAIN_BUDGET_MS = 2000;
 export declare function sweep(ctx: TenantContext): Promise<void>;
+/** Failed deliveries after which the sweep parks an outbox row (`Tx.failOutbox`). */
+export declare const MAX_OUTBOX_ATTEMPTS = 10;
 /**
- * Deliver the wake outbox rows written before `before` (oldest first, one batch) and delete
- * the delivered ones. A row the Tenant declines (it is closing) stays. Returns the ids of the
- * rows delivered.
+ * Deliver the outbox rows that are due (`Tx.pendingOutbox`: older than `graceMs`, or whose
+ * delivery failed), oldest first, batch after batch until none is left or `budgetMs` is
+ * spent, and delete the delivered ones. Each row is delivered on its own: one that fails
+ * (Restate refuses it, or a Runtime that does not know a wake's reason) is tried again later,
+ * with backoff, so it never holds back the rows behind it, and after `MAX_OUTBOX_ATTEMPTS`
+ * failures it is parked: logged once, at error, and kept in the outbox for an operator. A
+ * parked wake's session is still re-woken by the orphan scan while it is runnable, and a
+ * parked sandbox signal's pod by the stale pod check. A row the Tenant declines (it is
+ * closing) stays as it is, and ends the drain. Never throws for a delivery; returns the rows
+ * delivered.
  */
-export declare function deliverPendingWakes(ctx: Pick<TenantContext, "store" | "wake">, before?: Date): Promise<string[]>;
+export declare function deliverOutbox(ctx: Pick<TenantContext, "store" | "send" | "config">, graceMs?: number, budgetMs?: number): Promise<PendingRequest[]>;
 /** Settle pending workflow `agent` effects whose linked turn already finished. */
-export declare function reconcileLinkedAgents(ctx: Pick<TenantContext, "store" | "wake">): Promise<void>;
-/** Wake `running`/`runnable` sessions without a live owner. Returns the ids woken. */
-export declare function wakeOrphanedSessions(ctx: Pick<TenantContext, "store" | "wake">, now?: Date): Promise<string[]>;
+export declare function reconcileLinkedAgents(ctx: Pick<TenantContext, "store">): Promise<void>;
+/**
+ * Wake `running`/`runnable` sessions without a live owner, page after page from the first id
+ * after `after`, until none is left or `budgetMs` is spent. Returns the ids woken, and the last
+ * id when the budget ran out first (`next`, where the next scan goes on).
+ */
+export declare function wakeOrphanedSessions(ctx: Pick<TenantContext, "store" | "wake">, now?: Date, after?: string, budgetMs?: number): Promise<{
+    woken: string[];
+    next?: string;
+}>;