@fungi.computer/shiitake 0.0.0-stage → 0.0.1

package/dist/internal/compaction/session-compaction.js

@@ -0,0 +1,330 @@
+import { isContextOverflow, } from "@fungi.computer/mule/effect";
+import { isRecoverableLength } from "@earendil-works/pi-ai";
+import * as Effect from "effect/Effect";
+import { ShiitakeError } from "../../errors.js";
+import { borrowedView, compact, prepareCompaction, } from "./compaction.js";
+import { estimateContextTokens, estimateTokens, shouldCompact, } from "./utils.js";
+import { appendCompactionNotice, appendCompactionTransition, beginCompactionActivity, buildSessionContext, endCompactionActivity, withdrawnWorkIds, contextMessageIds, commandContextMessage, operatorContextMessage, promptCommand, readSessionContextPath, } from "../woodstock/index.js";
+function runtimeFailure(message) {
+    return new ShiitakeError("runtime", "rejected", message);
+}
+const commitFailures = {
+    handoff: "The compaction handoff failed; the conversation context is unchanged",
+    conflict: "The Session changed during compaction; the conversation context is unchanged",
+};
+/**
+ * A commit that stopped before its CAS append took effect. The phase is
+ * owner-closed, so its diagnostic is safe to record and show.
+ */
+export class CompactionCommitError extends ShiitakeError {
+    phase;
+    constructor(phase) {
+        super(phase === "conflict" ? "store" : "runtime", phase === "conflict" ? "conflict" : "rejected", commitFailures[phase]);
+        this.phase = phase;
+    }
+    get diagnostic() {
+        return commitFailures[this.phase];
+    }
+}
+function sourceEntries(path, activeWorkId) {
+    const visible = contextMessageIds(path, activeWorkId);
+    const withdrawn = withdrawnWorkIds(path);
+    const entries = [];
+    for (const row of path) {
+        const prompt = promptCommand(row.entry);
+        if (prompt !== undefined && !withdrawn.has(prompt.workId)) {
+            entries.push({
+                id: row.id,
+                kind: "message",
+                message: commandContextMessage(prompt),
+            });
+            continue;
+        }
+        if (row.entry.kind === "operator") {
+            entries.push({
+                id: row.id,
+                kind: "message",
+                message: operatorContextMessage(row.entry),
+            });
+            continue;
+        }
+        if (row.entry.kind === "message") {
+            if (visible.has(row.id))
+                entries.push({ id: row.id, kind: "message", message: row.entry.value });
+            continue;
+        }
+        if (row.entry.kind === "compaction") {
+            const compaction = {
+                id: row.id,
+                kind: "compaction",
+                timestamp: row.timestamp,
+                firstKeptEntryId: row.entry.firstKeptEntryId,
+                summary: row.entry.summary,
+                usage: row.entry.usage,
+            };
+            entries.push(row.entry.details === undefined
+                ? compaction
+                : { ...compaction, details: row.entry.details });
+        }
+    }
+    return entries;
+}
+/** The current context rows: the latest kept window, never the whole lineage. */
+function readPath(store, sessionId, workId) {
+    return Effect.try({
+        try: () => readSessionContextPath(store, { sessionId, workId }),
+        catch: (error) => error instanceof ShiitakeError && error.cause === "context_too_large"
+            ? error
+            : runtimeFailure("Woodstock selected lineage is unavailable"),
+    });
+}
+/**
+ * The compaction owner's context estimate: Pi's usage-plus-trailing count,
+ * excluding provider usage that belongs before Woodstock's latest boundary.
+ *
+ * A provider's reported usage measures the context it actually read, so it
+ * is authoritative only while nothing has reshaped that context since. Once
+ * a compaction lands, every kept message's own usage figure is stale: it
+ * priced the pre-compaction history, not the summary that replaced it. The
+ * one safe fallback is a fresh chars/4 estimate of every message still in
+ * view, the same method `tokensAfterCompaction` uses when it records the
+ * marker's own `tokensAfter` at commit time; trailing-after-usage alone
+ * would undercount (even to zero, when the kept tail's own reply is the
+ * newest message and nothing followed it).
+ */
+export function estimateThresholdContextTokens(path, messages) {
+    const boundary = path.reduce((latest, row) => (row.entry.kind === "compaction" ? row.timestamp : latest), undefined);
+    const estimate = estimateContextTokens(messages);
+    const usageIndex = estimate.lastUsageIndex;
+    const usageMessage = usageIndex === null ? undefined : messages[usageIndex];
+    if (boundary === undefined ||
+        usageMessage?.role !== "assistant" ||
+        usageMessage.timestamp > boundary)
+        return estimate.tokens;
+    return messages.reduce((sum, message) => sum + estimateTokens(message), 0);
+}
+/** The context the model reads once a compaction row becomes the boundary. */
+function tokensAfterCompaction(path, expected, entry, workId) {
+    const boundary = {
+        ...expected,
+        id: `${expected.id}:compaction`,
+        parentId: expected.id,
+        sequence: expected.sequence + 1,
+        timestamp: Date.now(),
+        entry,
+    };
+    return buildSessionContext([...path, boundary], workId).reduce((sum, message) => sum + estimateTokens(message), 0);
+}
+/** One exact preparation, handoff, CAS append, and authoritative rebuild. */
+function commitCompaction(input, path, request) {
+    return Effect.suspend(() => {
+        beginCompactionActivity(input.store, input.sessionId, request.trigger);
+        return commitCompactionEffect(input, path, request).pipe(Effect.ensuring(Effect.sync(() => {
+            endCompactionActivity(input.store, input.sessionId);
+        })));
+    });
+}
+/** The commit itself; `commitCompaction` wraps it with the live activity fact. */
+function commitCompactionEffect(input, path, request) {
+    return Effect.gen(function* () {
+        const preparation = prepareCompaction(sourceEntries(path, input.workId), input.settings);
+        if (preparation === undefined)
+            return undefined;
+        const expected = path.at(-1);
+        if (expected === undefined)
+            return undefined;
+        const result = yield* compact(preparation, input.model, input.stream, request.instructions);
+        if (input.handoff !== undefined)
+            yield* input.handoff
+                .consume(borrowedView(preparation, result, expected.id))
+                .pipe(Effect.mapError(() => new CompactionCommitError("handoff")));
+        const tokensAfter = tokensAfterCompaction(path, expected, {
+            kind: "compaction",
+            resumesRun: request.resumesRun,
+            trigger: request.trigger,
+            workId: input.workId,
+            firstKeptEntryId: result.firstKeptEntryId,
+            summary: result.summary,
+            tokensBefore: result.tokensBefore,
+            usage: result.usage,
+            contextRevision: expected.id,
+        }, input.workId);
+        const committed = yield* Effect.try({
+            try: () => appendCompactionTransition(input.store, {
+                sessionId: input.sessionId,
+                resumesRun: request.resumesRun,
+                trigger: request.trigger,
+                tokensAfter,
+                expectedLeafId: expected.id,
+                workId: input.workId,
+                firstKeptEntryId: result.firstKeptEntryId,
+                summary: result.summary,
+                tokensBefore: result.tokensBefore,
+                usage: result.usage,
+                contextRevision: expected.id,
+                details: result.details,
+            }),
+            catch: (error) => error instanceof ShiitakeError
+                ? error.cause === "conflict"
+                    ? new CompactionCommitError("conflict")
+                    : error
+                : runtimeFailure("Woodstock compaction append failed"),
+        });
+        const committedPath = [...path, committed];
+        return {
+            path: committedPath,
+            messages: buildSessionContext(committedPath, input.workId),
+        };
+    });
+}
+/** A failure's display-safe reason: owner-closed text or the model's message. */
+function failureDiagnostic(error) {
+    if (error instanceof CompactionCommitError)
+        return error.diagnostic;
+    if (error.boundary === "model")
+        return error.message;
+    return `Compaction failed (${error.boundary}: ${error.cause})`;
+}
+/** Record a compaction that committed nothing, so clients can show it. */
+function recordNotice(input, trigger, failure) {
+    return Effect.try({
+        try: () => {
+            appendCompactionNotice(input.store, {
+                sessionId: input.sessionId,
+                workId: input.workId,
+                trigger,
+                result: failure === undefined ? "nothing_to_compact" : "failed",
+                diagnostic: failure === undefined ? undefined : failureDiagnostic(failure),
+            });
+        },
+        catch: (error) => error instanceof ShiitakeError
+            ? error
+            : runtimeFailure("Compaction notice could not be recorded"),
+    });
+}
+/**
+ * Run one automatic compaction. A failure is recorded as a notice and the
+ * caller keeps its current context; automatic compaction never fails a run.
+ */
+function autoCompaction(input, path, request) {
+    return Effect.result(commitCompaction(input, path, request)).pipe(Effect.flatMap((result) => result._tag === "Success"
+        ? Effect.succeed(result.success)
+        : recordNotice(input, request.trigger, result.failure).pipe(Effect.as(undefined))));
+}
+/** Apply the pre-run threshold check, preserving unchanged input on failure. */
+function preRunMessages(input) {
+    if (input.resuming === true ||
+        !shouldCompact(estimateThresholdContextTokens(input.path, input.messages), input.model.contextWindow, input.settings))
+        return Effect.succeed({ path: input.path, messages: input.messages });
+    return autoCompaction(input, input.path, {
+        trigger: "threshold",
+        resumesRun: false,
+    }).pipe(Effect.map((compacted) => compacted ?? { path: input.path, messages: input.messages }));
+}
+function classifyRecovery(outcome, model) {
+    const overflow = isContextOverflow(outcome.message, model.contextWindow);
+    const recoverableLength = isRecoverableLength(outcome.message, model.maxTokens);
+    return {
+        triggered: overflow || recoverableLength,
+        overflow,
+        retry: (overflow || recoverableLength) && outcome.message.stopReason !== "stop",
+    };
+}
+function removeFailedAssistant(messages) {
+    const last = messages.at(-1);
+    return last?.role === "assistant" &&
+        (last.stopReason === "error" || last.stopReason === "length")
+        ? messages.slice(0, -1)
+        : messages;
+}
+function postRunPath(input, working, outcome, recovery) {
+    if (!input.settings.enabled)
+        return Effect.succeed(undefined);
+    const threshold = shouldCompact(estimateThresholdContextTokens(working.path, [
+        ...working.messages,
+        ...outcome.messages.slice(working.newMessageCount),
+    ]), input.model.contextWindow, input.settings);
+    return recovery.triggered || threshold
+        ? readPath(input.store, input.sessionId, input.workId)
+        : Effect.succeed(undefined);
+}
+/**
+ * Pi's between-turn threshold check: when a running work's context has grown
+ * past the threshold, compact the durable lineage (which already holds this
+ * turn's tool results) and continue from the rebuilt context.
+ */
+function betweenTurns(input, working) {
+    return (context, newMessageCount) => Effect.gen(function* () {
+        if (!shouldCompact(estimateThresholdContextTokens(working.path, context), input.model.contextWindow, input.settings))
+            return undefined;
+        const path = yield* readPath(input.store, input.sessionId, input.workId);
+        const compacted = yield* autoCompaction(input, path, {
+            trigger: "threshold",
+            resumesRun: false,
+        });
+        if (compacted === undefined)
+            return undefined;
+        working.path = compacted.path;
+        working.messages = compacted.messages;
+        working.newMessageCount = newMessageCount;
+        return compacted.messages;
+    });
+}
+/** Run terminal outcomes through post-threshold and one-time recovery policy. */
+function postRunOutcome(input, initial) {
+    return Effect.gen(function* () {
+        let current = initial;
+        let recoveryAttempted = initial.path.some(({ entry }) => entry.kind === "compaction" &&
+            entry.workId === input.workId &&
+            entry.resumesRun === true);
+        for (;;) {
+            const working = {
+                path: current.path,
+                messages: current.messages,
+                newMessageCount: 0,
+            };
+            const outcome = yield* input.run(working.messages, betweenTurns(input, working));
+            const recovery = classifyRecovery(outcome, input.model);
+            const path = yield* postRunPath(input, working, outcome, recovery);
+            if (path === undefined)
+                return outcome;
+            if (recovery.retry && recoveryAttempted)
+                return outcome;
+            const compacted = yield* autoCompaction(input, path, {
+                trigger: recovery.overflow ? "overflow" : "threshold",
+                resumesRun: recovery.retry,
+            });
+            if (compacted === undefined || !recovery.retry)
+                return outcome;
+            current = {
+                path: compacted.path,
+                messages: removeFailedAssistant(compacted.messages),
+            };
+            recoveryAttempted = true;
+        }
+    });
+}
+/** Compose the retained pre-run, between-turn and post-run compaction phases. */
+export function runWithCompaction(input) {
+    if (!input.settings.enabled)
+        return postRunOutcome(input, input);
+    return preRunMessages(input).pipe(Effect.flatMap((initial) => postRunOutcome(input, initial)));
+}
+/**
+ * Compact one Session now, as accepted work: the same commit the automatic
+ * triggers use, with `resumesRun: false`, the user's optional focus and no
+ * model turn. "Nothing to compact" and a failure are each recorded as a
+ * notice. A retried claim of the same work never compacts twice.
+ */
+export function compactSession(input) {
+    if (input.path.some(({ entry }) => (entry.kind === "compaction" || entry.kind === "compaction_notice") &&
+        entry.workId === input.workId))
+        return Effect.succeed("compacted");
+    return commitCompaction(input, input.path, {
+        trigger: "manual",
+        resumesRun: false,
+        instructions: input.instructions,
+    }).pipe(Effect.tapError((error) => recordNotice(input, "manual", error)), Effect.flatMap((committed) => committed === undefined
+        ? recordNotice(input, "manual", undefined).pipe(Effect.as("nothing_to_compact"))
+        : Effect.succeed("compacted")));
+}

package/dist/internal/compaction/settings.d.ts

@@ -0,0 +1,11 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { CompactionOptions } from "../contracts.js";
+import { type CompactionSettings } from "./utils.js";
+/** Resolve one model's compaction settings from the host's validated options. */
+export type CompactionSettingsFor = (model: Model<Api>) => CompactionSettings;
+/**
+ * Validate the host's compaction options once, when the owner opens, and
+ * resolve each budget per model: exact `provider/modelId` override, then the
+ * ordinary value, then Pi's default.
+ */
+export declare function openCompactionSettings(options: CompactionOptions | undefined): CompactionSettingsFor;

package/dist/internal/compaction/settings.js

@@ -0,0 +1,40 @@
+import * as Schema from "effect/Schema";
+import { ShiitakeError } from "../../errors.js";
+import { DEFAULT_COMPACTION_SETTINGS, } from "./utils.js";
+const tokens = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)), Schema.check(Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)));
+const BudgetSchema = Schema.Struct({
+    reserveTokens: Schema.optionalKey(tokens),
+    keepRecentTokens: Schema.optionalKey(tokens),
+});
+const CompactionOptionsSchema = Schema.Struct({
+    enabled: Schema.optionalKey(Schema.Boolean),
+    reserveTokens: Schema.optionalKey(tokens),
+    keepRecentTokens: Schema.optionalKey(tokens),
+    modelOverrides: Schema.optionalKey(Schema.Record(Schema.String, BudgetSchema)),
+});
+const decodeOptions = Schema.decodeUnknownResult(CompactionOptionsSchema, {
+    onExcessProperty: "error",
+});
+/**
+ * Validate the host's compaction options once, when the owner opens, and
+ * resolve each budget per model: exact `provider/modelId` override, then the
+ * ordinary value, then Pi's default.
+ */
+export function openCompactionSettings(options) {
+    const decoded = decodeOptions(options ?? {});
+    if (decoded._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Compaction settings must be non-negative whole token counts");
+    const settings = decoded.success;
+    return (model) => {
+        const override = settings.modelOverrides?.[`${model.provider}/${model.id}`];
+        return {
+            enabled: settings.enabled ?? DEFAULT_COMPACTION_SETTINGS.enabled,
+            reserveTokens: override?.reserveTokens ??
+                settings.reserveTokens ??
+                DEFAULT_COMPACTION_SETTINGS.reserveTokens,
+            keepRecentTokens: override?.keepRecentTokens ??
+                settings.keepRecentTokens ??
+                DEFAULT_COMPACTION_SETTINGS.keepRecentTokens,
+        };
+    };
+}

package/dist/internal/compaction/utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Adapted from the maintained Pi v0.84.4 coding-agent compaction utilities.
+ * The only destination delta is carrying Pi's native Message values directly.
+ */
+import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
+/** Pi's native compaction boundary projection, retained without a custom role. */
+export declare function compactionSummaryMessage(summary: string, timestamp: number): Message;
+export type FileOperations = {
+    edited: Set<string>;
+    read: Set<string>;
+    written: Set<string>;
+};
+export declare function createFileOps(): FileOperations;
+export declare function extractFileOpsFromMessage(message: Message, fileOps: FileOperations): void;
+export declare function computeFileLists(fileOps: FileOperations): {
+    modifiedFiles: string[];
+    readFiles: string[];
+};
+export declare function formatFileOperations(readFiles: readonly string[], modifiedFiles: readonly string[]): string;
+export declare function serializeConversation(messages: readonly Message[]): string;
+/** Pi's chars/4 estimator, including its image and tool-call constants. */
+export declare function estimateTokens(message: Message): number;
+export declare function estimateContextTokens(messages: readonly Message[]): {
+    tokens: number;
+    usageTokens: number;
+    trailingTokens: number;
+    lastUsageIndex: null;
+} | {
+    tokens: number;
+    usageTokens: number;
+    trailingTokens: number;
+    lastUsageIndex: number;
+};
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+export type CompactionSettings = {
+    enabled: boolean;
+    reserveTokens: number;
+    keepRecentTokens: number;
+};
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
+export declare const SUMMARIZATION_PROMPT = "The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.\n\nUse this EXACT format:\n\n## Goal\n[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements mentioned by user]\n- [Or \"(none)\" if none were mentioned]\n\n## Progress\n### Done\n- [x] [Completed tasks/changes]\n\n### In Progress\n- [ ] [Current work]\n\n### Blocked\n- [Issues preventing progress, if any]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Ordered list of what should happen next]\n\n## Critical Context\n- [Any data, examples, or references needed to continue]\n- [Or \"(none)\" if not applicable]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.";
+export declare const UPDATE_SUMMARIZATION_PROMPT = "The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.\n\nUpdate the existing structured summary with new information. RULES:\n- PRESERVE all existing information from the previous summary\n- ADD new progress, decisions, and context from the new messages\n- UPDATE the Progress section: move items from \"In Progress\" to \"Done\" when completed\n- UPDATE \"Next Steps\" based on what was accomplished\n- PRESERVE exact file paths, function names, and error messages\n- If something is no longer relevant, you may remove it\n\nUse this EXACT format:\n\n## Goal\n[Preserve existing goals, add new ones if the task expanded]\n\n## Constraints & Preferences\n- [Preserve existing, add new ones discovered]\n\n## Progress\n### Done\n- [x] [Include previously done items AND newly completed items]\n\n### In Progress\n- [ ] [Current work - update based on progress]\n\n### Blocked\n- [Current blockers - remove if resolved]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale] (preserve all previous, add new)\n\n## Next Steps\n1. [Update based on current state]\n\n## Critical Context\n- [Preserve important context, add new if needed]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.";
+export declare const TURN_PREFIX_SUMMARIZATION_PROMPT = "The messages above are earlier context from an ongoing conversation. Later messages are stored separately and do not need to be reconstructed.\n\nCreate a concise checkpoint of the user's request and the progress shown above. This checkpoint will be placed before the later messages so the conversation can continue with the necessary context.\n\n## Original Request\n[What did the user ask for?]\n\n## Progress So Far\n- [Key decisions and work completed in these messages]\n\n## Context Needed to Continue\n- [Information from these messages needed to understand the later work]\n\nOnly summarize information explicitly present above. Do not infer or recreate later messages.";
+export declare function summaryFailure(response: AssistantMessage, label: string): string | undefined;