@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/remote-client.js

@@ -0,0 +1,298 @@
+import { nanoid } from "@fungi.computer/cairn";
+import { parseModelPreferenceJson } from "./internal/model-preference.js";
+import * as Effect from "effect/Effect";
+import * as Cause from "effect/Cause";
+import * as Latch from "effect/Latch";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { parseAccepted, parseCancelResult, parseForkedSession, parseCreatedSession, parseDeletedSession, parseExtensionOutput, parseExtensionStatus, parseExtensionStatuses, parseSessionFrame, parseSessionSnapshot, parseSessionSummaryPage, parseShiitakeError, } from "./client-wire.js";
+import { ShiitakeError } from "./errors.js";
+import { decodeClientReadOptions, decodeClientSessionCreationRequestId, decodeClientPageCursor, decodeClientSessionId, decodeClientSubscribeOptions, } from "./internal/client-boundary.js";
+import { toPromiseAgent } from "./internal/effect-client.js";
+function unavailable(message = "Remote Shiitake operation is unavailable") {
+    return new ShiitakeError("runtime", "unavailable", message);
+}
+function invalid(message) {
+    return new ShiitakeError("runtime", "invalid", message);
+}
+function clientClosedError() {
+    return new ShiitakeError("runtime", "closed", "Shiitake client is closed");
+}
+const closedEventSourceReadyState = 2;
+const decodeEventData = Schema.decodeUnknownSync(Schema.String);
+function eventData(event) {
+    if (!(event instanceof MessageEvent))
+        throw invalid("Session stream event is invalid");
+    return decodeEventData(event.data);
+}
+function decodeRemoteEvent(input) {
+    if (input.kind === "source-error")
+        return Effect.fail(unavailable("Session stream is unavailable"));
+    if (input.kind === "snapshot")
+        return Effect.try({
+            try: () => ({
+                kind: "snapshot",
+                value: parseSessionSnapshot(eventData(input.event)),
+            }),
+            catch: () => invalid("Session snapshot is invalid"),
+        });
+    if (input.kind === "frame")
+        return Effect.try({
+            try: () => ({
+                kind: "frame",
+                value: parseSessionFrame(eventData(input.event)),
+            }),
+            catch: () => invalid("Session frame is invalid"),
+        });
+    return Effect.try({
+        try: () => parseShiitakeError(eventData(input.event)),
+        catch: () => invalid("Session runtime error is invalid"),
+    }).pipe(Effect.flatMap(Effect.fail));
+}
+function closeRemoteSource(active, sources) {
+    return Effect.sync(() => {
+        if (active.closed)
+            return;
+        active.closed = true;
+        sources.delete(active);
+        active.source.close();
+    });
+}
+function remoteEvents(url, clientClosed, sources, eventSource) {
+    return Stream.callback((queue) => Effect.acquireRelease(Effect.try({
+        try: () => {
+            const constructor = eventSource ?? EventSource;
+            const active = {
+                source: new constructor(url),
+                closed: false,
+            };
+            const emit = (kind, event) => {
+                Queue.offerUnsafe(queue, { kind, event });
+            };
+            active.source.addEventListener("snapshot", (event) => {
+                emit("snapshot", event);
+            });
+            active.source.addEventListener("frame", (event) => {
+                emit("frame", event);
+            });
+            active.source.addEventListener("runtime-error", (event) => {
+                emit("runtime-error", event);
+            });
+            active.source.addEventListener("error", (event) => {
+                if (active.source.readyState === closedEventSourceReadyState)
+                    emit("source-error", event);
+            });
+            sources.add(active);
+            return active;
+        },
+        catch: () => unavailable("Session stream could not open"),
+    }), (active) => closeRemoteSource(active, sources))).pipe(Stream.mapEffect(decodeRemoteEvent), Stream.interruptWhen(clientClosed.await));
+}
+function sessionUrl(baseUrl, sessionId) {
+    return `${baseUrl}/sessions/${encodeURIComponent(sessionId)}`;
+}
+function subscriptionEventsPath(eventsUrl, after, includeSandboxFailures = false) {
+    const query = new URLSearchParams({ mode: "subscribe" });
+    if (after !== undefined)
+        query.set("after", after);
+    if (includeSandboxFailures)
+        query.set("includeSandboxFailures", "true");
+    return `${eventsUrl}?${query.toString()}`;
+}
+function remoteFrames(url, clientClosed, sources, eventSource) {
+    return remoteEvents(url, clientClosed, sources, eventSource).pipe(Stream.mapEffect((event) => event.kind === "frame"
+        ? Effect.succeed(event.value)
+        : Effect.fail(invalid("Session subscription received a snapshot"))));
+}
+function openRemoteWatch(url, scopes, ensureOpen, clientClosed, sources, eventSource) {
+    return Effect.gen(function* () {
+        yield* ensureOpen;
+        const watchClosed = yield* Latch.make(false);
+        const scope = yield* Scope.make();
+        yield* Effect.sync(() => scopes.add(scope));
+        yield* Scope.addFinalizer(scope, Effect.sync(() => {
+            scopes.delete(scope);
+        }));
+        const opened = yield* Effect.exit(remoteEvents(url, clientClosed, sources, eventSource).pipe(Stream.peel(Sink.head()), Scope.provide(scope)));
+        if (Exit.isFailure(opened)) {
+            yield* Scope.close(scope, opened);
+            return yield* Effect.failCause(opened.cause);
+        }
+        const [first, remaining] = opened.value;
+        if (Option.isNone(first) || first.value.kind !== "snapshot") {
+            const error = invalid("Session stream did not begin with a snapshot");
+            yield* Scope.close(scope, Exit.fail(error));
+            return yield* Effect.fail(error);
+        }
+        const changes = remaining.pipe(Stream.mapEffect((event) => event.kind === "frame"
+            ? Effect.succeed(event.value)
+            : Effect.succeed({
+                kind: "reset",
+                reason: "history_unavailable",
+                cursor: event.value.cursor,
+                baseline: event.value,
+            })), Stream.interruptWhen(watchClosed.await), Stream.catchCause((cause) => watchClosed.isOpen() && Cause.hasInterruptsOnly(cause)
+            ? Stream.empty
+            : Stream.failCause(cause)));
+        return Object.freeze({
+            snapshot: first.value.value,
+            changes,
+            close: watchClosed.open.pipe(Effect.andThen(Scope.close(scope, Exit.void))),
+        });
+    });
+}
+function parseResponse(send, parse, description) {
+    return Effect.tryPromise({
+        try: async (signal) => {
+            const response = await send(signal);
+            return { response, body: await response.text() };
+        },
+        catch: () => unavailable(`${description} request failed`),
+    }).pipe(Effect.flatMap(({ response, body }) => {
+        if (!response.ok)
+            return Effect.try({
+                try: () => parseShiitakeError(body),
+                catch: () => invalid(`${description} error response is invalid`),
+            }).pipe(Effect.flatMap(Effect.fail));
+        return Effect.try({
+            try: () => parse(body),
+            catch: () => invalid(`${description} response is invalid`),
+        });
+    }));
+}
+function makeRemoteEffectAgent(options) {
+    const baseUrl = options.baseUrl.replace(/\/+$/u, "");
+    const fetch = options.fetch ?? globalThis.fetch;
+    const scopes = new Set();
+    const sources = new Set();
+    const clientClosed = Latch.makeUnsafe(false);
+    let closed = false;
+    const ensureOpen = Effect.suspend(() => closed ? Effect.fail(clientClosedError()) : Effect.void);
+    const request = (send, parse, description) => Effect.raceFirst(parseResponse(send, parse, description), clientClosed.await.pipe(Effect.andThen(Effect.fail(clientClosedError()))));
+    /** The one generic extension command fetcher (session or agent scope). */
+    const callExtension = (url, input) => ensureOpen.pipe(Effect.andThen(request((signal) => fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+        signal,
+    }), parseExtensionOutput, "Extension command")));
+    const session = (sessionIdInput) => {
+        const sessionId = decodeClientSessionId(sessionIdInput);
+        const addressedUrl = sessionUrl(baseUrl, sessionId);
+        const eventsUrl = `${addressedUrl}/events`;
+        function command(input) {
+            return ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${addressedUrl}/command`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ command: input }),
+                signal,
+            }), input.type === "prompt" || input.type === "compact"
+                ? parseAccepted
+                : input.type === "cancel"
+                    ? parseCancelResult
+                    : input.type === "fork"
+                        ? parseForkedSession
+                        : () => undefined, "Command")));
+        }
+        return Object.freeze({
+            command,
+            abort: command({ type: "abort" }),
+            send: (text, sendOptions) => Effect.sync(() => sendOptions?.requestId ?? nanoid()).pipe(Effect.flatMap((requestId) => {
+                const prompt = {
+                    type: "prompt",
+                    delivery: sendOptions?.delivery ?? "steer",
+                    requestId,
+                    text,
+                };
+                return command(sendOptions?.images === undefined
+                    ? prompt
+                    : { ...prompt, images: sendOptions.images }).pipe(Effect.mapError((error) => error.requestId === requestId
+                    ? error
+                    : new ShiitakeError(error.boundary, error.cause, error.message, requestId)));
+            })),
+            cancel: (input) => command({ type: "cancel", ...input }),
+            modelPreference: Object.freeze({
+                read: ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${addressedUrl}/model-preference`, { signal }), parseModelPreferenceJson, "Model preference read"))),
+                set: (preference) => ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${addressedUrl}/model-preference`, {
+                    signal,
+                    method: "PUT",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(preference),
+                }), () => undefined, "Model preference set"))),
+            }),
+            extension: (extensionId) => Object.freeze({
+                call: (command, input) => callExtension(`${addressedUrl}/extensions/${encodeURIComponent(extensionId)}/commands/${encodeURIComponent(command)}`, input),
+            }),
+            read: (input) => ensureOpen.pipe(Effect.andThen(Effect.try({
+                try: () => decodeClientReadOptions(input),
+                catch: (error) => error instanceof ShiitakeError
+                    ? error
+                    : invalid("Read options are invalid"),
+            })), Effect.flatMap(({ limit, before, includeSandboxFailures }) => {
+                const params = new URLSearchParams({ limit: String(limit) });
+                if (before !== undefined)
+                    params.set("before", before);
+                if (includeSandboxFailures === true)
+                    params.set("includeSandboxFailures", "true");
+                return request((signal) => fetch(`${addressedUrl}?${params.toString()}`, { signal }), parseSessionSnapshot, "Session read");
+            })),
+            subscribe: (input) => Stream.unwrap(ensureOpen.pipe(Effect.andThen(Effect.try({
+                try: () => decodeClientSubscribeOptions(input),
+                catch: (error) => error instanceof ShiitakeError
+                    ? error
+                    : invalid("Subscribe options are invalid"),
+            })), Effect.map(({ after, includeSandboxFailures }) => remoteFrames(subscriptionEventsPath(eventsUrl, after, includeSandboxFailures === true), clientClosed, sources, options.eventSource)))),
+            watch: (input) => openRemoteWatch(input?.includeSandboxFailures === true
+                ? `${eventsUrl}?includeSandboxFailures=true`
+                : eventsUrl, scopes, ensureOpen, clientClosed, sources, options.eventSource),
+        });
+    };
+    return Object.freeze({
+        createSession: (requestIdInput) => ensureOpen.pipe(Effect.flatMap(() => {
+            const requestId = decodeClientSessionCreationRequestId({
+                requestId: requestIdInput,
+            });
+            return request((signal) => fetch(`${baseUrl}/sessions`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ requestId }),
+                signal,
+            }), parseCreatedSession, "Session creation");
+        })),
+        deleteSession: (sessionIdInput) => ensureOpen.pipe(Effect.flatMap(() => {
+            const sessionId = decodeClientSessionId(sessionIdInput);
+            return request((signal) => fetch(`${baseUrl}/sessions/${encodeURIComponent(sessionId)}`, {
+                method: "DELETE",
+                signal,
+            }), parseDeletedSession, "Session deletion");
+        })),
+        listSessions: (after) => ensureOpen.pipe(Effect.flatMap(() => {
+            const query = new URLSearchParams();
+            if (after !== undefined)
+                query.set("after", decodeClientPageCursor(after));
+            const suffix = query.size === 0 ? "" : `?${query.toString()}`;
+            return request((signal) => fetch(`${baseUrl}/sessions${suffix}`, { signal }), parseSessionSummaryPage, "Session discovery");
+        })),
+        extensions: Object.freeze({
+            list: ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${baseUrl}/extensions`, { signal }), parseExtensionStatuses, "Extension list"))),
+            resume: (extensionId) => ensureOpen.pipe(Effect.andThen(request((signal) => fetch(`${baseUrl}/extensions/${encodeURIComponent(extensionId)}/resume`, { method: "POST", signal }), parseExtensionStatus, "Extension resume"))),
+            call: (extensionId, command, input) => callExtension(`${baseUrl}/extensions/${encodeURIComponent(extensionId)}/commands/${encodeURIComponent(command)}`, input),
+        }),
+        session,
+        close: Effect.suspend(() => {
+            if (closed)
+                return Effect.void;
+            closed = true;
+            return clientClosed.open.pipe(Effect.andThen(Effect.forEach([...scopes], (scope) => Scope.close(scope, Exit.void), { discard: true })), Effect.andThen(Effect.forEach([...sources], (active) => closeRemoteSource(active, sources), { discard: true })));
+        }),
+    });
+}
+/** Connect to a remotely hosted Shiitake agent. */
+export function createShiitakeClient(options) {
+    return toPromiseAgent(makeRemoteEffectAgent(options), options.baseUrl.replace(/\/+$/u, ""));
+}

package/dist/session-attention.d.ts

@@ -0,0 +1,35 @@
+import * as Schema from "effect/Schema";
+/** An extension-owned request for human attention; expiry is owned by its timer. */
+export declare const AttentionItemSchema: Schema.Struct<{
+    readonly id: Schema.NonEmptyString;
+    readonly kind: Schema.NonEmptyString;
+    readonly summary: Schema.NonEmptyString;
+    readonly since: Schema.Int;
+    readonly expiresAt: Schema.optional<Schema.Int>;
+}>;
+/** Input to the granted attention door, scoped to the calling extension. */
+export type AttentionItem = typeof AttentionItemSchema.Type;
+/** Public identity includes the owner so two extensions can use the same id. */
+export declare const SessionAttentionSchema: Schema.Struct<{
+    readonly extensionId: Schema.NonEmptyString;
+    readonly id: Schema.NonEmptyString;
+    readonly kind: Schema.NonEmptyString;
+    readonly summary: Schema.NonEmptyString;
+    readonly since: Schema.Int;
+    readonly expiresAt: Schema.optional<Schema.Int>;
+}>;
+/** One open attention item in a Session observation. */
+export type SessionAttention = typeof SessionAttentionSchema.Type;
+/** Private resource ceiling for a complete, bounded Session observation. */
+export declare const maximumSessionAttention = 64;
+/** Private outstanding-resource ceiling per extension, released when items clear. */
+export declare const maximumExtensionAttention = 4096;
+/** All open items, ordered by extension and id; cleared only by their owner. */
+export declare const SessionAttentionListSchema: Schema.$Array<Schema.Struct<{
+    readonly extensionId: Schema.NonEmptyString;
+    readonly id: Schema.NonEmptyString;
+    readonly kind: Schema.NonEmptyString;
+    readonly summary: Schema.NonEmptyString;
+    readonly since: Schema.Int;
+    readonly expiresAt: Schema.optional<Schema.Int>;
+}>>;

package/dist/session-attention.js

@@ -0,0 +1,22 @@
+import * as Schema from "effect/Schema";
+const identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const instant = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/** An extension-owned request for human attention; expiry is owned by its timer. */
+export const AttentionItemSchema = Schema.Struct({
+    id: identity,
+    kind: Schema.NonEmptyString.check(Schema.isMaxLength(64)),
+    summary: Schema.NonEmptyString.check(Schema.isMaxLength(200)),
+    since: instant,
+    expiresAt: Schema.optional(instant),
+});
+/** Public identity includes the owner so two extensions can use the same id. */
+export const SessionAttentionSchema = AttentionItemSchema.mapFields((fields) => ({
+    ...fields,
+    extensionId: identity,
+}));
+/** Private resource ceiling for a complete, bounded Session observation. */
+export const maximumSessionAttention = 64;
+/** Private outstanding-resource ceiling per extension, released when items clear. */
+export const maximumExtensionAttention = 4096;
+/** All open items, ordered by extension and id; cleared only by their owner. */
+export const SessionAttentionListSchema = Schema.Array(SessionAttentionSchema).check(Schema.isMaxLength(maximumSessionAttention));

package/dist/session-documents.d.ts

@@ -0,0 +1,28 @@
+import type * as Schema from "effect/Schema";
+/** Which source value a new Session starts with. */
+export type DocumentForkPolicyV0 = "inherit-at-fork-point" | "current" | "fresh";
+/** A typed JSON document, bounded by its encoded UTF-8 size. */
+export type DocumentSpecV0<A, I = A> = Readonly<{
+    schema: Schema.Codec<A, I>;
+    initial: A;
+    fork: DocumentForkPolicyV0;
+    maxBytes: number;
+}>;
+/** Existential declarations; each initial value is decoded by its own schema. */
+export type DocumentsV0 = Readonly<Record<string, Readonly<{
+    schema: Schema.Codec<unknown>;
+    initial: unknown;
+    fork: DocumentForkPolicyV0;
+    maxBytes: number;
+}>>>;
+/** Both operations require the declaring extension's active core transaction. */
+export type DocumentHandleV0<A> = Readonly<{
+    /** Read the value at the Session’s selected transcript leaf, or its initial value. */
+    read: (sessionId: string) => A;
+    /** Validate and append a new snapshot atomically with the enclosing transaction. */
+    update: (sessionId: string, change: (value: A) => A) => void;
+}>;
+/** Handles preserve the decoded type of each declared document. */
+export type DocumentHandlesV0<D extends DocumentsV0> = {
+    readonly [K in keyof D]: DocumentHandleV0<D[K]["schema"]["Type"]>;
+};

package/dist/session-documents.js

@@ -0,0 +1 @@
+export {};

package/dist/testing.d.ts

@@ -0,0 +1,54 @@
+import type { ExtensionRosterV0, Json, RosteredExtensionV0 } from "./extensions.js";
+import { type FauxResponseStep } from "@earendil-works/pi-ai/providers/faux";
+import { type ModelSource, type SessionSnapshot, type ShiitakeOwnerAgent, type ShiitakeOptions, type SqliteOwner } from "./index.js";
+/** A deterministic model source for trusted tests; no provider account or I/O. */
+export declare function fauxModelSource(replies: readonly FauxResponseStep[]): ModelSource;
+/** One scripted model tool call; the scripted sandbox runs exactly this call. */
+export declare class ScriptedToolCall {
+    /** `<alias>.<operation>` as the model would call it, e.g. `bookmarks.add`. */
+    readonly path: string;
+    readonly input: Json;
+    constructor(
+    /** `<alias>.<operation>` as the model would call it, e.g. `bookmarks.add`. */
+    path: string, input: Json);
+}
+/** One model turn in a test script: a reply, a tool call, or a faux step. */
+export type ScriptStep = string | ScriptedToolCall | FauxResponseStep;
+/** Script one model turn that calls an operation with this input. */
+export declare function callTool(path: string, input?: Json): ScriptedToolCall;
+/** Script one model turn that replies with the system prompt it received. */
+export declare function echoSystemPrompt(): FauxResponseStep;
+/** Optional canonical Agent inputs and a borrowed owner; defaults are in-memory. */
+export type MemoryHostOptions = Partial<Omit<ShiitakeOptions, "store" | "runtime" | "extensions">> & Readonly<{
+    /** Borrow this owner without closing it; otherwise own a Node memory database. */
+    owner?: SqliteOwner;
+    /**
+     * An explicit roster and grants, or a plain list of extensions. A list is
+     * granted exactly what each extension requests: test hosts only;
+     * `Shiitake.make` always takes explicit grants.
+     */
+    extensions?: ExtensionRosterV0 | readonly RosteredExtensionV0[];
+    /**
+     * Script the model turns. Tool calls run through a sandbox that only runs
+     * these calls. Use instead of `model` and `tools.sandbox`.
+     */
+    script?: readonly ScriptStep[];
+}>;
+/** Explicitly driven in-process host for trusted tests and runnable examples. */
+export type MemoryHost = Readonly<{
+    /** The canonical public Shiitake Agent. */
+    agent: ShiitakeOwnerAgent;
+    /** Invoke one canonical reconciliation tick; no timer runs in the background. */
+    reconcile: () => Promise<void>;
+    /** Drain pending Agent work with a 1–1,000 tick budget (default 1,000). */
+    settle: (sessionId: string, maxTicks?: number) => Promise<SessionSnapshot>;
+    /** Close the Agent and only the database owned by this helper. */
+    close: () => Promise<void>;
+}>;
+/**
+ * Compose the real Shiitake runtime over an optional borrowed SQLite owner.
+ * Call reconcile/settle explicitly after acceptance. Defaults use a faux model
+ * and rejecting sandbox; custom callbacks are NOT isolation and retain host
+ * privileges. No submitted JavaScript is evaluated by this helper.
+ */
+export declare function memoryHost(options?: MemoryHostOptions): Promise<MemoryHost>;

package/dist/testing.js

@@ -0,0 +1,215 @@
+import { DatabaseSync } from "node:sqlite";
+import { fromNodeSqlite } from "@fungi.computer/watchdog/node-sqlite";
+import { fauxModel } from "@fungi.computer/mule/testing";
+import { rejectingSandbox } from "@fungi.computer/mycelium/testing";
+import * as Schema from "effect/Schema";
+import * as z from "zod";
+import { fauxAssistantMessage, fauxToolCall, } from "@earendil-works/pi-ai/providers/faux";
+import { GuestThrew } from "@fungi.computer/mycelium";
+import { Shiitake, } from "./index.js";
+const settlementBudgetSchema = z.int().min(1).max(1_000).default(1_000);
+/** A deterministic model source for trusted tests; no provider account or I/O. */
+export function fauxModelSource(replies) {
+    return {
+        acquire: ({ signal }) => {
+            signal.throwIfAborted();
+            const faux = fauxModel(replies);
+            return Promise.resolve({
+                model: faux.model,
+                stream: faux.stream,
+                release: () => Promise.resolve(),
+            });
+        },
+        describe: ({ signal }) => {
+            signal.throwIfAborted();
+            return Promise.resolve({
+                contextWindow: fauxModel(replies).model.contextWindow,
+            });
+        },
+    };
+}
+/** One scripted model tool call; the scripted sandbox runs exactly this call. */
+export class ScriptedToolCall {
+    path;
+    input;
+    constructor(
+    /** `<alias>.<operation>` as the model would call it, e.g. `bookmarks.add`. */
+    path, input) {
+        this.path = path;
+        this.input = input;
+    }
+}
+/** Script one model turn that calls an operation with this input. */
+export function callTool(path, input = {}) {
+    return new ScriptedToolCall(path, input);
+}
+const systemMessage = z.object({
+    role: z.literal("system"),
+    content: z.string(),
+});
+/** Script one model turn that replies with the system prompt it received. */
+export function echoSystemPrompt() {
+    return (context) => {
+        const system = systemMessage.safeParse(context.messages[0]);
+        return fauxAssistantMessage(system.success ? system.data.content : "(no system prompt)");
+    };
+}
+function scriptedCode(call) {
+    return `return await ${call.path}(${JSON.stringify(call.input)});`;
+}
+const isReplyText = Schema.is(Schema.String);
+const thrownMessage = z.object({ message: z.string() });
+function scriptedRun(steps) {
+    const calls = new Map();
+    const replies = steps.map((step) => {
+        if (isReplyText(step))
+            return fauxAssistantMessage(step);
+        if (step instanceof ScriptedToolCall) {
+            const code = scriptedCode(step);
+            calls.set(code, step);
+            return fauxAssistantMessage(fauxToolCall("execute", { code }), {
+                stopReason: "toolUse",
+            });
+        }
+        return step;
+    });
+    return {
+        model: fauxModelSource(replies),
+        sandbox: {
+            execute: async (request, signal) => {
+                signal.throwIfAborted();
+                const call = calls.get(request.code);
+                if (call === undefined)
+                    throw new Error("The scripted sandbox runs only scripted calls");
+                const dot = call.path.indexOf(".");
+                const operation = request.bindings[call.path.slice(0, dot)]?.[call.path.slice(dot + 1)];
+                if (dot < 1 || operation === undefined)
+                    // Model code calling an operation this run lacks fails in the guest.
+                    throw new GuestThrew({
+                        name: "ReferenceError",
+                        message: `${call.path} is not available to this run`,
+                    });
+                try {
+                    return await operation(call.input);
+                }
+                catch (cause) {
+                    // An uncaught rejection in model code is a guest exception.
+                    throw new GuestThrew({
+                        name: "Error",
+                        message: thrownMessage.safeParse(cause).data?.message ?? String(cause),
+                    });
+                }
+            },
+        },
+    };
+}
+/** Grant each listed extension exactly the capabilities it requests. */
+function requestedRoster(extensions) {
+    if ("roster" in extensions)
+        return extensions;
+    return {
+        roster: extensions,
+        grants: extensions.map((extension) => ({
+            id: extension.manifest.id,
+            capabilities: extension.manifest.requests,
+        })),
+    };
+}
+/**
+ * Compose the real Shiitake runtime over an optional borrowed SQLite owner.
+ * Call reconcile/settle explicitly after acceptance. Defaults use a faux model
+ * and rejecting sandbox; custom callbacks are NOT isolation and retain host
+ * privileges. No submitted JavaScript is evaluated by this helper.
+ */
+export async function memoryHost(options = {}) {
+    const { owner, script, extensions, ...agentOptions } = options;
+    if (script !== undefined &&
+        (options.model !== undefined || options.tools !== undefined))
+        throw new Error("Use script, or model and tools, not both");
+    const scripted = script === undefined ? undefined : scriptedRun(script);
+    const storage = owner === undefined ? openMemoryOwner() : { owner, close: () => undefined };
+    let released = false;
+    let bound;
+    let closed = false;
+    const runtime = {
+        bind: (input) => {
+            bound = input;
+            return Promise.resolve({
+                commit: (mutation) => mutation(),
+                requestWake: () => Promise.resolve(),
+                close: () => {
+                    closed = true;
+                    return Promise.resolve();
+                },
+            });
+        },
+    };
+    const requireBound = () => {
+        if (closed || bound === undefined)
+            throw new Error("Memory host is closed or unbound");
+        return bound;
+    };
+    try {
+        const agent = await Shiitake.make({
+            ...agentOptions,
+            store: storage.owner,
+            runtime,
+            model: scripted?.model ??
+                options.model ??
+                fauxModelSource([fauxAssistantMessage("complete")]),
+            instructions: options.instructions ?? {
+                load: () => Promise.resolve({
+                    revision: "memory-host-v1",
+                    text: "Complete this test run.",
+                }),
+            },
+            extensions: extensions === undefined
+                ? { roster: [], grants: [] }
+                : requestedRoster(extensions),
+            tools: scripted === undefined
+                ? (options.tools ?? {
+                    sandbox: rejectingSandbox("Memory host has no direct tools"),
+                })
+                : { sandbox: scripted.sandbox },
+        });
+        return {
+            agent,
+            reconcile: async () => requireBound().reconcile(),
+            settle: async (sessionId, maxTicks) => {
+                const budget = settlementBudgetSchema.parse(maxTicks);
+                for (let tick = 0; tick < budget; tick += 1) {
+                    const host = requireBound();
+                    if (!(await host.pendingWork()).pending)
+                        return agent.session(sessionId).read();
+                    await host.reconcile();
+                }
+                throw new Error(`Memory host did not settle within ${String(budget)} reconciliation ticks`);
+            },
+            close: async () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    await agent.close();
+                }
+                finally {
+                    storage.close();
+                }
+            },
+        };
+    }
+    catch (cause) {
+        storage.close();
+        throw cause;
+    }
+}
+function openMemoryOwner() {
+    const database = new DatabaseSync(":memory:");
+    database.exec("PRAGMA foreign_keys = ON");
+    return {
+        owner: fromNodeSqlite(database),
+        close: () => {
+            database.close();
+        },
+    };
+}