@fungi.computer/truffle 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,321 @@
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import { join } from "node:path";
+import { localFailureMetadata, logEvent } from "./log-event.js";
+import { z } from "zod";
+export const serviceLogRecordBytes = 32 * 1024;
+const serviceLogFileBytes = 1024 * 1024;
+const serviceLogBackupFiles = 3;
+export const serviceLogSampleIntervalMs = 5 * 60 * 1000;
+export const serviceDiagnosticsStatusSchema = z.discriminatedUnion("state", [
+    z.strictObject({ state: z.literal("active") }),
+    z.strictObject({
+        state: z.literal("failed"),
+        code: z.enum([
+            "sink-open-failed",
+            "sink-write-failed",
+            "sink-close-failed",
+        ]),
+        since: z.iso.datetime(),
+    }),
+    z.strictObject({
+        state: z.literal("recovery-disabled"),
+        code: z.enum(["read-failed", "decode-failed"]),
+        since: z.iso.datetime(),
+    }),
+]);
+function privateLogFileSize(file) {
+    if (!file.isFile() || (file.mode & 0o777) !== 0o600)
+        throw new Error("Diagnostic log is not a private regular file");
+    if (file.size > serviceLogFileBytes)
+        throw new Error("Diagnostic log exceeds its file byte bound");
+    return file.size;
+}
+function existingLogArchive(path) {
+    try {
+        return fs.statSync(path);
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+}
+/**
+ * Exactly four owned names, each at most 1 MiB. Rotation happens BEFORE append,
+ * oldest destination first; each rename either succeeds or throws to the
+ * resource's Option2 latch. Replacing .3 cannot add a fifth file or extra bytes.
+ * No retries, asynchronous work, chmod repair or second lifecycle owner.
+ */
+function openNativeServiceLogWriter(directory) {
+    const path = join(directory, "service.jsonl");
+    for (let index = 1; index <= serviceLogBackupFiles; index++) {
+        const file = existingLogArchive(`${path}.${String(index)}`);
+        if (file !== undefined)
+            privateLogFileSize(file);
+    }
+    let descriptor;
+    const currentDescriptor = () => {
+        if (descriptor === undefined)
+            throw new Error("Diagnostic log is closed");
+        return descriptor;
+    };
+    const close = () => {
+        const fd = descriptor;
+        // Retire before calling the runtime: never close a reused descriptor.
+        descriptor = undefined;
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    };
+    const open = () => {
+        descriptor = fs.openSync(path, "a", 0o600);
+        try {
+            privateLogFileSize(fs.fstatSync(descriptor));
+        }
+        catch (cause) {
+            try {
+                close();
+            }
+            catch (closeCause) {
+                logEvent("service-log.open-close", closeCause);
+            }
+            throw cause;
+        }
+    };
+    const rotate = () => {
+        close();
+        for (let index = serviceLogBackupFiles - 1; index >= 1; index--) {
+            const source = `${path}.${String(index)}`;
+            const file = existingLogArchive(source);
+            if (file === undefined)
+                continue; // only genuinely absent archive slots
+            privateLogFileSize(file);
+            fs.renameSync(source, `${path}.${String(index + 1)}`);
+        }
+        // Unlike optional archives, the active pathname MUST exist.
+        fs.renameSync(path, `${path}.1`);
+        open();
+    };
+    open();
+    return {
+        writeLine(line) {
+            const bytes = Buffer.byteLength(line, "utf8");
+            if (bytes > serviceLogRecordBytes)
+                throw new Error("Diagnostic record exceeds its byte bound");
+            const size = privateLogFileSize(fs.fstatSync(currentDescriptor()));
+            if (size + bytes > serviceLogFileBytes)
+                rotate();
+            const written = fs.writeSync(currentDescriptor(), line, null, "utf8");
+            if (written !== bytes)
+                throw new Error("Diagnostic log short write");
+        },
+        close,
+    };
+}
+/** A drain-timeout record names at most this many unfinished owners. */
+const drainTimeoutOwnerLimit = 32;
+function omissionSummary(counts) {
+    return {
+        status: "omitted-byte-bound",
+        typeCount: Object.keys(counts).length,
+        allocatedCells: Object.values(counts).reduce((sum, count) => sum + count, 0),
+    };
+}
+/**
+ * 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 function encodeServiceLogRecord(record) {
+    const line = JSON.stringify(record) + "\n";
+    const encodedBytes = Buffer.byteLength(line, "utf8");
+    if (encodedBytes <= serviceLogRecordBytes)
+        return line;
+    if (record.event === "memory") {
+        const summary = JSON.stringify({
+            ...record,
+            heap: {
+                ...record.heap,
+                objectTypeCounts: omissionSummary(record.heap.objectTypeCounts),
+                protectedObjectTypeCounts: omissionSummary(record.heap.protectedObjectTypeCounts),
+            },
+            omittedRecordBytes: encodedBytes,
+        }) + "\n";
+        if (Buffer.byteLength(summary, "utf8") <= serviceLogRecordBytes)
+            return summary;
+    }
+    // Only fixed classification and numeric size survive an oversized record.
+    return (JSON.stringify({
+        source: "local-service",
+        timestamp: record.timestamp,
+        pid: record.pid,
+        event: "record-omitted",
+        recordEvent: record.event,
+        encodedBytes,
+    }) + "\n");
+}
+/**
+ * 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 function createServiceLogSampler(input) {
+    let timer;
+    let closed = false;
+    return {
+        start() {
+            if (closed)
+                throw new Error("Cannot restart a disposed service log sampler");
+            if (timer !== undefined)
+                return;
+            timer = setInterval(() => {
+                let memory;
+                try {
+                    memory = input.readMemory();
+                }
+                catch (cause) {
+                    logEvent("service-log.sample", cause);
+                    input.emit({
+                        event: "memory-unavailable",
+                        failure: localFailureMetadata("service-log.sample", cause),
+                    });
+                    return;
+                }
+                // A sink failure must stay observable, not be mislabeled heap failure.
+                input.emit({ event: "memory", ...memory });
+            }, serviceLogSampleIntervalMs);
+            timer.unref();
+        },
+        close() {
+            closed = true;
+            if (timer !== undefined)
+                clearInterval(timer);
+            timer = undefined;
+        },
+    };
+}
+/**
+ * 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 function createServiceLogLifecycle(input) {
+    let ready = false;
+    let closed = false;
+    let reason;
+    let status = { state: "active" };
+    let recovery;
+    let writer;
+    let writerClosed = false;
+    const closeWriter = () => {
+        if (writerClosed)
+            return;
+        writerClosed = true;
+        try {
+            writer?.close();
+        }
+        catch (cause) {
+            if (status.state === "active")
+                status = {
+                    state: "failed",
+                    code: "sink-close-failed",
+                    since: new Date().toISOString(),
+                };
+            logEvent("service-log.close", cause);
+        }
+    };
+    const fail = (code) => {
+        if (status.state === "failed")
+            return;
+        status = { state: "failed", code, since: new Date().toISOString() };
+        sampler.close();
+        closeWriter();
+    };
+    const emit = (event) => {
+        if (closed || status.state === "failed")
+            return;
+        try {
+            if (writer === undefined)
+                throw new Error("Diagnostic writer did not open");
+            writer.writeLine(encodeServiceLogRecord({
+                ...event,
+                source: "local-service",
+                timestamp: new Date().toISOString(),
+                pid: input.pid,
+                version: input.version,
+            }));
+        }
+        catch (cause) {
+            // Publish failure before disposal/reporting: even a reentrant status read
+            // sees the first code/time. No further writer call or retry is permitted.
+            fail("sink-write-failed");
+            logEvent("service-log.write", cause);
+        }
+    };
+    const sampler = createServiceLogSampler({
+        readMemory: input.readMemory,
+        emit,
+    });
+    try {
+        writer = (input.openWriter ?? openNativeServiceLogWriter)(input.directory);
+    }
+    catch (cause) {
+        fail("sink-open-failed");
+        logEvent("service-log.open", cause);
+    }
+    emit({ event: "starting" });
+    return {
+        // A sink failure still takes precedence: it means diagnostics cannot be
+        // persisted at all. Recovery disablement must not stop a working log sink.
+        getStatus: () => status.state === "failed" ? status : (recovery ?? status),
+        ready(serviceId) {
+            if (closed || ready)
+                return;
+            emit({ event: "ready", serviceId });
+            ready = true;
+            if (status.state === "active")
+                sampler.start();
+        },
+        stopping(observedReason) {
+            if (reason !== undefined)
+                return;
+            reason = observedReason;
+            sampler.close();
+            emit({ event: "stopping", reason });
+        },
+        failure(failure) {
+            emit({ event: "failure", failure });
+        },
+        recoveryDisabled(code) {
+            if (closed || recovery !== undefined)
+                return;
+            recovery = {
+                state: "recovery-disabled",
+                code,
+                since: new Date().toISOString(),
+            };
+            emit({ event: "recovery-persistence-disabled", code });
+        },
+        drainTimeout(drain) {
+            // Owner names only (Agent IDs or store keys), never exception or input
+            // text. The record encoder still enforces the per-record byte bound.
+            emit({
+                event: "drain-timeout",
+                deadlineMs: drain.deadlineMs,
+                phase: drain.phase,
+                unfinishedOwners: drain.unfinishedOwners.slice(0, drainTimeoutOwnerLimit),
+                unfinishedOwnerCount: drain.unfinishedOwners.length,
+            });
+        },
+        close() {
+            if (closed)
+                return;
+            sampler.close();
+            if (reason !== undefined)
+                emit({ event: "stopped", reason });
+            closeWriter();
+            closed = true;
+        },
+    };
+}

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

@@ -0,0 +1,135 @@
+import type { Accepted, CancelResult } from "@fungi.computer/shiitake";
+import { type PrivateLocalConfigRoot } from "./private-local-config-root.js";
+import type { ServiceLogLifecycle } from "./private-local-service-log.js";
+import type { StopAllResult } from "./private-local-stop-all.js";
+import { type LocalExtensions } from "./local-extensions.js";
+import type { PrivateLocalServiceSelection, PrivateLocalSessionCreation } from "./private-local-service-contract.js";
+import { openPrivateLocalRuntimeHost, type PrivateLocalRuntimeHost } from "./private-local-runtime-host.js";
+import type { LocalUiAttachment } from "./private-local-ui-attachment.js";
+export type LocalServiceRuntime = Pick<PrivateLocalRuntimeHost, "databasePath" | "agentId" | "name" | "getSession" | "effectiveModel" | "setModel" | "setArchived" | "setRequireSandbox" | "sandboxStatus" | "pendingDelegation" | "assertModelReady" | "listSessions" | "createSession" | "deleteSession" | "extensions" | "prepareReload" | "bindSessionPath" | "acceptMail" | "readSettlement" | "idle" | "close">;
+export declare class LocalSessionPathConflict extends Error {
+    readonly name = "LocalSessionPathConflict";
+    constructor();
+}
+/**
+ * A folder holds several Agent stores and the request chose none of them.
+ * The service never picks one for the caller; --agent, --db or the
+ * landing screen does.
+ */
+export declare class LocalAgentSelectionAmbiguous extends Error {
+    readonly name = "LocalAgentSelectionAmbiguous";
+    readonly agentIds: readonly string[];
+    constructor(agentIds: readonly string[]);
+}
+export type OpenLocalServiceRuntime = (
+/** Selected by the service, never by a client selection or Agent Files root. */
+options: Parameters<typeof openPrivateLocalRuntimeHost>[0] & Readonly<{
+    configRoot: PrivateLocalConfigRoot;
+}>) => Promise<LocalServiceRuntime>;
+/** One service owns each store, independently of how many clients select it. */
+export declare function createLocalServiceOwners(openRuntime?: OpenLocalServiceRuntime, recoveryDirectory?: string, 
+/** The installed-extension owner that decides what each Agent holds. */
+suppliedExtensions?: Pick<LocalExtensions, "assertHeldByAgent" | "enableAgent">, 
+/** How often idle Agents are checked; one is released on its second idle check. */
+idleSweepMs?: number, 
+/** Read the recovery manifest; tests can hold this I/O independently of opens. */
+readRecoveryManifest?: (path: string) => Promise<string>, 
+/** Report only the classification, never the manifest or exception text. */
+onRecoveryDisabled?: ServiceLogLifecycle["recoveryDisabled"], configRoot?: PrivateLocalConfigRoot): {
+    refreshMesh: () => Promise<void>;
+    createSession: (creation: PrivateLocalSessionCreation) => Promise<{
+        agentId: string;
+        databasePath: string;
+        invocationRoot: string;
+        sessionId: string;
+        session: Readonly<{
+            address: string;
+            command: import("@fungi.computer/shiitake").SessionCommandHandler;
+            withdraw: (requestId: string) => Promise<import("@fungi.computer/shiitake/client").WithdrawResult>;
+            abort: () => Promise<void>;
+            send: (text: string, options?: import("@fungi.computer/shiitake").SendOptions) => Promise<Accepted>;
+            cancel: (input: Readonly<{
+                commandId: string;
+                onlyIfPending?: boolean;
+            }>) => Promise<CancelResult>;
+            latestPending: () => Promise<import("@fungi.computer/shiitake/client").SessionPendingPrompt | null>;
+            extension: (extensionId: string) => import("@fungi.computer/shiitake").SessionExtensionControls;
+            modelPreference: Readonly<{
+                read: () => Promise<import("@fungi.computer/shiitake").ModelPreference | null>;
+                set: (preference: import("@fungi.computer/shiitake").ModelPreference | null) => Promise<void>;
+            }>;
+            read: (input?: import("@fungi.computer/shiitake").ReadOptions) => Promise<import("@fungi.computer/shiitake").SessionSnapshot>;
+            subscribe: (input: import("@fungi.computer/shiitake").SubscribeOptions) => AsyncIterable<import("@fungi.computer/shiitake").SessionFrame>;
+            watch: (input?: import("@fungi.computer/shiitake").WatchOptions) => Promise<import("@fungi.computer/shiitake").SessionWatch>;
+        }>;
+        /** End this selection's use; the mounted route reopens the Agent later. */
+        release: () => void;
+    }>;
+    select: (selection: PrivateLocalServiceSelection, createRequestId?: string) => Promise<{
+        agentId: string;
+        databasePath: string;
+        invocationRoot: string;
+        sessionId: string;
+        session: Readonly<{
+            address: string;
+            command: import("@fungi.computer/shiitake").SessionCommandHandler;
+            withdraw: (requestId: string) => Promise<import("@fungi.computer/shiitake/client").WithdrawResult>;
+            abort: () => Promise<void>;
+            send: (text: string, options?: import("@fungi.computer/shiitake").SendOptions) => Promise<Accepted>;
+            cancel: (input: Readonly<{
+                commandId: string;
+                onlyIfPending?: boolean;
+            }>) => Promise<CancelResult>;
+            latestPending: () => Promise<import("@fungi.computer/shiitake/client").SessionPendingPrompt | null>;
+            extension: (extensionId: string) => import("@fungi.computer/shiitake").SessionExtensionControls;
+            modelPreference: Readonly<{
+                read: () => Promise<import("@fungi.computer/shiitake").ModelPreference | null>;
+                set: (preference: import("@fungi.computer/shiitake").ModelPreference | null) => Promise<void>;
+            }>;
+            read: (input?: import("@fungi.computer/shiitake").ReadOptions) => Promise<import("@fungi.computer/shiitake").SessionSnapshot>;
+            subscribe: (input: import("@fungi.computer/shiitake").SubscribeOptions) => AsyncIterable<import("@fungi.computer/shiitake").SessionFrame>;
+            watch: (input?: import("@fungi.computer/shiitake").WatchOptions) => Promise<import("@fungi.computer/shiitake").SessionWatch>;
+        }>;
+        /** End this selection's use; the mounted route reopens the Agent later. */
+        release: () => void;
+    }>;
+    serve: (selection: Pick<PrivateLocalServiceSelection, "invocationRoot" | "databasePath" | "fungiMcp">, request: Request, attachment?: LocalUiAttachment) => Promise<Response>;
+    effectiveModel: (selection: Pick<PrivateLocalServiceSelection, "invocationRoot" | "databasePath" | "fungiMcp">, sessionId: string, signal: AbortSignal) => Promise<{
+        agentName: "Shiitake";
+        providerId: string;
+        providerName: string;
+        modelId: string;
+        modelName: string;
+        credential: {
+            kind: "oauth" | "api_key" | "missing";
+            source: string;
+        };
+        label: string;
+        reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    }>;
+    sandboxStatus: (selection: Pick<PrivateLocalServiceSelection, "invocationRoot" | "databasePath" | "fungiMcp">, signal: AbortSignal) => Promise<{
+        state: "available";
+        requireSandbox: boolean;
+    } | {
+        state: "unavailable";
+        requireSandbox: boolean;
+        reason: {
+            kind: "missing" | "invalid-digest" | "digest-mismatch" | "not-executable" | "unsupported-platform" | "invalid-folder" | "backend-refused";
+            message: string;
+        };
+    }>;
+    sweepIdle: () => Promise<void>;
+    archive: (request: Readonly<{
+        invocationRoot: string;
+        agentId: string;
+        archived: boolean;
+    }>, signal: AbortSignal) => Promise<void>;
+    stopAll: (request: Readonly<{
+        invocationRoot: string;
+        agentId: string;
+    }>) => Promise<StopAllResult>;
+    restore: () => Promise<void>;
+    close: () => Promise<void>;
+    reload: (invocationRoot: string, clientPath: string) => Promise<void>;
+    unfinishedOwners: () => string[];
+};