@womp/spark-agent 6.3.0 → 6.4.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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

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.
 

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/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;

package/dist/context-budget.js

@@ -14,7 +14,9 @@
 // WHAT, in this order, until the estimate is back under the target:
 //
 //  1. Images before the current turn, oldest first -- the most tokens for the
-//     least text, and the ones a later step least needs to see again.
+//     least text, and the ones a later step least needs to see again. The
+//     agent's own screenshots go before the images the user attached, which
+//     are what the work is often built from.
 //  2. Large tool results before the current turn, oldest first. The call and a
 //     result part stay, with a note in place of the output, so no provider is
 //     handed a call without its result.
@@ -155,12 +157,12 @@ export function fitMessagesToContext(messages, options) {
      * replacement and roughly what that saves -- used only to stop partway through a
      * message, which is then measured again.
      */
-    const rewriteEarlier = (rewrite) => {
+    const rewriteEarlier = (rewrite, only = () => true) => {
         for (let i = 0; i < protectedFrom && total > target; i += 1) {
             if (i === current)
                 continue;
             const message = out[i];
-            if (message === undefined || !Array.isArray(message.content))
+            if (message === undefined || !Array.isArray(message.content) || !only(message))
                 continue;
             let projected = total;
             let changed = false;
@@ -183,8 +185,8 @@ export function fitMessagesToContext(messages, options) {
             out[i] = next;
         }
     };
-    // 1. Earlier images.
-    rewriteEarlier((part, projected) => {
+    // 1. Earlier images: the agent's own first, then those the user attached.
+    const omitImages = (part, projected) => {
         if (isImage(part)) {
             report.omittedImages += 1;
             return { part: omittedImage(), saved: IMAGE_TOKENS };
@@ -201,7 +203,9 @@ export function fitMessagesToContext(messages, options) {
             return omittedImage();
         });
         return saved === 0 ? { part, saved } : { part: { ...part, output: { ...part.output, value } }, saved };
-    });
+    };
+    rewriteEarlier(omitImages, ({ role }) => role !== "user");
+    rewriteEarlier(omitImages, ({ role }) => role === "user");
     // 2. Earlier large tool results.
     rewriteEarlier((part) => {
         if (!isToolResult(part))
@@ -249,6 +253,10 @@ export function fitMessagesToContext(messages, options) {
 export function estimateMessagesTokens(messages) {
     return sum(messages.map(messageTokens));
 }
+/** The estimate for a whole request: its messages, system prompt and tool definitions. */
+export function estimateRequestTokens(messages, options) {
+    return estimateMessagesTokens(messages) + textTokens(options.system ?? "") + toolsTokens(options.tools);
+}
 // ── estimation ──────────────────────────────────────────────────────────────
 const estimates = new WeakMap();
 function messageTokens(message) {

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { runSparkAgent, type SparkAgentOptions, type SparkAgentResult, type SparkAgentRun, } from "./agent.js";
 export { createSparkTools, type SparkPersistence, type SparkToolCall } from "./agent-tools.js";
 export { convertSparkMessages } from "./model-history.js";
+export type { SparkCompactionLimits } from "./compaction.js";
 export * from "./context-budget.js";
 export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, type SdkSceneEditor, type SdkSceneEditorOptions, type SdkSceneEditIdentity, type SdkSceneServices, } from "./sdk-scene-host.js";

package/dist/model-history.d.ts

@@ -1,5 +1,15 @@
 import { type ModelMessage } from "ai";
 import type { createSparkTools } from "./agent-tools.js";
-import { type SparkUIMessage } from "./ui.js";
-/** UI artifact previews already represented by a tool result are not model output. */
-export declare function convertSparkMessages(messages: SparkUIMessage[], tools: ReturnType<typeof createSparkTools>): Promise<ModelMessage[]>;
+import type { SparkSkill } from "./capabilities.js";
+import { type SparkCompaction, type SparkUIMessage } from "./ui.js";
+/**
+ * The stored conversation as model messages. UI artifact previews already
+ * represented by a tool result are not model output. The messages before the
+ * latest compaction's kept message -- or `options.compaction`'s -- are sent as
+ * its summary, with the current text of the skills it names from
+ * `options.skills` and the images the user attached to them (./compaction.ts).
+ */
+export declare function convertSparkMessages(messages: SparkUIMessage[], tools: ReturnType<typeof createSparkTools>, options?: {
+    compaction?: SparkCompaction;
+    skills?: readonly SparkSkill[];
+}): Promise<ModelMessage[]>;

package/dist/model-history.js

@@ -1,4 +1,5 @@
 import { asSchema, convertToModelMessages } from "ai";
+import { applyCompaction } from "./compaction.js";
 import { sparkDataPartSchemas } from "./ui.js";
 function record(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -32,9 +33,15 @@ function goalConditionsText({ conditions }) {
         + (reviewed ? `\nPreferences the user will review themselves:${reviewed}` : "")
         + "]";
 }
-/** UI artifact previews already represented by a tool result are not model output. */
-export async function convertSparkMessages(messages, tools) {
-    const history = await Promise.all(messages.map(async (message) => {
+/**
+ * The stored conversation as model messages. UI artifact previews already
+ * represented by a tool result are not model output. The messages before the
+ * latest compaction's kept message -- or `options.compaction`'s -- are sent as
+ * its summary, with the current text of the skills it names from
+ * `options.skills` and the images the user attached to them (./compaction.ts).
+ */
+export async function convertSparkMessages(messages, tools, options = {}) {
+    const history = await Promise.all(applyCompaction(messages, options).map(async (message) => {
         if (message.role !== "assistant")
             return message;
         const previews = new Set();

package/dist/server/executor.d.ts

@@ -8,6 +8,8 @@ export type ResolvedSparkModel = {
     maxOutputTokens?: number;
 };
 export type SparkRunExecutorOptions = {
+    /** When a run's conversation is compacted; see `SparkAgentOptions.compaction`. */
+    compaction?: SparkAgentOptions["compaction"];
     resolveModel(settings: SparkRunSettings): ResolvedSparkModel | Promise<ResolvedSparkModel>;
     createHost(context: SparkRunExecutionContext): Promise<Pick<SparkAgentOptions, "capabilities" | "executor" | "artifacts" | "persistence"> & {
         dispose(): void;

package/dist/server/executor.js

@@ -1,25 +1,17 @@
-import { convertSparkMessages } from "../model-history.js";
 import { runSparkAgent } from "../agent.js";
-import { createSparkTools } from "../agent-tools.js";
 export function createSparkRunExecutor(options) {
     return async (context) => {
         const resolved = await options.resolveModel(context.settings);
         const host = await options.createHost(context);
         try {
-            const tools = createSparkTools({
-                ...host,
-                runId: context.runId,
-                controller: new AbortController(),
-                write: () => undefined,
-            });
-            const messages = await convertSparkMessages(context.uiMessages, tools);
             const run = runSparkAgent({
                 ...host,
-                messages,
+                history: context.uiMessages,
                 model: resolved.model,
                 modelId: resolved.modelId,
                 providerOptions: resolved.providerOptions,
                 maxOutputTokens: resolved.maxOutputTokens,
+                compaction: options.compaction,
                 runId: context.runId,
                 messageId: context.assistantMessageId,
                 signal: context.signal,

package/dist/server/goal-evaluator.d.ts

@@ -2,6 +2,8 @@ import { z } from "zod";
 import type { SparkGoal } from "../goals.js";
 import type { SparkUIMessage } from "../ui.js";
 import type { SparkRunExecutorOptions } from "./executor.js";
+/** How many of the user's newest images an evaluation attaches as the reference. */
+export declare const GOAL_REFERENCE_IMAGES = 4;
 export declare const goalVerdictSchema: z.ZodObject<{
     conditions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         index: z.ZodNumber;
@@ -19,6 +21,11 @@ export type SparkGoalEvaluation = z.infer<typeof goalVerdictSchema>;
 export type SparkGoalEvaluator = (input: {
     ownerId?: string;
     goal: SparkGoal;
+    /**
+     * The conversation. The images the user attached to it are the evaluation's
+     * reference, read only from `data:` URLs: a host that stores them elsewhere
+     * passes the messages with those images inline.
+     */
     messages: SparkUIMessage[];
     context?: Record<string, unknown>;
     signal: AbortSignal;

package/dist/server/goal-evaluator.js

@@ -1,6 +1,14 @@
 import { generateText, Output } from "ai";
 import { z } from "zod";
+import { userImages } from "../user-images.js";
 import { WOMPIFY_PRESETS, wompifyContextSchema } from "../wompify.js";
+/** How many of the user's newest images an evaluation attaches as the reference. */
+export const GOAL_REFERENCE_IMAGES = 4;
+/** A `data:` URL's bytes; hosts hand the evaluator the user's images inline. */
+function dataUrlBytes(url) {
+    const match = /^data:[^,]*;base64,(.*)$/s.exec(url);
+    return match ? new Uint8Array(Buffer.from(match[1], "base64")) : undefined;
+}
 const verdictShape = {
     verdict: z.enum(["met", "continue", "blocked"]),
     reason: z.string().min(1).max(2_000),
@@ -36,6 +44,20 @@ export function createSparkGoalEvaluator(options) {
         const content = [];
         const unavailable = [];
         let bytes = 0;
+        // The images the user attached are the reference the reconstruction views
+        // are compared with, so they go first, ahead of the byte cap. A Wompify
+        // goal's reference is a scene object instead.
+        const references = wompify.success ? [] : userImages(messages).slice(-GOAL_REFERENCE_IMAGES);
+        for (const [index, image] of references.entries()) {
+            const name = image.filename ?? `reference ${index + 1}`;
+            const data = dataUrlBytes(image.url);
+            if (!data || bytes + data.byteLength > 8_000_000) {
+                unavailable.push(name);
+                continue;
+            }
+            bytes += data.byteLength;
+            content.push({ type: "text", text: `Reference image the user attached: ${name}` }, { type: "file", data, mediaType: image.mediaType });
+        }
         for (const id of selected) {
             signal.throwIfAborted();
             const image = ownerId ? await options.resolveImage?.(ownerId, id) : undefined;

package/dist/server/index.d.ts

@@ -1,6 +1,6 @@
 export { MemorySparkArtifactStore } from "./artifacts.js";
 export { WompifyCreditCapReachedError } from "../wompify.js";
-export { createSparkGoalEvaluator, type SparkGoalEvaluator, type SparkGoalEvaluation } from "./goal-evaluator.js";
+export { createSparkGoalEvaluator, GOAL_REFERENCE_IMAGES, type SparkGoalEvaluator, type SparkGoalEvaluation } from "./goal-evaluator.js";
 export { createSparkGoalProposer, type SparkGoalProposer } from "./goal-proposer.js";
 export { sparkGoalCommandSchema, sparkGoalProposalSchema, type SparkGoal, type SparkGoalCommand, type SparkGoalCondition, type SparkGoalProposal, type SparkGoalTry } from "../goals.js";
 export type { SparkArtifactStore, StoredSparkArtifact } from "./artifacts.js";

package/dist/server/index.js

@@ -1,6 +1,6 @@
 export { MemorySparkArtifactStore } from "./artifacts.js";
 export { WompifyCreditCapReachedError } from "../wompify.js";
-export { createSparkGoalEvaluator } from "./goal-evaluator.js";
+export { createSparkGoalEvaluator, GOAL_REFERENCE_IMAGES } from "./goal-evaluator.js";
 export { createSparkGoalProposer } from "./goal-proposer.js";
 export { sparkGoalCommandSchema, sparkGoalProposalSchema } from "../goals.js";
 export { createSparkRunExecutor, } from "./executor.js";

package/dist/ui.d.ts

@@ -91,12 +91,31 @@ export type SparkDataParts = {
         receipt: ExecutionReceipt;
     };
     selection: SparkSelectionData;
+    compaction: SparkCompaction;
     goal: SparkGoalProposal;
 };
 /** Editor node IDs selected when a user message was sent; never rendered as chat text. */
 export type SparkSelectionData = {
     nodeIds: string[];
 };
+/**
+ * A summary of a long conversation's earlier messages, recorded on the assistant
+ * message of the turn that wrote it. The model is sent the summary in place of
+ * every message before `firstKeptMessageId`; the chat still shows all of them.
+ */
+export type SparkCompaction = {
+    /** The user message the model reads verbatim from; everything before it is summarized. */
+    firstKeptMessageId: string;
+    summary: string;
+    /** Skills read in the summarized messages; their current text is sent after the summary. */
+    skills: string[];
+    /** The model that wrote the summary. */
+    modelId: string;
+    /** The conversation's size before and after, in tokens. */
+    tokensBefore: number;
+    tokensAfter: number;
+    createdAt: string;
+};
 export type ExecuteJavaScriptInput = {
     purpose: string;
     code: string;
@@ -335,6 +354,15 @@ export declare const sparkDataPartSchemas: {
     readonly selection: z.ZodObject<{
         nodeIds: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+    readonly compaction: z.ZodObject<{
+        firstKeptMessageId: z.ZodString;
+        summary: z.ZodString;
+        skills: z.ZodArray<z.ZodString>;
+        modelId: z.ZodString;
+        tokensBefore: z.ZodNumber;
+        tokensAfter: z.ZodNumber;
+        createdAt: z.ZodString;
+    }, z.core.$strip>;
     /**
      * The conditions the user confirmed for the goal this message starts. The model
      * reads it as text (model-history.ts).

package/dist/ui.js

@@ -86,6 +86,15 @@ export const sparkDataPartSchemas = {
      */
     // Editor ids are the engine's decimal integers; 8192 covers a select-all at the engine's budgets.
     selection: z.object({ nodeIds: z.array(z.string().min(1).max(64)).min(1).max(8192) }),
+    compaction: z.object({
+        firstKeptMessageId: z.string().min(1),
+        summary: z.string().min(1),
+        skills: z.array(z.string().min(1)),
+        modelId: z.string(),
+        tokensBefore: z.number().int().nonnegative(),
+        tokensAfter: z.number().int().nonnegative(),
+        createdAt: z.string().datetime(),
+    }),
     /**
      * The conditions the user confirmed for the goal this message starts. The model
      * reads it as text (model-history.ts).

package/dist/user-images.d.ts

@@ -0,0 +1,10 @@
+import type { SparkUIMessage } from "./ui.js";
+export type SparkFilePart = Extract<SparkUIMessage["parts"][number], {
+    type: "file";
+}>;
+/**
+ * The images the user attached to `messages`, each once, in the order sent:
+ * what the work is often built from, so the model calls that do or judge it
+ * keep them longest.
+ */
+export declare function userImages(messages: readonly SparkUIMessage[]): SparkFilePart[];

package/dist/user-images.js

@@ -0,0 +1,20 @@
+/**
+ * The images the user attached to `messages`, each once, in the order sent:
+ * what the work is often built from, so the model calls that do or judge it
+ * keep them longest.
+ */
+export function userImages(messages) {
+    const seen = new Set();
+    const images = [];
+    for (const message of messages) {
+        if (message.role !== "user")
+            continue;
+        for (const part of message.parts) {
+            if (part.type !== "file" || !part.mediaType.startsWith("image/") || seen.has(part.url))
+                continue;
+            seen.add(part.url);
+            images.push(part);
+        }
+    }
+    return images;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",