@fungi.computer/shiitake 0.0.0-stage → 0.0.1

package/dist/http-routes.js

@@ -0,0 +1,242 @@
+import { reportCatchFailure } from "./internal/failure.js";
+import { parseModelPreference } from "./internal/model-preference.js";
+import { Hono } from "hono";
+import { streamSSE, } from "hono/streaming";
+import { validator } from "hono/validator";
+import * as Schema from "effect/Schema";
+import { ShiitakeError, toShiitakeErrorWire } from "./errors.js";
+import { JsonValueSchema } from "./internal/json-value.js";
+import { decodeClientIdentity, decodeClientEventsQuery, decodeClientReadQuery, decodeClientSessionCommandRequest, decodeClientSessionCreationRequest, decodeClientPageCursor, decodeClientSessionId, } from "./internal/client-boundary.js";
+const decodeJsonValue = Schema.decodeUnknownResult(Schema.fromJsonString(JsonValueSchema));
+/** One encoded extension output; its contract, not Hono, types the value. */
+function jsonResponse(value) {
+    return new Response(JSON.stringify(value), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/** The raw request body text; JSON decoding belongs to `decodeJsonValue`. */
+function readJsonBody(request) {
+    return request.text();
+}
+function invalidRequest(message, cause) {
+    return new ShiitakeError("contract", "invalid", message, undefined, cause);
+}
+/** Build the exact public read options named by a decoded read query. */
+function readOptionsFromQuery(query) {
+    let options = {};
+    if (query.limit !== undefined)
+        options = { ...options, limit: query.limit };
+    if (query.before !== undefined)
+        options = { ...options, before: query.before };
+    if (query.includeSandboxFailures === "true")
+        options = { ...options, includeSandboxFailures: true };
+    return options;
+}
+function closeOnce(close) {
+    let closed = false;
+    return async () => {
+        if (closed)
+            return;
+        closed = true;
+        await close();
+    };
+}
+async function openSessionEvents(session, request) {
+    if (request.subscribe) {
+        let options = {};
+        if (request.after !== undefined)
+            options = { ...options, after: request.after };
+        if (request.includeSandboxFailures === true)
+            options = { ...options, includeSandboxFailures: true };
+        const frames = session.subscribe(options);
+        const iterator = frames[Symbol.asyncIterator]();
+        return Object.freeze({
+            snapshot: undefined,
+            iterator,
+            close: async () => {
+                await iterator.return?.();
+            },
+        });
+    }
+    let options = {};
+    if (request.limit !== undefined)
+        options = { ...options, limit: request.limit };
+    if (request.includeSandboxFailures === true)
+        options = { ...options, includeSandboxFailures: true };
+    const watch = await session.watch(options);
+    return Object.freeze({
+        snapshot: watch.snapshot,
+        iterator: watch.changes[Symbol.asyncIterator](),
+        close: watch.close,
+    });
+}
+function snapshotEvent(snapshot) {
+    const event = {
+        event: "snapshot",
+        data: JSON.stringify(snapshot),
+    };
+    return snapshot.cursor === null ? event : { ...event, id: snapshot.cursor };
+}
+function frameEvent(frame) {
+    const id = frame.kind === "update"
+        ? (frame.cursor ?? "")
+        : frame.kind === "reset"
+            ? (frame.cursor ?? "")
+            : undefined;
+    const event = { event: "frame", data: JSON.stringify(frame) };
+    return id === undefined ? event : { ...event, id };
+}
+async function writeSessionEvents(stream, session, request) {
+    let close = () => Promise.resolve();
+    try {
+        const opened = await openSessionEvents(session, request);
+        close = closeOnce(opened.close);
+        stream.onAbort(close);
+        if (!stream.aborted && opened.snapshot !== undefined)
+            await stream.writeSSE(snapshotEvent(opened.snapshot));
+        while (!stream.aborted) {
+            const next = await opened.iterator.next();
+            if (next.done === true)
+                break;
+            await stream.writeSSE(frameEvent(next.value));
+        }
+    }
+    catch (error) {
+        reportCatchFailure("session.events", error);
+        if (!stream.aborted)
+            await stream.writeSSE({
+                event: "runtime-error",
+                data: JSON.stringify(toShiitakeErrorWire(error)),
+            });
+    }
+    finally {
+        await close();
+    }
+}
+/** Build Shiitake's typed HTTP routes around an existing Session owner. */
+export function createShiitakeHttpRoutes(resolveSession, listSessions, createSession, deleteSession, resolveExtensions) {
+    return new Hono()
+        .get("/extensions", async (context) => context.json(await (await resolveExtensions()).list(), 200))
+        .post("/extensions/:extensionId/resume", async (context) => {
+        const id = decodeClientIdentity(context.req.param("extensionId"));
+        if (id._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Extension id is invalid")), 400);
+        return context.json(await (await resolveExtensions()).resume(id.success), 200);
+    })
+        .post("/extensions/:extensionId/commands/:command", async (context) => {
+        const id = decodeClientIdentity(context.req.param("extensionId"));
+        const command = decodeClientIdentity(context.req.param("command"));
+        const input = decodeJsonValue(await readJsonBody(context.req.raw));
+        if (id._tag === "Failure" ||
+            command._tag === "Failure" ||
+            input._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Extension command is invalid")), 400);
+        return jsonResponse(await (await resolveExtensions()).call(id.success, command.success, input.success));
+    })
+        .post("/sessions/:sessionId/extensions/:extensionId/commands/:command", async (context) => {
+        const sessionId = decodeClientSessionId(context.req.param("sessionId"));
+        const id = decodeClientIdentity(context.req.param("extensionId"));
+        const command = decodeClientIdentity(context.req.param("command"));
+        const input = decodeJsonValue(await readJsonBody(context.req.raw));
+        if (id._tag === "Failure" ||
+            command._tag === "Failure" ||
+            input._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Extension command is invalid")), 400);
+        const session = await resolveSession(sessionId, context.get("shiitakeMeta"));
+        return jsonResponse(await session
+            .extension(id.success)
+            .call(command.success, input.success));
+    })
+        .post("/sessions", validator("json", (value, context) => {
+        const decoded = decodeClientSessionCreationRequest(value);
+        if (decoded._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Session creation request is invalid")), 400);
+        return decoded.success;
+    }), async (context) => context.json({
+        sessionId: await createSession(context.req.valid("json").requestId),
+    }, 201))
+        .delete("/sessions/:sessionId", async (context) => context.json({
+        deleted: await deleteSession(decodeClientSessionId(context.req.param("sessionId"))),
+    }, 200))
+        .get("/sessions", async (context) => {
+        const after = context.req.query("after");
+        let cursor;
+        try {
+            cursor =
+                after === undefined ? undefined : decodeClientPageCursor(after);
+        }
+        catch (cause) {
+            return context.json(toShiitakeErrorWire(invalidRequest("Session cursor is invalid", cause)), 400);
+        }
+        const page = await listSessions(cursor);
+        return context.json(page, 200);
+    })
+        .get("/sessions/:sessionId/model-preference", async (context) => {
+        const session = await resolveSession(decodeClientSessionId(context.req.param("sessionId")), context.get("shiitakeMeta"));
+        return context.json(await session.modelPreference.read(), 200);
+    })
+        .put("/sessions/:sessionId/model-preference", validator("json", (value, context) => {
+        try {
+            return parseModelPreference(value);
+        }
+        catch (cause) {
+            return context.json(toShiitakeErrorWire(invalidRequest("Model preference is invalid", cause)), 400);
+        }
+    }), async (context) => {
+        const session = await resolveSession(decodeClientSessionId(context.req.param("sessionId")), context.get("shiitakeMeta"));
+        await session.modelPreference.set(context.req.valid("json"));
+        return context.body(null, 204);
+    })
+        .post("/sessions/:sessionId/command", validator("json", (value, context) => {
+        const decoded = decodeClientSessionCommandRequest(value);
+        if (decoded._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Command is invalid")), 400);
+        return decoded.success;
+    }), async (context) => {
+        const sessionId = decodeClientSessionId(context.req.param("sessionId"));
+        const session = await resolveSession(sessionId, context.get("shiitakeMeta"));
+        const command = context.req.valid("json").command;
+        if (command.type === "abort" ||
+            command.type === "branch" ||
+            command.type === "operator" ||
+            command.type === "title") {
+            await session.command(command);
+            return context.body(null, 204);
+        }
+        return context.json(await session.command(command), 200);
+    })
+        .get("/sessions/:sessionId", validator("query", (value, context) => {
+        const decoded = decodeClientReadQuery(value);
+        if (decoded._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Read options are invalid")), 400);
+        return decoded.success;
+    }), async (context) => {
+        const sessionId = decodeClientSessionId(context.req.param("sessionId"));
+        const session = await resolveSession(sessionId, context.get("shiitakeMeta"));
+        const query = context.req.valid("query");
+        return context.json(await session.read(readOptionsFromQuery(query)), 200);
+    })
+        .get("/sessions/:sessionId/events", validator("query", (value, context) => {
+        const decoded = decodeClientEventsQuery(value);
+        if (decoded._tag === "Failure")
+            return context.json(toShiitakeErrorWire(invalidRequest("Event options are invalid")), 400);
+        return decoded.success;
+    }), async (context) => {
+        const sessionId = decodeClientSessionId(context.req.param("sessionId"));
+        const session = await resolveSession(sessionId, context.get("shiitakeMeta"));
+        const query = context.req.valid("query");
+        const lastEventId = context.req.header("Last-Event-ID");
+        const after = lastEventId ?? query.after;
+        const shouldSubscribe = lastEventId !== undefined || query.mode === "subscribe";
+        context.header("Content-Encoding", "Identity");
+        context.header("Cache-Control", "no-cache");
+        return streamSSE(context, (stream) => writeSessionEvents(stream, session, {
+            after,
+            limit: query.limit,
+            subscribe: shouldSubscribe,
+            includeSandboxFailures: query.includeSandboxFailures === "true",
+        }));
+    })
+        .onError((error, context) => context.json(toShiitakeErrorWire(error), 503));
+}

package/dist/http.d.ts

@@ -0,0 +1 @@
+export { createShiitakeHttpRoutes, type ShiitakeHttpEnv, type ShiitakeSessionResolver, } from "./http-routes.js";

package/dist/http.js

@@ -0,0 +1 @@
+export { createShiitakeHttpRoutes, } from "./http-routes.js";

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { CommandSettlement } from "./internal/contracts.js";
+import type { Json as HostJson } from "./extensions.js";
+import type { BirdDogMail } from "@fungi.computer/bird-dog";
+import type { VerifiedAgentReply } from "./internal/woodstock/index.js";
+import type { BirdDogEffect } from "@fungi.computer/bird-dog/effect";
+import type { Accepted } from "./client.js";
+import type { ShiitakeOptions, ShiitakeOwnerAgent } from "./internal/contracts.js";
+export type { AbortCommand, AgentExtensionControls, BranchCommand, CompactCommand, CancelCommand, CancelResult, Accepted, ForkCommand, ForkedSession, PromptCommand, PromptDelivery, SendOptions, ReadOptions, SessionCommand, SessionCommandHandler, SessionExtensionControls, SessionExtensionSlots, SessionFrame, SessionMessage, SessionProgress, SessionContext, SessionSnapshot, SessionInboxState, SessionSummary, SessionSummaryPage, SessionSummaryRow, SessionActivity, AgentRunningWork, SessionTerminal, SessionCompactionMarker, SessionCompactionNotice, SessionCompactionTrigger, ShiitakeEventSourceConstructor, SessionWatch, ShiitakeAgent, ShiitakeSession, SubscribeOptions, TooLate, WatchOptions, } from "./client.js";
+export { parseForkedSession, parseSessionFrame, parseSessionSnapshot, } from "./client.js";
+export type { InstructionSnapshot, InstructionSource, ModelAcquisition, ModelDescription, ModelSource, RuntimeHost, RuntimePendingWork, SqliteCursor, SqliteOwner, SqliteValue, SqliteRow, StorageBudget, CompactionBudget, CompactionOptions, GrantsDelivery, GrantsDeliveryResult, ShiitakeOptions, ShiitakeOwnerAgent, ToolAccess, HostMetaOptions, StandardHostMetaResult, StandardHostMetaSchema, ToolSource, } from "./internal/contracts.js";
+export type { BorrowedCompactionViewV0, CompactionHandoffErrorV0, CompactionHandoffResultV0, CompactionHandoffV0, ExtensionCapabilityV0, ExtensionGrantV0, ExtensionRosterV0, ExtensionSlotV0, ExtensionStatusV0, RosteredExtensionV0, } from "./extensions.js";
+export { ShiitakeError, type ShiitakeErrorBoundary, type ShiitakeErrorCause, } from "./errors.js";
+/** Public construction namespace for the Promise-facing durable harness. */
+export type ShiitakeApi = Readonly<{
+    /** Construct a Promise-facing durable harness. */
+    make: (options: ShiitakeOptions) => Promise<ShiitakeOwnerAgent>;
+}>;
+/** Promise-facing host composition with addressed mail kept off Session. */
+export type ShiitakeHost = Readonly<{
+    /** Exact settled command facts; never a selected-lineage transcript query. */
+    readSettlement: (sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
+    agent: ShiitakeOwnerAgent;
+    /** Durably admit one addressed mail item through the host owner. */
+    acceptMail: (mail: BirdDogMail, meta?: HostJson, reply?: VerifiedAgentReply) => Promise<Accepted>;
+}>;
+/** Construct the host-only Promise facade over the canonical Effect program. */
+export declare function makeHost(options: ShiitakeOptions, mailRoom: BirdDogEffect): Promise<ShiitakeHost>;
+/** Construct the Promise facade over the canonical Effect program. */
+export declare const Shiitake: ShiitakeApi;
+export type { ModelPreference } from "./internal/model-preference.js";
+export type { DocumentSpecV0, DocumentsV0, DocumentForkPolicyV0, DocumentHandleV0, DocumentHandlesV0, } from "./session-documents.js";
+export { sqliteRowSchema } from "./internal/contracts.js";
+export type { CommandSettlement } from "./internal/contracts.js";
+/** A delegated Agent reply after the admitting host authenticated it. */
+export type { VerifiedAgentReply } from "./internal/woodstock/index.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+import { make as makeEffect, openHost as openEffectHost } from "./effect.js";
+import { openPromiseAgent, openPromiseHost, } from "./internal/promise-facade.js";
+export { parseForkedSession, parseSessionFrame, parseSessionSnapshot, } from "./client.js";
+export { ShiitakeError, } from "./errors.js";
+/** Construct the host-only Promise facade over the canonical Effect program. */
+export function makeHost(options, mailRoom) {
+    return openPromiseHost(options, mailRoom, openEffectHost);
+}
+/** Construct the Promise facade over the canonical Effect program. */
+export const Shiitake = Object.freeze({
+    make: (options) => openPromiseAgent(options, makeEffect),
+});
+export { sqliteRowSchema } from "./internal/contracts.js";

package/dist/internal/accepted-run-executor.d.ts

@@ -0,0 +1,23 @@
+import { type WatchdogRunningJob } from "@fungi.computer/watchdog";
+import * as Effect from "effect/Effect";
+import type { ShiitakeEffectOptions } from "./effect-contracts.js";
+import type { ExtensionRuntime } from "./extension-runtime.js";
+/** Bounded process-loss recovery for every accepted Agent turn. */
+export declare const agentTurnRecovery: Readonly<{
+    maxRecoveries: 2;
+}>;
+/** Execute one claimed opaque job through Shiitake's accepted run scope. */
+export declare function executeAcceptedRun(options: ShiitakeEffectOptions, coreDigest: string, job: WatchdogRunningJob, extensions: ExtensionRuntime | undefined): Effect.Effect<{
+    readonly kind: "completed";
+} | {
+    readonly kind: "failed";
+    readonly reason?: string;
+} | {
+    readonly kind: "cancelled";
+} | {
+    readonly kind: "outcome_unknown";
+} | {
+    kind: "failed" | "cancelled";
+} | {
+    kind: "completed";
+}, never, never>;

package/dist/internal/accepted-run-executor.js

@@ -0,0 +1,129 @@
+import { decodeAgentJob } from "@fungi.computer/bird-dog/effect";
+import {} from "@fungi.computer/watchdog";
+import { Mycelium } from "@fungi.computer/mycelium";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { ShiitakeError } from "../errors.js";
+import { ExtensionId } from "../extension-contract.js";
+import { publishOwnerObservation } from "./observation-kernel.js";
+import { coreProtocolDigest } from "./extension-roster.js";
+import { runAcceptedCommand, runAcceptedCompaction, ToolSetupError, } from "./run-scope.js";
+import { CompactionCommitError } from "./compaction/session-compaction.js";
+import { isCompactCommand, loadAcceptedRun, readExtensionAdmissionOrigin, recordWorkSettlement, } from "./woodstock/index.js";
+/** Bounded process-loss recovery for every accepted Agent turn. */
+export const agentTurnRecovery = Object.freeze({ maxRecoveries: 2 });
+function runtimeFailure(message) {
+    return new ShiitakeError("runtime", "rejected", message);
+}
+/**
+ * Settle a run that could not finish. The durable job records the sanitized
+ * boundary and category, plus a safe model-host or closed tool-setup diagnostic.
+ * Original provider causes stay in the server log only.
+ */
+function failedDecision(error) {
+    const category = `${error.boundary}:${error.cause}`;
+    const diagnostic = error instanceof ToolSetupError || error instanceof CompactionCommitError
+        ? error.diagnostic
+        : error.boundary === "model"
+            ? error.message
+            : undefined;
+    return {
+        kind: "failed",
+        reason: diagnostic === undefined
+            ? category
+            : `${category}: ${diagnostic}`.slice(0, 200),
+    };
+}
+/** Log a run failure with its sanitized reason and underlying cause. */
+function logRunFailed(workId, error) {
+    return Effect.logError("shiitake_run_failed", Redacted.make(error)).pipe(Effect.annotateLogs({
+        workId,
+        reason: `${error.boundary}:${error.cause}`,
+    }));
+}
+/** Execute one claimed opaque job through Shiitake's accepted run scope. */
+export function executeAcceptedRun(options, coreDigest, job, extensions) {
+    return Effect.gen(function* () {
+        publishOwnerObservation(options.store, job.queue);
+        const payload = yield* Effect.try({
+            try: () => decodeAgentJob(job),
+            catch: () => runtimeFailure("Agent work payload is invalid"),
+        });
+        const prepared = yield* loadAcceptedRun(options.store, payload.work);
+        if (prepared.abnormalTerminal !== undefined)
+            return { kind: prepared.abnormalTerminal };
+        const incompatible = extensions?.incompatibleMigrations()[0];
+        if (incompatible !== undefined) {
+            yield* Effect.logError("shiitake_run_contract_changed").pipe(Effect.annotateLogs({
+                workId: job.jobId,
+                terminal: `contract_changed: ${incompatible}`,
+            }));
+            return yield* Effect.fail(runtimeFailure(`contract_changed: ${incompatible}`));
+        }
+        // A cold reopen selects its current admitted code at the next execution
+        // boundary. The command's admission contract remains an audit fact.
+        const participants = new Set(extensions?.runParticipants().map(([id]) => id) ?? []);
+        // A compaction request runs the Session's one compaction commit with the
+        // run's model and handoff, and no model turn. A failure settles through
+        // the ordinary failed decision with its owner-closed diagnostic.
+        // "Nothing to compact" completes the work; the Session records it as a
+        // compaction notice, which clients show as the request's result.
+        if (isCompactCommand(prepared.command.entry)) {
+            yield* runAcceptedCompaction(options, prepared, extensions?.compactionHandoff(participants));
+            yield* recordWorkSettlement(options.store, {
+                sessionId: prepared.command.sessionId,
+                commandFactId: payload.work.commandFactId,
+                workId: prepared.command.entry.workId,
+                outcome: "completed",
+            });
+            return { kind: "completed" };
+        }
+        const origin = yield* Effect.try({
+            try: () => readExtensionAdmissionOrigin(options.store, payload.work.sessionId, payload.work.commandFactId, prepared.command.entry.workId),
+            catch: () => runtimeFailure("Accepted run origin is unavailable"),
+        });
+        const runIdentity = {
+            sessionId: prepared.command.sessionId,
+            workId: prepared.command.entry.workId,
+            origin: origin === null
+                ? null
+                : {
+                    extensionId: Schema.decodeUnknownSync(ExtensionId)(origin.extensionId),
+                    correlation: origin.correlation,
+                },
+        };
+        const fileTools = extensions === undefined
+            ? []
+            : yield* extensions.filesForRun(runIdentity, participants);
+        // Every participant offers its tools under the grant key its host grant
+        // names (its id by default); Mycelium decides each call.
+        const extensionModules = extensions === undefined
+            ? []
+            : yield* Effect.forEach([...participants], (extensionId) => extensions.modulesForRun(runIdentity, new Set([extensionId])).pipe(Effect.flatMap((modules) => Effect.try({
+                try: () => {
+                    const grantKey = options.extensions.grants.find((grant) => grant.id === extensionId)?.grantKey ?? extensionId;
+                    return modules.map((module) => Mycelium.grantAs(module, grantKey));
+                },
+                catch: () => runtimeFailure("Extension tools are invalid"),
+            })))).pipe(Effect.map((groups) => groups.flat()));
+        const extensionHandoff = extensions?.compactionHandoff(participants);
+        const executionContract = {
+            core: fileTools.length === 0
+                ? coreDigest
+                : yield* coreProtocolDigest(fileTools.map((tool) => tool.descriptor.name)),
+            extensions: extensions?.runParticipants() ?? [],
+        };
+        const run = yield* runAcceptedCommand(options, prepared, executionContract, extensionModules, fileTools, extensionHandoff, extensions === undefined
+            ? undefined
+            : () => extensions.promptSections(runIdentity, participants));
+        switch (run.status) {
+            case "completed":
+                return { kind: "completed" };
+            case "cancelled":
+                return { kind: "cancelled" };
+            case "failed":
+                return { kind: "failed" };
+        }
+    }).pipe(Effect.catch((error) => logRunFailed(job.jobId, error).pipe(Effect.as(failedDecision(error)))));
+}

package/dist/internal/admission-door.d.ts

@@ -0,0 +1,75 @@
+import type { BirdDogMail } from "@fungi.computer/bird-dog";
+import * as Effect from "effect/Effect";
+import type { AcceptedWork } from "./client-boundary.js";
+import type { Json } from "../extensions.js";
+import { type HostMetaOptions } from "./host-meta.js";
+import { ShiitakeError } from "../errors.js";
+import type { SqliteOwner } from "./contracts.js";
+import { type AdmissionOrigin, type EnqueueAcceptedWork, type RunContract, type SessionQueueHead, type VerifiedAgentReply } from "./woodstock/index.js";
+export type { AdmissionOrigin } from "./woodstock/index.js";
+/**
+ * `now` admits immediately (a steer targets the running job). `idle` admits
+ * only while the Session queue head is idle and otherwise reports `not_ready`
+ * without writing anything; a retried request id still replays.
+ */
+export type AdmitWhen = "now" | "idle";
+/** One prompt or compaction request submitted to the door, still encoded. */
+export type AdmitRequest = Readonly<{
+    sessionId: string;
+    /** Checked atomically before admission; an absent target fails closed. */
+    requireExistingSession?: boolean;
+    /** Encoded accepted work, decoded once by the public command schema. */
+    command: AcceptedWork;
+    when: AdmitWhen;
+    origin: AdmissionOrigin;
+    /** Addressed BirdDog mail whose reply settles with this work. */
+    mail?: BirdDogMail;
+    /** Host metadata stored beside the prompt; only the in-process host sets it. */
+    meta?: Json;
+    /**
+     * The host's authentication of `mail` as a delegated Agent's reply. Only the
+     * host passes it, after checking the reply against the mail it sent.
+     */
+    reply?: VerifiedAgentReply;
+}>;
+/** Outcome of one door admission. */
+export type AdmitResult = Readonly<{
+    status: "accepted";
+    commandId: string;
+    delivery: "new" | "replay";
+}> | Readonly<{
+    status: "not_ready";
+}>;
+/** Admit inside the door's open owner transaction. Throws `ShiitakeError`. */
+export type AdmitWithin = (request: AdmitRequest) => AdmitResult;
+/**
+ * Where a door transaction runs. `request` commits through the host so the
+ * wake guarantee is durable with the mutation; `reconcile` is already inside
+ * the host's reconciliation and commits on the owner alone.
+ */
+export type AdmissionBoundary = "request" | "reconcile";
+/** The one accepted-command door. Nothing else writes accepted commands. */
+export type AdmissionDoor = Readonly<{
+    /** Admit one prompt in its own transaction. */
+    admit: (request: AdmitRequest, boundary?: AdmissionBoundary) => Effect.Effect<AdmitResult, ShiitakeError>;
+    /**
+     * Run one owner transaction that may admit through `admit`. After commit the
+     * door publishes each Session with new work and requests one wake.
+     */
+    transact: <A>(body: (admit: AdmitWithin) => A, boundary?: AdmissionBoundary) => Effect.Effect<A, ShiitakeError>;
+}>;
+/** Bind the door to one owner, run contract, Watchdog queue and host wake. */
+export declare function openAdmissionDoor(input: Readonly<{
+    owner: SqliteOwner;
+    /** The host's metadata schema, checked before any write. */
+    hostMeta?: HostMetaOptions | undefined;
+    /** Refuses a new prompt under storage pressure; replays skip it. */
+    admitNew: () => void;
+    /** The run contract captured at this instant (participants may change). */
+    contract: () => RunContract;
+    enqueue: (work: Parameters<EnqueueAcceptedWork>[0], mail?: BirdDogMail) => void;
+    /** Transactional queue-head projection for the steer and idle decisions. */
+    readQueueHead: (sessionId: string) => SessionQueueHead;
+    commit: <A>(mutation: Effect.Effect<A, ShiitakeError>) => Effect.Effect<A, ShiitakeError>;
+    requestWake: Effect.Effect<void, ShiitakeError>;
+}>): AdmissionDoor;

package/dist/internal/admission-door.js

@@ -0,0 +1,105 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { checkHostMeta } from "./host-meta.js";
+import { ShiitakeError } from "../errors.js";
+import { decodeClientAcceptedCommand, decodeClientSessionId, requireDecoded, } from "./client-boundary.js";
+import { publishOwnerObservation } from "./observation-kernel.js";
+import { AdmissionOriginSchema, acceptSessionCommandOwned, readSessionCommandAdmissionByRequest, hasStoredSession, VerifiedAgentReplySchema, } from "./woodstock/index.js";
+const decodeOrigin = Schema.decodeUnknownResult(AdmissionOriginSchema, {
+    onExcessProperty: "error",
+});
+const decodeExistingSessionCondition = Schema.decodeUnknownResult(Schema.UndefinedOr(Schema.Boolean));
+const decodeVerifiedReply = Schema.decodeUnknownResult(VerifiedAgentReplySchema, { onExcessProperty: "error" });
+/** A verified reply names the mail it arrived on and that mail's sender. */
+function decodeReply(request) {
+    if (request.reply === undefined)
+        return undefined;
+    const reply = requireDecoded(decodeVerifiedReply(request.reply), "Verified Agent reply is invalid");
+    const mail = request.mail;
+    if (mail?.replyTo.length !== 0 ||
+        mail.from.agentId !== reply.agentId ||
+        mail.from.sessionId !== reply.sessionId ||
+        request.command.type !== "prompt" ||
+        request.command.delivery !== "followUp")
+        throw new ShiitakeError("contract", "invalid", "Verified Agent reply does not match its mail");
+    return reply;
+}
+/** Bind the door to one owner, run contract, Watchdog queue and host wake. */
+export function openAdmissionDoor(input) {
+    /** The door's one decode, done before any owner operation when possible. */
+    const decode = (request) => ({
+        sessionId: decodeClientSessionId(request.sessionId),
+        requireExistingSession: requireDecoded(decodeExistingSessionCondition(request.requireExistingSession), "Session admission condition is invalid") ?? false,
+        command: requireDecoded(decodeClientAcceptedCommand(request.command), "Session command is invalid"),
+        origin: requireDecoded(decodeOrigin(request.origin), "Session command origin is invalid"),
+        when: request.when,
+        mail: request.mail,
+        reply: decodeReply(request),
+        meta: request.meta === undefined
+            ? undefined
+            : checkHostMeta(input.hostMeta, request.meta),
+    });
+    const admitDecoded = (request, touched) => {
+        const { sessionId, origin } = request;
+        const command = request.command;
+        if (request.requireExistingSession &&
+            !hasStoredSession(input.owner, sessionId))
+            throw new ShiitakeError("contract", "closed", "Session target is unavailable");
+        const head = input.readQueueHead(sessionId);
+        if (request.when === "idle" &&
+            head.state !== "idle" &&
+            readSessionCommandAdmissionByRequest(input.owner, sessionId, command.requestId) === undefined)
+            return Object.freeze({ status: "not_ready" });
+        // Storage pressure refuses new prompts. A compaction request adds no
+        // prompt and frees model context, so it is admitted.
+        if (command.type === "prompt" &&
+            readSessionCommandAdmissionByRequest(input.owner, sessionId, command.requestId) === undefined)
+            input.admitNew();
+        // Only a steering prompt targets the running job; a compaction request
+        // always queues behind running work.
+        const targetWorkId = command.type === "prompt" &&
+            command.delivery === "steer" &&
+            head.state === "running" &&
+            !head.cancellationRequested
+            ? head.jobId
+            : undefined;
+        const accepted = acceptSessionCommandOwned(input.owner, sessionId, command, request.meta, origin, input.contract(), targetWorkId === undefined
+            ? (work) => {
+                input.enqueue(work, request.mail);
+            }
+            : undefined, targetWorkId, request.reply);
+        touched.set(sessionId, (touched.get(sessionId) ?? false) || accepted.delivery === "new");
+        return Object.freeze({
+            status: "accepted",
+            commandId: accepted.accepted.commandId,
+            delivery: accepted.delivery,
+        });
+    };
+    const run = (body, boundary) => Effect.suspend(() => {
+        const touched = new Map();
+        const mutation = Effect.try({
+            try: () => {
+                touched.clear();
+                return input.owner.transactionSync(() => body((request) => admitDecoded(request, touched)));
+            },
+            catch: (error) => error instanceof ShiitakeError
+                ? error
+                : new ShiitakeError("store", "unavailable", "Session command admission is unavailable"),
+        });
+        return (boundary === "request" ? input.commit(mutation) : mutation).pipe(Effect.tap(() => Effect.sync(() => {
+            for (const [sessionId, isNew] of touched)
+                if (isNew)
+                    publishOwnerObservation(input.owner, sessionId);
+        })), Effect.tap(() => (touched.size > 0 ? input.requestWake : Effect.void)));
+    });
+    const transact = (body, boundary = "request") => run((admit) => body((request) => admit(decode(request))), boundary);
+    return Object.freeze({
+        transact,
+        admit: (request, boundary) => Effect.try({
+            try: () => decode(request),
+            catch: (error) => error instanceof ShiitakeError
+                ? error
+                : new ShiitakeError("contract", "invalid", "Session command is invalid"),
+        }).pipe(Effect.flatMap((decoded) => run((admit) => admit(decoded), boundary ?? "request"))),
+    });
+}

package/dist/internal/agent-close.d.ts

@@ -0,0 +1,4 @@
+import * as Effect from "effect/Effect";
+import type { ShiitakeError } from "../errors.js";
+/** Compose one idempotent close action for the constructed agent. */
+export declare function composeAgentClose(coordinatorClose: Effect.Effect<void, ShiitakeError>, extensionClose: Effect.Effect<void, ShiitakeError>): Effect.Effect<void, ShiitakeError>;