Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(composer): compact transcript + soft-cap so long compose runs finish
Matt Kissingerd09e2c9e53fa
diff --git a/src/__tests__/composer-compaction.test.ts b/src/__tests__/composer-compaction.test.tsnew file mode 100644index 00000000..01686937--- /dev/null+++ b/src/__tests__/composer-compaction.test.ts@@ -0,0 +1,153 @@+/**+ * SceneCompactionManager tests — the composer's context compaction.+ *+ * The scene state lives in the PlacementModel, so the transcript is disposable: once+ * it bloats, `reduce()` collapses the WHOLE history to one synthetic user message+ * carrying the current program + a finalize directive. These tests pin the collapse+ * (always a single valid message, no dangling tool pairs), the message contents+ * (program, counts, goal, finalize nudge), and the message-count trigger wired in+ * `initAgent`.+ */+import { describe, expect, test } from 'bun:test';+import { BeforeModelCallEvent, Message, TextBlock } from '@strands-agents/sdk';++import { type CatalogEntry, PlacementModel, serialize } from '../composer';+import { SceneCompactionManager, type SceneCompactionInfo } from '../composer/agent';++const asset = (id: string, w = 2, h = 3, d = 2): CatalogEntry => ({+ generationId: id,+ bbox: { min: [-w / 2, 0, -d / 2], max: [w / 2, h, d / 2] },+ name: id,+});++/** A small scene with a couple of placements (so serialize() is non-trivial). */+function scene(): PlacementModel {+ const m = new PlacementModel('Compaction Test', {+ seed: 7,+ catalog: [asset('temple', 6, 8, 6), asset('obelisk', 1, 5, 1), asset('palm', 1, 4, 1)],+ });+ m.addPlace('temple', { at: [0, 0], face: 'center', role: 'hero' });+ m.addPlace('obelisk', { at: [12, 0], face: 'center', role: 'support' });+ return m;+}++const msg = (role: 'user' | 'assistant', text: string): Message =>+ new Message({ role, content: [new TextBlock(text)] });++/** A bloated transcript: one task message + many tool-churn turns. */+function bloated(n: number): Message[] {+ const out: Message[] = [msg('user', 'compose the necropolis')];+ for (let i = 0; i < n; i++) {+ out.push(msg('assistant', `move asset ${i}`), msg('user', `[tool result ${i}]`));+ }+ return out;+}++/** Pull the text out of a single-block user message. */+function textOf(m: Message): string {+ const block = m.content[0] as { text?: string };+ return block.text ?? '';+}++describe('SceneCompactionManager.reduce', () => {+ test('collapses the whole transcript to one synthetic user message', () => {+ const model = scene();+ const mgr = new SceneCompactionManager({ model });+ const agent = { messages: bloated(30) } as never as { messages: Message[] };+ expect(agent.messages.length).toBe(61);++ const reduced = mgr.reduce({ agent, model } as never);++ expect(reduced).toBe(true);+ expect(agent.messages).toHaveLength(1);+ expect(agent.messages[0]?.role).toBe('user');+ });++ test('the synthetic message carries the program, counts, and a finalize directive', () => {+ const model = scene();+ const mgr = new SceneCompactionManager({+ model,+ taskRecap: 'Egyptian Necropolis — grand plaza',+ });+ const agent = { messages: bloated(20) } as never as { messages: Message[] };++ mgr.reduce({ agent, model } as never);+ const body = textOf(agent.messages[0]!);++ // The program IS the compacted state — it must be reproduced verbatim.+ expect(body).toContain(serialize(model));+ // The two placements are surfaced in the count line.+ expect(body).toContain('2 placement(s)');+ // The goal recap is restated so the collapsed transcript is self-contained.+ expect(body).toContain('Egyptian Necropolis — grand plaza');+ // The convergence nudge: render once, fix a little, finalize.+ expect(body).toContain('scene_render');+ expect(body).toContain('scene_finalize');+ expect(body).toMatch(/source of truth/i);+ });++ test('is a no-op when there is nothing to compact (<= 1 message)', () => {+ const model = scene();+ const mgr = new SceneCompactionManager({ model });+ const agent = { messages: [msg('user', 'start')] } as never as { messages: Message[] };++ expect(mgr.reduce({ agent, model } as never)).toBe(false);+ expect(agent.messages).toHaveLength(1);+ });++ test('reports compaction telemetry via onCompact', () => {+ const model = scene();+ const seen: SceneCompactionInfo[] = [];+ const mgr = new SceneCompactionManager({ model, onCompact: (i) => seen.push(i) });+ const agent = { messages: bloated(10) } as never as { messages: Message[] };++ mgr.reduce({ agent, model } as never);++ expect(seen).toHaveLength(1);+ expect(seen[0]).toEqual({ messagesBefore: 21, placements: 2, overlaps: 0 });+ });+});++describe('SceneCompactionManager.initAgent (message-count trigger)', () => {+ test('compacts before a model call once the transcript exceeds maxMessages', () => {+ const model = scene();+ const mgr = new SceneCompactionManager({ model, maxMessages: 10 });++ // Capture every hook the manager registers (base reactive + proactive + ours).+ const hooks: Array<{ evt: unknown; cb: (e: unknown) => unknown }> = [];+ const agent = {+ messages: bloated(20), // 41 messages, well over maxMessages+ addHook(evt: unknown, cb: (e: unknown) => unknown) {+ hooks.push({ evt, cb });+ return () => {};+ },+ };++ mgr.initAgent(agent as never);++ // Fire the BeforeModelCall hooks (base proactive is inert without a threshold; ours compacts).+ const before = hooks.filter((h) => h.evt === BeforeModelCallEvent);+ expect(before.length).toBeGreaterThan(0);+ for (const h of before) h.cb({ agent, model });++ expect(agent.messages).toHaveLength(1);+ });++ test('does not compact while the transcript is within maxMessages', () => {+ const model = scene();+ const mgr = new SceneCompactionManager({ model, maxMessages: 40 });+ const hooks: Array<{ evt: unknown; cb: (e: unknown) => unknown }> = [];+ const agent = {+ messages: bloated(5), // 11 messages, under maxMessages+ addHook(evt: unknown, cb: (e: unknown) => unknown) {+ hooks.push({ evt, cb });+ return () => {};+ },+ };++ mgr.initAgent(agent as never);+ for (const h of hooks.filter((h) => h.evt === BeforeModelCallEvent)) h.cb({ agent, model });++ expect(agent.messages).toHaveLength(11);+ });+});diff --git a/src/agent/hooks.ts b/src/agent/hooks.tsindex e5090701..73942821 100644--- a/src/agent/hooks.ts+++ b/src/agent/hooks.ts@@ -27,7 +27,16 @@ export interface AgentUsage {/** A live agent-loop event, emitted as the loop runs (for progress UIs). */export type KilnAgentEvent =| { type: 'tool'; tool: string; step: number }- | { type: 'model_call'; step: number };+ | { type: 'model_call'; step: number }+ | {+ /** The composer compacted its transcript (state lives in the scene model, not+ * the history) — surfaced so a progress UI can show the loop staying lean. */+ type: 'compaction';+ step: number;+ messagesBefore: number;+ placements: number;+ overlaps: number;+ };/** The agent-loop-derived metrics this collector produces. */export interface CollectedMetrics {diff --git a/src/composer/agent/compaction.ts b/src/composer/agent/compaction.tsnew file mode 100644index 00000000..1696cd5e--- /dev/null+++ b/src/composer/agent/compaction.ts@@ -0,0 +1,146 @@+/**+ * Scene-composition context compaction.+ *+ * The composer's scene state lives in the `PlacementModel`, NOT the transcript —+ * every tool autosaves to the model, so the conversation history is pure working+ * memory (render images, move/face chatter) that bloats fast. Worse, with+ * image-bearing tool results it defeats the SDK's default+ * `SlidingWindowConversationManager`: its trim can't find a valid cut between a+ * tool-use and its tool-result, so it gives up ("no valid trim point found") and the+ * context grows unbounded.+ *+ * This manager exploits the externalized state. When the transcript grows past a+ * threshold, `reduce()` discards the ENTIRE history and replaces it with a single+ * synthetic user message carrying `serialize(model)` — the exact current program —+ * plus a directive to render once, make a few targeted fixes, and finalize. No LLM+ * summary (the model already IS the summary), no tool-pair surgery (we collapse to+ * one message, which is always a valid boundary), and the directive doubles as a+ * convergence nudge for a loop that would otherwise over-refine forever.+ *+ * Two triggers, both routed through `reduce`:+ * - message-count — our own `BeforeModelCallEvent` hook; the signal that actually+ * bloats for us, and a clean proxy for "past N steps".+ * - context overflow — reactive, inherited from the base `ConversationManager`+ * (`AfterModelCallEvent` on `ContextWindowOverflowError`); the hard safety net if+ * a single step ever overflows the model window.+ */+import {+ BeforeModelCallEvent,+ ConversationManager,+ type ConversationManagerReduceOptions,+ type LocalAgent,+ Message,+ TextBlock,+} from '@strands-agents/sdk';++import { serialize } from '../dsl';+import type { PlacementModel } from '../model';++/** Telemetry for one compaction event (best-effort, for progress UIs). */+export interface SceneCompactionInfo {+ /** Transcript length immediately before the collapse. */+ messagesBefore: number;+ /** Placements in the scene at compaction time. */+ placements: number;+ /** Unresolved footprint overlaps at compaction time. */+ overlaps: number;+}++export interface SceneCompactionConfig {+ /** The live scene model — its serialization IS the compacted context. */+ model: PlacementModel;+ /** Short recap of the scene goal, re-stated in the compaction message so the+ * collapsed transcript stays self-contained. The system prompt (conventions) is+ * retained separately and the asset catalog is re-discoverable via+ * scene_list_assets, so the program + goal is all the agent needs to continue. */+ taskRecap?: string;+ /** Compact when the transcript grows past this many messages. Default 24. */+ maxMessages?: number;+ /** Notified after each compaction (best-effort; errors are swallowed). */+ onCompact?: (info: SceneCompactionInfo) => void;+}++const DEFAULT_MAX_MESSAGES = 24;++/**+ * Collapses the composer transcript to the current scene program once it grows past+ * `maxMessages`, so a long compose loop stays cheap and can actually reach finalize.+ */+export class SceneCompactionManager extends ConversationManager {+ readonly name = 'kiln:scene-compaction';+ private readonly model: PlacementModel;+ private readonly taskRecap: string | undefined;+ private readonly maxMessages: number;+ private readonly onCompact: ((info: SceneCompactionInfo) => void) | undefined;++ constructor(config: SceneCompactionConfig) {+ // Base wires reactive overflow recovery only; the message-count trigger below is+ // our proactive path (token-fraction proactive is a poor fit for big-window models).+ super();+ this.model = config.model;+ this.taskRecap = config.taskRecap;+ this.maxMessages =+ config.maxMessages && config.maxMessages > 0 ? config.maxMessages : DEFAULT_MAX_MESSAGES;+ this.onCompact = config.onCompact;+ }++ /** Keep the base's reactive overflow hook, and add a per-model-call message-count+ * trigger so we compact proactively before the transcript ever overflows. */+ override initAgent(agent: LocalAgent): void {+ super.initAgent(agent);+ agent.addHook(BeforeModelCallEvent, (event) => {+ if (event.agent.messages.length > this.maxMessages) {+ this.reduce({ agent: event.agent, model: event.model });+ }+ });+ }++ /** Replace the whole transcript with one synthetic user message carrying the current+ * program. A single message is always a valid boundary (no dangling tool pairs) and+ * reduces history for both the message-count trigger and reactive overflow. */+ reduce({ agent }: ConversationManagerReduceOptions): boolean {+ const messages = agent.messages;+ if (messages.length <= 1) return false;+ const before = messages.length;+ const ev = this.model.placements();+ const text = this.compactionText(+ serialize(this.model),+ ev.placements.length,+ ev.overlaps.length,+ );+ const synthetic = new Message({ role: 'user', content: [new TextBlock(text)] });+ messages.splice(0, messages.length, synthetic);+ if (this.onCompact) {+ try {+ this.onCompact({+ messagesBefore: before,+ placements: ev.placements.length,+ overlaps: ev.overlaps.length,+ });+ } catch {+ // progress sinks are best-effort+ }+ }+ return true;+ }++ /** The "proper compaction prompt": the program is the state; render, fix a little,+ * finalize. Engineered to break the blind over-refine spiral. */+ private compactionText(program: string, placements: number, overlaps: number): string {+ const goal = this.taskRecap ? `\nScene goal: ${this.taskRecap.trim()}\n` : '';+ return (+ '[Context compacted to save budget. The scene program below is the source of truth — it ' ++ 'reflects every placement you have made so far; the earlier tool history (renders, edits) has ' ++ 'been dropped. Call scene_render again whenever you need to see the current state.]\n' ++ goal ++ `\nCurrent scene program — ${placements} placement(s), ${overlaps} unresolved overlap(s):\n` ++ '```\n' ++ `${program}\n` ++ '```\n\n' ++ 'You are deep into your tool budget. Bring the scene to a clean finish now:\n' ++ '1. scene_render ONCE and look at all three angles.\n' ++ '2. Make at most 2-3 targeted fixes (worst overlap, anything facing the wrong way, an obvious gap).\n' ++ '3. scene_finalize. Do NOT re-layout or re-place from scratch — refine what is here, then finalize.'+ );+ }+}diff --git a/src/composer/agent/index.ts b/src/composer/agent/index.tsindex 365009a4..f2ceaae1 100644--- a/src/composer/agent/index.ts+++ b/src/composer/agent/index.ts@@ -19,3 +19,6 @@ export type { ComposerSink, MakeComposerToolsOptions, SceneRenderCandidate } froexport { buildComposerUserPrompt, COMPOSER_SYSTEM_PROMPT } from './prompt';export type { BuildComposerPromptOptions } from './prompt';++export { SceneCompactionManager } from './compaction';+export type { SceneCompactionConfig, SceneCompactionInfo } from './compaction';diff --git a/src/composer/agent/run.ts b/src/composer/agent/run.tsindex 7e1bf98d..d2e4933e 100644--- a/src/composer/agent/run.ts+++ b/src/composer/agent/run.ts@@ -17,6 +17,7 @@ import { Agent, type Message, type Tool } from '@strands-agents/sdk';import { unifiedDiff } from '../../agent/diff';import { type AgentUsage, type KilnAgentEvent, MetricsCollector } from '../../agent/hooks';+import { SceneCompactionManager } from './compaction';import { serialize } from '../dsl';import { flatGround, type GroundSampler } from '../ground';import {@@ -85,7 +86,11 @@ export interface RunKilnComposerResult {lastText?: string;/** When refining (seedScene set): a unified diff from the parent program. */diff?: string;- /** Error message if the run threw or was step-capped. */+ /** True when the run hit the step cap before the agent called scene_finalize. NOT+ * an error — the returned scene is the agent's best effort (layout + whatever+ * refinement fit the budget); the host can persist it and flag it unfinalized. */+ capped?: boolean;+ /** Error message if the run THREW (a real failure). A step-cap is `capped`, not this. */error?: string;}@@ -125,10 +130,14 @@ export async function runKilnComposer(opts: RunKilnComposerOptions,): Promise<RunKilnComposerResult> {// Runaway backstop (NOT a throttle): a stuck model could loop place/render- // forever, re-feeding a growing transcript. Default 60 — composition takes more- // tool turns than a single asset (many placements + renders). Env-overridable- // (0 disables); shares the asset-gen knob name for one place to tune.- const maxSteps = Number(process.env['KILN_AGENT_MAX_STEPS'] ?? 60) || 0;+ // forever. Default 80 — compaction (below) keeps each step cheap regardless of how+ // long the run gets, so the cap is a far-back safety net, not the primary stop; the+ // agent should finalize well before it. Env-overridable (0 disables); shares the+ // asset-gen knob name for one place to tune.+ const maxSteps = Number(process.env['KILN_AGENT_MAX_STEPS'] ?? 80) || 0;+ // Compact the transcript once it grows past this many messages: the scene state+ // lives in the model, so the history is disposable working memory. Env-tunable.+ const compactAt = Number(process.env['KILN_COMPOSER_COMPACT_AT'] ?? 24) || 0;const metrics = new MetricsCollector(opts.onEvent, maxSteps);const model = buildModel(opts);const parentProgram = opts.seedScene ? serialize(model) : undefined;@@ -143,11 +152,22 @@ export async function runKilnComposer(});const allTools: unknown[] = opts.extraTools ? [...tools, ...opts.extraTools] : tools;+ // Keep the loop lean + convergent: collapse the transcript to the live program+ // once it bloats (state is in the model, not the history) and nudge toward finalize.+ const compaction = new SceneCompactionManager({+ model,+ taskRecap: opts.sceneName ? `${opts.sceneName} — ${opts.prompt}` : opts.prompt,+ ...(compactAt ? { maxMessages: compactAt } : {}),+ onCompact: (info) =>+ opts.onEvent?.({ type: 'compaction', step: metrics.readMetrics().steps, ...info }),+ });+const agent = new Agent({model: opts.model as never,systemPrompt: COMPOSER_SYSTEM_PROMPT,tools: allTools as never,name: opts.agentName ?? 'kiln-composer',+ conversationManager: compaction,});metrics.attach(agent);@@ -167,18 +187,20 @@ export async function runKilnComposer(metrics.recordResultUsage(result.metrics?.latestAgentInvocation?.usage);const lastText = lastMessageText(result.lastMessage);- // Halted by the step cap: surface a clear failure but still return the partial- // scene the sink captured (continuous autosave), so the host can show progress.+ // Halted by the step cap: a SOFT stop, not a failure. Return the scene the sink+ // captured (continuous autosave: layout + whatever refinement fit the budget) with+ // `capped` set so the host can persist it and flag it unfinalized — discarding a+ // fully laid-out scene just because the agent over-refined would waste the work.if (metrics.wasCapped()) {const collected = metrics.readMetrics();return {...sceneFields(sink, model),finalized: sink.finalized ?? false,+ capped: true,toolCalls: collected.toolCalls,steps: collected.steps,...(collected.usage ? { usage: collected.usage } : {}),...(lastText ? { lastText } : {}),- error: `kiln composer exceeded ${maxSteps} model calls (step cap) — aborted to bound cost`,};}