@a5c-ai/agent-comm-mux 5.0.1-staging.04ca6ab00d21

package/dist/run-handle-impl.js

@@ -0,0 +1,695 @@
+/**
+ * RunHandleImpl — concrete implementation of RunHandle.
+ *
+ * Implements:
+ * - Typed EventEmitter dispatch with per-type handler maps
+ * - AsyncIterator fan-out with shared replay buffer (high-water-mark bounded)
+ * - State machine (via state-machine.ts)
+ * - Thenable contract (lazy internal promise, resolves to RunResult)
+ * - Control method guards (RUN_NOT_ACTIVE, INVALID_STATE_TRANSITION)
+ * - Interaction channel wiring
+ */
+import { AgentMuxError } from './errors.js';
+import { assertTransition, isTerminal } from './state-machine.js';
+import { InteractionChannelImpl } from './interaction-channel-impl.js';
+import { accumulateTokenUsage, accumulateCost, buildTokenUsageSummary, } from './run-handle-cost.js';
+import { createComponentLogger, telemetry } from '@a5c-ai/agent-mux-observability';
+/** Default high-water mark for the shared event buffer. */
+const DEFAULT_HWM = 1000;
+// ---------------------------------------------------------------------------
+// RunHandleImpl
+// ---------------------------------------------------------------------------
+export class RunHandleImpl {
+    // ── Identity ─────────────────────────────────────────────────────────────
+    runId;
+    agent;
+    model;
+    // ── State machine ─────────────────────────────────────────────────────────
+    _state = 'spawned';
+    // ── EventEmitter handler map ──────────────────────────────────────────────
+    /** Map from event type -> array of handlers. */
+    _handlers = new Map();
+    // ── AsyncIterator fan-out ─────────────────────────────────────────────────
+    /** Shared ordered buffer of all events emitted so far. */
+    _buffer = [];
+    /** Per-iterator tracking state. */
+    _iterators = new Set();
+    /** When true, the run has ended and all iterators should drain and stop. */
+    _done = false;
+    /** High-water mark for the buffer. */
+    _hwm;
+    // ── Thenable / result promise (lazy, per spec §2) ─────────────────────────
+    _resultPromise = null;
+    _resolveResult = null;
+    /** Queued result if complete() is called before the promise is created. */
+    _pendingResult = null;
+    // ── Run result accumulators ───────────────────────────────────────────────
+    _text = '';
+    _sessionId;
+    _cost = null;
+    _startTime = Date.now();
+    _tokenUsage = { inputTokens: 0, outputTokens: 0, thinkingTokens: 0, cachedTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+    _turnCount = 0;
+    _exitCode = null;
+    _signal = null;
+    _runError = null;
+    _collectedEvents = [];
+    _collectEvents;
+    _tags;
+    // ── Interaction channel ───────────────────────────────────────────────────
+    interaction;
+    /** Logger instance for this run. */
+    logger;
+    /** OpenTelemetry span for this run. */
+    _runSpan;
+    /** Map of active tool call spans by toolCallId. */
+    _toolSpans = new Map();
+    /** Map of active subagent spans by subagentId. */
+    _subagentSpans = new Map();
+    /** Bound runtime input transport used by send()/queue()/steer(). */
+    _inputTransport = null;
+    /** Bound interaction response transport used by approval/input dispatch. */
+    _interactionTransport = null;
+    /** Deferred prompts waiting for a matching run boundary. */
+    _deferredPrompts = [];
+    /** Serializes deferred prompt delivery. */
+    _deferredDeliveryChain = Promise.resolve();
+    /** Monotonic counter for deferred prompt bookkeeping. */
+    _deferredPromptSeq = 0;
+    // ── Constructor ───────────────────────────────────────────────────────────
+    constructor(options) {
+        this.runId = options.runId;
+        this.agent = options.agent;
+        this.model = options.model;
+        this._hwm = options.bufferHighWaterMark ?? DEFAULT_HWM;
+        this._collectEvents = options.collectEvents ?? false;
+        this._tags = options.tags ?? [];
+        this.interaction = new InteractionChannelImpl(options.approvalMode ?? 'prompt');
+        // Initialize logger for this run
+        this.logger = createComponentLogger(this.agent);
+        // Start OpenTelemetry span for this run
+        this._runSpan = telemetry.startRunSpan(this.runId, this.agent, this.model);
+        // Wire up the interaction channel's response dispatcher.
+        this.interaction.setDispatch(async (id, response) => {
+            await this._handleInteractionResponse(id, response);
+        });
+        // Result promise is created lazily per spec §2.
+    }
+    // ── State machine ─────────────────────────────────────────────────────────
+    /** Current run state. */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Transition to a new state.
+     * Validates the transition and updates the internal state.
+     * Does NOT emit a state-change event — callers should emit the appropriate event then call this.
+     */
+    transitionTo(next) {
+        assertTransition(this._state, next);
+        this._state = next;
+    }
+    // ── Event dispatch ────────────────────────────────────────────────────────
+    /**
+     * Emit an event. Called by the adapter or test harness.
+     *
+     * 1. Accumulates relevant fields (text, token usage, cost, session ID).
+     * 2. Appends to the shared buffer (with HWM enforcement).
+     * 3. Wakes up waiting async iterators.
+     * 4. Dispatches to registered EventEmitter handlers.
+     */
+    emit(event) {
+        // Log important events
+        this._logEvent(event);
+        // Accumulate run result fields.
+        this._accumulate(event);
+        // Collect if requested.
+        if (this._collectEvents) {
+            this._collectedEvents.push(event);
+        }
+        // Append to shared buffer with HWM enforcement.
+        if (this._buffer.length >= this._hwm) {
+            // Drop oldest events already consumed by all iterators per spec §10.3.
+            let minPosition = this._buffer.length;
+            for (const iter of this._iterators) {
+                if (iter.position < minPosition)
+                    minPosition = iter.position;
+            }
+            if (minPosition > 0) {
+                // Evict events already consumed by all iterators.
+                this._buffer.splice(0, minPosition);
+                for (const iter of this._iterators) {
+                    iter.position -= minPosition;
+                }
+            }
+            else if (this._buffer.length >= this._hwm) {
+                // All iterators at position 0 — must drop oldest anyway.
+                this._buffer.shift();
+                // No position adjustment needed since they haven't consumed it.
+            }
+            this._emitDebugEvent('warn', `Event buffer overflow: events dropped (HWM=${this._hwm})`);
+        }
+        this._buffer.push(event);
+        // Wake waiting iterators.
+        for (const iter of this._iterators) {
+            if (iter.waiting !== null) {
+                const resolve = iter.waiting;
+                iter.waiting = null;
+                iter.position++;
+                resolve({ value: event, done: false });
+            }
+        }
+        // Dispatch to EventEmitter handlers.
+        this._dispatchHandlers(event);
+        // Deferred prompt delivery runs after consumers have observed the
+        // boundary event that triggered it.
+        this._triggerDeferredPromptDelivery(event);
+    }
+    /**
+     * Log important events for observability.
+     */
+    _logEvent(event) {
+        switch (event.type) {
+            case 'tool_call_start':
+                this.logger.toolCallStart({
+                    runId: this.runId,
+                    toolName: event.toolName,
+                    toolCallId: event.toolCallId,
+                    args: event.inputAccumulated,
+                });
+                // Start tool call span
+                const toolSpan = telemetry.startToolCallSpan(event.toolName, event.toolCallId, this._runSpan);
+                this._toolSpans.set(event.toolCallId, toolSpan);
+                break;
+            case 'tool_call_ready':
+                // Tool call is ready to be executed (or result is pending)
+                break;
+            case 'tool_result':
+                {
+                    const span = this._toolSpans.get(event.toolCallId);
+                    const duration = event.durationMs || 0;
+                    this.logger.toolCallComplete({
+                        runId: this.runId,
+                        toolName: event.toolName,
+                        toolCallId: event.toolCallId,
+                        duration,
+                        result: event.result,
+                    });
+                    if (span) {
+                        telemetry.endSpanSuccess(span, {
+                            'tool.duration_ms': duration,
+                        });
+                        this._toolSpans.delete(event.toolCallId);
+                    }
+                    telemetry.recordToolCall(event.toolName, duration, true);
+                }
+                break;
+            case 'tool_error':
+                {
+                    const span = this._toolSpans.get(event.toolCallId);
+                    const duration = event.durationMs || 0;
+                    this.logger.toolCallComplete({
+                        runId: this.runId,
+                        toolName: event.toolName,
+                        toolCallId: event.toolCallId,
+                        duration,
+                        result: event.error,
+                    });
+                    if (span) {
+                        telemetry.endSpanError(span, event.error);
+                        this._toolSpans.delete(event.toolCallId);
+                    }
+                    telemetry.recordToolCall(event.toolName, duration, false);
+                }
+                break;
+            case 'subagent_spawn':
+                {
+                    const subagentSpan = telemetry.startSubagentSpan(event.subagentId, event.agentName, this._runSpan);
+                    this._subagentSpans.set(event.subagentId, subagentSpan);
+                }
+                break;
+            case 'subagent_result':
+                {
+                    const span = this._subagentSpans.get(event.subagentId);
+                    if (span) {
+                        telemetry.endSpanSuccess(span);
+                        this._subagentSpans.delete(event.subagentId);
+                    }
+                }
+                break;
+            case 'subagent_error':
+                {
+                    const span = this._subagentSpans.get(event.subagentId);
+                    if (span) {
+                        telemetry.endSpanError(span, event.error);
+                        this._subagentSpans.delete(event.subagentId);
+                    }
+                }
+                break;
+            case 'error':
+                this.logger.error({
+                    runId: this.runId,
+                    agent: this.agent,
+                    error: {
+                        code: event.code,
+                        message: event.message,
+                        recoverable: event.recoverable,
+                    },
+                }, 'Agent error occurred');
+                break;
+            case 'session_start':
+                this.logger.session('Session started', {
+                    runId: this.runId,
+                    sessionId: event.sessionId,
+                    action: 'create',
+                });
+                break;
+            case 'session_resume':
+                this.logger.session('Session resumed', {
+                    runId: this.runId,
+                    sessionId: event.sessionId,
+                    action: 'resume',
+                });
+                break;
+            case 'cost':
+                this.logger.debug({
+                    runId: this.runId,
+                    cost: event.cost,
+                }, 'Cost update received');
+                break;
+            // Log other important events as debug
+            default:
+                if (['approval_request', 'input_required'].includes(event.type)) {
+                    this.logger.debug({ runId: this.runId, eventType: event.type }, 'Interaction event');
+                }
+                break;
+        }
+    }
+    /**
+     * Signal that the run has ended with the given exit information.
+     * Resolves the result promise and terminates all async iterators.
+     */
+    complete(exitReason, exitCode, signal) {
+        this._exitCode = exitCode;
+        this._signal = signal;
+        this._done = true;
+        this.interaction.terminate();
+        // Log run completion
+        const duration = Date.now() - this._startTime;
+        const cost = this._cost ? {
+            totalUsd: this._cost.totalUsd,
+            inputTokens: this._tokenUsage.inputTokens,
+            outputTokens: this._tokenUsage.outputTokens,
+            thinkingTokens: this._tokenUsage.thinkingTokens,
+        } : undefined;
+        if (exitReason === 'completed') {
+            this.logger.runComplete({
+                runId: this.runId,
+                agent: this.agent,
+                duration,
+                cost,
+            });
+            telemetry.recordRunComplete(this.agent, this.model, duration, cost);
+            telemetry.endSpanSuccess(this._runSpan, {
+                exitReason,
+                durationMs: duration,
+                ...(cost || {}),
+            });
+        }
+        else {
+            const error = this._runError || { message: `Run failed with reason: ${exitReason}` };
+            this.logger.runError({
+                runId: this.runId,
+                agent: this.agent,
+                error,
+            });
+            telemetry.recordRunError(this.agent, this.model, error.message, cost);
+            telemetry.endSpanError(this._runSpan, error.message, {
+                exitReason,
+                durationMs: duration,
+                ...(cost || {}),
+            });
+        }
+        // Wake all waiting iterators with done = true.
+        for (const iter of this._iterators) {
+            if (iter.waiting !== null) {
+                const resolve = iter.waiting;
+                iter.waiting = null;
+                resolve({ value: undefined, done: true });
+            }
+        }
+        // Resolve the result promise (or queue for lazy creation).
+        const result = this._buildResult(exitReason);
+        if (this._resolveResult) {
+            this._resolveResult(result);
+        }
+        else {
+            this._pendingResult = result;
+        }
+    }
+    // ── AsyncIterable ─────────────────────────────────────────────────────────
+    [Symbol.asyncIterator]() {
+        const iterState = {
+            position: 0,
+            waiting: null,
+        };
+        this._iterators.add(iterState);
+        const self = this;
+        return {
+            next() {
+                // Replay buffered events that this iterator hasn't consumed yet.
+                if (iterState.position < self._buffer.length) {
+                    const event = self._buffer[iterState.position++];
+                    return Promise.resolve({ value: event, done: false });
+                }
+                // If the run is done and we've consumed all buffered events, terminate.
+                if (self._done) {
+                    self._iterators.delete(iterState);
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                // Wait for the next event.
+                return new Promise((resolve) => {
+                    iterState.waiting = resolve;
+                });
+            },
+            return() {
+                iterState.waiting = null;
+                self._iterators.delete(iterState);
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+    // ── EventEmitter ──────────────────────────────────────────────────────────
+    on(type, handler) {
+        const list = this._handlers.get(type) ?? [];
+        list.push(handler);
+        this._handlers.set(type, list);
+        return this;
+    }
+    off(type, handler) {
+        const list = this._handlers.get(type);
+        if (!list)
+            return this;
+        const idx = list.indexOf(handler);
+        if (idx !== -1)
+            list.splice(idx, 1);
+        return this;
+    }
+    once(type, handler) {
+        const wrapper = (event) => {
+            this.off(type, wrapper);
+            handler(event);
+        };
+        return this.on(type, wrapper);
+    }
+    // ── Thenable ──────────────────────────────────────────────────────────────
+    /** Lazily create the result promise per spec §2. */
+    _ensureResultPromise() {
+        if (!this._resultPromise) {
+            if (this._pendingResult) {
+                // complete() was called before anyone accessed the promise.
+                this._resultPromise = Promise.resolve(this._pendingResult);
+            }
+            else {
+                this._resultPromise = new Promise((resolve) => {
+                    this._resolveResult = resolve;
+                });
+            }
+        }
+        return this._resultPromise;
+    }
+    get then() {
+        const p = this._ensureResultPromise();
+        return p.then.bind(p);
+    }
+    get catch() {
+        const p = this._ensureResultPromise();
+        return p.catch.bind(p);
+    }
+    get finally() {
+        const p = this._ensureResultPromise();
+        return p.finally.bind(p);
+    }
+    result() {
+        return this._ensureResultPromise();
+    }
+    /** @internal Bind the active runtime input transport. */
+    bindInputTransport(writer) {
+        this._inputTransport = writer;
+    }
+    /** @internal Bind the active runtime interaction transport. */
+    bindInteractionTransport(writer) {
+        this._interactionTransport = writer;
+    }
+    // ── Interaction methods ───────────────────────────────────────────────────
+    async send(text) {
+        this._assertActive();
+        if (!text) {
+            throw new AgentMuxError('VALIDATION_ERROR', 'send() requires non-empty text', false);
+        }
+        await this._sendNow(text);
+    }
+    async queue(prompt, options) {
+        await this._enqueueDeferredPrompt('queue', prompt, options?.when ?? 'next-turn');
+    }
+    async approve(detail) {
+        this._assertActive();
+        const pending = this.interaction.pending.filter((p) => p.type === 'approval');
+        if (pending.length === 0) {
+            throw new AgentMuxError('NO_PENDING_INTERACTION', 'No pending approval interaction', false);
+        }
+        await this.interaction.respond(pending[0].id, { type: 'approve', detail });
+    }
+    async deny(reason) {
+        this._assertActive();
+        const pending = this.interaction.pending.filter((p) => p.type === 'approval');
+        if (pending.length === 0) {
+            throw new AgentMuxError('NO_PENDING_INTERACTION', 'No pending approval interaction', false);
+        }
+        await this.interaction.respond(pending[0].id, { type: 'deny', reason });
+    }
+    async continue(prompt) {
+        this._assertActive();
+        if (!prompt) {
+            throw new AgentMuxError('VALIDATION_ERROR', 'continue() requires non-empty prompt', false);
+        }
+        // Semantically equivalent to send() — adapters may differentiate later.
+        await this.send(prompt);
+    }
+    async steer(prompt, options) {
+        await this._enqueueDeferredPrompt('steer', prompt, options?.when ?? 'after-response');
+    }
+    // ── Control methods ───────────────────────────────────────────────────────
+    async interrupt() {
+        this._assertActive();
+        this.transitionTo('interrupted');
+    }
+    async abort() {
+        if (isTerminal(this._state)) {
+            // No-op for already-terminated runs.
+            return;
+        }
+        this.transitionTo('aborted');
+    }
+    async pause() {
+        this._assertActive();
+        this.transitionTo('paused');
+    }
+    async resume() {
+        this._assertActive();
+        this.transitionTo('running');
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    _assertActive() {
+        if (isTerminal(this._state)) {
+            throw new AgentMuxError('RUN_NOT_ACTIVE', `Run ${this.runId} is not active (state: ${this._state})`, false);
+        }
+    }
+    _accumulate(event) {
+        switch (event.type) {
+            case 'text_delta':
+                this._text += event.delta;
+                break;
+            case 'session_start':
+                this._sessionId = event.sessionId;
+                break;
+            case 'token_usage':
+                accumulateTokenUsage(this._tokenUsage, event);
+                break;
+            case 'cost':
+                this._cost = accumulateCost(this._cost, event);
+                break;
+            case 'turn_start':
+                this._turnCount = event.turnIndex + 1;
+                break;
+            case 'crash':
+                this._runError = {
+                    code: 'AGENT_CRASH',
+                    message: event.stderr || 'Agent crashed',
+                    stderr: event.stderr,
+                    recoverable: false,
+                };
+                break;
+            case 'error':
+                this._runError = {
+                    code: event.code,
+                    message: event.message,
+                    stderr: '',
+                    recoverable: event.recoverable,
+                };
+                break;
+            case 'approval_request':
+                this.interaction.handleApprovalRequest(event);
+                break;
+            case 'input_required':
+                this.interaction.handleInputRequired(event);
+                break;
+        }
+    }
+    _dispatchHandlers(event) {
+        const list = this._handlers.get(event.type);
+        if (!list || list.length === 0)
+            return;
+        // Invoke handlers in registration order; catch errors and emit debug events per spec §10.4.
+        for (const handler of list.slice()) {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                // Per spec: errors in handlers are caught, logged via debug event,
+                // and do not prevent subsequent handlers from executing.
+                this._emitDebugEvent('warn', `EventEmitter handler threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /** Emit a debug event without recursing through _dispatchHandlers for debug handlers. */
+    _emitDebugEvent(level, message) {
+        const debugEvent = {
+            type: 'debug',
+            runId: this.runId,
+            agent: this.agent,
+            timestamp: Date.now(),
+            level,
+            message,
+        };
+        // Append to buffer and collected events, but dispatch to debug handlers
+        // directly to avoid infinite recursion.
+        if (this._collectEvents) {
+            this._collectedEvents.push(debugEvent);
+        }
+        this._buffer.push(debugEvent);
+        // Wake waiting iterators for the debug event.
+        for (const iter of this._iterators) {
+            if (iter.waiting !== null) {
+                const resolve = iter.waiting;
+                iter.waiting = null;
+                iter.position++;
+                resolve({ value: debugEvent, done: false });
+            }
+        }
+        // Dispatch only to 'debug' handlers (not the handler that just threw).
+        const debugHandlers = this._handlers.get('debug');
+        if (debugHandlers && debugHandlers.length > 0) {
+            for (const h of debugHandlers.slice()) {
+                try {
+                    h(debugEvent);
+                }
+                catch {
+                    // Swallow errors in debug handlers to prevent infinite recursion.
+                }
+            }
+        }
+    }
+    _buildResult(exitReason) {
+        const durationMs = Date.now() - this._startTime;
+        const tokenUsage = buildTokenUsageSummary(this._tokenUsage);
+        return {
+            runId: this.runId,
+            agent: this.agent,
+            model: this.model,
+            sessionId: this._sessionId,
+            text: this._text,
+            cost: this._cost,
+            durationMs,
+            exitCode: this._exitCode,
+            signal: this._signal,
+            exitReason,
+            tokenUsage,
+            turnCount: this._turnCount,
+            error: this._runError,
+            events: this._collectEvents ? [...this._collectedEvents] : [],
+            tags: [...this._tags],
+        };
+    }
+    async _handleInteractionResponse(_id, _response) {
+        const writer = this._interactionTransport;
+        if (!writer) {
+            return;
+        }
+        await writer(_id, _response);
+    }
+    async _sendNow(text) {
+        const writer = this._inputTransport;
+        if (!writer) {
+            throw new AgentMuxError('STDIN_NOT_AVAILABLE', 'Agent stdin is not available', false);
+        }
+        await writer(text);
+    }
+    async _enqueueDeferredPrompt(mode, prompt, when) {
+        this._assertActive();
+        if (!prompt) {
+            const method = mode === 'queue' ? 'queue()' : 'steer()';
+            throw new AgentMuxError('VALIDATION_ERROR', `${method} requires non-empty prompt`, false);
+        }
+        if (!this._inputTransport) {
+            throw new AgentMuxError('STDIN_NOT_AVAILABLE', 'Agent stdin is not available', false);
+        }
+        this._deferredPrompts.push({
+            id: `deferred-${++this._deferredPromptSeq}`,
+            mode,
+            prompt,
+            when,
+        });
+    }
+    _triggerDeferredPromptDelivery(event) {
+        if (this._deferredPrompts.length === 0 || !this._inputTransport) {
+            return;
+        }
+        const boundaries = this._boundariesForEvent(event);
+        if (boundaries.length === 0) {
+            return;
+        }
+        const deliverNow = this._deferredPrompts.filter((entry) => boundaries.includes(entry.when));
+        if (deliverNow.length === 0) {
+            return;
+        }
+        const pending = this._deferredPrompts.filter((entry) => !boundaries.includes(entry.when));
+        this._deferredPrompts.splice(0, this._deferredPrompts.length, ...pending);
+        this._deferredDeliveryChain = this._deferredDeliveryChain
+            .then(async () => {
+            for (const entry of deliverNow) {
+                try {
+                    await this._sendNow(entry.prompt);
+                }
+                catch (err) {
+                    this._emitDebugEvent('warn', `Deferred ${entry.mode} delivery failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        })
+            .catch(() => { });
+    }
+    _boundariesForEvent(event) {
+        switch (event.type) {
+            case 'tool_result':
+            case 'tool_error':
+                return ['after-tool'];
+            case 'message_stop':
+                return ['after-response', 'next-turn'];
+            case 'turn_end':
+                return ['next-turn'];
+            default:
+                return [];
+        }
+    }
+}
+//# sourceMappingURL=run-handle-impl.js.map