@agentick/core 0.0.1

package/dist/app/session.js

@@ -0,0 +1,2131 @@
+/**
+ * Session - The Execution Unit
+ *
+ * A session holds component state (fiber tree) across ticks.
+ * Each tick: compile JSX -> call model -> execute tools -> decide continue?
+ *
+ * Design principles:
+ * - Single class, no intermediate layers
+ * - Minimal state - just what's needed for execution
+ * - render() is a Procedure returning SessionExecutionHandle (AsyncIterable)
+ * - Clean, elegant code over feature completeness
+ *
+ * @module agentick/app/session
+ */
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { Context, createProcedure, Channel, EventBuffer, ExecutionHandleBrand, Logger, } from "@agentick/kernel";
+import { FiberCompiler, StructureRenderer, ReconciliationScheduler, } from "../compiler";
+import { COM } from "../com/object-model";
+import { MarkdownRenderer } from "../renderers/index";
+import { ToolExecutor } from "../engine/tool-executor";
+import { AbortError } from "../utils/abort-utils";
+import { jsx } from "../jsx/jsx-runtime";
+import { devToolsEmitter, forwardToDevTools, FrameworkChannels, getEffectiveModelInfo, getContextUtilization, } from "@agentick/shared";
+import { computeTokenSummary } from "../utils/token-estimate";
+import React from "react";
+/**
+ * Get session context from the current ALS context.
+ */
+function getSessionContext() {
+    const ctx = Context.tryGet();
+    return {
+        sessionId: ctx?.sessionId,
+        rootComponent: ctx?.rootComponent,
+        devToolsEnabled: ctx?.devToolsEnabled,
+    };
+}
+/**
+ * Ensure a message has an ID. If no ID exists, generate one.
+ * This is critical for deduplication in reactive clients.
+ */
+function ensureMessageId(message) {
+    if (message.id)
+        return message;
+    return { ...message, id: randomUUID() };
+}
+/**
+ * Session implementation.
+ *
+ * A session manages the execution lifecycle: compile JSX, call model, execute tools.
+ * Component state (hooks, signals) persists across ticks within a session.
+ */
+export class SessionImpl extends EventEmitter {
+    id;
+    log = Logger.for("SessionImpl");
+    // Core execution state
+    _status = "idle";
+    _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;
+    _currentOutput = null;
+    // Track timeline sent to model (for combining with response in complete())
+    _lastSentTimeline = [];
+    // Estimated context tokens from last compilation (pre-model-call)
+    _estimatedContextTokens;
+    // Track last published timeline length for delta publishing
+    _lastPublishedTimelineLength = 0;
+    // Message queue
+    _queuedMessages = [];
+    // Abort handling
+    sessionAbortController;
+    executionAbortController = null;
+    executionAbortCleanup = [];
+    // Event streaming
+    _eventQueue = [];
+    _eventResolvers = [];
+    _executionComplete = false;
+    _sequence = 0; // Monotonically increasing sequence number for durable streams
+    // Usage tracking
+    _totalUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        ticks: 0,
+    };
+    // Last model output tracking
+    _lastModelOutput = null;
+    // Recording support
+    _recording = null;
+    _recordingMode = null;
+    _recordingStartedAt = null;
+    _snapshots = [];
+    // Configuration
+    Component;
+    appOptions;
+    sessionOptions;
+    // Last props for hot-update support
+    _lastProps = null;
+    // Captured context from session creation
+    _capturedContext;
+    // Channels for pub/sub communication
+    _channels = new Map();
+    // Current execution handle (for concurrent send idempotency)
+    _currentHandle = null;
+    _currentResultResolve = null;
+    _currentResultReject = null;
+    // Hibernate callback (set by App when registering session)
+    _hibernateCallback = null;
+    // Spawn hierarchy
+    _parent = null;
+    _children = [];
+    _spawnDepth = 0;
+    static MAX_SPAWN_DEPTH = 10;
+    constructor(Component, appOptions, sessionOptions = {}) {
+        super();
+        this.id = sessionOptions.sessionId ?? randomUUID();
+        this.Component = Component;
+        this.appOptions = appOptions;
+        this.sessionOptions = sessionOptions;
+        // Capture ALS context at session creation time
+        // Include Agentick middleware registry if available (for procedure middleware support)
+        const currentContext = Context.tryGet();
+        const agentickInstance = appOptions
+            ._agentickInstance;
+        if (agentickInstance && currentContext) {
+            this._capturedContext = { ...currentContext, middleware: agentickInstance };
+        }
+        else if (agentickInstance && !currentContext) {
+            this._capturedContext = Context.create({ middleware: agentickInstance });
+        }
+        else {
+            this._capturedContext = currentContext;
+        }
+        // Create session abort controller linked to external signals
+        this.sessionAbortController = new AbortController();
+        const externalSignal = sessionOptions.signal ?? appOptions.signal;
+        if (externalSignal) {
+            if (externalSignal.aborted) {
+                this.sessionAbortController.abort(externalSignal.reason);
+            }
+            else {
+                externalSignal.addEventListener("abort", () => {
+                    this.sessionAbortController.abort(externalSignal.reason);
+                });
+            }
+        }
+        // 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: {},
+            };
+        }
+        // Start recording if enabled via options
+        if (sessionOptions.recording) {
+            this.startRecording(sessionOptions.recording);
+        }
+        // Initialize procedures
+        this.initProcedures();
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Public Properties
+    // ════════════════════════════════════════════════════════════════════════
+    get status() {
+        return this._status;
+    }
+    get currentTick() {
+        return this._tick;
+    }
+    get isAborted() {
+        return this._isAborted;
+    }
+    get parent() {
+        return this._parent;
+    }
+    get children() {
+        return this._children;
+    }
+    get queuedMessages() {
+        return this._queuedMessages;
+    }
+    /**
+     * Observable scheduler state for DevTools.
+     *
+     * Returns a Signal containing the scheduler's current state,
+     * including status, pending reasons, and reconciliation metrics.
+     *
+     * Returns null if the session hasn't been initialized yet.
+     *
+     * @example
+     * ```typescript
+     * // In DevTools
+     * effect(() => {
+     *   const state = session.schedulerState?.();
+     *   if (state) {
+     *     console.log(`Status: ${state.status}, reconciles: ${state.reconcileCount}`);
+     *   }
+     * });
+     * ```
+     */
+    get schedulerState() {
+        return this.scheduler?.getState() ?? null;
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Queue Procedure
+    // ════════════════════════════════════════════════════════════════════════
+    queue;
+    send;
+    render;
+    spawn;
+    initProcedures() {
+        // Queue procedure - queues messages and notifies components
+        this.queue = createProcedure({
+            name: "session:queue",
+            metadata: { operation: "queue" },
+            handleFactory: false,
+            executionBoundary: false,
+        }, async (message) => {
+            if (this._status === "closed") {
+                throw new Error("Session is closed");
+            }
+            const messageWithId = ensureMessageId(message);
+            this._queuedMessages.push(messageWithId);
+            // Publish to messages channel for reactive updates
+            this.channel("messages").publish({
+                type: "message_queued",
+                channel: "messages",
+                payload: messageWithId,
+            });
+            // Notify components via useOnMessage hooks if compiler exists
+            if (this.compiler) {
+                const executionMessage = {
+                    id: randomUUID(),
+                    type: "message",
+                    content: message,
+                    timestamp: Date.now(),
+                };
+                const tickState = {
+                    tick: this._tick,
+                    stop: () => { },
+                    queuedMessages: [],
+                };
+                await this.compiler.notifyOnMessage(executionMessage, tickState);
+            }
+        });
+        // Send procedure - queues messages + delegates to render
+        this.send = createProcedure({
+            name: "session:send",
+            metadata: { operation: "send" },
+            handleFactory: false,
+            executionBoundary: false,
+        }, async (input) => {
+            if (this._status === "closed") {
+                throw new Error("Session is closed");
+            }
+            const { messages = [], props, metadata, maxTicks, signal } = input;
+            // Apply metadata to messages
+            const allMessages = messages.map((m) => (metadata ? { ...m, metadata } : m));
+            // Update props if provided
+            if (props) {
+                this._lastProps = props;
+            }
+            // Queue messages synchronously and notify components
+            for (const msg of allMessages) {
+                const msgWithId = ensureMessageId(msg);
+                this._queuedMessages.push(msgWithId);
+                this.channel("messages").publish({
+                    type: "message_queued",
+                    channel: "messages",
+                    payload: msgWithId,
+                });
+                // Notify components via useOnMessage hooks if compiler exists
+                if (this.compiler) {
+                    const executionMessage = {
+                        id: randomUUID(),
+                        type: "message",
+                        content: msgWithId,
+                        timestamp: Date.now(),
+                    };
+                    const tickState = {
+                        tick: this._tick,
+                        stop: () => { },
+                        queuedMessages: [],
+                    };
+                    // Fire and forget - don't await to keep send() fast
+                    this.compiler.notifyOnMessage(executionMessage, tickState).catch(() => { });
+                }
+            }
+            // Build execution options from input
+            const executionOptions = {};
+            if (maxTicks !== undefined)
+                executionOptions.maxTicks = maxTicks;
+            if (signal)
+                executionOptions.signal = signal;
+            // If already running, return the existing handle (concurrent send idempotency)
+            if (this._status === "running" && this._currentHandle) {
+                this.addExecutionSignal(signal);
+                return this._currentHandle;
+            }
+            // If idle and we have something to do, start tick
+            if ((allMessages.length > 0 || props) && this._status === "idle") {
+                // Use last known props if available, otherwise default to empty props.
+                const tickProps = (this._lastProps ?? {});
+                return await this.render(tickProps, executionOptions);
+            }
+            // Nothing to do - create a handle that resolves immediately with empty result
+            return this.createEmptyHandle();
+        });
+        // Render procedure - creates and runs a tick execution
+        this.render = createProcedure({
+            name: "session:render",
+            metadata: { operation: "render" },
+            handleFactory: false,
+            executionBoundary: false,
+        }, (props, options) => {
+            if (this._status === "closed") {
+                throw new Error("Session is closed");
+            }
+            // Props is explicitly provided (even if empty object) - always run tick
+            // Only skip if props is undefined/null AND no queued messages
+            const propsProvided = props !== undefined && props !== null;
+            if (!propsProvided && this._queuedMessages.length === 0) {
+                return this.createEmptyHandle();
+            }
+            // Hot-update: if already running, update props and return existing handle
+            if (this._status === "running" && this._currentHandle) {
+                this._lastProps = props;
+                this.addExecutionSignal(options?.signal);
+                return this._currentHandle;
+            }
+            // Create new execution
+            this._lastProps = props;
+            const handle = this.createSessionHandle(props, options);
+            this._currentHandle = handle;
+            return handle;
+        });
+        // Spawn procedure - creates ephemeral child session
+        this.spawn = createProcedure({
+            name: "session:spawn",
+            metadata: { operation: "spawn" },
+            handleFactory: false,
+            executionBoundary: false,
+        }, async (component, input = {}) => {
+            if (this._status === "closed") {
+                throw new Error("Session is closed");
+            }
+            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);
+            // 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.
+            const childAppOptions = {
+                model: this.appOptions.model,
+                tools: this.appOptions.tools,
+                mcpServers: this.appOptions.mcpServers,
+                maxTicks: this.appOptions.maxTicks,
+                inheritDefaults: this.appOptions.inheritDefaults,
+            };
+            const childOptions = {
+                signal: this.executionAbortController?.signal,
+                devTools: this.sessionOptions.devTools ?? this.appOptions.devTools,
+            };
+            const child = new SessionImpl(Component, childAppOptions, childOptions);
+            child._parent = this;
+            child._spawnDepth = this._spawnDepth + 1;
+            this._children.push(child);
+            // 3. Delegate to child.send()
+            const handle = await child.send({
+                ...input,
+                props: mergedProps,
+            });
+            // 4. Cleanup on completion
+            handle.result
+                .finally(() => {
+                this._children = this._children.filter((c) => c !== child);
+                child.close();
+            })
+                .catch(() => { });
+            return handle;
+        });
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // SessionExecutionHandle Creation
+    // ════════════════════════════════════════════════════════════════════════
+    /**
+     * Create a SessionExecutionHandle with explicit delegation.
+     * The handle is AsyncIterable (not PromiseLike — use `.result` for the final value).
+     */
+    createSessionHandle(props, options) {
+        const session = this;
+        const events = new EventEmitter();
+        const traceId = randomUUID();
+        // Create the result promise
+        let resolveResult;
+        let rejectResult;
+        const resultPromise = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        // Prevent unhandled rejections when abort happens before awaiting.
+        resultPromise.catch(() => { });
+        // Store resolvers for external completion
+        this._currentResultResolve = resolveResult;
+        this._currentResultReject = rejectResult;
+        // Track status
+        let status = "running";
+        // Event queue for async iteration
+        const eventQueue = [];
+        const eventResolvers = [];
+        let _iterationComplete = false;
+        this.startExecutionAbort(options?.signal);
+        // Create event buffer for dual consumption BEFORE starting execution
+        const eventBuffer = new EventBuffer();
+        // Forward events to event buffer
+        events.on("*", (event) => {
+            eventBuffer.push(event);
+        });
+        const pushEvent = (event) => {
+            if (eventResolvers.length > 0) {
+                const resolver = eventResolvers.shift();
+                resolver({ value: event, done: false });
+            }
+            else {
+                eventQueue.push(event);
+            }
+            events.emit("event", event);
+            events.emit("*", event);
+        };
+        const completeIteration = () => {
+            _iterationComplete = true;
+            eventBuffer.close();
+            for (const resolver of eventResolvers) {
+                resolver({ value: undefined, done: true });
+            }
+            eventResolvers.length = 0;
+        };
+        // Start execution asynchronously
+        (async () => {
+            try {
+                const result = await this.runWithContext(() => this.executeTick(props, options));
+                status = "completed";
+                // Call onComplete callback
+                try {
+                    this.callbacks.onComplete?.(result);
+                }
+                catch {
+                    // Callbacks should not throw
+                }
+                resolveResult(result);
+                completeIteration();
+            }
+            catch (error) {
+                status = "error";
+                const err = error instanceof Error ? error : new Error(String(error));
+                // Call onError callback
+                try {
+                    this.callbacks.onError?.(err);
+                }
+                catch {
+                    // Callbacks should not throw
+                }
+                eventBuffer.error(err);
+                rejectResult(err);
+                completeIteration();
+            }
+            finally {
+                this._currentHandle = null;
+                this._currentResultResolve = null;
+                this._currentResultReject = null;
+                this._isAborted = false;
+                this.finishExecutionAbort();
+            }
+        })();
+        // Create handle - use .result for final value, not PromiseLike
+        const handle = {
+            [ExecutionHandleBrand]: true,
+            // AsyncIterable delegation - delegates to EventBuffer for dual consumption
+            [Symbol.asyncIterator]() {
+                return eventBuffer[Symbol.asyncIterator]();
+            },
+            // ExecutionHandle properties
+            get status() {
+                return status;
+            },
+            get traceId() {
+                return traceId;
+            },
+            get events() {
+                return eventBuffer;
+            },
+            get result() {
+                return resultPromise;
+            },
+            abort(reason) {
+                if (status === "running") {
+                    status = "aborted";
+                    session._isAborted = true;
+                    session.executionAbortController?.abort(reason ?? "Aborted via handle");
+                    eventBuffer.close();
+                    rejectResult(new AbortError(reason ?? "Aborted via handle", "ABORT_SIGNAL"));
+                    completeIteration();
+                }
+            },
+            // Session-specific properties
+            get sessionId() {
+                return session.id;
+            },
+            get currentTick() {
+                return session._tick;
+            },
+            queueMessage(message) {
+                session._queuedMessages.push(message);
+                session.channel("messages").publish({
+                    type: "message_queued",
+                    channel: "messages",
+                    payload: message,
+                });
+            },
+            submitToolResult(toolUseId, response) {
+                session.channel("tool_confirmation").publish({
+                    type: "response",
+                    channel: "tool_confirmation",
+                    id: toolUseId,
+                    payload: response,
+                });
+            },
+        };
+        // Wire up event emission from session to handle
+        this.on("event", pushEvent);
+        return handle;
+    }
+    /**
+     * Create an empty handle for when there's nothing to do.
+     */
+    createEmptyHandle() {
+        const session = this;
+        const emptyResult = {
+            response: "",
+            outputs: {},
+            usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+            raw: {
+                timeline: [],
+                system: [],
+                ephemeral: [],
+                sections: {},
+                tools: [],
+                metadata: {},
+            },
+        };
+        // Empty event buffer for empty handle
+        const emptyEventBuffer = new EventBuffer();
+        emptyEventBuffer.close();
+        const handle = {
+            [ExecutionHandleBrand]: true,
+            [Symbol.asyncIterator]() {
+                return emptyEventBuffer[Symbol.asyncIterator]();
+            },
+            get status() {
+                return "completed";
+            },
+            get traceId() {
+                return randomUUID();
+            },
+            get events() {
+                return emptyEventBuffer;
+            },
+            get result() {
+                return Promise.resolve(emptyResult);
+            },
+            abort() { },
+            get sessionId() {
+                return session.id;
+            },
+            get currentTick() {
+                return session._tick;
+            },
+            queueMessage(message) {
+                session._queuedMessages.push(message);
+            },
+            submitToolResult(_toolUseId, _response) { },
+        };
+        return handle;
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Spawn Target Resolution
+    // ════════════════════════════════════════════════════════════════════════
+    /**
+     * Resolve spawn target to a ComponentFunction and merged props.
+     */
+    resolveSpawnTarget(component, input) {
+        // JSX Element
+        if (React.isValidElement(component)) {
+            return {
+                Component: component.type,
+                mergedProps: {
+                    ...component.props,
+                    ...(input.props ?? {}),
+                },
+            };
+        }
+        // Component function
+        return {
+            Component: component,
+            mergedProps: input.props ?? {},
+        };
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Channels
+    // ════════════════════════════════════════════════════════════════════════
+    channel(name) {
+        let channel = this._channels.get(name);
+        if (!channel) {
+            channel = new Channel(name);
+            this._channels.set(name, channel);
+        }
+        return channel;
+    }
+    submitToolResult(toolUseId, response) {
+        this.channel("tool_confirmation").publish({
+            type: "response",
+            channel: "tool_confirmation",
+            id: toolUseId,
+            payload: response,
+        });
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Interrupt & Abort
+    // ════════════════════════════════════════════════════════════════════════
+    interrupt(message, reason) {
+        if (this._status === "closed") {
+            throw new Error("Session is closed");
+        }
+        if (message) {
+            this._queuedMessages.push(message);
+        }
+        if (this._status === "running") {
+            this._isAborted = true;
+            this.executionAbortController?.abort(reason ?? "interrupt");
+            // Propagate interrupt to child sessions (spread-copy: interrupt cleanup may mutate array)
+            for (const child of [...this._children]) {
+                child.interrupt(undefined, reason ?? "Parent interrupted");
+            }
+        }
+    }
+    clearAbort() {
+        this._isAborted = false;
+    }
+    startExecutionAbort(signal) {
+        this.executionAbortCleanup.forEach((cleanup) => cleanup());
+        this.executionAbortCleanup = [];
+        this._isAborted = false;
+        this.executionAbortController = new AbortController();
+        this.addExecutionSignal(this.sessionAbortController.signal);
+        this.addExecutionSignal(signal);
+    }
+    addExecutionSignal(signal) {
+        if (!signal || !this.executionAbortController)
+            return;
+        if (signal.aborted) {
+            this._isAborted = true;
+            this.executionAbortController.abort(signal.reason);
+            return;
+        }
+        const handler = () => {
+            this._isAborted = true;
+            this.executionAbortController?.abort(signal.reason);
+        };
+        signal.addEventListener("abort", handler);
+        this.executionAbortCleanup.push(() => signal.removeEventListener("abort", handler));
+    }
+    finishExecutionAbort() {
+        this.executionAbortCleanup.forEach((cleanup) => cleanup());
+        this.executionAbortCleanup = [];
+        this.executionAbortController = null;
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Events (AsyncIterable)
+    // ════════════════════════════════════════════════════════════════════════
+    events() {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        if (self._eventQueue.length > 0) {
+                            return { value: self._eventQueue.shift(), done: false };
+                        }
+                        if (self._executionComplete) {
+                            return { value: undefined, done: true };
+                        }
+                        return new Promise((resolve) => {
+                            self._eventResolvers.push(resolve);
+                        });
+                    },
+                };
+            },
+        };
+    }
+    /**
+     * Get merged lifecycle callbacks (session overrides app).
+     */
+    get callbacks() {
+        return {
+            onEvent: this.sessionOptions.onEvent ?? this.appOptions.onEvent,
+            onTickStart: this.sessionOptions.onTickStart ?? this.appOptions.onTickStart,
+            onTickEnd: this.sessionOptions.onTickEnd ?? this.appOptions.onTickEnd,
+            onComplete: this.sessionOptions.onComplete ?? this.appOptions.onComplete,
+            onError: this.sessionOptions.onError ?? this.appOptions.onError,
+        };
+    }
+    emitEvent(event) {
+        const executionId = this._currentExecutionId ?? Context.tryGet()?.executionId;
+        // Enrich event with executionId and tick if missing
+        let enrichedEvent = executionId && !("executionId" in event) ? { ...event, executionId } : event;
+        if (!("id" in event)) {
+            enrichedEvent = { ...enrichedEvent, id: randomUUID() };
+        }
+        if (!("timestamp" in event)) {
+            enrichedEvent = { ...enrichedEvent, timestamp: new Date().toISOString() };
+        }
+        // Always set tick if missing - session knows the actual tick
+        if (!("tick" in event)) {
+            enrichedEvent = { ...enrichedEvent, tick: this._tick || 1 };
+        }
+        // Assign monotonically increasing sequence number for durable streams
+        this._sequence++;
+        enrichedEvent = { ...enrichedEvent, sequence: this._sequence };
+        // Forward to DevTools (check context for overrides)
+        const sessionCtx = getSessionContext();
+        forwardToDevTools(enrichedEvent, {
+            sessionId: sessionCtx.sessionId ?? this.id,
+            rootComponent: sessionCtx.rootComponent ?? (this.Component.name || "Agent"),
+            devToolsEnabled: sessionCtx.devToolsEnabled ?? this.sessionOptions.devTools ?? false,
+        });
+        // Invoke lifecycle callbacks
+        const cb = this.callbacks;
+        try {
+            cb.onEvent?.(enrichedEvent);
+            // Call specific callbacks based on event type
+            const eventType = enrichedEvent.type;
+            if (eventType === "tick_start") {
+                cb.onTickStart?.(enrichedEvent.tick, enrichedEvent.executionId);
+            }
+            else if (eventType === "tick_end") {
+                cb.onTickEnd?.(enrichedEvent.tick, enrichedEvent.usage);
+            }
+        }
+        catch {
+            // Callbacks should not throw, but don't let them break execution
+        }
+        // Emit via EventEmitter
+        this.emit("event", enrichedEvent);
+        // Also queue for AsyncIterable consumers
+        if (this._eventResolvers.length > 0) {
+            const resolve = this._eventResolvers.shift();
+            resolve({ value: enrichedEvent, done: false });
+        }
+        else {
+            this._eventQueue.push(enrichedEvent);
+        }
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Snapshot & Inspect
+    // ════════════════════════════════════════════════════════════════════════
+    snapshot() {
+        return {
+            version: "1.0",
+            sessionId: this.id,
+            tick: this._tick,
+            timeline: this._previousOutput?.timeline ?? null,
+            componentState: this.serializeFiberTree(), // Serialized fiber tree with hook states
+            usage: { ...this._totalUsage },
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Set the hibernate callback.
+     * Called by the App when registering this session.
+     * @internal
+     */
+    setHibernateCallback(callback) {
+        this._hibernateCallback = 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;
+    }
+    inspect() {
+        // Get fiber summary for component/hook stats
+        const fiberSummary = this.getFiberSummary();
+        // Get component names from fiber tree
+        const componentNames = this.collectComponentNames();
+        // Get last tick's tool data from snapshots if available
+        const lastSnapshot = this._snapshots.length > 0 ? this._snapshots[this._snapshots.length - 1] : null;
+        return {
+            id: this.id,
+            status: this._status,
+            currentTick: this._tick,
+            queuedMessages: [...this._queuedMessages],
+            currentPhase: this._status === "running" ? "model" : undefined, // Approximate
+            isAborted: this._isAborted,
+            lastOutput: this._previousOutput,
+            lastModelOutput: this._lastModelOutput,
+            lastToolCalls: lastSnapshot?.tools.calls ?? [],
+            lastToolResults: lastSnapshot?.tools.results.map((r) => ({
+                toolUseId: r.toolUseId,
+                name: r.name,
+                success: r.success,
+            })) ?? [],
+            totalUsage: { ...this._totalUsage },
+            tickCount: this._totalUsage.ticks ?? 0,
+            components: {
+                count: fiberSummary.componentCount,
+                names: componentNames,
+            },
+            hooks: {
+                count: fiberSummary.hookCount,
+                // React manages hooks internally, so detailed type info isn't available
+                byType: {},
+            },
+        };
+    }
+    /**
+     * Collect unique component names from the fiber tree.
+     */
+    collectComponentNames() {
+        if (!this.compiler)
+            return [];
+        const tree = this.compiler.serializeFiberTree();
+        if (!tree)
+            return [];
+        const names = new Set();
+        const collectNames = (node) => {
+            // Skip host primitives (Section, Message, etc.) and fragments
+            if (!node.type.startsWith("agentick.") && node.type !== "Fragment") {
+                names.add(node.type);
+            }
+            for (const child of node.children) {
+                collectNames(child);
+            }
+        };
+        collectNames(tree);
+        return Array.from(names);
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Recording (stub - can add back if needed)
+    // ════════════════════════════════════════════════════════════════════════
+    startRecording(mode) {
+        this._recordingMode = mode;
+        this._recordingStartedAt = new Date().toISOString();
+        this._snapshots = [];
+        this._recording = {
+            sessionId: this.id,
+            startedAt: this._recordingStartedAt,
+            config: {
+                componentName: this.Component.name || "Anonymous",
+                initialProps: {},
+                maxTicks: this.appOptions.maxTicks ?? 10,
+                mode,
+            },
+            inputs: [],
+            snapshots: this._snapshots,
+            summary: {
+                tickCount: 0,
+                totalDuration: 0,
+                totalUsage: { inputTokens: 0, outputTokens: 0, totalTokens: 0, ticks: 0 },
+                finalStatus: "running",
+            },
+        };
+    }
+    stopRecording() {
+        if (this._recording) {
+            this._recording.endedAt = new Date().toISOString();
+            this._recording.summary.tickCount = this._snapshots.length;
+            this._recording.summary.totalUsage = { ...this._totalUsage };
+            this._recording.summary.finalStatus =
+                this._status === "idle" ? "completed" : this._status;
+        }
+        this._recordingMode = null;
+    }
+    getRecording() {
+        if (this._recording) {
+            // Update summary with current state
+            this._recording.summary.tickCount = this._snapshots.length;
+            this._recording.summary.totalUsage = { ...this._totalUsage };
+        }
+        return this._recording;
+    }
+    getSnapshotAt(tick) {
+        return this._snapshots.find((s) => s.tick === tick) ?? null;
+    }
+    /**
+     * Record a tick snapshot for time-travel debugging.
+     */
+    recordSnapshot(tickNumber, tickStartTime, tickData) {
+        if (!this._recordingMode)
+            return;
+        const { formatted, modelId, modelInput, modelStartTime, modelOutput, toolCalls = [], toolResults = [], toolStartTime, shouldContinue = false, stopReason, } = tickData;
+        const now = Date.now();
+        const fiberSummary = this.getFiberSummary();
+        // Extract COM data from formatted input
+        const comSections = {};
+        if (formatted?.sections) {
+            for (const [id, section] of Object.entries(formatted.sections)) {
+                comSections[id] = {
+                    content: typeof section.content === "string" ? section.content : JSON.stringify(section.content),
+                    priority: section.priority,
+                };
+            }
+        }
+        // Extract tool definitions (ToolDefinition has name/description/input directly)
+        const comTools = (formatted?.tools ?? []).map((t) => ({
+            name: t.name ?? "unknown",
+            description: t.description,
+            inputSchema: t.input,
+        }));
+        const snapshot = {
+            sessionId: this.id,
+            tick: tickNumber,
+            timestamp: new Date().toISOString(),
+            duration: now - tickStartTime,
+            fiber: {
+                tree: this._recordingMode === "full" ? this.serializeFiberTree() : null,
+                summary: {
+                    componentCount: fiberSummary.componentCount,
+                    hookCount: fiberSummary.hookCount,
+                    hooksByType: fiberSummary.hooksByType,
+                },
+            },
+            com: {
+                sections: comSections,
+                timeline: formatted?.timeline ?? [],
+                tools: comTools,
+                modelId: modelId ?? null,
+                metadata: formatted?.metadata ?? {},
+            },
+            model: {
+                input: {
+                    formatted: modelInput ?? "",
+                    tokenCount: undefined, // Could be populated if available
+                },
+                output: {
+                    content: modelOutput?.message?.content ?? [],
+                    stopReason: modelOutput?.stopReason ?? "unknown",
+                    tokenCount: modelOutput?.usage?.outputTokens,
+                },
+                latency: modelStartTime ? (toolStartTime ?? now) - modelStartTime : 0,
+            },
+            tools: {
+                calls: toolCalls,
+                results: toolResults.map((r) => ({
+                    toolUseId: r.toolUseId,
+                    name: r.name ?? "unknown",
+                    success: !r.error,
+                    content: r.content,
+                })),
+                totalDuration: toolStartTime ? now - toolStartTime : 0,
+            },
+            execution: {
+                phase: "complete",
+                shouldContinue,
+                stopReason,
+                queuedMessages: [...this._queuedMessages],
+                executionId: Context.tryGet()?.executionId,
+            },
+        };
+        this._snapshots.push(snapshot);
+    }
+    serializeFiberTree() {
+        if (!this.compiler)
+            return null;
+        return this.compiler.serializeFiberTree();
+    }
+    getFiberSummary() {
+        if (!this.compiler) {
+            return { componentCount: 0, hookCount: 0, effectCount: 0, depth: 0, hooksByType: {} };
+        }
+        return this.compiler.getFiberSummary();
+    }
+    /**
+     * Broadcast context utilization info via the session:context channel.
+     * Enables real-time context tracking in UI via useContextInfo() hook.
+     */
+    broadcastContextInfo(executionId, modelId, modelMetadata, tickUsage, tick, cumulativeUsage, timestampStr) {
+        // Get context info (effective = adapter metadata merged with catalog)
+        const modelInfo = getEffectiveModelInfo({
+            model: modelId,
+            provider: modelMetadata?.provider,
+            contextWindow: modelMetadata?.contextWindow,
+            maxOutputTokens: modelMetadata?.maxOutputTokens,
+        }, modelId);
+        const inputTokens = tickUsage?.inputTokens ?? 0;
+        const outputTokens = tickUsage?.outputTokens ?? 0;
+        const totalTokens = tickUsage?.totalTokens ?? inputTokens + outputTokens;
+        // Calculate utilization if we have context window info
+        const utilization = modelInfo?.contextWindow
+            ? (getContextUtilization(modelId, inputTokens) ?? undefined)
+            : undefined;
+        const payload = {
+            modelId,
+            modelName: modelInfo?.name,
+            provider: modelInfo?.provider || modelMetadata?.provider,
+            contextWindow: modelInfo?.contextWindow,
+            inputTokens,
+            outputTokens,
+            totalTokens,
+            utilization,
+            maxOutputTokens: modelInfo?.maxOutputTokens,
+            supportsVision: modelInfo?.supportsVision,
+            supportsToolUse: modelInfo?.supportsToolUse,
+            isReasoningModel: modelInfo?.isReasoningModel,
+            tick,
+            cumulativeUsage: {
+                inputTokens: cumulativeUsage.inputTokens,
+                outputTokens: cumulativeUsage.outputTokens,
+                totalTokens: cumulativeUsage.totalTokens,
+                ticks: cumulativeUsage.ticks ?? tick,
+            },
+            timestamp: timestampStr,
+        };
+        // Publish to channel (if channel service is available)
+        const ctx = Context.tryGet();
+        if (ctx?.channels) {
+            try {
+                ctx.channels.publish(ctx, FrameworkChannels.CONTEXT, {
+                    type: "context_update",
+                    payload,
+                });
+            }
+            catch {
+                // Silently ignore if channel publish fails
+            }
+        }
+        // Also emit as DevTools event for DevTools UI
+        if (devToolsEmitter.hasSubscribers()) {
+            devToolsEmitter.emitEvent({
+                type: "context_update",
+                executionId,
+                sessionId: this.id,
+                sequence: ++this._sequence,
+                timestamp: Date.now(),
+                modelId: payload.modelId,
+                modelName: payload.modelName,
+                provider: payload.provider,
+                contextWindow: payload.contextWindow,
+                inputTokens: payload.inputTokens,
+                outputTokens: payload.outputTokens,
+                totalTokens: payload.totalTokens,
+                utilization: payload.utilization,
+                maxOutputTokens: payload.maxOutputTokens,
+                supportsVision: payload.supportsVision,
+                supportsToolUse: payload.supportsToolUse,
+                isReasoningModel: payload.isReasoningModel,
+                tick: payload.tick,
+                cumulativeUsage: payload.cumulativeUsage,
+            });
+        }
+        // Update compiler's contextInfoStore so JSX components can access via useContextInfo
+        if (this.compiler) {
+            this.compiler.contextInfoStore.update({
+                modelId: payload.modelId,
+                modelName: payload.modelName,
+                provider: payload.provider,
+                contextWindow: payload.contextWindow,
+                inputTokens: payload.inputTokens,
+                outputTokens: payload.outputTokens,
+                totalTokens: payload.totalTokens,
+                utilization: payload.utilization,
+                maxOutputTokens: payload.maxOutputTokens,
+                supportsVision: payload.supportsVision,
+                supportsToolUse: payload.supportsToolUse,
+                isReasoningModel: payload.isReasoningModel,
+                tick: payload.tick,
+                cumulativeUsage: payload.cumulativeUsage,
+                estimatedContextTokens: this._estimatedContextTokens,
+            });
+        }
+        // Emit as stream event for client-side React consumption
+        this.emitEvent({
+            type: "context_update",
+            modelId: payload.modelId,
+            modelName: payload.modelName,
+            provider: payload.provider,
+            contextWindow: payload.contextWindow,
+            inputTokens: payload.inputTokens,
+            outputTokens: payload.outputTokens,
+            totalTokens: payload.totalTokens,
+            utilization: payload.utilization,
+            maxOutputTokens: payload.maxOutputTokens,
+            supportsVision: payload.supportsVision,
+            supportsToolUse: payload.supportsToolUse,
+            isReasoningModel: payload.isReasoningModel,
+            cumulativeUsage: payload.cumulativeUsage,
+            tick,
+            timestamp: timestampStr,
+        });
+    }
+    /**
+     * Emit a fiber_snapshot event to DevTools after each tick.
+     * This enables the Fiber Tree panel in DevTools to show component hierarchy and hook values.
+     *
+     * @param tick - The tick number
+     * @param executionId - The execution ID
+     * @param compiled - Optional compiled structure for token estimation
+     */
+    emitFiberSnapshot(tick, executionId, compiled) {
+        // Only emit if DevTools has subscribers (avoid serialization overhead)
+        if (!devToolsEmitter.hasSubscribers())
+            return;
+        try {
+            const tree = this.serializeFiberTree();
+            const summary = this.getFiberSummary();
+            // Compute token summary if compiled structure is available
+            let tokenSummary;
+            let compiledPreview;
+            if (compiled) {
+                try {
+                    const tokens = computeTokenSummary(compiled);
+                    tokenSummary = {
+                        system: tokens.system,
+                        messages: tokens.messages,
+                        tools: tokens.tools,
+                        ephemeral: tokens.ephemeral,
+                        total: tokens.total,
+                        byComponent: Object.fromEntries(tokens.byComponent),
+                    };
+                    // Get system prompt preview (first 200 chars)
+                    let systemPrompt;
+                    if (compiled.systemEntries.length > 0) {
+                        const firstSystem = compiled.systemEntries[0];
+                        if (firstSystem.content.length > 0) {
+                            const firstBlock = firstSystem.content[0];
+                            if ("text" in firstBlock && typeof firstBlock.text === "string") {
+                                systemPrompt = firstBlock.text.slice(0, 200);
+                            }
+                        }
+                    }
+                    compiledPreview = {
+                        systemPrompt,
+                        messageCount: compiled.timelineEntries.length,
+                        toolCount: compiled.tools.length,
+                        ephemeralCount: compiled.ephemeral.length,
+                    };
+                }
+                catch {
+                    // Ignore token estimation errors
+                }
+            }
+            const event = {
+                type: "fiber_snapshot",
+                sessionId: this.id,
+                executionId,
+                sequence: ++this._sequence, // Use session's sequence counter for DevTools events
+                tick,
+                timestamp: Date.now(),
+                tree: tree,
+                summary: summary,
+                tokenSummary,
+                compiledPreview,
+            };
+            devToolsEmitter.emitEvent(event);
+        }
+        catch {
+            // Silently ignore serialization errors - DevTools is optional
+        }
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Close
+    // ════════════════════════════════════════════════════════════════════════
+    close() {
+        if (this._status === "closed")
+            return;
+        this._status = "closed";
+        // Close all child sessions
+        for (const child of [...this._children]) {
+            child.close();
+        }
+        this._children = [];
+        this.sessionAbortController.abort("Session closed");
+        this.executionAbortController?.abort("Session closed");
+        // Complete any pending event iterators
+        this._executionComplete = true;
+        for (const resolve of this._eventResolvers) {
+            resolve({ value: undefined, done: true });
+        }
+        this._eventResolvers = [];
+        // Dispose scheduler (cancels pending work and cleans up signal)
+        if (this.scheduler) {
+            this.scheduler.dispose();
+            this.scheduler = null;
+        }
+        // Unmount compiler if it exists
+        if (this.compiler) {
+            this.compiler.unmount().catch(() => { });
+            this.compiler = null;
+        }
+        this.ctx = null;
+        this.structureRenderer = null;
+        this.emit("close", this.id);
+    }
+    // ════════════════════════════════════════════════════════════════════════
+    // Internal: Execution
+    // ════════════════════════════════════════════════════════════════════════
+    async runWithContext(fn) {
+        const current = Context.tryGet();
+        const baseContext = this._capturedContext || current;
+        // Create a channel service that wraps session channels
+        // This allows tools to publish events via Context.get().channels
+        const channelService = {
+            getChannel: (_ctx, channelName) => this.channel(channelName),
+            publish: (_ctx, channelName, event) => {
+                this.channel(channelName).publish({ ...event, channel: channelName });
+            },
+            subscribe: (_ctx, channelName, handler) => {
+                return this.channel(channelName).subscribe(handler);
+            },
+            waitForResponse: (_ctx, channelName, requestId, timeoutMs) => {
+                return this.channel(channelName).waitForResponse(requestId, timeoutMs);
+            },
+        };
+        // Session-specific context fields for DevTools enrichment
+        const sessionContext = {
+            sessionId: this.id,
+            rootComponent: this.Component.name || "Agent",
+            devToolsEnabled: this.sessionOptions.devTools ?? false,
+            channels: channelService,
+        };
+        if (!baseContext) {
+            // No base context - create minimal context with session fields
+            return Context.run(Context.create(sessionContext), fn);
+        }
+        // Merge base, current, and session context
+        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.
+     *
+     * This is where the magic happens:
+     * 1. Setup compilation infrastructure (COM, FiberCompiler)
+     * 2. Loop: compile -> model -> tools -> ingest
+     * 3. Return result
+     */
+    async executeTick(props, options) {
+        if (this._status === "closed") {
+            throw new Error("Session is closed");
+        }
+        const signal = this.executionAbortController?.signal ?? this.sessionAbortController.signal;
+        if (signal.aborted) {
+            throw new AbortError("Session aborted", signal.reason);
+        }
+        this._status = "running";
+        this._executionComplete = false;
+        this._lastProps = props;
+        // Clear _currentOutput from previous execution to prevent stale data
+        // from being included in useConversationHistory() via state.current
+        this._currentOutput = null;
+        const executionId = Context.tryGet()?.executionId || randomUUID();
+        this._currentExecutionId = executionId;
+        const maxTicks = options?.maxTicks ?? this.sessionOptions.maxTicks ?? this.appOptions.maxTicks ?? 10;
+        const timestamp = () => new Date().toISOString();
+        // Create root JSX element
+        const rootElement = jsx(this.Component, props);
+        // Setup or reuse compilation infrastructure
+        await this.ensureCompilationInfrastructure(rootElement);
+        // Transfer queued messages to COM
+        if (this._queuedMessages.length > 0 && this.ctx) {
+            this.log.debug({ count: this._queuedMessages.length }, "Transferring queued messages to COM");
+            for (const msg of this._queuedMessages) {
+                this.log.debug({ role: msg.role }, "Queuing message to COM");
+                this.ctx.queueMessage({
+                    id: randomUUID(),
+                    type: "message",
+                    content: msg,
+                });
+            }
+            this._queuedMessages = [];
+            this.log.debug({ comQueuedCount: this.ctx.getQueuedMessages().length }, "COM queued messages after transfer");
+        }
+        // Track state for this execution
+        const usage = {
+            inputTokens: 0,
+            outputTokens: 0,
+            totalTokens: 0,
+            ticks: 0,
+        };
+        let stopReason;
+        let output;
+        const outputs = {};
+        const responseChunks = [];
+        const toolExecutor = new ToolExecutor();
+        this.emitEvent({
+            type: "execution_start",
+            executionId,
+            timestamp: timestamp(),
+        });
+        try {
+            // Tick loop
+            let shouldContinue = true;
+            while (shouldContinue && this._tick <= maxTicks) {
+                if (signal.aborted) {
+                    throw new AbortError("Execution aborted", signal.reason);
+                }
+                const currentTick = this._tick;
+                const tickStartTime = Date.now();
+                this.emitEvent({
+                    type: "tick_start",
+                    tick: currentTick,
+                    timestamp: timestamp(),
+                });
+                // Phase 1: Compile
+                const compiled = await this.compileTick(rootElement);
+                // Emit compiled context to DevTools
+                // Extract system text from COMTimelineEntry[]
+                const systemText = compiled.formatted?.system
+                    ?.map((entry) => {
+                    const content = entry.message?.content ?? entry.content;
+                    if (Array.isArray(content)) {
+                        return content
+                            .filter((b) => b.type === "text")
+                            .map((b) => b.text)
+                            .join("\n");
+                    }
+                    return String(content ?? "");
+                })
+                    .filter(Boolean)
+                    .join("\n\n");
+                this.emitEvent({
+                    type: "compiled",
+                    tick: currentTick,
+                    timestamp: timestamp(),
+                    // Rendered output (existing)
+                    system: systemText || undefined,
+                    messages: compiled.formatted?.timeline,
+                    tools: compiled.tools?.map((t) => ({
+                        name: t.metadata?.name ?? t.name,
+                        description: t.metadata?.description ?? t.description,
+                    })),
+                    // Raw compiled structure (before rendering)
+                    rawCompiled: compiled.rawCompiled
+                        ? {
+                            sections: Object.fromEntries(compiled.rawCompiled.sections ?? new Map()),
+                            timelineEntries: compiled.rawCompiled.timelineEntries,
+                            systemEntries: compiled.rawCompiled.systemEntries,
+                            tools: compiled.rawCompiled.tools,
+                            ephemeral: compiled.rawCompiled.ephemeral,
+                        }
+                        : undefined,
+                    // Formatted COMInput (after rendering)
+                    formattedInput: compiled.formatted,
+                });
+                if (compiled.shouldStop) {
+                    stopReason = compiled.stopReason;
+                    this.emitEvent({
+                        type: "tick_end",
+                        tick: currentTick,
+                        shouldContinue: false,
+                        timestamp: timestamp(),
+                    });
+                    // Emit fiber snapshot to DevTools
+                    this.emitFiberSnapshot(currentTick, executionId, compiled.rawCompiled);
+                    // Clear queued messages - they were made available during compilation
+                    this.ctx?.clearQueuedMessages();
+                    break;
+                }
+                // Phase 2: Model
+                const model = this.appOptions.model ?? compiled.model;
+                if (!model) {
+                    throw new Error("No model configured. Add a <Model> component or pass model in options.");
+                }
+                if (signal.aborted) {
+                    throw new AbortError("Execution aborted", signal.reason);
+                }
+                const modelInput = compiled.modelInput ?? compiled.formatted;
+                const modelStartTime = Date.now();
+                // Emit model request to DevTools
+                // modelInput is the Agentick ModelInput format (after fromEngineState transformation)
+                this.emitEvent({
+                    type: "model_request",
+                    tick: currentTick,
+                    timestamp: timestamp(),
+                    modelId: model?.metadata?.id ?? model?.metadata?.model,
+                    // ModelInput: Agentick's model input format
+                    input: modelInput,
+                    // Stage marker for pipeline visualization
+                    stage: "model_input",
+                });
+                // Emit provider request to DevTools (Stage 4: what the SDK actually receives)
+                if (model.getProviderInput) {
+                    const providerInput = await model.getProviderInput(modelInput);
+                    this.emitEvent({
+                        type: "provider_request",
+                        tick: currentTick,
+                        timestamp: timestamp(),
+                        modelId: model?.metadata?.id ?? model?.metadata?.model,
+                        provider: model?.metadata?.provider,
+                        providerInput,
+                    });
+                }
+                // 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 = {
+                                messages: [messageEvent.message],
+                                message: messageEvent.message,
+                                stopReason: messageEvent.stopReason,
+                                usage: messageEvent.usage,
+                                raw: messageEvent.raw, // Reconstructed provider response from adapter
+                            };
+                        }
+                    }
+                    // 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");
+                        }
+                    }
+                }
+                else {
+                    // Procedure returns ExecutionHandle by default - access .result for actual return value
+                    // Handle both real procedures (with .result) and mock functions (direct value)
+                    const generateResult = model.generate(modelInput);
+                    modelOutput =
+                        generateResult && "result" in generateResult
+                            ? await generateResult.result
+                            : await generateResult;
+                }
+                // Extract text from model output
+                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);
+                    }
+                }
+                // Update usage
+                if (modelOutput?.usage) {
+                    usage.inputTokens += modelOutput.usage.inputTokens ?? 0;
+                    usage.outputTokens += modelOutput.usage.outputTokens ?? 0;
+                    usage.totalTokens += modelOutput.usage.totalTokens ?? 0;
+                }
+                if (signal.aborted) {
+                    throw new AbortError("Execution aborted", signal.reason);
+                }
+                // Convert model output to engine format
+                if (!model.toEngineState) {
+                    throw new Error("Model missing toEngineState method");
+                }
+                const response = await model.toEngineState(modelOutput);
+                // Emit model response to DevTools with full pipeline visibility
+                this.emitEvent({
+                    type: "model_response",
+                    tick: currentTick,
+                    timestamp: timestamp(),
+                    // Provider output (raw from SDK - may be reconstructed for streaming)
+                    providerOutput: modelOutput?.raw,
+                    // ModelOutput (normalized Agentick format)
+                    modelOutput: {
+                        model: modelOutput?.model,
+                        message: modelOutput?.message,
+                        usage: modelOutput?.usage,
+                        stopReason: modelOutput?.stopReason,
+                        toolCalls: modelOutput?.toolCalls,
+                    },
+                    // Engine state (how it's ingested into timeline)
+                    engineState: {
+                        newTimelineEntries: response.newTimelineEntries,
+                        toolCalls: response.toolCalls,
+                        shouldStop: response.shouldStop,
+                        stopReason: response.stopReason,
+                    },
+                });
+                // Track last model output for inspection
+                if (modelOutput?.message) {
+                    this._lastModelOutput = {
+                        content: modelOutput.message.content ?? [],
+                        stopReason: modelOutput.stopReason ?? "unknown",
+                    };
+                }
+                // Phase 3: Tools
+                let toolResults = [];
+                let toolStartTime;
+                if (response.toolCalls?.length && this.ctx) {
+                    toolStartTime = Date.now();
+                    for (const call of response.toolCalls) {
+                        const toolCallTimestamp = timestamp();
+                        this.emitEvent({
+                            type: "tool_call",
+                            callId: call.id,
+                            blockIndex: 0,
+                            name: call.name,
+                            input: call.input,
+                            startedAt: toolCallTimestamp,
+                            completedAt: toolCallTimestamp,
+                        });
+                    }
+                    toolResults = await this.executeTools(toolExecutor, response.toolCalls, compiled.tools, outputs, currentTick, timestamp);
+                }
+                // Phase 4: Ingest & Tick End Callbacks
+                const ingestResult = await this.ingestTickResult(response, toolResults);
+                // Build TickResult for useTickEnd/useContinuation callbacks
+                // Extract text from model response
+                let tickText;
+                if (modelOutput?.message?.content) {
+                    const textContent = modelOutput.message.content.find((b) => b.type === "text");
+                    if (textContent && "text" in textContent) {
+                        tickText = textContent.text;
+                    }
+                }
+                // Build TickResult with data and control methods
+                const tickResult = {
+                    tick: currentTick,
+                    text: tickText,
+                    content: modelOutput?.message?.content ?? [],
+                    toolCalls: response.toolCalls ?? [],
+                    toolResults,
+                    stopReason: modelOutput?.stopReason,
+                    usage: modelOutput?.usage,
+                    timeline: ingestResult.timeline,
+                    stop: (reasonOrOptions) => {
+                        if (typeof reasonOrOptions === "string") {
+                            this.ctx?.requestStop({ reason: reasonOrOptions });
+                        }
+                        else {
+                            this.ctx?.requestStop(reasonOrOptions ?? {});
+                        }
+                    },
+                    continue: (reasonOrOptions) => {
+                        if (typeof reasonOrOptions === "string") {
+                            this.ctx?.requestContinue({ reason: reasonOrOptions });
+                        }
+                        else {
+                            this.ctx?.requestContinue(reasonOrOptions ?? {});
+                        }
+                    },
+                };
+                // Run useTickEnd/useContinuation callbacks
+                // These can call tickResult.stop() or tickResult.continue() to influence continuation
+                const tickEndState = {
+                    tick: currentTick,
+                    previous: this._previousOutput ?? undefined,
+                    current: this._currentOutput,
+                    queuedMessages: [],
+                    stop: () => { }, // No-op at tick end - use tickResult.stop() instead
+                };
+                await this.compiler?.notifyTickEnd(tickEndState, tickResult);
+                // Resolve final tick control using COM's priority-based system
+                // This considers: explicit stop/continue requests from callbacks > default behavior
+                const defaultStatus = ingestResult.shouldContinue ? "continue" : "completed";
+                const tickDecision = this.ctx?._resolveTickControl(defaultStatus, ingestResult.stopReason) ?? { status: defaultStatus };
+                shouldContinue = tickDecision.status === "continue";
+                // Get actual model ID: prefer response model, then metadata.model, then metadata.id
+                const actualModelId = modelOutput?.model || model?.metadata?.model || model?.metadata?.id || "unknown";
+                this.emitEvent({
+                    type: "tick_end",
+                    tick: currentTick,
+                    shouldContinue,
+                    usage: modelOutput?.usage,
+                    stopReason: modelOutput?.stopReason,
+                    model: actualModelId,
+                    timestamp: timestamp(),
+                });
+                // Broadcast context utilization via channel
+                this.broadcastContextInfo(executionId, actualModelId, model?.metadata, modelOutput?.usage, currentTick, usage, timestamp());
+                // Emit fiber snapshot to DevTools
+                this.emitFiberSnapshot(currentTick, executionId, compiled.rawCompiled);
+                // Clear queued messages after tick completes - they've been processed
+                this.ctx?.clearQueuedMessages();
+                // Record snapshot if recording is enabled
+                this.recordSnapshot(currentTick, tickStartTime, {
+                    formatted: compiled.formatted,
+                    modelId: model?.metadata?.id ?? model?.metadata?.model ?? null,
+                    modelInput: typeof modelInput === "string" ? modelInput : JSON.stringify(modelInput),
+                    modelStartTime,
+                    modelOutput,
+                    toolCalls: response.toolCalls ?? [],
+                    toolResults,
+                    toolStartTime,
+                    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._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(""),
+                outputs,
+                usage,
+                stopReason,
+            };
+            this.emitEvent({
+                type: "result",
+                result: resultPayload,
+                timestamp: timestamp(),
+            });
+        }
+        finally {
+            this._executionComplete = true;
+            // Ensure queued messages are cleared even on error/abort paths
+            // (normal path already clears at tick_end, this is a safety net)
+            this.ctx?.clearQueuedMessages();
+            this.emitEvent({
+                type: "execution_end",
+                executionId,
+                stopReason,
+                aborted: this._isAborted,
+                usage,
+                output: output ?? null,
+                timestamp: timestamp(),
+            });
+            // 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) {
+                const allMessages = output.timeline
+                    .filter((entry) => entry.message)
+                    .map((entry) => entry.message);
+                // Only publish if there are new messages
+                if (allMessages.length > this._lastPublishedTimelineLength) {
+                    const newMessages = allMessages.slice(this._lastPublishedTimelineLength);
+                    this._lastPublishedTimelineLength = allMessages.length;
+                    this.channel("timeline").publish({
+                        type: "timeline_delta",
+                        channel: "timeline",
+                        payload: {
+                            messages: newMessages, // Only new messages
+                            totalCount: allMessages.length, // For sync verification
+                            tick: this._tick,
+                        },
+                    });
+                }
+            }
+            // Clear execution ID after emitting execution_end
+            this._currentExecutionId = null;
+            for (const resolve of this._eventResolvers) {
+                resolve({ value: undefined, done: true });
+            }
+            this._eventResolvers = [];
+            this._status = "idle";
+        }
+        return {
+            response: responseChunks.join(""),
+            outputs,
+            usage,
+            stopReason,
+            raw: output,
+        };
+    }
+    /**
+     * Ensure compilation infrastructure exists or reset for new run.
+     */
+    async ensureCompilationInfrastructure(_rootElement) {
+        if (this.ctx && this.compiler && this.structureRenderer) {
+            // Reuse existing - reset for new run
+            this.ctx.clear();
+            this._tick = 1;
+            return;
+        }
+        // Create new infrastructure
+        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
+        }
+        // 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, {
+            onReconcile: (event) => {
+                this.emit("reconcile", event);
+            },
+        });
+        // Wire compiler state changes to scheduler
+        this.compiler.setReconcileCallback((reason) => {
+            this.scheduler.schedule(reason ?? "compiler recompile request");
+        });
+        // Wire COM recompile requests to scheduler
+        // This unifies COM state signals with the reactive model
+        this.ctx.setRecompileCallback((reason) => {
+            this.scheduler.schedule(reason ?? "COM recompile request");
+        });
+        // Wire COM spawn delegate to session's spawn Procedure
+        this.ctx.setSpawnCallback((agent, input) => this.spawn(agent, input));
+        this.structureRenderer = new StructureRenderer(this.ctx);
+        this.structureRenderer.setDefaultRenderer(new MarkdownRenderer());
+        // Register tools from appOptions
+        if (this.appOptions.tools) {
+            for (const tool of this.appOptions.tools) {
+                this.ctx.addTool(tool);
+            }
+        }
+        // Notify compiler that compilation is starting
+        await this.compiler.notifyStart();
+    }
+    /**
+     * Compile a single tick.
+     */
+    async compileTick(rootElement) {
+        if (!this.ctx || !this.compiler || !this.structureRenderer) {
+            throw new Error("Compilation infrastructure not initialized");
+        }
+        // Clear COM for this tick
+        this.ctx.clear();
+        // NOTE: Previous timeline entries are NOT injected into COM here.
+        // They are merged in at formatInput time. This keeps the architecture declarative:
+        // - JSX compilation produces CompiledStructure with NEW entries
+        // - formatInput merges previousTimeline + new entries
+        // - No imperative accumulation during render
+        // Re-register tools
+        if (this.appOptions.tools) {
+            for (const tool of this.appOptions.tools) {
+                this.ctx.addTool(tool);
+            }
+        }
+        // Get queued messages for TickState - these are NEW messages for this tick
+        const queuedMessages = this.ctx.getQueuedMessages();
+        this.log.debug({ queuedCount: queuedMessages.length }, "Queued messages available for TickState");
+        // Prepare tick state
+        const tickState = {
+            tick: this._tick,
+            previous: this._previousOutput ?? undefined,
+            current: this._currentOutput,
+            queuedMessages: queuedMessages,
+            stop: (reason) => {
+                tickState.stopReason = reason;
+            },
+        };
+        // Notify compiler of tick start
+        await this.compiler.notifyTickStart(tickState);
+        // Create tick control for useTick() hook
+        const tickControl = {
+            requestTick: () => {
+                // For now, requesting a tick schedules the next iteration
+                // This will be used by the reactive model for external triggers
+                this.emit("tick:request");
+            },
+            cancelTick: () => {
+                this.emit("tick:cancel");
+            },
+            status: this._status,
+            tickCount: this._tick,
+        };
+        // Create channel accessor for useChannel() hook
+        const getChannel = (name) => this.channel(name);
+        // 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
+            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
+            this.scheduler?.exitTick();
+        }
+        // Apply compiled structure (sections, tools, metadata - but NOT timeline entries)
+        await this.structureRenderer.apply(compiled);
+        // 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
+        const model = this.ctx.getModel?.();
+        let modelInput;
+        if (model?.fromEngineState) {
+            modelInput = await model.fromEngineState(formatted);
+        }
+        // Get tools
+        const tools = this.ctx.getTools?.() ?? [];
+        // Check for stop
+        const stopReason = tickState.stopReason;
+        return {
+            formatted,
+            model,
+            modelInput,
+            tools: tools,
+            shouldStop: !!stopReason,
+            stopReason,
+            rawCompiled: compiled,
+        };
+    }
+    /**
+     * Execute tools and emit results.
+     */
+    async executeTools(executor, toolCalls, configTools, outputs, currentTick, timestamp) {
+        const results = [];
+        const executableTools = configTools.filter((t) => "run" in t);
+        for (const call of toolCalls) {
+            const startedAt = timestamp();
+            // Check if OUTPUT tool
+            const tool = executableTools.find((t) => t.metadata?.name === call.name);
+            const isOutputTool = tool && tool.metadata?.type === "output";
+            if (isOutputTool) {
+                outputs[call.name] = call.input;
+                const completedAt = timestamp();
+                this.emitEvent({
+                    type: "tool_result",
+                    callId: call.id,
+                    name: call.name,
+                    result: call.input,
+                    isError: false,
+                    executedBy: "engine",
+                    startedAt,
+                    completedAt,
+                });
+                continue;
+            }
+            // Execute tool
+            try {
+                const result = await executor.processToolWithConfirmation(call, this.ctx, executableTools);
+                results.push(result.result);
+                const completedAt = timestamp();
+                this.emitEvent({
+                    type: "tool_result",
+                    callId: result.result.toolUseId,
+                    name: result.result.name,
+                    result: result.result,
+                    isError: !result.result.success,
+                    executedBy: "engine",
+                    startedAt,
+                    completedAt,
+                });
+            }
+            catch (error) {
+                const errorResult = {
+                    id: randomUUID(),
+                    toolUseId: call.id,
+                    name: call.name,
+                    success: false,
+                    content: [
+                        {
+                            type: "text",
+                            text: `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                };
+                results.push(errorResult);
+                const completedAt = timestamp();
+                this.emitEvent({
+                    type: "tool_result",
+                    callId: call.id,
+                    name: call.name,
+                    result: errorResult,
+                    isError: true,
+                    executedBy: "engine",
+                    startedAt,
+                    completedAt,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Ingest model response and tool results.
+     */
+    async ingestTickResult(response, toolResults) {
+        if (!this.ctx || !this.compiler) {
+            throw new Error("Compilation infrastructure not initialized");
+        }
+        // Convert queued user messages to timeline entries BEFORE clearing
+        // This preserves the user message in the conversation history
+        const queuedMessages = this.ctx.getQueuedMessages();
+        const existingTimeline = this.ctx.getTimeline();
+        const existingByMessage = new Map();
+        for (const entry of existingTimeline) {
+            if (entry.message) {
+                existingByMessage.set(entry.message, entry);
+            }
+        }
+        const userEntries = [];
+        const newUserEntries = [];
+        for (const queued of queuedMessages) {
+            if (queued.type !== "user" || !queued.content)
+                continue;
+            const message = queued.content;
+            const existing = existingByMessage.get(message);
+            if (existing) {
+                userEntries.push(existing);
+                continue;
+            }
+            const entry = {
+                kind: "message",
+                message,
+                tags: ["user_input"],
+            };
+            userEntries.push(entry);
+            newUserEntries.push(entry);
+        }
+        // Build tool result entries
+        const toolResultEntries = toolResults.length > 0
+            ? [
+                {
+                    kind: "message",
+                    message: {
+                        role: "tool",
+                        content: toolResults.map((r) => ({
+                            id: r.id,
+                            type: "tool_result",
+                            toolUseId: r.toolUseId,
+                            name: r.name,
+                            content: r.content || [],
+                            isError: !r.success,
+                        })),
+                    },
+                    tags: ["tool_output"],
+                },
+            ]
+            : [];
+        // Build current output - user messages first, then assistant response, then tool results
+        const current = {
+            timeline: [...userEntries, ...(response.newTimelineEntries || []), ...toolResultEntries],
+            toolCalls: response.toolCalls,
+            toolResults,
+        };
+        // Add entries to COM - user entries first, then assistant response
+        for (const entry of newUserEntries) {
+            this.ctx.addTimelineEntry(entry);
+        }
+        if (response.newTimelineEntries) {
+            for (const entry of response.newTimelineEntries) {
+                this.ctx.addTimelineEntry(entry);
+            }
+        }
+        if (toolResults.length > 0) {
+            this.ctx.addTimelineEntry({
+                kind: "message",
+                message: {
+                    role: "tool",
+                    content: toolResults.map((r) => ({
+                        type: "tool_result",
+                        toolUseId: r.toolUseId,
+                        name: r.name,
+                        content: r.content || [],
+                        isError: !r.success,
+                    })),
+                },
+                tags: ["tool_output"],
+            });
+        }
+        this._currentOutput = current;
+        // Resolve tick control
+        const shouldStop = response.shouldStop || false;
+        const stopReason = response.stopReason?.reason;
+        return {
+            shouldContinue: !shouldStop && (response.toolCalls?.length > 0 || false),
+            stopReason,
+            timeline: current.timeline,
+        };
+    }
+    /**
+     * 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.
+     */
+    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,
+        };
+        // Notify compiler of completion
+        try {
+            await this.compiler.notifyComplete(finalOutput);
+        }
+        catch {
+            // Ignore completion errors
+        }
+        return finalOutput;
+    }
+}
+//# sourceMappingURL=session.js.map