@nylorun/runtime 0.23.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/sweep.js

@@ -28,10 +28,12 @@
  *    for a Tenant not open on its Worker, an invocation an operator killed, Restate's state
  *    wiped (§17.11), or a parked outbox row.
  * 4. **Sandboxes.** Idle sandboxes are stopped, records of compute no longer held are marked
- *    stopped, and sandboxes whose session or sandbox resource is gone are removed, by the
+ *    stopped, and sandboxes whose session or Environment is gone are removed, by the
  *    workspace capability (`harness-api/workspace.ts`: here, or in the harness that serves
  *    workspaces). Idle MCP connections of the in-process harness are closed. As often as the
- *    orphan scan, pod sandboxes whose change stalled get a reconcile (`reconcileStalePods`).
+ *    orphan scan, pod Environments whose change stalled get a reconcile (`reconcileStalePods`).
+ *    Environments unused for their `lifecycle.deleteAfter` are deleted
+ *    (`sweepUnusedEnvironments`).
  * 5. **Control signals.** Signals on the control bus older than `SIGNAL_RETENTION_MS` are
  *    deleted: followers read back only the last two minutes (`store/postgres/control.ts`).
  * 6. **Hooks.** Callbacks registered with `ctx.onSweep`.
@@ -41,6 +43,8 @@
  * step does not stop the others; the first error is rethrown at the end so the execution
  * reports it.
  */
+import { sweepUnusedEnvironments } from "./environments.js";
+import { sweepPendingSeeds } from "../artifacts/disk.js";
 import { pendingAgentEffects, reconcilePendingAgentEffect, } from "../core/flow-host.js";
 const BATCH = 100;
 /** How long a control signal is kept after it was written. */
@@ -101,7 +105,7 @@ export async function sweep(ctx) {
             () => ctx.sandbox.sweep({
                 now: now.getTime(),
                 sessionExists: async (id) => !!(await ctx.store.tx((t) => t.get("sessions", id))),
-                sandboxExists: async (id) => (await ctx.store.tx((t) => t.sandboxResource(id))) !== undefined,
+                sandboxExists: async (id) => (await ctx.store.tx((t) => t.environment(id))) !== undefined,
             }),
         ],
         ...(checkPods
@@ -115,6 +119,10 @@ export async function sweep(ctx) {
                 ],
             ]
             : []),
+        // Environments unused for their `lifecycle.deleteAfter`: one query when none is due.
+        ["environments", () => sweepUnusedEnvironments(ctx, now.getTime())],
+        // Seeds of new volumes whose engine is connected and no process copies (R2d step 3).
+        ["seeds", () => sweepPendingSeeds(ctx)],
         // A harness elsewhere closes its own idle MCP connections.
         ["mcp", async () => ctx.mcp?.sweep()],
         [
@@ -257,16 +265,14 @@ const STALE_POD_MS = 60_000;
 async function reconcileStalePods(ctx, now) {
     if (!ctx.pods)
         return;
-    const stale = await ctx.store.tx(async (t) => (await t.listSandboxResources()).filter((row) => {
+    const stale = await ctx.store.tx(async (t) => (await t.listEnvironments()).filter((row) => {
         const pod = row.pod;
         if (!pod || now.getTime() - Date.parse(row.updatedAt) < STALE_POD_MS)
             return false;
-        const expiring = pod.expiresAt !== undefined && Date.parse(pod.expiresAt) <= now.getTime() && pod.observed !== "expired";
         return (pod.desired === "deleted" ||
             pod.retiring !== undefined ||
             pod.observed === "creating" ||
             pod.observed === "deleting" ||
-            expiring ||
             (pod.desired === "suspended" && pod.observed !== "suspended") ||
             // Running, but its engine is not connected: the pod may be gone, or its volume.
             (pod.desired === "running" && pod.observed === "running" && !ctx.harness.hosting(row.id)));