@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/internal/runtime-reconciliation.js

@@ -0,0 +1,162 @@
+import { agentJobFromInput, decodeAgentJob, } from "@fungi.computer/bird-dog/effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Schema from "effect/Schema";
+import { agentTurnRecovery } from "./accepted-run-executor.js";
+import { ShiitakeError } from "../errors.js";
+import { ExtensionId } from "../extension-contract.js";
+import { coreConsumer } from "./extension-runtime.js";
+import { publishOwnerObservation } from "./observation-kernel.js";
+import { advanceCursor, readCursor, readSettledRunFacts, readSettlementContent, readSettlementDiagnostic, readSettlementMeta, recordWorkSettlement, settleControls, } from "./woodstock/index.js";
+const pageSize = 64;
+function runtimeFailure(message) {
+    return new ShiitakeError("runtime", "rejected", message);
+}
+function fanOutSettlement(store, mailRoom, job) {
+    if (mailRoom === undefined)
+        return Effect.void;
+    return Effect.gen(function* () {
+        const payload = yield* Effect.try({
+            try: () => decodeAgentJob(job),
+            catch: () => runtimeFailure("Agent work payload is invalid"),
+        });
+        const content = job.outcome === "cancelled"
+            ? ""
+            : yield* readSettlementContent(store, payload.work);
+        const meta = yield* readSettlementMeta(store, payload.work, job.outcome);
+        const diagnostic = job.outcome === "completed" || job.outcome === "cancelled"
+            ? undefined
+            : yield* readSettlementDiagnostic(store, payload.work);
+        const settled = diagnostic === undefined
+            ? { job, content }
+            : { job, content, diagnostic };
+        yield* mailRoom
+            .fanOut(meta === undefined ? settled : { ...settled, meta })
+            .pipe(Effect.mapError(() => runtimeFailure("Agent reply fan-out is unavailable")));
+    });
+}
+function repairWorkSettlement(store, job) {
+    const outcome = job.outcome;
+    if (outcome !== "interrupted" &&
+        outcome !== "cancelled" &&
+        outcome !== "failed")
+        return Effect.void;
+    return Effect.gen(function* () {
+        const payload = yield* Effect.try({
+            try: () => decodeAgentJob(job),
+            catch: () => runtimeFailure("Agent work payload is invalid"),
+        });
+        yield* recordWorkSettlement(store, {
+            sessionId: payload.work.sessionId,
+            commandFactId: payload.work.commandFactId,
+            workId: job.jobId,
+            outcome,
+            diagnostic: job.failureReason,
+        });
+    });
+}
+function settleTargetedControls(store, watchdog, job) {
+    return Effect.gen(function* () {
+        const payload = yield* Effect.try({
+            try: () => decodeAgentJob(job),
+            catch: () => runtimeFailure("Agent work payload is invalid"),
+        });
+        const outcome = job.outcome === "outcome_unknown" ? "interrupted" : job.outcome;
+        yield* settleControls(store, {
+            sessionId: payload.work.sessionId,
+            parentWorkId: job.jobId,
+            outcome,
+            enqueue: (work) => {
+                watchdog.transactional.enqueueAcceptedJob(agentJobFromInput({ work: { ...work, recovery: agentTurnRecovery } }));
+            },
+        });
+    });
+}
+function drainMail(mailRoom) {
+    if (mailRoom === undefined)
+        return Effect.void;
+    return mailRoom
+        .drainOutbox()
+        .pipe(Effect.mapError(() => runtimeFailure("Agent reply delivery is unavailable")));
+}
+/** Join one core-processed settled record with its exact Woodstock facts. */
+function settledRun(store, record) {
+    const payload = decodeAgentJob(record.job);
+    const facts = readSettledRunFacts(store, payload.work.sessionId, payload.work.commandFactId, record.job.jobId);
+    return Object.freeze({
+        sequence: record.sequence,
+        sessionId: payload.work.sessionId,
+        workId: record.job.jobId,
+        outcome: record.job.outcome,
+        terminal: facts.terminal,
+        toolCalls: facts.toolCalls,
+        origin: facts.origin === null
+            ? null
+            : Object.freeze({
+                extensionId: Schema.decodeUnknownSync(ExtensionId)(facts.origin.extensionId),
+                correlation: facts.origin.correlation,
+            }),
+    });
+}
+/**
+ * The `core` settled consumer: publish the idle owner observation, repair
+ * terminals, settle targeted controls, fan out mail, then advance the durable core cursor, one record
+ * at a time. Every step is idempotent, so a crash before the cursor advance
+ * repeats work without duplicating a reply.
+ */
+function settleCore(store, watchdog, mailRoom, records) {
+    return Effect.forEach(records, (record) => Effect.gen(function* () {
+        // Watchdog has durably settled the work: its queue head is idle now.
+        // Announce that before any Session repair, so a repair failure cannot
+        // leave live watchers reporting the finished run as active. A replay
+        // after a crash repeats the same announcement.
+        publishOwnerObservation(store, record.job.queue);
+        yield* repairWorkSettlement(store, record.job);
+        yield* settleTargetedControls(store, watchdog, record.job);
+        yield* fanOutSettlement(store, mailRoom, record.job);
+        yield* Effect.try({
+            try: () => {
+                advanceCursor(store, coreConsumer, record.sequence);
+            },
+            catch: () => runtimeFailure("Settled cursor is unavailable"),
+        });
+    }), { discard: true });
+}
+/**
+ * One reconcile tick. Each step is its own Exit boundary: a failed extension
+ * stops only itself, and mail always drains. Only a core failure fails the
+ * tick, so the host backs off only for core.
+ */
+export function reconcileRuntime(input) {
+    return Effect.gen(function* () {
+        const result = yield* input.watchdog.tick();
+        if (result.status === "busy")
+            return yield* Effect.fail(runtimeFailure("Runtime reconciliation is already active"));
+        const coreCursor = yield* Effect.try({
+            try: () => readCursor(input.store, coreConsumer) ?? 0,
+            catch: () => runtimeFailure("Settled cursor is unavailable"),
+        });
+        const consumers = input.extensions.settledConsumers();
+        const after = Math.min(coreCursor, ...consumers.map(({ cursor }) => cursor));
+        const page = yield* input.watchdog.readSettled(pageSize, after);
+        const core = yield* Effect.exit(settleCore(input.store, input.watchdog, input.mailRoom, page.filter(({ sequence }) => sequence > coreCursor)));
+        const runs = yield* Effect.try({
+            try: () => {
+                const processed = readCursor(input.store, coreConsumer) ?? 0;
+                return page
+                    .filter(({ sequence }) => sequence <= processed)
+                    .map((record) => settledRun(input.store, record));
+            },
+            catch: () => runtimeFailure("Settled run facts are unavailable"),
+        });
+        yield* input.extensions.deliverSettled(runs, readCursor(input.store, coreConsumer) ?? 0);
+        const moreTimers = yield* input.extensions.fireDueTimers(Date.now());
+        if (page.length === pageSize || moreTimers)
+            yield* input.requestWake;
+        yield* drainMail(input.mailRoom);
+        if (Exit.isFailure(core))
+            return yield* Effect.failCause(core.cause);
+    }).pipe(Effect.mapError((failure) => failure instanceof ShiitakeError
+        ? failure
+        : runtimeFailure("Runtime reconciliation failed")));
+}

package/dist/internal/session-context.d.ts

@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect";
+import type { SessionContext } from "../client.js";
+import type { ShiitakeEffectOptions } from "./effect-contracts.js";
+import type { RuntimeCoordinator } from "./runtime-coordinator.js";
+/**
+ * The Session's context use as compaction measures it, against the window of
+ * the model a run would select now. Undefined while the Session has no
+ * context or its context cannot be read; a window the host cannot describe is
+ * null, never guessed.
+ */
+export declare function readSessionContext(options: ShiitakeEffectOptions, runtime: RuntimeCoordinator, sessionId: string): Effect.Effect<SessionContext | undefined>;

package/dist/internal/session-context.js

@@ -0,0 +1,67 @@
+import * as Effect from "effect/Effect";
+import { estimateThresholdContextTokens } from "./compaction/session-compaction.js";
+import { reportCatchFailure } from "./failure.js";
+import { buildSessionContext, readSessionContextPath, readSessionModelPreference, } from "./woodstock/index.js";
+/**
+ * The context size compaction measures against the model's window, for the
+ * Session's settled context: the next run starts from it. Null before the
+ * Session has any context.
+ */
+function settledContextTokens(store, sessionId) {
+    const path = readSessionContextPath(store, { sessionId });
+    const messages = buildSessionContext(path);
+    return messages.length === 0
+        ? null
+        : estimateThresholdContextTokens(path, messages);
+}
+/**
+ * Each runtime keeps the last described window per Session. A saved model
+ * preference changes the key, so `/model` is described again at once.
+ */
+const describedWindows = new WeakMap();
+function windowsFor(runtime) {
+    const existing = describedWindows.get(runtime);
+    if (existing !== undefined)
+        return existing;
+    const created = new Map();
+    describedWindows.set(runtime, created);
+    return created;
+}
+/**
+ * The Session's context use as compaction measures it, against the window of
+ * the model a run would select now. Undefined while the Session has no
+ * context or its context cannot be read; a window the host cannot describe is
+ * null, never guessed.
+ */
+export function readSessionContext(options, runtime, sessionId) {
+    return Effect.gen(function* () {
+        // A context too large to read safely has no footer figure.
+        const read = yield* Effect.result(Effect.try({
+            try: () => ({
+                tokens: settledContextTokens(options.store, sessionId),
+                preference: readSessionModelPreference(options.store, sessionId),
+            }),
+            catch: (error) => error,
+        }));
+        if (read._tag === "Failure" || read.success.tokens === null)
+            return undefined;
+        const { tokens, preference } = read.success;
+        const windows = windowsFor(runtime);
+        const key = JSON.stringify(preference);
+        const cached = windows.get(sessionId);
+        if (cached?.preference === key)
+            return Object.freeze({ tokens, window: cached.window });
+        const describe = options.model.describe;
+        if (describe === undefined)
+            return Object.freeze({ tokens, window: null });
+        const described = yield* describe({ sessionId, preference }).pipe(Effect.map(({ contextWindow }) => contextWindow), Effect.catch((error) => Effect.sync(() => {
+            reportCatchFailure("session-context.describe", error);
+            return undefined;
+        })));
+        // A failed description is retried on the next read, never cached.
+        if (described === undefined)
+            return Object.freeze({ tokens, window: null });
+        windows.set(sessionId, { preference: key, window: described });
+        return Object.freeze({ tokens, window: described });
+    });
+}

package/dist/internal/session-status.d.ts

@@ -0,0 +1,10 @@
+import type { WatchdogQueueHead } from "@fungi.computer/watchdog/effect";
+import type { AgentRunningWork, SessionActivity, SessionProgress } from "../client.js";
+import type { SqliteOwner } from "./contracts.js";
+/** Public activity facts plus the process-local progress read with them. */
+export type ObservedActivity = Readonly<{
+    facts: SessionActivity;
+    progress: SessionProgress | null;
+}>;
+/** Join Watchdog authority with Woodstock facts and process-local progress. */
+export declare function readSessionActivity(owner: SqliteOwner, sessionId: string, head: WatchdogQueueHead, runningWork: AgentRunningWork | null): ObservedActivity;

package/dist/internal/session-status.js

@@ -0,0 +1,52 @@
+import { readProcessProgressForWork, readProcessCompaction, readLatestLiveRetryForWork, readActiveToolForWork, readLastModelChoiceSequence, } from "./woodstock/index.js";
+/** Join Watchdog authority with Woodstock facts and process-local progress. */
+export function readSessionActivity(owner, sessionId, head, runningWork) {
+    const lastModelChoiceSequence = readLastModelChoiceSequence(owner, sessionId);
+    if (head.state === "idle")
+        return {
+            facts: {
+                queue: { state: "idle" },
+                cancellationRequested: false,
+                retry: null,
+                activeTool: null,
+                lastModelChoiceSequence,
+                compaction: null,
+            },
+            progress: null,
+        };
+    if (head.state === "queued")
+        // The queue job id is the admitted command id: the one identity a person
+        // may cancel while this Session's work waits for the Agent.
+        return {
+            facts: {
+                queue: { state: "queued", commandId: head.jobId, runningWork },
+                cancellationRequested: head.cancellationRequested,
+                retry: null,
+                activeTool: null,
+                lastModelChoiceSequence,
+                compaction: null,
+            },
+            progress: null,
+        };
+    const latestRetry = readLatestLiveRetryForWork(owner, sessionId, head.jobId);
+    const retry = latestRetry?.event.type === "auto_retry_start"
+        ? {
+            attempt: latestRetry.event.attempt,
+            maxAttempts: latestRetry.event.maxAttempts,
+            delayMs: latestRetry.event.delayMs,
+            errorMessage: latestRetry.event.errorMessage,
+            scheduledAt: latestRetry.timestamp,
+        }
+        : null;
+    return {
+        facts: {
+            queue: { state: "running", commandId: head.jobId },
+            cancellationRequested: head.cancellationRequested,
+            retry,
+            activeTool: readActiveToolForWork(owner, sessionId, head.jobId) ?? null,
+            lastModelChoiceSequence,
+            compaction: readProcessCompaction(owner, sessionId),
+        },
+        progress: readProcessProgressForWork(owner, sessionId, head.jobId),
+    };
+}

package/dist/internal/woodstock/agent-reply.d.ts

@@ -0,0 +1,25 @@
+import type { UserMessage } from "@fungi.computer/mule/effect";
+import * as Schema from "effect/Schema";
+/**
+ * A delegated Agent's reply after the admitting host authenticated it against
+ * the mail it sent: the replying Agent and Session plus BirdDog's settlement
+ * facts. Only `acceptMail` stores it, and only the host passes it.
+ */
+export declare const VerifiedAgentReplySchema: Schema.Struct<{
+    readonly commandId: Schema.String;
+    readonly outcome: Schema.Literals<readonly ["completed", "failed", "interrupted", "cancelled", "outcome_unknown"]>;
+    readonly diagnostic: Schema.optionalKey<Schema.String>;
+    readonly agentId: Schema.String;
+    readonly sessionId: Schema.String;
+}>;
+/** A delegated Agent's reply after the admitting host authenticated it. */
+export type VerifiedAgentReply = typeof VerifiedAgentReplySchema.Type;
+/** The tag that marks a host-verified Agent reply in model context. */
+export declare const AGENT_REPLY_TAG = "fungi_agent_reply";
+/**
+ * What a model sees of one stored user-role line. Every typed, mailed or
+ * operator text is neutralized, so only Shiitake can open the verified-reply
+ * tag; a line the host admitted with a verified reply is wrapped in it. The
+ * provider role stays `user`.
+ */
+export declare function userContextMessage(message: UserMessage, reply?: VerifiedAgentReply): UserMessage;

package/dist/internal/woodstock/agent-reply.js

@@ -0,0 +1,67 @@
+import { BirdDogReplySchema } from "@fungi.computer/bird-dog/effect";
+import * as Schema from "effect/Schema";
+const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/**
+ * A delegated Agent's reply after the admitting host authenticated it against
+ * the mail it sent: the replying Agent and Session plus BirdDog's settlement
+ * facts. Only `acceptMail` stores it, and only the host passes it.
+ */
+export const VerifiedAgentReplySchema = Schema.Struct({
+    agentId: Identifier,
+    sessionId: Identifier,
+    ...BirdDogReplySchema.fields,
+});
+/** The tag that marks a host-verified Agent reply in model context. */
+export const AGENT_REPLY_TAG = "fungi_agent_reply";
+// `<` before the tag name, allowing the spacing and case a model would still read as the tag.
+const tagOpening = new RegExp(`<(?=\\s*/?\\s*${AGENT_REPLY_TAG})`, "giu");
+/** Make untrusted text unable to open or close the verified-reply tag. */
+function neutralize(text) {
+    return text.replace(tagOpening, "&lt;");
+}
+function attribute(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function opening(reply) {
+    const attributes = [
+        ["agent_id", reply.agentId],
+        ["session_id", reply.sessionId],
+        ["command_id", reply.commandId],
+        ["outcome", reply.outcome],
+    ];
+    if (reply.diagnostic !== undefined)
+        attributes.push(["diagnostic", reply.diagnostic]);
+    const rendered = attributes
+        .map(([name, value]) => `${name}="${attribute(value)}"`)
+        .join(" ");
+    return `<${AGENT_REPLY_TAG} ${rendered}>`;
+}
+/**
+ * What a model sees of one stored user-role line. Every typed, mailed or
+ * operator text is neutralized, so only Shiitake can open the verified-reply
+ * tag; a line the host admitted with a verified reply is wrapped in it. The
+ * provider role stays `user`.
+ */
+export function userContextMessage(message, reply) {
+    const content = Array.isArray(message.content)
+        ? message.content.map((part) => part.type === "text" ? { ...part, text: neutralize(part.text) } : part)
+        : neutralize(message.content);
+    if (reply === undefined)
+        return { ...message, content };
+    const open = opening(reply);
+    const close = `</${AGENT_REPLY_TAG}>`;
+    return {
+        ...message,
+        content: Array.isArray(content)
+            ? [
+                { type: "text", text: open },
+                ...content,
+                { type: "text", text: close },
+            ]
+            : `${open}\n${content}\n${close}`,
+    };
+}

package/dist/internal/woodstock/client-projection.d.ts

@@ -0,0 +1,29 @@
+import type { SessionFrame, SessionExtensionSlots, SessionSnapshot } from "../../client.js";
+import type { ClientReadOptions } from "../client-boundary.js";
+import type { CommandSettlement, SqliteOwner } from "../contracts.js";
+import type { ObservedActivity } from "../session-status.js";
+import { type StoredSessionRow } from "./session-store.js";
+/**
+ * Newest failure message each work recorded: a work-terminal diagnostic, an
+ * assistant error or a final retry error. Raw text; clients and the reply
+ * fan-out decide how to present and bound it.
+ */
+export declare function diagnosticsByWorkId(path: readonly StoredSessionRow[]): ReadonlyMap<string, string>;
+/**
+ * Read one bounded public baseline from the selected Session lineage. Only
+ * the page's rows are decoded; `before` pages back through the whole saved
+ * history, including what compaction summarized away.
+ */
+export declare function readClientSnapshot(owner: SqliteOwner, sessionId: string, options: ClientReadOptions, activity: ObservedActivity, projectExtensions?: () => SessionExtensionSlots): SessionSnapshot;
+/** One bounded durable replay decision for the process-local observation stream. */
+export type ClientReplayPage = Readonly<{
+    kind: "page";
+    frames: readonly SessionFrame[];
+    hasMore: boolean;
+}> | Readonly<{
+    kind: "reset";
+}>;
+/** Read strict-after history plus the current waiting-admission view. */
+export declare function readClientReplayPage(owner: SqliteOwner, sessionId: string, after: string | undefined, delivery: "replay" | "live", activity: ObservedActivity, projectExtensions?: () => SessionExtensionSlots, includeSandboxFailures?: boolean): ClientReplayPage;
+/** Project one exact command's durable facts without selecting a transcript lineage. */
+export declare function projectCommandSettlement(owner: SqliteOwner, sessionId: string, commandId: string): CommandSettlement | undefined;