@womp/spark-agent 6.5.0 → 8.0.0

package/CHANGELOG.md

@@ -4,6 +4,92 @@ Notable changes to `@womp/spark-agent`, newest first. Versions follow
 [Semantic Versioning](https://semver.org/). Add an entry with each version bump; describe what
 changed for hosts and users, and how to migrate across breaking changes.
 
+## 8.0.0 — 2026-10-12
+
+Geometry Nodes moves to FlowIR 0.5.0. The dialect is FlowIR's strict, flat format, the
+`geometry-nodes-reference` skill is the prompt FlowIR renders from it, and the names the agent
+writes come back when it reads the graph, so a follow-up edit can refer to them.
+
+### Changed
+
+- `@womp/flowir` is 0.5.0. The geometry dialect declares its types, enum ports, casts and the
+  `Geometry` program output. `param` and `const` declare Int, Float and Vec3; other types are
+  rejected instead of being dropped when the graph is written.
+- A write stores each statement's name in `graphExt.nodes[id].flowirSymbol`, and a read returns
+  those names. Graphs written without stored names read back as before.
+- Compiler diagnostics are formatted by FlowIR, within the existing count and size bounds.
+- `geometry-nodes` (skill version 6) and `geometry-nodes-reference` (version 3) are rewritten
+  for the new dialect.
+
+### Added
+
+- `GeometryTarget.transform` and `GeometryTarget.bounds`: the target's position, rotation and
+  size relative to its parent, and its world-space extent, in project units. Both are `null`
+  where they do not apply.
+- An applied `GeometryWriteResult` also carries the committed `source`, `transform` and
+  `bounds`, read back from the scene.
+
+### Removed
+
+- `loadGeoNodesDialect` from `@womp/spark-agent/geometry`.
+
+### Migration
+
+- `geometryReference()` returns a string instead of `{ rules, catalog }`, and
+  `createGeometryCapability` takes that string. Pass `geometryReference()` through unchanged.
+- A host that builds `GeometryTarget` values itself, rather than through
+  `createSdkGeometryHost`, must set `transform` and `bounds` (`null` when unknown).
+
+## 7.0.0 — 2026-10-12
+
+Compaction is now the only thing that takes messages out of what the model reads, and it can run
+before any step of a turn, not just the first. The per-step trimming that replaced earlier images,
+tool results and whole turns with placeholder text is gone: it rewrote the start of the prompt
+whenever it fired, which threw away the provider's prompt cache on every later step. A request
+that is still over the model's context window after compaction is sent as it is and fails with
+the provider's error.
+
+### Changed
+
+- A run given `history` checks the conversation before every step. Once it reaches the compaction
+  threshold during a turn, everything before the current user message and the turn's steps before
+  its most recent `COMPACTION_KEEP_RECENT_TOKENS` are summarized; the user's message is kept
+  verbatim. The summary request is the first kept step's request plus one instruction, so it is
+  served from the prompt cache. A compaction that would save less than
+  `COMPACTION_MIN_SAVED_RATIO` of the threshold is skipped, so a turn whose own message is over
+  the threshold does not summarize on every step.
+- A summary covers only the messages it replaces, before a turn as well as during one. It used to
+  tell of the kept messages too, and the model, reading them again after it, took that work for
+  done twice.
+- `SparkCompaction.firstKeptStep` records a compaction written during its turn: the first step of
+  the recording assistant message the model still reads. `applyCompaction` (and so
+  `convertSparkMessages`) leaves the earlier steps out, so the next turn rebuilds exactly the
+  messages the last step was sent. A run may now record more than one `data-compaction` part; the
+  latest is the one in force. Hosts must store and reload message parts in order, including
+  `step-start`.
+- When to compact is measured from the provider's count for the conversation's last step after the
+  latest compaction, including the steps of the message that recorded it.
+
+### Added
+
+- `applyCompaction` and `latestCompaction` are exported from the package root, so a host can tell
+  which stored messages, and which of their images, the model will be sent.
+
+### Removed
+
+- `fitMessagesToContext`, `ContextBudgetOptions`, `ContextBudgetReport`, `ContextBudgetResult`,
+  `TRIM_TRIGGER_RATIO`, `TRIM_TARGET_RATIO`, `SMALL_TOOL_OUTPUT_TOKENS`,
+  `PROTECTED_CURRENT_STEPS` and the `OMITTED_HISTORY_TEXT`, `OMITTED_HISTORY_IMAGE_TEXT` and
+  `OMITTED_TOOL_OUTPUT_TEXT` notes.
+- `SparkAgentOptions.onContextBudget`.
+
+### Migration
+
+- Remove any `onContextBudget` handler and any host-side trimming. Pass `history` to have long
+  conversations compacted; a run given `messages` is sent exactly what it is given.
+- `contextWindowFor`, `estimateMessagesTokens`, `estimateRequestTokens`, `CHARS_PER_TOKEN` and
+  `IMAGE_TOKENS` are unchanged; they now live in `src/context-window.ts`.
+
 ## 6.5.0 — 2026-10-12
 
 The agent proposes a goal during its turn, instead of the host asking a separate model call to

package/README.md

@@ -75,9 +75,11 @@ The default model-step limit is 100; reaching it returns `status: "incomplete"`,
 restart automatically to bypass it. A generation that ends on any other non-`stop` reason fails the
 run with the unified and provider finish reasons in its error and diagnostics.
 
-Before each model step, Spark trims older images, large tool results, and whole earlier turns to
-keep the request inside the model's context window. The latest user message and the most recent
-steps are never trimmed.
+When a run is given its stored `history`, Spark compacts it before any model step once the
+conversation reaches the compaction threshold: earlier turns, and earlier steps of a long turn, are
+replaced by a summary recorded on the run's message as a `data-compaction` part. Nothing else
+shortens a request; one that is still over the model's context window fails with the provider's
+error.
 
 ### Artifacts
 
@@ -355,7 +357,8 @@ features, patch for backward-compatible fixes.
 
 - `src/agent.ts` — AI SDK stream and Spark tool orchestration
 - `src/prompt.ts` — shared system prompt
-- `src/context-budget.ts` — per-step context-window trimming
+- `src/compaction.ts` — conversation compaction before each model step
+- `src/context-window.ts` — model context windows and request size estimates
 - `src/ui.ts` — browser-safe protocol types and validation schemas
 - `src/client.ts` — durable `ChatTransport` implementation
 - `src/server/` — service, storage contracts, Express adapter, artifacts, and standalone composition

package/dist/agent.d.ts

@@ -2,7 +2,6 @@ import { streamText, type LanguageModel, type ModelMessage } from "ai";
 import { type SparkGoalOffer, type SparkPersistence } from "./agent-tools.js";
 import type { SparkArtifactResolver, SparkCapabilities } from "./capabilities.js";
 import type { JavaScriptExecutor } from "./executor.js";
-import { type ContextBudgetReport } from "./context-budget.js";
 import { type SparkCompactionLimits } from "./compaction.js";
 import type { SparkUIMessage, SparkUIMessageChunk } from "./ui.js";
 export type SparkAgentResult = {
@@ -17,8 +16,8 @@ export type SparkAgentOptions = {
     messages?: ModelMessage[];
     /**
      * The stored conversation. It is converted with `convertSparkMessages`, and
-     * compacted first once it is long enough (./compaction.ts); the new
-     * compaction is written to this run's message as a `data-compaction` part.
+     * compacted before any step once it is long enough (./compaction.ts); each
+     * new compaction is written to this run's message as a `data-compaction` part.
      */
     history?: SparkUIMessage[];
     model: LanguageModel;
@@ -38,12 +37,10 @@ export type SparkAgentOptions = {
     /** Gives the model `propose_goal`; absent, it has no way to offer a goal. */
     proposeGoal?: SparkGoalOffer;
     prepareMessages?(messages: ModelMessage[]): Promise<ModelMessage[]>;
-    /** The model's context window. Absent: `contextWindowFor(modelId)`. */
+    /** The model's context window, which caps when `history` is compacted. Absent: `contextWindowFor(modelId)`. */
     contextWindow?: number;
     /** When `history` is compacted. Absent: the defaults in ./compaction.ts. */
     compaction?: SparkCompactionLimits;
-    /** Called when a step's messages had to be trimmed to fit, or still do not fit. */
-    onContextBudget?(report: ContextBudgetReport): void;
 };
 export type SparkAgentRun = {
     stream: ReadableStream<SparkUIMessageChunk>;

package/dist/agent.js

@@ -4,8 +4,8 @@ import { createUIMessageStream, stepCountIs, streamText, } from "ai";
 import { createSparkTools } from "./agent-tools.js";
 import { sparkSystemPrompt } from "./prompt.js";
 import { calculateStepCost } from "./pricing.js";
-import { contextWindowFor, fitMessagesToContext } from "./context-budget.js";
-import { compactSparkHistory } from "./compaction.js";
+import { contextWindowFor } from "./context-window.js";
+import { compactSparkHistory, createStepCompaction, latestCompaction } from "./compaction.js";
 import { convertSparkMessages } from "./model-history.js";
 function errorMessage(error) {
     return sparkErrorDiagnostics(error).message;
@@ -131,11 +131,14 @@ export function runSparkAgent(options) {
                 });
                 const readSystem = () => sparkSystemPrompt(options.capabilities.skills, options.instructions);
                 let messages = options.messages ?? [];
+                // Compaction before each later step; only for a stored conversation,
+                // where the compaction can be recorded.
+                let compactStep;
                 if (options.history !== undefined) {
                     const history = options.history;
-                    const compacted = await compactSparkHistory({
-                        history,
-                        convert: (compaction) => convertSparkMessages(history, tools, { compaction, skills: options.capabilities.skills }),
+                    const skills = options.capabilities.skills;
+                    let compactions = 0;
+                    const summaryOptions = {
                         model: options.model,
                         modelId: options.modelId,
                         system: readSystem(),
@@ -149,12 +152,29 @@ export function runSparkAgent(options) {
                             type: "data-run-status",
                             data: { runId: options.runId, status: "running", label: "Making room so we can keep talking" },
                         }),
+                    };
+                    const record = (compaction) => writer.write({
+                        type: "data-compaction",
+                        id: `compaction-${options.messageId}${compactions++ === 0 ? "" : `-${compactions}`}`,
+                        data: compaction,
+                    });
+                    const compacted = await compactSparkHistory({
+                        ...summaryOptions,
+                        history,
+                        convert: (compaction) => convertSparkMessages(history, tools, { compaction, skills }),
                     });
                     messages = compacted.messages;
-                    if (compacted.compaction !== undefined) {
-                        writer.write({ type: "data-compaction", id: `compaction-${options.messageId}`, data: compacted.compaction });
-                    }
+                    if (compacted.compaction !== undefined)
+                        record(compacted.compaction);
                     controller.signal.throwIfAborted();
+                    compactStep = createStepCompaction({
+                        ...summaryOptions,
+                        history,
+                        previous: compacted.compaction ?? latestCompaction(history)?.compaction,
+                        skills,
+                        convert: (stored) => convertSparkMessages(stored, tools, { skills }),
+                        onCompaction: record,
+                    });
                 }
                 const generation = streamText({
                     model: options.model,
@@ -166,25 +186,23 @@ export function runSparkAgent(options) {
                     stopWhen: stepCountIs(maxSteps),
                     maxOutputTokens: options.maxOutputTokens,
                     providerOptions: options.providerOptions,
-                    prepareStep: async ({ messages }) => {
+                    prepareStep: async ({ messages, steps }) => {
                         controller.signal.throwIfAborted();
-                        const prepared = options.prepareMessages === undefined
+                        // The first step was compacted above, before the request was built.
+                        // The AI SDK sends each later step what the one before it was sent,
+                        // so a compaction here holds for the rest of the turn.
+                        const last = steps.at(-1)?.usage;
+                        const current = compactStep === undefined || steps.length === 0
                             ? messages
-                            : await options.prepareMessages(messages);
+                            : await compactStep(messages, { inputTokens: last?.inputTokens, outputTokens: last?.outputTokens });
+                        controller.signal.throwIfAborted();
+                        const prepared = options.prepareMessages === undefined
+                            ? current
+                            : await options.prepareMessages(current);
                         controller.signal.throwIfAborted();
-                        const system = readSystem();
-                        // After the host's own preparation, so what is measured is what is sent.
-                        const fitted = fitMessagesToContext(prepared, {
-                            contextWindow,
-                            maxOutputTokens: options.maxOutputTokens,
-                            system,
-                            tools,
-                        });
-                        if (fitted.report && (fitted.messages !== prepared || !fitted.report.fits))
-                            options.onContextBudget?.(fitted.report);
                         return {
-                            system,
-                            messages: fitted.messages,
+                            system: readSystem(),
+                            messages: prepared,
                         };
                     },
                     onError: ({ error }) => {

package/dist/capabilities/geometry.d.ts

@@ -1,9 +1,19 @@
 import type { SparkCapability, SparkInvocationContext } from "../capabilities.js";
-export type GeometryParamValue = number | {
+export type GeometryVector = {
     x: number;
     y: number;
     z: number;
 };
+export type GeometryParamValue = number | GeometryVector;
+export type GeometryTransform = {
+    position: GeometryVector;
+    rotation: GeometryVector;
+    size: GeometryVector;
+};
+export type GeometryBounds = {
+    min: GeometryVector;
+    max: GeometryVector;
+};
 export type GeometryInstance = {
     instanceId: number;
     objectIds: number[];
@@ -16,6 +26,8 @@ export type GeometryTarget = {
     graphId?: number;
     instanceId?: number;
     source: string | null;
+    transform: GeometryTransform | null;
+    bounds: GeometryBounds | null;
     instances: GeometryInstance[];
     diagnostics: string[];
 };
@@ -28,6 +40,9 @@ export type GeometryWriteResult = {
     objectId: number;
     graphId?: number;
     instanceId?: number;
+    source?: string;
+    transform?: GeometryTransform | null;
+    bounds?: GeometryBounds | null;
     affectedObjectIds: number[];
     diagnostics: string[];
 };
@@ -39,7 +54,4 @@ export interface GeometryHost {
     read(objectId: number, context: SparkInvocationContext): Promise<GeometryTarget>;
     write(options: GeometryWrite, context: SparkInvocationContext): Promise<GeometryWriteResult>;
 }
-export declare function createGeometryCapability(host: GeometryHost, reference: {
-    rules: string;
-    catalog: string;
-}): SparkCapability<WompGeometryApi>;
+export declare function createGeometryCapability(host: GeometryHost, reference: string): SparkCapability<WompGeometryApi>;

package/dist/capabilities/geometry.js

@@ -12,23 +12,22 @@ export function createGeometryCapability(host, reference) {
         skills: [
             {
                 name: "geometry-nodes",
-                version: "5",
+                version: "6",
                 description: "Create and edit visual Geometry Nodes graphs with adjustable parameters and animation.",
                 instructions: `Use womp.geometry for requested Geometry Nodes, parametric organic/procedural geometry, or animation.
 Keep follow-up edits to an existing Geometry Nodes object in its graph, preserving its adjustable parameters and instances.
-Read the target after any scene edit this build needs. read(0) reads the scene root as a creation container.
+An Area is a scene object that holds one Geometry Nodes graph; a Group is a container. read(0) reads the scene root as a creation container.
+read returns the target's FlowIR source, its instances with their parameter overrides (in FlowIR units), its transform and its bounds. transform is position, rotation and size relative to the parent, in project units as the scene API reports them; an Area's size is a dimensionless scale, and the scene root's transform is null. bounds is the world-space extent in project units, null unless the target is a top-level Area whose graph renders geometry. Read the target again after another scene edit changes it.
+If source is null and diagnostics is non-empty, the existing graph cannot be edited without loss. Explain the limitation; never treat it as empty or create a replacement to bypass the refusal.
+Read geometry-nodes-reference before writing source. source is the complete FlowIR text for the target; JavaScript calls execute JavaScript, and source is a FlowIR string, not JavaScript or JSON.
 write updates an existing shared graph, attaches a new graph to an Area without one, or creates a new Area beneath the root/Group target. Use the returned objectId for follow-up edits.
-Read geometry-nodes-reference before writing source. Supply the complete FlowIR text after inspecting the target. JavaScript calls execute JavaScript; source is a FlowIR string, not JavaScript or JSON.
-Inspect the current target before replacing its graph; preserve unrelated geometry and parameter overrides.
-If source is null and diagnostics are present, the existing graph cannot be edited without loss. Explain the limitation; never treat it as empty or create a replacement to bypass the refusal.
-Preserve unrelated statements, parameter names, and FlowIR node IDs from the read. Shared graph edits affect all listed instances; report the affected objects. Valid overrides migrate by parameter name and type. Removed or type-changed parameters return to graph defaults and are reported.
+Preserve unrelated statements, parameter names, FlowIR node IDs and parameter overrides from the read. Shared graph edits affect all listed instances; report the affected objects. Valid overrides migrate by parameter name and type. Removed or type-changed parameters return to graph defaults and are reported.
 Use min/max/step for naturally bounded parameters and omit ranges for free-form positions/rotations. Meaningful parameter names become editor labels. Do not invent label fields.
 SetMaterial assigns one scene material to every primitive it receives. Its Material input is a scene material ID, not a color; 0 selects the scene default material.
-Obtain that ID from the scene-editing skill inside one scene.access, where those lookups live: materialList with materialGetName and materialGetColor to reuse an existing material, materialCreate with materialSetColor and materialSetName for a new one, or listSuperMaterials with materialImport for a library material. Prefer reusing a material that already matches the request over creating another, and do not recolor a shared material unless every object using it should change.
-Create or import the material inside scene.access before writing the geometry target, all within one JavaScript call. Each call has a fresh scope and cannot read an earlier call's variables.
-Positions and sizes are millimetres; Boolean Blend uses the conversion in geometry-nodes-reference. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
+Obtain that ID from the scene-editing skill inside womp.scene.access, in the same JavaScript call as the write and before it: materialList with materialGetName and materialGetColor to reuse an existing material, materialCreate with materialSetColor and materialSetName for a new one, or listSuperMaterials with materialImport for a library material. Prefer reusing a material that already matches the request over creating another, and do not recolor a shared material unless every object using it should change.
+FlowIR positions and sizes are millimetres; Boolean Blend uses the conversion in geometry-nodes-reference. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
 On compiler errors, repair the source in this same conversation and retry with a fresh read. A rejected write made no change. Committed/unknown effects remain in execution receipts even if a later call fails; inspect before retrying.
-After applying, read the returned object and use the scene screenshot API with emitImage to inspect the applied result.`,
+When status is "applied", the write result also holds the committed target read back from the scene: source, transform and bounds. Print it; it verifies the graph, so do not read the target again to check it. When the target's latest source is already printed in this conversation, make its next edit in a single call: read, replace and write. Use the scene screenshot API with emitImage to inspect the applied result.`,
                 declarations: WOMP_GEOMETRY_DECLARATIONS,
                 examples: [
                     "const target = await womp.geometry.read(objectId); print(target);",
@@ -38,9 +37,9 @@ After applying, read the returned object and use the scene screenshot API with e
             },
             {
                 name: "geometry-nodes-reference",
-                version: "2",
+                version: "3",
                 description: "FlowIR syntax, types, enums, and supported Geometry Nodes catalog; read before writing a graph.",
-                instructions: `${reference.rules}\n${reference.catalog}`,
+                instructions: reference,
                 declarations: "",
                 examples: [],
             },

package/dist/compaction.d.ts

@@ -3,10 +3,12 @@ import type { SparkSkill } from "./capabilities.js";
 import { type SparkCompaction, type SparkUIMessage } from "./ui.js";
 /** Compact once the conversation reaches this many tokens. */
 export declare const COMPACTION_THRESHOLD_TOKENS = 256000;
-/** Recent whole turns kept verbatim, up to this many tokens, besides the current turn. */
+/** Recent whole turns, or recent steps of the current turn, kept verbatim, up to this many tokens. */
 export declare const COMPACTION_KEEP_RECENT_TOKENS = 16000;
 /** The user's newest images from the summarized messages that the summary message carries. */
 export declare const COMPACTION_USER_IMAGES = 4;
+/** A compaction during a turn saves at least this share of the threshold, or is not made. */
+export declare const COMPACTION_MIN_SAVED_RATIO = 0.25;
 /**
  * When a conversation is compacted, for a host that exercises compaction
  * without filling a production-sized conversation, such as local development.
@@ -19,27 +21,28 @@ export type SparkCompactionLimits = {
 };
 export declare const COMPACTION_PROMPT = "Write a checkpoint summary of this conversation so far. It replaces the earlier messages in your context, so the work must be able to continue from it alone. Reply with the summary only, without calling tools. This request is not part of the conversation: leave it out of the summary.\nIf the conversation begins with an earlier summary, carry its content forward and update it.\nUse these sections:\n## Goal\n## User preferences and constraints\n## Decisions and current scene state (objects with their names and IDs)\n## Done\n## Open and next steps\n## Artifacts and images (each artifact ID, and what each image the user attached shows)\n## Errors and approaches to avoid\nKeep exact names, IDs, numbers and the user's own wording for requirements. Stay under 1,500 words.";
 export declare const COMPACTION_NOTE = "[Earlier messages in this conversation were replaced by the summary below. The scene itself is unchanged; inspect it for its exact state.]";
+export declare const COMPACTION_STEPS_NOTE = "[Earlier messages in this conversation, and the earlier steps of your work on the message after this one, were replaced by the summary below. The scene itself is unchanged; inspect it for its exact state.]";
 /** The latest compaction in the conversation whose kept message is still in it. */
 export declare function latestCompaction(history: SparkUIMessage[]): {
     compaction: SparkCompaction;
     carrier: number;
+    part: number;
     firstKept: number;
 } | undefined;
 /**
  * The conversation as the model reads it: the messages before the compaction's
  * kept message replaced by its summary, with the newest COMPACTION_USER_IMAGES
- * images the user attached to them. `compaction` defaults to the latest one in `history`; `skills` are the
- * host's, to send the current text of the skills it names. Without a
- * compaction, `history` is returned as it is.
+ * images the user attached to them, and -- for the latest compaction, when it was
+ * written during its turn -- the recording message's steps before
+ * `firstKeptStep` left out with them. `compaction` defaults to the latest one in
+ * `history`; `skills` are the host's, to send the current text of the skills it
+ * names. Without a compaction, `history` is returned as it is.
  */
 export declare function applyCompaction(history: SparkUIMessage[], options?: {
     compaction?: SparkCompaction;
     skills?: readonly SparkSkill[];
 }): SparkUIMessage[];
-export type CompactSparkHistoryOptions = {
-    history: SparkUIMessage[];
-    /** `history` as model messages, with `compaction` applied when given. */
-    convert(compaction?: SparkCompaction): Promise<ModelMessage[]>;
+type SummaryOptions = {
     model: LanguageModel;
     modelId: string;
     system: string;
@@ -53,6 +56,11 @@ export type CompactSparkHistoryOptions = {
     onCompacting?(): void;
     limits?: SparkCompactionLimits;
 };
+export type CompactSparkHistoryOptions = SummaryOptions & {
+    history: SparkUIMessage[];
+    /** `history` as model messages, with `compaction` applied when given. */
+    convert(compaction?: SparkCompaction): Promise<ModelMessage[]>;
+};
 /**
  * The turn's model messages, compacted first when the conversation has reached
  * the threshold. `compaction` is the new one, for the host to record; it is
@@ -62,3 +70,28 @@ export declare function compactSparkHistory(options: CompactSparkHistoryOptions)
     messages: ModelMessage[];
     compaction?: SparkCompaction;
 }>;
+export type StepCompactionOptions = SummaryOptions & {
+    /** The stored conversation, ending with the current user message. */
+    history: SparkUIMessage[];
+    /** The compaction the turn started from: the one written before its first step, else `history`'s latest. */
+    previous?: SparkCompaction;
+    /** The host's skills, for the summary message's skill text. */
+    skills?: readonly SparkSkill[];
+    /** Stored messages as model messages. */
+    convert(messages: SparkUIMessage[]): Promise<ModelMessage[]>;
+    /** A new compaction, for the host to record on the turn's message. */
+    onCompaction(compaction: SparkCompaction): void;
+};
+/** What the provider reported for the step before. */
+export type StepUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+};
+/**
+ * Compaction before each later step of a turn. Returns the step's messages,
+ * compacted when the conversation has reached the threshold; the AI SDK carries
+ * what a step was sent into the next, so a compaction holds for the rest of the
+ * turn.
+ */
+export declare function createStepCompaction(options: StepCompactionOptions): (messages: ModelMessage[], last?: StepUsage) => Promise<ModelMessage[]>;
+export {};