clanka 0.3.1 → 0.4.0

package/dist/Compaction.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Context compaction for the shared Agent loop.
+ *
+ * Two independent mechanisms live here:
+ *
+ * 1. An always-on cap on `execute` results before they enter the Prompt
+ *    (`capOutput`). It runs on every surface and is not affected by the
+ *    compaction kill switch.
+ * 2. Auto-compaction of the live Prompt (`compactIfNeeded` before a model
+ *    call, `compactAfterOverflow` after a context-length error). Both rewrite
+ *    the Prompt to `system + <compaction-summary> user message + kept tail`.
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as AiError from "effect/unstable/ai/AiError";
+import * as LanguageModel from "effect/unstable/ai/LanguageModel";
+import * as Prompt from "effect/unstable/ai/Prompt";
+import type * as AgentOutput from "./AgentOutput.ts";
+/**
+ * Runtime configuration for auto-compaction.
+ *
+ * - `enabled`: kill switch for both compact paths. Does **not** disable the
+ *   `execute` output cap.
+ * - `contextWindow`: assumed model context window in tokens.
+ * - `reserveTokens`: headroom kept free below `contextWindow`. Compaction
+ *   triggers once the last reported `contextTokens` (or the estimate) exceeds
+ *   `contextWindow - reserveTokens`.
+ * - `keepRecentTokens`: size of the recent tail preserved verbatim after a
+ *   compaction.
+ *
+ * @since 1.0.0
+ * @category Configuration
+ */
+export interface CompactionConfigService {
+    readonly enabled: boolean;
+    readonly contextWindow: number;
+    readonly reserveTokens: number;
+    readonly keepRecentTokens: number;
+}
+/**
+ * @since 1.0.0
+ * @category Configuration
+ */
+export declare const defaultConfig: CompactionConfigService;
+declare const CompactionConfig_base: Context.Reference<CompactionConfigService>;
+/**
+ * @since 1.0.0
+ * @category Configuration
+ */
+export declare class CompactionConfig extends CompactionConfig_base {
+    static readonly layer: (options: Partial<CompactionConfigService>) => Layer.Layer<never>;
+}
+declare const SummarizerTransform_base: Context.Reference<<A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>>;
+/**
+ * Wraps the summarizer model call so a provider can apply request overrides
+ * (e.g. Copilot's `max_output_tokens`). Defaults to the identity.
+ *
+ * @since 1.0.0
+ * @category Configuration
+ */
+export declare class SummarizerTransform extends SummarizerTransform_base {
+}
+/**
+ * Hard cap, in characters, applied to every `execute` success string before it
+ * is appended to the Prompt. Always on.
+ *
+ * @since 1.0.0
+ * @category Constants
+ */
+export declare const executeOutputCapChars = 32000;
+/**
+ * Cap applied to `execute` results that remain in the kept tail when the tail
+ * itself still exceeds `keepRecentTokens` after reasoning has been dropped.
+ *
+ * @since 1.0.0
+ * @category Constants
+ */
+export declare const keptToolResultStubChars = 2000;
+/**
+ * Maximum output tokens requested by providers that support a summary cap.
+ * Copilot uses this limit; Codex rejects max_output_tokens and has no
+ * configured summary output-token cap.
+ *
+ * @since 1.0.0
+ * @category Constants
+ */
+export declare const summarizerMaxOutputTokens = 4000;
+/**
+ * The synthetic summary user message is wrapped in these tags so a later
+ * compaction can locate it without a new Prompt schema.
+ *
+ * @since 1.0.0
+ * @category Constants
+ */
+export declare const summaryOpenTag = "<compaction-summary>";
+/**
+ * @since 1.0.0
+ * @category Constants
+ */
+export declare const summaryCloseTag = "</compaction-summary>";
+/**
+ * System prompt included in the summarizer's Prompt.
+ *
+ * @since 1.0.0
+ * @category Constants
+ */
+export declare const summarizerSystem = "You compact the conversation history of a coding agent so the agent can continue with less context.\nReply with the summary only. No preamble, no commentary, no markdown fences.";
+/**
+ * @since 1.0.0
+ * @category Cap
+ */
+export interface CapResult {
+    /**
+     * The (possibly capped) output. When capped this is `head + marker + tail`,
+     * where the marker tells the model how many characters were removed and
+     * to narrow the read (`readFile` `startLine`/`endLine`, smaller logs).
+     */
+    readonly output: string;
+    readonly capped: boolean;
+    readonly charsBefore: number;
+    readonly charsAfter: number;
+}
+/**
+ * Cap a string to `maxChars` characters, keeping the head and the tail and
+ * inserting a marker in between. Inputs at or under the cap are returned
+ * unchanged.
+ *
+ * @since 1.0.0
+ * @category Cap
+ */
+export declare const capOutput: (output: string, maxChars?: number) => CapResult;
+/**
+ * Cheap token estimate for a Prompt: JSON length / 4. Used when no
+ * `contextTokens` usage has been observed yet (first turn, ACP session load)
+ * and for sizing the kept tail.
+ *
+ * @since 1.0.0
+ * @category Tokens
+ */
+export declare const estimateTokens: (prompt: Prompt.Prompt) => number;
+/**
+ * Token estimate for a single message. Same measure as `estimateTokens`.
+ *
+ * @since 1.0.0
+ * @category Tokens
+ */
+export declare const estimateMessageTokens: (message: Prompt.Message) => number;
+/**
+ * Whether the threshold trigger fires for the next model call.
+ *
+ * `contextTokens` is the `inputTokens.total` from the most recent `finish`
+ * part, or `undefined` when no usage has been observed yet, in which case
+ * `estimateTokens(prompt)` is used instead.
+ *
+ * Always `false` when `config.enabled` is `false`.
+ *
+ * @since 1.0.0
+ * @category Tokens
+ */
+export declare const shouldCompact: (options: {
+    readonly prompt: Prompt.Prompt;
+    readonly contextTokens: number | undefined;
+    readonly config: CompactionConfigService;
+}) => boolean;
+/**
+ * Whether an `AiError` is a context-length overflow from a known provider
+ * (Codex / Copilot), as opposed to any other request or transport failure.
+ *
+ * Any request, unknown or provider error counts when it carries a 413 status,
+ * a `context_length_exceeded` code, or a context-length description. These
+ * errors are never retried as-is; the Agent compacts first.
+ *
+ * @since 1.0.0
+ * @category Overflow
+ */
+export declare const isContextLengthError: (error: AiError.AiError) => boolean;
+/**
+ * The result of choosing a cut point in a Prompt.
+ *
+ * - `system`: the system message, passed through unchanged.
+ * - `previousSummary`: the text inside an existing `<compaction-summary>`
+ *   message, if the prompt was compacted before. That message is excluded from
+ *   `toSummarize`.
+ * - `toSummarize`: the messages older than the cut point.
+ * - `kept`: the messages at and after the cut point, preserved verbatim
+ *   (subject to `trimKept`).
+ *
+ * @since 1.0.0
+ * @category Cut points
+ */
+export interface Split {
+    readonly system: Option.Option<Prompt.SystemMessage>;
+    readonly previousSummary: Option.Option<string>;
+    readonly toSummarize: ReadonlyArray<Prompt.Message>;
+    readonly kept: ReadonlyArray<Prompt.Message>;
+}
+/**
+ * Whether a message is the synthetic `<compaction-summary>` user message
+ * produced by `rewrite`. Surfaces that replay history (ACP) skip it.
+ *
+ * @since 1.0.0
+ * @category Cut points
+ */
+export declare const isSummaryMessage: (message: Prompt.Message) => boolean;
+/**
+ * Choose the cut point for a compaction.
+ *
+ * Walks back from the newest message, accumulating `estimateMessageTokens`,
+ * and stops at the first message boundary where the accumulated tail would
+ * exceed `keepRecentTokens`. The cut is then adjusted so that an `execute`
+ * tool-call (assistant message) and its tool-result (tool message) are never
+ * separated: if the boundary falls between them the assistant message is kept
+ * as well. The kept tail always contains at least the newest complete unit.
+ *
+ * Returns `None` when there is nothing to summarize, which happens when the
+ * kept tail is the whole prompt (ignoring the system message and a previous
+ * summary message). Callers treat `None` as a no-op.
+ *
+ * @since 1.0.0
+ * @category Cut points
+ */
+export declare const split: (prompt: Prompt.Prompt, keepRecentTokens: number) => Option.Option<Split>;
+/**
+ * Find the text of a previous compaction summary in a Prompt, if present.
+ *
+ * @since 1.0.0
+ * @category Cut points
+ */
+export declare const findPreviousSummary: (prompt: Prompt.Prompt) => Option.Option<string>;
+/**
+ * Shrink a kept tail that still exceeds `keepRecentTokens`:
+ *
+ * 1. Drop `reasoning` parts from assistant messages, oldest first, until the
+ *    tail fits.
+ * 2. If it still does not fit, stub `execute` tool-result strings in place,
+ *    oldest first, using `capOutput(result, keptToolResultStubChars)`.
+ *
+ * Message order, message count and tool-call / tool-result ids are never
+ * changed, so call/result pairing stays valid. Returns the input unchanged
+ * when it already fits.
+ *
+ * @since 1.0.0
+ * @category Cut points
+ */
+export declare const trimKept: (kept: ReadonlyArray<Prompt.Message>, keepRecentTokens: number) => ReadonlyArray<Prompt.Message>;
+/**
+ * Build the Prompt sent to the summarizer model call.
+ *
+ * The conversation is rendered as text using the OpenCode-style summary
+ * template. `reasoning` parts are omitted, `execute` tool results are capped
+ * to `summarizerToolResultCapChars`, and `previousSummary` is folded in so the
+ * new summary supersedes it. No tools, no system prompt from the agent.
+ *
+ * @since 1.0.0
+ * @category Rewrite
+ */
+export declare const summarizerPrompt: (options: {
+    readonly previousSummary: Option.Option<string>;
+    readonly messages: ReadonlyArray<Prompt.Message>;
+}) => Prompt.Prompt;
+/**
+ * Wrap a summary in the `<compaction-summary>` tags used for the synthetic
+ * user message.
+ *
+ * @since 1.0.0
+ * @category Rewrite
+ */
+export declare const wrapSummary: (summary: string) => string;
+/**
+ * Assemble the compacted Prompt: `[system?, user(wrapSummary(summary)),
+ * ...kept]`. The system message is passed through untouched.
+ *
+ * @since 1.0.0
+ * @category Rewrite
+ */
+export declare const rewrite: (options: {
+    readonly system: Option.Option<Prompt.SystemMessage>;
+    readonly summary: string;
+    readonly kept: ReadonlyArray<Prompt.Message>;
+}) => Prompt.Prompt;
+/**
+ * @since 1.0.0
+ * @category Compaction
+ */
+export type CompactionReason = typeof AgentOutput.CompactionReason.Type;
+/**
+ * @since 1.0.0
+ * @category Compaction
+ */
+export interface CompactionResult {
+    readonly reason: CompactionReason;
+    readonly prompt: Prompt.Prompt;
+    /**
+     * `estimateTokens` of the prompt before and after the rewrite.
+     */
+    readonly tokensBefore: number;
+    readonly tokensAfter: number;
+}
+/**
+ * Run one compaction of `prompt`.
+ *
+ * Returns `None` without calling the model when compaction is disabled or
+ * when `split` finds nothing to summarize. Otherwise `onStart` runs, the
+ * summarizer is called with `streamText` (the Codex backend rejects
+ * non-streaming requests) through `SummarizerTransform`, and the prompt is
+ * rewritten to `system + summary + trimKept(kept)`.
+ *
+ * Fails with the summarizer's `AiError`. Callers decide whether that is fatal.
+ *
+ * @since 1.0.0
+ * @category Compaction
+ */
+export declare const compact: (options: {
+    readonly prompt: Prompt.Prompt;
+    readonly reason: CompactionReason;
+    /**
+     * Runs once a cut point was found, before the summarizer call. Not invoked
+     * for no-op compactions.
+     */
+    readonly onStart?: ((reason: CompactionReason) => Effect.Effect<void>) | undefined;
+}) => Effect.Effect<Option.Option<CompactionResult>, AiError.AiError, LanguageModel.LanguageModel>;
+/**
+ * Compact before the next model call when `shouldCompact` fires.
+ *
+ * Returns `None` when compaction is disabled, not needed, or a no-op. A
+ * failing summarizer is swallowed here: the caller proceeds with the
+ * uncompacted prompt and relies on the overflow path.
+ *
+ * @since 1.0.0
+ * @category Compaction
+ */
+export declare const compactIfNeeded: (options: {
+    readonly prompt: Prompt.Prompt;
+    readonly contextTokens: number | undefined;
+    readonly onStart?: ((reason: CompactionReason) => Effect.Effect<void>) | undefined;
+}) => Effect.Effect<Option.Option<CompactionResult>, never, LanguageModel.LanguageModel>;
+export {};
+//# sourceMappingURL=Compaction.d.ts.map

package/dist/Compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Compaction.d.ts","sourceRoot":"","sources":["../src/Compaction.ts"],"names":[],"mappings":"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"}