@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/internal/client-boundary.js

@@ -0,0 +1,202 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { ShiitakeError } from "../errors.js";
+const encoder = new TextEncoder();
+function boundedText(maximumBytes) {
+    return Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maximumBytes), Schema.makeFilter((value) => encoder.encode(value).byteLength <= maximumBytes));
+}
+const boundedId = boundedText(256);
+/**
+ * The one prompt-text grammar. Human, mail, host and extension prompts are all
+ * admitted through the accepted-command door under this bound. Text is
+ * stored exactly as sent: no decoder trims it.
+ */
+const PromptTextSchema = boundedText(256 * 1024);
+/** Bounded image payload admitted and persisted by the Session owner. */
+export const PromptImageSchema = Schema.Struct({
+    type: Schema.Literal("image"),
+    data: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(1024 * 1024), Schema.isBase64()),
+    mimeType: Schema.String.check(Schema.makeFilter((value) => ["image/png", "image/jpeg", "image/gif", "image/webp"].includes(value))),
+});
+const PromptImagesSchema = Schema.Array(PromptImageSchema).check(Schema.isMinLength(1), Schema.isMaxLength(8));
+const PromptDeliverySchema = Schema.Literals(["steer", "followUp"]);
+const SessionIdSchema = boundedId;
+const decodeSessionPageCursorValue = Schema.decodeUnknownResult(boundedText(512));
+const SessionCreationRequestSchema = Schema.Struct({ requestId: boundedId });
+const PromptCommandSchema = Schema.Struct({
+    delivery: PromptDeliverySchema,
+    requestId: boundedId,
+    type: Schema.Literal("prompt"),
+    text: Schema.String.check(Schema.isMaxLength(256 * 1024), Schema.makeFilter((value) => encoder.encode(value).byteLength <= 256 * 1024)),
+    images: Schema.optionalKey(PromptImagesSchema),
+}).check(Schema.makeFilter((value) => (value.text.length > 0 || (value.images?.length ?? 0) > 0) &&
+    encoder.encode(value.text).byteLength +
+        (value.images ?? []).reduce((bytes, image) => bytes + image.data.length, 0) <=
+        1024 * 1024));
+const AbortCommandSchema = Schema.Struct({ type: Schema.Literal("abort") });
+const CancelCommandSchema = Schema.Struct({
+    commandId: boundedId,
+    onlyIfPending: Schema.optional(Schema.Boolean),
+    type: Schema.Literal("cancel"),
+});
+/**
+ * One human-to-human line recorded into an idle Session outside any run, for
+ * example during a live takeover: `operator` is a person answering for the
+ * Agent, `party` is the other side's message while the Agent is held. It is
+ * context for later runs, is idempotent by request id and starts no run.
+ */
+const OperatorCommandSchema = Schema.Struct({
+    type: Schema.Literal("operator"),
+    requestId: boundedId,
+    author: Schema.Literals(["operator", "party"]),
+    text: PromptTextSchema,
+});
+const BranchCommandSchema = Schema.Struct({
+    type: Schema.Literal("branch"),
+    entryId: boundedId,
+});
+const ForkCommandSchema = Schema.Struct({
+    type: Schema.Literal("fork"),
+    entryId: boundedId,
+});
+/**
+ * Compact the Session's context now. It is accepted Session work, queued
+ * behind any running work and idempotent by `requestId`; it runs no model
+ * turn beyond the summary and never enters model context or a title.
+ */
+/** Bounded focus text a manual compaction passes to its summary. */
+export const CompactionInstructionsSchema = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(4_096));
+const CompactCommandSchema = Schema.Struct({
+    type: Schema.Literal("compact"),
+    requestId: boundedId,
+    /** Focus for the summary, appended as Pi's "Additional focus". */
+    instructions: Schema.optionalKey(CompactionInstructionsSchema),
+});
+/** Work the accepted-command door admits: a prompt or a compaction request. */
+const AcceptedCommandSchema = Schema.Union([
+    PromptCommandSchema,
+    CompactCommandSchema,
+]);
+/**
+ * The longest Session title, in Unicode code points; the derived first-prompt
+ * title uses the same bound.
+ */
+export const sessionTitleLimit = 120;
+/** One user-set Session title: trimmed, single-line and bounded. */
+export const SessionTitleSchema = Schema.String.check(Schema.makeFilter((value) => value.length > 0 &&
+    value.trim() === value &&
+    !/\p{Cc}/u.test(value) &&
+    Array.from(value).length <= sessionTitleLimit));
+/**
+ * Set or clear the user's Session title. It is display metadata only: it
+ * overrides the first-prompt title everywhere the title shows, and `null`
+ * restores the derived title. Session identity and history are unchanged.
+ */
+const TitleCommandSchema = Schema.Struct({
+    type: Schema.Literal("title"),
+    title: Schema.NullOr(SessionTitleSchema),
+});
+const SessionCommandSchema = Schema.Union([
+    PromptCommandSchema,
+    AbortCommandSchema,
+    CancelCommandSchema,
+    BranchCommandSchema,
+    ForkCommandSchema,
+    OperatorCommandSchema,
+    CompactCommandSchema,
+    TitleCommandSchema,
+]);
+const SessionCommandRequestSchema = Schema.Struct({
+    command: SessionCommandSchema,
+});
+const ReadOptionsSchema = Schema.Struct({
+    includeSandboxFailures: Schema.optional(Schema.Boolean),
+    limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+    before: Schema.optional(boundedText(512)),
+});
+const ReadQuerySchema = Schema.Struct({
+    includeSandboxFailures: Schema.optional(Schema.Literal("true")),
+    limit: Schema.optional(Schema.NumberFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 200 }))),
+    before: Schema.optional(boundedText(512)),
+});
+const SubscribeOptionsSchema = Schema.Struct({
+    includeSandboxFailures: Schema.optional(Schema.Boolean),
+    after: Schema.optional(Schema.String),
+});
+const EventsQuerySchema = Schema.Struct({
+    includeSandboxFailures: Schema.optional(Schema.Literal("true")),
+    mode: Schema.optional(Schema.Literal("subscribe")),
+    after: Schema.optional(Schema.String),
+    limit: Schema.optional(Schema.NumberFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+const closed = { onExcessProperty: "error" };
+const decodeSessionIdValue = Schema.decodeUnknownResult(SessionIdSchema, closed);
+export const decodeClientSessionCreationRequest = Schema.decodeUnknownResult(SessionCreationRequestSchema, closed);
+/** The accepted-command door's one decoder for queued Session work. */
+export const decodeClientAcceptedCommand = Schema.decodeUnknownResult(AcceptedCommandSchema, closed);
+/** Decode one owner-issued identity (command, extension or cursor). */
+export const decodeClientIdentity = Schema.decodeUnknownResult(boundedId);
+export const decodeClientSessionCommand = Schema.decodeUnknownResult(SessionCommandSchema, closed);
+export const decodeClientSessionCommandRequest = Schema.decodeUnknownResult(SessionCommandRequestSchema, closed);
+const decodeReadOptionsValue = Schema.decodeUnknownResult(Schema.Union([ReadOptionsSchema, Schema.Undefined]), closed);
+export const decodeClientReadQuery = Schema.decodeUnknownResult(ReadQuerySchema, closed);
+const decodeSubscribeOptionsValue = Schema.decodeUnknownResult(SubscribeOptionsSchema, closed);
+export const decodeClientEventsQuery = Schema.decodeUnknownResult(EventsQuerySchema, closed);
+/** Decode one ordinary Session-id value without exposing input detail. */
+export function decodeClientSessionId(value) {
+    const decoded = decodeSessionIdValue(value);
+    if (decoded._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Session id is invalid");
+    return decoded.success;
+}
+/** Decode one opaque session-page cursor; its owner decodes the position. */
+export function decodeClientPageCursor(value) {
+    const decoded = decodeSessionPageCursorValue(value);
+    if (decoded._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Session cursor is invalid");
+    return decoded.success;
+}
+/** Decode the exact public Session creation request. */
+export function decodeClientSessionCreationRequestId(value) {
+    const decoded = decodeClientSessionCreationRequest(value);
+    if (decoded._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Session creation request is invalid");
+    return decoded.success.requestId;
+}
+/** Decode and normalize the exact public C1 read option bag. */
+export function decodeClientReadOptions(value) {
+    const decoded = decodeReadOptionsValue(value);
+    if (decoded._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Read options are invalid");
+    const read = decoded.success ?? {};
+    let options = { limit: read.limit ?? 200 };
+    if (read.before !== undefined)
+        options = { ...options, before: read.before };
+    if (read.includeSandboxFailures !== undefined)
+        options = {
+            ...options,
+            includeSandboxFailures: read.includeSandboxFailures,
+        };
+    return Object.freeze(options);
+}
+/** Decode the exact public C2 subscribe option bag before cursor classification. */
+export function decodeClientSubscribeOptions(value) {
+    const decoded = decodeSubscribeOptionsValue(value);
+    if (decoded._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Subscribe options are invalid");
+    let options = {};
+    if (decoded.success.after !== undefined)
+        options = { ...options, after: decoded.success.after };
+    if (decoded.success.includeSandboxFailures !== undefined)
+        options = {
+            ...options,
+            includeSandboxFailures: decoded.success.includeSandboxFailures,
+        };
+    return Object.freeze(options);
+}
+/** Take one decoder result, or reject with a sanitized contract error. */
+export function requireDecoded(decoded, message) {
+    if (Result.isFailure(decoded))
+        throw new ShiitakeError("contract", "invalid", message);
+    return decoded.success;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Pi v0.84.4 semantic compaction, adapted only at Woodstock's entry boundary.
+ * The retained preparation/result vocabulary is intentionally visible here;
+ * Shiitake supplies native Message values and its selected model stream.
+ */
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
+import type { MuleStreamFunction } from "@fungi.computer/mule/effect";
+import * as Effect from "effect/Effect";
+import type { BorrowedCompactionViewV0 } from "../../extensions.js";
+import { ShiitakeError } from "../../errors.js";
+import { createFileOps, type CompactionSettings } from "./utils.js";
+export type CompactionSourceEntry = Readonly<{
+    id: string;
+    kind: "message";
+    message: import("@earendil-works/pi-ai").Message;
+}> | Readonly<{
+    id: string;
+    kind: "compaction";
+    timestamp: number;
+    firstKeptEntryId: string;
+    summary: string;
+    usage: Usage;
+    details?: Readonly<{
+        readFiles: readonly string[];
+        modifiedFiles: readonly string[];
+    }>;
+}>;
+export type CompactionPreparation = Readonly<{
+    firstKeptEntryId: string;
+    messagesToSummarize: readonly import("@earendil-works/pi-ai").Message[];
+    turnPrefixMessages: readonly import("@earendil-works/pi-ai").Message[];
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    previousSummary?: string;
+    fileOps: ReturnType<typeof createFileOps>;
+    settings: CompactionSettings;
+}>;
+export type CompactionResult = Readonly<{
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    usage: Usage;
+    details: Readonly<{
+        readFiles: readonly string[];
+        modifiedFiles: readonly string[];
+    }>;
+}>;
+/** Mechanically retained Pi preparation, using only context-visible Woodstock entries. */
+export declare function prepareCompaction(entries: readonly CompactionSourceEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+/** Generate Pi's history and optional split-turn summaries, in order. */
+export declare function compact(preparation: CompactionPreparation, model: Model<Api>, streamFn?: MuleStreamFunction, 
+/** A manual compaction's focus, appended to the history summary prompt. */
+instructions?: string): Effect.Effect<CompactionResult, ShiitakeError>;
+export declare function borrowedView(preparation: CompactionPreparation, result: CompactionResult, contextRevision: string): BorrowedCompactionViewV0;

package/dist/internal/compaction/compaction.js

@@ -0,0 +1,291 @@
+// Leaf helpers, not Pi's root entry, which also evaluates its validators.
+import { retryAssistantCall } from "@earendil-works/pi-ai/utils/retry";
+import { contentText } from "@earendil-works/pi-ai/utils/text";
+import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
+import { uuidv7 } from "@earendil-works/pi-ai/utils/uuid";
+import * as Effect from "effect/Effect";
+import { ShiitakeError } from "../../errors.js";
+import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, serializeConversation, SUMMARIZATION_PROMPT, SUMMARIZATION_SYSTEM_PROMPT, TURN_PREFIX_SUMMARIZATION_PROMPT, UPDATE_SUMMARIZATION_PROMPT, compactionSummaryMessage, estimateContextTokens, estimateTokens, summaryFailure, } from "./utils.js";
+/** A summary is a model call: its bounded provider message is shown. */
+function failure(message) {
+    return new ShiitakeError("model", "rejected", message);
+}
+function combineUsage(first, second) {
+    const combined = {
+        input: first.input + second.input,
+        output: first.output + second.output,
+        cacheRead: first.cacheRead + second.cacheRead,
+        cacheWrite: first.cacheWrite + second.cacheWrite,
+        totalTokens: first.totalTokens + second.totalTokens,
+        cost: {
+            input: first.cost.input + second.cost.input,
+            output: first.cost.output + second.cost.output,
+            cacheRead: first.cost.cacheRead + second.cost.cacheRead,
+            cacheWrite: first.cost.cacheWrite + second.cost.cacheWrite,
+            total: first.cost.total + second.cost.total,
+        },
+    };
+    if (first.cacheWrite1h !== undefined || second.cacheWrite1h !== undefined)
+        combined.cacheWrite1h =
+            (first.cacheWrite1h ?? 0) + (second.cacheWrite1h ?? 0);
+    if (first.reasoning !== undefined || second.reasoning !== undefined)
+        combined.reasoning = (first.reasoning ?? 0) + (second.reasoning ?? 0);
+    return combined;
+}
+function contextMessages(entries) {
+    let latest;
+    for (const entry of entries) {
+        if (entry.kind === "compaction")
+            latest = entry;
+    }
+    const latestCompaction = latest;
+    const keptIndex = latestCompaction === undefined
+        ? 0
+        : Math.max(0, entries.findIndex(({ id }) => id === latestCompaction.firstKeptEntryId));
+    const messages = entries.flatMap((entry, index) => entry.kind === "message" && index >= keptIndex ? [entry.message] : []);
+    if (latestCompaction === undefined)
+        return messages;
+    return [
+        compactionSummaryMessage(latestCompaction.summary, latestCompaction.timestamp),
+        ...messages,
+    ];
+}
+function extractFileOperations(messages, entries, previousIndex) {
+    const fileOps = createFileOps();
+    const previous = entries[previousIndex];
+    if (previous?.kind === "compaction" && previous.details !== undefined) {
+        for (const file of previous.details.readFiles)
+            fileOps.read.add(file);
+        for (const file of previous.details.modifiedFiles)
+            fileOps.edited.add(file);
+    }
+    for (const message of messages)
+        extractFileOpsFromMessage(message, fileOps);
+    return fileOps;
+}
+function isCutPoint(message) {
+    return message.role !== "toolResult";
+}
+function selectCutIndex(entries, startIndex, endIndex, keepRecentTokens) {
+    const points = entries.flatMap((entry, index) => entry.kind === "message" &&
+        index >= startIndex &&
+        index < endIndex &&
+        isCutPoint(entry.message)
+        ? [index]
+        : []);
+    const firstPoint = points[0];
+    if (firstPoint === undefined)
+        return undefined;
+    let accumulated = 0;
+    let cut = firstPoint;
+    for (let index = endIndex - 1; index >= startIndex; index -= 1) {
+        const entry = entries[index];
+        if (entry?.kind !== "message")
+            continue;
+        accumulated += estimateTokens(entry.message);
+        if (accumulated >= keepRecentTokens) {
+            // Pi 0.99.2: when trailing tool results alone exceed the budget, keep
+            // their tool call (the last cut point), never fall back to the start.
+            cut =
+                points.find((candidate) => candidate >= index) ?? points.at(-1) ?? cut;
+            break;
+        }
+    }
+    return cut;
+}
+function classifyCut(entries, startIndex, cut) {
+    const cutEntry = entries[cut];
+    const startsTurn = cutEntry?.kind === "message" && cutEntry.message.role === "user";
+    let turnStartIndex = -1;
+    if (!startsTurn) {
+        for (let index = cut; index >= startIndex; index -= 1) {
+            const entry = entries[index];
+            if (entry?.kind === "message" && entry.message.role === "user") {
+                turnStartIndex = index;
+                break;
+            }
+        }
+    }
+    return {
+        isSplitTurn: !startsTurn && turnStartIndex >= 0,
+        turnStartIndex,
+    };
+}
+function findCutPoint(entries, startIndex, endIndex, keepRecentTokens) {
+    const cut = selectCutIndex(entries, startIndex, endIndex, keepRecentTokens);
+    if (cut === undefined)
+        return {
+            firstKeptEntryIndex: startIndex,
+            isSplitTurn: false,
+            turnStartIndex: -1,
+        };
+    return { firstKeptEntryIndex: cut, ...classifyCut(entries, startIndex, cut) };
+}
+/** Mechanically retained Pi preparation, using only context-visible Woodstock entries. */
+export function prepareCompaction(entries, settings) {
+    const last = entries.at(-1);
+    if (last?.kind === "compaction")
+        return undefined;
+    let previousSummary;
+    let previousIndex = -1;
+    let boundaryStart = 0;
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.kind === "compaction") {
+            previousSummary = entry.summary;
+            previousIndex = index;
+            const kept = entries.findIndex((candidate) => candidate.id === entry.firstKeptEntryId);
+            boundaryStart = kept >= 0 ? kept : index + 1;
+            break;
+        }
+    }
+    const visible = entries.flatMap((entry, index) => entry.kind === "message" && index >= boundaryStart ? [entry] : []);
+    const tokensBefore = estimateContextTokens(contextMessages(entries)).tokens;
+    const cut = findCutPoint(visible, 0, visible.length, settings.keepRecentTokens);
+    const firstKept = visible[cut.firstKeptEntryIndex];
+    if (firstKept?.kind !== "message")
+        return undefined;
+    const historyEnd = cut.isSplitTurn
+        ? cut.turnStartIndex
+        : cut.firstKeptEntryIndex;
+    const messagesToSummarize = Object.freeze(visible.slice(0, historyEnd).map(({ message }) => message));
+    const turnPrefixMessages = Object.freeze(cut.isSplitTurn
+        ? visible
+            .slice(cut.turnStartIndex, cut.firstKeptEntryIndex)
+            .map(({ message }) => message)
+        : []);
+    if (messagesToSummarize.length === 0 && turnPrefixMessages.length === 0)
+        return undefined;
+    const fileOps = extractFileOperations(messagesToSummarize, entries, previousIndex);
+    for (const message of turnPrefixMessages)
+        extractFileOpsFromMessage(message, fileOps);
+    const base = {
+        firstKeptEntryId: firstKept.id,
+        messagesToSummarize,
+        turnPrefixMessages,
+        isSplitTurn: cut.isSplitTurn,
+        tokensBefore,
+        fileOps,
+        settings,
+    };
+    return previousSummary === undefined ? base : { ...base, previousSummary };
+}
+// Pi v0.84.4's compaction retry defaults; retryAssistantCall owns the retry policy.
+const RETRY_POLICY = {
+    enabled: true,
+    maxRetries: 3,
+    baseDelayMs: 2000,
+};
+function completeSummarization(model, context, options, streamFn) {
+    const requestOptions = {
+        ...options,
+        cacheRetention: "none",
+        sessionId: options.sessionId ?? uuidv7(),
+    };
+    return retryAssistantCall(() => streamFn
+        ? Promise.resolve(streamFn(model, normalizeContext(context), requestOptions)).then((stream) => stream.result())
+        : import("@earendil-works/pi-ai/compat").then(({ completeSimple }) => completeSimple(model, context, requestOptions)), RETRY_POLICY, requestOptions.signal);
+}
+function buildContext(promptText) {
+    return {
+        systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+        messages: [
+            {
+                role: "user",
+                content: [{ type: "text", text: promptText }],
+                timestamp: Date.now(),
+            },
+        ],
+    };
+}
+function historyPrompt(preparation, hasPreviousSummary, instructions) {
+    const previousSummary = preparation.previousSummary ?? "";
+    const basePrompt = hasPreviousSummary
+        ? UPDATE_SUMMARIZATION_PROMPT
+        : SUMMARIZATION_PROMPT;
+    const focused = instructions === undefined
+        ? basePrompt
+        : `${basePrompt}\n\nAdditional focus: ${instructions}`;
+    return `<conversation>\n${serializeConversation(preparation.messagesToSummarize)}\n</conversation>\n\n${hasPreviousSummary ? `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n` : ""}${focused}`;
+}
+function prefixPrompt(preparation) {
+    return `# Conversation\n${serializeConversation(preparation.turnPrefixMessages)}\n\n# Instructions\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+}
+async function summarize(model, maxTokens, signal, prompt, label, streamFn) {
+    const options = signal === undefined ? { maxTokens } : { maxTokens, signal };
+    const response = await completeSummarization(model, buildContext(prompt), options, streamFn);
+    const failureMessage = summaryFailure(response, label);
+    if (failureMessage !== undefined)
+        throw new Error(failureMessage);
+    return response;
+}
+function historySummary(preparation, model, maxTokens, signal, instructions, streamFn) {
+    if (preparation.messagesToSummarize.length === 0)
+        return Promise.resolve(undefined);
+    const hasPreviousSummary = preparation.previousSummary !== undefined &&
+        preparation.previousSummary.length > 0;
+    return summarize(model, maxTokens, signal, historyPrompt(preparation, hasPreviousSummary, instructions), "Summarization", streamFn);
+}
+function prefixSummary(preparation, model, signal, streamFn) {
+    if (!preparation.isSplitTurn || preparation.turnPrefixMessages.length === 0)
+        return Promise.resolve(undefined);
+    return summarize(model, Math.min(Math.floor(0.5 * preparation.settings.reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY), signal, prefixPrompt(preparation), "Turn prefix summarization", streamFn);
+}
+function composeCompactionResult(preparation, historyResult, turnPrefixResult) {
+    let summary;
+    let usage;
+    if (preparation.isSplitTurn) {
+        if (turnPrefixResult === undefined)
+            throw new Error("Split-turn compaction did not produce a prefix summary");
+        // With no new history to summarize, the previous summary still stands.
+        const historyText = historyResult === undefined
+            ? (preparation.previousSummary ?? "No prior history.")
+            : contentText(historyResult.content);
+        summary = `${historyText}\n\n---\n\n**Turn Context (split turn):**\n\n${contentText(turnPrefixResult.content)}`;
+        usage =
+            historyResult === undefined
+                ? turnPrefixResult.usage
+                : combineUsage(historyResult.usage, turnPrefixResult.usage);
+    }
+    else {
+        if (historyResult === undefined)
+            throw new Error("Compaction did not produce a history summary");
+        summary = contentText(historyResult.content);
+        usage = historyResult.usage;
+    }
+    const files = computeFileLists(preparation.fileOps);
+    return {
+        summary: summary + formatFileOperations(files.readFiles, files.modifiedFiles),
+        firstKeptEntryId: preparation.firstKeptEntryId,
+        tokensBefore: preparation.tokensBefore,
+        usage,
+        details: files,
+    };
+}
+async function compactPromise(preparation, model, signal, instructions, streamFn) {
+    const maxTokens = Math.min(Math.floor(0.8 * preparation.settings.reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
+    // Pi runs the two summaries one after the other: in order, and never two
+    // concurrent calls against a single-concurrency provider (Pi #5536).
+    const historyResult = await historySummary(preparation, model, maxTokens, signal, instructions, streamFn);
+    const turnPrefixResult = preparation.isSplitTurn && preparation.turnPrefixMessages.length > 0
+        ? await prefixSummary(preparation, model, signal, streamFn)
+        : undefined;
+    return composeCompactionResult(preparation, historyResult, turnPrefixResult);
+}
+/** Generate Pi's history and optional split-turn summaries, in order. */
+export function compact(preparation, model, streamFn, 
+/** A manual compaction's focus, appended to the history summary prompt. */
+instructions) {
+    return Effect.tryPromise({
+        try: (effectSignal) => compactPromise(preparation, model, effectSignal, instructions, streamFn),
+        catch: (error) => failure(error instanceof Error ? error.message : String(error)),
+    });
+}
+export function borrowedView(preparation, result, contextRevision) {
+    return {
+        messagesToSummarize: preparation.messagesToSummarize,
+        turnPrefixMessages: preparation.turnPrefixMessages,
+        result,
+        contextRevision,
+    };
+}

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

@@ -0,0 +1,69 @@
+import { type Message, type Model, type Api, type MuleRunOutcome, type MuleStreamFunction } from "@fungi.computer/mule/effect";
+import * as Effect from "effect/Effect";
+import type { CompactionHandoffV0 } from "../../extensions.js";
+import { ShiitakeError } from "../../errors.js";
+import { type CompactionSettings } from "./utils.js";
+import { type StoredSessionRow } from "../woodstock/index.js";
+import type { SqliteOwner } from "../contracts.js";
+declare const commitFailures: {
+    readonly handoff: "The compaction handoff failed; the conversation context is unchanged";
+    readonly 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 declare class CompactionCommitError extends ShiitakeError {
+    readonly phase: keyof typeof commitFailures;
+    constructor(phase: keyof typeof commitFailures);
+    get diagnostic(): string;
+}
+/**
+ * Replace the context before a running work's next assistant request, or
+ * keep it (`undefined`). Run scope hands this to Mule's between-turn point.
+ */
+export type BetweenTurns = (context: readonly Message[], newMessageCount: number) => Effect.Effect<readonly Message[] | undefined, ShiitakeError>;
+export type SessionCompactionInput = Readonly<{
+    store: SqliteOwner;
+    sessionId: string;
+    workId: string;
+    model: Model<Api>;
+    stream?: MuleStreamFunction | undefined;
+    handoff?: CompactionHandoffV0 | undefined;
+    /** This model's resolved budgets and the global automatic switch. */
+    settings: CompactionSettings;
+    path: readonly StoredSessionRow[];
+    messages: readonly Message[];
+    /** Finish the durable assistant/tool boundary before compacting it. */
+    resuming?: boolean;
+    run: (messages: readonly Message[], betweenTurns: BetweenTurns) => Effect.Effect<MuleRunOutcome, ShiitakeError>;
+}>;
+/**
+ * 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 declare function estimateThresholdContextTokens(path: readonly StoredSessionRow[], messages: readonly Message[]): number;
+/** Compose the retained pre-run, between-turn and post-run compaction phases. */
+export declare function runWithCompaction(input: SessionCompactionInput): Effect.Effect<MuleRunOutcome, ShiitakeError>;
+/** What a manual compaction did; a failure is the Effect's error. */
+export type ManualCompactionOutcome = "compacted" | "nothing_to_compact";
+/**
+ * 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 declare function compactSession(input: Pick<SessionCompactionInput, "store" | "sessionId" | "workId" | "model" | "stream" | "handoff" | "settings" | "path"> & Readonly<{
+    instructions?: string | undefined;
+}>): Effect.Effect<ManualCompactionOutcome, ShiitakeError>;
+export {};