@nylorun/runtime 0.8.0-beta → 0.10.0-beta

package/dist/launcher/status.js

@@ -0,0 +1,65 @@
+import { LAUNCHER_PROTOCOL } from "@nylorun/core/compatibility";
+import { readHostConfig } from "./host-config.js";
+import { readHostState } from "./host-state.js";
+import { processAlive } from "./locks.js";
+import { hostUrl } from "./paths.js";
+import { portBindable, probeHostHealth } from "./probe.js";
+/**
+ * Status with no lock and no mutation (D§9.3).
+ */
+export async function status(paths, launcherVersion) {
+    const config = await readHostConfig(paths);
+    const stateFile = await readHostState(paths);
+    const runtimeVersion = config && typeof config.runtimeVersion === "string"
+        ? config.runtimeVersion
+        : undefined;
+    const base = {
+        launcherProtocol: LAUNCHER_PROTOCOL,
+        home: paths.root,
+        state: "absent",
+        launcherVersion,
+        ...(runtimeVersion ? { runtimeVersion } : {}),
+    };
+    if (!config) {
+        return base;
+    }
+    const url = hostUrl(config);
+    const withConfig = {
+        ...base,
+        state: "stopped",
+        url,
+        hostId: config.hostId,
+        ...(stateFile?.pid ? { pid: stateFile.pid } : {}),
+        ...(stateFile?.version ? { version: stateFile.version } : {}),
+    };
+    const probe = await probeHostHealth(url);
+    const ours = probe.health !== undefined &&
+        (probe.health.hostId === undefined ||
+            probe.health.hostId === config.hostId);
+    if (probe.foreign) {
+        return { ...withConfig, state: "foreign-port" };
+    }
+    if (probe.health && ours) {
+        return {
+            ...withConfig,
+            state: "running",
+            ...(probe.health.version ? { version: probe.health.version } : {}),
+            ...(probe.health.hostId ? { hostId: probe.health.hostId } : {}),
+            ...(probe.health.pid ? { pid: probe.health.pid } : {}),
+        };
+    }
+    if (probe.health && !ours) {
+        return {
+            ...withConfig,
+            state: "foreign-port",
+            ...(probe.health.hostId ? { hostId: probe.health.hostId } : {}),
+        };
+    }
+    if (stateFile && processAlive(stateFile.pid)) {
+        return { ...withConfig, state: "unresponsive", pid: stateFile.pid };
+    }
+    if (!(await portBindable(config.host, config.port))) {
+        return { ...withConfig, state: "foreign-port" };
+    }
+    return withConfig;
+}

package/dist/mcp/connect.d.ts

@@ -11,6 +11,7 @@ export declare function openMcpServer(input: {
     authorize?: (url: string) => Promise<AuthorizeResult>;
     pluginRoot?: string;
     pluginData: string;
+    childEnv?: Readonly<Record<string, string>>;
 }): Promise<LiveConnection>;
 export declare function listMcpTools(client: Client, input: {
     capabilityId: string;

package/dist/mcp/connect.js

@@ -10,11 +10,13 @@ export async function openMcpServer(input) {
         const launch = prepareStdioLaunch(input.server, {
             pluginRoot: input.pluginRoot,
             pluginData: input.pluginData,
+            childEnv: input.childEnv,
         });
         const transport = new StdioClientTransport({
             command: launch.command,
             args: [...launch.args],
             cwd: launch.cwd,
+            // Full explicit env so HOME/TMPDIR from the Tenant override getDefaultEnvironment().
             env: { ...launch.env },
             stderr: "pipe",
         });

package/dist/mcp/pool.d.ts

@@ -1,4 +1,4 @@
-import type { AgentManifest } from "@nylorun/core/define";
+import type { AgentManifest, McpServerManifest } from "@nylorun/core/define";
 import type { AuthorizeResult } from "../vault/service.js";
 import { callMcpTool } from "./connect.js";
 import { type McpDiagnostic, type McpSnapshot, type McpToolRecord } from "./snapshot.js";
@@ -6,7 +6,9 @@ export declare class McpPool {
     private readonly options;
     private readonly live;
     constructor(options: {
-        readonly dataDir: string;
+        /** Absolute Tenant `plugin-data` directory. */
+        readonly pluginData: string;
+        readonly childEnv: Readonly<Record<string, string>>;
         readonly authorize: (sessionId: string, request: {
             url: string;
             serverName: string;
@@ -31,6 +33,7 @@ export declare class McpPool {
     }): Promise<McpDiagnostic[]>;
     call(input: {
         sessionId: string;
+        agentId?: string;
         capabilityId: string;
         serverName: string;
         serverToolName: string;
@@ -43,3 +46,14 @@ export declare class McpPool {
     private liveKey;
     private connectDeclared;
 }
+interface DeclaredServer {
+    /** Absent for the session's root agent. */
+    readonly agentId?: string;
+    /** The manifest of the agent that declares the server. */
+    readonly manifest: AgentManifest;
+    readonly capabilityId: string;
+    readonly server: McpServerManifest;
+}
+/** Servers of the root agent, then of each agent it uses as a tool. */
+export declare function serversOf(manifest: AgentManifest): DeclaredServer[];
+export {};

package/dist/mcp/pool.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { delegatesOf } from "@nylorun/core/define";
 import { callMcpTool, diagnosticFromError, listMcpTools, openMcpServer, } from "./connect.js";
 import { declaredToolNames, } from "./snapshot.js";
 export class McpPool {
@@ -8,7 +9,8 @@ export class McpPool {
         this.options = options;
     }
     async discover(input) {
-        const taken = declaredToolNames(input.manifest);
+        // Each agent names its own tools, so collisions are checked per agent.
+        const taken = new Map();
         const tools = [];
         const diagnostics = [];
         for (const declared of serversOf(input.manifest)) {
@@ -19,13 +21,16 @@ export class McpPool {
                 continue;
             }
             try {
+                if (!taken.has(declared.agentId))
+                    taken.set(declared.agentId, declaredToolNames(declared.manifest));
                 const listed = await listMcpTools(opened.connection.client, {
                     capabilityId: declared.capabilityId,
                     serverName: declared.server.name,
-                    taken,
+                    taken: taken.get(declared.agentId),
                 });
-                tools.push(...listed.tools);
+                tools.push(...listed.tools.map((tool) => owned(declared, tool)));
                 diagnostics.push({
+                    ...ownerOf(declared),
                     capabilityId: declared.capabilityId,
                     serverName: declared.server.name,
                     outcome: "connected",
@@ -37,7 +42,7 @@ export class McpPool {
             }
             catch (error) {
                 await opened.connection.close().catch(() => { });
-                diagnostics.push(diagnosticFromError(declared.capabilityId, declared.server.name, error));
+                diagnostics.push(owned(declared, diagnosticFromError(declared.capabilityId, declared.server.name, error)));
             }
         }
         return {
@@ -53,16 +58,17 @@ export class McpPool {
         const diagnostics = [];
         const seen = new Set();
         for (const tool of input.tools) {
-            const key = `${tool.capabilityId}\0${tool.serverName}`;
+            const key = this.liveKey(input.sessionId, tool.agentId, tool.capabilityId, tool.serverName);
             if (seen.has(key))
                 continue;
             seen.add(key);
-            if (this.live.has(this.liveKey(input.sessionId, tool.capabilityId, tool.serverName)))
+            if (this.live.has(key))
                 continue;
             input.signal?.throwIfAborted();
-            const declared = serversOf(input.manifest).find((item) => item.capabilityId === tool.capabilityId && item.server.name === tool.serverName);
+            const declared = findServer(input.manifest, tool.agentId, tool.capabilityId, tool.serverName);
             if (!declared) {
                 diagnostics.push({
+                    ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
                     capabilityId: tool.capabilityId,
                     serverName: tool.serverName,
                     outcome: "failed",
@@ -80,10 +86,10 @@ export class McpPool {
         return diagnostics;
     }
     async call(input) {
-        const key = this.liveKey(input.sessionId, input.capabilityId, input.serverName);
+        const key = this.liveKey(input.sessionId, input.agentId, input.capabilityId, input.serverName);
         let live = this.live.get(key);
         if (!live) {
-            const declared = serversOf(input.manifest).find((item) => item.capabilityId === input.capabilityId && item.server.name === input.serverName);
+            const declared = findServer(input.manifest, input.agentId, input.capabilityId, input.serverName);
             if (!declared)
                 throw new Error(`MCP server '${input.serverName}' is not declared`);
             const opened = await this.connectDeclared(input, declared);
@@ -102,21 +108,22 @@ export class McpPool {
         await Promise.all(connections.map((item) => item.connection.close().catch(() => { })));
     }
     remember(sessionId, declared, connection) {
-        this.live.set(this.liveKey(sessionId, declared.capabilityId, declared.server.name), {
+        this.live.set(this.liveKey(sessionId, declared.agentId, declared.capabilityId, declared.server.name), {
             capabilityId: declared.capabilityId,
             serverName: declared.server.name,
             connection,
         });
     }
-    liveKey(sessionId, capabilityId, serverName) {
-        return JSON.stringify([sessionId, capabilityId, serverName]);
+    liveKey(sessionId, agentId, capabilityId, serverName) {
+        return JSON.stringify([sessionId, agentId ?? null, capabilityId, serverName]);
     }
     async connectDeclared(input, declared) {
         try {
             const connection = await openMcpServer({
                 server: declared.server,
-                pluginRoot: input.pluginRoots[declared.capabilityId],
-                pluginData: join(this.options.dataDir, "plugin-data", declared.capabilityId),
+                pluginRoot: input.pluginRoots[pluginKey(declared)],
+                pluginData: join(this.options.pluginData, ...pluginKey(declared).split("/")),
+                childEnv: this.options.childEnv,
                 authorize: declared.server.type === "stdio"
                     ? undefined
                     : (url) => this.options.authorize(input.sessionId, {
@@ -129,15 +136,43 @@ export class McpPool {
         catch (error) {
             return {
                 ok: false,
-                diagnostic: diagnosticFromError(declared.capabilityId, declared.server.name, error),
+                diagnostic: owned(declared, diagnosticFromError(declared.capabilityId, declared.server.name, error)),
             };
         }
     }
 }
-function serversOf(manifest) {
+/** Servers of the root agent, then of each agent it uses as a tool. */
+export function serversOf(manifest) {
     const servers = [];
-    for (const capability of manifest.capabilities)
-        for (const server of Object.values(capability.mcpServers ?? {}))
-            servers.push({ capabilityId: capability.id, server });
+    const add = (agent, agentId) => {
+        for (const capability of agent.capabilities)
+            for (const server of Object.values(capability.mcpServers ?? {}))
+                servers.push({
+                    ...(agentId === undefined ? {} : { agentId }),
+                    manifest: agent,
+                    capabilityId: capability.id,
+                    server,
+                });
+    };
+    add(manifest);
+    for (const child of delegatesOf(manifest))
+        add(child.manifest, child.manifest.id);
     return servers;
 }
+function findServer(manifest, agentId, capabilityId, serverName) {
+    return serversOf(manifest).find((item) => item.agentId === agentId &&
+        item.capabilityId === capabilityId &&
+        item.server.name === serverName);
+}
+/** Plugin roots of agents used as tools are registered as `<agent>/<capability>`. */
+function pluginKey(declared) {
+    return declared.agentId === undefined
+        ? declared.capabilityId
+        : `${declared.agentId}/${declared.capabilityId}`;
+}
+function ownerOf(declared) {
+    return declared.agentId === undefined ? {} : { agentId: declared.agentId };
+}
+function owned(declared, value) {
+    return { ...ownerOf(declared), ...value };
+}

package/dist/mcp/snapshot.d.ts

@@ -1,6 +1,8 @@
 import type { JsonObject } from "@nylorun/core/define";
 import type { AgentManifest } from "@nylorun/core/define";
 export interface McpToolRecord {
+    /** The agent used as a tool that declares the server; absent for the session's root agent. */
+    readonly agentId?: string;
     readonly capabilityId: string;
     readonly serverName: string;
     readonly serverToolName: string;
@@ -15,6 +17,8 @@ export interface McpSnapshot {
     readonly mcpTools: readonly McpToolRecord[];
 }
 export interface McpDiagnostic {
+    /** The agent used as a tool that declares the server; absent for the session's root agent. */
+    readonly agentId?: string;
     readonly capabilityId: string;
     readonly serverName: string;
     readonly outcome: "connected" | "refused" | "failed";

package/dist/mcp/stdio.d.ts

@@ -12,4 +12,6 @@ export declare function prepareStdioLaunch(server: Extract<McpServerManifest, {
 }>, options: {
     readonly pluginRoot?: string;
     readonly pluginData: string;
+    /** Allowlisted base env (Tenant HOME/TMPDIR/PATH). Manifest env overlays it (A9). */
+    readonly childEnv?: Readonly<Record<string, string>>;
 }): StdioLaunch;

package/dist/mcp/stdio.js

@@ -38,7 +38,9 @@ export function prepareStdioLaunch(server, options) {
     const cwd = server.cwd
         ? resolveContainedCwd(server.cwd, pluginRoot, pluginData)
         : (pluginRoot ?? pluginData);
-    const env = {};
+    // childEnv under manifest env; HOME/TMPDIR from childEnv override Host defaults
+    // that StdioClientTransport merges via getDefaultEnvironment() (R2).
+    const env = { ...(options.childEnv ?? {}) };
     for (const [key, value] of Object.entries(server.env ?? {}))
         env[key] = expand(value, pluginRoot, pluginData);
     if (pluginRoot)

package/dist/model/auth-store.d.ts

@@ -3,7 +3,7 @@ export declare class ProjectCredentialStore implements CredentialStore {
     #private;
     private readonly file;
     private readonly legacyFile?;
-    constructor(file?: string, legacyFile?: string | undefined);
+    constructor(file: string, legacyFile?: string | undefined);
     read(providerId: string): Promise<Credential | undefined>;
     list(): Promise<readonly CredentialInfo[]>;
     modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;

package/dist/model/auth-store.js

@@ -1,11 +1,11 @@
 var _a;
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 export class ProjectCredentialStore {
     file;
     legacyFile;
     #chain = Promise.resolve();
-    constructor(file = join(process.cwd(), ".nylorun", "auth.json"), legacyFile) {
+    constructor(file, legacyFile) {
         this.file = file;
         this.legacyFile = legacyFile;
     }

package/dist/model/models.d.ts

@@ -6,6 +6,10 @@ export type Selection = Readonly<{
         baseUrl: string;
     }>;
 }>;
+/**
+ * Build the pi-ai model registry from explicit credentials only.
+ * Ambient process environment / provider env auth is never consulted (A7, A10).
+ */
 export declare function modelsFor(selection: Selection, credentials: CredentialStore, options?: {
     environment?: boolean;
 }): import("@earendil-works/pi-ai").MutableModels;

package/dist/model/models.js

@@ -1,31 +1,15 @@
-import { createProvider, defaultProviderAuthContext, envApiKeyAuth, } from "@earendil-works/pi-ai";
+import { createProvider, } from "@earendil-works/pi-ai";
 import { stream, streamSimple, } from "@earendil-works/pi-ai/api/openai-completions";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+/**
+ * Build the pi-ai model registry from explicit credentials only.
+ * Ambient process environment / provider env auth is never consulted (A7, A10).
+ */
 export function modelsFor(selection, credentials, options = {}) {
-    const environmentFirst = {
-        async read(providerId, options) {
-            const explicit = process.env.MODEL_PROVIDER_API_KEY;
-            if (explicit &&
-                (!selection.provider || selection.provider === providerId))
-                return { type: "api_key", key: explicit };
-            const provider = models
-                .getProviders()
-                .find((item) => item.id === providerId);
-            const ambient = await provider?.auth.apiKey?.resolve({
-                ctx: defaultProviderAuthContext(),
-                signal: options?.signal ?? new AbortController().signal,
-            });
-            if (ambient)
-                return undefined;
-            return credentials.read(providerId, options);
-        },
-        list: (options) => credentials.list(options),
-        modify: (id, fn, options) => credentials.modify(id, fn, options),
-        delete: (id, options) => credentials.delete(id, options),
-    };
-    const models = builtinModels({
-        credentials: options.environment === false ? credentials : environmentFirst,
-    });
+    if (options.environment) {
+        throw new Error("Ambient model environment is not supported; pass credentials explicitly");
+    }
+    const models = builtinModels({ credentials });
     if (!selection.custom)
         return models;
     const model = {
@@ -45,7 +29,19 @@ export function modelsFor(selection, credentials, options = {}) {
         name: "Custom OpenAI-compatible",
         baseUrl: selection.custom.baseUrl,
         auth: {
-            apiKey: envApiKeyAuth("Custom API key", ["MODEL_PROVIDER_API_KEY"]),
+            apiKey: {
+                label: "Custom API key",
+                schemas: [],
+                async resolve() {
+                    const credential = await credentials.read("custom");
+                    if (!credential || credential.type !== "api_key")
+                        return undefined;
+                    const key = credential.key;
+                    if (!key)
+                        return undefined;
+                    return { type: "api_key", auth: { apiKey: key } };
+                },
+            },
         },
         models: [model],
         api: { stream, streamSimple },

package/dist/model/pi-model.js

@@ -13,7 +13,7 @@ const emptyUsage = () => ({
 export function piModel(options = {}) {
     return async (call, context) => {
         context.signal.throwIfAborted();
-        const root = options.root ?? process.cwd();
+        const root = options.root ?? "";
         const stored = options.readHostModel?.();
         if (!stored)
             throw new Error("Model provider is not configured. Start nylorun dev in a terminal, or set it in Studio.");

package/dist/model/settings.d.ts

@@ -1 +1,5 @@
-export declare function projectSecrets(root?: string): readonly string[];
+/**
+ * Collect likely secret strings from an explicit env map and optional auth.json
+ * under `root`. Callers must pass values; no ambient environment or cwd (A7).
+ */
+export declare function projectSecrets(root: string, env?: Readonly<Record<string, string | undefined>>): readonly string[];

package/dist/model/settings.js

@@ -1,7 +1,11 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-export function projectSecrets(root = process.cwd()) {
-    const values = Object.entries(process.env)
+/**
+ * Collect likely secret strings from an explicit env map and optional auth.json
+ * under `root`. Callers must pass values; no ambient environment or cwd (A7).
+ */
+export function projectSecrets(root, env = {}) {
+    const values = Object.entries(env)
         .filter(([key]) => /key|token|secret|password|credential/i.test(key))
         .flatMap(([, value]) => (value ? [value] : []));
     for (const directory of [".nylorun", ".env"])

package/dist/sandbox/select.d.ts

@@ -7,7 +7,7 @@ export interface SandboxSelection {
     readonly reason: string;
     readonly probes: readonly SandboxProbe[];
 }
-/** Serializable view of a selection for the CLI and `GET /v1/host/sandbox`. */
+/** Serializable view of a selection for the CLI and `GET /v1/tenant/sandbox`. */
 export interface SandboxSelectionReport {
     readonly preference: SandboxPreference;
     readonly backend: SandboxBackendName | null;
@@ -27,9 +27,10 @@ export declare function parseSandboxPreference(value: string | undefined): Sandb
 export declare function selectSandboxBackend(backends: readonly SandboxBackend[], preference: SandboxPreference): Promise<SandboxSelection>;
 export declare function reportSelection(selection: SandboxSelection): SandboxSelectionReport;
 /**
- * Probe this machine the way a Runtime would at startup. Used by `nylorun doctor sandbox`.
- * Nothing is created or booted.
+ * Probe backends the way a Tenant Runtime would at open.
+ * Callers must pass an explicit probe root; no ambient env or OS temp (A7).
  */
 export declare function probeSandboxBackends(options?: {
     readonly preference?: string;
+    readonly root?: string;
 }): Promise<SandboxSelectionReport>;

package/dist/sandbox/select.js

@@ -1,5 +1,3 @@
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { microsandboxBackend } from "../adapters/sandbox/microsandbox.js";
 import { virtualBackend } from "../adapters/sandbox/virtual.js";
 const PREFERENCES = ["auto", "microsandbox", "virtual"];
@@ -26,10 +24,15 @@ export async function selectSandboxBackend(backends, preference) {
         const backend = backends.find((item) => item.name === preference);
         const probe = probeOf(preference);
         if (backend && probe?.available)
-            return { preference, backend, reason: `${preference} selected by NYLORUN_SANDBOX`, probes };
+            return {
+                preference,
+                backend,
+                reason: `${preference} selected by TenantConfig.sandbox.backend`,
+                probes,
+            };
         return {
             preference,
-            reason: `NYLORUN_SANDBOX=${preference} but ${preference} is unavailable: ${probe?.reason ?? "unknown backend"}. Fix it, or unset NYLORUN_SANDBOX to use the best available backend`,
+            reason: `sandbox.backend=${preference} but ${preference} is unavailable: ${probe?.reason ?? "unknown backend"}. Fix it, or set backend to auto to use the best available backend`,
             probes,
         };
     }
@@ -58,18 +61,21 @@ export function reportSelection(selection) {
     };
 }
 /**
- * Probe this machine the way a Runtime would at startup. Used by `nylorun doctor sandbox`.
- * Nothing is created or booted.
+ * Probe backends the way a Tenant Runtime would at open.
+ * Callers must pass an explicit probe root; no ambient env or OS temp (A7).
  */
 export async function probeSandboxBackends(options = {}) {
-    const preference = parseSandboxPreference(options.preference ?? process.env.NYLORUN_SANDBOX);
-    const backends = defaultSandboxBackends({ root: join(tmpdir(), "nylorun-sandbox-probe") });
+    if (!options.root) {
+        throw new Error("probeSandboxBackends requires an explicit root (Tenant or Host tmp path)");
+    }
+    const preference = parseSandboxPreference(options.preference ?? "auto");
+    const backends = defaultSandboxBackends({ root: options.root });
     if (!preference)
         return {
             preference: "auto",
             backend: null,
             isolation: null,
-            reason: "NYLORUN_SANDBOX must be auto, microsandbox or virtual",
+            reason: "sandbox.backend must be auto, microsandbox or virtual",
             probes: await Promise.all(backends.map((backend) => backend.probe())),
         };
     return reportSelection(await selectSandboxBackend(backends, preference));

package/dist/sandbox/share.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared workflow sandbox: one sandbox per owning session, attached via
+ * PutSession.sandbox = { session }. Specs must match; keys use the owner id.
+ */
+import { type AgentManifest, type CapabilityManifest, type SandboxManifest, type WorkflowManifest } from "@nylorun/core/define";
+export type SessionSandboxRef = {
+    readonly id: string;
+    readonly ownerUserId: string;
+    readonly manifest: AgentManifest | WorkflowManifest | Record<string, unknown>;
+    /** Session whose id keys the sandbox. Absent means this session owns its own. */
+    readonly sandboxOwnerId?: string | null;
+};
+/** Sandbox spec declared on an agent capability or a workflow manifest. */
+export declare function sandboxSpecOf(manifest: AgentManifest | WorkflowManifest | Record<string, unknown> | undefined): SandboxManifest | undefined;
+export declare function sandboxSpecsEqual(a: SandboxManifest | undefined, b: SandboxManifest | undefined): boolean;
+/** Synthetic capability so SandboxManager.run can use a workflow (or shared) spec. */
+export declare function capabilityForSandbox(sandbox: SandboxManifest): CapabilityManifest;
+/**
+ * Resolve the session id that keys the sandbox. Walks one hop via sandboxOwnerId;
+ * cycles fall back to the starting session.
+ */
+export declare function owningSandboxSessionId(session: SessionSandboxRef, lookup: (id: string) => SessionSandboxRef | undefined): string;
+export declare function sessionHasSandbox(session: SessionSandboxRef, lookup: (id: string) => SessionSandboxRef | undefined): boolean;

package/dist/sandbox/share.js

@@ -0,0 +1,58 @@
+/**
+ * Shared workflow sandbox: one sandbox per owning session, attached via
+ * PutSession.sandbox = { session }. Specs must match; keys use the owner id.
+ */
+import { canonical, } from "@nylorun/core/define";
+/** Sandbox spec declared on an agent capability or a workflow manifest. */
+export function sandboxSpecOf(manifest) {
+    if (!manifest || typeof manifest !== "object")
+        return undefined;
+    if (manifest.kind === "workflow")
+        return manifest.sandbox;
+    const capabilities = manifest.capabilities;
+    if (!Array.isArray(capabilities))
+        return undefined;
+    for (const capability of capabilities)
+        if (capability.sandbox)
+            return capability.sandbox;
+    return undefined;
+}
+export function sandboxSpecsEqual(a, b) {
+    if (a === undefined && b === undefined)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    return canonical(a) === canonical(b);
+}
+/** Synthetic capability so SandboxManager.run can use a workflow (or shared) spec. */
+export function capabilityForSandbox(sandbox) {
+    return {
+        id: "sandbox",
+        type: "agent",
+        sandbox,
+        tools: [],
+    };
+}
+/**
+ * Resolve the session id that keys the sandbox. Walks one hop via sandboxOwnerId;
+ * cycles fall back to the starting session.
+ */
+export function owningSandboxSessionId(session, lookup) {
+    const seen = new Set();
+    let current = session;
+    while (current) {
+        if (seen.has(current.id))
+            return session.id;
+        seen.add(current.id);
+        const ownerId = current.sandboxOwnerId;
+        if (!ownerId || ownerId === current.id)
+            return current.id;
+        current = lookup(ownerId);
+    }
+    return session.id;
+}
+export function sessionHasSandbox(session, lookup) {
+    const ownerId = owningSandboxSessionId(session, lookup);
+    const owner = ownerId === session.id ? session : lookup(ownerId) ?? session;
+    return sandboxSpecOf(owner.manifest) !== undefined || sandboxSpecOf(session.manifest) !== undefined;
+}

package/dist/tenant/envelope.d.ts

@@ -0,0 +1,10 @@
+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;
+    schemaVersion: number;
+}, now?: Date): TenantEnvelope;