@amodalai/runtime 0.1.26 → 0.2.1

package/dist/src/agent/loop.js

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Agent Loop (State Machine Core)
+ *
+ * The outer `runAgent()` async generator drives state transitions and
+ * yields SSE events. Each state handler returns the next state plus
+ * a list of effects (SSE events) to emit.
+ *
+ * The loop is transport-agnostic — the caller (HTTP route, automation
+ * runner, eval runner) iterates over it and decides what to do with
+ * the events.
+ */
+import { SSEEventType } from '../types.js';
+import { handleThinking } from './states/thinking.js';
+import { handleStreaming } from './states/streaming.js';
+import { handleExecuting } from './states/executing.js';
+import { handleConfirming } from './states/confirming.js';
+import { handleCompacting } from './states/compacting.js';
+import { handleDispatching } from './states/dispatching.js';
+// ---------------------------------------------------------------------------
+// Transition dispatcher
+// ---------------------------------------------------------------------------
+/**
+ * Dispatch to the appropriate state handler based on the current state.
+ *
+ * Uses exhaustive switch with `never` check so adding a new state
+ * variant causes a compile error, not a silent fallthrough.
+ */
+export async function transition(state, ctx) {
+    switch (state.type) {
+        case 'thinking':
+            return handleThinking(state, ctx);
+        case 'streaming':
+            return handleStreaming(state, ctx);
+        case 'executing':
+            return handleExecuting(state, ctx);
+        case 'confirming':
+            return handleConfirming(state, ctx);
+        case 'compacting':
+            return handleCompacting(state, ctx);
+        case 'dispatching':
+            return handleDispatching(state, ctx);
+        case 'done':
+            // Should never be called with 'done' state — the loop exits before this
+            return { next: state, effects: [] };
+        default: {
+            const _exhaustive = state;
+            throw new Error(`Unhandled agent state: ${_exhaustive.type}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Main loop
+// ---------------------------------------------------------------------------
+/**
+ * Run the agent loop as an async generator yielding SSE events.
+ *
+ * The generator:
+ * 1. Emits an `init` event
+ * 2. Transitions through states until `done`
+ * 3. Checks abort signal and turn budget between transitions
+ * 4. Emits a `done` event with token usage
+ *
+ * Usage:
+ * ```typescript
+ * for await (const event of runAgent({ messages, context })) {
+ *   sendSSE(event);
+ * }
+ * ```
+ */
+export async function* runAgent(options) {
+    const { messages, context: ctx } = options;
+    // Emit init event
+    yield {
+        type: SSEEventType.Init,
+        session_id: ctx.sessionId,
+        timestamp: new Date().toISOString(),
+    };
+    let state = { type: 'thinking', messages };
+    ctx.logger.info('agent_loop_start', {
+        session: ctx.sessionId,
+        maxTurns: ctx.maxTurns,
+        messageCount: messages.length,
+    });
+    while (state.type !== 'done') {
+        const result = await transition(state, ctx);
+        // Yield all effects (SSE events) to the caller
+        for (const event of result.effects) {
+            yield event;
+        }
+        // Check abort between every state transition
+        if (ctx.signal.aborted) {
+            ctx.logger.info('agent_loop_aborted', {
+                session: ctx.sessionId,
+                turn: ctx.turnCount,
+                previousState: state.type,
+            });
+            state = { type: 'done', usage: { ...ctx.usage }, reason: 'user_abort' };
+            continue;
+        }
+        // Check turn budget
+        if (ctx.turnCount >= ctx.maxTurns && result.next.type !== 'done') {
+            ctx.logger.warn('agent_loop_max_turns', {
+                session: ctx.sessionId,
+                turnCount: ctx.turnCount,
+                maxTurns: ctx.maxTurns,
+            });
+            state = { type: 'done', usage: { ...ctx.usage }, reason: 'max_turns' };
+            continue;
+        }
+        // Check token budget — closes the silent-cost-runaway hole where a long-
+        // running automation could burn through a large budget in a tight retry
+        // loop. Undefined maxSessionTokens means no cap (existing behavior).
+        if (ctx.maxSessionTokens !== undefined &&
+            ctx.usage.totalTokens >= ctx.maxSessionTokens &&
+            result.next.type !== 'done') {
+            ctx.logger.info('agent_loop_budget_exceeded', {
+                session: ctx.sessionId,
+                turnCount: ctx.turnCount,
+                totalTokens: ctx.usage.totalTokens,
+                maxSessionTokens: ctx.maxSessionTokens,
+            });
+            state = { type: 'done', usage: { ...ctx.usage }, reason: 'budget_exceeded' };
+            continue;
+        }
+        state = result.next;
+    }
+    // Emit done event with usage — always, regardless of done reason
+    ctx.logger.info('agent_loop_done', {
+        session: ctx.sessionId,
+        reason: state.reason,
+        turns: ctx.turnCount,
+        usage: ctx.usage,
+    });
+    yield {
+        type: SSEEventType.Done,
+        timestamp: new Date().toISOString(),
+        reason: state.reason,
+        usage: {
+            input_tokens: ctx.usage.inputTokens,
+            output_tokens: ctx.usage.outputTokens,
+            cached_tokens: ctx.usage.cachedInputTokens ?? 0,
+            cache_creation_tokens: ctx.usage.cacheCreationInputTokens ?? 0,
+            total_tokens: ctx.usage.totalTokens,
+        },
+    };
+}
+//# sourceMappingURL=loop.js.map

package/dist/src/agent/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../../src/agent/loop.ts"],"names":[],"mappings":"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"}