@flowcodex/core 0.3.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flowcodex/core",
+  "version": "0.3.0",
+  "description": "FlowCodex kernel and agent runtime — Container, Pipeline, EventBus, RunController, Agent, ToolExecutor",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./kernel": {
+      "types": "./src/kernel/index.ts",
+      "development": "./src/kernel/index.ts",
+      "import": "./dist/kernel/index.js"
+    }
+  },
+  "dependencies": {
+    "@silvia-odwyer/photon": "^0.3.3",
+    "ulid": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}

package/src/agent/agent-loop.ts

@@ -0,0 +1,254 @@
+import type { CatalogParser } from '../infrastructure/catalog-parser.js';
+import type { RetryPolicy } from '../infrastructure/retry-policy.js';
+import type { TokenCounter } from '../infrastructure/token-counter.js';
+import { DefaultTokenCounter } from '../infrastructure/token-counter.js';
+import type { EventBus } from '../kernel/events.js';
+import type { ContentBlock, Message } from '../types/blocks.js';
+import { isToolUseBlock } from '../types/blocks.js';
+import type { Tool } from '../types/tool.js';
+import type { SystemPromptBuilder } from './system-prompt-builder.js';
+import type { AgentStatus, Context, RunResult } from '../types/context.js';
+import type { LLMRequest, LLMResponse, Provider } from '../types/provider.js';
+import type { FallbackEntry } from './provider-runner.js';
+import { FlowCodexError, ERROR_CODES } from '../types/errors.js';
+import { runProviderWithRetry } from './provider-runner.js';
+import type { Compactor } from '../execution/compactor.js';
+import { MODE_CONFIGS, ACTIVE_MODE, NOOP_RETRY_DELTA_TOKENS } from '../execution/compactor.js';
+
+export interface AgentLoopOptions {
+  ctx: Context;
+  provider: Provider;
+  events: EventBus;
+  retry: RetryPolicy;
+  maxIterations?: number;
+  signal: AbortSignal;
+  executeTools?: (toolUses: { id: string; name: string; input: unknown }[]) => Promise<void>;
+  fallbackModel?: string | undefined;
+  fallback?: FallbackEntry[] | undefined;
+  catalog?: CatalogParser | undefined;
+  /** DI TokenCounter — single source of truth for token estimates. Falls back
+   *  to a per-run DefaultTokenCounter when omitted (e.g. unit tests). */
+  tokenCounter?: TokenCounter | undefined;
+  /** Builds the structured system prompt (4 layers + cache_control). When
+   *  provided, the loop refreshes ctx.systemPrompt each iteration. */
+  systemPromptBuilder?: SystemPromptBuilder | undefined;
+  tokenSavingMode?: boolean | undefined;
+  /** HybridCompactor for inline compaction at the soft/hard thresholds. When
+   *  provided, the loop compacts ctx.state.messages before each request. */
+  compactor?: Compactor | undefined;
+}
+
+export async function runAgentLoop(opts: AgentLoopOptions): Promise<RunResult> {
+  const { ctx, provider, events, retry, signal } = opts;
+  const tokenCounter = opts.tokenCounter ?? new DefaultTokenCounter();
+  const maxIterations = opts.maxIterations ?? ctx.budget.maxIterations;
+  let iterations = 0;
+  let finalText = '';
+
+  for (let i = 0; ; i++) {
+    iterations = i + 1;
+
+    if (signal.aborted) {
+      return { status: 'aborted', iterations, finalText, abortReason: 'aborted' };
+    }
+
+    if (i >= maxIterations) {
+      events.emit('iteration.limit_reached', {
+        currentIterations: i,
+        currentLimit: maxIterations,
+        grant: () => {},
+        deny: () => {},
+      });
+      return { status: 'limit_reached' as AgentStatus, iterations, finalText };
+    }
+
+    events.emit('iteration.started', { index: i });
+
+    if (ctx.btwNotes.length > 0) {
+      const notes = ctx.btwNotes.splice(0, ctx.btwNotes.length);
+      const block: ContentBlock = {
+        type: 'text',
+        text: `[BY THE WAY — the user added this while you were working. Fold it into your current task; do not restart.]\n${notes.join('\n')}`,
+      };
+      const last = ctx.messages[ctx.messages.length - 1];
+      if (last && last.role === 'user') {
+        const content: ContentBlock[] =
+          typeof last.content === 'string'
+            ? [{ type: 'text', text: last.content }, block]
+            : [...last.content, block];
+        ctx.messages[ctx.messages.length - 1] = { ...last, content };
+      } else {
+        ctx.messages.push({ role: 'user', content: [block] });
+      }
+    }
+
+    const structuredOutput = ctx.structuredOutput;
+    const toolsForRequest = structuredOutput
+      ? [{
+          name: structuredOutput.name,
+          description: structuredOutput.description ?? 'Return the structured output as JSON.',
+          inputSchema: structuredOutput.schema,
+        }]
+      : ctx.readOnly
+        ? (ctx.tools as Array<{ mutating?: boolean }>).filter((t) => !t.mutating)
+        : ctx.tools;
+
+    if (opts.systemPromptBuilder) {
+      ctx.systemPrompt = await opts.systemPromptBuilder.build({
+        tools: toolsForRequest as readonly Tool[],
+        model: ctx.model,
+        projectRoot: ctx.projectRoot,
+        cwd: ctx.workingDir,
+        tokenSavingMode: opts.tokenSavingMode ?? false,
+      });
+    }
+
+    const requestMaxTokens = ctx.maxTokens ?? 8192;
+    ctx.lastRequestTokens = tokenCounter.estimateRequestTokens(
+      ctx.systemPrompt,
+      ctx.messages,
+      toolsForRequest,
+      ctx.model.model,
+    );
+    tokenCounter.setRequestTokens(ctx.lastRequestTokens);
+
+    if (opts.compactor) {
+      const config = MODE_CONFIGS[ACTIVE_MODE];
+      const usable = resolveUsable(opts.catalog, ctx.model.provider, ctx.model.model, requestMaxTokens);
+      const load = usable > 0 ? ctx.lastRequestTokens / usable : 0;
+
+      events.emit('ctx.pct', { load, tokens: ctx.lastRequestTokens, maxContext: usable });
+
+      if (load >= config.soft) {
+        const aggressive = load >= config.hard;
+        const result = await opts.compactor.compact({
+          messages: ctx.state.messages,
+          mode: ACTIVE_MODE,
+          aggressive,
+        });
+        if (result.after < result.before - NOOP_RETRY_DELTA_TOKENS) {
+          ctx.state.replaceMessages(result.messages);
+          ctx.lastRequestTokens = result.after;
+          events.emit('compaction.fired', { before: result.before, after: result.after, level: result.level, aggressive });
+        } else {
+          events.emit('compaction.failed', { reason: 'noop below delta', attemptedLevel: result.level });
+        }
+        if (load >= config.hard) {
+          const newLoad = usable > 0 ? ctx.lastRequestTokens / usable : 0;
+          if (newLoad >= config.hard) {
+            throw new FlowCodexError({
+              message: 'compaction could not reduce context below hard threshold',
+              code: ERROR_CODES.COMPACTION_FAILED,
+              subsystem: 'agent',
+            });
+          }
+        }
+      }
+    }
+
+    const request: LLMRequest = {
+      model: ctx.model.model,
+      system: ctx.systemPrompt,
+      messages: ctx.messages,
+      tools: toolsForRequest,
+      max_tokens: requestMaxTokens,
+      ...(structuredOutput && { tool_choice: { type: 'tool', name: structuredOutput.name } }),
+    };
+
+    let response: LLMResponse;
+    try {
+      response = await runProviderWithRetry({
+        provider,
+        request,
+        signal,
+        events,
+        retry,
+        fallbackModel: opts.fallbackModel,
+        fallback: opts.fallback,
+        catalog: opts.catalog,
+      });
+    } catch (err) {
+      if (signal.aborted) {
+        return { status: 'aborted', iterations, finalText, abortReason: 'aborted' };
+      }
+      return { status: 'failed', iterations, finalText, error: err };
+    }
+
+    if (response.usage) {
+      tokenCounter.account(response.usage, ctx.model.model);
+      const cost = tokenCounter.estimateCost(ctx.model.model, response.usage);
+      events.emit('token.accounted', { usage: response.usage, cost: { input: cost, output: cost, total: cost } });
+    }
+
+    const assistantMessage: Message = { role: 'assistant', content: response.content };
+    ctx.messages.push(assistantMessage);
+
+    const toolUses = response.content.filter(isToolUseBlock);
+    const textBlocks = response.content.filter((b) => b.type === 'text');
+    const firstText = textBlocks[0];
+    if (firstText && 'text' in firstText) {
+      finalText = firstText.text;
+    }
+
+    if (structuredOutput) {
+      const structuredCall = toolUses.find((t) => t.name === structuredOutput.name);
+      if (structuredCall) {
+        events.emit('provider.structured_output', { name: structuredOutput.name, valid: true });
+        return { status: 'structured', iterations, finalText, structuredResult: structuredCall.input };
+      }
+      events.emit('provider.structured_output', { name: structuredOutput.name, valid: false });
+      return {
+        status: 'failed',
+        iterations,
+        finalText,
+        error: new FlowCodexError({
+          message: 'model did not call the forced structured tool',
+          code: ERROR_CODES.AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED,
+          subsystem: 'agent',
+        }),
+      };
+    }
+
+    if (toolUses.length === 0 || response.stopReason !== 'tool_use') {
+      events.emit('iteration.completed', { index: i });
+      return { status: 'completed', iterations, finalText };
+    }
+
+    if (opts.executeTools) {
+      try {
+        await opts.executeTools(toolUses);
+      } catch (toolErr) {
+        if (signal.aborted) {
+          return { status: 'aborted', iterations, finalText, abortReason: 'aborted' };
+        }
+        return { status: 'failed', iterations, finalText, error: toolErr };
+      }
+    }
+
+    if (signal.aborted) {
+      return { status: 'aborted', iterations, finalText, abortReason: 'aborted' };
+    }
+
+    events.emit('iteration.completed', { index: i });
+  }
+}
+
+function resolveUsable(
+  catalog: CatalogParser | undefined,
+  provider: string,
+  model: string,
+  requestMaxTokens: number,
+): number {
+  let context = 200_000;
+  try {
+    const models = catalog?.getModels(provider);
+    const match = models?.find(
+      (m) => m.id === model,
+    );
+    if (match?.limit?.context) context = match.limit.context;
+  } catch {
+    // catalog unavailable → fallback
+  }
+  const reserved = Math.max(20_000, requestMaxTokens);
+  return context - reserved;
+}

package/src/agent/context.ts

@@ -0,0 +1,99 @@
+import * as path from 'node:path';
+import type { ContentBlock, Message, ModelRef } from '../types/blocks.js';
+import type { Budget } from '../types/context.js';
+import type { Context as IContext } from '../types/context.js';
+import type { StructuredOutputConfig } from '../types/provider.js';
+import { DefaultConversationState } from './conversation-state.js';
+import type { ConversationState } from './conversation-state.js';
+
+export interface ContextInit {
+  model: ModelRef;
+  projectRoot: string;
+  cwd?: string;
+  systemPrompt?: ContentBlock[];
+  budget?: Budget;
+  signal?: AbortSignal;
+  readOnly?: boolean;
+  structuredOutput?: StructuredOutputConfig | undefined;
+  maxTokens?: number | undefined;
+  batchToolUse?: boolean | undefined;
+}
+
+export class AgentContext implements IContext {
+  private readonly _state = new DefaultConversationState();
+  get messages(): Message[] {
+    return this._state.messages;
+  }
+  get state(): ConversationState {
+    return this._state;
+  }
+  model: ModelRef;
+  projectRoot: string;
+  workingDir: string;
+  tools: unknown[] = [];
+  readFiles = new Map<string, number>();
+  btwNotes: string[] = [];
+  lastRequestTokens = 0;
+  budget: Budget;
+  signal: AbortSignal;
+  systemPrompt: ContentBlock[];
+  readOnly: boolean;
+  structuredOutput: StructuredOutputConfig | undefined;
+  maxTokens: number | undefined;
+  batchToolUse: boolean | undefined;
+
+  private abortHooks = new Set<() => void | Promise<void>>();
+
+  constructor(init: ContextInit) {
+    this.model = init.model;
+    this.projectRoot = init.projectRoot;
+    this.workingDir = init.cwd ?? init.projectRoot;
+    this.budget = init.budget ?? { maxIterations: 50, maxTokens: 1_000_000, maxCost: 10 };
+    this.signal = init.signal ?? new AbortController().signal;
+    this.systemPrompt = init.systemPrompt ?? [];
+    this.readOnly = init.readOnly ?? false;
+    this.structuredOutput = init.structuredOutput;
+    this.maxTokens = init.maxTokens;
+    this.batchToolUse = init.batchToolUse;
+  }
+
+  registerAbortHook(fn: () => void | Promise<void>): () => void {
+    this.abortHooks.add(fn);
+    return () => this.abortHooks.delete(fn);
+  }
+
+  async drainAbortHooks(): Promise<void> {
+    const snapshot = [...this.abortHooks].reverse();
+    this.abortHooks.clear();
+    for (const fn of snapshot) {
+      try {
+        await fn();
+      } catch {
+        // best-effort
+      }
+    }
+  }
+
+  setWorkingDir(dir: string): void {
+    const resolved = path.isAbsolute(dir)
+      ? path.resolve(dir)
+      : path.resolve(this.projectRoot, dir);
+    const rel = path.relative(this.projectRoot, resolved);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`Working directory "${resolved}" is outside project root "${this.projectRoot}"`);
+    }
+    this.workingDir = resolved;
+  }
+
+  recordRead(absPath: string, mtimeMs: number): void {
+    this.readFiles.set(absPath, mtimeMs);
+  }
+
+  clearFileTracking(): void {
+    this.readFiles.clear();
+  }
+
+  hasRead(absPath: string): boolean {
+    return this.readFiles.has(absPath);
+  }
+}

package/src/agent/conversation-state.ts

@@ -0,0 +1,44 @@
+import type { Message } from '../types/blocks.js';
+
+export interface ConversationState {
+  readonly messages: readonly Message[];
+  appendMessage(m: Message): void;
+  replaceMessages(ms: readonly Message[]): void;
+  onChange(cb: () => void): () => void;
+}
+
+export class DefaultConversationState implements ConversationState {
+  private _messages: Message[] = [];
+  private readonly listeners = new Set<() => void>();
+
+  get messages(): Message[] {
+    return this._messages;
+  }
+
+  appendMessage(m: Message): void {
+    this._messages.push(m);
+    this._notify();
+  }
+
+  replaceMessages(ms: readonly Message[]): void {
+    this._messages = [...ms];
+    this._notify();
+  }
+
+  onChange(cb: () => void): () => void {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  private _notify(): void {
+    for (const cb of this.listeners) {
+      try {
+        cb();
+      } catch {
+        // swallow — mirrors EventBus listener semantics (one bad listener can't block siblings)
+      }
+    }
+  }
+}

package/src/agent/provider-runner.ts

@@ -0,0 +1,241 @@
+import type { CatalogParser } from '../infrastructure/catalog-parser.js';
+import type { RetryPolicy } from '../infrastructure/retry-policy.js';
+import type { EventBus } from '../kernel/events.js';
+import { toFlowCodexError } from '../types/errors.js';
+import type { LLMRequest, LLMResponse, Provider } from '../types/provider.js';
+import { toErrorMessage } from '../utils/error.js';
+
+export interface FallbackEntry {
+  providerId: string;
+  model: string;
+  providerFactory: () => Provider | undefined;
+}
+
+export interface RunProviderOptions {
+  provider: Provider;
+  request: LLMRequest;
+  signal: AbortSignal;
+  events: EventBus;
+  retry: RetryPolicy;
+  fallbackModel?: string | undefined;
+  fallback?: FallbackEntry[] | undefined;
+  catalog?: CatalogParser | undefined;
+}
+
+export async function runProviderWithRetry(opts: RunProviderOptions): Promise<LLMResponse> {
+  const { signal, events, retry } = opts;
+  let request = opts.request;
+  let activeProvider = opts.provider;
+  let attempt = 0;
+  let fallbackTried = false;
+  const triedModels = new Set<string>([`${activeProvider.name}/${request.model}`]);
+
+  for (;;) {
+    try {
+      const response = await aggregateStream(activeProvider, request, signal, events);
+      return response;
+    } catch (err) {
+      if (signal.aborted) throw err;
+
+      const providerErr = err as { status?: number; message: string; retryable?: boolean; retryAfterMs?: number };
+      const status = providerErr.status ?? 0;
+      const message = toErrorMessage(err);
+      const retryable = providerErr.retryable ?? false;
+
+      const shouldRetry = retry.shouldRetry({ status, message, retryable }, attempt);
+      if (!shouldRetry) {
+        if ((status === 429 || status === 529) && !fallbackTried) {
+          const fb = resolveFallbackModel(opts, activeProvider.name, request.model);
+          if (fb && !triedModels.has(`${activeProvider.name}/${fb}`)) {
+            triedModels.add(`${activeProvider.name}/${fb}`);
+            events.emit('provider.fallback', {
+              providerId: activeProvider.name,
+              from: `${activeProvider.name}/${request.model}`,
+              to: `${activeProvider.name}/${fb}`,
+              reason: 'rate_limit_exhausted',
+              status,
+            });
+            request = { ...request, model: fb };
+            attempt = 0;
+            fallbackTried = true;
+            continue;
+          }
+
+          if (opts.fallback && opts.fallback.length > 0) {
+            let hopped = false;
+            for (const entry of opts.fallback) {
+              const key = `${entry.providerId}/${entry.model}`;
+              if (triedModels.has(key)) continue;
+              triedModels.add(key);
+              const nextProvider = entry.providerFactory();
+              if (!nextProvider) {
+                events.emit('provider.fallback_skipped', {
+                  providerId: entry.providerId,
+                  reason: 'no_api_key',
+                });
+                continue;
+              }
+              events.emit('provider.fallback', {
+                providerId: entry.providerId,
+                from: `${activeProvider.name}/${request.model}`,
+                to: key,
+                reason: 'rate_limit_exhausted',
+                status,
+              });
+              activeProvider = nextProvider;
+              request = { ...request, model: entry.model };
+              attempt = 0;
+              fallbackTried = true;
+              hopped = true;
+              break;
+            }
+            if (hopped) continue;
+          }
+        }
+
+        events.emit('provider.error', {
+          providerId: activeProvider.name,
+          status,
+          description: message,
+          retryable: false,
+        });
+        throw toFlowCodexError(err);
+      }
+
+      const delay = providerErr.retryAfterMs ?? retry.delayMs(attempt, { status, message, retryable });
+      const attemptNum = attempt + 1;
+
+      events.emit('provider.retry', {
+        providerId: activeProvider.name,
+        attempt: attemptNum,
+        delayMs: delay,
+        status,
+        description: message,
+      });
+
+      await sleep(delay, signal);
+      attempt++;
+    }
+  }
+}
+
+function resolveFallbackModel(
+  opts: RunProviderOptions,
+  providerName: string,
+  currentModel: string,
+): string | undefined {
+  if (opts.fallbackModel) return opts.fallbackModel;
+  if (opts.catalog) {
+    const entry = opts.catalog.getCheapestModel(providerName, currentModel);
+    return entry?.id;
+  }
+  return undefined;
+}
+
+async function aggregateStream(
+  provider: Provider,
+  request: LLMRequest,
+  signal: AbortSignal,
+  events: EventBus,
+): Promise<LLMResponse> {
+  const textBuffers: string[] = [];
+  const thinkingBlocks: { text: string; signature?: string | undefined }[] = [];
+  const tools: Map<string, { name: string; input: string }> = new Map();
+  const blockOrder: string[] = [];
+  let usage: {
+    input: number;
+    output: number;
+    cache_read?: number | undefined;
+    cache_creation?: number | undefined;
+  } = { input: 0, output: 0 };
+  let stopReason = 'end_turn';
+
+  for await (const ev of provider.stream(request)) {
+    if (signal.aborted) throw new Error('aborted');
+
+    switch (ev.type) {
+      case 'text_delta':
+        textBuffers.push(ev.text);
+        events.emit('provider.text_delta', { text: ev.text });
+        break;
+      case 'thinking_delta':
+        thinkingBlocks.push({ text: ev.text });
+        events.emit('provider.thinking_delta', { text: ev.text });
+        break;
+      case 'tool_use_start':
+        tools.set(ev.id, { name: ev.name, input: '' });
+        blockOrder.push(`tool:${ev.id}`);
+        events.emit('provider.tool_use_start', { id: ev.id, name: ev.name });
+        break;
+      case 'tool_use_input_delta': {
+        const tool = tools.get(ev.id);
+        if (tool) {
+          tool.input += ev.partialJson;
+        }
+        events.emit('provider.tool_use_input_delta', { id: ev.id, partialJson: ev.partialJson });
+        break;
+      }
+      case 'tool_use_stop':
+        events.emit('provider.tool_use_stop', { id: ev.id, name: tools.get(ev.id)?.name ?? '' });
+        break;
+      case 'finish':
+        usage = ev.usage;
+        stopReason = ev.stopReason;
+        break;
+      case 'error':
+        events.emit('provider.stream_error', { eventType: 'error', msg: ev.error.message });
+        const streamErr = new Error(ev.error.message) as Error & {
+          status: number;
+          retryable: boolean;
+          retryAfterMs?: number | undefined;
+        };
+        streamErr.status = ev.error.status;
+        streamErr.retryable = ev.error.retryable;
+        streamErr.retryAfterMs = ev.error.retryAfterMs;
+        throw streamErr;
+    }
+  }
+
+  const content: import('../types/blocks.js').ContentBlock[] = [];
+
+  for (const t of thinkingBlocks) {
+    content.push({ type: 'thinking', text: t.text, signature: t.signature });
+  }
+
+  const text = textBuffers.join('');
+  if (text) {
+    content.push({ type: 'text', text });
+  }
+
+  for (const [id, tool] of tools) {
+    let input: unknown;
+    try {
+      input = JSON.parse(tool.input);
+    } catch {
+      input = { __raw: tool.input };
+    }
+    content.push({ type: 'tool_use', id, name: tool.name, input });
+  }
+
+  events.emit('provider.response', { usage, stopReason });
+
+  return { content, usage, stopReason };
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new Error('aborted'));
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}