Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 365009a4..f2ceaae1 100644
--- a/src/composer/agent/index.ts
+++ b/src/composer/agent/index.ts
@@ -19,3 +19,6 @@ export type { ComposerSink, MakeComposerToolsOptions, SceneRenderCandidate } fro
export { 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.ts
index 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`,
};
}