@womp/spark-agent 6.5.0 → 7.0.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.
 
+## 7.0.0 — 2026-10-12
+
+Compaction is now the only thing that takes messages out of what the model reads, and it can run
+before any step of a turn, not just the first. The per-step trimming that replaced earlier images,
+tool results and whole turns with placeholder text is gone: it rewrote the start of the prompt
+whenever it fired, which threw away the provider's prompt cache on every later step. A request
+that is still over the model's context window after compaction is sent as it is and fails with
+the provider's error.
+
+### Changed
+
+- A run given `history` checks the conversation before every step. Once it reaches the compaction
+  threshold during a turn, everything before the current user message and the turn's steps before
+  its most recent `COMPACTION_KEEP_RECENT_TOKENS` are summarized; the user's message is kept
+  verbatim. The summary request is the first kept step's request plus one instruction, so it is
+  served from the prompt cache. A compaction that would save less than
+  `COMPACTION_MIN_SAVED_RATIO` of the threshold is skipped, so a turn whose own message is over
+  the threshold does not summarize on every step.
+- A summary covers only the messages it replaces, before a turn as well as during one. It used to
+  tell of the kept messages too, and the model, reading them again after it, took that work for
+  done twice.
+- `SparkCompaction.firstKeptStep` records a compaction written during its turn: the first step of
+  the recording assistant message the model still reads. `applyCompaction` (and so
+  `convertSparkMessages`) leaves the earlier steps out, so the next turn rebuilds exactly the
+  messages the last step was sent. A run may now record more than one `data-compaction` part; the
+  latest is the one in force. Hosts must store and reload message parts in order, including
+  `step-start`.
+- When to compact is measured from the provider's count for the conversation's last step after the
+  latest compaction, including the steps of the message that recorded it.
+
+### Added
+
+- `applyCompaction` and `latestCompaction` are exported from the package root, so a host can tell
+  which stored messages, and which of their images, the model will be sent.
+
+### Removed
+
+- `fitMessagesToContext`, `ContextBudgetOptions`, `ContextBudgetReport`, `ContextBudgetResult`,
+  `TRIM_TRIGGER_RATIO`, `TRIM_TARGET_RATIO`, `SMALL_TOOL_OUTPUT_TOKENS`,
+  `PROTECTED_CURRENT_STEPS` and the `OMITTED_HISTORY_TEXT`, `OMITTED_HISTORY_IMAGE_TEXT` and
+  `OMITTED_TOOL_OUTPUT_TEXT` notes.
+- `SparkAgentOptions.onContextBudget`.
+
+### Migration
+
+- Remove any `onContextBudget` handler and any host-side trimming. Pass `history` to have long
+  conversations compacted; a run given `messages` is sent exactly what it is given.
+- `contextWindowFor`, `estimateMessagesTokens`, `estimateRequestTokens`, `CHARS_PER_TOKEN` and
+  `IMAGE_TOKENS` are unchanged; they now live in `src/context-window.ts`.
+
 ## 6.5.0 — 2026-10-12
 
 The agent proposes a goal during its turn, instead of the host asking a separate model call to

package/README.md

@@ -75,9 +75,11 @@ The default model-step limit is 100; reaching it returns `status: "incomplete"`,
 restart automatically to bypass it. A generation that ends on any other non-`stop` reason fails the
 run with the unified and provider finish reasons in its error and diagnostics.
 
-Before each model step, Spark trims older images, large tool results, and whole earlier turns to
-keep the request inside the model's context window. The latest user message and the most recent
-steps are never trimmed.
+When a run is given its stored `history`, Spark compacts it before any model step once the
+conversation reaches the compaction threshold: earlier turns, and earlier steps of a long turn, are
+replaced by a summary recorded on the run's message as a `data-compaction` part. Nothing else
+shortens a request; one that is still over the model's context window fails with the provider's
+error.
 
 ### Artifacts
 
@@ -355,7 +357,8 @@ features, patch for backward-compatible fixes.
 
 - `src/agent.ts` — AI SDK stream and Spark tool orchestration
 - `src/prompt.ts` — shared system prompt
-- `src/context-budget.ts` — per-step context-window trimming
+- `src/compaction.ts` — conversation compaction before each model step
+- `src/context-window.ts` — model context windows and request size estimates
 - `src/ui.ts` — browser-safe protocol types and validation schemas
 - `src/client.ts` — durable `ChatTransport` implementation
 - `src/server/` — service, storage contracts, Express adapter, artifacts, and standalone composition

package/dist/agent.d.ts

@@ -2,7 +2,6 @@ import { streamText, type LanguageModel, type ModelMessage } from "ai";
 import { type SparkGoalOffer, 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 SparkCompactionLimits } from "./compaction.js";
 import type { SparkUIMessage, SparkUIMessageChunk } from "./ui.js";
 export type SparkAgentResult = {
@@ -17,8 +16,8 @@ export type SparkAgentOptions = {
     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.
+     * compacted before any step once it is long enough (./compaction.ts); each
+     * new compaction is written to this run's message as a `data-compaction` part.
      */
     history?: SparkUIMessage[];
     model: LanguageModel;
@@ -38,12 +37,10 @@ export type SparkAgentOptions = {
     /** Gives the model `propose_goal`; absent, it has no way to offer a goal. */
     proposeGoal?: SparkGoalOffer;
     prepareMessages?(messages: ModelMessage[]): Promise<ModelMessage[]>;
-    /** The model's context window. Absent: `contextWindowFor(modelId)`. */
+    /** The model's context window, which caps when `history` is compacted. 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;
 };
 export type SparkAgentRun = {
     stream: ReadableStream<SparkUIMessageChunk>;

package/dist/agent.js

@@ -4,8 +4,8 @@ import { createUIMessageStream, stepCountIs, streamText, } from "ai";
 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 { contextWindowFor } from "./context-window.js";
+import { compactSparkHistory, createStepCompaction, latestCompaction } from "./compaction.js";
 import { convertSparkMessages } from "./model-history.js";
 function errorMessage(error) {
     return sparkErrorDiagnostics(error).message;
@@ -131,11 +131,14 @@ export function runSparkAgent(options) {
                 });
                 const readSystem = () => sparkSystemPrompt(options.capabilities.skills, options.instructions);
                 let messages = options.messages ?? [];
+                // Compaction before each later step; only for a stored conversation,
+                // where the compaction can be recorded.
+                let compactStep;
                 if (options.history !== undefined) {
                     const history = options.history;
-                    const compacted = await compactSparkHistory({
-                        history,
-                        convert: (compaction) => convertSparkMessages(history, tools, { compaction, skills: options.capabilities.skills }),
+                    const skills = options.capabilities.skills;
+                    let compactions = 0;
+                    const summaryOptions = {
                         model: options.model,
                         modelId: options.modelId,
                         system: readSystem(),
@@ -149,12 +152,29 @@ export function runSparkAgent(options) {
                             type: "data-run-status",
                             data: { runId: options.runId, status: "running", label: "Making room so we can keep talking" },
                         }),
+                    };
+                    const record = (compaction) => writer.write({
+                        type: "data-compaction",
+                        id: `compaction-${options.messageId}${compactions++ === 0 ? "" : `-${compactions}`}`,
+                        data: compaction,
+                    });
+                    const compacted = await compactSparkHistory({
+                        ...summaryOptions,
+                        history,
+                        convert: (compaction) => convertSparkMessages(history, tools, { compaction, skills }),
                     });
                     messages = compacted.messages;
-                    if (compacted.compaction !== undefined) {
-                        writer.write({ type: "data-compaction", id: `compaction-${options.messageId}`, data: compacted.compaction });
-                    }
+                    if (compacted.compaction !== undefined)
+                        record(compacted.compaction);
                     controller.signal.throwIfAborted();
+                    compactStep = createStepCompaction({
+                        ...summaryOptions,
+                        history,
+                        previous: compacted.compaction ?? latestCompaction(history)?.compaction,
+                        skills,
+                        convert: (stored) => convertSparkMessages(stored, tools, { skills }),
+                        onCompaction: record,
+                    });
                 }
                 const generation = streamText({
                     model: options.model,
@@ -166,25 +186,23 @@ export function runSparkAgent(options) {
                     stopWhen: stepCountIs(maxSteps),
                     maxOutputTokens: options.maxOutputTokens,
                     providerOptions: options.providerOptions,
-                    prepareStep: async ({ messages }) => {
+                    prepareStep: async ({ messages, steps }) => {
                         controller.signal.throwIfAborted();
-                        const prepared = options.prepareMessages === undefined
+                        // The first step was compacted above, before the request was built.
+                        // The AI SDK sends each later step what the one before it was sent,
+                        // so a compaction here holds for the rest of the turn.
+                        const last = steps.at(-1)?.usage;
+                        const current = compactStep === undefined || steps.length === 0
                             ? messages
-                            : await options.prepareMessages(messages);
+                            : await compactStep(messages, { inputTokens: last?.inputTokens, outputTokens: last?.outputTokens });
+                        controller.signal.throwIfAborted();
+                        const prepared = options.prepareMessages === undefined
+                            ? current
+                            : await options.prepareMessages(current);
                         controller.signal.throwIfAborted();
-                        const system = readSystem();
-                        // After the host's own preparation, so what is measured is what is sent.
-                        const fitted = fitMessagesToContext(prepared, {
-                            contextWindow,
-                            maxOutputTokens: options.maxOutputTokens,
-                            system,
-                            tools,
-                        });
-                        if (fitted.report && (fitted.messages !== prepared || !fitted.report.fits))
-                            options.onContextBudget?.(fitted.report);
                         return {
-                            system,
-                            messages: fitted.messages,
+                            system: readSystem(),
+                            messages: prepared,
                         };
                     },
                     onError: ({ error }) => {

package/dist/compaction.d.ts

@@ -3,10 +3,12 @@ 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. */
+/** Recent whole turns, or recent steps of the current turn, kept verbatim, up to this many tokens. */
 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;
+/** A compaction during a turn saves at least this share of the threshold, or is not made. */
+export declare const COMPACTION_MIN_SAVED_RATIO = 0.25;
 /**
  * When a conversation is compacted, for a host that exercises compaction
  * without filling a production-sized conversation, such as local development.
@@ -19,27 +21,28 @@ export type SparkCompactionLimits = {
 };
 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.]";
+export declare const COMPACTION_STEPS_NOTE = "[Earlier messages in this conversation, and the earlier steps of your work on the message after this one, 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;
+    part: 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.
+ * images the user attached to them, and -- for the latest compaction, when it was
+ * written during its turn -- the recording message's steps before
+ * `firstKeptStep` left out with 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[]>;
+type SummaryOptions = {
     model: LanguageModel;
     modelId: string;
     system: string;
@@ -53,6 +56,11 @@ export type CompactSparkHistoryOptions = {
     onCompacting?(): void;
     limits?: SparkCompactionLimits;
 };
+export type CompactSparkHistoryOptions = SummaryOptions & {
+    history: SparkUIMessage[];
+    /** `history` as model messages, with `compaction` applied when given. */
+    convert(compaction?: SparkCompaction): Promise<ModelMessage[]>;
+};
 /**
  * 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
@@ -62,3 +70,28 @@ export declare function compactSparkHistory(options: CompactSparkHistoryOptions)
     messages: ModelMessage[];
     compaction?: SparkCompaction;
 }>;
+export type StepCompactionOptions = SummaryOptions & {
+    /** The stored conversation, ending with the current user message. */
+    history: SparkUIMessage[];
+    /** The compaction the turn started from: the one written before its first step, else `history`'s latest. */
+    previous?: SparkCompaction;
+    /** The host's skills, for the summary message's skill text. */
+    skills?: readonly SparkSkill[];
+    /** Stored messages as model messages. */
+    convert(messages: SparkUIMessage[]): Promise<ModelMessage[]>;
+    /** A new compaction, for the host to record on the turn's message. */
+    onCompaction(compaction: SparkCompaction): void;
+};
+/** What the provider reported for the step before. */
+export type StepUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+};
+/**
+ * Compaction before each later step of a turn. Returns the step's messages,
+ * compacted when the conversation has reached the threshold; the AI SDK carries
+ * what a step was sent into the next, so a compaction holds for the rest of the
+ * turn.
+ */
+export declare function createStepCompaction(options: StepCompactionOptions): (messages: ModelMessage[], last?: StepUsage) => Promise<ModelMessage[]>;
+export {};