@agentick/core 0.7.0 → 0.9.0

package/dist/app/session.js

@@ -14,7 +14,7 @@
  */
 import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
-import { Context, createProcedure, Channel, EventBuffer, ExecutionHandleBrand, Logger, } from "@agentick/kernel";
+import { Context, createProcedure, Channel, EventBuffer, ExecutionHandleBrand, Logger, parseSchema, } from "@agentick/kernel";
 import { FiberCompiler, StructureRenderer, ReconciliationScheduler, } from "../compiler";
 import { COM } from "../com/object-model";
 import { MarkdownRenderer } from "../renderers/index";
@@ -71,6 +71,7 @@ export class SessionImpl extends EventEmitter {
     _tick = 1;
     _isAborted = false;
     _currentExecutionId = null;
+    _currentToolCallId = null;
     // Compilation infrastructure (no intermediate layer)
     compiler = null;
     ctx = null;
@@ -117,8 +118,14 @@ export class SessionImpl extends EventEmitter {
     sessionOptions;
     // Last props for hot-update support
     _lastProps = null;
+    _mountPromise = null;
     // Captured context from session creation
     _capturedContext;
+    // Inbox (durable external message delivery)
+    _inboxStorage = null;
+    _inboxUnsubscribe = null;
+    _draining = false;
+    _drainRequested = false;
     // Channels for pub/sub communication
     _channels = new Map();
     // Current execution handle (for concurrent send idempotency)
@@ -238,6 +245,7 @@ export class SessionImpl extends EventEmitter {
     send;
     render;
     spawn;
+    dispatch;
     initProcedures() {
         // Queue procedure - queues messages and notifies components
         this.queue = createProcedure({
@@ -401,8 +409,15 @@ export class SessionImpl extends EventEmitter {
                 inheritDefaults: this.appOptions.inheritDefaults,
                 runner: spawnOptions?.runner ?? this.appOptions.runner,
             };
+            // Child abort signal: merge session-level (parent dies → child dies)
+            // and execution-level (parent execution aborted → child aborted).
+            // Session signal always present; execution signal only during active tick.
+            const abortSignals = [this.sessionAbortController.signal];
+            if (this.executionAbortController) {
+                abortSignals.push(this.executionAbortController.signal);
+            }
             const childOptions = {
-                signal: this.executionAbortController?.signal,
+                signal: AbortSignal.any(abortSignals),
                 devTools: this.sessionOptions.devTools ?? this.appOptions.devTools,
             };
             const child = new SessionImpl(Component, childAppOptions, childOptions);
@@ -414,15 +429,108 @@ export class SessionImpl extends EventEmitter {
                 ...resolvedInput,
                 props: mergedProps,
             });
-            // 4. Cleanup on completion
-            handle.result
+            // 4. Spawn lifecycle events & child event forwarding
+            const spawnId = randomUUID();
+            this.emitEvent({
+                type: "spawn_start",
+                spawnId,
+                parentExecutionId: this._currentExecutionId ?? "",
+                childExecutionId: handle.sessionId,
+                componentName: Component.displayName || Component.name,
+                label: spawnOptions?.label,
+                originCallId: this._currentToolCallId ?? undefined,
+            });
+            // Forward child events to parent's buffer, tagged with spawnPath.
+            // Recursive spawns work automatically: child events already have
+            // spawnPath from grandchildren, we prepend our spawnId.
+            const childCallIds = new Set();
+            // Forward child events, then emit spawn_end after forwarding completes.
+            // This guarantees spawn_end comes AFTER all forwarded child events —
+            // no interleaving of spawn_end with trailing content deltas.
+            const forwardingPromise = (async () => {
+                for await (const event of handle) {
+                    if (event.type === "tool_confirmation_required") {
+                        childCallIds.add(event.callId);
+                    }
+                    this.emitEvent({
+                        ...event,
+                        spawnPath: [spawnId, ...(event.spawnPath ?? [])],
+                    });
+                }
+            })();
+            // Prevent unhandled rejection if parent aborts mid-forward
+            forwardingPromise.catch(() => { });
+            // Route parent confirmation responses to child's channel
+            const parentConfirmChannel = this.channel("tool_confirmation");
+            const unsubConfirm = parentConfirmChannel.subscribe((event) => {
+                if (event.type === "response" && event.id && childCallIds.has(event.id)) {
+                    child.channel("tool_confirmation").publish(event);
+                    childCallIds.delete(event.id);
+                }
+            });
+            // spawn_end after all child events are forwarded (not racing with them).
+            // We await forwardingPromise to ensure ordering, then use handle.result
+            // for the final output/error.
+            forwardingPromise
+                .then(() => handle.result)
+                .then((result) => {
+                this.emitEvent({
+                    type: "spawn_end",
+                    spawnId,
+                    parentExecutionId: this._currentExecutionId ?? "",
+                    childExecutionId: handle.sessionId,
+                    output: result.response,
+                    usage: result.usage,
+                });
+            })
+                .catch((error) => {
+                this.emitEvent({
+                    type: "spawn_end",
+                    spawnId,
+                    parentExecutionId: this._currentExecutionId ?? "",
+                    childExecutionId: handle.sessionId,
+                    output: error?.message ?? "spawn failed",
+                    isError: true,
+                });
+            });
+            // 5. Cleanup after spawn_end is emitted
+            forwardingPromise
+                .then(() => handle.result)
                 .finally(async () => {
+                unsubConfirm();
+                childCallIds.clear();
                 this._children = this._children.filter((c) => c !== child);
                 await child.close();
             })
                 .catch(() => { });
             return handle;
         });
+        // Dispatch procedure - dispatches tools by name/alias from the user side
+        this.dispatch = createProcedure({
+            name: "session:dispatch",
+            metadata: { operation: "dispatch" },
+            handleFactory: false,
+            executionBoundary: false,
+        }, async (name, input) => {
+            if (this.isTerminal)
+                throw new Error(this.terminalError);
+            await this.mount();
+            const tool = this.ctx.getTool(name) ?? this.ctx.getToolByAlias(name);
+            if (!tool)
+                throw new Error(`Unknown command: ${name}`);
+            if (!tool.run)
+                throw new Error(`Command "${name}" has no handler`);
+            // Validate input against tool's schema
+            const validatedInput = tool.metadata.input
+                ? await parseSchema(tool.metadata.input, input)
+                : input;
+            const result = await tool.run.exec(validatedInput).result;
+            if (Array.isArray(result))
+                return result;
+            if (typeof result === "string")
+                return [{ type: "text", text: result }];
+            throw new Error(`Unexpected tool result type: ${typeof result}. Expected ContentBlock[] or string.`);
+        });
     }
     // ════════════════════════════════════════════════════════════════════════
     // SessionExecutionHandle Creation
@@ -690,6 +798,40 @@ export class SessionImpl extends EventEmitter {
     clearAbort() {
         this._isAborted = false;
     }
+    async mount() {
+        // Order matters: _mountPromise must be checked FIRST.
+        // _doMount() sets this.compiler synchronously (via ensureCompilationInfrastructure)
+        // before tool registration completes. A concurrent caller seeing compiler=truthy
+        // would skip the mount and fail tool lookup.
+        if (this._mountPromise)
+            return this._mountPromise;
+        if (this.compiler)
+            return; // Mounted via render() or previous mount()
+        this._mountPromise = this._doMount();
+        try {
+            await this._mountPromise;
+        }
+        catch (e) {
+            this._mountPromise = null; // Allow retry on failure
+            throw e;
+        }
+    }
+    async _doMount() {
+        const rootElement = jsx(this.Component, this._lastProps ?? {});
+        await this.ensureCompilationInfrastructure(rootElement);
+        // Single compile pass — no notifyTickStart (no catch-up), no compileUntilStable (no afterCompile).
+        // This only renders the tree to collect tools. No tick lifecycle hooks fire.
+        const tickState = {
+            tick: 0,
+            queuedMessages: [],
+            timeline: [],
+            stop: () => { },
+        };
+        const compiled = await this.compiler.compile(rootElement, tickState);
+        // Register collected tools so they're available for dispatch
+        const mergedTools = this.mergeTools(this.appOptions.tools ?? [], this.sessionOptions.tools ?? [], [], compiled.tools);
+        await Promise.all(mergedTools.map((tool) => this.ctx.addTool(tool)));
+    }
     startExecutionAbort(signal) {
         this.executionAbortCleanup.forEach((cleanup) => cleanup());
         this.executionAbortCleanup = [];
@@ -778,16 +920,22 @@ export class SessionImpl extends EventEmitter {
             devToolsEnabled: sessionCtx.devToolsEnabled ?? this.sessionOptions.devTools ?? false,
         });
         // Invoke lifecycle callbacks
+        // Forwarded child events (with spawnPath) only trigger onEvent, not
+        // lifecycle-specific callbacks like onTickStart/onTickEnd — those
+        // semantics belong to the parent's own tick lifecycle.
         const cb = this.callbacks;
+        const isForwarded = enrichedEvent.spawnPath?.length > 0;
         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);
+            if (!isForwarded) {
+                // 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 {
@@ -829,6 +977,78 @@ export class SessionImpl extends EventEmitter {
     setPersistCallback(callback) {
         this._persistCallback = callback;
     }
+    /**
+     * Connect this session to an inbox storage backend.
+     * Subscribes to notifications and drains any pre-existing pending messages.
+     * @internal
+     */
+    setInboxStorage(storage) {
+        this._inboxStorage = storage;
+        this._inboxUnsubscribe = storage.subscribe(this.id, () => {
+            this.drainInbox().catch((err) => {
+                this.log.warn({ error: err }, "Inbox drain failed");
+            });
+        });
+        // Drain pre-existing pending messages
+        this.drainInbox().catch((err) => {
+            this.log.warn({ error: err }, "Initial inbox drain failed");
+        });
+    }
+    /**
+     * Process all pending inbox messages. Called by App.processInbox().
+     * @internal
+     */
+    async processInboxMessages() {
+        await this.drainInbox();
+    }
+    async drainInbox() {
+        const storage = this._inboxStorage;
+        if (this.isTerminal || !storage)
+            return;
+        if (this._draining) {
+            // Signal that new messages arrived; current drain will re-check on exit
+            this._drainRequested = true;
+            return;
+        }
+        this._draining = true;
+        try {
+            do {
+                this._drainRequested = false;
+                const messages = await storage.pending(this.id);
+                for (const msg of messages) {
+                    if (this.isTerminal)
+                        return;
+                    try {
+                        if (msg.type === "message") {
+                            const handle = await this.send({ messages: [msg.payload] });
+                            await handle.result;
+                        }
+                        else {
+                            await this.dispatch.exec(msg.payload.tool, msg.payload.input).result;
+                        }
+                        if (this.isTerminal)
+                            return;
+                        await storage.markDone(this.id, msg.id);
+                    }
+                    catch (err) {
+                        this.log.warn({ error: err, messageId: msg.id }, "Inbox message processing failed");
+                        break; // Preserve FIFO — stop on first failure
+                    }
+                }
+            } while (this._drainRequested && !this.isTerminal);
+        }
+        finally {
+            this._draining = false;
+            // Do NOT clear _drainRequested here — a notification may have arrived
+            // between the while-check and finally. If so, re-enter.
+            if (this._drainRequested && !this.isTerminal) {
+                this._drainRequested = false;
+                this.drainInbox().catch((err) => {
+                    this.log.warn({ error: err }, "Inbox re-drain failed");
+                });
+            }
+        }
+    }
     /**
      * Set a snapshot to be applied/resolved when compilation infrastructure is created.
      * @internal
@@ -1222,6 +1442,10 @@ export class SessionImpl extends EventEmitter {
         if (this.isTerminal)
             return;
         this._status = "closed";
+        // Unsubscribe from inbox before anything else
+        this._inboxUnsubscribe?.();
+        this._inboxUnsubscribe = null;
+        this._inboxStorage = null;
         // Notify execution runner of destroy
         if (this._runnerInitialized && this.appOptions.runner?.onDestroy) {
             try {
@@ -1474,12 +1698,25 @@ export class SessionImpl extends EventEmitter {
                 }
                 // Stream model output if supported
                 let modelOutput;
+                let streamed = false;
                 if (model.stream) {
+                    streamed = true;
                     const streamIterable = await model.stream(modelInput);
                     for await (const event of streamIterable) {
                         if (signal.aborted) {
                             throw new AbortError("Execution aborted", signal.reason);
                         }
+                        // Enrich tool_call with displaySummary — the stream accumulator
+                        // doesn't have access to tool definitions, so we add it here.
+                        if (event.type === "tool_call" && "name" in event && compiled.tools) {
+                            const toolDef = compiled.tools.find((t) => t.metadata?.name === event.name);
+                            if (toolDef) {
+                                const summary = tryDisplaySummary(toolDef, event.input);
+                                if (summary) {
+                                    event.summary = summary;
+                                }
+                            }
+                        }
                         this.emitEvent(event);
                         if (event.type === "message" && "message" in event) {
                             const messageEvent = event;
@@ -1561,20 +1798,24 @@ export class SessionImpl extends EventEmitter {
                 let toolStartTime;
                 if (response.toolCalls?.length && this.ctx) {
                     toolStartTime = Date.now();
-                    for (const call of response.toolCalls) {
-                        const toolCallTimestamp = timestamp();
-                        const toolDef = compiled.tools?.find((t) => t.metadata?.name === call.name);
-                        const summary = tryDisplaySummary(toolDef, call.input);
-                        this.emitEvent({
-                            type: "tool_call",
-                            callId: call.id,
-                            blockIndex: 0,
-                            name: call.name,
-                            input: call.input,
-                            summary,
-                            startedAt: toolCallTimestamp,
-                            completedAt: toolCallTimestamp,
-                        });
+                    // Only emit tool_call events for non-streaming path.
+                    // The streaming path already emitted these via stream accumulator.
+                    if (!streamed) {
+                        for (const call of response.toolCalls) {
+                            const toolCallTimestamp = timestamp();
+                            const toolDef = compiled.tools?.find((t) => t.metadata?.name === call.name);
+                            const summary = tryDisplaySummary(toolDef, call.input);
+                            this.emitEvent({
+                                type: "tool_call",
+                                callId: call.id,
+                                blockIndex: 0,
+                                name: call.name,
+                                input: call.input,
+                                summary,
+                                startedAt: toolCallTimestamp,
+                                completedAt: toolCallTimestamp,
+                            });
+                        }
                     }
                     toolResults = await this.executeTools(toolExecutor, response.toolCalls, compiled.tools, outputs, currentTick, timestamp);
                 }
@@ -1623,6 +1864,7 @@ export class SessionImpl extends EventEmitter {
                 // via _resolveCurrentShouldContinue, so each sees the accumulated decision.
                 const tickEndState = {
                     tick: currentTick,
+                    executionId: this._currentExecutionId ?? undefined,
                     current: this._currentOutput,
                     queuedMessages: [],
                     timeline: this._timeline,
@@ -1807,7 +2049,7 @@ export class SessionImpl extends EventEmitter {
             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.ctx.setSpawnCallback((agent, input, options) => this.spawn(agent, input, options));
         this.structureRenderer = new StructureRenderer(this.ctx);
         this.structureRenderer.setDefaultRenderer(new MarkdownRenderer());
         // Tools are registered in compileTick() after merging all sources
@@ -1904,6 +2146,7 @@ export class SessionImpl extends EventEmitter {
         // Prepare tick state
         const tickState = {
             tick: this._tick,
+            executionId: this._currentExecutionId ?? undefined,
             current: this._currentOutput,
             queuedMessages: queuedMessages,
             timeline: [...this._timeline],
@@ -2009,6 +2252,11 @@ export class SessionImpl extends EventEmitter {
                 }
             }
         });
+        // Cancel pending confirmations when execution is aborted (e.g. Ctrl+C).
+        // Without this, waitForConfirmation() hangs forever on abort.
+        const abortSignal = this.executionAbortController?.signal;
+        const onAbort = () => coordinator.cancelAll();
+        abortSignal?.addEventListener("abort", onAbort);
         // Confirmation callbacks for stream event emission
         const confirmationCallbacks = {
             onConfirmationRequired: async (call, message, metadata) => {
@@ -2033,7 +2281,16 @@ export class SessionImpl extends EventEmitter {
         };
         try {
             for (const call of toolCalls) {
+                if (abortSignal?.aborted)
+                    break;
                 const startedAt = timestamp();
+                this._currentToolCallId = call.id;
+                // Signal tool execution beginning (fills the gap between tool_call and tool_result)
+                this.emitEvent({
+                    type: "tool_result_start",
+                    callId: call.id,
+                    name: call.name,
+                });
                 // Check if OUTPUT tool
                 const tool = executableTools.find((t) => t.metadata?.name === call.name);
                 const isOutputTool = tool && tool.metadata?.type === "output";
@@ -2108,6 +2365,8 @@ export class SessionImpl extends EventEmitter {
             }
         }
         finally {
+            this._currentToolCallId = null;
+            abortSignal?.removeEventListener("abort", onAbort);
             unsubscribe();
         }
         return results;
@@ -2178,17 +2437,34 @@ export class SessionImpl extends EventEmitter {
         };
         // Add entries to COM and session timeline - user entries first, then assistant response
         for (const entry of newUserEntries) {
+            if (!entry.id)
+                entry.id = randomUUID();
             this.ctx.addTimelineEntry(entry);
             this._timeline.push(entry);
+            this.emitEvent({
+                type: "entry_committed",
+                entry,
+                executionId: this._currentExecutionId,
+                timelineIndex: this._timeline.length - 1,
+            });
         }
         if (response.newTimelineEntries) {
             for (const entry of response.newTimelineEntries) {
+                if (!entry.id)
+                    entry.id = randomUUID();
                 this.ctx.addTimelineEntry(entry);
                 this._timeline.push(entry);
+                this.emitEvent({
+                    type: "entry_committed",
+                    entry,
+                    executionId: this._currentExecutionId,
+                    timelineIndex: this._timeline.length - 1,
+                });
             }
         }
         if (toolResults.length > 0) {
             const toolResultEntry = {
+                id: randomUUID(),
                 kind: "message",
                 message: {
                     role: "tool",
@@ -2204,6 +2480,12 @@ export class SessionImpl extends EventEmitter {
             };
             this.ctx.addTimelineEntry(toolResultEntry);
             this._timeline.push(toolResultEntry);
+            this.emitEvent({
+                type: "entry_committed",
+                entry: toolResultEntry,
+                executionId: this._currentExecutionId,
+                timelineIndex: this._timeline.length - 1,
+            });
         }
         // Apply maxTimelineEntries trim
         if (this._maxTimelineEntries && this._timeline.length > this._maxTimelineEntries) {