@fungi.computer/truffle 0.0.0-stage → 0.1.1

package/dist/private-local-service.js

@@ -0,0 +1,330 @@
+import { FungiMcpSelectionConflict } from "./private-fungi-mcp-selection.js";
+import { LocalSessionPathConflict } from "./private-local-service-owner.js";
+export { LocalSessionPathConflict } from "./private-local-service-owner.js";
+import { EventSource } from "eventsource";
+import { newWebSocketRpcSession } from "@fungi.computer/capnweb";
+import { runPrivateLocalAuthRemote, } from "./private-local-auth-rpc.js";
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { createShiitakeClient, parseSessionSnapshot, } from "@fungi.computer/shiitake/client";
+import { acquireServiceLock, assertNoUntrackedServiceOwner, handshake, modelChoicesSchema, readLiveServiceStatus, readServiceRecord, removeOwnedServiceRecord, selectedSchema, sessionDiscoverySchema, sessionInspectionSchema, serviceDirectory, serviceOwnerIsLive, } from "./private-local-service-discovery.js";
+import { privateLocalEffectiveModelSchema } from "./private-local-effective-model.js";
+import { projectPrivateLocalSessionDiscovery } from "./private-local-session-discovery.js";
+import { capturePrivateLocalExecPath, parsePrivateLocalExecPath, } from "./private-local-exec-path.js";
+import { z } from "zod";
+export { runPrivateLocalWorkerServer, } from "./private-local-worker-server.js";
+/** Construction does not start a service or open a store. Call start/connect explicitly. */
+export function createPrivateLocalServiceManager(options = {}) {
+    const clientPath = options.executionPath === undefined
+        ? capturePrivateLocalExecPath(process.env.PATH ?? "/usr/bin:/bin", process.cwd())
+        : parsePrivateLocalExecPath(options.executionPath);
+    const expectedBuildId = z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional()
+        .parse(process.env.FUNGI_BUNDLED_BUILD_ID);
+    function acceptBuild(ready) {
+        if (ready.buildId !== expectedBuildId)
+            throw new Error("The running service belongs to a different Fungi build. Finish active turns, run fungi stop, then reopen Fungi. Saved Sessions are preserved.");
+        return ready;
+    }
+    const maximumInspectionResponseBytes = 2_097_152;
+    async function readBoundedResponse(response) {
+        const declared = response.headers.get("content-length");
+        if (declared !== null) {
+            const declaredBytes = Number(declared);
+            if (!Number.isSafeInteger(declaredBytes) ||
+                declaredBytes < 0 ||
+                declaredBytes > maximumInspectionResponseBytes)
+                throw new Error("Local Session inspection response is too large");
+        }
+        if (response.body === null)
+            throw new Error("Local Session inspection returned no body");
+        const stream = response.body.pipeThrough(new TransformStream());
+        const reader = stream.getReader();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            const bytes = next.value;
+            size += bytes.byteLength;
+            if (size > maximumInspectionResponseBytes) {
+                await reader.cancel();
+                throw new Error("Local Session inspection response is too large");
+            }
+            chunks.push(bytes);
+        }
+        const joined = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            joined.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return new TextDecoder().decode(joined);
+    }
+    async function status(timeoutMs) {
+        const record = await readServiceRecord(await serviceDirectory(options.directory));
+        if (record === undefined)
+            return undefined;
+        const probe = await readLiveServiceStatus(record, timeoutMs);
+        return probe.kind === "running" ? probe.service : undefined;
+    }
+    /**
+     * A loaded machine can delay a live service past the short handshake. Its
+     * lease proves it is alive, so wait for it outside the startup lock instead
+     * of spawning a second service that can only fail on that lease.
+     */
+    async function awaitBusyService(request) {
+        const waitMs = options.busyServiceWaitMs ?? 60_000;
+        const deadline = Date.now() + waitMs;
+        while (Date.now() < deadline) {
+            request.signal?.throwIfAborted();
+            const ready = await status(Math.min(10_000, waitMs));
+            if (ready)
+                return acceptBuild(ready);
+            await delay(250, undefined, { signal: request.signal });
+        }
+        throw new Error(`The Fungi service is running but has not answered for ${String(Math.round(waitMs / 1000))} seconds; the machine may be overloaded. Retry, or run fungi stop after its turns finish.`);
+    }
+    async function ownerLockReleased(directory) {
+        try {
+            await stat(join(directory, "owner.lock"));
+            return false;
+        }
+        catch (cause) {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                return true;
+            throw cause;
+        }
+    }
+    async function start(request = {}) {
+        const started = await startUnderLock(request);
+        return started === "busy" ? awaitBusyService(request) : started;
+    }
+    async function startUnderLock(request) {
+        request.signal?.throwIfAborted();
+        const directory = await serviceDirectory(options.directory);
+        const release = await acquireServiceLock(directory, "startup");
+        try {
+            const existing = await status();
+            request.signal?.throwIfAborted();
+            if (existing)
+                return acceptBuild(existing);
+            await assertNoUntrackedServiceOwner(directory);
+            if (serviceOwnerIsLive(directory))
+                return "busy";
+            const bundledCli = process.env.FUNGI_BUNDLED_CLI;
+            const child = spawn(options.executable ?? process.execPath, bundledCli === undefined
+                ? [
+                    fileURLToPath(new URL("./private-local-service-process.js", import.meta.url)),
+                    directory,
+                ]
+                : [bundledCli, "--internal-service", directory], { detached: true, stdio: "ignore" });
+            let failure;
+            let exited = false;
+            const readFailure = () => failure;
+            const hasExited = () => exited;
+            child.once("error", (cause) => {
+                failure = cause;
+            });
+            child.once("exit", () => {
+                exited = true;
+            });
+            child.unref();
+            for (let attempt = 0; attempt < 100; attempt += 1) {
+                const childFailure = readFailure();
+                if (childFailure !== undefined)
+                    throw childFailure;
+                const ready = await status();
+                if (ready)
+                    return acceptBuild(ready);
+                if (hasExited())
+                    throw new Error("Local service exited before its handshake");
+                await delay(100, undefined, { signal: request.signal });
+            }
+            child.kill("SIGTERM");
+            for (let attempt = 0; attempt < 20 && !hasExited(); attempt += 1)
+                await delay(100);
+            throw new Error(hasExited()
+                ? "Local service did not become ready and its owned child was stopped"
+                : `Local service did not become ready; child ${String(child.pid)} is still running`);
+        }
+        finally {
+            await release();
+        }
+    }
+    const openConnection = async (endpoint, input, request = {}) => {
+        request.signal?.throwIfAborted();
+        const service = await start(request);
+        const init = {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ ...input, clientPath }),
+            redirect: "error",
+        };
+        if (request.signal !== undefined)
+            init.signal = request.signal;
+        const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/${endpoint}`, init);
+        if (response.status === 409) {
+            const conflict = z.object({ code: z.string() }).safeParse(await response.json().catch((cause) => {
+                console.error("Local service response unavailable", cause);
+                return undefined;
+            }));
+            if (conflict.success && conflict.data.code === "session_path_conflict")
+                throw new LocalSessionPathConflict();
+            if (conflict.success && conflict.data.code === "store_in_use")
+                throw new Error("This Agent store is held by another Fungi service. Stop the older service process, then retry; keep the Agent store files.");
+            throw new FungiMcpSelectionConflict();
+        }
+        if (!response.ok)
+            throw new Error(`Local service selection failed (${String(response.status)})`);
+        const selected = selectedSchema.parse(await response.json());
+        const baseUrl = `${service.baseUrl}/service/${service.serviceId}${selected.routePath}`;
+        const client = createShiitakeClient({
+            baseUrl,
+            eventSource: options.eventSource ?? EventSource,
+        });
+        return {
+            service,
+            agentId: selected.agentId,
+            databasePath: selected.databasePath,
+            sessionId: selected.sessionId,
+            client,
+            session: client.session(selected.sessionId),
+            effectiveModel: async (request = {}) => {
+                request.signal?.throwIfAborted();
+                const init = { redirect: "error" };
+                if (request.signal !== undefined)
+                    init.signal = request.signal;
+                const response = await fetch(`${baseUrl}/sessions/${encodeURIComponent(selected.sessionId)}/effective-model`, init);
+                if (!response.ok)
+                    throw new Error(`Local effective model read failed (${String(response.status)})`);
+                return privateLocalEffectiveModelSchema.parse(await response.json());
+            },
+            close: () => client.close(),
+        };
+    };
+    const connect = (selection, request) => openConnection("select", selection, request);
+    const inspectResponseSchema = z.strictObject({
+        selected: selectedSchema,
+        snapshot: z.unknown(),
+    });
+    return {
+        status,
+        start,
+        createSession: (creation, request) => openConnection("sessions", creation, request),
+        connect,
+        async discover(invocationRoot, request = {}) {
+            request.signal?.throwIfAborted();
+            const service = await start(request);
+            const init = {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ invocationRoot }),
+                redirect: "error",
+            };
+            if (request.signal !== undefined)
+                init.signal = request.signal;
+            const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/discover`, init);
+            if (!response.ok)
+                throw new Error(`Local session discovery failed (${String(response.status)})`);
+            return projectPrivateLocalSessionDiscovery(sessionDiscoverySchema.parse(await response.json()), connect);
+        },
+        async inspect(selection, request = {}) {
+            request.signal?.throwIfAborted();
+            const service = await start(request);
+            const input = sessionInspectionSchema.parse({
+                ...selection,
+                limit: request.limit ?? 100,
+            });
+            const init = {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(input),
+                redirect: "error",
+            };
+            if (request.signal !== undefined)
+                init.signal = request.signal;
+            const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/inspect`, init);
+            if (!response.ok)
+                throw new Error(`Local Session inspection failed (${String(response.status)})`);
+            const decoded = inspectResponseSchema.parse(JSON.parse(await readBoundedResponse(response)));
+            const baseUrl = `${service.baseUrl}/service/${service.serviceId}${decoded.selected.routePath}`;
+            const client = createShiitakeClient({
+                baseUrl,
+                eventSource: options.eventSource ?? EventSource,
+            });
+            return {
+                session: client.session(decoded.selected.sessionId),
+                snapshot: parseSessionSnapshot(JSON.stringify(decoded.snapshot)),
+                close: () => client.close(),
+            };
+        },
+        async auth(request, interaction) {
+            interaction.signal?.throwIfAborted();
+            const service = await start(interaction.signal === undefined ? {} : { signal: interaction.signal });
+            interaction.signal?.throwIfAborted();
+            const url = new URL(`${service.baseUrl}/service/${service.serviceId}/auth`);
+            url.protocol = "ws:";
+            const socket = new WebSocket(url);
+            const remote = newWebSocketRpcSession(socket);
+            try {
+                return await runPrivateLocalAuthRemote(remote, request, interaction);
+            }
+            finally {
+                socket.close();
+            }
+        },
+        async models(request = {}) {
+            request.signal?.throwIfAborted();
+            const service = await start(request);
+            const init = { redirect: "error" };
+            if (request.signal !== undefined)
+                init.signal = request.signal;
+            const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/models`, init);
+            if (!response.ok)
+                throw new Error(`Local service model catalogue failed (${String(response.status)})`);
+            return modelChoicesSchema.parse(await response.json());
+        },
+        async stop(expectedServiceId) {
+            const directory = await serviceDirectory(options.directory);
+            const release = await acquireServiceLock(directory, "startup");
+            try {
+                const service = await readServiceRecord(directory);
+                if (service === undefined)
+                    return { kind: "not-running", recordCleaned: false };
+                if (expectedServiceId !== undefined &&
+                    service.serviceId !== expectedServiceId)
+                    return { kind: "replaced" };
+                const probe = await readLiveServiceStatus(service);
+                if (probe.kind === "not-running" && !serviceOwnerIsLive(directory)) {
+                    await removeOwnedServiceRecord(directory, service.serviceId);
+                    return { kind: "not-running", recordCleaned: true };
+                }
+                if (probe.kind !== "running")
+                    throw new Error("Local service is not answering; retry after its active turns finish.");
+                const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/stop`, {
+                    method: "POST",
+                    redirect: "error",
+                });
+                if (!response.ok)
+                    throw new Error("Local service refused shutdown");
+                for (let attempt = 0; attempt < 100; attempt += 1) {
+                    if (!(await handshake(service)) &&
+                        (await ownerLockReleased(directory)))
+                        return { kind: "stopped" };
+                    await delay(100);
+                }
+                throw new Error("Local service shutdown has not released its owner lock");
+            }
+            finally {
+                await release();
+            }
+        },
+    };
+}

package/dist/private-local-session-discovery.d.ts

@@ -0,0 +1,19 @@
+import { type StoredSessionSummary } from "@fungi.computer/shiitake/effect";
+import type { PrivateLocalServiceManager, PrivateLocalServiceRequestOptions, PrivateLocalSessionDiscovery } from "./private-local-service-contract.js";
+export type LocalSummary = StoredSessionSummary & Readonly<{
+    databasePath: string;
+    sessionId: string;
+}>;
+export declare function listPrivateLocalAgentStores(root: string): Promise<readonly string[]>;
+export declare function readPrivateLocalSessionSummaries(path: string): Promise<readonly LocalSummary[]>;
+/** Discover existing folder sessions without opening or reconciling a host. */
+export declare function readPrivateLocalSessionDiscovery(invocationRoot: string, request?: PrivateLocalServiceRequestOptions): Promise<{
+    root: string;
+    agentCount: number;
+    sessions: LocalSummary[];
+    problems: Readonly<{
+        kind: "corrupt" | "in_use" | "unreadable";
+    }>[];
+}>;
+/** Project the service-owned discovery into choices that resume through it. */
+export declare function projectPrivateLocalSessionDiscovery(discovered: Awaited<ReturnType<typeof readPrivateLocalSessionDiscovery>>, connect: PrivateLocalServiceManager["connect"]): PrivateLocalSessionDiscovery;

package/dist/private-local-session-discovery.js

@@ -0,0 +1,157 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import * as Effect from "effect/Effect";
+import { readSessionSummaries, } from "@fungi.computer/shiitake/effect";
+import { createPrivateSqliteOwner, privateSqliteFailureCode, } from "./private-sqlite-owner.js";
+function compareSummaries(left, right) {
+    return (right.updatedAt - left.updatedAt ||
+        right.createdAt - left.createdAt ||
+        left.title.localeCompare(right.title) ||
+        left.databasePath.localeCompare(right.databasePath) ||
+        left.sessionId.localeCompare(right.sessionId));
+}
+class LocalSessionDiscoveryError extends Error {
+    kind;
+    constructor(kind, options) {
+        super("Local session store could not be read", options);
+        this.kind = kind;
+    }
+}
+function sqliteProblemKind(code) {
+    if (code === "busy" || code === "locked")
+        return "in_use";
+    if (code === "corrupt" || code === "not_a_database")
+        return "corrupt";
+    return "unreadable";
+}
+function problemKind(cause) {
+    return cause instanceof LocalSessionDiscoveryError
+        ? cause.kind
+        : sqliteProblemKind(privateSqliteFailureCode(cause));
+}
+async function immediateStoreCandidates(root, relative) {
+    const directory = resolve(root, relative);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return [];
+        throw cause;
+    }
+    return Promise.all(entries
+        .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) &&
+        entry.name.length > 0)
+        .map(async (entry) => {
+        const path = join(directory, entry.name, "agent.sqlite");
+        try {
+            const metadata = await stat(path);
+            if (!metadata.isFile())
+                return undefined;
+            return { path };
+        }
+        catch (cause) {
+            if (cause instanceof Error &&
+                "code" in cause &&
+                cause.code === "ENOENT")
+                return undefined;
+            throw cause;
+        }
+    })).then((values) => values.filter((value) => value !== undefined));
+}
+export async function listPrivateLocalAgentStores(root) {
+    const candidates = await immediateStoreCandidates(root, ".fungi/agents");
+    const paths = new Set();
+    for (const candidate of candidates) {
+        try {
+            paths.add(await realpath(candidate.path));
+        }
+        catch (cause) {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                continue;
+            throw cause;
+        }
+    }
+    return [...paths];
+}
+export async function readPrivateLocalSessionSummaries(path) {
+    const database = new DatabaseSync(path, { readOnly: true, timeout: 0 });
+    try {
+        database.exec("PRAGMA foreign_keys = ON");
+        let sqliteFailure;
+        const owner = createPrivateSqliteOwner(database, (code) => {
+            sqliteFailure = code;
+        });
+        const summaries = [];
+        let after;
+        try {
+            do {
+                const page = await Effect.runPromise(readSessionSummaries(owner, after));
+                for (const row of page.sessions) {
+                    // One unreadable Session marks this store corrupt, as before.
+                    if (row.kind === "unavailable")
+                        throw new LocalSessionDiscoveryError("corrupt");
+                    summaries.push({
+                        sessionId: row.sessionId,
+                        title: row.title,
+                        createdAt: row.createdAt,
+                        updatedAt: row.updatedAt,
+                        databasePath: path,
+                    });
+                }
+                after = page.next;
+            } while (after !== undefined);
+        }
+        catch (cause) {
+            if (cause instanceof LocalSessionDiscoveryError)
+                throw cause;
+            throw new LocalSessionDiscoveryError(sqliteProblemKind(sqliteFailure), {
+                cause,
+            });
+        }
+        return summaries.sort(compareSummaries);
+    }
+    finally {
+        database.close();
+    }
+}
+/** Discover existing folder sessions without opening or reconciling a host. */
+export async function readPrivateLocalSessionDiscovery(invocationRoot, request = {}) {
+    request.signal?.throwIfAborted();
+    const root = await realpath(resolve(invocationRoot));
+    const paths = await listPrivateLocalAgentStores(root);
+    const discovered = [];
+    const problems = [];
+    for (const path of paths) {
+        request.signal?.throwIfAborted();
+        try {
+            discovered.push(...(await readPrivateLocalSessionSummaries(path)));
+        }
+        catch (cause) {
+            problems.push({ kind: problemKind(cause) });
+        }
+    }
+    discovered.sort(compareSummaries);
+    return { root, agentCount: paths.length, sessions: discovered, problems };
+}
+/** Project the service-owned discovery into choices that resume through it. */
+export function projectPrivateLocalSessionDiscovery(discovered, connect) {
+    const sessions = discovered.sessions.map(({ databasePath, sessionId, ...display }) => Object.freeze({
+        ...display,
+        databasePath,
+        sessionId,
+        resume: (resumeRequest) => connect({
+            invocationRoot: discovered.root,
+            databasePath,
+            sessionId,
+            fungiMcp: resumeRequest?.fungiMcp,
+        }, resumeRequest),
+    }));
+    return Object.freeze({
+        agentCount: discovered.agentCount,
+        sessions: Object.freeze(sessions),
+        problems: Object.freeze(discovered.problems),
+    });
+}

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

@@ -0,0 +1,44 @@
+import type { ShiitakeAgent, ShiitakeSession } from "@fungi.computer/shiitake";
+import type { ShiitakeEventSourceConstructor } from "@fungi.computer/shiitake/client";
+import { openPrivateLocalRuntimeHost, type PrivateLocalRuntimeHostOptions } from "./private-local-runtime-host.js";
+export type PrivateLocalShiitakeServer = Readonly<{
+    baseUrl: string;
+    close: () => Promise<void>;
+}>;
+export type PrivateLocalShiitakeServerOpener = (fetch: (request: Request) => Response | Promise<Response>) => PrivateLocalShiitakeServer;
+export type PrivateLocalShiitakeHostOpener = (input: PrivateLocalRuntimeHostOptions) => Promise<PrivateLocalShiitakeHost>;
+/** One private loopback Hono owner plus a neutral client mounted on it. */
+export type PrivateLocalShiitakeHost = Readonly<{
+    /** Stable Local directory identity of this authorized Agent. */
+    agentId: string;
+    /** Canonical file path owned by the server-backed local host. */
+    databasePath: string;
+    /** Private loopback origin for another neutral Shiitake client. */
+    baseUrl: string;
+    /** Client-owned neutral Session; close only releases client watches. */
+    client: ShiitakeAgent;
+    session: ShiitakeSession;
+    /** Stop the transport before releasing the RuntimeHost and database. */
+    close: () => Promise<void>;
+}>;
+/** Open one bounded private local Hono host on a loopback-only ephemeral port. */
+export declare function openPrivateLocalShiitakeHost(input: PrivateLocalRuntimeHostOptions, openServer: PrivateLocalShiitakeServerOpener, openHost?: typeof openPrivateLocalRuntimeHost, eventSource?: ShiitakeEventSourceConstructor): Promise<PrivateLocalShiitakeHost>;
+/** Explicit static input for one independently owned local worker route. */
+export type PrivateLocalShiitakeWorkerInput = Readonly<{
+    name: string;
+    owner: PrivateLocalRuntimeHostOptions;
+}>;
+/** One mounted route and its resolved durable Agent store. */
+export type PrivateLocalShiitakeWorkerRoute = Readonly<{
+    name: string;
+    routePath: string;
+    databasePath: string;
+}>;
+/** One physical server hosting a static batch of independent local owners. */
+export type PrivateLocalShiitakeWorkerBatch = Readonly<{
+    baseUrl: string;
+    workers: readonly PrivateLocalShiitakeWorkerRoute[];
+    close: () => Promise<void>;
+}>;
+/** Mount a static batch of Local Agents behind exactly one maintained Hono server. */
+export declare function openPrivateLocalShiitakeWorkerBatch(inputs: readonly PrivateLocalShiitakeWorkerInput[], openServer: PrivateLocalShiitakeServerOpener, openHost?: typeof openPrivateLocalRuntimeHost): Promise<PrivateLocalShiitakeWorkerBatch>;