@womp/spark-agent 6.5.0 → 8.0.0

package/dist/compaction.js

@@ -1,25 +1,44 @@
 // 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.
+// This is the only thing that takes messages out of what the model reads. Nothing
+// trims a request to fit the window: a request still over it after compaction is
+// sent as it is, and fails with the provider's own error.
+//
+// WHEN. Before every step of a turn, once the conversation reaches
+// COMPACTION_THRESHOLD_TOKENS (or the model's window less its output, if that is
+// lower):
+//
+//  - Before the first step (`compactSparkHistory`), everything before the most
+//    recent COMPACTION_KEEP_RECENT_TOKENS of whole turns is summarized.
+//  - Before a later step (`createStepCompaction`), the turn has grown by its own
+//    work: everything before the current user message, and the turn's steps
+//    before its most recent COMPACTION_KEEP_RECENT_TOKENS, is summarized. The
+//    user's message itself is kept as it is. A compaction that would save less
+//    than a quarter of the threshold is not made, so a turn whose own message is
+//    over the threshold does not summarize again on every step.
+//
+// A summary that fails leaves the step as it was.
 //
 // 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.
+// sends the latest one in place of the messages before `firstKeptMessageId` --
+// and, for one written during its turn, in place of that message's steps before
+// `firstKeptStep`. 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.
+//
+// WHAT IS SUMMARIZED. Only the messages the summary replaces. A kept message
+// it also told of would come after it again, and the model would take that work
+// for done twice.
 //
-// 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
+// THE CACHE. The summary request is an earlier request -- the same system
+// prompt, tool definitions and messages, up to the kept ones -- 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.
+// summary instead. The messages a step is sent after a compaction are the ones a
+// later turn rebuilds from storage, so the next turn's prefix is cached too.
 //
 // SKILLS. A skill read in the summarized messages would otherwise be lost with
 // them. The compaction names them, and its summary message carries their
@@ -30,15 +49,17 @@
 // 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 { CHARS_PER_TOKEN, IMAGE_TOKENS, estimateMessagesTokens, estimateRequestTokens } from "./context-window.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. */
+/** Recent whole turns, or recent steps of the current turn, kept verbatim, up to this many tokens. */
 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;
+/** A compaction during a turn saves at least this share of the threshold, or is not made. */
+export const COMPACTION_MIN_SAVED_RATIO = 0.25;
 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:
@@ -51,22 +72,23 @@ Use these sections:
 ## 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.]";
+export 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 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")
+        for (let part = message.parts.length - 1; part >= 0; part -= 1) {
+            const value = message.parts[part];
+            if (value?.type !== "data-compaction")
                 continue;
-            const parsed = sparkDataPartSchemas.compaction.safeParse(part.data);
+            const parsed = sparkDataPartSchemas.compaction.safeParse(value.data);
             if (!parsed.success)
                 continue;
             const firstKept = history.findIndex(({ id }) => id === parsed.data.firstKeptMessageId);
             if (firstKept >= 0)
-                return { compaction: parsed.data, carrier, firstKept };
+                return { compaction: parsed.data, carrier, part, firstKept };
         }
     }
     return undefined;
@@ -74,21 +96,37 @@ export function latestCompaction(history) {
 /**
  * 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 function applyCompaction(history, options = {}) {
-    const compaction = options.compaction ?? latestCompaction(history)?.compaction;
+    const latest = options.compaction === undefined ? latestCompaction(history) : undefined;
+    const compaction = options.compaction ?? latest?.compaction;
     if (compaction === undefined)
         return history;
     const firstKept = history.findIndex(({ id }) => id === compaction.firstKeptMessageId);
     if (firstKept < 0)
         return history;
+    const kept = history.slice(firstKept);
+    const carrier = latest === undefined ? -1 : latest.carrier - firstKept;
+    if (compaction.firstKeptStep !== undefined && carrier >= 0) {
+        kept[carrier] = fromStep(kept[carrier], compaction.firstKeptStep);
+    }
+    return [compactionMessage(history, firstKept, compaction, options.skills), ...kept];
+}
+/**
+ * The message the model reads in place of the summarized ones: the note, the
+ * skills, the user's newest images from before `firstKept`, then the summary.
+ */
+function compactionMessage(history, firstKept, compaction, available) {
     // 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 }];
+    const skills = skillsText(compaction.skills, available);
+    const note = compaction.firstKeptStep === undefined ? COMPACTION_NOTE : COMPACTION_STEPS_NOTE;
+    const parts = [{ type: "text", text: note }];
     if (skills !== undefined)
         parts.push({ type: "text", text: skills });
     const shown = new Set(userImages(history.slice(firstKept)).map(({ url }) => url));
@@ -99,7 +137,17 @@ export function applyCompaction(history, options = {}) {
         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)];
+    return { id: `compaction-${compaction.firstKeptMessageId}`, role: "user", parts };
+}
+/**
+ * `message` from its `step`th step on, counted from 0 by its `step-start` parts.
+ * A message with fewer steps than that is kept whole: sending a step twice, once
+ * summarized, is better than losing one.
+ */
+function fromStep(message, step) {
+    let seen = -1;
+    const start = message.parts.findIndex((part) => part.type === "step-start" && ++seen === step);
+    return start < 0 ? message : { ...message, parts: message.parts.slice(start) };
 }
 function skillsText(names, available) {
     if (names.length === 0)
@@ -123,35 +171,27 @@ function skillsText(names, available) {
 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)
+    const size = conversationTokens(history, previous) ?? estimate(messages, options);
+    if (size < threshold(options))
         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)
+    // The summary covers what it replaces and nothing it keeps: a kept message it
+    // also told of would read as done twice. Those are the messages before the
+    // kept tail, which ends a request the provider has cached.
+    const kept = keptTail(messages, await options.convert({ ...placeholder(options), firstKeptMessageId: history[firstKept].id }));
+    const end = Math.min(messages.length - kept, lastIndex(messages, ({ role }) => role === "user"));
+    if (end <= 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();
+    const summary = await summarize(messages.slice(0, end), options);
     if (summary === undefined)
         return { messages };
-    const kept = readSkills(history.slice(firstKept));
+    const keptSkills = readSkills(history.slice(firstKept));
     const skills = [
         ...new Set([...(previous?.compaction.skills ?? []), ...readSkills(history.slice(previous?.firstKept ?? 0, firstKept))]),
-    ].filter((name) => !kept.has(name));
+    ].filter((name) => !keptSkills.has(name));
     const compaction = {
         firstKeptMessageId: history[firstKept].id,
         summary,
@@ -165,29 +205,135 @@ export async function compactSparkHistory(options) {
     compaction.tokensAfter = estimate(compacted, options);
     return { messages: compacted, compaction };
 }
+/**
+ * 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 function createStepCompaction(options) {
+    const { history } = options;
+    const request = history[history.length - 1];
+    let previous = options.previous;
+    /** Steps of the turn already summarized. */
+    let summarizedSteps = 0;
+    return async (messages, last) => {
+        if (request?.role !== "user")
+            return messages;
+        const current = lastIndex(messages, ({ role }) => role === "user");
+        const lastStep = lastIndex(messages, ({ role }) => role === "assistant");
+        if (current < 0 || lastStep < current)
+            return messages;
+        // The provider's count for the step before, plus the results that came after it.
+        const size = last?.inputTokens !== undefined
+            ? last.inputTokens + (last.outputTokens ?? 0) + estimateMessagesTokens(messages.slice(lastStep + 1))
+            : estimate(messages, options);
+        const limit = threshold(options);
+        if (size < limit)
+            return messages;
+        // The turn's steps kept: the most recent that fit, whole, each an assistant
+        // message and the tool results after it.
+        const keepRecent = options.limits?.keepRecentTokens ?? COMPACTION_KEEP_RECENT_TOKENS;
+        let firstKept = messages.length;
+        for (let i = messages.length - 1; i > current; i -= 1) {
+            if (messages[i].role !== "assistant")
+                continue;
+            if (estimateMessagesTokens(messages.slice(i)) > keepRecent)
+                break;
+            firstKept = i;
+        }
+        const steps = summarizedSteps + messages.slice(current + 1, firstKept).filter(({ role }) => role === "assistant").length;
+        const compaction = (summary) => ({
+            firstKeptMessageId: request.id,
+            ...(steps > 0 ? { firstKeptStep: steps } : {}),
+            summary,
+            skills: summarizedSkills(messages, current, firstKept),
+            modelId: options.modelId,
+            tokensBefore: estimate(messages, options),
+            tokensAfter: 0,
+            createdAt: new Date().toISOString(),
+        });
+        const compacted = async (value) => [
+            ...(await options.convert([compactionMessage(history, history.length - 1, value, options.skills)])),
+            messages[current],
+            ...messages.slice(firstKept),
+        ];
+        // A summary costs a request; one that saves too little is not worth it.
+        const placeholder = await compacted(compaction("x".repeat(1_500 * 6)));
+        if (estimate(messages, options) - estimate(placeholder, options) < limit * COMPACTION_MIN_SAVED_RATIO)
+            return messages;
+        // Only the steps it replaces: a kept step it also told of would read as done
+        // twice. They end the request of the first kept step, which the provider has
+        // cached.
+        const summary = await summarize(messages.slice(0, firstKept), options);
+        if (summary === undefined)
+            return messages;
+        const next = compaction(summary);
+        const sent = await compacted(next);
+        next.tokensAfter = estimate(sent, options);
+        previous = next;
+        summarizedSteps = steps;
+        options.onCompaction(next);
+        return sent;
+    };
+    /** Skills read in what this compaction summarizes and not read again in what it keeps. */
+    function summarizedSkills(messages, current, firstKept) {
+        const from = previous === undefined ? 0 : Math.max(0, history.findIndex(({ id }) => id === previous.firstKeptMessageId));
+        const kept = modelSkills(messages.slice(firstKept));
+        return [
+            ...new Set([
+                ...(previous?.skills ?? []),
+                ...readSkills(history.slice(from, history.length - 1)),
+                ...modelSkills(messages.slice(current + 1, firstKept)),
+            ]),
+        ].filter((name) => !kept.has(name));
+    }
+}
+/** A compaction to measure with, before its summary is written. */
+function placeholder(options) {
+    return { summary: "", skills: [], modelId: options.modelId, tokensBefore: 0, tokensAfter: 0, createdAt: new Date(0).toISOString() };
+}
+/** How many of `messages`' last messages `compacted` still sends as they are. */
+function keptTail(messages, compacted) {
+    let kept = 0;
+    while (kept < messages.length &&
+        kept < compacted.length - 1 &&
+        JSON.stringify(messages[messages.length - 1 - kept]) === JSON.stringify(compacted[compacted.length - 1 - kept])) {
+        kept += 1;
+    }
+    return kept;
+}
 async function summarize(messages, options) {
+    options.onCompacting?.();
     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;
+    let summary;
+    try {
+        const result = await generateText({
+            model: options.model,
+            system: options.system,
+            tools: definitions,
+            toolChoice: "auto",
+            messages: [...messages, { role: "user", content: [{ type: "text", text: COMPACTION_PROMPT }] }],
+            providerOptions: options.providerOptions,
+            maxOutputTokens: options.maxOutputTokens,
+            abortSignal: options.signal,
+        });
+        const text = result.text.trim();
+        if (result.finishReason === "stop" && result.toolCalls.length === 0 && text.length > 0)
+            summary = text;
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+    }
+    options.signal?.throwIfAborted();
+    return summary;
+}
+function threshold(options) {
+    return Math.min(options.limits?.thresholdTokens ?? COMPACTION_THRESHOLD_TOKENS, options.contextWindow === undefined ? Infinity : options.contextWindow - (options.maxOutputTokens ?? 0));
 }
 function estimate(messages, options) {
     return estimateRequestTokens(messages, { system: options.system, tools: options.tools });
@@ -197,8 +343,8 @@ function estimate(messages, options) {
  * 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);
+function conversationTokens(history, latest) {
+    const step = lastStepTokens(history, latest);
     if (step === undefined)
         return undefined;
     return step.tokens + sum(history.slice(step.index + 1).map(uiMessageTokens));
@@ -206,14 +352,16 @@ function conversationTokens(history, carrier) {
 /**
  * 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.
+ * the model no longer reads. The compaction's own message counts from the part
+ * that records it on.
  */
-function lastStepTokens(history, carrier) {
-    for (let index = history.length - 1; index > carrier; index -= 1) {
+function lastStepTokens(history, latest) {
+    for (let index = history.length - 1; index >= (latest?.carrier ?? 0); index -= 1) {
         const message = history[index];
         if (message?.role !== "assistant")
             continue;
-        for (let i = message.parts.length - 1; i >= 0; i -= 1) {
+        const after = index === latest?.carrier ? latest.part : -1;
+        for (let i = message.parts.length - 1; i > after; i -= 1) {
             const part = message.parts[i];
             if (part?.type !== "data-step-metrics")
                 continue;
@@ -246,7 +394,7 @@ function cutIndex(history, floor, keepRecent) {
     }
     return cut;
 }
-/** Skills read successfully in these messages, in the order first read. */
+/** Skills read successfully in these stored messages, in the order first read. */
 function readSkills(messages) {
     const names = new Set();
     for (const message of messages) {
@@ -256,17 +404,33 @@ function readSkills(messages) {
             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))
+            addSkills(names, part.output?.skills);
+        }
+    }
+    return names;
+}
+/** Skills read successfully in these model messages, in the order first read. */
+function modelSkills(messages) {
+    const names = new Set();
+    for (const message of messages) {
+        if (message.role !== "tool")
+            continue;
+        for (const part of message.content) {
+            if (part.type !== "tool-result" || part.toolName !== "read_skill" || part.output.type !== "json")
                 continue;
-            for (const skill of skills) {
-                if (skill?.ok === true && typeof skill.name === "string")
-                    names.add(skill.name);
-            }
+            addSkills(names, part.output.value?.skills);
         }
     }
     return names;
 }
+function addSkills(names, skills) {
+    if (!Array.isArray(skills))
+        return;
+    for (const skill of skills) {
+        if (skill?.ok === true && typeof skill.name === "string")
+            names.add(skill.name);
+    }
+}
 /** 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;

package/dist/context-window.d.ts

@@ -0,0 +1,23 @@
+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;
+/**
+ * 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:
+ * compaction then goes by its own threshold alone.
+ */
+export declare function contextWindowFor(modelId: string): number | undefined;
+/** The estimate for a list of messages. */
+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: {
+    system?: string;
+    tools?: Record<string, unknown>;
+}): number;

package/dist/context-window.js

@@ -0,0 +1,141 @@
+// A model's context window, and how much of it a request uses.
+//
+// Spark never cuts a request down to fit: compaction (./compaction.ts) is the one
+// thing that takes earlier messages out of what the model reads, and it decides
+// when with these numbers. A request that is still over the window after it 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), so dense JSON that tokenizes worse than prose is not underestimated.
+// Images count by number, never by their bytes. Where the provider has counted a
+// step already, compaction uses its count instead.
+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;
+/**
+ * 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:
+ * compaction then goes by its own threshold alone.
+ */
+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;
+}
+/** The estimate for a list of messages. */
+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);
+}
+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 "";
+    }
+}
+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;
+}

package/dist/generated/geometry-declarations.d.ts

@@ -1 +1 @@
-export declare const WOMP_GEOMETRY_DECLARATIONS = "declare const womp: { geometry: {\n\"read\": ((objectId: number) => Promise<{\n\"kind\": \"container\" | \"graph\";\n\"objectId\": number;\n\"title\": string;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"source\": null | string;\n\"instances\": Array<{\n\"instanceId\": number;\n\"objectIds\": Array<number>;\n\"params\": {\n[key: string]: number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n}>;\n\"diagnostics\": Array<string>;\n}>);\n\"write\": ((options: {\n\"objectId\": number;\n\"source\": string;\n}) => Promise<{\n\"status\": \"applied\" | \"rejected\";\n\"objectId\": number;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"affectedObjectIds\": Array<number>;\n\"diagnostics\": Array<string>;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";
+export declare const WOMP_GEOMETRY_DECLARATIONS = "declare const womp: { geometry: {\n\"read\": ((objectId: number) => Promise<{\n\"kind\": \"container\" | \"graph\";\n\"objectId\": number;\n\"title\": string;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"source\": null | string;\n\"transform\": null | {\n\"position\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"rotation\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"size\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"bounds\": null | {\n\"min\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"max\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"instances\": Array<{\n\"instanceId\": number;\n\"objectIds\": Array<number>;\n\"params\": {\n[key: string]: number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n}>;\n\"diagnostics\": Array<string>;\n}>);\n\"write\": ((options: {\n\"objectId\": number;\n\"source\": string;\n}) => Promise<{\n\"status\": \"applied\" | \"rejected\";\n\"objectId\": number;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"source\"?: undefined | string;\n\"transform\"?: undefined | null | {\n\"position\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"rotation\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"size\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"bounds\"?: undefined | null | {\n\"min\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"max\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"affectedObjectIds\": Array<number>;\n\"diagnostics\": Array<string>;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";

package/dist/generated/geometry-declarations.js

@@ -1,3 +1,3 @@
 // Generated by scripts/generate-skill-declarations.mjs.
 // prettier-ignore
-export const WOMP_GEOMETRY_DECLARATIONS = "declare const womp: { geometry: {\n\"read\": ((objectId: number) => Promise<{\n\"kind\": \"container\" | \"graph\";\n\"objectId\": number;\n\"title\": string;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"source\": null | string;\n\"instances\": Array<{\n\"instanceId\": number;\n\"objectIds\": Array<number>;\n\"params\": {\n[key: string]: number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n}>;\n\"diagnostics\": Array<string>;\n}>);\n\"write\": ((options: {\n\"objectId\": number;\n\"source\": string;\n}) => Promise<{\n\"status\": \"applied\" | \"rejected\";\n\"objectId\": number;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"affectedObjectIds\": Array<number>;\n\"diagnostics\": Array<string>;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";
+export const WOMP_GEOMETRY_DECLARATIONS = "declare const womp: { geometry: {\n\"read\": ((objectId: number) => Promise<{\n\"kind\": \"container\" | \"graph\";\n\"objectId\": number;\n\"title\": string;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"source\": null | string;\n\"transform\": null | {\n\"position\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"rotation\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"size\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"bounds\": null | {\n\"min\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"max\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"instances\": Array<{\n\"instanceId\": number;\n\"objectIds\": Array<number>;\n\"params\": {\n[key: string]: number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n}>;\n\"diagnostics\": Array<string>;\n}>);\n\"write\": ((options: {\n\"objectId\": number;\n\"source\": string;\n}) => Promise<{\n\"status\": \"applied\" | \"rejected\";\n\"objectId\": number;\n\"graphId\"?: undefined | number;\n\"instanceId\"?: undefined | number;\n\"source\"?: undefined | string;\n\"transform\"?: undefined | null | {\n\"position\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"rotation\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"size\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"bounds\"?: undefined | null | {\n\"min\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"max\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"affectedObjectIds\": Array<number>;\n\"diagnostics\": Array<string>;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";

package/dist/geometry/backendRegistry.d.ts

@@ -31,6 +31,7 @@ export type GraphExt = {
     nodes: Record<string, {
         name?: string;
         position?: number[];
+        flowirSymbol?: string;
         [key: string]: unknown;
     }>;
     [key: string]: unknown;