@fungi.computer/truffle 0.1.1 → 0.2.0

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

@@ -1,45 +1,54 @@
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai/utils/event-stream";
-import { isContextOverflow } from "@earendil-works/pi-ai/utils/overflow";
-import { isRetryableAssistantError } from "@earendil-works/pi-ai/utils/retry";
+import { observeProviderStatus } from "@fungi.computer/mule";
+import { modelFailureMessage, modelFailureRetryable, } from "./private-provider-rejection.js";
 import { logEvent } from "./log-event.js";
-import { localExtensions } from "./local-extensions.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 { DatabaseSync } from "node:sqlite";
 import { createHash } from "node:crypto";
-import { cleanupSessionResources, clampThinkingLevel, getSupportedThinkingLevels, } from "@earendil-works/pi-ai";
-import { parseModelPreference, parseModelPreferenceJson, resolveModelPreference, } from "@fungi.computer/shiitake/model-preference";
+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 { defaultLocalModel, listOfferedLocalModels, } from "./private-local-default-model.js";
-import { createLocalModelSettings } from "./private-local-model-settings.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 { 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 { 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 } from "./private-sqlite-owner.js";
-import { createPrivateLocalMailRoom } from "./private-local-mail.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 { createPrivateLocalSubagents } from "./private-local-subagents.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-v2";
-const authoredInstructions = "You are the local coding agent. Explain durable changes clearly. Discover available operations through forage.search and inspect their input with forage.describe; call only the exact paths they return. Extension prompt sections describe the Session's tools and controls. After a run fails, each new user message is a new instruction. Retry or continue the previous task only when the user explicitly asks; if the new message is ambiguous, ask what they want before acting.";
+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",
@@ -55,30 +64,51 @@ function isErrnoException(error) {
 function sidecarPathFor(databasePath) {
     return `${databasePath}.owner.sqlite`;
 }
-function ensureLocalAgentId(database, pathAgentId) {
+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
+        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 FROM private_local_identity WHERE singleton = 1")
+            .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) VALUES (1, ?)")
-            .run(agentId);
+            .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;
     }
@@ -119,11 +149,15 @@ async function ensurePrivateLocalDirectory(path) {
         canonical !== path)
         throw new Error("Local Agent create directory is not project owned");
 }
-async function assertPrivateLocalReceiptFile(path) {
+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 ||
@@ -148,18 +182,17 @@ export async function resolvePrivateLocalCreateStore(root, requestId) {
     await ensurePrivateLocalDirectory(fungiDirectory);
     await ensurePrivateLocalDirectory(agentsDirectory);
     const receiptPath = join(agentsDirectory, localCreateReceiptFile);
-    await assertPrivateLocalReceiptFile(receiptPath);
-    await assertPrivateLocalReceiptFile(`${receiptPath}-journal`);
-    const database = new DatabaseSync(receiptPath, {
-        timeout: receiptBusyTimeoutMs,
-    });
+    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
+        agent_id TEXT NOT NULL UNIQUE,
+        name TEXT
       ) WITHOUT ROWID
     `);
         const existing = database
@@ -346,6 +379,8 @@ export function createPrivateLocalInstructionSource(port) {
                     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;
@@ -372,26 +407,6 @@ export function createPrivateLocalInstructionSource(port) {
         },
     });
 }
-/** Validate the selected registered model before resolving credentials. */
-function validateLocalReasoning(model, requested) {
-    if (requested === undefined)
-        return;
-    const supported = getSupportedThinkingLevels(model).filter((level) => level !== "off");
-    if (!supported.includes(requested))
-        throw new Error("Reasoning level " +
-            requested +
-            " is not supported by " +
-            model.provider +
-            "/" +
-            model.id +
-            "; supported levels: " +
-            (supported.join(", ") || "none"));
-}
-/** Local's default is medium, clamped through Pi's model capabilities. */
-function defaultLocalReasoning(model) {
-    const level = clampThinkingLevel(model, "medium");
-    return level === "off" ? undefined : level;
-}
 export function createPrivateLocalModelSource(models, providerId, modelId, providerCacheKey, selectedOwnerReasoning, defaults) {
     const model = modelId === undefined || providerId === undefined
         ? undefined
@@ -402,25 +417,23 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
         validateLocalReasoning(model, selectedOwnerReasoning);
     const ownerReasoning = selectedOwnerReasoning ??
         (model === undefined ? undefined : defaultLocalReasoning(model));
-    const select = async (preference, signal) => {
-        const agent = defaults?.agent?.() ??
-            (providerId === undefined
-                ? null
-                : {
-                    providerId,
-                    modelId: modelId ?? "@fungi/luna",
-                });
-        const explicit = resolveModelPreference({
+    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,
-            manual: preference === null && agent === null ? await defaults?.manual() : null,
+            agent: agentPreference(),
+            signal,
         });
-        const choice = resolveModelPreference({
-            session: explicit,
-            available: explicit === null ? await defaultLocalModel(models, signal) : null,
-        });
-        if (choice === null)
+        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 {
@@ -445,11 +458,7 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
         const selected = models.getModel(selectedProvider, selectedId);
         if (selected === undefined)
             throw new ShiitakeError("model", "rejected", `Local model is not registered: ${selectedProvider}/${selectedId}`);
-        const reasoning = choice.reasoning ??
-            (ownerReasoning !== undefined &&
-                getSupportedThinkingLevels(selected).includes(ownerReasoning)
-                ? ownerReasoning
-                : defaultLocalReasoning(selected));
+        const reasoning = startupReasoning(selected, choice, ownerReasoning);
         validateLocalReasoning(selected, reasoning);
         return { selected, reasoning };
     };
@@ -467,14 +476,14 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
     };
     return Object.freeze({
         assertReady: async (preference, signal) => {
-            const { selected } = await select(preference, signal);
+            const { selected } = await prepareSelection(preference, signal);
             await assertAuthenticated(selected.provider, signal);
         },
         effective: async (preference, signal) => {
             signal.throwIfAborted();
             let selection;
             try {
-                selection = await select(preference, signal);
+                selection = await prepareSelection(preference, signal);
             }
             catch (cause) {
                 if (signal.aborted ||
@@ -514,38 +523,61 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
                 modelId: selected.id,
                 modelName: selected.name,
                 credential: { kind: auth?.type ?? "missing", source },
+                reasoning,
                 label: `Shiitake · ${selected.name} (${reasoning ?? "no reasoning"}) · ${source}`,
             });
         },
-        // The window comes from the same registry entry a run would acquire.
-        describe: async ({ signal, preference }) => {
+        // 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 { selected } = await select(preference, signal);
-            return {
-                contextWindow: selected.contextWindow > 0 ? selected.contextWindow : null,
-            };
+            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 select(preference, signal);
+            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) => {
-                        let message = `${selected.provider} rejected the model request. Check /login or choose another model with /model.`;
-                        if (upstream !== undefined) {
-                            if (isContextOverflow(upstream))
-                                message = `${selected.provider} request exceeds the context window. Compact the Session or choose another model.`;
-                            else if (isRetryableAssistantError(upstream))
-                                message = `${selected.provider} service unavailable. Try again shortly.`;
-                        }
-                        return {
+                        const evidence = {
+                            refusal: turn.refusal(),
+                            upstream,
+                            rejection: provider.rejection(),
+                        };
+                        const message = modelFailureMessage(selected.provider, evidence);
+                        const result = {
                             role: "assistant",
                             content: [],
                             api: selected.api,
@@ -556,11 +588,20 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
                             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 = models.streamSimple(selected, context, {
+                            const upstream = turn.models.streamSimple(selected, context, {
                                 ...streamOptions,
+                                fetch: provider.fetch,
+                                onProviderStreamEvent: provider.onProviderStreamEvent,
                                 sessionId: providerCacheKey,
                                 transport: options?.transport ?? "auto",
                             });
@@ -601,13 +642,13 @@ export function createPrivateLocalModelSource(models, providerId, modelId, provi
                     })();
                     return events;
                 },
-                release: () => Promise.resolve(),
+                release: turn.release,
             }));
         },
     });
 }
 /** One local Computer source, resolving its PATH and process scope per Session. */
-function createPrivateLocalComputerSource(root, port, sessionPath, processes) {
+function createPrivateLocalComputerSource(root, port, sessionPath, processes, home, sandbox) {
     const id = "local-computer";
     return {
         id,
@@ -617,7 +658,7 @@ function createPrivateLocalComputerSource(root, port, sessionPath, processes) {
                 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));
+            const selected = await createPrivateInvocationComputer(root, path, processes.scope(sessionId), home, sandbox);
             return Knapsack.computer({
                 id,
                 name: "local",
@@ -642,10 +683,11 @@ 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) {
+subagents, configuration, configRoot = capturePrivateLocalConfigRoot(), sandbox) {
+    const forms = createMcpFormSession();
     const root = await realpath(resolve(invocationRoot));
-    const port = await createPrivateInvocationFilesPort(root);
-    const processes = createPrivateLocalComputerProcesses(root);
+    const port = await createPrivateInvocationFilesPort(root, undefined, sandbox);
+    const processes = createPrivateLocalComputerProcesses(root, configRoot.home);
     const computerSources = sessionPath === undefined
         ? [
             Knapsack.computer({
@@ -656,60 +698,110 @@ subagents) {
                     port,
                     pathInstructions: localPathInstructions(root),
                 },
-                computer: await createPrivateInvocationComputer(root, undefined, processes.scope("invocation")),
+                computer: await createPrivateInvocationComputer(root, undefined, processes.scope("invocation"), configRoot.home, sandbox?.launch),
             }),
         ]
-        : [createPrivateLocalComputerSource(root, port, sessionPath, processes)];
-    const base = botanicalExtensionsWithSkills(createLocalSkillSource({ cwd: root }));
-    const installed = storeDirectory === undefined
-        ? { roster: [], grants: [], diagnostics: [] }
-        : await localExtensions().agent(storeDirectory, root);
-    for (const diagnostic of installed.diagnostics)
-        logEvent("local-extension-load", diagnostic.error);
-    const extensions = {
-        roster: [
-            ...base.roster,
-            homeExtension({
-                computers: {
-                    read: () => [{ name: "local", attachmentId: "local-computer", port }],
+        : [
+            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(),
             }),
-            ...(subagents === undefined
-                ? []
-                : [subagentsExtension({ source: subagents.source })]),
-            ...installed.roster,
-        ],
-        grants: [
-            ...base.grants,
-            homeGrant,
-            ...(subagents === undefined ? [] : [subagentsGrant]),
-            ...installed.grants,
-        ],
-    };
-    return Object.freeze({
+        });
+    }
+    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,
-        extensions,
         processes,
-        tools: Object.freeze({
-            execution: Object.freeze({ timeoutMs: 900_000 }),
-            sources: Object.freeze([
-                ...(agentControl === undefined
-                    ? []
-                    : [subagents?.control ?? createAgentControlSource(agentControl)]),
-                ...computerSources,
-                ...(fungiMcp === undefined
-                    ? []
-                    : [createPrivateFungiMcpConnection(fungiMcp)]),
-            ]),
-            sandbox: createPrivateWorkerdSandbox(),
-        }),
-    });
+        configure,
+        bindSession: forms.bindSession,
+        presentApproval: forms.presentApproval,
+    };
 }
-/** Shiitake's public Node runtime host, reporting failed passes to local logs. */
 function localRuntimeOwner() {
-    return nodeRuntimeHost((cause) => {
+    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() {
@@ -756,6 +848,11 @@ export async function closePrivateLocalResources(resources, initiatingFailure) {
         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);
@@ -784,13 +881,23 @@ export async function closePrivateLocalResources(resources, initiatingFailure) {
     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, models = createPrivateModels()) {
+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;
@@ -810,18 +917,43 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
     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 = new DatabaseSync(paths.databasePath, { timeout: 0 });
+        database = openPrivateWritableSqliteDatabase(paths.databasePath, 0);
         database.exec("PRAGMA foreign_keys = ON");
-        const agentId = ensureLocalAgentId(database, paths.agentId);
+        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;
-        modelDatabase.exec("CREATE TABLE IF NOT EXISTS private_local_model_settings (singleton INTEGER PRIMARY KEY CHECK(singleton = 1), model TEXT NOT NULL) STRICT");
+        ensureAgentDefaultModelTable(modelDatabase);
         let initialModel = selectedProviderId === undefined || selectedModelId === undefined
             ? null
             : parseModelPreference({
@@ -833,16 +965,8 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
                 ...initialModel,
                 reasoning: input.reasoning,
             });
-        modelDatabase
-            .prepare("INSERT OR IGNORE INTO private_local_model_settings VALUES (1, ?)")
-            .run(JSON.stringify(initialModel));
-        const readAgentModel = () => {
-            const row = modelDatabase
-                .prepare("SELECT model FROM private_local_model_settings WHERE singleton = 1")
-                .get();
-            return parseModelPreferenceJson(row?.model);
-        };
-        const modelSettings = createLocalModelSettings(input.modelSettingsPath);
+        seedAgentDefaultModel(modelDatabase, initialModel);
+        const readAgentModel = () => readAgentDefaultModel(modelDatabase);
         const store = createPrivateSqliteOwner(database);
         let acceptMail;
         let readSettlement;
@@ -855,28 +979,39 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
                 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 agentControl;
+        let projectDirectory;
         if (input.agentControl !== undefined) {
-            agentControl = {
+            projectDirectory = {
                 ...input.agentControl,
                 models: (signal) => listOfferedLocalModels(models, signal),
             };
             if (delegation !== undefined)
-                agentControl = { ...agentControl, send: delegation.send };
+                projectDirectory = {
+                    ...projectDirectory,
+                    send: delegation.send,
+                    recall: delegation.recall,
+                };
         }
-        const subagents = agentControl === undefined
+        const subagents = projectDirectory === undefined
             ? undefined
-            : createPrivateLocalSubagents({ database, directory: agentControl });
-        const localTools = await createPrivateLocalTools(root, input.fungiMcp, agentControl, (sessionId) => sessionPaths.get(sessionId), dirname(paths.databasePath), subagents);
+            : 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, manual: modelSettings.read });
+        const modelSource = createPrivateLocalModelSource(models, selectedProviderId, selectedModelId, providerCacheKey, input.reasoning, { agent: readAgentModel });
         const hostOptions = {
             store,
             runtime: runtime.runtime,
@@ -899,17 +1034,27 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
             readSettlement = host.readSettlement;
         }
         const sessionOwner = agent;
-        const getSession = (sessionId) => {
-            const session = sessionOwner.session(sessionId);
+        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: session.modelPreference.read,
+                    read: async () => (await session.modelPreference.read()) ?? readAgentModel(),
                     set: async (input) => {
                         const preference = parseModelPreference(input);
                         if (preference !== null)
-                            await modelSource.assertReady(preference, new AbortController().signal);
-                        await session.modelPreference.set(preference);
+                            await setAgentModel(preference, new AbortController().signal);
+                        await session.modelPreference.set(null);
                     },
                 },
             };
@@ -918,18 +1063,23 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
         let closing;
         return Object.freeze({
             agentId,
+            name,
             databasePath: paths.databasePath,
             session,
             getSession,
-            setModel: 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();
+            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_model_settings SET model = ? WHERE singleton = 1")
-                    .run(JSON.stringify(preference));
+                    .prepare("UPDATE private_local_identity SET archived = ? WHERE singleton = 1")
+                    .run(archived ? 1 : 0);
             },
             assertModelReady: async (sessionId, signal) => {
                 const preference = await sessionOwner
@@ -939,6 +1089,8 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
             },
             bindSessionPath: (sessionId, path) => {
                 const selected = parsePrivateLocalExecPath(path);
+                if (usesServiceConfiguration)
+                    return true;
                 const previous = sessionPaths.get(sessionId);
                 if (previous !== undefined && previous !== selected)
                     return false;
@@ -961,16 +1113,53 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
                 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,
@@ -981,8 +1170,8 @@ export async function openPrivateLocalRuntimeHost(input, models = createPrivateM
         });
     }
     catch (cause) {
-        const openingFailure = asLocalFailure(cause, "Local host opening failed");
-        await closePrivateLocalResources({ agent, processes, runtime, database, lease, providerCacheKey }, openingFailure);
+        const openingFailure = localHostOpeningFailure(cause, paths.databasePath);
+        await closePrivateLocalResources({ agent, processes, sandbox, runtime, database, lease, providerCacheKey }, openingFailure);
         throw openingFailure;
     }
 }