@celestea/studio 2.7.1

package/dist/runtime/engine-permissions.js

@@ -0,0 +1,92 @@
+/**
+ * effectivePermissionOf (W9) - the ONE reader of a session's permission
+ * BASELINE. engine-grants.ts intersects grants into it.
+ *
+ * Resolution of the requested preset:
+ *   1. the caller hint (worker sessions have no directory and carry it in meta);
+ *   2. <session dir>/permission.json;
+ *   3. CELESTEA_PERMISSION_DEFAULT (default "full-access").
+ * The baseline capabilities are then CLAMPED by CELESTEA_PERMISSION_MAX
+ * (default "full-access"). The operator env gate for "unsandboxed" is applied
+ * by engine-grants.ts when it builds the final EffectiveGrants, so this module
+ * never imports engine-grants (no cycle).
+ */
+import { dirname } from "node:path";
+import { parseToolRoots } from "@celestea/tools";
+import { loadStudioConfig } from "../config.js";
+import { builtinPreset, defaultPermissionId, maxPermissionId, readPermissionsFile, readSessionPermission, } from "../store/permissions.js";
+/** The data dir of the studio (same one workspaces.json / auth secret use). */
+export function permissionDataDir(env) {
+    return dirname(loadStudioConfig({ env }).paths.workspacesFile);
+}
+function presetById(id, custom) {
+    const builtin = builtinPreset(id);
+    if (builtin !== null)
+        return builtin;
+    for (const preset of custom)
+        if (preset.id === id)
+            return preset;
+    return null;
+}
+/** Capability-wise clamp by the operator MAX preset (a grant/档 can only narrow). */
+function clampByMax(preset, max) {
+    const writesAllowed = max.allPaths || max.workspaceWritable || max.toolRootsWritable || max.writeRoots.length > 0;
+    return {
+        id: preset.id,
+        label: preset.label,
+        network: preset.network && max.network,
+        workspaceWritable: preset.workspaceWritable && max.workspaceWritable,
+        toolRootsWritable: preset.toolRootsWritable && max.toolRootsWritable,
+        writeRoots: writesAllowed ? preset.writeRoots.filter((root) => max.writeRoots.includes(root)) : [],
+        allPaths: preset.allPaths && max.allPaths,
+        unsandboxed: preset.unsandboxed && max.unsandboxed,
+        toolDeny: [...new Set([...preset.toolDeny, ...max.toolDeny])],
+    };
+}
+export function effectivePermissionOf(sessionDir, sessionId, env, presetHint) {
+    const warnings = [];
+    const dataDir = permissionDataDir(env);
+    const customRead = readPermissionsFile(dataDir);
+    warnings.push(...customRead.warnings);
+    const custom = customRead.presets;
+    let requested = presetHint ?? null;
+    // W878: the sidecar is self-describing — use the TRUSTED id, never a path
+    // inference. A null id with a real directory degrades fail-closed.
+    if (requested === null && sessionDir !== null && sessionId !== null) {
+        const file = readSessionPermission(sessionDir, sessionId);
+        if (file.error !== undefined)
+            warnings.push("permission_unreadable: " + file.error);
+        if (file.preset !== undefined)
+            requested = file.preset;
+    }
+    if (requested === null || requested === "")
+        requested = defaultPermissionId(env);
+    const fallback = presetById(defaultPermissionId(env), custom) ?? builtinPreset("full-access");
+    const max = presetById(maxPermissionId(env), custom) ?? builtinPreset("full-access");
+    let preset = presetById(requested, custom);
+    if (preset === null) {
+        warnings.push("unknown permission preset " + JSON.stringify(requested) + " - using " + fallback.id);
+        preset = fallback;
+    }
+    const clamped = clampByMax(preset, max);
+    const writeRoots = [];
+    if (clamped.toolRootsWritable) {
+        for (const root of parseToolRoots(env["CELESTEA_TOOL_ROOTS"]))
+            if (!writeRoots.includes(root))
+                writeRoots.push(root);
+    }
+    for (const root of clamped.writeRoots)
+        if (!writeRoots.includes(root))
+            writeRoots.push(root);
+    return {
+        preset: clamped.id,
+        network: clamped.network,
+        workspaceWritable: clamped.workspaceWritable,
+        toolRootsWritable: clamped.toolRootsWritable,
+        writeRoots,
+        allPaths: clamped.allPaths,
+        unsandboxed: clamped.unsandboxed,
+        toolDeny: clamped.toolDeny,
+        warnings,
+    };
+}

package/dist/runtime/engine-plugins.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The engine's compose plugins: the `Llm` seam, the tool registry (builtins +
+ * the three worker-orchestration tools) and the agent loop.
+ *
+ * This module exists so `real-runtime-adapter.ts` stays about the HTTP contract:
+ * every `Context` service the runtime resolves at turn start is provided here,
+ * in one place, with the tool set assembled explicitly (a later `provide` wins,
+ * so the host can override any of them by mounting its own plugin).
+ *
+ * W741 (fixes the W738 §4 finding): the sandbox is **always** chosen by the
+ * provider policy — `selectSandboxDetailed`, i.e. bwrap whenever the host can
+ * give it, with or without session grants — and the resulting decision travels
+ * with every run (`SandboxDecision`). `CELESTEA_SANDBOX_FALLBACK=fail` is read on
+ * the default path too and it REFUSES to execute (structured `SandboxError`)
+ * instead of degrading to the userspace provider behind the operator's back.
+ */
+import { type AskUserQuestionAnswerItem, type EventBus, type Llm, type Plugin, type Sandbox, type SandboxMeta, type Tool, type ToolGuard, type ToolRegistry } from "@celestea/core";
+import { PendingQuestion, type QuestionRegistry } from "../question-registry.js";
+import { type Profile } from "@celestea/runtime";
+import { DisclosurePolicy, ProcessRegistry, type AttachmentStore, type SessionFsScope, type HostProbe, type SandboxFallbackMode } from "@celestea/tools";
+import { type WorkerRegistry } from "@celestea/workers";
+import { type EffectiveGrants, type EngineGrantAudit } from "./engine-grants.js";
+import { type SessionMode } from "../store/mode.js";
+/** Everything the engine context needs from the host. */
+export interface EnginePluginInput {
+    profile: Profile;
+    llm: Llm;
+    /**
+     * W804: the session's content-addressed attachment store. Present = the tool
+     * face also offers `read_image` (and the wire can resolve bytes); absent = no
+     * attachment capability at all.
+     */
+    attachments?: AttachmentStore | null;
+    /**
+     * W804: false ONLY when the target model's input_modalities was EXPLICITLY
+     * configured without "image". Absent/true = the optimistic default.
+     */
+    imageInputAllowed?: boolean;
+    /**
+     * W791 (P1, §5.2 #2): the session's working mode. `execution` folds the SDK
+     * tools out of the DIRECT face (the inner registry keeps them, so `run_code`
+     * sub-calls still run); absent/`standard` = the whole registry, byte-for-byte
+     * what every pre-P1 generation exposed.
+     */
+    mode?: SessionMode;
+    /**
+     * W806 (P0): dynamic tool disclosure. Absent = the static mode baseline, i.e.
+     * today's byte-identical face. Present = `initial` is offered from the start
+     * and the rest of the disclosable universe is revealed ONE TURN AT A TIME,
+     * appended at the tail, when a direct call is refused (monotonic; never
+     * reordered — see `disclosure.ts`).
+     */
+    disclosure?: DisclosureOptions;
+    /** Worker registry to expose the three orchestration tools over (null = none). */
+    workers: WorkerRegistry | null;
+    /** Extra tools appended after the builtins. */
+    tools?: readonly Tool[];
+    /**
+     * Sandbox override (tests inject a fake). This is the ONE explicit policy
+     * bypass: it is reported as `fallback_source: "injected"` in every result.
+     */
+    sandbox?: Sandbox;
+    /** Guard override: `undefined` = mount the production guard, `null` = none. */
+    guard?: ToolGuard | null;
+    env?: NodeJS.ProcessEnv;
+    /** The session's effective grants (W516); default: none (least privilege). */
+    grants?: EffectiveGrants;
+    /** Bound audit sink for grant use / degradation events (W516 §4.4). */
+    audit?: EngineGrantAudit;
+    /** Injected host probe (tests / diagnostics); default: the memoized host probe. */
+    probe?: HostProbe;
+    /**
+     * W768: the composing SESSION's workspace (see `SessionFsScope`). The host
+     * resolves it from the session's own record — the very same value its system
+     * prompt renders — so the sandbox cwd/root and the guard's writable workspace
+     * follow the session, not the process. `null`/absent = the env posture.
+     */
+    workspace?: SessionFsScope | null;
+    /**
+     * W783: the pending-question table of this process. Supplied = the session
+     * mounts `ask_user_question` and answers through the waterfall; absent = the
+     * feature is not mounted at all (the tool is then not offered to the model).
+     */
+    questions?: QuestionWiring | null;
+}
+/**
+ * W783: a one-slot holder for the session's event bus. `engineTools()` runs
+ * before `compose()` provides the bus and the plugin body runs after, so the
+ * value travels through this object instead of a compose-time argument.
+ */
+export interface BusHolder {
+    current: EventBus | null;
+}
+/**
+ * W806: activation of the dynamic-disclosure layer. The mechanism is always
+ * assembled; this is what asks it to withhold anything.
+ */
+export interface DisclosureOptions {
+    /**
+     * Names offered from the start. Default = the whole disclosable universe for
+     * the session's mode (the mode baseline = today's face, a no-op). Names
+     * outside the registry, or blocked by the mode, are dropped.
+     */
+    initial?: readonly string[];
+}
+/** W783: everything the engine needs to mount the user-question capability. */
+export interface QuestionWiring {
+    /** Process-wide pending table (shared by every session generation). */
+    registry: QuestionRegistry;
+    /**
+     * The session's async answerer chain (the runtime's own event bus). The plugin
+     * body fills this in, so the wiring can be built BEFORE `compose()` runs while
+     * the bus only exists DURING it.
+     */
+    bus: BusHolder;
+    /** The session id this generation is composed for (`null` = detached). */
+    sessionId: string | null;
+    /** Is this generation still live? (§5.3 `CALLER_NOT_LIVE` when it is not.) */
+    isLive?: () => boolean;
+    /** Publish one request to the UI (`question` SSE frame). */
+    publish: (question: PendingQuestion) => void;
+    /** Record the request in the session log (`user_question` row, §7). */
+    record: (question: PendingQuestion) => void;
+    /** Record how it ended (`user_answer` row, §7) — answer and timeout alike. */
+    recordAnswer: (requestId: string, answers: AskUserQuestionAnswerItem[], timedOut: boolean) => void;
+}
+export interface EngineTools {
+    /** Plugin providing TOOL_REGISTRY_SERVICE / SANDBOX_SERVICE / PROCESS_REGISTRY_SERVICE. */
+    plugin: Plugin;
+    /**
+     * The registry the session's Context provides (and therefore the face `GET
+     * /api/tools?session=` and `{{tools}}` read). W791: in `execution` mode this is
+     * the EXPOSED view — the inner registry stays reachable to `run_code` only.
+     */
+    registry: ToolRegistry;
+    /** The sandbox actually mounted (W741: annotated with the policy decision). */
+    sandbox: Sandbox;
+    /**
+     * W855: the session's background-process registry. The HOST keeps this handle
+     * so `Runtime.shutdown` can reap detached children via a shutdown hook —
+     * `ProcessRegistry.dispose()` had no caller before this.
+     */
+    processes: ProcessRegistry;
+    /** Why that sandbox was chosen — auditable, never inferred by a caller. */
+    decision: SandboxDecision;
+    /**
+     * W806: the dynamic-disclosure policy of this generation. Always present; inert
+     * (nothing withheld) unless `EnginePluginInput.disclosure` asked for a reduced
+     * initial set. The runtime calls `beginTurn()` at every turn start.
+     */
+    disclosure: DisclosurePolicy;
+}
+/** The tool set: six builtins + the three worker tools (when a registry exists). */
+export declare function engineTools(opts: EnginePluginInput): EngineTools;
+/** Where one session's sandbox came from (W741 §3 — never inferred by a caller). */
+export type SandboxDecisionSource = "policy" | "grant" | "refused" | "injected";
+/**
+ * The provider-policy decision behind one composed session.
+ *
+ * `degraded` keeps one invariant: `true` ⟺ commands really run on the userspace
+ * provider (no namespaces, no seccomp). A refusal is therefore NOT "degraded" —
+ * it is `source: "refused"` plus a structured `SandboxError` on every execution
+ * attempt — and an injected sandbox reports `null` (the policy never decided it).
+ */
+export interface SandboxDecision {
+    /** Provider that will execute (`"none"` when every run is refused). */
+    provider: string;
+    degraded: boolean | null;
+    reason: string | null;
+    /** `CELESTEA_SANDBOX_FALLBACK` in force at compose time (`null` = unreadable). */
+    mode: SandboxFallbackMode | null;
+    source: SandboxDecisionSource;
+}
+/** `SandboxMeta` plus the fallback decision the 4-field contract cannot carry. */
+export interface DecidedSandboxMeta extends SandboxMeta {
+    degraded: boolean | null;
+    fallback_reason: string | null;
+    fallback_mode: SandboxFallbackMode | null;
+    fallback_source: SandboxDecisionSource;
+}
+/** Provide the `Llm` seam (the offline engine by default). */
+export declare function engineLlmPlugin(llm: Llm, name?: string): Plugin;
+/** Provide the agent loop driver (needed for worker driving). */
+export declare function engineLoopPlugin(profile: Profile, name?: string): Plugin;
+/** Convenience: the three plugins in mount order (llm, loop, tools). */
+export declare function enginePlugins(input: EnginePluginInput): {
+    plugins: Plugin[];
+    tools: EngineTools;
+};

package/dist/runtime/engine-plugins.js

@@ -0,0 +1,292 @@
+/**
+ * The engine's compose plugins: the `Llm` seam, the tool registry (builtins +
+ * the three worker-orchestration tools) and the agent loop.
+ *
+ * This module exists so `real-runtime-adapter.ts` stays about the HTTP contract:
+ * every `Context` service the runtime resolves at turn start is provided here,
+ * in one place, with the tool set assembled explicitly (a later `provide` wins,
+ * so the host can override any of them by mounting its own plugin).
+ *
+ * W741 (fixes the W738 §4 finding): the sandbox is **always** chosen by the
+ * provider policy — `selectSandboxDetailed`, i.e. bwrap whenever the host can
+ * give it, with or without session grants — and the resulting decision travels
+ * with every run (`SandboxDecision`). `CELESTEA_SANDBOX_FALLBACK=fail` is read on
+ * the default path too and it REFUSES to execute (structured `SandboxError`)
+ * instead of degrading to the userspace provider behind the operator's back.
+ */
+import { definePlugin, LLM_SERVICE, SANDBOX_SERVICE, TOOL_REGISTRY_SERVICE, USER_QUESTION_SERVICE, EVENT_BUS_SERVICE, SandboxError, } from "@celestea/core";
+import { agentLoopPlugin } from "@celestea/agent-loop";
+import { createUserQuestionService } from "../user-questions.js";
+import { PendingQuestion } from "../question-registry.js";
+import { agentConfigFromProfile } from "@celestea/runtime";
+import { assembleTools, builtinTools, DisclosurePolicy, disclosureExposure, ENV_SANDBOX_FALLBACK, EXECUTION_TOOL_NAMES, exposedRegistry, fallbackMode, httpOptions, PROCESS_REGISTRY_SERVICE, ProcessRegistry, sandboxConfigFromEnv, sessionSandboxConfig, selectSandboxDetailed, } from "@celestea/tools";
+import { workerTools } from "@celestea/workers";
+import { EMPTY_GRANTS } from "./engine-grants.js";
+import { DEFAULT_SESSION_MODE } from "../store/mode.js";
+/** The tool set: six builtins + the three worker tools (when a registry exists). */
+export function engineTools(opts) {
+    const env = opts.env ?? process.env;
+    const grants = opts.grants ?? EMPTY_GRANTS;
+    const scope = opts.workspace ?? null;
+    const processes = new ProcessRegistry();
+    const choice = opts.sandbox === undefined ? chooseSandbox(env, grants, opts.audit, opts.probe, scope) : injectedChoice(opts.sandbox, env);
+    const sandbox = choice.sandbox;
+    const http = httpOptions(env, { netHosts: grants.netHosts });
+    if (http.policy?.netHostsIneffective) {
+        opts.audit?.({ event: "net_hosts_ineffective", cap: "net_hosts", reason: "neither CELESTEA_HTTP_ALLOW nor CELESTEA_HTTP_DENY is set: the policy stays inactive" });
+    }
+    // W783 §5.3: the service refuses a DELEGATED caller itself (a worker turn has
+    // no human), so the guard is mounted unconditionally here.
+    // W783: the bus holder is filled in by the plugin body below, which runs
+    // inside `compose()` AFTER the runtime provided EVENT_BUS_SERVICE.
+    const busHolder = { current: null };
+    const questions = opts.questions === undefined || opts.questions === null ? null : userQuestionsOf(opts.questions, busHolder);
+    const tools = [
+        ...builtinTools({
+            sandbox,
+            processes,
+            http,
+            // W884: `load_skill` resolves its two source layers from the session's own
+            // workspace — the value the composer resolved via `sessionWorkspaceOf`.
+            workspace: scope?.workspace ?? null,
+            env,
+            ...(questions === null ? {} : { questions }),
+            ...(opts.attachments === undefined ? {} : { attachments: opts.attachments }),
+            ...(opts.imageInputAllowed === undefined ? {} : { imageInputAllowed: opts.imageInputAllowed }),
+            model: opts.profile.model,
+        }),
+        ...(opts.tools ?? []),
+    ];
+    if (opts.workers !== null)
+        tools.push(...workerTools(opts.workers));
+    const assembly = assembleTools({
+        tools,
+        sandbox,
+        processes,
+        env,
+        scope,
+        grants: { readRoots: grants.readRoots, writeRoots: grants.writeRoots, workspaceWritable: grants.workspaceWritable },
+        ...(opts.guard === undefined ? {} : { guard: opts.guard }),
+    });
+    // W791 (P1, §5.2 #2 — the "关键机关"): the CONTEXT sees the mode's model-visible
+    // face while `run_code`'s RegistryHandle stays bound to the INNER registry
+    // (`assembleTools` bound it above), so a program's `tools.read_file(...)` is
+    // dispatched exactly like a direct call was before the fold.
+    // W806 (P0): the SAME face is projected through the dynamic-disclosure policy.
+    // Absent `opts.disclosure` the policy's initial set IS the mode baseline, so
+    // `hidden()` is exactly the old fold and the wire array is byte-identical.
+    // Present, it withholds part of the disclosable universe and reveals it one
+    // turn at a time, appended at the tail (see `disclosure.ts`).
+    const mode = opts.mode ?? DEFAULT_SESSION_MODE;
+    // W9: the permission baseline's denied tools join the BLOCKED set (never
+    // disclosed), so the mode fold and the dynamic-disclosure layer both keep
+    // them out — the universe still lists them, which is what makes `hidden()`
+    // and therefore `exposedRegistry` drop them from the face.
+    const universe = assembly.registry.schemas().map((spec) => spec.name);
+    const blocked = [
+        ...(mode === "execution" ? universe.filter((name) => !EXECUTION_TOOL_NAMES.includes(name)) : []),
+        ...grants.toolDeny,
+    ];
+    const disclosure = new DisclosurePolicy({ universe, initial: opts.disclosure?.initial ?? universe, blocked });
+    const wrapped = mode === "execution" || opts.disclosure !== undefined || grants.toolDeny.length > 0;
+    const exposed = wrapped ? exposedRegistry(assembly.registry, disclosureExposure(disclosure)) : assembly.registry;
+    const plugin = definePlugin("studio.engine.tools", (ctx) => {
+        ctx.provide(TOOL_REGISTRY_SERVICE, exposed);
+        ctx.provide(SANDBOX_SERVICE, assembly.sandbox);
+        ctx.provide(PROCESS_REGISTRY_SERVICE, assembly.processes);
+        // W783: the same service instance the tool was constructed with, published
+        // as a seam too so an answerer layer (or a test) can reach it.
+        if (questions !== null) {
+            busHolder.current = ctx.require(EVENT_BUS_SERVICE);
+            ctx.provide(USER_QUESTION_SERVICE, questions);
+        }
+    });
+    return { plugin, registry: exposed, sandbox, processes, decision: choice.decision, disclosure };
+}
+/** Annotate one provider meta with the decision (`run_shell` reports it verbatim). */
+function decidedMeta(meta, decision) {
+    return {
+        ...meta,
+        degraded: decision.degraded,
+        fallback_reason: decision.reason,
+        fallback_mode: decision.mode,
+        fallback_source: decision.source,
+    };
+}
+/** Wraps a policy-chosen sandbox so every result carries WHY it was chosen. */
+class DecidedSandbox {
+    config;
+    decision;
+    inner;
+    constructor(inner, decision) {
+        this.inner = inner;
+        this.decision = decision;
+        this.config = inner.config;
+    }
+    async run(request) {
+        const result = await this.inner.run(request);
+        return { ...result, sandbox: decidedMeta(result.sandbox, this.decision) };
+    }
+    async spawn(request) {
+        const spawned = await this.inner.spawn(request);
+        return { ...spawned, sandbox: decidedMeta(spawned.sandbox, this.decision) };
+    }
+}
+/** Fail-closed provider: the `fail` policy's answer is a refusal, not a degrade. */
+class RefusingSandbox {
+    config;
+    decision;
+    constructor(config, decision) {
+        this.config = config;
+        this.decision = decision;
+    }
+    async run() {
+        throw this.refusal();
+    }
+    async spawn() {
+        throw this.refusal();
+    }
+    /** The structured error every caller sees: `run_shell-sandbox: code=config …`. */
+    refusal() {
+        const reason = this.decision.reason ?? "bubblewrap is unusable on this host";
+        return new SandboxError("config", `${reason}; CELESTEA_SANDBOX_FALLBACK refuses to execute without OS isolation (only an 'unsandboxed' session grant overrides it)`, { provider: this.decision.provider, reason, mode: this.decision.mode, executed: false });
+    }
+}
+/**
+ * W516/W741: the session's sandbox comes from the provider POLICY — bwrap
+ * whenever the host can give it, with or without grants. Grants only ever widen
+ * what bwrap may keep (`network` → `--share-net`; `unsandboxed` → accept the
+ * userspace provider under `fail`), and nothing here degrades silently: a policy
+ * refusal (or an unreadable policy) becomes a [RefusingSandbox].
+ */
+function chooseSandbox(env, grants, audit, probe, scope = null) {
+    let selection;
+    try {
+        const view = { network: grants.network, unsandboxed: grants.unsandboxed, workspaceWritable: grants.workspaceWritable, writeRoots: grants.writeRoots };
+        selection = selectSandboxDetailed({
+            env,
+            grants: view,
+            config: sessionSandboxConfig(scope, env),
+            ...(probe === undefined ? {} : { probe }),
+        });
+    }
+    catch (error) {
+        return refusedChoice(env, error, audit, scope);
+    }
+    const decision = {
+        provider: selection.provider,
+        degraded: selection.degraded,
+        reason: selection.reason,
+        mode: selection.mode,
+        source: selection.degradedByGrant ? "grant" : "policy",
+    };
+    if (selection.degradedByGrant) {
+        audit?.({ event: "degraded_by_grant", cap: "unsandboxed", provider: selection.provider, reason: selection.reason ?? undefined });
+    }
+    return { sandbox: new DecidedSandbox(selection.sandbox, decision), decision };
+}
+/** Policy refused (or could not be read): refuse to execute, never degrade. */
+function refusedChoice(env, error, audit, scope = null) {
+    const reason = refusalReason(error);
+    const decision = { provider: "none", degraded: false, reason, mode: modeOrNull(env), source: "refused" };
+    audit?.({
+        event: "deny",
+        cap: "sandbox",
+        provider: "none",
+        reason,
+        detail: "the sandbox provider policy refuses to execute: no OS isolation and no degradation allowed (an 'unsandboxed' session grant is the only override)",
+    });
+    return { sandbox: new RefusingSandbox(sessionSandboxConfig(scope, env), decision), decision };
+}
+/** Explicit host injection: the policy is bypassed ON PURPOSE, and says so. */
+function injectedChoice(sandbox, env) {
+    const decision = {
+        provider: sandbox.constructor.name === "" ? "injected" : sandbox.constructor.name,
+        degraded: null,
+        reason: "sandbox injected through EnginePluginInput.sandbox: the provider policy was bypassed explicitly",
+        mode: modeOrNull(env),
+        source: "injected",
+    };
+    return { sandbox: new DecidedSandbox(sandbox, decision), decision };
+}
+/** Cleanest available reason for a refusal (never a nested error envelope). */
+function refusalReason(error) {
+    if (error instanceof SandboxError) {
+        const probeReason = error.detail["reason"];
+        if (typeof probeReason === "string" && probeReason !== "")
+            return `sandbox_unavailable: ${probeReason}`;
+        const badValue = error.detail["value"];
+        if (typeof badValue === "string")
+            return `invalid ${ENV_SANDBOX_FALLBACK}='${badValue}' (expected 'userspace' or 'fail')`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/** The operator's fallback mode as text, or null when it is unreadable (a typo). */
+function modeOrNull(env) {
+    try {
+        return fallbackMode(env);
+    }
+    catch {
+        return null;
+    }
+}
+/** Provide the `Llm` seam (the offline engine by default). */
+export function engineLlmPlugin(llm, name = "studio.engine.llm") {
+    return definePlugin(name, (ctx) => ctx.provide(LLM_SERVICE, llm));
+}
+/** Provide the agent loop driver (needed for worker driving). */
+export function engineLoopPlugin(profile, name = "studio.engine.agent-loop") {
+    return agentLoopPlugin(agentConfigFromProfile(profile), {}, name);
+}
+/** Convenience: the three plugins in mount order (llm, loop, tools). */
+export function enginePlugins(input) {
+    const tools = engineTools(input);
+    return {
+        plugins: [engineLlmPlugin(input.llm), engineLoopPlugin(input.profile), tools.plugin],
+        tools,
+    };
+}
+/**
+ * W783: the session's user-question service. `isLive` answers "is this
+ * generation still the live one?" — a settled/released instance must refuse
+ * instead of parking a question nobody can ever answer (§5.3 `CALLER_NOT_LIVE`).
+ *
+ * The bus is the runtime's own `EVENT_BUS_SERVICE` instance, handed in by the
+ * composer (`session-compose.ts` reads it from the Context at compose time, by
+ * which point `compose()` has already provided it).
+ */
+function userQuestionsOf(wiring, bus) {
+    return createUserQuestionService({
+        registry: wiring.registry,
+        bus: lazyBus(bus),
+        sessionId: wiring.sessionId,
+        ...(wiring.isLive === undefined ? {} : { isLive: wiring.isLive }),
+        publish: wiring.publish,
+        record: wiring.record,
+        recordAnswer: wiring.recordAnswer,
+    });
+}
+/**
+ * A deferred view of the session's event bus. The service holds this for its
+ * whole life while the real bus only exists from the moment `compose()` provides
+ * it, so the first question resolves it and every later one reuses that answer.
+ */
+function lazyBus(holder) {
+    const get = () => {
+        const bus = holder.current;
+        if (bus === null)
+            throw new Error("the session EventBus is not mounted yet: ask_user_question cannot reach the answerer waterfall");
+        return bus;
+    };
+    return {
+        on: (key, listener) => get().on(key, listener),
+        emit: (key, event) => get().emit(key, event),
+        bail: (key, listener) => get().bail(key, listener),
+        runBail: (key, event) => get().runBail(key, event),
+        waterfall: (key, listener) => get().waterfall(key, listener),
+        runWaterfall: (key, event, init) => get().runWaterfall(key, event, init),
+        waterfallAsync: (key, listener) => get().waterfallAsync(key, listener),
+        runWaterfallAsync: (key, event, init) => get().runWaterfallAsync(key, event, init),
+        counts: (key) => get().counts(key),
+    };
+}

package/dist/runtime/engine-profile.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `EngineProfile` (the HTTP-facing host view) <-> `Profile` (the runtime's
+ * frozen 12-key compose config).
+ *
+ * The two shapes differ on purpose: the host view uses the contract names of
+ * `GET /api/config` (`context_window`, no key source), while the engine profile
+ * carries the key RESOLUTION (env var name + optional file) and the request
+ * format. This module is the only translation point, so a new profile key can
+ * never be added on one side only.
+ */
+import type { Profile } from "@celestea/runtime";
+import type { EngineProfile, ProfilePatch } from "../runtime-adapter.js";
+/** The only request format the TS engine composes today (OpenAI-compatible). */
+export declare const ENGINE_REQUEST_FORMAT: Profile["request_format"];
+/** Host view of a composed profile. */
+export declare function engineProfileOf(profile: Profile): EngineProfile;
+/** Compose profile from the host view (extra keys inherit from `base`). */
+export declare function profileFromEngine(engine: EngineProfile, base?: Partial<Profile>): Profile;
+/** Apply an accepted `POST /api/config` patch (the host already validated it). */
+export declare function applyProfilePatch(profile: Profile, patch: ProfilePatch): Profile;
+/**
+ * The startup profile: the host's frozen constants (`MIN_STEPS`,
+ * `CONTEXT_WINDOW`, both read off the frozen `/api/config` snapshot) plus the env
+ * overrides the host honors. The loop budget derives from this profile
+ * (`agentConfigFromProfile`), so the statusline window and the trim budget can
+ * never disagree.
+ */
+export declare function defaultEngineProfile(env: NodeJS.ProcessEnv, apiKeyEnv: string): EngineProfile;