@fungi.computer/shiitake 0.0.0-stage → 0.0.1

package/dist/internal/woodstock/storage-admission.d.ts

@@ -0,0 +1,14 @@
+import type { StorageBudget } from "../contracts.js";
+/** The admission check for writes that start new work. */
+export type StorageAdmission = Readonly<{
+    /**
+     * Throw a typed `storage_pressure` refusal when the owner is near its
+     * budget. Called only for a new Session or a new prompt, never for a
+     * replayed request or for writes that finish admitted work.
+     */
+    admitNew: () => void;
+}>;
+/** The admission of a host that set no budget: nothing is refused. */
+export declare const admitWithoutBudget: StorageAdmission;
+/** Open the owner's admission check over the host's measured budget. */
+export declare function openStorageAdmission(budget: StorageBudget | undefined): StorageAdmission;

package/dist/internal/woodstock/storage-admission.js

@@ -0,0 +1,44 @@
+import * as Schema from "effect/Schema";
+import { ShiitakeError } from "../../errors.js";
+/**
+ * Provisional disk thresholds, as fractions of the host's budget. At
+ * `refuseAt` new Sessions and new prompts are refused; once refusing, they
+ * are admitted again only below `readmitBelow`, so admission does not flap
+ * while usage hovers at the threshold. The gap is the room the work already
+ * admitted keeps for finishing: its writes never pass through this check.
+ */
+const storagePressureThresholds = Object.freeze({
+    refuseAt: 0.8,
+    readmitBelow: 0.75,
+});
+const decodeBudgetBytes = Schema.decodeUnknownResult(Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))));
+const decodeUsedBytes = Schema.decodeUnknownResult(Schema.Number.pipe(Schema.check(Schema.isFinite()), Schema.check(Schema.isGreaterThanOrEqualTo(0))));
+/** The admission of a host that set no budget: nothing is refused. */
+export const admitWithoutBudget = Object.freeze({
+    admitNew: () => {
+        // No budget, so there is no storage pressure to refuse for.
+    },
+});
+/** Open the owner's admission check over the host's measured budget. */
+export function openStorageAdmission(budget) {
+    if (budget === undefined)
+        return admitWithoutBudget;
+    const budgetBytes = decodeBudgetBytes(budget.budgetBytes);
+    if (budgetBytes._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Storage budget must be a positive whole number of bytes");
+    const limit = budgetBytes.success;
+    let refusing = false;
+    return Object.freeze({
+        admitNew: () => {
+            const used = decodeUsedBytes(budget.usedBytes());
+            if (used._tag === "Failure")
+                throw new ShiitakeError("store", "unavailable", "Owner storage size is unavailable");
+            const fraction = used.success / limit;
+            refusing = refusing
+                ? fraction >= storagePressureThresholds.readmitBelow
+                : fraction >= storagePressureThresholds.refuseAt;
+            if (refusing)
+                throw new ShiitakeError("store", "storage_pressure", "Storage is near its budget. New Sessions and prompts are refused until space is freed; running work continues.");
+        },
+    });
+}

package/dist/model-preference.d.ts

@@ -0,0 +1,20 @@
+import * as JsonSchema from "effect/JsonSchema";
+import { ModelPreferenceSchema, parseModelPreference, parseModelPreferenceJson } from "./internal/model-preference.js";
+import type { ModelPreference } from "./internal/model-preference.js";
+export { ModelPreferenceSchema, parseModelPreference, parseModelPreferenceJson, };
+export type { ModelPreference } from "./internal/model-preference.js";
+/** JSON Schema generated from Shiitake's maintained model preference schema. */
+export declare const modelPreferenceJsonSchema: JsonSchema.JsonSchema;
+/** Parse the footer's provider/model spelling; model ids may contain slashes. */
+export declare function parseModelAddress(input: unknown): ModelPreference;
+/**
+ * Resolve host-owned defaults for a future run. Hosts supply offered, logged-in
+ * availability; an explicit choice never silently falls through on auth failure.
+ */
+export declare function resolveModelPreference(layers: Readonly<{
+    session?: ModelPreference | null | undefined;
+    agent?: ModelPreference | null | undefined;
+    manual?: ModelPreference | null | undefined;
+    team?: ModelPreference | null | undefined;
+    available?: ModelPreference | null | undefined;
+}>): ModelPreference | null;

package/dist/model-preference.js

@@ -0,0 +1,30 @@
+import * as JsonSchema from "effect/JsonSchema";
+import * as Schema from "effect/Schema";
+import { ModelPreferenceSchema, parseModelPreference, parseModelPreferenceJson, } from "./internal/model-preference.js";
+export { ModelPreferenceSchema, parseModelPreference, parseModelPreferenceJson, };
+/** JSON Schema generated from Shiitake's maintained model preference schema. */
+export const modelPreferenceJsonSchema = JsonSchema.toDocumentDraft07(Schema.toJsonSchemaDocument(ModelPreferenceSchema, {
+    onExcessProperty: "error",
+})).schema;
+const modelAddressSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^[^/\s]+\/[^\s]+$/u)), Schema.check(Schema.isMaxLength(513)));
+/** Parse the footer's provider/model spelling; model ids may contain slashes. */
+export function parseModelAddress(input) {
+    const address = Schema.decodeUnknownSync(modelAddressSchema)(input);
+    const slash = address.indexOf("/");
+    return Schema.decodeUnknownSync(ModelPreferenceSchema)({
+        providerId: address.slice(0, slash),
+        modelId: address.slice(slash + 1),
+    });
+}
+/**
+ * Resolve host-owned defaults for a future run. Hosts supply offered, logged-in
+ * availability; an explicit choice never silently falls through on auth failure.
+ */
+export function resolveModelPreference(layers) {
+    return (layers.session ??
+        layers.agent ??
+        layers.manual ??
+        layers.team ??
+        layers.available ??
+        null);
+}

package/dist/node.d.ts

@@ -0,0 +1,64 @@
+import type { Hono } from "hono";
+import { type ShiitakeHttpEnv } from "./http-routes.js";
+import type { RuntimeHost, ShiitakeOptions, ShiitakeOwnerAgent } from "./internal/contracts.js";
+/** The event-loop runtime host one Node process gives one durable Agent. */
+export type NodeRuntimeHost = Readonly<{
+    /** Pass as `runtime` to `Shiitake.make`. */
+    runtime: RuntimeHost;
+    /** Ask for a reconciliation at an epoch-millisecond time; null clears it. */
+    scheduleWake: (at: number | null) => void;
+    /** Stop waking and await the reconciliation in flight. */
+    close: () => Promise<void>;
+}>;
+/**
+ * The Node event loop as Shiitake's runtime host: one reconciliation at a
+ * time, re-run when woken during a pass, and a timer for the earliest due
+ * retry. It has no queue policy; Watchdog owns execution and retries.
+ * `observeFailure` sees a failed pass, which is retried after five seconds;
+ * if it throws, the throw is logged and the retry still happens.
+ */
+export declare function nodeRuntimeHost(observeFailure: (cause: unknown) => void): NodeRuntimeHost;
+/** An exclusive, process-held claim on one store file. */
+export type NodeStoreLease = Readonly<{
+    /** End the claim; later calls do nothing. */
+    release: () => void;
+}>;
+/**
+ * Claim one store for this process: an exclusive transaction held open on a
+ * sidecar file, so a second owner of the same store is refused at once and
+ * the claim ends with the process, never with a missed heartbeat.
+ */
+export declare function acquireNodeStoreLease(sidecarPath: string): NodeStoreLease;
+/** Everything a Node host supplies except the store and runtime it owns. */
+export type NodeShiitakeOptions = Omit<ShiitakeOptions, "store" | "runtime"> & Readonly<{
+    /**
+     * The SQLite file this Agent lives in; created when missing, private to
+     * this user. It may not be a symbolic link or have another hard link.
+     */
+    path: string;
+    /**
+     * Observe a failed reconciliation pass; it is retried after 5 seconds.
+     * Absent, the failure goes to Effect's logger.
+     */
+    onRuntimeFailure?: (cause: unknown) => void;
+}>;
+/** One durable Agent in a SQLite file, owned by this Node process. */
+export type NodeShiitake = Readonly<{
+    /** The in-process owner: sends, metadata views and grant deliveries. */
+    agent: ShiitakeOwnerAgent;
+    /**
+     * Shiitake's Session routes as a Hono app. Serve it with any Node or Bun
+     * server, behind host middleware that alone sets `shiitakeMeta`.
+     */
+    routes: Hono<ShiitakeHttpEnv>;
+    /** Stop waking, close the Agent, then release the store. */
+    close: () => Promise<void>;
+}>;
+/**
+ * Open one durable Agent in a SQLite file on disk. The process holds an
+ * exclusive lease on the store until `close`, so a second opener is refused.
+ * The store and its lease file are private to this user (0600), and a store
+ * reached through a symbolic link or with a second hard link is refused.
+ * Accepted work survives a restart: reopening the file resumes it.
+ */
+export declare function openNodeShiitake(options: NodeShiitakeOptions): Promise<NodeShiitake>;

package/dist/node.js

@@ -0,0 +1,256 @@
+import { closeSync, constants, fchmodSync, fstatSync, mkdirSync, openSync, realpathSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import * as Effect from "effect/Effect";
+import { fromNodeSqlite } from "@fungi.computer/watchdog/node-sqlite";
+import { createShiitakeHttpRoutes, } from "./http-routes.js";
+import { Shiitake } from "./index.js";
+/** A retry hint after a failed or still-pending reconciliation pass. */
+const retryAfterMs = 5_000;
+/**
+ * The Node event loop as Shiitake's runtime host: one reconciliation at a
+ * time, re-run when woken during a pass, and a timer for the earliest due
+ * retry. It has no queue policy; Watchdog owns execution and retries.
+ * `observeFailure` sees a failed pass, which is retried after five seconds;
+ * if it throws, the throw is logged and the retry still happens.
+ */
+export function nodeRuntimeHost(observeFailure) {
+    // A throwing observer must never cost the retry or crash the process.
+    const reportFailure = (cause) => {
+        try {
+            observeFailure(cause);
+        }
+        catch (observerCause) {
+            Effect.runFork(Effect.logError("shiitake_failure_observer_threw", {
+                cause: observerCause,
+                failure: String(cause),
+            }));
+        }
+    };
+    let bound;
+    let wakeTimer;
+    let wakeAt;
+    let closed = false;
+    const scheduleWake = (at) => {
+        if (closed)
+            return;
+        if (at === null) {
+            if (wakeTimer !== undefined)
+                clearTimeout(wakeTimer);
+            wakeTimer = undefined;
+            wakeAt = undefined;
+            return;
+        }
+        // Keep the earliest retry hint; later requests must not postpone it.
+        if (wakeTimer !== undefined && wakeAt !== undefined && at >= wakeAt)
+            return;
+        if (wakeTimer !== undefined)
+            clearTimeout(wakeTimer);
+        wakeAt = at;
+        wakeTimer = setTimeout(() => {
+            wakeTimer = undefined;
+            wakeAt = undefined;
+            void bound?.requestWake().catch(reportFailure);
+        }, Math.max(0, at - Date.now()));
+    };
+    const runtime = Object.freeze({
+        bind: ({ reconcile, pendingWork }) => {
+            if (bound !== undefined)
+                return Promise.reject(new Error("Shiitake Node runtime is already bound"));
+            let active;
+            let pending;
+            let rerun = false;
+            let closing;
+            const run = () => {
+                if (active !== undefined)
+                    return;
+                const task = Promise.resolve().then(async () => {
+                    try {
+                        await reconcile();
+                        const work = await pendingWork();
+                        scheduleWake(work.pending ? Date.now() + retryAfterMs : work.nextWakeAt);
+                    }
+                    catch (cause) {
+                        reportFailure(cause);
+                        scheduleWake(Date.now() + retryAfterMs);
+                    }
+                    finally {
+                        if (active === task)
+                            active = undefined;
+                        if (rerun) {
+                            rerun = false;
+                            // A wake admitted before close still drains its one rerun.
+                            if (closed)
+                                run();
+                            else
+                                schedule();
+                        }
+                    }
+                });
+                active = task;
+            };
+            const schedule = () => {
+                if (closed || active !== undefined || pending !== undefined)
+                    return;
+                pending = setImmediate(() => {
+                    pending = undefined;
+                    if (!closed)
+                        run();
+                });
+            };
+            const handle = Object.freeze({
+                commit: (mutation) => mutation(),
+                requestWake: () => {
+                    if (closed)
+                        return Promise.reject(new Error("Shiitake Node runtime is closed"));
+                    if (active !== undefined)
+                        rerun = true;
+                    else
+                        schedule();
+                    return Promise.resolve();
+                },
+                close: () => {
+                    closing ??= (async () => {
+                        closed = true;
+                        if (wakeTimer !== undefined)
+                            clearTimeout(wakeTimer);
+                        wakeTimer = undefined;
+                        wakeAt = undefined;
+                        if (pending !== undefined)
+                            clearImmediate(pending);
+                        pending = undefined;
+                        while (active !== undefined)
+                            await active;
+                    })();
+                    return closing;
+                },
+            });
+            schedule();
+            bound = handle;
+            return Promise.resolve(handle);
+        },
+    });
+    return Object.freeze({
+        runtime,
+        scheduleWake,
+        close: () => bound?.close() ?? Promise.resolve(),
+    });
+}
+/**
+ * Claim one store for this process: an exclusive transaction held open on a
+ * sidecar file, so a second owner of the same store is refused at once and
+ * the claim ends with the process, never with a missed heartbeat.
+ */
+export function acquireNodeStoreLease(sidecarPath) {
+    const database = new DatabaseSync(sidecarPath, { timeout: 0 });
+    try {
+        database.exec("PRAGMA busy_timeout = 0");
+        database.exec("PRAGMA journal_mode = DELETE");
+        database.exec("BEGIN EXCLUSIVE");
+    }
+    catch (cause) {
+        database.close();
+        throw cause;
+    }
+    let released = false;
+    return Object.freeze({
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                database.exec("ROLLBACK");
+            }
+            finally {
+                database.close();
+            }
+        },
+    });
+}
+/**
+ * Create or open one store file for this process alone: never through a
+ * symbolic link, never a file with a second hard link (either would let a
+ * second owner claim the same bytes under another name), and readable by
+ * this user only, whatever the umask.
+ */
+function claimPrivateFile(path) {
+    const descriptor = openSync(path, constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+        const metadata = fstatSync(descriptor);
+        if (!metadata.isFile() || metadata.nlink !== 1)
+            throw new Error(`Shiitake Node store must be one regular file with one name: ${path}`);
+        fchmodSync(descriptor, 0o600);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/**
+ * The one name every opener of a store agrees on: its real directory (created
+ * private when missing) and its own file name, so a linked directory still
+ * meets the same lease.
+ */
+function canonicalStorePath(path) {
+    const directory = dirname(resolve(path));
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    return join(realpathSync(directory), basename(path));
+}
+/**
+ * Open one durable Agent in a SQLite file on disk. The process holds an
+ * exclusive lease on the store until `close`, so a second opener is refused.
+ * The store and its lease file are private to this user (0600), and a store
+ * reached through a symbolic link or with a second hard link is refused.
+ * Accepted work survives a restart: reopening the file resumes it.
+ */
+export async function openNodeShiitake(options) {
+    const { path: requested, onRuntimeFailure, ...shiitakeOptions } = options;
+    const path = canonicalStorePath(requested);
+    const sidecarPath = `${path}.owner.sqlite`;
+    claimPrivateFile(sidecarPath);
+    const lease = acquireNodeStoreLease(sidecarPath);
+    let database;
+    let host;
+    try {
+        // Checked under the lease: a link made after this is refused by the next
+        // opener's own check, before it can open the bytes.
+        claimPrivateFile(path);
+        const opened = new DatabaseSync(path, { timeout: 0 });
+        database = opened;
+        opened.exec("PRAGMA foreign_keys = ON");
+        const runtime = nodeRuntimeHost(onRuntimeFailure ??
+            ((cause) => {
+                Effect.runFork(Effect.logError("shiitake_reconciliation_failed").pipe(Effect.annotateLogs({ cause: String(cause) })));
+            }));
+        host = runtime;
+        const agent = await Shiitake.make({
+            ...shiitakeOptions,
+            store: fromNodeSqlite(opened),
+            runtime: runtime.runtime,
+        });
+        const routes = createShiitakeHttpRoutes((sessionId, meta) => (meta === undefined ? agent : agent.withMeta(meta)).session(sessionId), agent.listSessions, agent.createSession, agent.deleteSession, () => agent.extensions);
+        let closing;
+        return Object.freeze({
+            agent,
+            routes,
+            close: () => {
+                closing ??= (async () => {
+                    try {
+                        await agent.close();
+                        await runtime.close();
+                    }
+                    finally {
+                        opened.close();
+                        lease.release();
+                    }
+                })();
+                return closing;
+            },
+        });
+    }
+    catch (cause) {
+        await host?.close();
+        database?.close();
+        lease.release();
+        throw cause;
+    }
+}

package/dist/remote-client.d.ts

@@ -0,0 +1,11 @@
+import type { ShiitakeEventSourceConstructor, ShiitakeAgent } from "./client.js";
+/** Network location of one remotely hosted Shiitake agent. */
+export type ShiitakeClientOptions = Readonly<{
+    baseUrl: string;
+    /** Host-owned HTTP transport, including authenticated internal bindings. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional runtime EventSource constructor; browsers use the global by default. */
+    eventSource?: ShiitakeEventSourceConstructor;
+}>;
+/** Connect to a remotely hosted Shiitake agent. */
+export declare function createShiitakeClient(options: ShiitakeClientOptions): ShiitakeAgent;