@womp/spark-agent 6.5.0 → 7.0.0

package/dist/ui.d.ts

@@ -106,6 +106,12 @@ export type SparkSelectionData = {
 export type SparkCompaction = {
     /** The user message the model reads verbatim from; everything before it is summarized. */
     firstKeptMessageId: string;
+    /**
+     * Set when the summary was written during its turn: the first step of the
+     * recording message the model still reads, counted from 0. Its earlier steps
+     * are summarized too.
+     */
+    firstKeptStep?: number;
     summary: string;
     /** Skills read in the summarized messages; their current text is sent after the summary. */
     skills: string[];
@@ -363,6 +369,7 @@ export declare const sparkDataPartSchemas: {
     }, z.core.$strip>;
     readonly compaction: z.ZodObject<{
         firstKeptMessageId: z.ZodString;
+        firstKeptStep: z.ZodOptional<z.ZodNumber>;
         summary: z.ZodString;
         skills: z.ZodArray<z.ZodString>;
         modelId: z.ZodString;

package/dist/ui.js

@@ -88,6 +88,7 @@ export const sparkDataPartSchemas = {
     selection: z.object({ nodeIds: z.array(z.string().min(1).max(64)).min(1).max(8192) }),
     compaction: z.object({
         firstKeptMessageId: z.string().min(1),
+        firstKeptStep: z.number().int().positive().optional(),
         summary: z.string().min(1),
         skills: z.array(z.string().min(1)),
         modelId: z.string(),

package/package.json

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

package/dist/context-budget.d.ts

@@ -1,65 +0,0 @@
-import type { ModelMessage } from "ai";
-/** Under prose's ~3.5-4, so the estimate errs high. */
-export declare const CHARS_PER_TOKEN = 3;
-/** About what one image at the providers' 1568 px ceiling costs. */
-export declare const IMAGE_TOKENS = 1600;
-export declare const MESSAGE_OVERHEAD_TOKENS = 4;
-/** Per tool: its name, description and input schema around the counted text. */
-export declare const TOOL_DEFINITION_OVERHEAD_TOKENS = 300;
-/** Start trimming once the estimate passes this share of the budget. */
-export declare const TRIM_TRIGGER_RATIO = 0.9;
-/** Then trim down to this share, so the next steps do not trim again. */
-export declare const TRIM_TARGET_RATIO = 0.75;
-/** A tool result at or below this is left whole: not worth the detail it loses. */
-export declare const SMALL_TOOL_OUTPUT_TOKENS = 500;
-/**
- * Steps of the CURRENT turn kept whole, however long that turn runs.
- *
- * The model is mid-task and reasons from what it just did, so the recent steps
- * have to survive; the ones before them are history like any other and are worth
- * more as window than as detail. Five is small enough that a long run always
- * recovers room and large enough to hold a read-edit-verify cycle.
- */
-export declare const PROTECTED_CURRENT_STEPS = 5;
-export declare const OMITTED_HISTORY_TEXT = "[Earlier messages in this conversation were left out of this request to fit the model's context window.]";
-export declare const OMITTED_HISTORY_IMAGE_TEXT = "[An earlier image was left out of this request to fit the model's context window.]";
-export declare const OMITTED_TOOL_OUTPUT_TEXT = "[This earlier tool result was left out of this request to fit the model's context window.]";
-/**
- * The model's context window, or undefined when it is not known.
- *
- * Listed models first, then model families whose window is certain. Anything
- * else -- a third-party model routed through OpenRouter -- is undefined, and the
- * conversation is then left exactly as it was: overestimating a window can only
- * repeat today's failure, but underestimating one would silently hide history
- * from a model that could read it.
- */
-export declare function contextWindowFor(modelId: string): number | undefined;
-export type ContextBudgetOptions = {
-    /** Undefined: the conversation is returned untouched, with no report. */
-    contextWindow: number | undefined;
-    /** Reserved for the response. */
-    maxOutputTokens?: number;
-    system?: string;
-    /** The request's tool set, by name. */
-    tools?: Record<string, unknown>;
-};
-export type ContextBudgetReport = {
-    /** What the messages may use: the window less output, system and tools. */
-    budgetTokens: number;
-    originalTokens: number;
-    estimatedTokens: number;
-    omittedImages: number;
-    omittedToolOutputs: number;
-    omittedMessages: number;
-    /** False when even the current turn alone is over the budget. */
-    fits: boolean;
-};
-export type ContextBudgetResult = {
-    messages: ModelMessage[];
-    report?: ContextBudgetReport;
-};
-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

@@ -1,364 +0,0 @@
-// Keep one model request inside the model's context window.
-//
-// A Spark turn sends the whole conversation on every step: for a thread that
-// Swan and Crow both write to, that is every earlier turn, every tool result
-// (each up to MODEL_RESULT_BYTE_LIMIT, ./bounded-output.ts) and every image. Nothing
-// bounded the total, so a long enough thread passed the provider's limit and every
-// later turn failed on its first request ("prompt is too long: 1006655 tokens >
-// 1000000 maximum") -- permanently, since each failed attempt only adds rows.
-//
-// This runs on the messages of every step, after the host's own preparation and
-// before the request is built, in both executors: the shared loop (./agent.ts,
-// which Crow runs) and the browser's own loop in Swan.
-//
-// 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. 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.
-//  3. Whole turns, oldest first, cut at user messages so every remaining call is
-//     still paired with its result. A note in their place tells the model that
-//     earlier messages were left out.
-//
-// THE CURRENT TURN is the latest user message and everything after it. The
-// message itself -- the question and any image the user just attached -- is never
-// changed, and neither are the last PROTECTED_CURRENT_STEPS steps after it: the
-// model has to be able to see what it just did.
-//
-// Its EARLIER steps are trimmed like any other history, by stages 1 and 2 above.
-// They were exempt until 2026-10-01, on the assumption that a turn is small. An
-// agentic run's turn is not: every step it takes lands after that user message,
-// and `maxSteps` is 100. dev0 thread 142417 reached the window that way -- ten
-// minutes of work, earlier history already trimmed to nothing, and what was left
-// over the limit was the run's own tool results, which nothing was allowed to
-// touch. Stage 3 still stops at the current turn, because dropping whole messages
-// inside it cannot keep calls paired with their results.
-//
-// When the protected part alone is over the window the request still goes out as
-// it is, and the provider's own error says so.
-//
-// ESTIMATES, NOT COUNTS. Counting needs the provider's tokenizer or a request.
-// The estimate is deliberately high (CHARS_PER_TOKEN is under the ~3.5-4 of prose)
-// and trimming starts at TRIM_TRIGGER_RATIO of the budget, so dense JSON that
-// tokenizes worse than prose still lands under the real limit. Images count by
-// number, never by their bytes.
-//
-// STABLE ACROSS STEPS. Once over, the conversation is trimmed to
-// TRIM_TARGET_RATIO rather than to the limit, and always oldest first, so the next
-// steps of the run trim the same prefix again instead of a little more each time --
-// which keeps a provider's prompt cache warm.
-import { SPARK_MODELS } from "./models.js";
-/** Under prose's ~3.5-4, so the estimate errs high. */
-export const CHARS_PER_TOKEN = 3;
-/** About what one image at the providers' 1568 px ceiling costs. */
-export const IMAGE_TOKENS = 1_600;
-export const MESSAGE_OVERHEAD_TOKENS = 4;
-/** Per tool: its name, description and input schema around the counted text. */
-export const TOOL_DEFINITION_OVERHEAD_TOKENS = 300;
-/** Start trimming once the estimate passes this share of the budget. */
-export const TRIM_TRIGGER_RATIO = 0.9;
-/** Then trim down to this share, so the next steps do not trim again. */
-export const TRIM_TARGET_RATIO = 0.75;
-/** A tool result at or below this is left whole: not worth the detail it loses. */
-export const SMALL_TOOL_OUTPUT_TOKENS = 500;
-/**
- * Steps of the CURRENT turn kept whole, however long that turn runs.
- *
- * The model is mid-task and reasons from what it just did, so the recent steps
- * have to survive; the ones before them are history like any other and are worth
- * more as window than as detail. Five is small enough that a long run always
- * recovers room and large enough to hold a read-edit-verify cycle.
- */
-export const PROTECTED_CURRENT_STEPS = 5;
-export const OMITTED_HISTORY_TEXT = "[Earlier messages in this conversation were left out of this request to fit the model's context window.]";
-export const OMITTED_HISTORY_IMAGE_TEXT = "[An earlier image was left out of this request to fit the model's context window.]";
-export const OMITTED_TOOL_OUTPUT_TEXT = "[This earlier tool result was left out of this request to fit the model's context window.]";
-/**
- * The model's context window, or undefined when it is not known.
- *
- * Listed models first, then model families whose window is certain. Anything
- * else -- a third-party model routed through OpenRouter -- is undefined, and the
- * conversation is then left exactly as it was: overestimating a window can only
- * repeat today's failure, but underestimating one would silently hide history
- * from a model that could read it.
- */
-export function contextWindowFor(modelId) {
-    const listed = SPARK_MODELS.find(({ id }) => id === modelId)?.contextWindow;
-    if (listed !== undefined)
-        return listed;
-    if (/^claude-haiku-/.test(modelId))
-        return 200_000;
-    if (/^claude-/.test(modelId))
-        return 1_000_000;
-    if (/^gpt-6-/.test(modelId))
-        return 1_050_000;
-    if (/^gemini-/.test(modelId))
-        return 1_048_576;
-    return undefined;
-}
-/**
- * Where the current turn's protected tail begins: the Nth-from-last step.
- *
- * Counted by ASSISTANT messages, because that is what starts a step -- the tool
- * messages that answer it follow and are protected with it, so no call is ever
- * separated from its result. A turn with fewer steps than that protects all of
- * them, which is what this did for every turn before it could trim one.
- */
-function protectedTailStart(messages, current) {
-    let steps = 0;
-    for (let i = messages.length - 1; i > current; i -= 1) {
-        if (messages[i]?.role !== "assistant")
-            continue;
-        steps += 1;
-        if (steps >= PROTECTED_CURRENT_STEPS)
-            return i;
-    }
-    return current + 1;
-}
-export function fitMessagesToContext(messages, options) {
-    if (options.contextWindow === undefined)
-        return { messages };
-    const budgetTokens = Math.max(0, options.contextWindow -
-        (options.maxOutputTokens ?? 0) -
-        textTokens(options.system ?? "") -
-        toolsTokens(options.tools));
-    const sizes = messages.map(messageTokens);
-    const originalTokens = sum(sizes);
-    const report = {
-        budgetTokens,
-        originalTokens,
-        estimatedTokens: originalTokens,
-        omittedImages: 0,
-        omittedToolOutputs: 0,
-        omittedMessages: 0,
-        fits: originalTokens <= budgetTokens,
-    };
-    if (originalTokens <= budgetTokens * TRIM_TRIGGER_RATIO)
-        return { messages, report };
-    // The current turn starts at the latest user message. With no user message at
-    // all there is no turn to reason about and nothing is touched.
-    const current = lastIndex(messages, ({ role }) => role === "user");
-    if (current < 0)
-        return { messages, report };
-    // Stages 1 and 2 rewrite everything before this: all earlier turns, and the
-    // current turn's own earlier steps. `current` itself is skipped -- the user's
-    // question and the image they just attached are not history.
-    const protectedFrom = protectedTailStart(messages, current);
-    const target = budgetTokens * TRIM_TARGET_RATIO;
-    const out = messages.slice();
-    let total = originalTokens;
-    /**
-     * Rewrites the parts of each earlier message, oldest first, until the estimate
-     * is under the target. `rewrite` answers the same part to keep it, or its
-     * replacement and roughly what that saves -- used only to stop partway through a
-     * message, which is then measured again.
-     */
-    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) || !only(message))
-                continue;
-            let projected = total;
-            let changed = false;
-            const content = message.content.map((part) => {
-                if (projected <= target)
-                    return part;
-                const result = rewrite(part, projected);
-                if (result.part === part)
-                    return part;
-                changed = true;
-                projected -= result.saved;
-                return result.part;
-            });
-            if (!changed)
-                continue;
-            const next = { ...message, content };
-            const size = messageTokens(next);
-            total += size - (sizes[i] ?? 0);
-            sizes[i] = size;
-            out[i] = next;
-        }
-    };
-    // 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 };
-        }
-        if (!isToolResult(part) || part.output.type !== "content" || !Array.isArray(part.output.value)) {
-            return { part, saved: 0 };
-        }
-        let saved = 0;
-        const value = part.output.value.map((item) => {
-            if (projected - saved <= target || !isImage(item))
-                return item;
-            report.omittedImages += 1;
-            saved += IMAGE_TOKENS;
-            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))
-            return { part, saved: 0 };
-        const saved = outputTokens(part.output);
-        if (saved <= SMALL_TOOL_OUTPUT_TOKENS)
-            return { part, saved: 0 };
-        report.omittedToolOutputs += 1;
-        return { part: { ...part, output: { type: "text", value: OMITTED_TOOL_OUTPUT_TEXT } }, saved };
-    });
-    // 3. Whole earlier turns, cut at user messages.
-    if (total > target) {
-        const note = { role: "user", content: [{ type: "text", text: OMITTED_HISTORY_TEXT }] };
-        const noteTokens = messageTokens(note);
-        const ends = [];
-        out.forEach(({ role }, i) => {
-            if (i > 0 && i < current && role === "user")
-                ends.push(i);
-        });
-        ends.push(current);
-        let cut = 0;
-        for (const end of ends) {
-            if (total + noteTokens <= target)
-                break;
-            for (let i = cut; i < end; i += 1) {
-                const message = out[i];
-                if (message === undefined || message.role === "system")
-                    continue;
-                total -= sizes[i] ?? 0;
-                report.omittedMessages += 1;
-            }
-            cut = end;
-        }
-        if (cut > 0) {
-            const kept = out.slice(0, cut).filter(({ role }) => role === "system");
-            out.splice(0, cut, ...kept, note);
-            total += noteTokens;
-        }
-    }
-    report.estimatedTokens = total;
-    report.fits = total <= budgetTokens;
-    return { messages: out, report };
-}
-/** The estimate for a list of messages, as `fitMessagesToContext` counts them. */
-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) {
-    const known = estimates.get(message);
-    if (known !== undefined)
-        return known;
-    const content = message.content;
-    const size = MESSAGE_OVERHEAD_TOKENS +
-        (typeof content === "string"
-            ? textTokens(content)
-            : Array.isArray(content)
-                ? sum(content.map(partTokens))
-                : 0);
-    estimates.set(message, size);
-    return size;
-}
-function partTokens(part) {
-    if (isImage(part))
-        return IMAGE_TOKENS;
-    switch (part.type) {
-        case "text":
-        case "reasoning":
-            return textTokens(String(part.text ?? ""));
-        case "file":
-            return dataTokens(part.data);
-        case "tool-call":
-            return textTokens(String(part.toolName ?? "")) + textTokens(json(part.input));
-        case "tool-result":
-            return isToolResult(part) ? outputTokens(part.output) : 0;
-        default:
-            return textTokens(json(part));
-    }
-}
-function outputTokens(output) {
-    switch (output.type) {
-        case "text":
-        case "error-text":
-            return textTokens(String(output.value ?? ""));
-        case "content":
-            return Array.isArray(output.value)
-                ? sum(output.value.map((item) => isImage(item) ? IMAGE_TOKENS : item.type === "text" ? textTokens(String(item.text ?? "")) : dataTokens(item.data)))
-                : 0;
-        default:
-            return textTokens(json(output.value));
-    }
-}
-function textTokens(text) {
-    return Math.ceil(text.length / CHARS_PER_TOKEN);
-}
-function dataTokens(data) {
-    if (typeof data === "string")
-        return textTokens(data);
-    if (data instanceof Uint8Array || data instanceof ArrayBuffer)
-        return Math.ceil(data.byteLength / CHARS_PER_TOKEN);
-    return 0;
-}
-function toolsTokens(tools) {
-    if (!tools)
-        return 0;
-    return sum(Object.entries(tools).map(([name, tool]) => {
-        const description = tool?.description;
-        return (TOOL_DEFINITION_OVERHEAD_TOKENS + textTokens(name) + textTokens(typeof description === "string" ? description : ""));
-    }));
-}
-/** JSON text, with binary left out: its size is not text the model reads. */
-function json(value) {
-    try {
-        return (JSON.stringify(value, (_key, v) => (v instanceof Uint8Array || v instanceof ArrayBuffer ? "" : v)) ?? "");
-    }
-    catch {
-        return "";
-    }
-}
-// ── shapes ──────────────────────────────────────────────────────────────────
-function isImage(part) {
-    if (part.type === "image" || part.type === "image-data" || part.type === "image-url")
-        return true;
-    const mediaType = part.mediaType;
-    return ((part.type === "file" || part.type === "media" || part.type === "file-data" || part.type === "file-url") &&
-        typeof mediaType === "string" &&
-        mediaType.startsWith("image/"));
-}
-function isToolResult(part) {
-    return (part.type === "tool-result" &&
-        typeof part.output === "object" &&
-        part.output !== null &&
-        typeof part.output.type === "string");
-}
-function sum(values) {
-    let total = 0;
-    for (const value of values)
-        total += value;
-    return total;
-}
-function lastIndex(items, test) {
-    for (let i = items.length - 1; i >= 0; i -= 1) {
-        const item = items[i];
-        if (item !== undefined && test(item))
-            return i;
-    }
-    return -1;
-}
-function omittedImage() {
-    return { type: "text", text: OMITTED_HISTORY_IMAGE_TEXT };
-}