@womp/spark-agent 6.4.0 → 7.0.0

package/CHANGELOG.md

@@ -4,6 +4,103 @@ 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
+read every message before it is sent. Ordinary messages start at once, the proposal shares the
+run's prompt cache, and when to propose is decided in one place: the tool's description.
+
+### Added
+
+- The `propose_goal({ title, conditions })` tool, declared only when the host can ask the user.
+  The run waits in `requires_action` for the answer, so nothing is built before it. The tool
+  result tells the agent to build toward the goal, to carry on as a single try, or to stop and
+  wait.
+- The `data-goal-proposal` part (`sparkGoalProposalPartSchema`) stores the proposal on the
+  assistant message that made it: `title`, `conditions`, the `toolCallId`, and the `outcome` once
+  there is one. Hosts render it as the confirmation while its run waits and as the goal once it
+  started; the model does not read it.
+- `SparkAgentServiceOptions.confirmGoal` shows a proposal and resolves a `SparkGoalDecision`
+  (`sparkGoalDecisionSchema`): a goal with its caps, a single try, or unanswered. A confirmed goal
+  starts with the run that proposed it as its first try, with the run's request as its objective.
+- `SparkAgentServiceOptions.onGoalStart`, called when a confirmed goal is stored and before the
+  agent continues. A goal it rejects does not start.
+- `SparkRunExecutionContext.proposeGoal` and `SparkAgentOptions.proposeGoal` (`SparkGoalOffer`)
+  carry the offer to the agent. A custom `executeRun` that drops it leaves the tool undeclared.
+
+### Removed
+
+- `createSparkGoalProposer`, `SparkGoalProposer`, `SparkAgentService.proposeGoal`,
+  `SparkAgentServiceOptions.proposeGoal`, `POST /conversations/:id/goal/proposal` and
+  `SparkChatTransport.proposeGoal`.
+- `title` and `conditions` on the goal `set` command, and the `data-goal` part with its
+  `sparkDataPartSchemas.goal` schema: conditions now come only from a proposal the user confirmed.
+  A conversation that holds a `data-goal` part, written by 6.3.0 or 6.4.0, no longer validates.
+- `SparkChatTransport.sendMessages` no longer forwards `body.goal`.
+- `MAX_GOAL_LENGTH` from `@womp/spark-agent/ui`.
+
+### Migration
+
+- Replace the pre-send proposal call and the `set` command that followed it with `confirmGoal`:
+  show the proposal when asked, resolve the user's answer, and send every message as an ordinary
+  one. Render the `data-goal-proposal` part as the confirmation while its run waits.
+- A host that billed a goal from the `set` command starts counting in `onGoalStart`; the first
+  try's run began before the goal existed.
+- A host that stores tool calls by name must accept `propose_goal`, and must offer the tool again
+  when it replays that history, so the earlier call reads as it did live.
+- A host that validates stored messages against `sparkDataPartSchemas` must be on this version
+  before it reads a conversation that holds a `data-goal-proposal` part.
+
 ## 6.4.0 — 2026-10-12
 
 ### Added

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
 
@@ -138,7 +140,6 @@ 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
 ```
@@ -147,14 +148,17 @@ 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`.
+A goal starts from an ordinary message, when the agent proposes one. A host that sets
+`SparkAgentServiceOptions.confirmGoal` (with `evaluateGoal`) gives the agent the `propose_goal`
+tool: it calls it before building when the request sets constraints a result can be measured
+against, with a title and the conditions, each marked `measurable` or left to the user's review.
+The run then waits in `requires_action` while `confirmGoal` shows the proposal, which the
+assistant message stores as a `data-goal-proposal` part, and resolves the user's answer: `{ kind: "goal", maxTurns,
+creditBudget }`, `{ kind: "once" }`, or `{ kind: "unanswered" }` when the host stops waiting. A
+confirmed goal starts with that run as its first try; the service evaluates each measurable
+condition after every try and records the result on `goal.conditions`. Any other answer leaves an
+ordinary turn. The part then carries the `outcome`: `started`, `declined`, `unanswered`, or `active`
+when a goal was already running. `onGoalStart` tells a host that counts a goal's spending when one starts.
 
 The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
 
@@ -353,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-tools.d.ts

@@ -1,12 +1,21 @@
 import { type Tool } from "ai";
 import type { ExecutionReceipt, SparkArtifactResolver, SparkCapabilities } from "./capabilities.js";
 import type { JavaScriptExecutor } from "./executor.js";
+import { type SparkGoalOutcome, type SparkGoalProposal } from "./goals.js";
 import type { SparkUIMessage, SparkUIMessageChunk, SparkUITools } from "./ui.js";
 export type SparkToolCall = {
     id: string;
-    name: "read_skill" | "execute_javascript";
+    name: "read_skill" | "execute_javascript" | "propose_goal";
     input: unknown;
 };
+/**
+ * Shows the user a goal the model proposed and waits for their answer, starting
+ * the goal for this run when they confirm it.
+ */
+export type SparkGoalOffer = (proposal: SparkGoalProposal, call: {
+    toolCallId: string;
+    signal: AbortSignal;
+}) => Promise<SparkGoalOutcome>;
 export interface SparkPersistence {
     beforeToolCall(call: SparkToolCall): Promise<void>;
     recordReceipt(callId: string, receipt: ExecutionReceipt): Promise<void>;
@@ -22,9 +31,16 @@ export type SparkToolOptions = {
     controller: AbortController;
     persistence?: SparkPersistence;
     executionTimeoutMs?: number;
+    /** Present when the host can ask the user: the model then has `propose_goal`. */
+    proposeGoal?: SparkGoalOffer;
     write(chunk: SparkUIMessageChunk): void;
 };
-export type SparkTools = {
-    [Name in keyof SparkUITools]: Tool<SparkUITools[Name]["input"], SparkUITools[Name]["output"]>;
+type SparkTool<Name extends keyof SparkUITools> = Tool<SparkUITools[Name]["input"], SparkUITools[Name]["output"]>;
+type SparkCoreTools = {
+    [Name in "read_skill" | "execute_javascript"]: SparkTool<Name>;
 };
+export type SparkTools = SparkCoreTools | (SparkCoreTools & {
+    propose_goal: SparkTool<"propose_goal">;
+});
 export declare function createSparkTools(options: SparkToolOptions): SparkTools;
+export {};

package/dist/agent-tools.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { boundedResultText, canonicalJsonValue } from "./bounded-output.js";
 import { completedInputString } from "./tool-input-label.js";
 import { UserWait } from "./execution-lifetime.js";
+import { sparkGoalProposalSchema } from "./goals.js";
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -21,6 +22,13 @@ const artifactRefSchema = z.object({
     mediaType: z.string().min(1),
     name: z.string().optional(),
 });
+/** What the model is told a proposal came to, and so what to do next. */
+const GOAL_OUTCOMES = {
+    started: "The user confirmed the goal. Build it now, and verify every measurable condition with tool results before you finish. An independent check follows each try and sends back what is still unmet.",
+    declined: "The user chose a single try. Carry out the request as usual and do not propose a goal for it again.",
+    unanswered: "The user has not answered. Build nothing: say that you are waiting for their answer, and stop.",
+    active: "A goal is already running in this conversation. Keep working toward it.",
+};
 export function createSparkTools(options) {
     const { controller, persistence } = options;
     const executionTimeoutMs = options.executionTimeoutMs ?? 60_000;
@@ -76,7 +84,37 @@ export function createSparkTools(options) {
             onInputAvailable: ({ toolCallId }) => { inputs.delete(toolCallId); },
         };
     };
+    const { proposeGoal } = options;
     return {
+        ...(proposeGoal === undefined ? {} : {
+            propose_goal: tool({
+                description: "Offer to run the user's request as a goal: work that repeats until an independent check verifies its conditions. Call it once, before building or generating anything, when the request sets a constraint the finished result passes or fails by measurement: a size, a count, a limit, a fit to something real, a clearance, an angle, a weight, a price, or a physical requirement such as being one piece, resting on the ground or parts not intersecting. Do not call it for a question, a small direct edit, a request that only describes what to make, or while a goal is running. It shows the user the conditions and waits for their answer.",
+                inputSchema: sparkGoalProposalSchema.extend({
+                    title: sparkGoalProposalSchema.shape.title.describe("Two to four words in sentence case naming what is being made."),
+                    conditions: sparkGoalProposalSchema.shape.conditions.describe("Only constraints the user stated or directly implied, never your own, each marked measurable. The description of what to make is not a list of constraints: leave out its parts and features, and any instruction about how to work, what to check or what to render. State each as a fact about the finished result in a few words of the user's language, with its number and unit: \"Height is 120 mm\", not \"Make it 120 mm tall\". Split compound constraints. If the user asked for a look, style, feel or quality that takes judgement, add it as one condition that is not measurable, left to their review."),
+                }),
+                execute: (input, { toolCallId }) => execute({ id: toolCallId, name: "propose_goal", input }, async () => {
+                    const status = (status, label) => options.write({ type: "data-run-status", data: { runId: options.runId, status, label } });
+                    // The message keeps the proposal, and then what became of it, under one id.
+                    const store = (outcome) => options.write({
+                        type: "data-goal-proposal", id: `goal-proposal-${toolCallId}`,
+                        data: { ...input, toolCallId, ...(outcome ? { outcome } : {}) },
+                    });
+                    store();
+                    status("requires_action", "Waiting for your answer");
+                    try {
+                        const goal = await proposeGoal(input, { toolCallId, signal: controller.signal });
+                        store(goal);
+                        return { goal };
+                    }
+                    finally {
+                        if (!controller.signal.aborted)
+                            status("running", "Continuing after user input");
+                    }
+                }),
+                toModelOutput: ({ output }) => ({ type: "text", value: GOAL_OUTCOMES[output.goal] }),
+            }),
+        }),
         read_skill: tool({
             ...inputLabels("name"),
             description: "Read the skills listed in names. Returns instructions, TypeScript API declarations, and JavaScript examples from the available directory.",

package/dist/agent.d.ts

@@ -1,8 +1,7 @@
 import { streamText, type LanguageModel, type ModelMessage } from "ai";
-import { type SparkPersistence } from "./agent-tools.js";
+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;
@@ -35,13 +34,13 @@ export type SparkAgentOptions = {
     maxOutputTokens?: number;
     executionTimeoutMs?: number;
     persistence?: SparkPersistence;
+    /** 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/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, SparkGoalProposal } from "./goals.js";
-export type { SparkGoal, SparkGoalCommand, SparkGoalCondition, SparkGoalProposal, SparkGoalTry } from "./goals.js";
+import type { SparkGoal, SparkGoalCommand } from "./goals.js";
+export type { SparkGoal, SparkGoalCommand, SparkGoalCondition, SparkGoalDecision, 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,8 +44,6 @@ 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

@@ -60,8 +60,6 @@ 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);
@@ -129,15 +127,6 @@ 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

@@ -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 {};