@womp/spark-agent 6.3.0 → 6.5.0

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/goals.d.ts

@@ -22,7 +22,7 @@ export type SparkGoalTry = {
     /** In the order of the goal's conditions; a condition left to the user has no result. */
     conditions: Pick<SparkGoalCondition, "met" | "reason">[];
 };
-/** The conditions read from a user message, for the user to confirm before a goal starts. */
+/** The goal the agent proposes for a request, for the user to confirm before it starts. */
 export declare const sparkGoalProposalSchema: z.ZodObject<{
     title: z.ZodString;
     conditions: z.ZodArray<z.ZodObject<{
@@ -31,6 +31,43 @@ export declare const sparkGoalProposalSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SparkGoalProposal = z.infer<typeof sparkGoalProposalSchema>;
+/**
+ * How the user answered a proposed goal: run it with these caps, try the request
+ * once, or nothing in the time the host waits.
+ */
+export declare const sparkGoalDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    creditBudget: z.ZodOptional<z.ZodNumber>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodLiteral<"goal">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"once">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"unanswered">;
+}, z.core.$strip>], "kind">;
+export type SparkGoalDecision = z.infer<typeof sparkGoalDecisionSchema>;
+/** What became of a proposal, as the agent is told: `active` when a goal was already running. */
+export declare const SPARK_GOAL_OUTCOMES: readonly ["started", "declined", "unanswered", "active"];
+export type SparkGoalOutcome = (typeof SPARK_GOAL_OUTCOMES)[number];
+/**
+ * A proposal as its message stores it: the `propose_goal` call that made it, and
+ * its outcome once there is one. Without an outcome it is waiting for the user
+ * while its run is, and was left unanswered once that run has ended.
+ */
+export declare const sparkGoalProposalPartSchema: z.ZodObject<{
+    title: z.ZodString;
+    conditions: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        measurable: z.ZodBoolean;
+    }, z.core.$strip>>;
+    toolCallId: z.ZodString;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        unanswered: "unanswered";
+        started: "started";
+        declined: "declined";
+    }>>;
+}, z.core.$strip>;
+export type SparkGoalProposalPart = z.infer<typeof sparkGoalProposalPartSchema>;
 /** The caps a goal confirmation offers before the user changes them. */
 export declare const GOAL_CONFIRMATION_DEFAULTS: {
     readonly tries: 5;
@@ -61,20 +98,15 @@ export type SparkGoal = {
     runId?: string;
 };
 export declare const sparkGoalCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    creditBudget: z.ZodOptional<z.ZodNumber>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
     action: z.ZodLiteral<"set">;
     objective: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-    conditions: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        text: z.ZodString;
-        measurable: z.ZodBoolean;
-    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
     creditBudget: z.ZodOptional<z.ZodNumber>;
     maxTurns: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"update_budget">;
     goalId: z.ZodString;
-    creditBudget: z.ZodOptional<z.ZodNumber>;
-    maxTurns: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodEnum<{
         status: "status";

package/dist/goals.js

@@ -11,10 +11,34 @@ export const sparkGoalConditionSchema = z.object({
      */
     measurable: z.boolean(),
 });
-/** The conditions read from a user message, for the user to confirm before a goal starts. */
+const goalCaps = {
+    creditBudget: z.number().int().positive().max(1_000_000_000).optional(),
+    maxTurns: z.number().int().min(1).max(100).optional(),
+};
+/** The goal the agent proposes for a request, for the user to confirm before it starts. */
 export const sparkGoalProposalSchema = z.object({
     title: z.string().trim().min(1).max(80),
-    conditions: z.array(sparkGoalConditionSchema).max(MAX_GOAL_CONDITIONS),
+    conditions: z.array(sparkGoalConditionSchema).min(1).max(MAX_GOAL_CONDITIONS),
+});
+/**
+ * How the user answered a proposed goal: run it with these caps, try the request
+ * once, or nothing in the time the host waits.
+ */
+export const sparkGoalDecisionSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("goal"), ...goalCaps }),
+    z.object({ kind: z.literal("once") }),
+    z.object({ kind: z.literal("unanswered") }),
+]);
+/** What became of a proposal, as the agent is told: `active` when a goal was already running. */
+export const SPARK_GOAL_OUTCOMES = ["started", "declined", "unanswered", "active"];
+/**
+ * A proposal as its message stores it: the `propose_goal` call that made it, and
+ * its outcome once there is one. Without an outcome it is waiting for the user
+ * while its run is, and was left unanswered once that run has ended.
+ */
+export const sparkGoalProposalPartSchema = sparkGoalProposalSchema.extend({
+    toolCallId: z.string().min(1),
+    outcome: z.enum(SPARK_GOAL_OUTCOMES).optional(),
 });
 /** The caps a goal confirmation offers before the user changes them. */
 export const GOAL_CONFIRMATION_DEFAULTS = { tries: 5, credits: 2_000 };
@@ -22,17 +46,13 @@ export const sparkGoalCommandSchema = z.discriminatedUnion("action", [
     z.object({
         action: z.literal("set"),
         objective: z.string().trim().min(1).max(MAX_GOAL_LENGTH),
-        title: sparkGoalProposalSchema.shape.title.optional(),
-        conditions: sparkGoalProposalSchema.shape.conditions.min(1).optional(),
-        creditBudget: z.number().int().positive().max(1_000_000_000).optional(),
-        maxTurns: z.number().int().min(1).max(100).optional(),
+        ...goalCaps,
     }),
     // Raises or lowers a goal's caps; at least one of them.
     z.object({
         action: z.literal("update_budget"),
         goalId: z.string().min(1),
-        creditBudget: z.number().int().positive().max(1_000_000_000).optional(),
-        maxTurns: z.number().int().min(1).max(100).optional(),
+        ...goalCaps,
     }),
     z.object({ action: z.enum(["status", "pause", "resume", "clear"]) }),
 ]);

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)
@@ -22,19 +23,15 @@ async function liveInput(tools, part) {
     const validated = await asSchema(tool.inputSchema).validate?.(input);
     return validated?.success ? { ...part, input: validated.value } : part;
 }
-/** How the worker reads the conditions the user confirmed for the goal a message starts. */
-function goalConditionsText({ conditions }) {
-    const list = (measurable) => conditions.filter((condition) => condition.measurable === measurable).map(({ text }) => `\n- ${text}`).join("");
-    const measured = list(true);
-    const reviewed = list(false);
-    return "[The user confirmed this request as a goal. Keep working until it is met; do not ask whether to continue."
-        + (measured ? `\nConditions an independent check will verify. Verify each with concrete tool results before claiming completion:${measured}` : "")
-        + (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();
@@ -63,10 +60,6 @@ export async function convertSparkMessages(messages, tools) {
     return convertToModelMessages(history, {
         tools,
         convertDataPart: (part) => {
-            if (part.type === "data-goal") {
-                const goal = sparkDataPartSchemas.goal.safeParse(part.data);
-                return goal.success ? { type: "text", text: goalConditionsText(goal.data) } : undefined;
-            }
             if (part.type !== "data-selection")
                 return undefined;
             const selection = sparkDataPartSchemas.selection.safeParse(part.data);

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,28 +1,21 @@
-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,
+                proposeGoal: context.proposeGoal,
             });
             return { stream: run.stream, result: run.result.finally(() => host.dispose()) };
         }

package/dist/server/express.js

@@ -100,15 +100,6 @@ export function createSparkAgentRouter(options) {
         const result = await options.service.goalCommand(ownerId, request.params.conversationId, body.command, body.settings, body.message);
         response.status(result.run ? 202 : 200).json(result);
     });
-    router.post("/conversations/:conversationId/goal/proposal", async (request, response) => {
-        const ownerId = await resolveOwnerId(request);
-        const body = z.object({ message: messageSchema, settings: settingsSchema }).parse(request.body);
-        const abortController = new AbortController();
-        response.on("close", () => { if (!response.writableEnded)
-            abortController.abort(); });
-        const proposal = await options.service.proposeGoal(ownerId, request.params.conversationId, body.message, body.settings, abortController.signal);
-        response.json({ proposal });
-    });
     router.get("/conversations/:conversationId/active-run", async (request, response) => {
         const ownerId = await resolveOwnerId(request);
         const run = await options.service.getActiveRun(ownerId, request.params.conversationId);

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;