@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/tenant/effects.js

@@ -0,0 +1,564 @@
+import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowEffect, isFlowToolEffect, linkedMessageKey, linkedTurnEnd, } from "../core/flow-host.js";
+import { mayDispatchMore } from "../core/limits.js";
+import { canonical } from "../store/canonical.js";
+import { isOwnershipLost } from "../store/ownership.js";
+import { newStreamIncarnation } from "../streams/types.js";
+import { piModel } from "../model/pi-model.js";
+import { scrub } from "../redact.js";
+import { serversOf } from "../mcp/pool.js";
+import { sandboxCapabilityOf } from "../sandbox/manager.js";
+import { owningSandboxSessionId, sandboxSpecOf } from "../sandbox/share.js";
+import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
+import { fail } from "./http.js";
+import { actionTarget, linkedAgentOutput, manifestFor, mcpToolOf, pinnedTool, } from "./session.js";
+import { command } from "./commands.js";
+import { assistantMessage, toolCompleted, toolIds } from "./transcript.js";
+import { abortKind } from "./worker.js";
+export function invokeModel(ctx, request, signal, model) {
+    if (model)
+        return model(request, signal);
+    if (!ctx.useVaultModel)
+        return ctx.modelProvider(request, signal);
+    const adapter = piModel({
+        root: ctx.config.paths.home,
+        readHostModel: () => ctx.vault.readHostModel(),
+        writeHostCredential: (credential) => ctx.vault.updateHostCredential(credential),
+    });
+    return adapter(request.input, {
+        request: request.context.request,
+        invocationId: String(request.context.invocationId),
+        signal,
+        reportPreparedCall() { },
+    });
+}
+/**
+ * The outcome of a flow `agent` effect once the linked turn it started ended, or undefined
+ * while it has not. The linked session may still show an earlier iteration's turn.
+ */
+async function linkedOutcome(t, effect, agent) {
+    const end = await linkedTurnEnd(t, effect, agent);
+    if (!end || !agent)
+        return undefined;
+    if (end.status === "completed")
+        return { value: linkedAgentOutput(agent, end.output) };
+    return {
+        value: {
+            kind: "failed",
+            code: `agent.${end.status}`,
+            message: end.error ??
+                (end.status === "failed"
+                    ? "Agent turn failed"
+                    : "Agent turn was cancelled"),
+        },
+    };
+}
+/**
+ * What an effect's journal row must match on replay. A delegation's context carries only the
+ * parent's tool call id, for its events; rows journaled before it existed still match.
+ */
+function requestIdentity(request) {
+    if (request.kind !== "delegation")
+        return request;
+    const { context: _, ...identity } = request;
+    return identity;
+}
+function delegationCallId(request) {
+    const callId = request.context?.callId;
+    return typeof callId === "string" ? { callId } : {};
+}
+export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
+    const { store } = ctx;
+    const journaled = await store.tx(async (t) => {
+        const s = await ownedSession(t, lease, request.sessionId);
+        if (s.status === "cancelled" || s.activeTurnId !== request.turnId)
+            throw new Error("Turn cancelled");
+        // An aborted advance starts no effect; the advance decides what the abort means.
+        signal.throwIfAborted();
+        const resolved = (resolution) => ({
+            kind: "resolved",
+            resolution,
+        });
+        const existing = await t.get("effects", request.effectId);
+        if (existing) {
+            if (canonical(requestIdentity(existing.request)) !== canonical(requestIdentity(request)))
+                throw new Error("Effect identity request drift");
+            if (existing.status === "completed")
+                return resolved({ status: "completed", outcome: existing.outcome });
+            if (request.kind === "agent" && existing.status === "pending") {
+                const agentSessionId = existing.agentSessionId;
+                if (agentSessionId) {
+                    const agent = await t.get("sessions", agentSessionId);
+                    const outcome = await linkedOutcome(t, existing, agent);
+                    if (outcome) {
+                        existing.status = "completed";
+                        existing.outcome = outcome;
+                        await t.put("effects", request.effectId, existing);
+                        return resolved({ status: "completed", outcome });
+                    }
+                }
+            }
+            return resolved({
+                status: existing.status === "uncertain" || existing.status === "invoking"
+                    ? "uncertain"
+                    : "pending",
+            });
+        }
+        if (request.kind === "agent" ||
+            request.kind === "fn" ||
+            request.kind === "verify" ||
+            isFlowToolEffect(request)) {
+            // Handled outside the agent-manifest path below.
+            return { kind: "flow" };
+        }
+        if (request.kind === "delegation") {
+            // Lifecycle points of an agent used as a tool: journaled once, so replays never re-emit.
+            const outcome = { value: null };
+            await t.put("effects", request.effectId, {
+                request,
+                status: "completed",
+                outcome,
+            });
+            const settled = request.effectId.endsWith(":settled");
+            await t.event(s.id, s.activeTurnId, settled ? "delegation.completed" : "delegation.started", {
+                agent: request.agent,
+                ...delegationCallId(request),
+                ...request.input,
+            });
+            return resolved({ status: "completed", outcome });
+        }
+        const agentManifest = manifestFor(s.manifest, request.agent);
+        if (!agentManifest)
+            throw new Error(`Agent '${request.agent?.id ?? ""}' is not used as a tool`);
+        const mcpTool = request.kind === "tool" ? mcpToolOf(s, request) : undefined;
+        const sandboxTool = request.kind === "tool" && !mcpTool
+            ? sandboxCapabilityOf(agentManifest, request.capabilityId, request.toolName)
+            : undefined;
+        await t.put("effects", request.effectId, {
+            request,
+            status: request.kind === "model" || mcpTool || sandboxTool
+                ? "invoking"
+                : "pending",
+        });
+        if (request.kind === "model" || mcpTool || sandboxTool)
+            return {
+                kind: "invoke",
+                invoke: mcpTool ? "mcp" : sandboxTool ? "sandbox" : "model",
+            };
+        const tool = request.kind === "tool"
+            ? pinnedTool(agentManifest, request.capabilityId, request.toolName)
+            : undefined;
+        const base = {
+            actionId: request.effectId,
+            sessionId: request.sessionId,
+            turnId: request.turnId,
+            agentId: request.agentId,
+            manifestHash: request.manifestHash,
+            implementationVersion: s.implementationVersion,
+            input: request.input,
+            context: request.context,
+            status: "pending",
+            generation: 0,
+            claimId: null,
+            leaseExpiresAt: null,
+            ...(request.agent ? { agent: request.agent } : {}),
+        };
+        const action = request.kind === "hook"
+            ? {
+                ...base,
+                kind: "hook",
+                hook: {
+                    at: request.hook.at,
+                    scope: request.hook.scope,
+                    capabilityIds: [...request.hook.capabilityIds],
+                },
+            }
+            : {
+                ...base,
+                kind: "tool",
+                capabilityId: request.capabilityId,
+                toolName: request.toolName,
+                ...(tool?.inputSchema ? { inputSchema: tool.inputSchema } : {}),
+                ...(tool?.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+            };
+        await t.put("actions", action.actionId, action);
+        await t.event(s.id, s.activeTurnId, "action.pending", {
+            actionId: action.actionId,
+            kind: action.kind,
+            ...actionTarget(action),
+            ...(action.kind === "tool" ? toolIds(request.context) : {}),
+            input: action.input,
+        });
+        t.signalWork();
+        return resolved({ status: "pending" });
+    });
+    if (journaled.kind === "resolved")
+        return journaled.resolution;
+    if (journaled.kind === "flow") {
+        if (isFlowEffect(request))
+            return resolveNewFlowEffect(ctx, request, signal, lease);
+        return { status: "pending" };
+    }
+    const invoke = journaled.invoke;
+    try {
+        // The intent is committed; the call itself runs outside any transaction.
+        const value = invoke === "mcp"
+            ? await callMcpTool(ctx, request)
+            : invoke === "sandbox"
+                ? await callSandboxTool(ctx, request, signal)
+                : await invokeModel(ctx, request, signal, segment.model);
+        return await store.tx(async (t) => {
+            const s = await ownedSession(t, lease, request.sessionId);
+            // Only a cancel discards an outcome in hand (§10.7). After any other abort (shutdown,
+            // deadline) it is recorded, so the next advance replays it instead of calling again.
+            if (s.status === "cancelled" ||
+                s.activeTurnId !== request.turnId ||
+                abortKind(signal) === "cancel")
+                throw new Error("Turn cancelled");
+            const effect = await t.get("effects", request.effectId);
+            effect.status = "completed";
+            effect.outcome = { value };
+            await t.put("effects", request.effectId, effect);
+            const transcript = invoke === "model"
+                ? assistantMessage(request, value)
+                : toolCompleted(request, value);
+            if (transcript)
+                await t.event(s.id, request.turnId, invoke === "model" ? "message.assistant" : "tool.completed", transcript);
+            return { status: "completed", outcome: effect.outcome };
+        });
+    }
+    catch (error) {
+        // A lost epoch writes nothing: the new owner decides what the effect became.
+        if (isOwnershipLost(error))
+            throw error;
+        await store.tx(async (t) => {
+            const s = request.sessionId === lease.sessionId
+                ? await t.assertEpoch(request.sessionId, lease.epoch)
+                : await t.lockSession(request.sessionId);
+            const effect = await t.get("effects", request.effectId);
+            if (!effect)
+                return;
+            effect.status = "uncertain";
+            effect.error = error instanceof Error ? error.message : String(error);
+            await t.put("effects", request.effectId, effect);
+            if (s && s.status !== "cancelled" && s.activeTurnId === request.turnId)
+                await t.event(s.id, request.turnId, "effect.uncertain", {
+                    effectId: request.effectId,
+                    message: effect.error,
+                });
+        });
+        return { status: "uncertain" };
+    }
+}
+/** Journal and dispatch a new flow effect (agent / tool node / fn / verify). */
+export async function resolveNewFlowEffect(ctx, request, signal, lease) {
+    const { store } = ctx;
+    signal.throwIfAborted();
+    const step = await store.tx(async (t) => {
+        const resolved = (resolution) => ({
+            kind: "resolved",
+            resolution,
+        });
+        const workflow = await ownedSession(t, lease, request.sessionId);
+        const existing = await t.get("effects", request.effectId);
+        if (existing) {
+            if (existing.status === "completed")
+                return resolved({ status: "completed", outcome: existing.outcome });
+            if (existing.status === "queued") {
+                // Fall through to dispatch when a concurrency slot is free.
+            }
+            else if (request.kind === "agent") {
+                const agentSessionId = existing.agentSessionId;
+                const agent = agentSessionId
+                    ? await t.get("sessions", agentSessionId)
+                    : undefined;
+                const outcome = await linkedOutcome(t, existing, agent);
+                if (!outcome)
+                    return resolved({ status: "pending" });
+                existing.status = "completed";
+                existing.outcome = outcome;
+                await t.put("effects", request.effectId, existing);
+                return resolved({ status: "completed", outcome });
+            }
+            else {
+                return resolved({ status: "pending" });
+            }
+        }
+        const active = await countActiveFlowWork(t, request.sessionId, request.turnId);
+        if (!mayDispatchMore(active, ctx.flowLimits)) {
+            if (!existing || existing.status !== "queued")
+                await t.put("effects", request.effectId, {
+                    request,
+                    status: "queued",
+                });
+            return resolved({ status: "pending" });
+        }
+        if (request.kind === "fn" ||
+            request.kind === "verify" ||
+            isFlowToolEffect(request)) {
+            await t.put("effects", request.effectId, {
+                request,
+                status: "pending",
+            });
+            const action = request.kind === "fn" || request.kind === "verify"
+                ? {
+                    actionId: request.effectId,
+                    sessionId: request.sessionId,
+                    turnId: request.turnId,
+                    agentId: request.agentId,
+                    manifestHash: request.manifestHash,
+                    implementationVersion: workflow.implementationVersion,
+                    input: request.input,
+                    context: request.context,
+                    status: "pending",
+                    generation: 0,
+                    claimId: null,
+                    leaseExpiresAt: null,
+                    kind: request.kind,
+                    path: request.path,
+                    key: request.key,
+                }
+                : {
+                    actionId: request.effectId,
+                    sessionId: request.sessionId,
+                    turnId: request.turnId,
+                    agentId: request.agentId,
+                    manifestHash: request.manifestHash,
+                    implementationVersion: workflow.implementationVersion,
+                    input: request.input,
+                    context: request.context,
+                    status: "pending",
+                    generation: 0,
+                    claimId: null,
+                    leaseExpiresAt: null,
+                    kind: "tool",
+                    path: request.path,
+                    key: request.key,
+                };
+            await t.put("actions", action.actionId, action);
+            if (isFlowToolEffect(request)) {
+                await t.event(workflow.id, workflow.activeTurnId, "node.started", {
+                    path: request.path,
+                    kind: "tool",
+                    key: request.key,
+                    ...(request.iterations !== undefined
+                        ? { iterations: request.iterations }
+                        : {}),
+                });
+            }
+            await t.event(workflow.id, workflow.activeTurnId, "action.pending", {
+                actionId: action.actionId,
+                kind: action.kind,
+                path: action.path,
+                key: action.key,
+                input: action.input,
+            });
+            t.signalWork();
+            return resolved({ status: "pending" });
+        }
+        return { kind: "agent", workflow };
+    });
+    if (step.kind === "resolved")
+        return step.resolution;
+    // agent effect: create linked session + message via the public contract path
+    const workflow = step.workflow;
+    const body = request.input;
+    const path = body.path ?? request.path;
+    const agentSessionId = deriveAgentEffectSessionId(workflow.id, path, request);
+    const iterations = request.iterations ?? "-";
+    const n = Number(request.context.n ?? iterations.split(".")[0] ?? 1);
+    await store.tx(async (t) => {
+        await ownedSession(t, lease, workflow.id);
+        await t.put("effects", request.effectId, {
+            request,
+            status: "pending",
+            agentSessionId,
+        });
+        await t.put("links", agentSessionId, {
+            workflowSessionId: workflow.id,
+            path,
+            effectId: request.effectId,
+            turnId: request.turnId,
+        });
+    });
+    await store.tx(async (t) => {
+        // The linked agent (child) session is locked before the workflow (parent).
+        const exists = await t.lockSession(agentSessionId);
+        await ownedSession(t, lease, workflow.id);
+        if (exists)
+            return;
+        const definition = (await t.get("definitions", body.agentId)) ??
+            fail(404, "Definition not found");
+        const sandboxOwnerId = sandboxSpecOf(workflow.manifest) || workflow.sandboxOwnerId
+            ? owningSandboxSessionId(workflow, await sandboxLookup(t, workflow.sandboxOwnerId))
+            : undefined;
+        const created = {
+            id: agentSessionId,
+            agentId: body.agentId,
+            ownerUserId: workflow.ownerUserId,
+            manifest: definition.manifest,
+            manifestHash: definition.manifestHash,
+            implementationVersion: definition.implementationVersion,
+            status: "idle",
+            activeTurnId: null,
+            creation: {
+                requestId: `flow-put-${request.effectId}`,
+                agentId: body.agentId,
+                ownerUserId: workflow.ownerUserId,
+                ...(sandboxOwnerId ? { sandbox: { session: sandboxOwnerId } } : {}),
+            },
+            vaultIds: workflow.vaultIds,
+            credentialSelections: workflow.credentialSelections,
+            pluginRoots: definition.pluginRoots ?? {},
+            ...(sandboxOwnerId ? { sandboxOwnerId } : {}),
+            streamIncarnation: newStreamIncarnation(),
+        };
+        await t.put("sessions", agentSessionId, created);
+    });
+    // Binds this effect to the one linked turn its message opens (`linkedTurnEnd`).
+    const idempotencyKey = linkedMessageKey(request);
+    const messageInput = body.input;
+    const messageCommand = typeof messageInput === "string"
+        ? {
+            type: "message",
+            content: messageInput,
+            requestId: `flow-${request.effectId}`,
+            idempotencyKey,
+            ...(body.manifest ? { manifest: body.manifest } : {}),
+        }
+        : {
+            type: "message",
+            data: messageInput,
+            requestId: `flow-${request.effectId}`,
+            idempotencyKey,
+            ...(body.manifest ? { manifest: body.manifest } : {}),
+        };
+    const accepted = (await command(ctx, agentSessionId, messageCommand, {
+        kind: "application",
+        principalId: "flow-host",
+    }));
+    // Workflow events; the linked agent session is only read here, never locked.
+    return store.tx(async (t) => {
+        const s = await ownedSession(t, lease, request.sessionId);
+        const agent = await sessionOf(t, agentSessionId);
+        await t.event(s.id, s.activeTurnId, "loop.iteration", {
+            path: String(request.context.loopPath ?? path.split("/")[0]),
+            n,
+            sessionId: agentSessionId,
+            turnId: accepted.turnId ?? undefined,
+            manifestHash: agent.checkpoint?.manifestHash,
+        });
+        await t.event(s.id, s.activeTurnId, "node.agent", {
+            path,
+            iterations,
+            sessionId: agentSessionId,
+            turnId: accepted.turnId,
+        });
+        // May already be settled if the agent was fast / replayed.
+        const outcome = await linkedOutcome(t, { request, agentSessionId }, agent);
+        if (outcome) {
+            await t.put("effects", request.effectId, {
+                request,
+                status: "completed",
+                outcome,
+                agentSessionId,
+            });
+            return { status: "completed", outcome };
+        }
+        return { status: "pending" };
+    });
+}
+/** Discover the session's MCP tools once, or reconnect and refresh diagnostics. */
+export async function prepareMcp(ctx, lease, signal) {
+    const { store } = ctx;
+    const id = lease.sessionId;
+    const s = await loadSession(ctx, id);
+    if (serversOf(s.manifest).length === 0)
+        return;
+    if (!s.mcpSnapshot) {
+        const found = await ctx.mcp.discover({
+            sessionId: id,
+            manifest: s.manifest,
+            manifestHash: s.manifestHash,
+            pluginRoots: s.pluginRoots ?? {},
+            signal,
+        });
+        await store.tx(async (t) => {
+            const current = await ownedSession(t, lease, id);
+            if (current.mcpSnapshot)
+                return;
+            current.mcpSnapshot = found.snapshot;
+            current.mcpDiagnostics = found.diagnostics;
+            await t.put("sessions", id, current);
+        });
+        return;
+    }
+    const diagnostics = await ctx.mcp.reconnect({
+        sessionId: id,
+        manifest: s.manifest,
+        pluginRoots: s.pluginRoots ?? {},
+        tools: s.mcpSnapshot.mcpTools,
+        signal,
+    });
+    if (diagnostics.length === 0)
+        return;
+    await store.tx(async (t) => {
+        const current = await ownedSession(t, lease, id);
+        const prior = [...(current.mcpDiagnostics ?? [])];
+        for (const item of diagnostics) {
+            const index = prior.findIndex((existing) => existing.capabilityId === item.capabilityId &&
+                existing.serverName === item.serverName);
+            if (index >= 0)
+                prior[index] = item;
+            else
+                prior.push(item);
+        }
+        current.mcpDiagnostics = prior;
+        await t.put("sessions", id, current);
+    });
+}
+async function callMcpTool(ctx, request) {
+    const s = await loadSession(ctx, request.sessionId);
+    const tool = mcpToolOf(s, request);
+    if (!tool)
+        throw new Error(`MCP tool '${request.toolName ?? ""}' is not in the session snapshot`);
+    return ctx.mcp.call({
+        sessionId: s.id,
+        ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
+        capabilityId: tool.capabilityId,
+        serverName: tool.serverName,
+        serverToolName: tool.serverToolName,
+        args: request.input,
+        manifest: s.manifest,
+        pluginRoots: s.pluginRoots ?? {},
+    });
+}
+async function callSandboxTool(ctx, request, signal) {
+    const { s, ownerId } = await ctx.store.tx(async (t) => {
+        const s = await sessionOf(t, request.sessionId);
+        // Agents used as tools share the session's sandbox; the tree declares one sandbox spec.
+        const lookup = await sandboxLookup(t, s.id);
+        return { s, ownerId: owningSandboxSessionId(s, lookup) };
+    });
+    const capability = sandboxCapabilityOf(manifestFor(s.manifest, request.agent), request.capabilityId, request.toolName);
+    if (!capability)
+        throw new Error(`'${request.toolName ?? ""}' is not a sandbox tool`);
+    return ctx.sandbox.run({ id: ownerId, activeTurnId: s.activeTurnId, manifest: s.manifest }, capability, request.toolName, request.input, signal);
+}
+/** Vault authorization for an MCP server request made on behalf of a session. */
+export async function authorize(ctx, sessionId, request) {
+    const s = await loadSession(ctx, sessionId);
+    const result = await ctx.vault.authorize({
+        sessionId,
+        vaultIds: s.vaultIds ?? [],
+        credentialSelections: s.credentialSelections ?? [],
+        url: request.url,
+        serverName: request.serverName,
+    });
+    if (result.status === "authorized") {
+        const token = result.headers.authorization.slice("Bearer ".length);
+        scrub({ authorization: result.headers.authorization, url: result.url }, [
+            token,
+        ]);
+    }
+    return result;
+}

package/dist/tenant/envelope.d.ts

@@ -1,8 +1,5 @@
 import { type TenantEnvelope } from "@nylorun/core/contracts";
 export declare function parseEnvelope(raw: unknown, expectedId?: string): TenantEnvelope;
-export declare function readEnvelopeFile(path: string, expectedId?: string): TenantEnvelope;
-/** Write envelope via temp sibling then rename (atomic on the same filesystem). */
-export declare function writeEnvelopeFile(envelopePath: string, envelope: TenantEnvelope): void;
 export declare function envelopeNow(input: {
     id: string;
     name: string;

package/dist/tenant/envelope.js

@@ -1,47 +1,15 @@
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { TenantEnvelopeSchema, } from "@nylorun/core/contracts";
 import { quarantine } from "./quarantine.js";
 export function parseEnvelope(raw, expectedId) {
     const parsed = TenantEnvelopeSchema.safeParse(raw);
     if (!parsed.success) {
-        throw quarantine("envelope-invalid", "tenant.json is missing or not a valid Tenant envelope", expectedId ? { tenantId: expectedId } : {});
+        throw quarantine("envelope-invalid", "the Tenant envelope is missing or invalid", expectedId ? { tenantId: expectedId } : {});
     }
     if (expectedId !== undefined && parsed.data.id !== expectedId) {
-        throw quarantine("envelope-invalid", `tenant.json id ${parsed.data.id} does not match directory ${expectedId}`, { tenantId: expectedId });
+        throw quarantine("envelope-invalid", `the Tenant envelope id ${parsed.data.id} does not match ${expectedId}`, { tenantId: expectedId });
     }
     return parsed.data;
 }
-export function readEnvelopeFile(path, expectedId) {
-    let text;
-    try {
-        text = readFileSync(path, "utf8");
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === "ENOENT") {
-            throw quarantine("envelope-invalid", "tenant.json is missing", expectedId ? { tenantId: expectedId } : {});
-        }
-        throw quarantine("corrupt", "tenant.json could not be read", expectedId ? { tenantId: expectedId } : {});
-    }
-    let json;
-    try {
-        json = JSON.parse(text);
-    }
-    catch {
-        throw quarantine("envelope-invalid", "tenant.json is not valid JSON", expectedId ? { tenantId: expectedId } : {});
-    }
-    return parseEnvelope(json, expectedId);
-}
-/** Write envelope via temp sibling then rename (atomic on the same filesystem). */
-export function writeEnvelopeFile(envelopePath, envelope) {
-    const validated = parseEnvelope(envelope, envelope.id);
-    const tmp = join(envelopePath + `.tmp-${process.pid}-${Date.now()}`);
-    writeFileSync(tmp, `${JSON.stringify(validated, null, 2)}\n`, {
-        mode: 0o600,
-    });
-    renameSync(tmp, envelopePath);
-}
 export function envelopeNow(input, now = new Date()) {
     const iso = now.toISOString();
     return {

package/dist/tenant/ephemeral.d.ts

@@ -1,19 +1,30 @@
+import type { PostgresClient } from "../store/postgres/connect.js";
 import type { Logger, TenantModelConfig } from "./types.js";
 export interface StartEphemeralRuntimeOptions {
-    /** Absolute Host root. Caller creates any temporary directory. */
+    /**
+     * Absolute Host root for `host.json`, the admin key and each Tenant's files (vault key,
+     * home, sandboxes). Caller creates any temporary directory. Session data never lands here.
+     */
     hostRoot: string;
     tenantId?: string;
     name?: string;
     applicationKey?: string;
     adminKey?: string;
     principalId?: string;
+    /** SHA-256 of a derived Studio key; registers principal `studio`. */
+    studioCredentialHash?: string;
     /** Allowlisted baseline for childEnv (e.g. PATH). Never read from ambient here. */
     baseline?: Readonly<Record<string, string>>;
     model?: TenantModelConfig;
-    sandboxBackend?: "auto" | "microsandbox" | "virtual";
+    sandboxBackend?: "auto" | "virtual";
     /** When true, close() leaves hostRoot on disk. */
     retainRoot?: boolean;
     logger?: Logger;
+    /**
+     * A Postgres pool: Tenants become schemas in it (`store-pg.ts`) instead of living in memory.
+     * The caller ends the pool; the schemas stay.
+     */
+    database?: PostgresClient;
 }
 export interface EphemeralRuntime {
     url: string;
@@ -25,7 +36,7 @@ export interface EphemeralRuntime {
     close(): Promise<void>;
 }
 /**
- * Private Host on port 0 with one Tenant (D9 / A19).
- * Exported from `@nylorun/runtime/core`.
+ * Private Host on port 0 with one Tenant (D9 / A19). Not durable (see the module comment).
+ * Exported from `@nylorun/runtime` and `@nylorun/runtime/core`.
  */
 export declare function startEphemeralRuntime(options: StartEphemeralRuntimeOptions): Promise<EphemeralRuntime>;