@agentick/core 0.2.0 → 0.3.0

package/dist/app/session.js

@@ -58,18 +58,17 @@ export class SessionImpl extends EventEmitter {
     _tick = 1;
     _isAborted = false;
     _currentExecutionId = null;
-    // Hydration state (pending fiber tree data to restore)
-    _pendingHydrationData = null;
     // Compilation infrastructure (no intermediate layer)
     compiler = null;
     ctx = null;
     structureRenderer = null;
     scheduler = null;
-    // State that persists across ticks
-    _previousOutput = null;
+    // Last completed tick's compiled output. Used only by inspect().lastOutput.
+    _lastCompleteOutput = null;
     _currentOutput = null;
-    // Track timeline sent to model (for combining with response in complete())
-    _lastSentTimeline = [];
+    // Session-owned timeline (source of truth, append-only)
+    _timeline = [];
+    _maxTimelineEntries;
     // Estimated context tokens from last compilation (pre-model-call)
     _estimatedContextTokens;
     // Track last published timeline length for delta publishing
@@ -113,8 +112,12 @@ export class SessionImpl extends EventEmitter {
     _currentHandle = null;
     _currentResultResolve = null;
     _currentResultReject = null;
-    // Hibernate callback (set by App when registering session)
-    _hibernateCallback = null;
+    // Auto-persist callback (set by App when store is configured)
+    _persistCallback = null;
+    // Snapshot for resolve (set when restoring from store)
+    _snapshotForResolve = null;
+    // Execution environment initialization tracking
+    _environmentInitialized = false;
     // Spawn hierarchy
     _parent = null;
     _children = [];
@@ -153,21 +156,10 @@ export class SessionImpl extends EventEmitter {
                 });
             }
         }
-        // Hydrate from snapshot if provided
-        if (sessionOptions.snapshot) {
-            this.hydrate(sessionOptions.snapshot);
-        }
-        // Seed initial timeline if provided
-        if (sessionOptions.initialTimeline?.length) {
-            this._previousOutput = {
-                timeline: sessionOptions.initialTimeline,
-                system: [],
-                ephemeral: [],
-                sections: {},
-                tools: [],
-                metadata: {},
-            };
-        }
+        // Read maxTimelineEntries from appOptions
+        this._maxTimelineEntries = appOptions.maxTimelineEntries;
+        // Note: snapshot/initialTimeline hydration now handled via _snapshotForResolve
+        // set by App.createSessionFromSnapshot() — applied in ensureCompilationInfrastructure()
         // Start recording if enabled via options
         if (sessionOptions.recording) {
             this.startRecording(sessionOptions.recording);
@@ -181,6 +173,14 @@ export class SessionImpl extends EventEmitter {
     get status() {
         return this._status;
     }
+    /** Whether the session is in a terminal state (closed). */
+    get isTerminal() {
+        return this._status === "closed";
+    }
+    /** Error message for operations attempted on a terminal session. */
+    get terminalError() {
+        return "Session is closed";
+    }
     get currentTick() {
         return this._tick;
     }
@@ -233,8 +233,8 @@ export class SessionImpl extends EventEmitter {
             handleFactory: false,
             executionBoundary: false,
         }, async (message) => {
-            if (this._status === "closed") {
-                throw new Error("Session is closed");
+            if (this.isTerminal) {
+                throw new Error(this.terminalError);
             }
             const messageWithId = ensureMessageId(message);
             this._queuedMessages.push(messageWithId);
@@ -254,6 +254,7 @@ export class SessionImpl extends EventEmitter {
                 };
                 const tickState = {
                     tick: this._tick,
+                    timeline: this._timeline,
                     stop: () => { },
                     queuedMessages: [],
                 };
@@ -267,8 +268,8 @@ export class SessionImpl extends EventEmitter {
             handleFactory: false,
             executionBoundary: false,
         }, async (input) => {
-            if (this._status === "closed") {
-                throw new Error("Session is closed");
+            if (this.isTerminal) {
+                throw new Error(this.terminalError);
             }
             const { messages = [], props, metadata, maxTicks, signal } = input;
             // Apply metadata to messages
@@ -296,6 +297,7 @@ export class SessionImpl extends EventEmitter {
                     };
                     const tickState = {
                         tick: this._tick,
+                        timeline: this._timeline,
                         stop: () => { },
                         queuedMessages: [],
                     };
@@ -330,8 +332,8 @@ export class SessionImpl extends EventEmitter {
             handleFactory: false,
             executionBoundary: false,
         }, (props, options) => {
-            if (this._status === "closed") {
-                throw new Error("Session is closed");
+            if (this.isTerminal) {
+                throw new Error(this.terminalError);
             }
             // Props is explicitly provided (even if empty object) - always run tick
             // Only skip if props is undefined/null AND no queued messages
@@ -357,25 +359,32 @@ export class SessionImpl extends EventEmitter {
             metadata: { operation: "spawn" },
             handleFactory: false,
             executionBoundary: false,
-        }, async (component, input = {}) => {
-            if (this._status === "closed") {
-                throw new Error("Session is closed");
+        }, async (component, input, spawnOptions) => {
+            if (this.isTerminal) {
+                throw new Error(this.terminalError);
             }
             if (this._spawnDepth >= SessionImpl.MAX_SPAWN_DEPTH) {
                 throw new Error(`Maximum spawn depth (${SessionImpl.MAX_SPAWN_DEPTH}) exceeded`);
             }
             // 1. Resolve to ComponentFunction
-            const { Component, mergedProps } = this.resolveSpawnTarget(component, input);
+            const resolvedInput = input ?? {};
+            const { Component, mergedProps } = this.resolveSpawnTarget(component, resolvedInput);
             // 2. Create child SessionImpl (ephemeral — NOT registered in App's registry)
             //    Whitelist structural fields only — lifecycle callbacks, session management,
             //    signal, and devTools are intentionally excluded. New AppOptions fields
             //    must be explicitly added here if children should inherit them.
+            //
+            //    NOTE: `environment` IS inherited by default. A REPL environment, sandbox,
+            //    or human-in-the-loop gateway should apply to sub-agents — the execution
+            //    model is structural, not observational (unlike lifecycle callbacks).
+            //    Use SpawnOptions to override for specific children.
             const childAppOptions = {
-                model: this.appOptions.model,
+                model: spawnOptions?.model ?? this.appOptions.model,
                 tools: this.appOptions.tools,
                 mcpServers: this.appOptions.mcpServers,
-                maxTicks: this.appOptions.maxTicks,
+                maxTicks: spawnOptions?.maxTicks ?? this.appOptions.maxTicks,
                 inheritDefaults: this.appOptions.inheritDefaults,
+                environment: spawnOptions?.environment ?? this.appOptions.environment,
             };
             const childOptions = {
                 signal: this.executionAbortController?.signal,
@@ -387,14 +396,14 @@ export class SessionImpl extends EventEmitter {
             this._children.push(child);
             // 3. Delegate to child.send()
             const handle = await child.send({
-                ...input,
+                ...resolvedInput,
                 props: mergedProps,
             });
             // 4. Cleanup on completion
             handle.result
-                .finally(() => {
+                .finally(async () => {
                 this._children = this._children.filter((c) => c !== child);
-                child.close();
+                await child.close();
             })
                 .catch(() => { });
             return handle;
@@ -648,8 +657,8 @@ export class SessionImpl extends EventEmitter {
     // Interrupt & Abort
     // ════════════════════════════════════════════════════════════════════════
     interrupt(message, reason) {
-        if (this._status === "closed") {
-            throw new Error("Session is closed");
+        if (this.isTerminal) {
+            throw new Error(this.terminalError);
         }
         if (message) {
             this._queuedMessages.push(message);
@@ -788,37 +797,29 @@ export class SessionImpl extends EventEmitter {
             version: "1.0",
             sessionId: this.id,
             tick: this._tick,
-            timeline: this._previousOutput?.timeline ?? null,
-            componentState: this.serializeFiberTree(), // Serialized fiber tree with hook states
+            timeline: [...this._timeline],
+            comState: this.compiler
+                ? this.compiler.getSerializableComState(this.ctx?.getStateAll() ?? {})
+                : {},
+            dataCache: this.compiler?.getSerializableDataCache() ?? {},
             usage: { ...this._totalUsage },
             timestamp: Date.now(),
         };
     }
     /**
-     * Set the hibernate callback.
-     * Called by the App when registering this session.
+     * Set the auto-persist callback.
+     * Called by the App when a store is configured.
      * @internal
      */
-    setHibernateCallback(callback) {
-        this._hibernateCallback = callback;
+    setPersistCallback(callback) {
+        this._persistCallback = callback;
     }
-    async hibernate() {
-        if (this._status === "closed") {
-            return null;
-        }
-        if (this._status === "running") {
-            // Cannot hibernate while running - abort first
-            this.interrupt(undefined, "Hibernation requested");
-        }
-        // Delegate to the App's hibernate callback if available
-        if (this._hibernateCallback) {
-            return this._hibernateCallback();
-        }
-        // No callback - just return the snapshot without persisting
-        // This allows sessions created outside of App management to still hibernate
-        const snapshot = this.snapshot();
-        this.close();
-        return snapshot;
+    /**
+     * Set a snapshot to be applied/resolved when compilation infrastructure is created.
+     * @internal
+     */
+    setSnapshotForResolve(snapshot) {
+        this._snapshotForResolve = snapshot;
     }
     inspect() {
         // Get fiber summary for component/hook stats
@@ -834,7 +835,7 @@ export class SessionImpl extends EventEmitter {
             queuedMessages: [...this._queuedMessages],
             currentPhase: this._status === "running" ? "model" : undefined, // Approximate
             isAborted: this._isAborted,
-            lastOutput: this._previousOutput,
+            lastOutput: this._lastCompleteOutput,
             lastModelOutput: this._lastModelOutput,
             lastToolCalls: lastSnapshot?.tools.calls ?? [],
             lastToolResults: lastSnapshot?.tools.results.map((r) => ({
@@ -1200,16 +1201,23 @@ export class SessionImpl extends EventEmitter {
         }
     }
     // ════════════════════════════════════════════════════════════════════════
-    // Close
+    // Close & Teardown
     // ════════════════════════════════════════════════════════════════════════
-    close() {
-        if (this._status === "closed")
+    async close() {
+        if (this.isTerminal)
             return;
         this._status = "closed";
-        // Close all child sessions
-        for (const child of [...this._children]) {
-            child.close();
+        // Notify execution environment of destroy
+        if (this._environmentInitialized && this.appOptions.environment?.onDestroy) {
+            try {
+                await this.appOptions.environment.onDestroy(this);
+            }
+            catch (err) {
+                this.log.warn({ error: err }, "Environment onDestroy failed");
+            }
         }
+        // Close all child sessions
+        await Promise.all(this._children.map((child) => child.close()));
         this._children = [];
         this.sessionAbortController.abort("Session closed");
         this.executionAbortController?.abort("Session closed");
@@ -1226,7 +1234,12 @@ export class SessionImpl extends EventEmitter {
         }
         // Unmount compiler if it exists
         if (this.compiler) {
-            this.compiler.unmount().catch(() => { });
+            try {
+                await this.compiler.unmount();
+            }
+            catch {
+                // Unmount errors during close are non-fatal
+            }
             this.compiler = null;
         }
         this.ctx = null;
@@ -1268,29 +1281,6 @@ export class SessionImpl extends EventEmitter {
         const merged = { ...baseContext, ...(current ?? {}), ...sessionContext };
         return Context.run(merged, fn);
     }
-    hydrate(snapshot) {
-        this._tick = snapshot.tick;
-        // Hydrate timeline (conversation history)
-        if (snapshot.timeline) {
-            this._previousOutput = {
-                timeline: snapshot.timeline,
-                system: [],
-                ephemeral: [],
-                sections: {},
-                tools: [],
-                metadata: {},
-            };
-        }
-        // Hydrate usage stats
-        if (snapshot.usage) {
-            this._totalUsage = { ...snapshot.usage };
-        }
-        // Hydrate fiber tree (component state)
-        // This will be applied when the compiler is first created
-        if (snapshot.componentState) {
-            this._pendingHydrationData = snapshot.componentState;
-        }
-    }
     /**
      * The core tick execution loop.
      *
@@ -1300,8 +1290,8 @@ export class SessionImpl extends EventEmitter {
      * 3. Return result
      */
     async executeTick(props, options) {
-        if (this._status === "closed") {
-            throw new Error("Session is closed");
+        if (this.isTerminal) {
+            throw new Error(this.terminalError);
         }
         const signal = this.executionAbortController?.signal ?? this.sessionAbortController.signal;
         if (signal.aborted) {
@@ -1345,7 +1335,7 @@ export class SessionImpl extends EventEmitter {
         let stopReason;
         let output;
         const outputs = {};
-        const responseChunks = [];
+        let responseText = "";
         const toolExecutor = new ToolExecutor();
         this.emitEvent({
             type: "execution_start",
@@ -1429,7 +1419,11 @@ export class SessionImpl extends EventEmitter {
                 if (signal.aborted) {
                     throw new AbortError("Execution aborted", signal.reason);
                 }
-                const modelInput = compiled.modelInput ?? compiled.formatted;
+                let modelInput = compiled.modelInput ?? compiled.formatted;
+                // Apply execution environment transformation
+                if (this.appOptions.environment?.prepareModelInput) {
+                    modelInput = await this.appOptions.environment.prepareModelInput(modelInput, (compiled.tools ?? []));
+                }
                 const modelStartTime = Date.now();
                 // Emit model request to DevTools
                 // modelInput is the Agentick ModelInput format (after fromEngineState transformation)
@@ -1458,17 +1452,12 @@ export class SessionImpl extends EventEmitter {
                 // Stream model output if supported
                 let modelOutput;
                 if (model.stream) {
-                    const streamEvents = [];
                     const streamIterable = await model.stream(modelInput);
                     for await (const event of streamIterable) {
                         if (signal.aborted) {
                             throw new AbortError("Execution aborted", signal.reason);
                         }
-                        streamEvents.push(event);
                         this.emitEvent(event);
-                        if (event.type === "content_delta" && "delta" in event) {
-                            responseChunks.push(event.delta);
-                        }
                         if (event.type === "message" && "message" in event) {
                             const messageEvent = event;
                             modelOutput = {
@@ -1480,27 +1469,8 @@ export class SessionImpl extends EventEmitter {
                             };
                         }
                     }
-                    // Aggregate stream events into final output
                     if (!modelOutput) {
-                        if (model.processStream) {
-                            // Use model's processStream if available
-                            modelOutput = await model.processStream(streamEvents);
-                        }
-                        else if (responseChunks.length > 0) {
-                            // Construct from collected chunks
-                            const text = responseChunks.join("");
-                            modelOutput = {
-                                message: {
-                                    role: "assistant",
-                                    content: [{ type: "text", text }],
-                                },
-                                stopReason: "stop",
-                                raw: { streamed: true },
-                            };
-                        }
-                        else {
-                            throw new Error("Streaming completed but no response was received");
-                        }
+                        throw new Error("Streaming completed but no model output was received");
                     }
                 }
                 else {
@@ -1516,8 +1486,7 @@ export class SessionImpl extends EventEmitter {
                 if (modelOutput?.message) {
                     const textContent = modelOutput.message.content?.find((b) => b.type === "text");
                     if (textContent && "text" in textContent) {
-                        responseChunks.length = 0;
-                        responseChunks.push(textContent.text);
+                        responseText = textContent.text;
                     }
                 }
                 // Update usage
@@ -1625,9 +1594,9 @@ export class SessionImpl extends EventEmitter {
                 // These can call tickResult.stop() or tickResult.continue() to influence continuation
                 const tickEndState = {
                     tick: currentTick,
-                    previous: this._previousOutput ?? undefined,
                     current: this._currentOutput,
                     queuedMessages: [],
+                    timeline: this._timeline,
                     stop: () => { }, // No-op at tick end - use tickResult.stop() instead
                 };
                 await this.compiler?.notifyTickEnd(tickEndState, tickResult);
@@ -1666,24 +1635,18 @@ export class SessionImpl extends EventEmitter {
                     shouldContinue,
                     stopReason,
                 });
-                // Update _previousOutput after each tick so the next tick has access to the timeline
-                // This is critical for <Timeline> to render conversation history on subsequent ticks
                 output = await this.complete();
-                this._previousOutput = output;
-                this.log.debug({ timelineLength: output.timeline?.length ?? 0 }, "Updated _previousOutput after tick");
+                this._lastCompleteOutput = output;
                 this._tick++;
                 usage.ticks = (usage.ticks ?? 0) + 1;
             }
-            // Final complete (may be redundant but ensures consistency)
-            output = await this.complete();
-            this._previousOutput = output;
             // Accumulate usage
             this._totalUsage.inputTokens += usage.inputTokens;
             this._totalUsage.outputTokens += usage.outputTokens;
             this._totalUsage.totalTokens += usage.totalTokens;
             this._totalUsage.ticks = (this._totalUsage.ticks ?? 0) + (usage.ticks ?? 0);
             const resultPayload = {
-                response: responseChunks.join(""),
+                response: responseText,
                 outputs,
                 usage,
                 stopReason,
@@ -1708,6 +1671,16 @@ export class SessionImpl extends EventEmitter {
                 output: output ?? null,
                 timestamp: timestamp(),
             });
+            // Auto-persist snapshot after successful execution (fire-and-forget, skip on abort)
+            if (this._persistCallback && !this._isAborted) {
+                let snap = this.snapshot();
+                if (this.appOptions.environment?.onPersist) {
+                    snap = await this.appOptions.environment.onPersist(this, snap);
+                }
+                this._persistCallback(snap).catch((err) => {
+                    this.log.warn({ error: err }, "Auto-persist failed");
+                });
+            }
             // Publish timeline delta to channel for real-time sync across clients
             // Only send NEW messages since last publish - O(delta) not O(n)
             if (output?.timeline) {
@@ -1738,7 +1711,7 @@ export class SessionImpl extends EventEmitter {
             this._status = "idle";
         }
         return {
-            response: responseChunks.join(""),
+            response: responseText,
             outputs,
             usage,
             stopReason,
@@ -1759,12 +1732,13 @@ export class SessionImpl extends EventEmitter {
         this.ctx = new COM({
             metadata: {},
         });
-        this.compiler = new FiberCompiler(this.ctx, undefined, {});
-        // Apply pending hydration data if available
-        if (this._pendingHydrationData) {
-            this.compiler.setHydrationData(this._pendingHydrationData);
-            this._pendingHydrationData = null; // Clear after applying
-        }
+        this.compiler = new FiberCompiler(this.ctx);
+        // Wire timeline accessors to RuntimeStore
+        const runtimeStore = this.compiler.getRuntimeStore();
+        runtimeStore.getSessionTimeline = () => this._timeline;
+        runtimeStore.setSessionTimeline = (entries) => {
+            this._timeline = [...entries];
+        };
         // Create scheduler and wire it to the compiler
         // This enables the reactive model: state changes between ticks trigger reconciliation
         this.scheduler = new ReconciliationScheduler(this.compiler, {
@@ -1793,6 +1767,75 @@ export class SessionImpl extends EventEmitter {
         }
         // Notify compiler that compilation is starting
         await this.compiler.notifyStart();
+        // Apply snapshot-for-resolve if set (restore from store)
+        if (this._snapshotForResolve) {
+            try {
+                const resolveConfig = this.appOptions.resolve;
+                if (resolveConfig) {
+                    // Layer 2: resolve controls reconstruction
+                    const ctx = { sessionId: this.id, snapshot: this._snapshotForResolve };
+                    const resolved = await this.executeResolve(resolveConfig, ctx);
+                    runtimeStore.resolvedData = resolved;
+                }
+                else {
+                    // Layer 1: auto-apply snapshot
+                    const snap = this._snapshotForResolve;
+                    this._timeline = [...(snap.timeline ?? [])];
+                    this._tick = snap.tick;
+                    if (snap.usage)
+                        this._totalUsage = { ...snap.usage };
+                    if (snap.comState && Object.keys(snap.comState).length > 0) {
+                        this.ctx.setStatePartial(snap.comState);
+                    }
+                    if (snap.dataCache && Object.keys(snap.dataCache).length > 0) {
+                        this.compiler.setDataCache(snap.dataCache);
+                    }
+                }
+                // Notify execution environment of restore
+                if (this.appOptions.environment?.onRestore) {
+                    await this.appOptions.environment.onRestore(this, this._snapshotForResolve);
+                }
+            }
+            finally {
+                this._snapshotForResolve = null;
+            }
+        }
+        // Initialize execution environment (once per session lifecycle)
+        if (!this._environmentInitialized) {
+            if (this.appOptions.environment?.onSessionInit) {
+                await this.appOptions.environment.onSessionInit(this);
+            }
+            this._environmentInitialized = true;
+        }
+    }
+    /**
+     * Execute resolve configuration and return results.
+     */
+    async executeResolve(config, ctx) {
+        if (typeof config === "function") {
+            try {
+                return await config(ctx);
+            }
+            catch (err) {
+                throw new Error(`resolve function failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Object form: resolve each entry
+        const results = {};
+        for (const [key, value] of Object.entries(config)) {
+            if (typeof value === "function") {
+                try {
+                    results[key] = await value(ctx);
+                }
+                catch (err) {
+                    throw new Error(`resolve["${key}"] failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                results[key] = value;
+            }
+        }
+        return results;
     }
     /**
      * Compile a single tick.
@@ -1820,9 +1863,9 @@ export class SessionImpl extends EventEmitter {
         // Prepare tick state
         const tickState = {
             tick: this._tick,
-            previous: this._previousOutput ?? undefined,
             current: this._currentOutput,
             queuedMessages: queuedMessages,
+            timeline: [...this._timeline],
             stop: (reason) => {
                 tickState.stopReason = reason;
             },
@@ -1847,21 +1890,16 @@ export class SessionImpl extends EventEmitter {
         // Enter tick mode - scheduler will defer reconciliations until exitTick
         this.scheduler?.enterTick();
         let compiled;
-        const wasHydrating = this.compiler.isHydratingNow();
         try {
             // Compile until stable
             // Note: tickControl and getChannel are available for future use
-            // but not currently used by the v2 FiberCompiler
+            // but not currently used by FiberCompiler
             void tickControl;
             void getChannel;
             const result = await this.compiler.compileUntilStable(rootElement, tickState, {
                 maxIterations: 50,
             });
             compiled = result.compiled;
-            // Complete hydration after first successful compile
-            if (wasHydrating) {
-                this.compiler.completeHydration();
-            }
         }
         finally {
             // Exit tick mode - any pending reconciliations will now flush
@@ -1872,8 +1910,6 @@ export class SessionImpl extends EventEmitter {
         // Format input - compiled structure IS the complete projection
         // JSX components render history as <Message>, so compiled.timelineEntries is complete
         const formatted = await this.structureRenderer.formatInput(this.ctx.toInput());
-        // Track what we're sending to the model (for combining with response in complete())
-        this._lastSentTimeline = formatted.timeline ?? [];
         // Track estimated context tokens for contextInfo
         this._estimatedContextTokens = formatted.totalTokens;
         // Get model from COM if not in options
@@ -1922,17 +1958,28 @@ export class SessionImpl extends EventEmitter {
                 });
                 continue;
             }
-            // Execute tool
+            // Execute tool (optionally wrapped by execution environment)
             try {
-                const result = await executor.processToolWithConfirmation(call, this.ctx, executableTools);
-                results.push(result.result);
+                const env = this.appOptions.environment;
+                let toolResult;
+                if (env?.executeToolCall) {
+                    toolResult = await env.executeToolCall(call, tool, async () => {
+                        const r = await executor.processToolWithConfirmation(call, this.ctx, executableTools);
+                        return r.result;
+                    });
+                }
+                else {
+                    const r = await executor.processToolWithConfirmation(call, this.ctx, executableTools);
+                    toolResult = r.result;
+                }
+                results.push(toolResult);
                 const completedAt = timestamp();
                 this.emitEvent({
                     type: "tool_result",
-                    callId: result.result.toolUseId,
-                    name: result.result.name,
-                    result: result.result,
-                    isError: !result.result.success,
+                    callId: toolResult.toolUseId,
+                    name: toolResult.name,
+                    result: toolResult,
+                    isError: !toolResult.success,
                     executedBy: "engine",
                     startedAt,
                     completedAt,
@@ -1987,9 +2034,11 @@ export class SessionImpl extends EventEmitter {
         const userEntries = [];
         const newUserEntries = [];
         for (const queued of queuedMessages) {
-            if (queued.type !== "user" || !queued.content)
+            if (!queued.content)
                 continue;
             const message = queued.content;
+            if (message.role !== "user")
+                continue;
             const existing = existingByMessage.get(message);
             if (existing) {
                 userEntries.push(existing);
@@ -2029,17 +2078,19 @@ export class SessionImpl extends EventEmitter {
             toolCalls: response.toolCalls,
             toolResults,
         };
-        // Add entries to COM - user entries first, then assistant response
+        // Add entries to COM and session timeline - user entries first, then assistant response
         for (const entry of newUserEntries) {
             this.ctx.addTimelineEntry(entry);
+            this._timeline.push(entry);
         }
         if (response.newTimelineEntries) {
             for (const entry of response.newTimelineEntries) {
                 this.ctx.addTimelineEntry(entry);
+                this._timeline.push(entry);
             }
         }
         if (toolResults.length > 0) {
-            this.ctx.addTimelineEntry({
+            const toolResultEntry = {
                 kind: "message",
                 message: {
                     role: "tool",
@@ -2052,7 +2103,15 @@ export class SessionImpl extends EventEmitter {
                     })),
                 },
                 tags: ["tool_output"],
-            });
+            };
+            this.ctx.addTimelineEntry(toolResultEntry);
+            this._timeline.push(toolResultEntry);
+        }
+        // Apply maxTimelineEntries trim
+        if (this._maxTimelineEntries && this._timeline.length > this._maxTimelineEntries) {
+            const removed = this._timeline.length - this._maxTimelineEntries;
+            this._timeline = this._timeline.slice(-this._maxTimelineEntries);
+            this.log.debug({ removed, remaining: this._timeline.length }, "Timeline trimmed (maxTimelineEntries)");
         }
         this._currentOutput = current;
         // Resolve tick control
@@ -2067,58 +2126,17 @@ export class SessionImpl extends EventEmitter {
     /**
      * Complete execution and return final state.
      *
-     * Returns the complete timeline for this execution:
-     * - What was sent to the model (from compiled JSX via _lastSentTimeline)
-     * - What the model responded (from _currentOutput.timeline - only NEW entries)
-     *
-     * This ensures the full conversation history is preserved across executions.
+     * Session._timeline is the source of truth. No merge/dedup logic needed.
      */
     async complete() {
         if (!this.ctx || !this.structureRenderer || !this.compiler) {
             throw new Error("Compilation infrastructure not initialized");
         }
-        // Build complete timeline:
-        // 1. _lastSentTimeline = what was sent to model (includes history rendered by JSX)
-        // 2. _currentOutput.timeline = new entries from this tick (user input + model response + tool results)
-        //
-        // Only USER messages might overlap (rendered via JSX AND in queuedMessages).
-        // Model responses (assistant/tool) are ALWAYS new and should NEVER be deduplicated.
-        //
-        // NOTE: We use content-based comparison for user messages because <Message {...entry.message}>
-        // creates NEW message objects when rendering history, so reference equality fails.
-        const sentTimeline = this._lastSentTimeline ?? [];
-        const currentTimeline = this._currentOutput?.timeline ?? [];
-        // Create a signature for user messages only
-        const userMessageSignature = (entry) => {
-            if (!entry.message || entry.message.role !== "user")
-                return null;
-            const m = entry.message;
-            if (m.id)
-                return `id:${m.id}`;
-            const contentStr = JSON.stringify(m.content);
-            return `user:${contentStr}`;
-        };
-        // Only track signatures of USER messages that were sent
-        const sentUserSignatures = new Set(sentTimeline.map(userMessageSignature).filter((s) => s !== null));
-        // Filter currentTimeline:
-        // - USER messages: dedupe against sentTimeline (might be rendered via JSX)
-        // - Other roles (assistant, tool): always include (they're new from this tick)
-        const newEntries = currentTimeline.filter((entry) => {
-            if (!entry.message)
-                return true; // Non-message entries always included
-            if (entry.message.role !== "user")
-                return true; // Assistant/tool always included
-            // User message: check for duplicates
-            const sig = userMessageSignature(entry);
-            return sig === null || !sentUserSignatures.has(sig);
-        });
-        const timeline = [...sentTimeline, ...newEntries];
         const comOutput = this.ctx.toInput();
         const finalOutput = {
             ...comOutput,
-            timeline,
+            timeline: [...this._timeline],
         };
-        // Notify compiler of completion
         try {
             await this.compiler.notifyComplete(finalOutput);
         }