@qduc/term2 0.1.4 → 0.1.6

package/dist/services/conversation-session.js

@@ -1,6 +1,12 @@
-import { extractCommandMessages, markToolCallAsApprovalRejection, } from '../utils/extract-command-messages.js';
+import { extractCommandMessages, markToolCallAsApprovalRejection } from '../utils/extract-command-messages.js';
 import { ConversationStore } from './conversation-store.js';
 import { ModelBehaviorError } from '@openai/agents';
+import { extractUsage } from '../utils/token-usage.js';
+import { getProvider } from '../providers/index.js';
+import { extractReasoningDelta, extractTextDelta } from './stream-event-parsing.js';
+import { captureToolCallArguments, emitCommandMessagesFromItems } from './command-message-streaming.js';
+import { ApprovalState } from './approval-state.js';
+import { createInvalidToolCallDiagnostic } from './logging-contract.js';
 const getCommandFromArgs = (args) => {
     if (!args) {
         return '';
@@ -16,7 +22,7 @@ const getCommandFromArgs = (args) => {
             if (Array.isArray(parsed?.commands)) {
                 return parsed.commands.join('\n');
             }
-            return args;
+            return JSON.stringify(parsed);
         }
         catch {
             return args;
@@ -29,7 +35,21 @@ const getCommandFromArgs = (args) => {
         if ('commands' in args && Array.isArray(args.commands)) {
             return args.commands.join('\n');
         }
-        const argsFromObject = 'arguments' in args ? String(args.arguments) : undefined;
+        let argsFromObject;
+        if ('arguments' in args) {
+            const rawArguments = args.arguments;
+            if (typeof rawArguments === 'string') {
+                try {
+                    argsFromObject = JSON.stringify(JSON.parse(rawArguments));
+                }
+                catch {
+                    argsFromObject = String(rawArguments);
+                }
+            }
+            else if (rawArguments !== undefined) {
+                argsFromObject = String(rawArguments);
+            }
+        }
         return cmdFromObject ?? argsFromObject ?? JSON.stringify(args);
     }
     return String(args);
@@ -48,19 +68,23 @@ const isToolHallucinationError = (error) => {
     const message = error.message.toLowerCase();
     return message.includes('tool') && message.includes('not found');
 };
+const supportsConversationChaining = (providerId) => {
+    const providerDef = getProvider(providerId);
+    return providerDef?.capabilities?.supportsConversationChaining ?? false;
+};
 export class ConversationSession {
     id;
     agentClient;
     logger;
     conversationStore;
     previousResponseId = null;
-    pendingApprovalContext = null;
-    abortedApprovalContext = null;
+    approvalState = new ApprovalState();
     textDeltaCount = 0;
     reasoningDeltaCount = 0;
     toolCallArgumentsById = new Map();
     lastEventType = null;
     eventTypeCount = 0;
+    emittedInvalidToolCallPackets = new Set();
     // private logStreamEvent = (eventType: string, eventData: any) => {
     // 	if (eventData.item) {
     // 		eventType = eventData.item.type;
@@ -97,7 +121,7 @@ export class ConversationSession {
         this.lastEventType = null;
         this.eventTypeCount = 0;
     };
-    constructor(id, { agentClient, deps, }) {
+    constructor(id, { agentClient, deps }) {
         this.id = id;
         this.agentClient = agentClient;
         this.logger = deps.logger;
@@ -106,8 +130,8 @@ export class ConversationSession {
     reset() {
         this.previousResponseId = null;
         this.conversationStore.clear();
-        this.pendingApprovalContext = null;
-        this.abortedApprovalContext = null;
+        this.approvalState.clearPending();
+        this.approvalState.consumeAborted();
         this.toolCallArgumentsById.clear();
         if (typeof this.agentClient.clearConversations === 'function') {
             this.agentClient.clearConversations();
@@ -145,10 +169,14 @@ export class ConversationSession {
     abort() {
         this.agentClient.abort();
         // Save pending approval context so we can handle it in the next message
-        if (this.pendingApprovalContext) {
-            this.abortedApprovalContext = this.pendingApprovalContext;
-            this.pendingApprovalContext = null;
-            this.logger.debug('Aborted approval - will handle rejection on next message');
+        if (this.approvalState.abortPending()) {
+            this.logger.debug('Aborted approval - will handle rejection on next message', {
+                eventType: 'approval.aborted',
+                category: 'approval',
+                phase: 'abort',
+                sessionId: this.id,
+                traceId: this.logger.getCorrelationId(),
+            });
         }
     }
     /**
@@ -159,34 +187,40 @@ export class ConversationSession {
     async *run(text, { hallucinationRetryCount = 0, skipUserMessage = false, } = {}) {
         let stream = null;
         try {
+            this.logger.info('Conversation stream start', {
+                eventType: 'stream.started',
+                category: 'stream',
+                phase: 'request_start',
+                sessionId: this.id,
+                traceId: this.logger.getCorrelationId(),
+            });
+            const abortedContext = this.approvalState.consumeAborted();
+            const shouldAddUserMessage = !skipUserMessage && !abortedContext;
             // Maintain canonical local history regardless of provider.
-            if (!skipUserMessage) {
+            if (shouldAddUserMessage) {
                 this.conversationStore.addUserMessage(text);
             }
             // If there's an aborted approval, we need to resolve it first.
             // The user's message is a new input, but the agent is stuck waiting for tool output.
-            if (this.abortedApprovalContext) {
+            if (abortedContext) {
                 this.logger.debug('Resolving aborted approval with fake execution', {
                     message: text,
                 });
-                const { state, interruption, emittedCommandIds, toolCallArgumentsById, } = this.abortedApprovalContext;
-                this.abortedApprovalContext = null;
+                const { state, interruption, emittedCommandIds, toolCallArgumentsById } = abortedContext;
                 // Restore cached tool-call arguments captured before abort so continuation can attach them
                 this.toolCallArgumentsById.clear();
                 if (toolCallArgumentsById?.size) {
-                    for (const [key, value,] of toolCallArgumentsById.entries()) {
+                    for (const [key, value] of toolCallArgumentsById.entries()) {
                         this.toolCallArgumentsById.set(key, value);
                     }
                 }
                 // Add interceptor for this tool execution
                 const toolName = interruption.name ?? 'unknown';
-                const expectedCallId = interruption.rawItem?.callId ??
-                    interruption.callId;
+                const expectedCallId = interruption.rawItem?.callId ?? interruption.callId;
                 const rejectionMessage = `Tool execution was not approved. User provided new input instead: ${text}`;
                 const removeInterceptor = this.agentClient.addToolInterceptor(async (name, _params, toolCallId) => {
                     // Match both tool name and call ID for stricter matching
-                    if (name === toolName &&
-                        (!expectedCallId || toolCallId === expectedCallId)) {
+                    if (name === toolName && (!expectedCallId || toolCallId === expectedCallId)) {
                         markToolCallAsApprovalRejection(toolCallId ?? expectedCallId);
                         return rejectionMessage;
                     }
@@ -201,6 +235,7 @@ export class ConversationSession {
                         finalOutput: '',
                         reasoningOutput: '',
                         emittedCommandIds: new Set(emittedCommandIds),
+                        latestUsage: undefined,
                     };
                     yield* this.#streamEvents(stream, acc, {
                         preserveExistingToolArgs: true,
@@ -208,11 +243,10 @@ export class ConversationSession {
                     this.previousResponseId = stream.lastResponseId;
                     this.conversationStore.updateFromResult(stream);
                     // Check if another interruption occurred
-                    if (stream.interruptions &&
-                        stream.interruptions.length > 0) {
+                    if (stream.interruptions && stream.interruptions.length > 0) {
                         this.logger.warn('Another interruption occurred after fake execution - handling as approval');
                         // Let the normal flow handle this
-                        const result = this.#buildResult(stream, acc.finalOutput, acc.reasoningOutput, acc.emittedCommandIds);
+                        const result = this.#buildResult(stream, acc.finalOutput, acc.reasoningOutput, acc.emittedCommandIds, acc.latestUsage);
                         // Re-emit the terminal event explicitly.
                         if (result.type === 'approval_required') {
                             const interruption = result.approval.rawInterruption;
@@ -236,19 +270,16 @@ export class ConversationSession {
                             yield {
                                 type: 'final',
                                 finalText: result.finalText,
-                                ...(result.reasoningText
-                                    ? { reasoningText: result.reasoningText }
-                                    : {}),
-                                ...(result.commandMessages?.length
-                                    ? { commandMessages: result.commandMessages }
-                                    : {}),
+                                ...(result.reasoningText ? { reasoningText: result.reasoningText } : {}),
+                                ...(result.commandMessages?.length ? { commandMessages: result.commandMessages } : {}),
+                                ...(result.usage ? { usage: result.usage } : {}),
                             };
                         }
                         return;
                     }
                     // Successfully resolved - agent should now have processed the fake rejection
                     this.logger.debug('Fake execution completed, agent received rejection message');
-                    const result = this.#buildResult(stream, acc.finalOutput, acc.reasoningOutput, acc.emittedCommandIds);
+                    const result = this.#buildResult(stream, acc.finalOutput, acc.reasoningOutput, acc.emittedCommandIds, acc.latestUsage);
                     if (result.type === 'approval_required') {
                         const interruption = result.approval.rawInterruption;
                         const callId = interruption?.rawItem?.callId ??
@@ -271,21 +302,16 @@ export class ConversationSession {
                         yield {
                             type: 'final',
                             finalText: result.finalText,
-                            ...(result.reasoningText
-                                ? { reasoningText: result.reasoningText }
-                                : {}),
-                            ...(result.commandMessages?.length
-                                ? { commandMessages: result.commandMessages }
-                                : {}),
+                            ...(result.reasoningText ? { reasoningText: result.reasoningText } : {}),
+                            ...(result.commandMessages?.length ? { commandMessages: result.commandMessages } : {}),
+                            ...(result.usage ? { usage: result.usage } : {}),
                         };
                     }
                     return;
                 }
                 catch (error) {
                     this.logger.warn('Error resolving aborted approval with fake execution', {
-                        error: error instanceof Error
-                            ? error.message
-                            : String(error),
+                        error: error instanceof Error ? error.message : String(error),
                     });
                     // Fall through to normal message flow
                 }
@@ -298,17 +324,15 @@ export class ConversationSession {
             const provider = typeof this.agentClient.getProvider === 'function'
                 ? this.agentClient.getProvider()
                 : 'openai';
-            // Only OpenAI uses server-side conversation management via previousResponseId.
-            // All other providers (OpenRouter, openai-compatible) need full history.
-            stream = await this.agentClient.startStream(provider !== 'openai'
-                ? this.conversationStore.getHistory()
-                : text, {
+            const supportsChaining = supportsConversationChaining(provider);
+            stream = await this.agentClient.startStream(supportsChaining ? text : this.conversationStore.getHistory(), {
                 previousResponseId: this.previousResponseId,
             });
             const acc = {
                 finalOutput: '',
                 reasoningOutput: '',
                 emittedCommandIds: new Set(),
+                latestUsage: undefined,
             };
             yield* this.#streamEvents(stream, acc, {
                 preserveExistingToolArgs: false,
@@ -316,8 +340,16 @@ export class ConversationSession {
             this.previousResponseId = stream.lastResponseId;
             this.conversationStore.updateFromResult(stream);
             // Build terminal event (approval_required or final)
-            const result = this.#buildResult(stream, acc.finalOutput || undefined, acc.reasoningOutput || undefined, acc.emittedCommandIds);
+            const result = this.#buildResult(stream, acc.finalOutput || undefined, acc.reasoningOutput || undefined, acc.emittedCommandIds, acc.latestUsage);
             if (result.type === 'approval_required') {
+                this.logger.info('Tool approval required', {
+                    eventType: 'approval.required',
+                    category: 'approval',
+                    phase: 'approval',
+                    sessionId: this.id,
+                    traceId: this.logger.getCorrelationId(),
+                    toolName: result.approval.toolName,
+                });
                 const interruption = result.approval.rawInterruption;
                 const callId = interruption?.rawItem?.callId ??
                     interruption?.callId ??
@@ -339,26 +371,26 @@ export class ConversationSession {
             yield {
                 type: 'final',
                 finalText: result.finalText,
-                ...(result.reasoningText
-                    ? { reasoningText: result.reasoningText }
-                    : {}),
-                ...(result.commandMessages?.length
-                    ? { commandMessages: result.commandMessages }
-                    : {}),
+                ...(result.reasoningText ? { reasoningText: result.reasoningText } : {}),
+                ...(result.commandMessages?.length ? { commandMessages: result.commandMessages } : {}),
+                ...(result.usage ? { usage: result.usage } : {}),
             };
         }
         catch (error) {
             // Handle tool hallucination: model called a non-existent tool
-            if (isToolHallucinationError(error) &&
-                hallucinationRetryCount < MAX_HALLUCINATION_RETRIES) {
-                const toolName = error instanceof Error
-                    ? error.message.match(/Tool (\S+) not found/)?.[1] ||
-                        'unknown'
-                    : 'unknown';
+            if (isToolHallucinationError(error) && hallucinationRetryCount < MAX_HALLUCINATION_RETRIES) {
+                const toolName = error instanceof Error ? error.message.match(/Tool (\S+) not found/)?.[1] || 'unknown' : 'unknown';
                 this.logger.warn('Tool hallucination detected, retrying', {
+                    eventType: 'retry.hallucination',
+                    category: 'retry',
+                    phase: 'retry',
                     toolName,
+                    retryType: 'hallucination',
+                    retryAttempt: hallucinationRetryCount + 1,
                     attempt: hallucinationRetryCount + 1,
                     maxRetries: MAX_HALLUCINATION_RETRIES,
+                    sessionId: this.id,
+                    traceId: this.logger.getCorrelationId(),
                     errorMessage: error instanceof Error ? error.message : String(error),
                 });
                 yield {
@@ -391,6 +423,14 @@ export class ConversationSession {
                 type: 'error',
                 message: error instanceof Error ? error.message : String(error),
             };
+            this.logger.error('Conversation stream error', {
+                eventType: 'stream.failed',
+                category: 'stream',
+                phase: 'abort',
+                sessionId: this.id,
+                traceId: this.logger.getCorrelationId(),
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
             throw error;
         }
     }
@@ -400,23 +440,31 @@ export class ConversationSession {
      * Named as a string-literal because `continue` is a keyword.
      */
     async *['continue']({ answer, rejectionReason, }) {
-        if (!this.pendingApprovalContext) {
+        const pendingApprovalContext = this.approvalState.getPending();
+        if (!pendingApprovalContext) {
             return;
         }
-        const { state, interruption, emittedCommandIds: previouslyEmittedIds, toolCallArgumentsById, } = this.pendingApprovalContext;
+        const { state, interruption, emittedCommandIds: previouslyEmittedIds, toolCallArgumentsById, } = pendingApprovalContext;
+        let removeInterceptor = null;
         if (answer === 'y') {
+            this.logger.info('Tool approval granted', {
+                eventType: 'approval.granted',
+                category: 'approval',
+                phase: 'approval',
+                sessionId: this.id,
+                traceId: this.logger.getCorrelationId(),
+            });
             state.approve(interruption);
         }
         else {
-            // If rejection reason provided, inject it as a tool interceptor result
-            if (rejectionReason) {
-                const toolName = interruption.name ?? 'unknown';
-                const expectedCallId = interruption.rawItem?.callId ??
-                    interruption.callId;
-                const rejectionMessage = `Tool execution was not approved. User's reason: ${rejectionReason}`;
+            const toolName = interruption.name ?? 'unknown';
+            const expectedCallId = interruption.rawItem?.callId ?? interruption.callId;
+            const rejectionMessage = rejectionReason
+                ? `Tool execution was not approved. User's reason: ${rejectionReason}`
+                : 'Tool execution was not approved.';
+            if (typeof this.agentClient.addToolInterceptor === 'function') {
                 const removeInterceptor = this.agentClient.addToolInterceptor(async (name, _params, toolCallId) => {
-                    if (name === toolName &&
-                        (!expectedCallId || toolCallId === expectedCallId)) {
+                    if (name === toolName && (!expectedCallId || toolCallId === expectedCallId)) {
                         markToolCallAsApprovalRejection(toolCallId ?? expectedCallId);
                         return rejectionMessage;
                     }
@@ -425,15 +473,21 @@ export class ConversationSession {
                 // Approve to continue but interceptor will return rejection message
                 state.approve(interruption);
                 // Store interceptor cleanup for after stream
-                this.pendingApprovalContext = {
-                    ...this.pendingApprovalContext,
-                    removeInterceptor,
-                };
+                this.approvalState.setPendingRemoveInterceptor(removeInterceptor);
             }
             else {
+                // Fallback for clients without tool interceptors
                 state.reject(interruption);
             }
+            this.logger.info('Tool approval rejected', {
+                eventType: 'approval.rejected',
+                category: 'approval',
+                phase: 'approval',
+                sessionId: this.id,
+                traceId: this.logger.getCorrelationId(),
+            });
         }
+        removeInterceptor = this.approvalState.getPending()?.removeInterceptor ?? null;
         // Restore cached tool-call arguments so continuation outputs can attach them
         this.toolCallArgumentsById.clear();
         if (toolCallArgumentsById?.size) {
@@ -449,6 +503,7 @@ export class ConversationSession {
                 finalOutput: '',
                 reasoningOutput: '',
                 emittedCommandIds: new Set(),
+                latestUsage: undefined,
             };
             yield* this.#streamEvents(stream, acc, {
                 preserveExistingToolArgs: true,
@@ -457,12 +512,17 @@ export class ConversationSession {
             this.conversationStore.updateFromResult(stream);
             // Merge previously emitted command IDs with newly emitted ones
             // This prevents duplicates when result.history contains commands from the initial stream
-            const allEmittedIds = new Set([
-                ...previouslyEmittedIds,
-                ...acc.emittedCommandIds,
-            ]);
-            const result = this.#buildResult(stream, acc.finalOutput || undefined, acc.reasoningOutput || undefined, allEmittedIds);
+            const allEmittedIds = new Set([...previouslyEmittedIds, ...acc.emittedCommandIds]);
+            const result = this.#buildResult(stream, acc.finalOutput || undefined, acc.reasoningOutput || undefined, allEmittedIds, acc.latestUsage);
             if (result.type === 'approval_required') {
+                this.logger.info('Tool approval required', {
+                    eventType: 'approval.required',
+                    category: 'approval',
+                    phase: 'approval',
+                    sessionId: this.id,
+                    traceId: this.logger.getCorrelationId(),
+                    toolName: result.approval.toolName,
+                });
                 const interruption = result.approval.rawInterruption;
                 const callId = interruption?.rawItem?.callId ??
                     interruption?.callId ??
@@ -484,12 +544,9 @@ export class ConversationSession {
             yield {
                 type: 'final',
                 finalText: result.finalText,
-                ...(result.reasoningText
-                    ? { reasoningText: result.reasoningText }
-                    : {}),
-                ...(result.commandMessages?.length
-                    ? { commandMessages: result.commandMessages }
-                    : {}),
+                ...(result.reasoningText ? { reasoningText: result.reasoningText } : {}),
+                ...(result.commandMessages?.length ? { commandMessages: result.commandMessages } : {}),
+                ...(result.usage ? { usage: result.usage } : {}),
             };
         }
         catch (error) {
@@ -501,16 +558,14 @@ export class ConversationSession {
         }
         finally {
             // Clean up interceptor if one was added for rejection reason
-            if (rejectionReason &&
-                this.pendingApprovalContext?.removeInterceptor) {
-                this.pendingApprovalContext.removeInterceptor();
-            }
+            removeInterceptor?.();
         }
     }
     async sendMessage(text, { onTextChunk, onReasoningChunk, onCommandMessage, onEvent, hallucinationRetryCount = 0, } = {}) {
         let finalText = '';
         let reasoningText = '';
         const commandMessages = [];
+        let usage;
         let sawTerminalEvent = null;
         for await (const event of this.run(text, { hallucinationRetryCount })) {
             onEvent?.(event);
@@ -532,7 +587,7 @@ export class ConversationSession {
                 case 'approval_required': {
                     sawTerminalEvent = event;
                     // pendingApprovalContext is set inside #buildResult during run()
-                    const rawInterruption = this.pendingApprovalContext?.interruption;
+                    const rawInterruption = this.approvalState.getPending()?.interruption;
                     return {
                         type: 'approval_required',
                         approval: {
@@ -547,6 +602,12 @@ export class ConversationSession {
                     sawTerminalEvent = event;
                     finalText = event.finalText;
                     reasoningText = event.reasoningText ?? '';
+                    usage = event.usage;
+                    this.logger.debug('sendMessage received final event', {
+                        sessionId: this.id,
+                        hasUsage: Boolean(event.usage),
+                        usage: event.usage,
+                    });
                     if (event.commandMessages?.length) {
                         for (const msg of event.commandMessages) {
                             commandMessages.push(msg);
@@ -566,20 +627,28 @@ export class ConversationSession {
         if (!sawTerminalEvent) {
             finalText = finalText || 'Done.';
         }
-        return {
+        const response = {
             type: 'response',
             commandMessages,
             finalText: finalText || 'Done.',
             ...(reasoningText ? { reasoningText } : {}),
+            ...(usage ? { usage } : {}),
         };
+        this.logger.debug('sendMessage returning response', {
+            sessionId: this.id,
+            hasUsage: Boolean(usage),
+            usage,
+        });
+        return response;
     }
     async handleApprovalDecision(answer, rejectionReason, { onTextChunk, onReasoningChunk, onCommandMessage, onEvent, } = {}) {
-        if (!this.pendingApprovalContext) {
+        if (!this.approvalState.getPending()) {
             return null;
         }
         let finalText = '';
         let reasoningText = '';
         const commandMessages = [];
+        let usage;
         let sawTerminalEvent = null;
         for await (const event of this['continue']({ answer, rejectionReason })) {
             onEvent?.(event);
@@ -600,7 +669,7 @@ export class ConversationSession {
                 }
                 case 'approval_required': {
                     sawTerminalEvent = event;
-                    const rawInterruption = this.pendingApprovalContext?.interruption;
+                    const rawInterruption = this.approvalState.getPending()?.interruption;
                     return {
                         type: 'approval_required',
                         approval: {
@@ -615,6 +684,12 @@ export class ConversationSession {
                     sawTerminalEvent = event;
                     finalText = event.finalText;
                     reasoningText = event.reasoningText ?? '';
+                    usage = event.usage;
+                    this.logger.debug('handleApprovalDecision received final event', {
+                        sessionId: this.id,
+                        hasUsage: Boolean(event.usage),
+                        usage: event.usage,
+                    });
                     if (event.commandMessages?.length) {
                         for (const msg of event.commandMessages) {
                             commandMessages.push(msg);
@@ -630,19 +705,33 @@ export class ConversationSession {
             }
         }
         if (!sawTerminalEvent) {
-            return {
+            const response = {
                 type: 'response',
                 commandMessages,
                 finalText: finalText || 'Done.',
                 ...(reasoningText ? { reasoningText } : {}),
+                ...(usage ? { usage } : {}),
             };
+            this.logger.debug('handleApprovalDecision returning response', {
+                sessionId: this.id,
+                hasUsage: Boolean(usage),
+                usage,
+            });
+            return response;
         }
-        return {
+        const response = {
             type: 'response',
             commandMessages,
             finalText: finalText || 'Done.',
             ...(reasoningText ? { reasoningText } : {}),
+            ...(usage ? { usage } : {}),
         };
+        this.logger.debug('handleApprovalDecision returning response', {
+            sessionId: this.id,
+            hasUsage: Boolean(usage),
+            usage,
+        });
+        return response;
     }
     async *#streamEvents(stream, acc, { preserveExistingToolArgs }) {
         const toolCallArgumentsById = this.toolCallArgumentsById;
@@ -676,21 +765,26 @@ export class ConversationSession {
             };
         };
         for await (const event of stream) {
+            // Extract usage if present in any of the common locations
+            const usage = extractUsage(event);
+            if (usage) {
+                acc.latestUsage = usage;
+                this.logger.debug('Usage extracted from stream event', {
+                    sessionId: this.id,
+                    source: 'stream_event',
+                    eventType: event?.type ?? event?.data?.type ?? 'unknown',
+                    usage,
+                });
+            }
             // Log event type with deduplication for ordering understanding
-            // const eventType = event?.type || 'unknown';
-            // this.logStreamEvent(eventType, {
-            //     eventName: event?.name,
-            //     hasData: !!event?.data,
-            //     item: event?.item,
-            // });
-            const delta1 = this.#extractTextDelta(event);
+            const delta1 = extractTextDelta(event);
             if (delta1) {
                 const e = emitText(delta1);
                 if (e)
                     yield e;
             }
             if (event?.data) {
-                const delta2 = this.#extractTextDelta(event.data);
+                const delta2 = extractTextDelta(event.data);
                 if (delta2) {
                     const e = emitText(delta2);
                     if (e)
@@ -698,71 +792,25 @@ export class ConversationSession {
                 }
             }
             // Handle reasoning items
-            const reasoningDelta = (() => {
-                // OpenAI style
-                const data = event?.data;
-                if (data &&
-                    typeof data === 'object' &&
-                    data.type === 'model') {
-                    const eventDetail = data.event;
-                    if (eventDetail &&
-                        typeof eventDetail === 'object' &&
-                        eventDetail.type ===
-                            'response.reasoning_summary_text.delta') {
-                        return eventDetail.delta ?? '';
-                    }
-                }
-                // OpenRouter style
-                const choices = event?.data?.event?.choices;
-                if (!choices)
-                    return '';
-                if (Array.isArray(choices)) {
-                    return choices[0]?.delta?.reasoning ?? choices[0]?.delta?.reasoning_content ?? '';
-                }
-                if (typeof choices === 'object') {
-                    const byZero = choices['0'];
-                    const first = byZero ?? choices[Object.keys(choices)[0]];
-                    return first?.delta?.reasoning ?? first?.delta?.reasoning_content ?? '';
-                }
-                return '';
-            })();
+            const reasoningDelta = extractReasoningDelta(event);
             if (reasoningDelta) {
                 const e = emitReasoning(reasoningDelta);
                 if (e)
                     yield e;
             }
-            const maybeEmitCommandMessagesFromItems = (items) => {
-                this.#attachCachedArguments(items, toolCallArgumentsById);
-                const commandMessages = extractCommandMessages(items);
-                const out = [];
-                for (const cmdMsg of commandMessages) {
-                    if (acc.emittedCommandIds.has(cmdMsg.id)) {
-                        continue;
-                    }
-                    if (cmdMsg.isApprovalRejection) {
-                        continue;
-                    }
-                    acc.emittedCommandIds.add(cmdMsg.id);
-                    out.push({ type: 'command_message', message: cmdMsg });
-                }
-                return out;
-            };
+            const maybeEmitCommandMessagesFromItems = (items) => emitCommandMessagesFromItems(items, {
+                toolCallArgumentsById,
+                emittedCommandIds: acc.emittedCommandIds,
+            });
             if (event?.type === 'run_item_stream_event') {
-                this.#captureToolCallArguments(event.item, toolCallArgumentsById);
+                captureToolCallArguments(event.item, toolCallArgumentsById);
                 // Emit tool_started event when a function_call is detected
                 const rawItem = event.item?.rawItem ?? event.item;
                 if (rawItem?.type === 'function_call') {
-                    const callId = rawItem.callId ??
-                        rawItem.call_id ??
-                        rawItem.tool_call_id ??
-                        rawItem.toolCallId ??
-                        rawItem.id;
+                    const callId = rawItem.callId ?? rawItem.call_id ?? rawItem.tool_call_id ?? rawItem.toolCallId ?? rawItem.id;
                     if (callId) {
                         const toolName = rawItem.name ?? event.item?.name;
-                        const args = rawItem.arguments ??
-                            rawItem.args ??
-                            event.item?.arguments ??
-                            event.item?.args;
+                        const args = rawItem.arguments ?? rawItem.args ?? event.item?.arguments ?? event.item?.args;
                         // Providers sometimes surface arguments as a JSON string.
                         // Normalize here so downstream UI (pending/running display)
                         // can reliably render parameters.
@@ -778,6 +826,30 @@ export class ConversationSession {
                                 return JSON.parse(trimmed);
                             }
                             catch {
+                                if ((trimmed.startsWith('{') || trimmed.startsWith('[')) &&
+                                    !this.emittedInvalidToolCallPackets.has(String(callId))) {
+                                    this.emittedInvalidToolCallPackets.add(String(callId));
+                                    const diagnostic = createInvalidToolCallDiagnostic({
+                                        toolName: toolName ?? 'unknown',
+                                        toolCallId: String(callId),
+                                        rawPayload: trimmed,
+                                        normalizedToolCall: {
+                                            toolName: toolName ?? 'unknown',
+                                            toolCallId: String(callId),
+                                            arguments: args,
+                                        },
+                                        validationErrors: ['arguments must be valid JSON'],
+                                        traceId: this.logger.getCorrelationId() ?? 'trace-unknown',
+                                        retryContext: {
+                                            sessionId: this.id,
+                                        },
+                                    });
+                                    this.logger.error('Invalid tool call argument payload', {
+                                        ...diagnostic,
+                                        sessionId: this.id,
+                                        messageId: String(callId),
+                                    });
+                                }
                                 return args;
                             }
                         })();
@@ -787,147 +859,86 @@ export class ConversationSession {
                             toolName: toolName ?? 'unknown',
                             arguments: normalizedArgs,
                         };
+                        this.logger.info('Tool execution started', {
+                            eventType: 'tool_call.execution_started',
+                            category: 'tool',
+                            phase: 'execution',
+                            sessionId: this.id,
+                            traceId: this.logger.getCorrelationId(),
+                            toolName: toolName ?? 'unknown',
+                            toolCallId: String(callId),
+                            messageId: String(callId),
+                        });
                     }
                 }
-                for (const e of maybeEmitCommandMessagesFromItems([
-                    event.item,
-                ])) {
+                for (const e of maybeEmitCommandMessagesFromItems([event.item])) {
                     yield e;
                 }
             }
-            else if (event?.type === 'tool_call_output_item' ||
-                event?.rawItem?.type === 'function_call_output') {
-                this.#captureToolCallArguments(event, toolCallArgumentsById);
+            else if (event?.type === 'tool_call_output_item' || event?.rawItem?.type === 'function_call_output') {
+                captureToolCallArguments(event, toolCallArgumentsById);
                 for (const e of maybeEmitCommandMessagesFromItems([event])) {
                     yield e;
                 }
             }
         }
-        await stream.completed;
-        this.flushStreamEventLog();
-    }
-    #captureToolCallArguments(item, toolCallArgumentsById) {
-        const rawItem = item?.rawItem ?? item;
-        if (!rawItem) {
-            return;
-        }
-        if (rawItem?.type !== 'function_call') {
-            return;
-        }
-        const callId = rawItem.callId ??
-            rawItem.call_id ??
-            rawItem.tool_call_id ??
-            rawItem.toolCallId ??
-            rawItem.id;
-        if (!callId) {
-            return;
-        }
-        const args = rawItem.arguments ?? rawItem.args ?? item?.arguments ?? item?.args;
-        if (!args) {
-            return;
-        }
-        toolCallArgumentsById.set(callId, args);
-    }
-    #attachCachedArguments(items = [], toolCallArgumentsById) {
-        if (!items?.length) {
-            return;
-        }
-        for (const item of items) {
-            if (!item) {
-                continue;
-            }
-            if (item.arguments ||
-                item.args ||
-                item?.rawItem?.arguments ||
-                item?.rawItem?.args) {
-                continue;
-            }
-            const rawItem = item?.rawItem ?? item;
-            const callId = rawItem?.callId ??
-                rawItem?.call_id ??
-                rawItem?.tool_call_id ??
-                rawItem?.toolCallId ??
-                rawItem?.id ??
-                item?.callId ??
-                item?.call_id ??
-                item?.tool_call_id ??
-                item?.toolCallId ??
-                item?.id;
-            if (!callId) {
-                continue;
-            }
-            const args = toolCallArgumentsById.get(callId);
-            if (!args) {
-                continue;
+        const completedResult = await stream.completed;
+        const rawResponses = Array.isArray(stream?.rawResponses) ? stream.rawResponses : [];
+        let usageFromRawResponses;
+        for (let i = rawResponses.length - 1; i >= 0; i--) {
+            const candidate = extractUsage(rawResponses[i]);
+            if (candidate) {
+                usageFromRawResponses = candidate;
+                break;
             }
-            item.arguments = args;
-        }
-    }
-    #extractTextDelta(payload) {
-        if (payload === null || payload === undefined) {
-            return null;
-        }
-        if (typeof payload === 'string') {
-            return payload || null;
         }
-        if (typeof payload !== 'object') {
-            return null;
-        }
-        const type = typeof payload.type === 'string' ? payload.type : '';
-        const looksLikeOutput = typeof type === 'string' && type.includes('output_text');
-        const hasOutputProperties = Boolean(payload.delta ??
-            payload.output_text ??
-            payload.text ??
-            payload.content);
-        if (!looksLikeOutput && !hasOutputProperties) {
-            return null;
-        }
-        const deltaCandidate = payload.delta ??
-            payload.output_text ??
-            payload.text ??
-            payload.content;
-        const text = this.#coerceToText(deltaCandidate);
-        return text || null;
-    }
-    #coerceToText(value) {
-        if (value === null || value === undefined) {
-            return '';
-        }
-        if (typeof value === 'string') {
-            return value;
-        }
-        if (typeof value === 'number' || typeof value === 'boolean') {
-            return String(value);
-        }
-        if (Array.isArray(value)) {
-            return value
-                .map(entry => this.#coerceToText(entry))
-                .filter(Boolean)
-                .join('');
+        const finalUsage = extractUsage(completedResult) || extractUsage(stream) || usageFromRawResponses;
+        if (finalUsage) {
+            acc.latestUsage = finalUsage;
+            const usageSource = extractUsage(completedResult)
+                ? 'completed_result'
+                : extractUsage(stream)
+                    ? 'stream_object'
+                    : 'stream_raw_responses';
+            this.logger.debug('Usage extracted from stream completion', {
+                sessionId: this.id,
+                source: 'stream_completed',
+                usageSource,
+                usage: finalUsage,
+            });
         }
-        if (typeof value === 'object') {
-            const record = value;
-            const candidates = ['text', 'value', 'content', 'delta'];
-            for (const field of candidates) {
-                if (field in record) {
-                    const text = this.#coerceToText(record[field]);
-                    if (text) {
-                        return text;
-                    }
-                }
-            }
+        else {
+            const completedResultRecord = completedResult && typeof completedResult === 'object' && !Array.isArray(completedResult)
+                ? completedResult
+                : undefined;
+            const streamRecord = stream && typeof stream === 'object' && !Array.isArray(stream)
+                ? stream
+                : undefined;
+            this.logger.debug('No usage found in stream completion', {
+                sessionId: this.id,
+                source: 'stream_completed',
+                completedResultType: completedResult === null ? 'null' : Array.isArray(completedResult) ? 'array' : typeof completedResult,
+                completedResultKeys: completedResultRecord ? Object.keys(completedResultRecord) : [],
+                streamKeys: streamRecord ? Object.keys(streamRecord) : [],
+                completedResultHasUsagePath: {
+                    usage: Boolean(completedResultRecord?.usage),
+                    usageMetadata: Boolean(completedResultRecord?.usageMetadata),
+                    usage_metadata: Boolean(completedResultRecord?.usage_metadata),
+                    responseUsage: Boolean(completedResultRecord?.response?.usage),
+                },
+            });
         }
-        return '';
+        this.flushStreamEventLog();
     }
-    #buildResult(result, finalOutputOverride, reasoningOutputOverride, emittedCommandIds) {
+    #buildResult(result, finalOutputOverride, reasoningOutputOverride, emittedCommandIds, usage) {
         if (result.interruptions && result.interruptions.length > 0) {
             const interruption = result.interruptions[0];
-            this.pendingApprovalContext = {
+            this.approvalState.setPending({
                 state: result.state,
                 interruption,
                 emittedCommandIds: emittedCommandIds ?? new Set(),
                 toolCallArgumentsById: new Map(this.toolCallArgumentsById),
-            };
+            });
             let argumentsText = '';
             const toolName = interruption.name;
             // For shell_call (built-in shell tool), extract commands from action
@@ -959,18 +970,19 @@ export class ConversationSession {
                 },
             };
         }
-        this.pendingApprovalContext = null;
+        this.approvalState.clearPending();
         const allCommandMessages = extractCommandMessages(result.newItems || result.history || []);
         // Filter out commands that were already emitted in real-time
         const commandMessages = emittedCommandIds
-            ? allCommandMessages.filter(msg => !emittedCommandIds.has(msg.id))
+            ? allCommandMessages.filter((msg) => !emittedCommandIds.has(msg.id))
             : allCommandMessages;
-        const visibleCommandMessages = commandMessages.filter(msg => !msg.isApprovalRejection);
+        const visibleCommandMessages = commandMessages.filter((msg) => !msg.isApprovalRejection);
         const response = {
             type: 'response',
             commandMessages: visibleCommandMessages,
             finalText: finalOutputOverride ?? result.finalOutput ?? 'Done.',
             reasoningText: reasoningOutputOverride,
+            usage: usage ?? extractUsage(result),
         };
         return response;
     }