@fungi.computer/truffle 0.0.0-stage → 0.2.0

package/dist/private-local-mesh-links.js

@@ -0,0 +1,229 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { createMachineLinkPostChannel, MachineLinkPostUnavailable, machineLinkAudience, machineLinkDialUrl, } from "@fungi.computer/seam/machine-link-protocol";
+import { importSeamSigner, signSeamRequest, seamHeader, unsignedPayload, } from "@fungi.computer/seam";
+import { createLocalMachineEnrollmentAccount } from "./private-fungi-account.js";
+import { logEvent } from "./log-event.js";
+export const localMeshLinkKey = (record) => JSON.stringify([
+    record.authority.kind,
+    record.authority.origin,
+    record.scopeId,
+    record.deviceId,
+]);
+/**
+ * Service-owned native I/O only. The account owns pins, Carrier owns retry
+ * custody, and the addressed runtime owns acceptance. No mail is queued here.
+ */
+export function createLocalMeshLinks(options) {
+    const account = createLocalMachineEnrollmentAccount(options.credentialPath);
+    const links = new Map();
+    let stopping = false;
+    let refreshing;
+    const isStopping = () => stopping;
+    async function current(record) {
+        const saved = await account.read();
+        const { authority, ...pin } = record;
+        return saved.some((source) => source.kind === authority.kind &&
+            source.origin === authority.origin &&
+            source.enrollments.some((candidate) => JSON.stringify(candidate) === JSON.stringify(pin)));
+    }
+    async function isCurrent(record) {
+        const link = links.get(localMeshLinkKey(record));
+        return (link !== undefined &&
+            !link.stop.signal.aborted &&
+            (await current(link.record)));
+    }
+    async function connection(record, signal, publish) {
+        const url = machineLinkDialUrl(record.authority.origin, record.scopeId, record.deviceId);
+        const signer = await importSeamSigner(`${record.deviceId}:${record.privateKey}`);
+        const signature = await signSeamRequest(signer, machineLinkAudience(record.scopeId, record.deviceId), "GET", url.href, unsignedPayload);
+        signal.throwIfAborted();
+        if (!(await current(record)))
+            throw new MachineLinkPostUnavailable({ reason: "closed" });
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        const socket = new WebSocket(url, {
+            headers: {
+                [seamHeader]: signature,
+            },
+        });
+        const channel = createMachineLinkPostChannel({
+            limits: {
+                maxInFlight: 32,
+                maxFrameBytes: 512 * 1024,
+                acknowledgmentMs: 10_000,
+            },
+            send: (frame) => {
+                socket.send(frame);
+            },
+            receive: async (envelope) => (await current(record)) ? options.receive(record, envelope) : "refused",
+        });
+        let ping;
+        let pong;
+        let opening;
+        const abort = () => {
+            socket.close(1000, "service stopping");
+        };
+        try {
+            await new Promise((resolve, reject) => {
+                const fail = (cause) => {
+                    reject(cause instanceof Error
+                        ? cause
+                        : new Error("Machine link failed", { cause }));
+                };
+                opening = setTimeout(() => {
+                    fail(new Error("Machine link upgrade timed out"));
+                }, 10_000);
+                signal.addEventListener("abort", abort, { once: true });
+                socket.addEventListener("error", () => {
+                    fail(new Error("Machine link native socket failed"));
+                });
+                socket.addEventListener("close", () => {
+                    resolve();
+                }, { once: true });
+                socket.addEventListener("open", () => {
+                    clearTimeout(opening);
+                    publish(channel);
+                    ping = setInterval(() => {
+                        void current(record).then((allowed) => {
+                            if (!allowed) {
+                                fail(new MachineLinkPostUnavailable({ reason: "closed" }));
+                                return;
+                            }
+                            try {
+                                socket.send("ping");
+                            }
+                            catch (cause) {
+                                reject(new Error("Machine link ping failed", { cause }));
+                                return;
+                            }
+                            pong = setTimeout(() => {
+                                fail(new Error("Machine link pong timed out"));
+                            }, 10_000);
+                        }, fail);
+                    }, 30_000);
+                }, { once: true });
+                socket.addEventListener("message", (event) => {
+                    if (event.data === "pong") {
+                        clearTimeout(pong);
+                        return;
+                    }
+                    const text = z.string().safeParse(event.data);
+                    if (!text.success) {
+                        fail(new Error("Machine link requires text frames"));
+                        return;
+                    }
+                    // EventTarget cannot await a handler. Transfer its actual outcome to
+                    // the connection's awaited lifetime, never a detached dropped catch.
+                    void channel.receive(text.data).then(() => undefined, fail);
+                });
+            });
+        }
+        finally {
+            publish(undefined);
+            signal.removeEventListener("abort", abort);
+            clearTimeout(opening);
+            clearInterval(ping);
+            clearTimeout(pong);
+            channel.close();
+            socket.close(1000, "connection ended");
+        }
+    }
+    async function refresh() {
+        if (refreshing !== undefined) {
+            await refreshing;
+            await refresh();
+            return;
+        }
+        const task = (async () => {
+            if (isStopping())
+                return;
+            const saved = await account.read();
+            const enrolled = saved.flatMap(({ kind, origin, enrollments }) => enrollments.flatMap((record) => record.state === "enrolled"
+                ? [{ ...record, authority: { kind, origin } }]
+                : []));
+            for (const [key, link] of links)
+                if (!enrolled.some((record) => localMeshLinkKey(record) === key &&
+                    JSON.stringify(record) === JSON.stringify(link.record))) {
+                    link.stop.abort();
+                    await link.done;
+                    links.delete(key);
+                }
+            if (isStopping())
+                return;
+            for (const record of enrolled) {
+                const key = localMeshLinkKey(record);
+                if (links.has(key))
+                    continue;
+                const stop = new AbortController();
+                const stopped = () => stop.signal.aborted;
+                const link = {
+                    record,
+                    stop,
+                    channel: undefined,
+                    done: (async () => {
+                        while (!stopped()) {
+                            try {
+                                if (!(await current(record)))
+                                    return "stopped";
+                                await connection(record, stop.signal, (channel) => {
+                                    link.channel = channel;
+                                });
+                            }
+                            catch (cause) {
+                                if (stopped())
+                                    return "stopped";
+                                logEvent("mesh-link.connection", cause);
+                            }
+                            try {
+                                await delay(1000, undefined, { signal: stop.signal });
+                            }
+                            catch (cause) {
+                                if (stopped())
+                                    return "stopped";
+                                throw cause;
+                            }
+                        }
+                        return "stopped";
+                    })(),
+                };
+                links.set(key, link);
+            }
+        })();
+        refreshing = task;
+        try {
+            await task;
+        }
+        finally {
+            refreshing = undefined;
+        }
+    }
+    return {
+        refresh,
+        isCurrent,
+        deliver: async (record, envelope) => {
+            const link = links.get(localMeshLinkKey(record));
+            const channel = link?.channel;
+            if (channel === undefined || !(await isCurrent(record))) {
+                link?.stop.abort();
+                throw new MachineLinkPostUnavailable({ reason: "closed" });
+            }
+            return await channel.deliver(envelope);
+        },
+        close: async () => {
+            stopping = true;
+            try {
+                await refreshing;
+            }
+            finally {
+                for (const link of links.values())
+                    link.stop.abort();
+                try {
+                    await Promise.all([...links.values()].map((link) => link.done));
+                }
+                finally {
+                    links.clear();
+                }
+            }
+        },
+    };
+}

package/dist/private-local-mesh-record.d.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+export declare const machineBindingSchema: z.ZodObject<{
+    selection: z.ZodNumber;
+    agentId: z.ZodString;
+}, z.core.$strict>;
+/** Private credential-file state; only public key, label and names go to Hub. */
+export declare const localMachineEnrollmentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    requestId: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"oauth">;
+        teamId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"oyster">;
+    }, z.core.$strict>], "kind">;
+    invocationRoot: z.ZodString;
+    machineLabel: z.ZodString;
+    publicKey: z.ZodBase64;
+    privateKey: z.ZodBase64;
+    agents: z.ZodArray<z.ZodObject<{
+        localAgentId: z.ZodString;
+        databasePath: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    state: z.ZodLiteral<"pending">;
+}, z.core.$strict>, z.ZodObject<{
+    requestId: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"oauth">;
+        teamId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"oyster">;
+    }, z.core.$strict>], "kind">;
+    invocationRoot: z.ZodString;
+    machineLabel: z.ZodString;
+    publicKey: z.ZodBase64;
+    privateKey: z.ZodBase64;
+    agents: z.ZodArray<z.ZodObject<{
+        localAgentId: z.ZodString;
+        databasePath: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    state: z.ZodLiteral<"enrolled">;
+    scopeId: z.ZodString;
+    deviceId: z.ZodString;
+    bindings: z.ZodArray<z.ZodObject<{
+        selection: z.ZodNumber;
+        agentId: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "state">;
+export type LocalMachineEnrollment = z.infer<typeof localMachineEnrollmentSchema>;
+export declare const machineEnrollmentAuthoritySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"oauth">;
+    origin: z.ZodURL;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"oyster">;
+    origin: z.ZodURL;
+}, z.core.$strict>], "kind">;
+export type MachineEnrollmentAuthority = z.infer<typeof machineEnrollmentAuthoritySchema>;
+/**
+ * One authority's device enrollments, keyed in the credential file by origin:
+ * a standalone Oyster's, or a Fungi issuer's partition. Every enrollment in a
+ * record names the same authority kind. Never a Pi credential or a bearer.
+ */
+export declare const machineEnrollmentRecordSchema: z.ZodObject<{
+    type: z.ZodLiteral<"machine_enrollment">;
+    origin: z.ZodURL;
+    enrollments: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        requestId: z.ZodString;
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"oauth">;
+            teamId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"oyster">;
+        }, z.core.$strict>], "kind">;
+        invocationRoot: z.ZodString;
+        machineLabel: z.ZodString;
+        publicKey: z.ZodBase64;
+        privateKey: z.ZodBase64;
+        agents: z.ZodArray<z.ZodObject<{
+            localAgentId: z.ZodString;
+            databasePath: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>>;
+        state: z.ZodLiteral<"pending">;
+    }, z.core.$strict>, z.ZodObject<{
+        requestId: z.ZodString;
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"oauth">;
+            teamId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"oyster">;
+        }, z.core.$strict>], "kind">;
+        invocationRoot: z.ZodString;
+        machineLabel: z.ZodString;
+        publicKey: z.ZodBase64;
+        privateKey: z.ZodBase64;
+        agents: z.ZodArray<z.ZodObject<{
+            localAgentId: z.ZodString;
+            databasePath: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>>;
+        state: z.ZodLiteral<"enrolled">;
+        scopeId: z.ZodString;
+        deviceId: z.ZodString;
+        bindings: z.ZodArray<z.ZodObject<{
+            selection: z.ZodNumber;
+            agentId: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "state">>;
+}, z.core.$strict>;
+export type MachineEnrollmentRecord = z.infer<typeof machineEnrollmentRecordSchema>;
+/** The authority kind a record's enrollments serve; none for an empty record. */
+export declare function machineEnrollmentRecordKind(record: MachineEnrollmentRecord): MachineEnrollmentAuthority["kind"] | undefined;
+/** The existing credential owner lends its one cross-process transaction. */
+export type LocalMachineEnrollmentAccount = Readonly<{
+    read: () => Promise<(MachineEnrollmentAuthority & {
+        enrollments: LocalMachineEnrollment[];
+    })[]>;
+    update: (authority: MachineEnrollmentAuthority, edit: (current: readonly LocalMachineEnrollment[]) => LocalMachineEnrollment[]) => Promise<void>;
+}>;

package/dist/private-local-mesh-record.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+const id = z.string().min(1).max(256);
+const selected = z.strictObject({
+    localAgentId: id,
+    databasePath: z.string().min(1).max(4096),
+    name: id,
+});
+export const machineBindingSchema = z.strictObject({
+    selection: z.number().int().min(0).max(255),
+    agentId: id,
+});
+const common = z.strictObject({
+    requestId: id,
+    target: z.discriminatedUnion("kind", [
+        z.strictObject({ kind: z.literal("oauth"), teamId: id }),
+        z.strictObject({ kind: z.literal("oyster") }),
+    ]),
+    invocationRoot: z.string().min(1).max(4096),
+    machineLabel: id,
+    publicKey: z.base64().length(44),
+    privateKey: z.base64().min(1).max(512),
+    agents: z.array(selected).max(256),
+});
+/** Private credential-file state; only public key, label and names go to Hub. */
+export const localMachineEnrollmentSchema = z.discriminatedUnion("state", [
+    common.extend({ state: z.literal("pending") }),
+    common.extend({
+        state: z.literal("enrolled"),
+        scopeId: id,
+        deviceId: id,
+        bindings: z.array(machineBindingSchema).max(256),
+    }),
+]);
+const origin = z.url().refine((value) => new URL(value).origin === value);
+export const machineEnrollmentAuthoritySchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("oauth"), origin }),
+    z.strictObject({ kind: z.literal("oyster"), origin }),
+]);
+/**
+ * One authority's device enrollments, keyed in the credential file by origin:
+ * a standalone Oyster's, or a Fungi issuer's partition. Every enrollment in a
+ * record names the same authority kind. Never a Pi credential or a bearer.
+ */
+export const machineEnrollmentRecordSchema = z.strictObject({
+    type: z.literal("machine_enrollment"),
+    origin,
+    enrollments: z
+        .array(localMachineEnrollmentSchema)
+        .max(256)
+        .refine((records) => records.every((record) => record.target.kind === records[0]?.target.kind)),
+});
+/** The authority kind a record's enrollments serve; none for an empty record. */
+export function machineEnrollmentRecordKind(record) {
+    return record.enrollments[0]?.target.kind;
+}

package/dist/private-local-process-identity.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A process-start discriminator. `unverifiable` means no sufficiently precise
+ * reader is implemented on this platform.
+ */
+export type ProcessStart = Readonly<{
+    kind: "running";
+    start: string;
+}> | Readonly<{
+    kind: "gone";
+}> | Readonly<{
+    kind: "unverifiable";
+}>;
+/**
+ * Linux reads proc(5)'s `starttime` (field 22 of `/proc/<pid>/stat`, in clock
+ * ticks since boot). macOS's ps lstart is only second-resolution and is not
+ * accepted as signal authority. No sub-second macOS reader is implemented.
+ */
+export declare function readProcessStart(pid: number): Promise<ProcessStart>;
+/** The owner's start discriminator; an unverifiable marker never permits signalling. */
+export declare function readOwnProcessStart(): Promise<string>;

package/dist/private-local-process-identity.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+const procStartSchema = z.string().regex(/^\d+$/u);
+/**
+ * Linux reads proc(5)'s `starttime` (field 22 of `/proc/<pid>/stat`, in clock
+ * ticks since boot). macOS's ps lstart is only second-resolution and is not
+ * accepted as signal authority. No sub-second macOS reader is implemented.
+ */
+export async function readProcessStart(pid) {
+    if (process.platform === "linux") {
+        let stat;
+        try {
+            stat = await readFile(`/proc/${String(pid)}/stat`, "utf8");
+        }
+        catch (cause) {
+            // The process may exit after procfs opened stat but before it was read.
+            if (cause instanceof Error &&
+                "code" in cause &&
+                (cause.code === "ENOENT" || cause.code === "ESRCH"))
+                return { kind: "gone" };
+            throw cause;
+        }
+        // Field 2 is the parenthesised command name, which may itself contain
+        // spaces or parentheses; the fields after its last `)` are plain.
+        const start = procStartSchema.safeParse(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19]);
+        return start.success
+            ? { kind: "running", start: `linux:${start.data}` }
+            : { kind: "unverifiable" };
+    }
+    return { kind: "unverifiable" };
+}
+/** The owner's start discriminator; an unverifiable marker never permits signalling. */
+export async function readOwnProcessStart() {
+    const own = await readProcessStart(process.pid);
+    if (own.kind === "unverifiable")
+        return "unverifiable";
+    if (own.kind === "gone")
+        throw new Error("The Fungi service cannot read its own process start time.");
+    return own.start;
+}

package/dist/private-local-runtime-host.d.ts

@@ -0,0 +1,192 @@
+import type { OutstandingDelegation } from "@fungi.computer/shiitake/fleet";
+import { createMcpFormSession } from "./private-mcp-form-session.js";
+import type { LocalUiAttachment } from "./private-local-ui-attachment.js";
+import { type LocalAgentExtensions } from "./local-extensions.js";
+import { type Models, type ThinkingLevel } from "@earendil-works/pi-ai";
+import type { CapabilitySource } from "@fungi.computer/mycelium";
+import type { BirdDogMail } from "@fungi.computer/bird-dog";
+import type { Accepted, CommandSettlement } from "@fungi.computer/shiitake";
+import { type ModelPreference } from "@fungi.computer/shiitake/model-preference";
+import { type AgentControlDirectory } from "@fungi.computer/shiitake/agent-control";
+import type { ExtensionRosterV0 } from "@fungi.computer/shiitake/extensions";
+import { type InstructionSource, type ModelSource, Shiitake, type RuntimeHost, type ShiitakeAgent, type ShiitakeSession, type ShiitakeOptions } from "@fungi.computer/shiitake";
+import { type PrivateLocalConfigRoot } from "./private-local-config-root.js";
+import { type PrivateLocalEffectiveModel } from "./private-local-effective-model.js";
+import { type PrivateLocalComputerProcesses } from "./private-local-computer-processes.js";
+import { type LocalSandboxControls, type LocalSandboxStatus } from "./private-local-sandbox.js";
+import { type NodeRuntimeHost, type NodeStoreLease } from "@fungi.computer/shiitake/node";
+import { createPrivateInvocationFilesPort, type LocalSandboxWrites } from "./private-invocation-files.js";
+import { type PrivateFungiMcpConnectionOptions } from "./private-fungi-mcp-connection.js";
+import { type PrivateSqliteDatabase } from "./private-sqlite-owner.js";
+import { type PrivateLocalMailRouting } from "./private-local-delegation.js";
+import { type LocalAgentControlDirectory } from "./private-local-agent-control.js";
+import { type SubagentSource } from "@fungi.computer/shiitake-extensions/subagents/host";
+declare const localHostIds: Readonly<{
+    readonly store: import("@fungi.computer/cairn").IdCodec<"local-host", "store", 1>;
+    readonly "session-create-request": import("@fungi.computer/cairn").IdCodec<"local-host", "session-create-request", 1>;
+}>;
+export type LocalStoreId = ReturnType<typeof localHostIds.store.generate>;
+export type LocalResources = Readonly<{
+    agent?: Pick<ShiitakeAgent, "close"> | undefined;
+    processes?: Pick<PrivateLocalComputerProcesses, "close"> | undefined;
+    sandbox?: Pick<LocalSandboxControls, "close"> | undefined;
+    runtime: Omit<NodeRuntimeHost, "scheduleWake">;
+    database?: Pick<PrivateSqliteDatabase, "close"> | undefined;
+    lease?: NodeStoreLease | undefined;
+    providerCacheKey?: string | undefined;
+}>;
+export type PrivateLocalTools = Readonly<{
+    bindSession: ReturnType<typeof createMcpFormSession>["bindSession"];
+    presentApproval: ReturnType<typeof createMcpFormSession>["presentApproval"];
+    configure: (installed: LocalAgentExtensions, fungiMcp: PrivateFungiMcpConnectionOptions | undefined, clientPath?: string) => Pick<ShiitakeOptions, "extensions" | "tools">;
+    port: Awaited<ReturnType<typeof createPrivateInvocationFilesPort>>;
+    tools: NonNullable<ShiitakeOptions["tools"]>;
+    extensions: ExtensionRosterV0;
+    /** Background Computer processes, scoped per Session; the host closes them. */
+    processes: PrivateLocalComputerProcesses;
+}>;
+/** Inputs for the one private local Agent opener. */
+export type PrivateLocalRuntimeHostOptions = Readonly<{
+    /** Service-selected host configuration, independent of this Agent's Files root. */
+    configRoot?: PrivateLocalConfigRoot;
+    configuration?: (storeDirectory: string) => Promise<LocalRuntimeConfiguration>;
+    /** Invocation root captured before selecting a fresh local database. */
+    invocationRoot: string;
+    /** Existing Agent database to reopen instead of creating a fresh local store. */
+    databasePath?: string | undefined;
+    /** Stable Local store identity for replaying one Agent create request. */
+    createRequestId?: string | undefined;
+    /** Display name chosen when this Agent is created; the id names it otherwise. */
+    name?: string | undefined;
+    /** The Agent that created this one; recorded once with its identity. Absent when a human made it. */
+    createdBy?: string | undefined;
+    /** Immutable project-relative folder authority, inherited by child Agents. */
+    folder?: string | undefined;
+    /** Persist before constructing the Agent, which can recover durable work. */
+    requireSandbox?: boolean | undefined;
+    /** Explicit Agent model; otherwise the Agent's stored default, then the available login. */
+    providerId?: string | undefined;
+    modelId?: string | undefined;
+    reasoning?: ThinkingLevel | undefined;
+    /**
+     * Service-owned project mail routing. With `agentControl`, it gives this
+     * Agent follow-up delegation with authenticated replies and settles its own
+     * addressed work back to the sender.
+     */
+    mail?: PrivateLocalMailRouting | undefined;
+    /** Service-owned directory scoped to the captured project. */
+    agentControl?: LocalAgentControlDirectory | undefined;
+    /** Service-owned Team context for this store; never a caller-supplied alias. */
+    meshAdmission?: (localAgentId: string, recipientAgentId: string) => Promise<readonly {
+        agentId: string;
+        name: string;
+    }[] | undefined>;
+    /** Explicit hosted capability connection; local tools and the Agent store stay local. */
+    fungiMcp?: PrivateFungiMcpConnectionOptions | undefined;
+}>;
+/** Typed Session and awaited resource owner supplied directly to the local TUI. */
+export type PrivateLocalRuntimeHost = Readonly<{
+    /** Native host-only form/record binding; never a Session or model command. */
+    presentApproval: PrivateLocalTools["presentApproval"];
+    prepareReload: (configuration: LocalRuntimeConfiguration) => ReturnType<Awaited<ReturnType<typeof Shiitake.make>>["prepareConfiguration"]>;
+    /** Stable Local directory identity of this authorized Agent. */
+    agentId: string;
+    /** The Agent's stored display name; its id for an Agent stored before names. */
+    name: string;
+    /** Canonical file path to pass explicitly to a later --db launch. */
+    databasePath: string;
+    session: ShiitakeSession;
+    /** Address a Session through this same Agent and resource owner. */
+    getSession: (sessionId: string, attachment?: LocalUiAttachment) => ShiitakeSession;
+    /** A selected Session keeps one client's command PATH while this host is live. */
+    bindSessionPath: (sessionId: string, path: string) => boolean;
+    /** Resolve this Session's effective model and nonsecret credential source. */
+    effectiveModel: (sessionId: string, signal: AbortSignal) => Promise<PrivateLocalEffectiveModel>;
+    /**
+     * Hide this Agent from lists, pickers and delegation, or restore it. Only the
+     * flag changes; the store, its Sessions and files stay.
+     */
+    setArchived: (archived: boolean) => void;
+    /** Persist the requirement before another affected launch is admitted. */
+    setRequireSandbox: (required: boolean) => void;
+    sandboxStatus: () => LocalSandboxStatus;
+    /** Set the persistent Agent default, thinking level included, without changing Session overrides. */
+    setModel: (model: ModelPreference, signal: AbortSignal) => Promise<void>;
+    /** Refuse unrunnable creation or send before claiming acceptance. */
+    assertModelReady: (sessionId: string, signal: AbortSignal) => Promise<void>;
+    listSessions: ShiitakeAgent["listSessions"];
+    createSession: ShiitakeAgent["createSession"];
+    deleteSession: ShiitakeAgent["deleteSession"];
+    /** List, resume and call this Agent's rostered extensions. */
+    extensions: ShiitakeAgent["extensions"];
+    /**
+     * Admit mail addressed to this Agent: new work that replies to its sender,
+     * or a reply authenticated against work this Agent sent. Anything else is
+     * refused.
+     */
+    acceptMail: (mail: BirdDogMail) => Promise<Accepted>;
+    /** Delegated work this Agent still waits on, as its target Session and command; undefined when none. */
+    pendingDelegation: () => Promise<OutstandingDelegation | undefined>;
+    /** Exact settled command facts for a delegating sender. */
+    readSettlement: (sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
+    /**
+     * Whether this Agent holds nothing a later reopen could not resume: no
+     * running or waiting Session, Watchdog job, scheduled wake, reply still
+     * owed a delivery attempt or running background process. Work it delegated
+     * is owed by the child, whose reply mail reopens this Agent.
+     */
+    idle: () => Promise<boolean>;
+    close: () => Promise<void>;
+}>;
+export type LocalRuntimeConfiguration = Readonly<{
+    installed: LocalAgentExtensions;
+    fungiMcp: PrivateFungiMcpConnectionOptions | undefined;
+    clientPath: string;
+}>;
+/** Local-owned id for a new Session creation request. */
+export declare function createPrivateLocalSessionRequestId(): import("@fungi.computer/cairn").CairnId<"local-host", "session-create-request", 1>;
+export type PrivateLocalCreateStore = Readonly<{
+    agentId: LocalStoreId;
+    databasePath: string;
+}>;
+/** Resolve an Agent create request through its durable Local receipt. */
+export declare function resolvePrivateLocalCreateStore(root: string, requestId: string): Promise<PrivateLocalCreateStore>;
+/** Build the fixed source read by Shiitake once for each local run. */
+export declare function createPrivateLocalInstructionSource(port: Awaited<ReturnType<typeof createPrivateInvocationFilesPort>>): InstructionSource;
+export declare function createPrivateLocalModelSource(models: Models, providerId: string | undefined, modelId: string | undefined, providerCacheKey: string, selectedOwnerReasoning?: ThinkingLevel, defaults?: Readonly<{
+    agent?: () => ModelPreference | null;
+}>): ModelSource & Readonly<{
+    /** The secret-free effective selection the footer and /model show. */
+    effective: (preference: ModelPreference | null, signal: AbortSignal) => Promise<PrivateLocalEffectiveModel>;
+    assertReady: (preference: ModelPreference | null, signal: AbortSignal) => Promise<void>;
+}>;
+/** Assemble the existing Files, Computer, and workerd owners once per host. */
+export declare function createPrivateLocalTools(invocationRoot: string, fungiMcp?: PrivateFungiMcpConnectionOptions, agentControl?: AgentControlDirectory, sessionPath?: (sessionId: string) => string | undefined, 
+/** This Agent's store; its owner-enabled installed extensions join the roster. */
+storeDirectory?: string, 
+/**
+ * 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?: Readonly<{
+    control: CapabilitySource;
+    source: SubagentSource;
+}>, configuration?: LocalRuntimeConfiguration, configRoot?: PrivateLocalConfigRoot, sandbox?: LocalSandboxWrites): Promise<PrivateLocalTools>;
+/** Event-loop adaptation for the one local Shiitake owner; it has no queue policy. */
+export declare function createPrivateLocalRuntimeHost(): RuntimeHost;
+/**
+ * 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 declare function closePrivateLocalResources(resources: LocalResources, initiatingFailure?: Error): Promise<void>;
+/**
+ * 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 declare function openPrivateLocalRuntimeHost(input: PrivateLocalRuntimeHostOptions, suppliedModels?: Models): Promise<PrivateLocalRuntimeHost>;
+export {};