@womp/spark-agent 6.2.0 → 6.4.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ Notable changes to `@womp/spark-agent`, newest first. Versions follow
 [Semantic Versioning](https://semver.org/). Add an entry with each version bump; describe what
 changed for hosts and users, and how to migrate across breaking changes.
 
+## 6.4.0 — 2026-10-12
+
+### Added
+
+- Conversation compaction. Once a conversation reaches 256k tokens (by the provider's count for its
+  last step, or an estimate), the run's own model summarizes everything before the most recent
+  16k tokens of whole turns, before the turn's first step. Later requests send the summary, the
+  current text of the skills read in the summarized messages, and the newest four images the user
+  attached to them (`COMPACTION_USER_IMAGES`), in their place. The summary is
+  recorded as a `data-compaction` part (`SparkCompaction`) on the turn's assistant message, so
+  hosts store it with the message; the chat still has every message. A summary that fails leaves
+  the turn uncompacted, and context trimming still applies.
+- `SparkAgentOptions.history`: the stored conversation, converted and compacted by the run. Pass it
+  instead of `messages` to get compaction; `createSparkRunExecutor` now does.
+- `convertSparkMessages` takes `{ compaction, skills }` and applies the latest compaction in the
+  messages it is given.
+- `SparkAgentOptions.compaction` and `SparkRunExecutorOptions.compaction` (`SparkCompactionLimits`)
+  lower the threshold and the recent tail kept, for a host that exercises compaction without a
+  production-sized conversation, such as local development. Absent, the defaults apply.
+
+### Changed
+
+- Goal evaluation attaches the newest `GOAL_REFERENCE_IMAGES` images the user attached to the
+  conversation, however far back, as the reference, ahead of the inspection screenshots. It reads
+  them only from `data:` URLs, so a host that stores them elsewhere passes `messages` with those
+  images inline; others are listed as unavailable.
+- When a conversation is over its context window, trimming omits the agent's older screenshots
+  before the older images the user attached.
+
+### Migration
+
+- Hosts that validate stored messages with `sparkDataPartSchemas` must take this version before any
+  host writing compactions reads the same conversations, or the new part fails validation.
+
+## 6.3.0 — 2026-10-09
+
+### Added
+
+- Goals start from the conditions in an ordinary message. `SparkAgentService.proposeGoal`,
+  `POST /conversations/:id/goal/proposal` and `SparkChatTransport.proposeGoal` return a title and
+  the message's success conditions, each marked `measurable` or left to the user's review. Hosts
+  supply `SparkAgentServiceOptions.proposeGoal`; `createSparkGoalProposer` is the shared one.
+- The goal `set` command accepts `title` and `conditions`. The service attaches them to the
+  initiating message as a `data-goal` part, the evaluator judges each measurable condition after
+  every try, and `SparkGoal.conditions` records `met` and `reason`. A goal with conditions completes
+  only when no measurable condition is unmet. `SparkChatTransport.sendMessages` forwards
+  `body.goal`, so a confirmed goal is sent with its message.
+- `SparkGoal.tries` keeps each check a goal with conditions has had: the try's number, the run that
+  made it, the evaluator's reason and every condition's result, so a host can show a goal's history.
+- The goal `update_budget` command accepts `maxTurns` as well as `creditBudget`, either or both, so
+  a goal that used its tries can be given more and resumed.
+- `GOAL_CONFIRMATION_DEFAULTS` (5 tries, 2,000 credits) and `MAX_GOAL_LENGTH` from
+  `@womp/spark-agent/ui`, for the confirmation a host shows and the objective it sends.
+- The standalone UI reads each request's conditions, asks the user to confirm them with a tries and
+  a credit cap or to try once, and shows the goal's progress. It estimates credits from model cost
+  at a development rate; it does not bill.
+
+### Changed
+
+- A goal's initiating user message can carry a `data-goal` part. Hosts that render or mirror user
+  message parts should show it as the confirmed goal or skip it. A host that gives the model its
+  own copy of the message, as Crow does from the Swan thread, must keep the part on that copy:
+  it is how the worker reads the conditions.
+
+### Removed
+
+- `parseSparkGoalCommand`. A goal starts from the confirmation, not from a typed `/goal`; hosts
+  send the `set`, `pause`, `resume` and `clear` commands from their own controls.
+
 ## 6.2.0 — 2026-10-09
 
 ### Added

package/README.md

@@ -35,8 +35,8 @@ Kakapo, Express, or React at runtime.
 
 ## Running in a host application
 
-`runSparkAgent` accepts a configured model, model messages, an executor, a capability composition,
-and an artifact resolver. It exposes exactly `read_skill` and `execute_javascript` to the model.
+`runSparkAgent` accepts a configured model, the stored conversation (`history`, compacted once it
+is long) or model messages, an executor, a capability composition, and an artifact resolver. It exposes exactly `read_skill` and `execute_javascript` to the model.
 Skills carry instructions, declarations, and JavaScript examples. Kakapo skill declarations are
 generated from its typed API at build time and packaged as JavaScript strings.
 
@@ -138,6 +138,7 @@ Closing or reloading the page only detaches the SSE subscriber. It does not canc
 POST  /agent/conversations/:conversationId/messages
 PATCH /agent/conversations/:conversationId/settings
 POST  /agent/conversations/:conversationId/goal
+POST  /agent/conversations/:conversationId/goal/proposal
 GET   /agent/runs/:runId/stream?after=0
 POST  /agent/runs/:runId/cancel
 ```
@@ -146,6 +147,15 @@ Conversation settings contain `modelId` and `reasoningEffort`; save them with
 `transport.saveConversationSettings(id, settings)`. The goal endpoint accepts `set`, `pause`,
 `resume`, `clear`, and `update_budget` commands.
 
+A goal starts from an ordinary message. `transport.proposeGoal(id, message, settings)` returns a
+title and the success conditions read from the message, each marked `measurable` or left to the
+user's review; it stores and starts nothing. After the user confirms them with a tries cap
+(`maxTurns`) and a credit cap, send the message with `body.goal` set to a `set` command carrying
+`title`, `conditions`, `maxTurns` and `creditBudget`. The service attaches the confirmed conditions
+to that message as a `data-goal` part, evaluates each measurable condition after every try, and
+records the result on `goal.conditions`. Send the message without `body.goal` to try once. Hosts
+enable proposals with `SparkAgentServiceOptions.proposeGoal`, such as `createSparkGoalProposer`.
+
 The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
 
 ```ts

package/dist/agent.d.ts

@@ -3,7 +3,8 @@ import { type SparkPersistence } from "./agent-tools.js";
 import type { SparkArtifactResolver, SparkCapabilities } from "./capabilities.js";
 import type { JavaScriptExecutor } from "./executor.js";
 import { type ContextBudgetReport } from "./context-budget.js";
-import type { SparkUIMessageChunk } from "./ui.js";
+import { type SparkCompactionLimits } from "./compaction.js";
+import type { SparkUIMessage, SparkUIMessageChunk } from "./ui.js";
 export type SparkAgentResult = {
     text: string;
     steps: number;
@@ -12,7 +13,14 @@ export type SparkAgentResult = {
     finishReason: string;
 };
 export type SparkAgentOptions = {
-    messages: ModelMessage[];
+    /** The conversation as model messages, sent as given. Pass `history` instead to have long conversations compacted. */
+    messages?: ModelMessage[];
+    /**
+     * The stored conversation. It is converted with `convertSparkMessages`, and
+     * compacted first once it is long enough (./compaction.ts); the new
+     * compaction is written to this run's message as a `data-compaction` part.
+     */
+    history?: SparkUIMessage[];
     model: LanguageModel;
     modelId: string;
     providerOptions?: Parameters<typeof streamText>[0]["providerOptions"];
@@ -30,6 +38,8 @@ export type SparkAgentOptions = {
     prepareMessages?(messages: ModelMessage[]): Promise<ModelMessage[]>;
     /** The model's context window. Absent: `contextWindowFor(modelId)`. */
     contextWindow?: number;
+    /** When `history` is compacted. Absent: the defaults in ./compaction.ts. */
+    compaction?: SparkCompactionLimits;
     /** Called when a step's messages had to be trimmed to fit, or still do not fit. */
     onContextBudget?(report: ContextBudgetReport): void;
 };

package/dist/agent.js

@@ -5,6 +5,8 @@ import { createSparkTools } from "./agent-tools.js";
 import { sparkSystemPrompt } from "./prompt.js";
 import { calculateStepCost } from "./pricing.js";
 import { contextWindowFor, fitMessagesToContext } from "./context-budget.js";
+import { compactSparkHistory } from "./compaction.js";
+import { convertSparkMessages } from "./model-history.js";
 function errorMessage(error) {
     return sparkErrorDiagnostics(error).message;
 }
@@ -37,6 +39,9 @@ export function runSparkAgent(options) {
     if (Number.isInteger(maxSteps) === false || maxSteps < 1) {
         throw new Error("maxSteps must be a positive integer.");
     }
+    if ((options.messages === undefined) === (options.history === undefined)) {
+        throw new Error("Pass either messages or history.");
+    }
     const startedAt = Date.now();
     const controller = new AbortController();
     const onAbort = () => controller.abort(options.signal?.reason);
@@ -125,10 +130,36 @@ export function runSparkAgent(options) {
                     write: (chunk) => writer.write(chunk),
                 });
                 const readSystem = () => sparkSystemPrompt(options.capabilities.skills, options.instructions);
+                let messages = options.messages ?? [];
+                if (options.history !== undefined) {
+                    const history = options.history;
+                    const compacted = await compactSparkHistory({
+                        history,
+                        convert: (compaction) => convertSparkMessages(history, tools, { compaction, skills: options.capabilities.skills }),
+                        model: options.model,
+                        modelId: options.modelId,
+                        system: readSystem(),
+                        tools,
+                        providerOptions: options.providerOptions,
+                        maxOutputTokens: options.maxOutputTokens,
+                        contextWindow,
+                        signal: controller.signal,
+                        limits: options.compaction,
+                        onCompacting: () => writer.write({
+                            type: "data-run-status",
+                            data: { runId: options.runId, status: "running", label: "Making room so we can keep talking" },
+                        }),
+                    });
+                    messages = compacted.messages;
+                    if (compacted.compaction !== undefined) {
+                        writer.write({ type: "data-compaction", id: `compaction-${options.messageId}`, data: compacted.compaction });
+                    }
+                    controller.signal.throwIfAborted();
+                }
                 const generation = streamText({
                     model: options.model,
                     system: readSystem(),
-                    messages: options.messages,
+                    messages,
                     tools,
                     toolChoice: "auto",
                     abortSignal: controller.signal,

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { ChatRequestOptions, ChatTransport, UIMessageChunk } from "ai";
 import type { SparkRunSettings } from "./server/types.js";
-import type { SparkGoal, SparkGoalCommand } from "./goals.js";
-export type { SparkGoal, SparkGoalCommand } from "./goals.js";
+import type { SparkGoal, SparkGoalCommand, SparkGoalProposal } from "./goals.js";
+export type { SparkGoal, SparkGoalCommand, SparkGoalCondition, SparkGoalProposal, SparkGoalTry } from "./goals.js";
 import type { SparkConversation, SparkConversationSummary, SparkRun } from "./server/types.js";
 import type { SparkUIMessage } from "./ui.js";
 export type { SparkConversation, SparkConversationSummary, SparkRun, SparkRunSettings, } from "./server/types.js";
@@ -44,6 +44,8 @@ export declare class SparkChatTransport implements ChatTransport<SparkUIMessage>
         goal?: SparkGoal;
         run?: SparkRun;
     }>;
+    /** The success conditions read from a message, to confirm before sending it as a goal. */
+    proposeGoal(id: string, message: SparkUIMessage, settings: SparkRunSettings, signal?: AbortSignal): Promise<SparkGoalProposal>;
     getGoal(id: string): Promise<SparkGoal | undefined>;
     getRun(id: string): Promise<SparkRun>;
     saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;

package/dist/client.js

@@ -51,7 +51,8 @@ export class SparkChatTransport {
             : options.messages.find(({ id }) => id === options.messageId) ?? options.messages.at(-1);
         if (message === undefined)
             throw new Error("Spark Agent requires a message to send.");
-        const settings = this.settingsFrom(options.body);
+        const requestBody = options.body;
+        const settings = this.settingsFrom(requestBody);
         const response = await this.request(`/conversations/${encodeURIComponent(options.chatId)}/messages`, {
             method: "POST",
             body: JSON.stringify({
@@ -59,6 +60,8 @@ export class SparkChatTransport {
                 message,
                 messageId: options.messageId,
                 settings,
+                // A confirmed goal: the message starts it, and the run is its first try.
+                ...(requestBody?.goal === undefined ? {} : { goal: requestBody.goal }),
             }),
             signal: options.abortSignal,
         }, options.headers);
@@ -126,6 +129,15 @@ export class SparkChatTransport {
             throw await responseError(response);
         return response.json();
     }
+    /** The success conditions read from a message, to confirm before sending it as a goal. */
+    async proposeGoal(id, message, settings, signal) {
+        const response = await this.request(`/conversations/${encodeURIComponent(id)}/goal/proposal`, {
+            method: "POST", body: JSON.stringify({ message, settings }), signal,
+        });
+        if (!response.ok)
+            throw await responseError(response);
+        return (await response.json()).proposal;
+    }
     async getGoal(id) {
         const response = await this.request(`/conversations/${encodeURIComponent(id)}/goal`, { method: "GET" });
         if (!response.ok)

package/dist/compaction.d.ts

@@ -0,0 +1,64 @@
+import { generateText, type LanguageModel, type ModelMessage, type ToolSet } from "ai";
+import type { SparkSkill } from "./capabilities.js";
+import { type SparkCompaction, type SparkUIMessage } from "./ui.js";
+/** Compact once the conversation reaches this many tokens. */
+export declare const COMPACTION_THRESHOLD_TOKENS = 256000;
+/** Recent whole turns kept verbatim, up to this many tokens, besides the current turn. */
+export declare const COMPACTION_KEEP_RECENT_TOKENS = 16000;
+/** The user's newest images from the summarized messages that the summary message carries. */
+export declare const COMPACTION_USER_IMAGES = 4;
+/**
+ * When a conversation is compacted, for a host that exercises compaction
+ * without filling a production-sized conversation, such as local development.
+ */
+export type SparkCompactionLimits = {
+    /** Default COMPACTION_THRESHOLD_TOKENS. */
+    thresholdTokens?: number;
+    /** Default COMPACTION_KEEP_RECENT_TOKENS. */
+    keepRecentTokens?: number;
+};
+export declare const COMPACTION_PROMPT = "Write a checkpoint summary of this conversation so far. It replaces the earlier messages in your context, so the work must be able to continue from it alone. Reply with the summary only, without calling tools. This request is not part of the conversation: leave it out of the summary.\nIf the conversation begins with an earlier summary, carry its content forward and update it.\nUse these sections:\n## Goal\n## User preferences and constraints\n## Decisions and current scene state (objects with their names and IDs)\n## Done\n## Open and next steps\n## Artifacts and images (each artifact ID, and what each image the user attached shows)\n## Errors and approaches to avoid\nKeep exact names, IDs, numbers and the user's own wording for requirements. Stay under 1,500 words.";
+export declare const COMPACTION_NOTE = "[Earlier messages in this conversation were replaced by the summary below. The scene itself is unchanged; inspect it for its exact state.]";
+/** The latest compaction in the conversation whose kept message is still in it. */
+export declare function latestCompaction(history: SparkUIMessage[]): {
+    compaction: SparkCompaction;
+    carrier: number;
+    firstKept: number;
+} | undefined;
+/**
+ * The conversation as the model reads it: the messages before the compaction's
+ * kept message replaced by its summary, with the newest COMPACTION_USER_IMAGES
+ * images the user attached to them. `compaction` defaults to the latest one in `history`; `skills` are the
+ * host's, to send the current text of the skills it names. Without a
+ * compaction, `history` is returned as it is.
+ */
+export declare function applyCompaction(history: SparkUIMessage[], options?: {
+    compaction?: SparkCompaction;
+    skills?: readonly SparkSkill[];
+}): SparkUIMessage[];
+export type CompactSparkHistoryOptions = {
+    history: SparkUIMessage[];
+    /** `history` as model messages, with `compaction` applied when given. */
+    convert(compaction?: SparkCompaction): Promise<ModelMessage[]>;
+    model: LanguageModel;
+    modelId: string;
+    system: string;
+    /** The run's tools; the summary request sends their definitions without `execute`. */
+    tools: ToolSet;
+    providerOptions?: Parameters<typeof generateText>[0]["providerOptions"];
+    maxOutputTokens?: number;
+    contextWindow?: number;
+    signal?: AbortSignal;
+    /** Called just before the summary request, which can take a while. */
+    onCompacting?(): void;
+    limits?: SparkCompactionLimits;
+};
+/**
+ * The turn's model messages, compacted first when the conversation has reached
+ * the threshold. `compaction` is the new one, for the host to record; it is
+ * absent when nothing was compacted, including when the summary failed.
+ */
+export declare function compactSparkHistory(options: CompactSparkHistoryOptions): Promise<{
+    messages: ModelMessage[];
+    compaction?: SparkCompaction;
+}>;

package/dist/compaction.js

@@ -0,0 +1,296 @@
+// Replace a long conversation's earlier messages with a summary.
+//
+// WHEN. Once per turn, before its first step: when the conversation reaches
+// COMPACTION_THRESHOLD_TOKENS, everything before the most recent
+// COMPACTION_KEEP_RECENT_TOKENS of whole turns is summarized by the run's own
+// model. Every later request sends the summary in their place. Below the
+// threshold nothing happens, and a summary that fails leaves the turn as it was:
+// ./context-budget.ts still keeps every request inside the model's window.
+//
+// WHERE IT IS KEPT. The summary is a `data-compaction` part on the assistant
+// message of the turn that wrote it (SparkCompaction, ./ui.ts), so every host
+// stores and reloads it with the message, and the chat still shows every
+// message it replaces. `applyCompaction`, called by `convertSparkMessages`,
+// sends the latest one in place of the messages before `firstKeptMessageId`.
+// A later compaction is written from the conversation as the model then sees
+// it -- the earlier summary first -- so the summary is updated, not restarted.
+//
+// THE CACHE. The summary request is the previous request's prefix -- the same
+// system prompt, tool definitions and messages -- plus one instruction, so the
+// provider's prompt cache serves almost all of it. Tool definitions are sent
+// without `execute`: a call the model makes anyway is never run, and fails the
+// summary instead.
+//
+// SKILLS. A skill read in the summarized messages would otherwise be lost with
+// them. The compaction names them, and its summary message carries their
+// current text, ahead of the summary, so the model does not have to read them again.
+//
+// IMAGES. The images the user attached to the summarized messages are what the
+// work is often built from, so the summary message carries the newest
+// COMPACTION_USER_IMAGES of them too, as the same file parts; the summary
+// describes the rest. They are still on the stored messages: nothing records them.
+import { generateText } from "ai";
+import { CHARS_PER_TOKEN, IMAGE_TOKENS, estimateRequestTokens, fitMessagesToContext, } from "./context-budget.js";
+import { sparkDataPartSchemas } from "./ui.js";
+import { userImages } from "./user-images.js";
+/** Compact once the conversation reaches this many tokens. */
+export const COMPACTION_THRESHOLD_TOKENS = 256_000;
+/** Recent whole turns kept verbatim, up to this many tokens, besides the current turn. */
+export const COMPACTION_KEEP_RECENT_TOKENS = 16_000;
+/** The user's newest images from the summarized messages that the summary message carries. */
+export const COMPACTION_USER_IMAGES = 4;
+export const COMPACTION_PROMPT = `Write a checkpoint summary of this conversation so far. It replaces the earlier messages in your context, so the work must be able to continue from it alone. Reply with the summary only, without calling tools. This request is not part of the conversation: leave it out of the summary.
+If the conversation begins with an earlier summary, carry its content forward and update it.
+Use these sections:
+## Goal
+## User preferences and constraints
+## Decisions and current scene state (objects with their names and IDs)
+## Done
+## Open and next steps
+## Artifacts and images (each artifact ID, and what each image the user attached shows)
+## Errors and approaches to avoid
+Keep exact names, IDs, numbers and the user's own wording for requirements. Stay under 1,500 words.`;
+export const COMPACTION_NOTE = "[Earlier messages in this conversation were replaced by the summary below. The scene itself is unchanged; inspect it for its exact state.]";
+/** The latest compaction in the conversation whose kept message is still in it. */
+export function latestCompaction(history) {
+    for (let carrier = history.length - 1; carrier >= 0; carrier -= 1) {
+        const message = history[carrier];
+        if (message?.role !== "assistant")
+            continue;
+        for (let i = message.parts.length - 1; i >= 0; i -= 1) {
+            const part = message.parts[i];
+            if (part?.type !== "data-compaction")
+                continue;
+            const parsed = sparkDataPartSchemas.compaction.safeParse(part.data);
+            if (!parsed.success)
+                continue;
+            const firstKept = history.findIndex(({ id }) => id === parsed.data.firstKeptMessageId);
+            if (firstKept >= 0)
+                return { compaction: parsed.data, carrier, firstKept };
+        }
+    }
+    return undefined;
+}
+/**
+ * The conversation as the model reads it: the messages before the compaction's
+ * kept message replaced by its summary, with the newest COMPACTION_USER_IMAGES
+ * images the user attached to them. `compaction` defaults to the latest one in `history`; `skills` are the
+ * host's, to send the current text of the skills it names. Without a
+ * compaction, `history` is returned as it is.
+ */
+export function applyCompaction(history, options = {}) {
+    const compaction = options.compaction ?? latestCompaction(history)?.compaction;
+    if (compaction === undefined)
+        return history;
+    const firstKept = history.findIndex(({ id }) => id === compaction.firstKeptMessageId);
+    if (firstKept < 0)
+        return history;
+    // The skills go before the summary, in a part of their own: they change less
+    // often, so the next compaction leaves them in the cached prefix.
+    const skills = skillsText(compaction.skills, options.skills);
+    const parts = [{ type: "text", text: COMPACTION_NOTE }];
+    if (skills !== undefined)
+        parts.push({ type: "text", text: skills });
+    const shown = new Set(userImages(history.slice(firstKept)).map(({ url }) => url));
+    const images = userImages(history.slice(0, firstKept))
+        .filter(({ url }) => !shown.has(url))
+        .slice(-COMPACTION_USER_IMAGES);
+    if (images.length > 0) {
+        parts.push({ type: "text", text: "The newest images the user attached to the messages the summary replaces, in the order sent:" }, ...images);
+    }
+    parts.push({ type: "text", text: `<conversation-summary>\n${compaction.summary}\n</conversation-summary>` });
+    return [{ id: `compaction-${compaction.firstKeptMessageId}`, role: "user", parts }, ...history.slice(firstKept)];
+}
+function skillsText(names, available) {
+    if (names.length === 0)
+        return undefined;
+    if (available === undefined) {
+        return `Skills read earlier in this conversation (read them again before using their APIs): ${names.join(", ")}`;
+    }
+    const skills = names.flatMap((name) => available.filter((skill) => skill.name === name));
+    if (skills.length === 0)
+        return undefined;
+    return [
+        "Skills already read in this conversation, as read_skill returns them now; they need no reading again:",
+        ...skills.map((skill) => `<skill name="${skill.name}" version="${skill.version}">\n${skill.instructions}\n\n${skill.declarations}${skill.examples.length > 0 ? `\n\nExamples:\n${skill.examples.join("\n\n")}` : ""}\n</skill>`),
+    ].join("\n\n");
+}
+/**
+ * The turn's model messages, compacted first when the conversation has reached
+ * the threshold. `compaction` is the new one, for the host to record; it is
+ * absent when nothing was compacted, including when the summary failed.
+ */
+export async function compactSparkHistory(options) {
+    const { history } = options;
+    const messages = await options.convert();
+    const threshold = Math.min(options.limits?.thresholdTokens ?? COMPACTION_THRESHOLD_TOKENS, options.contextWindow === undefined ? Infinity : options.contextWindow - (options.maxOutputTokens ?? 0));
+    const previous = latestCompaction(history);
+    const size = conversationTokens(history, previous?.carrier ?? -1) ?? estimate(messages, options);
+    if (size < threshold)
+        return { messages };
+    const firstKept = cutIndex(history, previous?.firstKept ?? 0, options.limits?.keepRecentTokens ?? COMPACTION_KEEP_RECENT_TOKENS);
+    if (firstKept === undefined)
+        return { messages };
+    // The request ends before the current user message: the previous request's
+    // prefix, which the provider has cached.
+    const current = lastIndex(messages, ({ role }) => role === "user");
+    if (current <= 0)
+        return { messages };
+    options.onCompacting?.();
+    let summary;
+    try {
+        summary = await summarize(messages.slice(0, current), options);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+    }
+    options.signal?.throwIfAborted();
+    if (summary === undefined)
+        return { messages };
+    const kept = readSkills(history.slice(firstKept));
+    const skills = [
+        ...new Set([...(previous?.compaction.skills ?? []), ...readSkills(history.slice(previous?.firstKept ?? 0, firstKept))]),
+    ].filter((name) => !kept.has(name));
+    const compaction = {
+        firstKeptMessageId: history[firstKept].id,
+        summary,
+        skills,
+        modelId: options.modelId,
+        tokensBefore: estimate(messages, options),
+        tokensAfter: 0,
+        createdAt: new Date().toISOString(),
+    };
+    const compacted = await options.convert(compaction);
+    compaction.tokensAfter = estimate(compacted, options);
+    return { messages: compacted, compaction };
+}
+async function summarize(messages, options) {
+    const definitions = Object.fromEntries(Object.entries(options.tools).map(([name, tool]) => {
+        const { execute: _execute, onInputStart: _start, onInputDelta: _delta, onInputAvailable: _available, ...definition } = tool;
+        return [name, definition];
+    }));
+    const fitted = fitMessagesToContext(messages, {
+        contextWindow: options.contextWindow,
+        maxOutputTokens: options.maxOutputTokens,
+        system: options.system,
+        tools: definitions,
+    }).messages;
+    const result = await generateText({
+        model: options.model,
+        system: options.system,
+        tools: definitions,
+        toolChoice: "auto",
+        messages: [...fitted, { role: "user", content: [{ type: "text", text: COMPACTION_PROMPT }] }],
+        providerOptions: options.providerOptions,
+        maxOutputTokens: options.maxOutputTokens,
+        abortSignal: options.signal,
+    });
+    const text = result.text.trim();
+    return result.finishReason === "stop" && result.toolCalls.length === 0 && text.length > 0 ? text : undefined;
+}
+function estimate(messages, options) {
+    return estimateRequestTokens(messages, { system: options.system, tools: options.tools });
+}
+/**
+ * The conversation's size from the provider's count for its last step, plus an
+ * estimate of what came after it. Undefined when there is no count to go by:
+ * the request is then estimated whole, which errs high.
+ */
+function conversationTokens(history, carrier) {
+    const step = lastStepTokens(history, carrier);
+    if (step === undefined)
+        return undefined;
+    return step.tokens + sum(history.slice(step.index + 1).map(uiMessageTokens));
+}
+/**
+ * Input and output tokens of the conversation's last recorded step, when that
+ * step was sent after the latest compaction -- otherwise it measured messages
+ * the model no longer reads.
+ */
+function lastStepTokens(history, carrier) {
+    for (let index = history.length - 1; index > carrier; index -= 1) {
+        const message = history[index];
+        if (message?.role !== "assistant")
+            continue;
+        for (let i = message.parts.length - 1; i >= 0; i -= 1) {
+            const part = message.parts[i];
+            if (part?.type !== "data-step-metrics")
+                continue;
+            const usage = part.data.usage;
+            if (typeof usage?.inputTokens !== "number")
+                continue;
+            return { index, tokens: usage.inputTokens + (typeof usage.outputTokens === "number" ? usage.outputTokens : 0) };
+        }
+    }
+    return undefined;
+}
+/**
+ * The first message to keep: the earliest user message after `floor` such that
+ * it and everything up to the current user message fit `keepRecent` tokens.
+ * The current user message when no earlier turn fits. Undefined when nothing
+ * after `floor` would be summarized.
+ */
+function cutIndex(history, floor, keepRecent) {
+    const current = lastIndex(history, ({ role }) => role === "user");
+    if (current <= floor)
+        return undefined;
+    let cut = current;
+    let tokens = 0;
+    for (let i = current - 1; i > floor; i -= 1) {
+        tokens += uiMessageTokens(history[i]);
+        if (tokens > keepRecent)
+            break;
+        if (history[i].role === "user")
+            cut = i;
+    }
+    return cut;
+}
+/** Skills read successfully in these messages, in the order first read. */
+function readSkills(messages) {
+    const names = new Set();
+    for (const message of messages) {
+        if (message.role !== "assistant")
+            continue;
+        for (const part of message.parts) {
+            const isReadSkill = part.type === "tool-read_skill" || (part.type === "dynamic-tool" && part.toolName === "read_skill");
+            if (!isReadSkill || part.state !== "output-available")
+                continue;
+            const skills = part.output?.skills;
+            if (!Array.isArray(skills))
+                continue;
+            for (const skill of skills) {
+                if (skill?.ok === true && typeof skill.name === "string")
+                    names.add(skill.name);
+            }
+        }
+    }
+    return names;
+}
+/** A stored message's size, roughly: its JSON, with images at their model cost and data URLs left out. */
+function uiMessageTokens(message) {
+    let images = 0;
+    const json = JSON.stringify(message.parts, (key, value) => {
+        if (typeof value === "string" && key === "url" && value.startsWith("data:"))
+            return "";
+        if (typeof value === "object" && value !== null) {
+            const item = value;
+            if (item.type === "file" && typeof item.mediaType === "string" && item.mediaType.startsWith("image/"))
+                images += 1;
+            if (item.kind === "image" && item.inspect !== false)
+                images += 1;
+        }
+        return value;
+    });
+    return Math.ceil((json?.length ?? 0) / CHARS_PER_TOKEN) + images * IMAGE_TOKENS;
+}
+function sum(values) {
+    return values.reduce((total, value) => total + value, 0);
+}
+function lastIndex(items, test) {
+    for (let i = items.length - 1; i >= 0; i -= 1) {
+        if (test(items[i]))
+            return i;
+    }
+    return -1;
+}

package/dist/context-budget.d.ts

@@ -61,3 +61,5 @@ export type ContextBudgetResult = {
 export declare function fitMessagesToContext(messages: ModelMessage[], options: ContextBudgetOptions): ContextBudgetResult;
 /** The estimate for a list of messages, as `fitMessagesToContext` counts them. */
 export declare function estimateMessagesTokens(messages: ModelMessage[]): number;
+/** The estimate for a whole request: its messages, system prompt and tool definitions. */
+export declare function estimateRequestTokens(messages: ModelMessage[], options: Pick<ContextBudgetOptions, "system" | "tools">): number;