@fungi.computer/truffle 0.0.0-stage → 0.2.0

package/dist/private-local-service-listener.d.ts

@@ -0,0 +1,22 @@
+import { type ServiceDrainPhase } from "./private-local-service-log.js";
+import { runLocalAuthCli } from "./auth-cli.js";
+import { type PrivateLocalConfigRoot } from "./private-local-config-root.js";
+import { listPrivateModels } from "./local-models.js";
+import { type OpenLocalServiceRuntime } from "./private-local-service-owner.js";
+export declare function createPrivateLocalServiceShutdown(input: {
+    closeOwners: () => Promise<void>;
+    closeServer: () => Promise<void>;
+    closeDiagnostics?: () => void;
+    removeRecord: () => Promise<void>;
+    releaseOwner: () => Promise<void>;
+}): {
+    finish: () => Promise<void>;
+    isDraining: () => boolean;
+    phase: () => ServiceDrainPhase;
+};
+/** Native Bun listener retained from TUI; service owns both listener and stores. */
+export declare function runPrivateLocalService(directory: string, openRuntime?: OpenLocalServiceRuntime, listModels?: typeof listPrivateModels, runAuth?: typeof runLocalAuthCli, 
+/** How often the service releases Agents nothing uses. */
+idleSweepMs?: number, 
+/** Narrow manifest I/O port, independent of the Agent-runtime opener. */
+readRecoveryManifest?: (path: string) => Promise<string>, root?: PrivateLocalConfigRoot): Promise<void>;

package/dist/private-local-service-listener.js

@@ -0,0 +1,407 @@
+import { localFailureMetadata, logEvent } from "./log-event.js";
+import { bodyLimit } from "hono/body-limit";
+import { enrollPrivateLocalMesh, localMeshJoinSchema, } from "./private-local-mesh-enrollment.js";
+import { createLocalMachineEnrollmentAccount, registerFungiAccountOwner, signOutOwnedFungiAccount, } from "./private-fungi-account.js";
+import { createServiceLogLifecycle, } from "./private-local-service-log.js";
+import { stopAllRequestSchema } from "./private-local-stop-all.js";
+import { FungiMcpSelectionConflict } from "./private-fungi-mcp-selection.js";
+import { LocalSandboxUnavailable } from "./private-local-containment.js";
+import { PrivateLocalAuthTarget } from "./private-local-auth-rpc.js";
+import { runLocalAuthCli } from "./auth-cli.js";
+import { capturePrivateLocalConfigRoot, } from "./private-local-config-root.js";
+import { Hono } from "hono";
+import { correlationKey } from "@fungi.computer/cairn";
+import { createLocalUiAttachment, } from "./private-local-ui-attachment.js";
+import { localServiceIds } from "./private-local-service-ids.js";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+import { privateLocalExecPathSchema } from "./private-local-exec-path.js";
+import { listPrivateModels } from "./local-models.js";
+import { privateSqliteFailureCode } from "./private-sqlite-owner.js";
+import { openPrivateLocalBunServer } from "./private-bun-shiitake-host.js";
+import { readOwnProcessStart } from "./private-local-process-identity.js";
+import { LocalStoreSchemaError, readPrivateLocalSessionDiscovery, } from "./private-local-session-discovery.js";
+import { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
+import { createLocalServiceOwners, LocalAgentSelectionAmbiguous, LocalSessionPathConflict, } from "./private-local-service-owner.js";
+import { acquireServiceLock, archiveRequestSchema, discoverRequestSchema, privateLocalServiceProtocol, privateLocalServiceVersion, recordPath, removeOwnedServiceRecord, selectionSchema, sessionCreationSchema, sessionInspectionSchema, sandboxStatusSchema, } from "./private-local-service-discovery.js";
+export function createPrivateLocalServiceShutdown(input) {
+    let draining;
+    let finishing;
+    let phase = "active";
+    const finish = () => {
+        finishing ??= (async () => {
+            // Keep discovery and the lease until owners settle. The process owner
+            // bounds this whole sequence, including a hung owner or listener.
+            phase = "owners";
+            draining ??= input.closeOwners();
+            await draining;
+            phase = "listener";
+            await input.closeServer();
+            // Stop diagnostics before releasing ownership. Its resource latches I/O
+            // faults and disables writes; a diagnostic fault cannot strand a service
+            // registration/lease or make normal shutdown reject.
+            try {
+                input.closeDiagnostics?.();
+            }
+            catch (cause) {
+                // Diagnostics cannot strand registration/lease or fail a normal stop.
+                // The owned resource latches its typed fault; this protects cleanup
+                // against an unexpected disposal callback failure as well.
+                logEvent("service-log.dispose", cause);
+            }
+            try {
+                phase = "record";
+                await input.removeRecord();
+            }
+            finally {
+                phase = "lease";
+                await input.releaseOwner();
+            }
+            phase = "closed";
+        })();
+        return finishing;
+    };
+    return {
+        finish,
+        isDraining: () => draining !== undefined,
+        phase: () => phase,
+    };
+}
+/** Native Bun listener retained from TUI; service owns both listener and stores. */
+export async function runPrivateLocalService(directory, openRuntime, listModels = listPrivateModels, runAuth = runLocalAuthCli, 
+/** How often the service releases Agents nothing uses. */
+idleSweepMs, 
+/** Narrow manifest I/O port, independent of the Agent-runtime opener. */
+readRecoveryManifest, root = capturePrivateLocalConfigRoot()) {
+    // Publish the same discriminator in the pointer and the acquired owner row.
+    const startedAt = await readOwnProcessStart();
+    const release = await acquireServiceLock(directory, "owner");
+    const serviceId = localServiceIds.service.generate();
+    const version = privateLocalServiceVersion();
+    const jsc = await import("bun:jsc");
+    const diagnostics = createServiceLogLifecycle({
+        directory,
+        pid: process.pid,
+        version,
+        readMemory: () => ({
+            rss: process.memoryUsage().rss,
+            heap: jsc.heapStats(),
+        }),
+    });
+    const owners = createLocalServiceOwners(openRuntime, directory, undefined, idleSweepMs, readRecoveryManifest, diagnostics.recoveryDisabled, root);
+    const prefix = `/service/${serviceId}`;
+    const releaseAccountOwner = registerFungiAccountOwner(root.credentialPath, () => owners.refreshMesh());
+    const app = new Hono();
+    app.onError((error, context) => {
+        diagnostics.failure(localFailureMetadata("service.request", error));
+        if (error instanceof LocalStoreSchemaError)
+            return context.json({
+                code: "store_schema_incompatible",
+                databasePath: error.databasePath,
+                error: error.message,
+            }, 409);
+        if (error instanceof LocalSandboxUnavailable)
+            return context.json({ code: "sandbox_unavailable", reason: error.reason }, 409);
+        if (error instanceof z.ZodError)
+            return context.json({
+                code: "invalid_selection",
+                issues: error.issues.map((issue) => ({
+                    field: issue.path.join("."),
+                    reason: issue.message,
+                })),
+            }, 400);
+        if (error instanceof LocalSessionPathConflict)
+            return context.json({ code: "session_path_conflict", error: error.message }, 409);
+        if (error instanceof LocalAgentSelectionAmbiguous)
+            return context.json({ code: "agent_selection_ambiguous", agentIds: error.agentIds }, 409);
+        if (error instanceof FungiMcpSelectionConflict)
+            return context.json({ error: error.message }, 409);
+        if (error instanceof AgentArchiveRefused)
+            return context.json({
+                code: "agent_archive_refused",
+                reason: error.reason,
+                error: error.message,
+            }, 409);
+        const sqliteFailure = privateSqliteFailureCode(error);
+        if (sqliteFailure === "busy" || sqliteFailure === "locked")
+            return context.json({ code: "store_in_use" }, 409);
+        logEvent("service-listener.request", error);
+        return context.json({
+            code: "internal_error",
+            error: error instanceof Error ? error.message : "Unknown failure",
+        }, 500);
+    });
+    const routes = new Map();
+    const stopped = Promise.withResolvers();
+    let server;
+    /** Identity-only pointer; live routes add current diagnostics separately. */
+    let record;
+    let recordWritten = false;
+    /**
+     * Mount an Agent's route by store, not by its open runtime: a request on a
+     * route reopens an Agent the service released while it was idle.
+     */
+    const mount = (selected, fungiMcp, attachment) => {
+        // Inspectors share a read route; each UI gets a private host-issued route.
+        let mounted = attachment === undefined ? routes.get(selected.databasePath) : undefined;
+        if (!mounted) {
+            const path = `/agents/${correlationKey()}`;
+            const routePrefix = prefix + path;
+            const target = {
+                invocationRoot: selected.invocationRoot,
+                databasePath: selected.databasePath,
+                fungiMcp,
+            };
+            mounted = {
+                path,
+                fetch: (request) => {
+                    const url = new URL(request.url);
+                    url.pathname = url.pathname.slice(routePrefix.length) || "/";
+                    if (request.method === "DELETE" &&
+                        url.pathname === "/" &&
+                        attachment !== undefined) {
+                        attachment.close();
+                        return new Response(null, { status: 204 });
+                    }
+                    return owners.serve(target, new Request(url.toString(), request), attachment);
+                },
+                effectiveModel: (sessionId, signal) => owners.effectiveModel(target, sessionId, signal),
+                sandboxStatus: (signal) => owners.sandboxStatus(target, signal),
+            };
+            const key = attachment === undefined ? selected.databasePath : path;
+            routes.set(key, mounted);
+            attachment?.signal.addEventListener("abort", () => {
+                routes.delete(key);
+            }, { once: true });
+        }
+        return {
+            agentId: selected.agentId,
+            databasePath: selected.databasePath,
+            sessionId: selected.sessionId,
+            routePath: mounted.path,
+        };
+    };
+    const shutdown = createPrivateLocalServiceShutdown({
+        closeOwners: owners.close,
+        closeServer: async () => {
+            await server?.close();
+        },
+        removeRecord: async () => {
+            if (recordWritten)
+                await removeOwnedServiceRecord(directory, serviceId);
+        },
+        releaseOwner: release,
+        closeDiagnostics: diagnostics.close,
+    });
+    const drainDeadlineMs = 4_000;
+    let deadline;
+    const finish = () => {
+        // Leave headroom before the maintained client's 5-second SIGKILL fallback.
+        // Never reset the overall budget for another Agent or another signal.
+        deadline ??= setTimeout(() => {
+            // The background service has no stderr (spawned with stdio "ignore");
+            // the private service log is its only durable diagnostic record.
+            diagnostics.drainTimeout({
+                deadlineMs: drainDeadlineMs,
+                phase: shutdown.phase(),
+                unfinishedOwners: owners.unfinishedOwners(),
+            });
+            // A Promise race cannot interrupt Agent.close's uninterruptible work.
+            // Committed SQLite facts and recovery references remain for the next
+            // owner; do not pretend those unfinished Agents closed successfully.
+            process.exit(1);
+        }, drainDeadlineMs);
+        const finishing = shutdown.finish();
+        void finishing.then(() => {
+            clearTimeout(deadline);
+            stopped.resolve(undefined);
+        }, (cause) => {
+            stopped.reject(cause);
+        });
+        return finishing;
+    };
+    const onSignal = (reason) => {
+        diagnostics.stopping(reason);
+        void finish();
+    };
+    const onInterrupt = () => {
+        onSignal("SIGINT");
+    };
+    const onTerminate = () => {
+        onSignal("SIGTERM");
+    };
+    const isLocalRequest = (request) => !request.headers.has("origin") &&
+        new URL(request.url).hostname === "127.0.0.1";
+    try {
+        app.use("*", async (context, next) => {
+            const request = context.req.raw;
+            // Local client only: no browser-origin admission or DNS rebinding authority.
+            if (!isLocalRequest(request))
+                return context.body(null, 403);
+            const path = new URL(request.url).pathname;
+            // While SIGTERM drains its owners, only the handshake answers, so
+            // `fungi stop` can still confirm the process it is waiting on.
+            if (shutdown.isDraining() && path !== `${prefix}/status`)
+                return context.body(null, 503);
+            await next();
+            return;
+        });
+        app.get(`${prefix}/status`, (context) => record === undefined
+            ? context.body(null, 503)
+            : context.json({
+                ...record,
+                diagnostics: diagnostics.getStatus(),
+            }));
+        app.get(`${prefix}/models`, async (context) => context.json(await listModels(root.credentialPath)));
+        app.post(`${prefix}/mesh/join`, bodyLimit({ maxSize: 512 * 1024 }), async (context) => {
+            const enrolled = await enrollPrivateLocalMesh(localMeshJoinSchema.parse(await context.req.json()), {
+                credentialPath: root.credentialPath,
+                signal: context.req.raw.signal,
+                account: createLocalMachineEnrollmentAccount(root.credentialPath),
+            });
+            await owners.refreshMesh();
+            // Enrollment is not a confirmed shared connection or command receipt.
+            return context.json(enrolled, 202);
+        });
+        app.post(`${prefix}/discover`, async (context) => {
+            const input = discoverRequestSchema.parse(await context.req.json());
+            return context.json(await readPrivateLocalSessionDiscovery(input.invocationRoot, {
+                signal: context.req.raw.signal,
+                archived: input.archived,
+            }));
+        });
+        app.post(`${prefix}/reload`, async (context) => {
+            try {
+                const input = z
+                    .strictObject({
+                    invocationRoot: z.string().min(1),
+                    clientPath: privateLocalExecPathSchema,
+                })
+                    .parse(await context.req.json());
+                await owners.reload(input.invocationRoot, input.clientPath);
+                return context.json({
+                    message: "Configuration reloaded; applies from the next turn",
+                });
+            }
+            catch (cause) {
+                return context.json({
+                    error: `${cause instanceof Error ? cause.message : String(cause)}\nOld configuration kept.`,
+                }, 400);
+            }
+        });
+        app.post(`${prefix}/stop-all`, async (context) => context.json(await owners.stopAll(stopAllRequestSchema.parse(await context.req.json()))));
+        app.post(`${prefix}/archive`, async (context) => {
+            await owners.archive(archiveRequestSchema.parse(await context.req.json()), context.req.raw.signal);
+            return context.body(null, 204);
+        });
+        app.get(`${prefix}/agents/:route/sessions/:sessionId/effective-model`, async (context) => {
+            const route = [...routes.values()].find((entry) => entry.path === `/agents/${context.req.param("route")}`);
+            if (route === undefined)
+                return context.body(null, 404);
+            return context.json(await route.effectiveModel(context.req.param("sessionId"), context.req.raw.signal));
+        });
+        app.get(`${prefix}/agents/:route/sandbox`, async (context) => {
+            const route = [...routes.values()].find((entry) => entry.path === `/agents/${context.req.param("route")}`);
+            if (route === undefined)
+                return context.body(null, 404);
+            return context.json(sandboxStatusSchema.parse(await route.sandboxStatus(context.req.raw.signal)));
+        });
+        app.post(`${prefix}/sessions`, async (context) => {
+            const input = sessionCreationSchema.parse(await context.req.json());
+            const selected = await owners.createSession(input);
+            try {
+                return context.json(mount(selected, input.fungiMcp, createLocalUiAttachment(selected.sessionId, input.uiAttachmentLifetime)));
+            }
+            finally {
+                selected.release();
+            }
+        });
+        app.post(`${prefix}/select`, async (context) => {
+            const input = selectionSchema.parse(await context.req.json());
+            const selected = await owners.select(input);
+            try {
+                return context.json(mount(selected, input.fungiMcp, createLocalUiAttachment(selected.sessionId, input.uiAttachmentLifetime)));
+            }
+            finally {
+                selected.release();
+            }
+        });
+        app.post(`${prefix}/inspect`, async (context) => {
+            const input = sessionInspectionSchema.parse(await context.req.json());
+            const selected = await owners.select(input);
+            try {
+                return context.json({
+                    diagnostics: diagnostics.getStatus(),
+                    selected: mount(selected, input.fungiMcp, undefined),
+                    snapshot: await selected.session.read({
+                        limit: input.limit,
+                        includeSandboxFailures: true,
+                    }),
+                });
+            }
+            finally {
+                selected.release();
+            }
+        });
+        app.all(`${prefix}/agents/*`, (context) => {
+            const path = new URL(context.req.url).pathname;
+            for (const route of routes.values()) {
+                if (path.startsWith(`${prefix}${route.path}/`))
+                    return route.fetch(context.req.raw);
+            }
+            return context.body(null, 404);
+        });
+        server = openPrivateLocalBunServer((request) => app.fetch(request), undefined, {
+            path: `${prefix}/auth`,
+            admit: (request) => isLocalRequest(request) && !shutdown.isDraining(),
+            createTarget: () => new PrivateLocalAuthTarget((argv, options) => runAuth(argv, {
+                ...options,
+                credentialPath: root.credentialPath,
+            }), async (request) => {
+                if (request.credentialPath !== root.credentialPath)
+                    throw new Error("Fungi account belongs to another Local home");
+                return await signOutOwnedFungiAccount(request.endpoint, {
+                    credentialPath: root.credentialPath,
+                });
+            }),
+        });
+        record = {
+            protocol: privateLocalServiceProtocol,
+            version,
+            serviceId,
+            pid: process.pid,
+            startedAt,
+            baseUrl: server.baseUrl,
+        };
+        await writeFileAtomic(recordPath(directory), JSON.stringify(record), {
+            mode: 0o600,
+        });
+        recordWritten = true;
+        diagnostics.ready(serviceId);
+        process.on("SIGINT", onInterrupt);
+        process.on("SIGTERM", onTerminate);
+        // Health and shutdown must answer before any saved Agent is reopened.
+        // Owner shutdown tracks this task; requests share its ordinary ownerFor.
+        void owners.restore();
+        void owners.refreshMesh().catch((cause) => {
+            logEvent("service-listener.mesh-start", cause);
+        });
+        await stopped.promise;
+    }
+    catch (cause) {
+        logEvent("service-listener.lifecycle", cause);
+        diagnostics.failure(localFailureMetadata("service-listener.lifecycle", cause));
+        diagnostics.stopping(recordWritten ? "runtime-failure" : "startup-failure");
+        throw cause;
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+        process.off("SIGTERM", onTerminate);
+        try {
+            await finish();
+        }
+        finally {
+            releaseAccountOwner();
+        }
+    }
+}

package/dist/private-local-service-log.d.ts

@@ -0,0 +1,128 @@
+import type { heapStats } from "bun:jsc";
+import { localFailureMetadata } from "./log-event.js";
+import { z } from "zod";
+export declare const serviceLogRecordBytes: number;
+export declare const serviceLogSampleIntervalMs: number;
+export type HeapStatistics = ReturnType<typeof heapStats>;
+export type FailureMetadata = ReturnType<typeof localFailureMetadata>;
+export declare const serviceDiagnosticsStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"active">;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"failed">;
+    code: z.ZodEnum<{
+        "sink-open-failed": "sink-open-failed";
+        "sink-write-failed": "sink-write-failed";
+        "sink-close-failed": "sink-close-failed";
+    }>;
+    since: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"recovery-disabled">;
+    code: z.ZodEnum<{
+        "read-failed": "read-failed";
+        "decode-failed": "decode-failed";
+    }>;
+    since: z.ZodISODateTime;
+}, z.core.$strict>], "state">;
+export type ServiceDiagnosticsStatus = z.infer<typeof serviceDiagnosticsStatusSchema>;
+export type ServiceDiagnosticsFailureCode = Extract<ServiceDiagnosticsStatus, {
+    state: "failed";
+}>["code"];
+export type RecoveryPersistenceFailureCode = Extract<ServiceDiagnosticsStatus, {
+    state: "recovery-disabled";
+}>["code"];
+export type ServiceLogWriter = Readonly<{
+    writeLine: (line: string) => void;
+    close: () => void;
+}>;
+export type OpenServiceLogWriter = (directory: string) => ServiceLogWriter;
+/** Catchable observations, not an inferred cause for a missing final record. */
+export type ServiceLogEvent = Readonly<{
+    event: "starting";
+}> | Readonly<{
+    event: "ready";
+    serviceId: string;
+}> | Readonly<{
+    event: "stopping" | "stopped";
+    reason: "SIGINT" | "SIGTERM" | "startup-failure" | "runtime-failure";
+}> | Readonly<{
+    event: "failure";
+    failure: FailureMetadata;
+}> | Readonly<{
+    event: "recovery-persistence-disabled";
+    code: RecoveryPersistenceFailureCode;
+}> | Readonly<{
+    event: "memory";
+    rss: number;
+    heap: HeapStatistics;
+}> | Readonly<{
+    event: "memory-unavailable";
+    failure: FailureMetadata;
+}> | Readonly<{
+    event: "drain-timeout";
+    deadlineMs: number;
+    phase: ServiceDrainPhase;
+    unfinishedOwners: readonly string[];
+    unfinishedOwnerCount: number;
+}>;
+/** Where SIGTERM drain stood; owners settle before listener, record, lease. */
+export type ServiceDrainPhase = "active" | "owners" | "listener" | "record" | "lease" | "closed";
+export type ServiceLogRecord = ServiceLogEvent & Readonly<{
+    source: "local-service";
+    timestamp: string;
+    pid: number;
+    version: string;
+}>;
+export type ServiceLogShutdownReason = Extract<ServiceLogEvent, {
+    event: "stopping" | "stopped";
+}>["reason"];
+export type ServiceLogLifecycle = Readonly<{
+    getStatus: () => ServiceDiagnosticsStatus;
+    ready: (serviceId: string) => void;
+    stopping: (reason: ServiceLogShutdownReason) => void;
+    failure: (failure: FailureMetadata) => void;
+    recoveryDisabled: (code: RecoveryPersistenceFailureCode) => void;
+    /** Synchronous, so it lands before the bounded drain exits the process. */
+    drainTimeout: (drain: Readonly<{
+        deadlineMs: number;
+        phase: ServiceDrainPhase;
+        unfinishedOwners: readonly string[];
+    }>) => void;
+    close: () => void;
+}>;
+/**
+ * Preserve ALL maintained count entries, in their producer order, when they fit.
+ * If they do not, explicitly omit the maps as a whole. No ranking/top-N policy,
+ * count substitution, exception serialization or byte-sliced JSON.
+ */
+export declare function encodeServiceLogRecord(record: ServiceLogRecord): string;
+/**
+ * One timer per service lifetime. The listener must close it before disposing
+ * the writer, and dispose the writer before releasing its existing owner lease.
+ * Both entry paths use this same owned resource.
+ */
+export declare function createServiceLogSampler(input: Readonly<{
+    readMemory: () => Readonly<{
+        rss: number;
+        heap: HeapStatistics;
+    }>;
+    emit: (event: ServiceLogEvent) => void;
+}>): {
+    start(): void;
+    close(): void;
+};
+/**
+ * Diagnostics resources only: no service lock, signal handler or runtime drain.
+ * The existing listener remains the owner. Native file I/O stays in this module.
+ * Writer faults latch a typed live failure, stop sampling and close once.
+ * They never escape into a request, turn, signal handler or timer callback.
+ */
+export declare function createServiceLogLifecycle(input: Readonly<{
+    pid: number;
+    version: string;
+    directory: string;
+    openWriter?: OpenServiceLogWriter;
+    readMemory: () => Readonly<{
+        rss: number;
+        heap: HeapStatistics;
+    }>;
+}>): ServiceLogLifecycle;