@fungi.computer/truffle 0.0.0-stage → 0.2.0

package/dist/private-local-runtime-host.js

@@ -0,0 +1,1177 @@
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai/utils/event-stream";
+import { observeProviderStatus } from "@fungi.computer/mule";
+import { modelFailureMessage, modelFailureRetryable, } from "./private-provider-rejection.js";
+import { logEvent } from "./log-event.js";
+import { localArchiveHandoff } from "./local-archive-handoff.js";
+import { createMcpFormSession } from "./private-mcp-form-session.js";
+import { localExtensions, } from "./local-extensions.js";
+import { lstat, mkdir, realpath, stat } from "node:fs/promises";
+import { lstatSync, mkdirSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { cleanupSessionResources, } from "@earendil-works/pi-ai";
+import { parseModelPreference, } from "@fungi.computer/shiitake/model-preference";
+import { createAgentControlSource, } from "@fungi.computer/shiitake/agent-control";
+import { defineIdFamily } from "@fungi.computer/cairn";
+import { words } from "@fungi.computer/cairn/words";
+import { botanicalExtensionsWithSkills } from "@fungi.computer/shiitake-extensions/roster";
+import { homeExtension, homeGrant, } from "@fungi.computer/shiitake-extensions/home/host";
+import { Knapsack } from "@fungi.computer/knapsack";
+import { makeHost, Shiitake, ShiitakeError, } from "@fungi.computer/shiitake";
+import { createPrivateModels } from "./local-models.js";
+import { capturePrivateLocalConfigRoot, } from "./private-local-config-root.js";
+import { acquireSubscriptionTurn } from "./subscription-turn.js";
+import { listOfferedLocalModels } from "./private-local-default-model.js";
+import { ensureAgentDefaultModelTable, readAgentDefaultModel, seedAgentDefaultModel, writeAgentDefaultModel, } from "./private-local-agent-default-model.js";
+import { defaultLocalReasoning, resolveKnownLocalStartupChoice, resolveLocalStartupChoice, startupReasoning, validateLocalReasoning, } from "./private-local-startup-model.js";
+import { assertFungiModelsEnabled } from "./private-fungi-model-api.js";
+import { privateLocalEffectiveModelSchema, } from "./private-local-effective-model.js";
+import { createPrivateInvocationComputer, } from "./private-invocation-computer.js";
+import { createPrivateLocalComputerProcesses, } from "./private-local-computer-processes.js";
+import { capturePrivateLocalExecPath, parsePrivateLocalExecPath, } from "./private-local-exec-path.js";
+import { ensurePrivateLocalGitExclude } from "./private-local-git-exclude.js";
+import { createLocalSandboxControls, } from "./private-local-sandbox.js";
+import { localAgentFolderSchema, resolveAgentFolder, } from "./private-local-sandbox-policy.js";
+import { LocalStoreSchemaError } from "./private-local-session-discovery.js";
+import { acquireNodeStoreLease, nodeRuntimeHost, } from "@fungi.computer/shiitake/node";
+import { createPrivateInvocationFilesPort, } from "./private-invocation-files.js";
+import { createLocalSkillSource } from "./local-skill-source.js";
+import { createPrivateWorkerdSandbox } from "./private-workerd-sandbox.js";
+import { createPrivateFungiMcpConnection, } from "./private-fungi-mcp-connection.js";
+import { createPrivateSqliteOwner, openPrivateWritableSqliteDatabase, } from "./private-sqlite-owner.js";
+import { createPrivateLocalMailRoom, hasPrivateLocalPendingMail, } from "./private-local-mail.js";
+import { createPrivateLocalDelegation, } from "./private-local-delegation.js";
+import { createPrivateLocalAgentControl, } from "./private-local-agent-control.js";
+import { subagentsExtension, subagentsGrant, } from "@fungi.computer/shiitake-extensions/subagents/host";
+const initialSessionId = "main";
+const maximumInstructionReadBytes = 128 * 1_024;
+const maximumInstructionSnapshotBytes = 32_000;
+const instructionRevisionVersion = "local-host-instructions-v3";
+const authoredInstructions = "You are the local coding agent. Explain durable changes clearly. After a run fails, each new user message is a new instruction: retry or continue the failed task only when the user explicitly asks, and ask what they want when the message is ambiguous.";
+const utf8 = new TextEncoder();
+const localHostIds = defineIdFamily({
+    family: "local-host",
+    version: 1,
+    kinds: {
+        store: { prefix: "local_store" },
+        "session-create-request": { prefix: "local_session_create_request" },
+    },
+});
+function isErrnoException(error) {
+    return "code" in error;
+}
+function sidecarPathFor(databasePath) {
+    return `${databasePath}.owner.sqlite`;
+}
+function ensureLocalAgentId(database, databasePath, pathAgentId, name, createdBy, folder, requireSandbox) {
+    database.exec("BEGIN IMMEDIATE");
+    try {
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS private_local_identity (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        agent_id TEXT NOT NULL UNIQUE,
+        name TEXT,
+        created_by TEXT,
+        archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1)),
+        folder TEXT NOT NULL DEFAULT '.',
+        require_sandbox INTEGER NOT NULL DEFAULT 0 CHECK (require_sandbox IN (0, 1))
+      )
+    `);
+        const columns = database
+            .prepare("PRAGMA table_info(private_local_identity)")
+            .all();
+        if (!["name", "created_by", "archived", "folder", "require_sandbox"].every((required) => columns.some((column) => column.name === required)))
+            throw new LocalStoreSchemaError(databasePath);
+        const row = database
+            .prepare("SELECT agent_id, created_by, folder FROM private_local_identity WHERE singleton = 1")
+            .get();
+        if (row !== undefined) {
+            const parsed = localHostIds.store.schema.safeParse(row.agent_id);
+            if (!parsed.success ||
+                (pathAgentId !== undefined && parsed.data !== pathAgentId))
+                throw new Error("Local Agent identity does not match its store");
+            if (createdBy !== undefined && row.created_by !== createdBy)
+                throw new Error("Local Agent creation identity conflicts with its store");
+            const storedFolder = localAgentFolderSchema.parse(row.folder);
+            if (folder !== undefined &&
+                localAgentFolderSchema.parse(folder) !== storedFolder)
+                throw new Error("Local Agent folder conflicts with its store");
+            if (requireSandbox !== undefined)
+                database
+                    .prepare("UPDATE private_local_identity SET require_sandbox = ? WHERE singleton = 1")
+                    .run(requireSandbox ? 1 : 0);
+            database.exec("COMMIT");
+            return parsed.data;
+        }
+        const agentId = pathAgentId ?? localHostIds.store.generate();
+        database
+            .prepare("INSERT INTO private_local_identity (singleton, agent_id, name, created_by, folder, require_sandbox) VALUES (1, ?, ?, ?, ?, ?)")
+            // An unnamed Agent gets a Cairn candidate word name so it never shows its id.
+            .run(agentId, name ?? words(), createdBy ?? null, localAgentFolderSchema.parse(folder ?? "."), requireSandbox === true ? 1 : 0);
+        database.exec("COMMIT");
+        return agentId;
+    }
+    catch (cause) {
+        if (database.isTransaction) {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch (rollbackCause) {
+                throw new AggregateError([cause, rollbackCause], "Local transaction and rollback failed", { cause: rollbackCause });
+            }
+        }
+        throw cause;
+    }
+}
+/** Local-owned id for a new Session creation request. */
+export function createPrivateLocalSessionRequestId() {
+    return localHostIds["session-create-request"].generate();
+}
+const localCreateReceiptFile = "local-agent-create-receipts.sqlite";
+const localCreateReceiptTable = "local_agent_create_receipts";
+const maximumReceiptIdAttempts = 3;
+const receiptBusyTimeoutMs = 5_000;
+async function ensurePrivateLocalDirectory(path) {
+    try {
+        await mkdir(path);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error) ||
+            !isErrnoException(cause) ||
+            cause.code !== "EEXIST")
+            throw cause;
+    }
+    const metadata = await lstat(path);
+    const canonical = await realpath(path);
+    if (!metadata.isDirectory() ||
+        metadata.isSymbolicLink() ||
+        canonical !== path)
+        throw new Error("Local Agent create directory is not project owned");
+}
+async function assertPrivateLocalReceiptFile(path, kind) {
+    // A concurrent create's commit deletes the rollback journal at any point
+    // between these reads; a file that is gone has nothing left to check.
+    try {
+        const metadata = await lstat(path);
+        // SQLite can unlink the journal between the kernel's lookup and getattr.
+        // Its now-unlinked regular inode is gone, just as with ENOENT below.
+        if (kind === "journal" && metadata.isFile() && metadata.nlink === 0)
+            return;
+        if (!metadata.isFile() ||
+            metadata.isSymbolicLink() ||
+            metadata.nlink !== 1 ||
+            (await realpath(path)) !== path)
+            throw new Error("Local Agent create receipt is not a unique project file");
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            isErrnoException(cause) &&
+            cause.code === "ENOENT")
+            return;
+        throw cause;
+    }
+}
+/** Resolve an Agent create request through its durable Local receipt. */
+export async function resolvePrivateLocalCreateStore(root, requestId) {
+    if (requestId.length === 0 || requestId.length > 256)
+        throw new Error("Local Agent create request id is invalid");
+    await ensurePrivateLocalGitExclude(root);
+    const fungiDirectory = join(root, ".fungi");
+    const agentsDirectory = join(fungiDirectory, "agents");
+    await ensurePrivateLocalDirectory(fungiDirectory);
+    await ensurePrivateLocalDirectory(agentsDirectory);
+    const receiptPath = join(agentsDirectory, localCreateReceiptFile);
+    await assertPrivateLocalReceiptFile(receiptPath, "receipt");
+    await assertPrivateLocalReceiptFile(`${receiptPath}-journal`, "journal");
+    const database = openPrivateWritableSqliteDatabase(receiptPath, receiptBusyTimeoutMs);
+    try {
+        database.exec(`PRAGMA busy_timeout = ${String(receiptBusyTimeoutMs)}`);
+        database.exec("BEGIN IMMEDIATE");
+        database.exec(`
+      CREATE TABLE IF NOT EXISTS ${localCreateReceiptTable} (
+        request_id TEXT PRIMARY KEY NOT NULL,
+        agent_id TEXT NOT NULL UNIQUE,
+        name TEXT
+      ) WITHOUT ROWID
+    `);
+        const existing = database
+            .prepare(`SELECT agent_id FROM ${localCreateReceiptTable} WHERE request_id = ?`)
+            .get(requestId);
+        if (existing !== undefined) {
+            const parsed = localHostIds.store.schema.safeParse(existing.agent_id);
+            if (!parsed.success)
+                throw new Error("Local Agent create receipt is invalid");
+            const agentId = parsed.data;
+            database.exec("COMMIT");
+            await ensurePrivateLocalDirectory(join(agentsDirectory, agentId));
+            return {
+                agentId,
+                databasePath: join(agentsDirectory, agentId, "agent.sqlite"),
+            };
+        }
+        let agentId;
+        const insert = database.prepare(`INSERT OR IGNORE INTO ${localCreateReceiptTable} (request_id, agent_id) VALUES (?, ?)`);
+        for (let attempt = 0; attempt < maximumReceiptIdAttempts; attempt += 1) {
+            const candidate = localHostIds.store.generate();
+            const candidateDirectory = join(agentsDirectory, candidate);
+            try {
+                // Keep the SQLite write transaction synchronous. Awaiting filesystem
+                // work here lets a concurrent same-process retry block the event loop
+                // in BEGIN IMMEDIATE, preventing this mkdir continuation from running.
+                mkdirSync(candidateDirectory);
+            }
+            catch (cause) {
+                if (cause instanceof Error &&
+                    isErrnoException(cause) &&
+                    cause.code === "EEXIST")
+                    continue;
+                throw cause;
+            }
+            const metadata = lstatSync(candidateDirectory);
+            if (!metadata.isDirectory() ||
+                metadata.isSymbolicLink() ||
+                realpathSync(candidateDirectory) !== candidateDirectory)
+                throw new Error("Local Agent create directory is not project owned");
+            if (insert.run(requestId, candidate).changes > 0) {
+                agentId = candidate;
+                break;
+            }
+        }
+        if (agentId === undefined)
+            throw new Error("Could not allocate a unique Local Agent identity");
+        database.exec("COMMIT");
+        return {
+            agentId,
+            databasePath: join(agentsDirectory, agentId, "agent.sqlite"),
+        };
+    }
+    catch (cause) {
+        if (database.isTransaction) {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch (rollbackCause) {
+                throw new AggregateError([cause, rollbackCause], "Local transaction and rollback failed", { cause: rollbackCause });
+            }
+        }
+        throw cause;
+    }
+    finally {
+        database.close();
+    }
+}
+async function localDatabasePaths(root, requested, createRequestId) {
+    if (requested !== undefined && createRequestId !== undefined)
+        throw new Error("Local Agent database and create request are mutually exclusive");
+    if (requested !== undefined) {
+        const existing = await realpath(resolve(root, requested));
+        const metadata = await stat(existing);
+        if (!metadata.isFile())
+            throw new Error(`Local Agent database is not a file: ${requested}`);
+        const parent = await realpath(dirname(existing));
+        const databasePath = join(parent, basename(existing));
+        const parsedAgentId = localHostIds.store.parse(basename(parent));
+        const agentId = parsedAgentId.ok ? parsedAgentId.value : undefined;
+        return { agentId, databasePath, sidecarPath: sidecarPathFor(databasePath) };
+    }
+    const createStore = createRequestId === undefined
+        ? undefined
+        : await resolvePrivateLocalCreateStore(root, createRequestId);
+    const createDatabasePath = createStore?.databasePath;
+    const generatedAgentId = createStore?.agentId ?? localHostIds.store.generate();
+    const selectedParent = createDatabasePath === undefined
+        ? join(root, ".fungi", "agents", generatedAgentId)
+        : dirname(createDatabasePath);
+    let parent;
+    if (createRequestId === undefined) {
+        await mkdir(selectedParent, { recursive: true });
+        parent = await realpath(selectedParent);
+    }
+    else {
+        for (const path of [
+            join(root, ".fungi"),
+            join(root, ".fungi", "agents"),
+            selectedParent,
+        ]) {
+            try {
+                await mkdir(path);
+            }
+            catch (cause) {
+                if (!(cause instanceof Error) ||
+                    !isErrnoException(cause) ||
+                    cause.code !== "EEXIST")
+                    throw cause;
+            }
+            const metadata = await lstat(path);
+            const canonical = await realpath(path);
+            if (!metadata.isDirectory() ||
+                metadata.isSymbolicLink() ||
+                canonical !== path)
+                throw new Error("Local Agent create directory is not project owned");
+        }
+        parent = await realpath(selectedParent);
+        const withinProject = relative(root, parent);
+        if (isAbsolute(withinProject) ||
+            withinProject === ".." ||
+            withinProject.startsWith("../"))
+            throw new Error("Local Agent create directory is outside this project");
+    }
+    const databasePath = createDatabasePath ?? join(parent, "agent.sqlite");
+    if (createRequestId !== undefined) {
+        for (const path of [databasePath, sidecarPathFor(databasePath)]) {
+            let metadata;
+            try {
+                metadata = await lstat(path);
+            }
+            catch (cause) {
+                if (!(cause instanceof Error) ||
+                    !isErrnoException(cause) ||
+                    cause.code !== "ENOENT")
+                    throw cause;
+                continue;
+            }
+            if (!metadata.isFile() ||
+                metadata.isSymbolicLink() ||
+                metadata.nlink !== 1)
+                throw new Error("Local Agent create store is not a unique project file");
+            if ((await realpath(path)) !== path)
+                throw new Error("Local Agent create store is not a unique project file");
+        }
+    }
+    return {
+        agentId: generatedAgentId,
+        databasePath,
+        sidecarPath: sidecarPathFor(databasePath),
+    };
+}
+function frame(parts) {
+    const total = parts.reduce((size, part) => size + 4 + part.byteLength, 0);
+    const framed = new Uint8Array(total);
+    const view = new DataView(framed.buffer);
+    let offset = 0;
+    for (const part of parts) {
+        view.setUint32(offset, part.byteLength);
+        offset += 4;
+        framed.set(part, offset);
+        offset += part.byteLength;
+    }
+    return framed;
+}
+async function instructionRevision(authored, agents) {
+    const digest = await crypto.subtle.digest("SHA-256", frame([
+        utf8.encode(instructionRevisionVersion),
+        utf8.encode(authored),
+        Uint8Array.of(agents === undefined ? 0 : 1),
+        utf8.encode(agents ?? ""),
+    ]));
+    return `local-instructions-${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+/** Build the fixed source read by Shiitake once for each local run. */
+export function createPrivateLocalInstructionSource(port) {
+    return Object.freeze({
+        load: async ({ sessionId, signal }) => {
+            signal.throwIfAborted();
+            let agents;
+            try {
+                const page = await port.read({ path: "AGENTS.md", offset: 0, limit: maximumInstructionReadBytes }, {
+                    executionId: `local-instructions/${sessionId}`,
+                    deadlineAt: null,
+                    signal,
+                });
+                if ("image" in page)
+                    throw new Error("Root AGENTS.md is an image, not instructions");
+                if (page.truncated)
+                    throw new Error("Root AGENTS.md exceeds the 128 KiB instruction bound");
+                agents = page.content;
+            }
+            catch (cause) {
+                if (cause instanceof Error &&
+                    isErrnoException(cause) &&
+                    cause.code === "ENOENT") {
+                    agents = undefined;
+                }
+                else
+                    throw cause;
+            }
+            signal.throwIfAborted();
+            const text = agents === undefined
+                ? authoredInstructions
+                : `${authoredInstructions}\n\n${agents}`;
+            if (utf8.encode(text).byteLength > maximumInstructionSnapshotBytes)
+                throw new Error(`Local instructions exceed Shiitake's ${String(maximumInstructionSnapshotBytes)}-byte snapshot bound`);
+            return Object.freeze({
+                revision: await instructionRevision(authoredInstructions, agents),
+                text,
+            });
+        },
+    });
+}
+export function createPrivateLocalModelSource(models, providerId, modelId, providerCacheKey, selectedOwnerReasoning, defaults) {
+    const model = modelId === undefined || providerId === undefined
+        ? undefined
+        : models.getModel(providerId, modelId);
+    if (providerId !== undefined && providerId !== "fungi" && model === undefined)
+        throw new ShiitakeError("model", "rejected", `Local model is not registered: ${providerId}/${modelId ?? "select with --model"}`);
+    if (model !== undefined)
+        validateLocalReasoning(model, selectedOwnerReasoning);
+    const ownerReasoning = selectedOwnerReasoning ??
+        (model === undefined ? undefined : defaultLocalReasoning(model));
+    const agentPreference = () => defaults?.agent?.() ??
+        (providerId === undefined
+            ? null
+            : {
+                providerId,
+                modelId: modelId ?? "@fungi/luna",
+            });
+    const prepareSelection = async (preference, signal) => {
+        const startup = await resolveLocalStartupChoice({
+            models,
+            session: preference,
+            agent: agentPreference(),
+            signal,
+        });
+        if (startup === null)
+            throw new ShiitakeError("model", "rejected", "No signed-in model provider is available. Run /login, then choose a model with /model.");
+        const choice = startup.preference;
+        const selectedProvider = choice.providerId;
+        if (selectedProvider === "fungi") {
+            try {
+                assertFungiModelsEnabled();
+            }
+            catch (cause) {
+                throw new ShiitakeError("model", "rejected", "Fungi models are paused. Try again later.", undefined, cause);
+            }
+            await assertAuthenticated("fungi", signal);
+            // Catalog facts choose a model; every stream rechecks live Hub authority.
+            // A failed catalog refresh must not hide a dispatch refusal from the transcript.
+            if (models.getModels("fungi").length === 0) {
+                const result = await models.refresh({ providers: ["fungi"], signal });
+                if (result.aborted)
+                    throw new Error("Fungi model catalog refresh was cancelled");
+                const failure = result.errors.get("fungi");
+                if (failure !== undefined)
+                    throw new ShiitakeError("model", "rejected", "Fungi models are unavailable. Sign in with /login or choose another provider with /model.", undefined, failure);
+            }
+        }
+        const selectedId = choice.modelId;
+        const selected = models.getModel(selectedProvider, selectedId);
+        if (selected === undefined)
+            throw new ShiitakeError("model", "rejected", `Local model is not registered: ${selectedProvider}/${selectedId}`);
+        const reasoning = startupReasoning(selected, choice, ownerReasoning);
+        validateLocalReasoning(selected, reasoning);
+        return { selected, reasoning };
+    };
+    const assertAuthenticated = async (provider, signal) => {
+        const message = `${provider} is not signed in. Run /login or choose another model with /model.`;
+        try {
+            if ((await models.checkAuth(provider, { signal })) === undefined)
+                throw new ShiitakeError("model", "rejected", message);
+            signal.throwIfAborted();
+        }
+        catch (cause) {
+            signal.throwIfAborted();
+            throw new ShiitakeError("model", "rejected", message, undefined, cause);
+        }
+    };
+    return Object.freeze({
+        assertReady: async (preference, signal) => {
+            const { selected } = await prepareSelection(preference, signal);
+            await assertAuthenticated(selected.provider, signal);
+        },
+        effective: async (preference, signal) => {
+            signal.throwIfAborted();
+            let selection;
+            try {
+                selection = await prepareSelection(preference, signal);
+            }
+            catch (cause) {
+                if (signal.aborted ||
+                    (preference?.providerId ?? providerId) !== "fungi")
+                    throw cause;
+                logEvent("fungi-model.status", cause);
+                const source = cause instanceof ShiitakeError
+                    ? cause.message
+                    : "Fungi is unreachable or unavailable. Retry or sign in again.";
+                return privateLocalEffectiveModelSchema.parse({
+                    agentName: "Shiitake",
+                    providerId: "fungi",
+                    providerName: "Fungi",
+                    modelId: preference?.modelId ?? modelId ?? "@fungi/luna",
+                    modelName: "Fungi",
+                    credential: { kind: "missing", source },
+                    label: `Shiitake · Fungi · ${source}`,
+                });
+            }
+            const { selected, reasoning } = selection;
+            const provider = models.getProvider(selected.provider);
+            if (provider === undefined)
+                throw new Error("Local model provider is not registered");
+            const auth = await models.checkAuth(provider.id, { signal });
+            signal.throwIfAborted();
+            const source = auth === undefined
+                ? "Sign in required"
+                : auth.source === undefined || auth.source === "OAuth"
+                    ? auth.type === "oauth"
+                        ? `${provider.name} login`
+                        : "API key"
+                    : auth.source;
+            return privateLocalEffectiveModelSchema.parse({
+                agentName: "Shiitake",
+                providerId: provider.id,
+                providerName: provider.name,
+                modelId: selected.id,
+                modelName: selected.name,
+                credential: { kind: auth?.type ?? "missing", source },
+                reasoning,
+                label: `Shiitake · ${selected.name} (${reasoning ?? "no reasoning"}) · ${source}`,
+            });
+        },
+        // Observe the same explicit layers against last-known registry facts.
+        // Catalog presence alone cannot identify the signed-in fallback: Pi's
+        // availability queries check auth. Leave that choice unknown here.
+        describe: ({ signal, preference }) => {
+            signal.throwIfAborted();
+            const choice = resolveKnownLocalStartupChoice({
+                session: preference,
+                agent: agentPreference(),
+            });
+            const selected = choice === null
+                ? undefined
+                : models.getModel(choice.preference.providerId, choice.preference.modelId);
+            const contextWindow = selected?.contextWindow;
+            return Promise.resolve({
+                contextWindow: contextWindow !== undefined && contextWindow > 0
+                    ? contextWindow
+                    : null,
+            });
+        },
+        acquire: async ({ signal, preference }) => {
+            signal.throwIfAborted();
+            const { selected, reasoning: selectedReasoning } = await prepareSelection(preference, signal);
+            await assertAuthenticated(selected.provider, signal);
+            const turn = await acquireSubscriptionTurn(models, selected.provider, signal);
+            // One acquired door owns at most its latest failure. Identity ties the
+            // description to the exact returned message, not to a provider name or
+            // prose that any SDK can supply.
+            let modelFailure;
+            return Promise.resolve(Object.freeze({
+                model: selected,
+                retryable: (message) => !signal.aborted &&
+                    message.stopReason === "error" &&
+                    modelFailure?.message === message &&
+                    modelFailure.retryable,
+                failureReason: (message) => modelFailure?.message === message ? modelFailure.reason : undefined,
+                stream: (selected, context, options) => {
+                    modelFailure = undefined;
+                    const streamOptions = { ...options };
+                    const reasoning = options?.reasoning ?? selectedReasoning;
+                    if (reasoning !== undefined)
+                        streamOptions.reasoning = reasoning;
+                    const provider = observeProviderStatus(streamOptions);
+                    const events = createAssistantMessageEventStream();
+                    const failure = (usage, aborted, upstream) => {
+                        const evidence = {
+                            refusal: turn.refusal(),
+                            upstream,
+                            rejection: provider.rejection(),
+                        };
+                        const message = modelFailureMessage(selected.provider, evidence);
+                        const result = {
+                            role: "assistant",
+                            content: [],
+                            api: selected.api,
+                            provider: selected.provider,
+                            model: selected.id,
+                            usage,
+                            stopReason: aborted ? "aborted" : "error",
+                            timestamp: Date.now(),
+                            errorMessage: aborted ? "Run cancelled" : message,
+                        };
+                        if (!aborted)
+                            modelFailure = {
+                                message: result,
+                                reason: message,
+                                retryable: modelFailureRetryable(evidence),
+                            };
+                        return result;
+                    };
+                    void (async () => {
+                        try {
+                            const upstream = turn.models.streamSimple(selected, context, {
+                                ...streamOptions,
+                                fetch: provider.fetch,
+                                onProviderStreamEvent: provider.onProviderStreamEvent,
+                                sessionId: providerCacheKey,
+                                transport: options?.transport ?? "auto",
+                            });
+                            for await (const event of upstream) {
+                                if (event.type === "error") {
+                                    const error = failure(event.error.usage, event.reason === "aborted", event.error);
+                                    events.push({ ...event, error });
+                                    events.end(error);
+                                    return;
+                                }
+                                events.push(event);
+                            }
+                            events.end(await upstream.result());
+                        }
+                        catch {
+                            const aborted = (options?.signal ?? signal).aborted;
+                            const error = failure({
+                                input: 0,
+                                output: 0,
+                                cacheRead: 0,
+                                cacheWrite: 0,
+                                totalTokens: 0,
+                                cost: {
+                                    input: 0,
+                                    output: 0,
+                                    cacheRead: 0,
+                                    cacheWrite: 0,
+                                    total: 0,
+                                },
+                            }, aborted);
+                            events.push({
+                                type: "error",
+                                reason: aborted ? "aborted" : "error",
+                                error,
+                            });
+                            events.end(error);
+                        }
+                    })();
+                    return events;
+                },
+                release: turn.release,
+            }));
+        },
+    });
+}
+/** One local Computer source, resolving its PATH and process scope per Session. */
+function createPrivateLocalComputerSource(root, port, sessionPath, processes, home, sandbox) {
+    const id = "local-computer";
+    return {
+        id,
+        acquire: async (context) => {
+            const sessionId = context.session?.sessionId;
+            if (sessionId === undefined)
+                throw new Error("Local Computer requires a Session");
+            const path = sessionPath(sessionId) ??
+                capturePrivateLocalExecPath(process.env.PATH ?? "/usr/bin:/bin", process.cwd());
+            const selected = await createPrivateInvocationComputer(root, path, processes.scope(sessionId), home, sandbox);
+            return Knapsack.computer({
+                id,
+                name: "local",
+                namespace: ["computers"],
+                files: {
+                    port,
+                    pathInstructions: localPathInstructions(root),
+                },
+                computer: selected,
+            }).acquire(context);
+        },
+    };
+}
+function localPathInstructions(root) {
+    return `Files root: ${root}. Relative paths resolve from this root; absolute paths must remain inside it.`;
+}
+/** Assemble the existing Files, Computer, and workerd owners once per host. */
+export async function createPrivateLocalTools(invocationRoot, fungiMcp, agentControl, sessionPath, 
+/** This Agent's store; its owner-enabled installed extensions join the roster. */
+storeDirectory, 
+/**
+ * This Agent's sub-agent record: its Session-bound Agent-control tools and
+ * the view's facts. Present when it can direct other Agents.
+ */
+subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox) {
+    const forms = createMcpFormSession();
+    const root = await realpath(resolve(invocationRoot));
+    const port = await createPrivateInvocationFilesPort(root, undefined, sandbox);
+    const processes = createPrivateLocalComputerProcesses(root, configRoot.home);
+    const computerSources = sessionPath === undefined
+        ? [
+            Knapsack.computer({
+                id: "local-computer",
+                name: "local",
+                namespace: ["computers"],
+                files: {
+                    port,
+                    pathInstructions: localPathInstructions(root),
+                },
+                computer: await createPrivateInvocationComputer(root, undefined, processes.scope("invocation"), configRoot.home, sandbox?.launch),
+            }),
+        ]
+        : [
+            createPrivateLocalComputerSource(root, port, sessionPath, processes, configRoot.home, sandbox?.launch),
+        ];
+    const installed = configuration?.installed ??
+        (storeDirectory === undefined
+            ? { roster: [], grants: [], skills: [], diagnostics: [] }
+            : await localExtensions({ home: configRoot.home }).agent(storeDirectory, root));
+    function configure(installed, connection, clientPath) {
+        const base = botanicalExtensionsWithSkills(createLocalSkillSource({
+            cwd: root,
+            home: configRoot.home,
+            extensions: installed.skills,
+        }));
+        for (const diagnostic of installed.diagnostics)
+            logEvent("local-extension-load", diagnostic.error);
+        const archive = storeDirectory === undefined
+            ? { roster: [], grants: [] }
+            : localArchiveHandoff(storeDirectory, installed.grants);
+        const extensions = {
+            roster: [
+                ...base.roster,
+                forms.extension,
+                homeExtension({
+                    computers: {
+                        read: () => [
+                            { name: "local", attachmentId: "local-computer", port },
+                        ],
+                    },
+                }),
+                ...(subagents === undefined
+                    ? []
+                    : [subagentsExtension({ source: subagents.source })]),
+                ...archive.roster,
+                ...installed.roster,
+            ],
+            grants: [
+                ...base.grants,
+                {
+                    id: forms.extension.manifest.id,
+                    capabilities: forms.extension.manifest.requests,
+                },
+                homeGrant,
+                ...(subagents === undefined ? [] : [subagentsGrant]),
+                ...archive.grants,
+                ...installed.grants,
+            ],
+        };
+        return Object.freeze({
+            extensions,
+            tools: Object.freeze({
+                execution: Object.freeze({ timeoutMs: 900_000 }),
+                sources: Object.freeze([
+                    ...(agentControl === undefined
+                        ? []
+                        : [subagents?.control ?? createAgentControlSource(agentControl)]),
+                    ...(clientPath === undefined
+                        ? computerSources
+                        : [
+                            createPrivateLocalComputerSource(root, port, () => clientPath, processes, configRoot.home, sandbox?.launch),
+                        ]),
+                    ...(connection === undefined
+                        ? []
+                        : [createPrivateFungiMcpConnection(connection)]),
+                ]),
+                sandbox: createPrivateWorkerdSandbox(),
+            }),
+        });
+    }
+    const initial = configure(installed, configuration === undefined ? fungiMcp : configuration.fungiMcp, configuration?.clientPath);
+    if (initial.tools === undefined)
+        throw new Error("Local tools are unavailable");
+    return {
+        ...initial,
+        tools: initial.tools,
+        port,
+        processes,
+        configure,
+        bindSession: forms.bindSession,
+        presentApproval: forms.presentApproval,
+    };
+}
+function localRuntimeOwner() {
+    const host = nodeRuntimeHost((cause) => {
+        logEvent("shiitake_reconciliation_failed", cause);
+    });
+    let pendingWork;
+    return Object.freeze({
+        ...host,
+        runtime: Object.freeze({
+            bind: (input) => {
+                pendingWork = input.pendingWork;
+                return host.runtime.bind(input);
+            },
+        }),
+        settled: async () => {
+            if (pendingWork === undefined)
+                return false;
+            const work = await pendingWork();
+            return !work.pending && work.nextWakeAt === null;
+        },
+    });
+}
+/** Event-loop adaptation for the one local Shiitake owner; it has no queue policy. */
+export function createPrivateLocalRuntimeHost() {
+    return localRuntimeOwner().runtime;
+}
+function asLocalFailure(cause, message) {
+    return cause instanceof Error ? cause : new Error(message, { cause });
+}
+function aggregateLocalFailures(failures, message) {
+    if (failures.length === 1) {
+        const [failure] = failures;
+        if (failure === undefined)
+            throw new Error("Missing local close failure");
+        return failure;
+    }
+    return new AggregateError(failures, message);
+}
+async function captureCloseFailure(close, message) {
+    try {
+        await close();
+        return undefined;
+    }
+    catch (cause) {
+        return asLocalFailure(cause, message);
+    }
+}
+/**
+ * Close the fixed local owner in dependency order without surrendering its
+ * sidecar before runtime drain and main-database close have succeeded.
+ *
+ * This source-local seam is intentionally not re-exported by the package; the
+ * focused tests use it to falsify injected failure ordering.
+ */
+export async function closePrivateLocalResources(resources, initiatingFailure) {
+    const failures = initiatingFailure === undefined ? [] : [initiatingFailure];
+    if (resources.agent !== undefined) {
+        const failure = await captureCloseFailure(resources.agent.close, "Local Agent close failed");
+        if (failure !== undefined)
+            failures.push(failure);
+    }
+    // No tool call runs after the Agent closed: stop its background processes.
+    if (resources.processes !== undefined) {
+        const failure = await captureCloseFailure(resources.processes.close, "Local Computer processes close failed");
+        if (failure !== undefined)
+            failures.push(failure);
+    }
+    if (resources.sandbox !== undefined) {
+        const failure = await captureCloseFailure(() => Promise.resolve().then(() => resources.sandbox?.close()), "Local sandbox close failed");
+        if (failure !== undefined)
+            failures.push(failure);
+    }
+    const runtimeFailure = await captureCloseFailure(resources.runtime.close, "Local runtime close failed");
+    if (runtimeFailure !== undefined) {
+        failures.push(runtimeFailure);
+        throw aggregateLocalFailures(failures, "Local host close failed");
+    }
+    const providerCacheKey = resources.providerCacheKey;
+    if (providerCacheKey !== undefined) {
+        const modelFailure = await captureCloseFailure(() => Promise.resolve().then(() => {
+            cleanupSessionResources(providerCacheKey);
+        }), "Local provider resources close failed");
+        if (modelFailure !== undefined)
+            failures.push(modelFailure);
+    }
+    if (resources.database !== undefined) {
+        const databaseFailure = await captureCloseFailure(() => Promise.resolve().then(() => resources.database?.close()), "Local Agent database close failed");
+        if (databaseFailure !== undefined) {
+            failures.push(databaseFailure);
+            throw aggregateLocalFailures(failures, "Local host close failed");
+        }
+    }
+    if (resources.lease !== undefined) {
+        const leaseFailure = await captureCloseFailure(() => Promise.resolve().then(() => resources.lease?.release()), "Local ownership sidecar release failed");
+        if (leaseFailure !== undefined)
+            failures.push(leaseFailure);
+    }
+    if (failures.length > 0)
+        throw aggregateLocalFailures(failures, "Local host close failed");
+}
+/** Adapt Core's store refusal without reclassifying other opening failures. */
+function localHostOpeningFailure(cause, databasePath) {
+    if (cause instanceof ShiitakeError &&
+        cause.boundary === "store" &&
+        cause.cause === "incompatible")
+        return new LocalStoreSchemaError(databasePath, { cause });
+    return asLocalFailure(cause, "Local host opening failed");
+}
+/**
+ * Open one private file-backed local Shiitake host and its fixed Session.
+ *
+ * The returned close owns agent, main database, and sidecar release in that
+ * order. It is the only lifecycle the current terminal caller needs to learn.
+ */
+export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
+    const configRoot = input.configRoot ?? capturePrivateLocalConfigRoot();
+    const models = suppliedModels ?? createPrivateModels(configRoot.credentialPath);
+    const root = await realpath(resolve(input.invocationRoot));
+    await ensurePrivateLocalGitExclude(root);
+    const selectedProviderId = input.providerId;
+    const selectedModelId = input.modelId;
+    if (selectedProviderId !== undefined && selectedProviderId !== "fungi") {
+        const model = selectedModelId === undefined
+            ? undefined
+            : models.getModel(selectedProviderId, selectedModelId);
+        if (model === undefined)
+            throw new ShiitakeError("model", "rejected", `Local model is not registered: ${selectedProviderId}/${selectedModelId ?? "select with --model"}`);
+        validateLocalReasoning(model, input.reasoning);
+    }
+    const paths = await localDatabasePaths(root, input.databasePath, input.createRequestId);
+    const runtime = localRuntimeOwner();
+    let lease;
+    let providerCacheKey;
+    let database;
+    let agent;
+    let processes;
+    let sandbox;
+    const sessionPaths = new Map();
+    let usesServiceConfiguration = input.configuration !== undefined;
+    try {
+        lease = acquireNodeStoreLease(paths.sidecarPath);
+        // Claim only after the lease: a rejected opener must not clean up its live owner.
+        providerCacheKey = createHash("sha256")
+            .update(JSON.stringify(["fungi-local", paths.databasePath, initialSessionId]))
+            .digest("hex");
+        database = openPrivateWritableSqliteDatabase(paths.databasePath, 0);
+        database.exec("PRAGMA foreign_keys = ON");
+        const agentId = ensureLocalAgentId(database, paths.databasePath, paths.agentId, input.name, input.createdBy, input.folder, input.requireSandbox);
+        const sandboxDatabase = database;
+        const readSandboxRequirement = () => z
+            .union([z.literal(0), z.literal(1)])
+            .parse(sandboxDatabase
+            .prepare("SELECT require_sandbox FROM private_local_identity WHERE singleton = 1")
+            .get()?.require_sandbox) === 1;
+        const selectedFolder = resolveAgentFolder(root, localAgentFolderSchema.parse(database
+            .prepare("SELECT folder FROM private_local_identity WHERE singleton = 1")
+            .get()?.folder));
+        const sandboxOwner = createLocalSandboxControls({
+            project: root,
+            folder: selectedFolder.folder,
+            required: readSandboxRequirement,
+        });
+        sandbox = sandboxOwner;
+        // Both constructors below can resume stored commands before returning.
+        // Admission must precede tools, configuration hooks and Agent construction.
+        const name = z
+            .string()
+            .nullable()
+            .parse(database
+            .prepare("SELECT name FROM private_local_identity WHERE singleton = 1")
+            .get()?.name) ?? agentId;
+        const modelDatabase = database;
+        ensureAgentDefaultModelTable(modelDatabase);
+        let initialModel = selectedProviderId === undefined || selectedModelId === undefined
+            ? null
+            : parseModelPreference({
+                providerId: selectedProviderId,
+                modelId: selectedModelId,
+            });
+        if (initialModel !== null && input.reasoning !== undefined)
+            initialModel = parseModelPreference({
+                ...initialModel,
+                reasoning: input.reasoning,
+            });
+        seedAgentDefaultModel(modelDatabase, initialModel);
+        const readAgentModel = () => readAgentDefaultModel(modelDatabase);
+        const store = createPrivateSqliteOwner(database);
+        let acceptMail;
+        let readSettlement;
+        if (input.mail !== undefined && input.agentControl === undefined)
+            throw new Error("Local delegation requires the project Agent directory");
+        const delegation = input.mail === undefined || input.agentControl === undefined
+            ? undefined
+            : createPrivateLocalDelegation({
+                agentId,
+                storage: store,
+                directory: input.agentControl,
+                routing: input.mail,
+                meshAdmission: input.meshAdmission === undefined
+                    ? undefined
+                    : async (recipientAgentId) => input.meshAdmission?.(agentId, recipientAgentId),
+                accept: (mail, meta, reply) => {
+                    if (acceptMail === undefined)
+                        return Promise.reject(new Error("Local mail ingress is unavailable"));
+                    return acceptMail(mail, meta, reply);
+                },
+            });
+        let projectDirectory;
+        if (input.agentControl !== undefined) {
+            projectDirectory = {
+                ...input.agentControl,
+                models: (signal) => listOfferedLocalModels(models, signal),
+            };
+            if (delegation !== undefined)
+                projectDirectory = {
+                    ...projectDirectory,
+                    send: delegation.send,
+                    recall: delegation.recall,
+                };
+        }
+        const subagents = projectDirectory === undefined
+            ? undefined
+            : createPrivateLocalAgentControl({
+                agentId,
+                directory: projectDirectory,
+                storage: store,
+            });
+        const localTools = await createPrivateLocalTools(selectedFolder.absolute, input.fungiMcp, subagents?.directory, (sessionId) => sessionPaths.get(sessionId), dirname(paths.databasePath), subagents, await input.configuration?.(dirname(paths.databasePath)), configRoot, sandboxOwner);
+        processes = localTools.processes;
+        const sessionProcesses = processes;
+        const modelSource = createPrivateLocalModelSource(models, selectedProviderId, selectedModelId, providerCacheKey, input.reasoning, { agent: readAgentModel });
+        const hostOptions = {
+            store,
+            runtime: runtime.runtime,
+            extensions: localTools.extensions,
+            model: modelSource,
+            instructions: createPrivateLocalInstructionSource(localTools.port),
+            tools: localTools.tools,
+        };
+        if (input.mail === undefined) {
+            agent = await Shiitake.make(hostOptions);
+        }
+        else {
+            const mailRoom = createPrivateLocalMailRoom(database, {
+                deliver: input.mail.deliver,
+                scheduleWake: runtime.scheduleWake,
+            });
+            const host = await makeHost(hostOptions, mailRoom);
+            agent = host.agent;
+            acceptMail = host.acceptMail;
+            readSettlement = host.readSettlement;
+        }
+        const sessionOwner = agent;
+        const setAgentModel = async (input, signal) => {
+            const preference = parseModelPreference(input);
+            if (preference === null)
+                throw new ShiitakeError("model", "invalid", "An Agent model is required");
+            await modelSource.assertReady(preference, signal);
+            signal.throwIfAborted();
+            writeAgentDefaultModel(modelDatabase, preference);
+        };
+        // /model in a chat sets this Agent's default and its thinking level; a
+        // Session override is cleared so the running Session follows the default.
+        const getSession = (sessionId, attachment) => {
+            const session = localTools.bindSession(sessionId, sessionOwner.session(sessionId), attachment);
+            return {
+                ...session,
+                modelPreference: {
+                    read: async () => (await session.modelPreference.read()) ?? readAgentModel(),
+                    set: async (input) => {
+                        const preference = parseModelPreference(input);
+                        if (preference !== null)
+                            await setAgentModel(preference, new AbortController().signal);
+                        await session.modelPreference.set(null);
+                    },
+                },
+            };
+        };
+        const session = getSession(initialSessionId);
+        let closing;
+        return Object.freeze({
+            agentId,
+            name,
+            databasePath: paths.databasePath,
+            session,
+            getSession,
+            presentApproval: localTools.presentApproval,
+            setModel: setAgentModel,
+            setRequireSandbox: (required) => {
+                sandboxDatabase
+                    .prepare("UPDATE private_local_identity SET require_sandbox = ? WHERE singleton = 1")
+                    .run(required ? 1 : 0);
+                sandboxOwner.assertReady();
+            },
+            sandboxStatus: sandboxOwner.status,
+            setArchived: (archived) => {
+                modelDatabase
+                    .prepare("UPDATE private_local_identity SET archived = ? WHERE singleton = 1")
+                    .run(archived ? 1 : 0);
+            },
+            assertModelReady: async (sessionId, signal) => {
+                const preference = await sessionOwner
+                    .session(sessionId)
+                    .modelPreference.read();
+                await modelSource.assertReady(preference, signal);
+            },
+            bindSessionPath: (sessionId, path) => {
+                const selected = parsePrivateLocalExecPath(path);
+                if (usesServiceConfiguration)
+                    return true;
+                const previous = sessionPaths.get(sessionId);
+                if (previous !== undefined && previous !== selected)
+                    return false;
+                sessionPaths.set(sessionId, selected);
+                return true;
+            },
+            effectiveModel: async (sessionId, signal) => {
+                signal.throwIfAborted();
+                const preference = await sessionOwner
+                    .session(sessionId)
+                    .modelPreference.read();
+                return modelSource.effective(preference, signal);
+            },
+            listSessions: (after) => sessionOwner.listSessions(after),
+            createSession: (requestId) => sessionOwner.createSession(requestId),
+            deleteSession: async (sessionId) => {
+                const deleted = await sessionOwner.deleteSession(sessionId);
+                // The Session ended: its background processes and logs go with it.
+                await sessionProcesses.disposeScope(sessionId);
+                return deleted;
+            },
+            extensions: sessionOwner.extensions,
+            prepareReload: async (configuration) => {
+                const prepared = await sessionOwner.prepareConfiguration(localTools.configure(configuration.installed, configuration.fungiMcp, configuration.clientPath));
+                return {
+                    discard: prepared.discard,
+                    commit: () => {
+                        prepared.commit();
+                        usesServiceConfiguration = true;
+                    },
+                };
+            },
+            acceptMail: (mail) => delegation === undefined
+                ? Promise.reject(new Error("Local mail ingress is unavailable"))
+                : delegation.receive(mail),
+            pendingDelegation: () => delegation === undefined
+                ? Promise.resolve(undefined)
+                : delegation.outstanding(),
+            readSettlement: (sessionId, commandId) => readSettlement === undefined
+                ? Promise.reject(new Error("Local settlement reads are unavailable"))
+                : readSettlement(sessionId, commandId),
+            idle: async () => {
+                if (sessionProcesses.running())
+                    return false;
+                if (!(await runtime.settled()))
+                    return false;
+                // Delegated work still owed to this Agent is not read here: that read
+                // reopens each child, and the child's reply mail reopens this Agent.
+                let after;
+                do {
+                    const page = await sessionOwner.listSessions(after);
+                    for (const row of page.sessions)
+                        if (row.state === "running" || row.state === "needs_you")
+                            return false;
+                    after = page.next;
+                } while (after !== undefined);
+                // Reconciliation enqueues replies before advancing its settled cursor.
+                // Observe mail last: an earlier empty outbox can become retryable mail
+                // while we await settlement or Session reads, especially during stop
+                // when delivery cannot reopen a parent. The owner rechecks admissions
+                // and uses after this observation before forgetting the Agent.
+                return (input.mail === undefined ||
+                    !(await hasPrivateLocalPendingMail(modelDatabase)));
+            },
+            close: () => {
+                closing ??= closePrivateLocalResources({
+                    agent,
+                    processes,
+                    sandbox,
+                    runtime,
+                    database,
+                    lease,
+                    providerCacheKey,
+                });
+                return closing;
+            },
+        });
+    }
+    catch (cause) {
+        const openingFailure = localHostOpeningFailure(cause, paths.databasePath);
+        await closePrivateLocalResources({ agent, processes, sandbox, runtime, database, lease, providerCacheKey }, openingFailure);
+        throw openingFailure;
+    }
+}