@falai/agent 2.7.0 → 3.1.0

package/docs/reference/providers.md

@@ -11,15 +11,17 @@ order: 10
 
 Providers are the strategy plug between an `Agent` and a model vendor. Every provider implements the same `AiProvider` interface, so the Agent itself stays vendor-agnostic. Pass an instance to `createAgent({ provider })` and the agent talks to that vendor for every turn (and for compaction, if you wire it in).
 
-`@falai/agent` ships five built-in providers. All five accept an `apiKey` and a required `model`, support `backupModels` for automatic failover on overload or 5xx, and accept a vendor-typed `config` object that flows through to the underlying SDK.
+`@falai/agent` ships five built-in providers. All five accept an `apiKey` and a required `model`, support `backupModels` for automatic failover, and take the same neutral `RequestConfig` for sampling defaults.
 
-| Provider | Class | Options | SDK |
-|----------|-------|---------|-----|
-| Google Gemini | `GeminiProvider` | `GeminiProviderOptions` | `@google/genai` |
-| OpenAI | `OpenAIProvider` | `OpenAIProviderOptions` | `openai` |
-| Anthropic Claude | `AnthropicProvider` | `AnthropicProviderOptions` | `@anthropic-ai/sdk` |
-| OpenRouter | `OpenRouterProvider` | `OpenRouterProviderOptions` | `openai` (compat) |
-| DeepSeek | `DeepSeekProvider` | `DeepSeekProviderOptions` | `openai` (compat) |
+There are no vendor SDKs behind them. Every provider is a thin binding over [`@providerkit/core`](https://www.npmjs.com/package/@providerkit/core), which speaks each vendor's REST API over `fetch` — so installing this package does not install one vendor's SDK for a consumer who uses another.
+
+| Provider | Class | Options | Wire |
+|----------|-------|---------|------|
+| Google Gemini | `GeminiProvider` | `GeminiProviderOptions` | `generateContent` (SSE) |
+| OpenAI | `OpenAIProvider` | `OpenAIProviderOptions` | Responses API |
+| Anthropic Claude | `AnthropicProvider` | `AnthropicProviderOptions` | Messages API |
+| OpenRouter | `OpenRouterProvider` | `OpenRouterProviderOptions` | chat completions |
+| DeepSeek | `DeepSeekProvider` | `DeepSeekProviderOptions` | chat completions |
 
 ## Capabilities
 
@@ -86,9 +88,10 @@ interface GeminiProviderOptions {
   apiKey: string;
   model: string;
   backupModels?: string[];
-  config?: Partial<GenerateContentConfig>; // from @google/genai
+  baseUrl?: string;
+  config?: RequestConfig;                  // temperature, topP, maxTokens, stopSequences
   retryConfig?: { timeout?: number; retries?: number };
-  client?: GoogleGenAI;                    // pre-configured SDK client override
+  fetchImpl?: typeof fetch;                // scripted wire, for tests
 }
 ```
 
@@ -140,7 +143,7 @@ interface OpenAIProviderOptions {
 | `organization` | `string` | no | — | Forwarded as `OpenAI-Organization`. |
 | `model` | `string` | yes | — | e.g. `"gpt-5.6"`, `"gpt-5.4-mini"`. |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on overload/rate-limit errors. |
-| `config` | OpenAI params | no | — | Defaults for `temperature`, `top_p`, etc. |
+| `config` | `RequestConfig` | no | — | Defaults for `temperature`, `topP`, `maxTokens`, `stopSequences`. |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
 | `retryConfig.retries` | `number` | no | `3` | Total attempts. |
 
@@ -179,7 +182,7 @@ interface AnthropicProviderOptions {
 | `apiKey` | `string` | yes* | — | Throws if empty (unless `client` is set). |
 | `model` | `string` | yes | — | e.g. `"claude-sonnet-5"`, `"claude-opus-5"`. |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on retriable failures (rate limits, overload incl. 529, timeouts, network). |
-| `config` | Anthropic params | no | — | Defaults for `max_tokens`, `system`, etc. The provider sets `max_tokens=4096` if neither `config.max_tokens` nor `parameters.maxOutputTokens` is set. |
+| `config` | `RequestConfig` | no | — | Defaults for `temperature`, `topP`, `maxTokens`, `stopSequences`. `maxTokens` falls back to 4096 if neither it nor `parameters.maxOutputTokens` is set. |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. On streams it also bounds time-to-first-token. |
 | `retryConfig.retries` | `number` | no | `3` | Total attempts. |
 | `client` | `Anthropic` | no | — | Pre-configured SDK client; overrides the internally-constructed one. Intended for tests injecting scripted transports; production callers should pass `apiKey`. |
@@ -190,7 +193,7 @@ interface AnthropicProviderOptions {
 const anthropic = new AnthropicProvider({
   apiKey: process.env.ANTHROPIC_API_KEY!,
   model: "claude-sonnet-5",
-  config: { max_tokens: 8192 },
+  config: { maxTokens: 8192 },
 });
 ```
 
@@ -282,12 +285,11 @@ const deepseek = new DeepSeekProvider({
 
 ## Building a custom OpenAI-compatible provider
 
-Many vendors (Groq, Together, Fireworks, …) expose OpenAI-compatible chat-completions APIs. Instead of implementing `AiProvider` from scratch, subclass the exported `OpenAICompatibleProvider` base class — it handles message/history building, tool-call parsing, streaming chunks, backup-model fallback, retries, schema passthrough, and normalized `ProviderError` wrapping. `OpenAIProvider`, `OpenRouterProvider`, and `DeepSeekProvider` are themselves thin subclasses.
+Many vendors (Groq, Together, Fireworks, …) expose OpenAI-compatible chat-completions APIs. Instead of implementing `AiProvider` from scratch, subclass the exported `OpenAICompatibleProvider` base class — history and tool translation, streaming, tool-call assembly, backup-model fallback, retries and normalized `ProviderError`s all come with it. `OpenAIProvider`, `OpenRouterProvider`, and `DeepSeekProvider` are themselves thin subclasses.
 
-A minimal subclass supplies the configured client, naming, and capabilities:
+A minimal subclass supplies the endpoint, naming, and capabilities:
 
 ```typescript
-import OpenAI from "openai";
 import {
   OpenAICompatibleProvider,
   type ProviderCapabilities,
@@ -303,23 +305,20 @@ export class GroqProvider extends OpenAICompatibleProvider {
     supportsPromptCaching: false,
   };
 
-  protected readonly logLabel = "GROQ";       // tag in log lines
-  protected readonly displayName = "Groq";    // name in retry/error messages
-
   constructor(options: { apiKey: string; model: string; backupModels?: string[] }) {
     super({
-      client: new OpenAI({
-        apiKey: options.apiKey,
-        baseURL: "https://api.groq.com/openai/v1",
-      }),
+      id: "groq",
+      apiKey: options.apiKey,
+      baseUrl: "https://api.groq.com/openai",
       model: options.model,
+      structuredOutput: "json_schema",
       backupModels: options.backupModels,
     });
   }
 }
 ```
 
-That is a complete, working provider. For genuinely vendor-specific behavior, override the protected hooks — `DeepSeekProvider` is the reference pattern: it overrides `executeStructuredGenerate` (no `responses.parse` API), `structuredResponseFormat` (native `json_schema` enforcement), `configureStreamParams` (usage in stream chunks), and `onStreamDelta` (reasoning content on the delta).
+That is a complete, working provider. Vendor-specific wire behaviour is not this layer's job any more: it lives in `@providerkit/core`, which the provider classes are thin bindings over. `DeepSeekProvider` is the reference pattern for what is left here — an id, a base URL, the structured-output mode the endpoint actually supports, and its capabilities. To bind a core provider this package does not ship a class for, subclass `ProviderAdapter` directly.
 
 ## Errors
 
@@ -333,7 +332,11 @@ All five providers share the same construction-time guards and runtime failure m
 | Primary and every backup model fail | `ProviderError` with a normalized `code` | After exhausting retries and `backupModels`. Propagates bare out of `respond()`. |
 | Anthropic streaming with `system: undefined` | Vendor 400 | Set `config.system` or rely on history-derived system messages. |
 
-The retry/backup logic only kicks in for **transient** errors: rate limits (429), overload/availability (500/503, Anthropic's 529, `overloaded`-style codes and messages such as `overloaded`, `unavailable`, `internal error`, or OpenRouter's `capacity`), timeouts, and network faults. Deterministic failures — auth (401/403), invalid requests (400/404/422), and caller aborts — fail fast without burning the retry budget. On streaming calls, only failures *before the first chunk* are retried; `retryConfig.timeout` doubles as the time-to-first-token deadline so a stream that opens and stalls is treated as failed.
+The retry/backup logic only kicks in for **transient** errors: rate limits, overload and availability, timeouts, and network faults. Deterministic failures — a wrong key, an exhausted balance, an invalid request, a caller's abort — fail fast without burning the retry budget. Classification reads the response BODY before its status, because vendors file the same cause under whatever status they like.
+
+Only failures *before the first chunk* are retried: past that the stream is committed, and a retry would replay text the reader has already seen. The same rule governs the walk to a backup model. `retryConfig.timeout` is the silence deadline — the wait allowed before the first byte, and between any two after it — so a stream that opens and stalls is treated as failed while a long, healthy one is left alone.
+
+A model the endpoint will not serve also walks to the next model on the list, which is what the list is for.
 
 ### `ProviderError`
 
@@ -342,24 +345,20 @@ Terminal failures — after retries and backup models are exhausted — throw th
 ```typescript
 import { ProviderError } from "@falai/agent";
 
-type ProviderErrorCode =
-  | 'rate_limited'      // 429-style throttling
-  | 'overloaded'        // capacity / 503 / 529
-  | 'auth'              // invalid or missing credentials
-  | 'invalid_request'   // vendor rejected the request shape
-  | 'schema_rejected'   // structured-output schema rejected
-  | 'timeout'           // per-attempt timeout exhausted
-  | 'network'           // connection-level failure
-  | 'unknown';          // anything unclassified
-
-try {
-  await provider.generateMessage(input);
-} catch (err) {
-  if (err instanceof ProviderError) {
-    console.error(err.provider, err.code); // e.g. "openai" "rate_limited"
-    console.error(err.cause);              // original SDK error
-  }
-}
+type ErrorKind =
+  | 'aborted'      // the caller pressed Stop — never retried
+  | 'timeout'      // our deadline, or a 408
+  | 'network'      // never reached the provider
+  | 'overload'     // theirs and temporary — retry, and try another model
+  | 'rate'         // per-minute throttle — wait, or rotate key or model
+  | 'quota'        // balance or usage window exhausted — waiting will not fix it
+  | 'entitlement'  // the plan never included this API
+  | 'auth'         // the key is wrong, not the request
+  | 'model'        // the model id is not served here
+  | 'context'      // the prompt outgrew the window — send less
+  | 'content'      // safety filter or refusal
+  | 'invalid'      // any other 4xx — a bug in what we sent
+  | 'unknown'
 ```
 
 When the failure surfaces through `agent.respond(...)`, the `ProviderError` propagates **bare** — catch it with `instanceof`, no unwrapping. (On streaming turns, errors arrive wrapped as `ResponseGenerationError` on the final chunk's `error` field, with the original on `.cause`.) See [Errors](./errors.md).

package/examples/01-quickstart.ts

@@ -1,7 +1,7 @@
 /** @intent Minimal agent: one flow, one step, one response.
  *  @teaches createAgent, GeminiProvider, Flow, Step, respond
  *  @readAfter docs/start/02-first-agent.md */
-import { createAgent, GeminiProvider } from "../src";
+import { createAgent, GeminiProvider } from "../src/index.js";
 
 if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 

package/examples/04-instructions.ts

@@ -4,7 +4,7 @@
  * Read next: docs/guides/instructions.md
  */
 
-import { createAgent, GeminiProvider } from "../src";
+import { createAgent, GeminiProvider } from "../src/index.js";
 
 if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 

package/examples/05-branching.ts

@@ -1,8 +1,8 @@
 /** @intent Demonstrates step.branches — source-local forks with if, when, and Directive targets.
  *  @teaches BranchEntry, BranchMap, if-only fork, when-only fork, combined if+when, mixed targets
  *  @readAfter docs/guides/branching.md */
-import { createAgent, GeminiProvider } from "../src";
-import type { BranchMap, Directive, FlowOptions, StepOptions } from "../src";
+import { createAgent, GeminiProvider } from "../src/index.js";
+import type { BranchMap, Directive, FlowOptions, StepOptions } from "../src/index.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 

package/examples/08-persistence.ts

@@ -1,7 +1,7 @@
 /** @intent Session persistence with MemoryAdapter: implicit default, explicit wiring, and sessionId for cross-turn continuity.
  *  @teaches MemoryAdapter, PersistenceConfig, sessionId, session resumption
  *  @readAfter docs/guides/persistence.md */
-import { createAgent, GeminiProvider, MemoryAdapter } from "../src";
+import { createAgent, GeminiProvider, MemoryAdapter } from "../src/index.js";
 
 if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 

package/examples/tsconfig.json

@@ -1,13 +1,15 @@
 {
     "compilerOptions": {
         "target": "ES2022",
-        "module": "ESNext",
+        "module": "node16",
         "lib": [
             "ES2022",
             "DOM"
         ],
-        "moduleResolution": "bundler",
-        "types": [],
+        "moduleResolution": "node16",
+        "types": [
+            "node"
+        ],
         "strict": true,
         "esModuleInterop": true,
         "skipLibCheck": true,
@@ -15,6 +17,7 @@
         "resolveJsonModule": true,
         "allowSyntheticDefaultImports": true,
         "noEmit": true,
+        "allowImportingTsExtensions": true,
         "paths": {
             "@falai/agent": [
                 "../src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.7.0",
+  "version": "3.1.0",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -38,10 +38,11 @@
   },
   "homepage": "https://falai.dev",
   "scripts": {
-    "build": "bun run build:esm && bun run build:cjs && bun run fix:cjs",
+    "build": "bun run build:esm && bun run build:cjs && bun run fix:cjs && bun run check:dist",
     "build:esm": "tsc",
     "build:cjs": "tsc --project tsconfig.cjs.json",
     "fix:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "check:dist": "node --input-type=module -e \"import './dist/index.js'\" && node -e \"require('./dist/cjs/index.js')\"",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "typecheck:examples": "tsc --noEmit --project examples/tsconfig.json",
@@ -49,10 +50,11 @@
     "lint:fix": "eslint src/**/*.ts --fix",
     "clean": "rm -rf dist",
     "prebuild": "bun run clean",
-    "prepublishOnly": "bun run lint && bun run typecheck && bun run build && bun run test",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run typecheck:examples && bun run build && bun run test",
     "release:patch": "bun pm version patch && bun publish",
     "release:minor": "bun pm version minor && bun publish",
-    "release:major": "bun pm version major && bun publish",
+    "release:major": "bun pm version major && bun publish && bun run release:pointer",
+    "release:pointer": "node -e \"const v=require('./package.json').version,p='./pointer/package.json',j=require(p);j.version=v;j.dependencies['@falai/agent']='^'+v.split('.')[0]+'.0.0';require('fs').writeFileSync(p,JSON.stringify(j,null,2)+'\\n')\" && cd pointer && bun install && bun publish",
     "release:alpha": "bun publish --tag alpha",
     "release": "bun publish",
     "test": "bun test tests/*.test.ts"
@@ -77,6 +79,9 @@
   ],
   "author": "Gustavo Salomé <gusnips>",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.12"
+  },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "@types/bun": "^1.3.0",
@@ -88,10 +93,8 @@
     "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.65.0",
-    "@google/genai": "^2.7.0",
-    "loglevel": "^1.9.2",
-    "openai": "^6.3.0"
+    "@providerkit/core": "^0.4.1",
+    "loglevel": "^1.9.2"
   },
   "peerDependencies": {
     "@opensearch-project/opensearch": "^2.0.0",

package/src/adapters/MemoryAdapter.ts

@@ -13,10 +13,10 @@ import type {
   SessionStatus,
   SessionUpdateOptions,
   CreateSessionData,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
-import { cloneDeep } from "../utils/clone";
-import { createSessionId } from "../utils";
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { cloneDeep } from "../utils/clone.js";
+import { createSessionId } from "../utils/index.js";
 
 /**
  * Memory Adapter - Provider-style API for in-memory persistence

package/src/adapters/MongoAdapter.ts

@@ -13,9 +13,9 @@ import type {
   CollectedStateData,
   CreateSessionData,
   SessionUpdateOptions,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
-import { createSessionId } from "../utils";
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { createSessionId } from "../utils/index.js";
 
 /**
  * MongoDB collection interface - matches mongodb driver

package/src/adapters/OpenSearchAdapter.ts

@@ -32,8 +32,8 @@
  * ```
  */
 
-import { cloneDeep } from "../utils/clone";
-import { createSessionId } from "../utils";
+import { cloneDeep } from "../utils/clone.js";
+import { createSessionId } from "../utils/index.js";
 import type {
   PersistenceAdapter,
   SessionRepository,
@@ -43,8 +43,8 @@ import type {
   CollectedStateData,
   CreateSessionData,
   SessionUpdateOptions,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
 
 /**
  * OpenSearch Client interface (minimal typing for the official client)

package/src/adapters/PostgreSQLAdapter.ts

@@ -26,10 +26,10 @@ import type {
   SessionStatus,
   PersistenceAdapter,
   SessionUpdateOptions,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
-import { createSessionId } from "../utils";
-import { deserializeSessionRow } from "./sessionRow";
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { createSessionId } from "../utils/index.js";
+import { deserializeSessionRow } from "./sessionRow.js";
 
 /**
  * PostgreSQL query result interface

package/src/adapters/PrismaAdapter.ts

@@ -15,10 +15,10 @@ import type {
   Event,
   CreateSessionData,
   SessionUpdateOptions,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
-import { logger } from '../utils'
-import { createSessionId } from '../utils';
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { logger } from '../utils/index.js'
+import { createSessionId } from '../utils/index.js';
 
 /**
  * Prisma model operations

package/src/adapters/RedisAdapter.ts

@@ -12,10 +12,10 @@ import type {
   SessionStatus,
   CollectedStateData,
   SessionUpdateOptions,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
-import { createSessionId, logger } from "../utils";
-import { coerceDate } from "./sessionRow";
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { createSessionId, logger } from "../utils/index.js";
+import { coerceDate } from "./sessionRow.js";
 
 /**
  * Redis client interface - matches ioredis/redis clients

package/src/adapters/SQLiteAdapter.ts

@@ -30,10 +30,10 @@ import type {
   CollectedStateData,
   CreateSessionData,
   SessionUpdateOptions,
-} from "../types";
-import { SessionConflictError } from "../types/errors";
-import { createSessionId } from "../utils";
-import { deserializeSessionRow } from "./sessionRow";
+} from "../types/index.js";
+import { SessionConflictError } from "../types/errors.js";
+import { createSessionId } from "../utils/index.js";
+import { deserializeSessionRow } from "./sessionRow.js";
 
 /**
  * SQLite database interface - matches better-sqlite3

package/src/adapters/index.ts

@@ -2,42 +2,42 @@
  * Database adapters for persistence
  */
 
-export { PrismaAdapter } from "./PrismaAdapter";
+export { PrismaAdapter } from "./PrismaAdapter.js";
 export type {
   PrismaClient,
   FieldMappings,
   PrismaAdapterOptions,
-} from "./PrismaAdapter";
+} from "./PrismaAdapter.js";
 
-export { RedisAdapter } from "./RedisAdapter";
-export type { RedisClient, RedisAdapterOptions } from "./RedisAdapter";
+export { RedisAdapter } from "./RedisAdapter.js";
+export type { RedisClient, RedisAdapterOptions } from "./RedisAdapter.js";
 
-export { MongoAdapter } from "./MongoAdapter";
+export { MongoAdapter } from "./MongoAdapter.js";
 export type {
   MongoClient,
   MongoDatabase,
   MongoCollection,
   MongoAdapterOptions,
-} from "./MongoAdapter";
+} from "./MongoAdapter.js";
 
-export { PostgreSQLAdapter } from "./PostgreSQLAdapter";
+export { PostgreSQLAdapter } from "./PostgreSQLAdapter.js";
 export type {
   PgClient,
   PgQueryResult,
   PostgreSQLAdapterOptions,
-} from "./PostgreSQLAdapter";
+} from "./PostgreSQLAdapter.js";
 
-export { SQLiteAdapter } from "./SQLiteAdapter";
+export { SQLiteAdapter } from "./SQLiteAdapter.js";
 export type {
   SqliteDatabase,
   SqliteStatement,
   SQLiteAdapterOptions,
-} from "./SQLiteAdapter";
+} from "./SQLiteAdapter.js";
 
-export { MemoryAdapter } from "./MemoryAdapter";
+export { MemoryAdapter } from "./MemoryAdapter.js";
 
-export { OpenSearchAdapter } from "./OpenSearchAdapter";
+export { OpenSearchAdapter } from "./OpenSearchAdapter.js";
 export type {
   OpenSearchClient,
   OpenSearchAdapterOptions,
-} from "./OpenSearchAdapter";
+} from "./OpenSearchAdapter.js";

package/src/adapters/sessionRow.ts

@@ -11,7 +11,7 @@ import type {
   CollectedStateData,
   SessionData,
   SessionStatus,
-} from "../types";
+} from "../types/index.js";
 
 /**
  * Coerce a raw stored value into a Date. Drivers variously hand back Date

package/src/core/Agent.ts

@@ -18,12 +18,12 @@ import type {
   AiProvider,
   CompactionOptions,
   Directive,
-} from "../types";
-import type { Signal } from "../types/signals";
-import { NotImplementedError } from "../types/errors";
-import { SignalProcessor } from "./SignalProcessor";
-import { SignalEvaluator } from "./SignalEvaluator";
-import type { StreamOptions, GenerateOptions, RespondParams, ResponseModalDeps } from "./ResponseModal";
+} from "../types/index.js";
+import type { Signal } from "../types/signals.js";
+import { NotImplementedError } from "../types/errors.js";
+import { SignalProcessor } from "./SignalProcessor.js";
+import { SignalEvaluator } from "./SignalEvaluator.js";
+import type { StreamOptions, GenerateOptions, RespondParams, ResponseModalDeps } from "./ResponseModal.js";
 import {
   mergeCollected,
   enterFlow,
@@ -32,18 +32,18 @@ import {
   logger,
   LoggerLevel,
   generateSignalId,
-} from "../utils";
-
-import { Flow } from "./Flow";
-import { Step, FlowConfigurationError as StepFlowConfigurationError } from "./Step";
-import { PersistenceManager } from "./PersistenceManager";
-import { SessionManager } from "./SessionManager";
-import { FlowRouter } from "./FlowRouter";
-import { PromptSectionCache } from "./PromptSectionCache";
-
-import { ResponseModal } from "./ResponseModal";
-import { ToolManager } from "./ToolManager";
-import { CompactionEngine } from "./CompactionEngine";
+} from "../utils/index.js";
+
+import { Flow } from "./Flow.js";
+import { Step, FlowConfigurationError as StepFlowConfigurationError } from "./Step.js";
+import { PersistenceManager } from "./PersistenceManager.js";
+import { SessionManager } from "./SessionManager.js";
+import { FlowRouter } from "./FlowRouter.js";
+import { PromptSectionCache } from "./PromptSectionCache.js";
+
+import { ResponseModal } from "./ResponseModal.js";
+import { ToolManager } from "./ToolManager.js";
+import { CompactionEngine } from "./CompactionEngine.js";
 
 /**
  * Error thrown when data validation fails

package/src/core/AutoChainExecutor.ts

@@ -15,20 +15,20 @@
  * Implements Algorithm 1 from `.kiro/specs/auto-steps/design.md`.
  */
 
-import type { Directive, SessionState } from "../types";
-import type { Event } from "../types/history";
-import { FlowConfigurationError, Step } from "./Step";
-import { Flow } from "./Flow";
-import { flow } from "./flow-namespace";
-import { enterStep, mergeCollected, logger } from "../utils";
-import { createTemplateContext } from "../utils/template";
+import type { Directive, SessionState } from "../types/index.js";
+import type { Event } from "../types/history.js";
+import { FlowConfigurationError, Step } from "./Step.js";
+import { Flow } from "./Flow.js";
+import { flow } from "./flow-namespace.js";
+import { enterStep, mergeCollected, logger } from "../utils/index.js";
+import { createTemplateContext } from "../utils/template.js";
 import type {
     StoppedReason,
     BranchMap,
     BranchEntry,
     BranchPredicateContext,
-} from "../types/flow";
-import { evaluateIfPredicates } from "../utils/condition";
+} from "../types/flow.js";
+import { evaluateIfPredicates } from "../utils/condition.js";
 
 /**
  * The directive-like object that `prepare` may return on auto-steps.

package/src/core/BranchEvaluator.ts

@@ -12,11 +12,11 @@ import type {
     BranchMap,
     BranchPredicateContext,
     Directive,
-} from "../types/flow";
-import type { AiProvider } from "../types/ai";
-import type { Event } from "../types/history";
-import { eventsToHistory, logger } from "../utils";
-import { splitWhenConditions, evaluateIfPredicates, type WhenConditionGroups } from "../utils/condition";
+} from "../types/flow.js";
+import type { AiProvider } from "../types/ai.js";
+import type { Event } from "../types/history.js";
+import { eventsToHistory, logger } from "../utils/index.js";
+import { splitWhenConditions, evaluateIfPredicates, type WhenConditionGroups } from "../utils/condition.js";
 
 /**
  * The AI condition evaluator function signature.

package/src/core/CompactionEngine.ts

@@ -9,8 +9,8 @@
  */
 
 import log from "loglevel";
-import type { HistoryItem } from "../types/history";
-import type { CompactionOptions, CompactionResult } from "../types/compaction";
+import type { HistoryItem } from "../types/history.js";
+import type { CompactionOptions, CompactionResult } from "../types/compaction.js";
 
 export class CompactionEngine {
     /**

package/src/core/DirectiveChainTracker.ts

@@ -12,9 +12,9 @@
  * Validates: Requirements 22.1, 22.2, 22.3
  */
 
-import { FlowConfigurationError } from "./Step";
-import { logger } from "../utils";
-import type { Directive } from "../types/flow";
+import { FlowConfigurationError } from "./Step.js";
+import { logger } from "../utils/index.js";
+import type { Directive } from "../types/flow.js";
 
 /**
  * Entry in the directive chain log — records what was emitted and by whom.

package/src/core/Events.ts

@@ -11,8 +11,8 @@ import type {
   MessageData,
   HistoryItem,
   History,
-} from "../types";
-import { EventKind, MessageRole } from "../types";
+} from "../types/index.js";
+import { EventKind, MessageRole } from "../types/index.js";
 
 /**
  * Convert a simple JSON history message to an internal Event