@flowcodex/core 0.3.0

package/src/infrastructure/token-counter.ts

@@ -0,0 +1,156 @@
+import type { ContentBlock, Message } from '../types/blocks.js';
+
+export interface Usage {
+  input: number;
+  output: number;
+  cache_read?: number | undefined;
+  cache_creation?: number | undefined;
+}
+
+export interface ModelPricing {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+export interface TokenCounter {
+  estimate(text: string, model?: string): number;
+  /** Pre-flight estimate of a full request: system + messages + tool schemas.
+   *  Single source of truth for ctx.lastRequestTokens, ctx.pct, and compaction thresholds. */
+  estimateRequestTokens(
+    system: readonly ContentBlock[],
+    messages: readonly Message[],
+    tools?: readonly unknown[],
+    model?: string,
+  ): number;
+  account(usage: Usage, model?: string): void;
+  currentRequestTokens(): number;
+  total(): number;
+  estimateCost(model: string, usage: Usage): number;
+  setRequestTokens(n: number): void;
+}
+
+const ANTHROPIC_RATIO = 3.5;
+const DEFAULT_RATIO = 4.0;
+const CALIBRATION_ALPHA = 0.3;
+const CALIBRATION_MIN_SAMPLES = 3;
+
+interface CalibrationBucket {
+  ratio: number;
+  samples: number;
+}
+
+export class DefaultTokenCounter implements TokenCounter {
+  private cumulativeInput = 0;
+  private cumulativeOutput = 0;
+  private requestTokens = 0;
+  private readonly pricing: Map<string, ModelPricing> = new Map();
+  private readonly calibration = new Map<string, CalibrationBucket>();
+
+  setPricing(model: string, pricing: ModelPricing): void {
+    this.pricing.set(model, pricing);
+  }
+
+  estimate(text: string, model?: string): number {
+    const ratio = this.getRatio(model);
+    return Math.max(1, Math.ceil(text.length / ratio));
+  }
+
+  estimateRequestTokens(
+    system: readonly ContentBlock[],
+    messages: readonly Message[],
+    tools?: readonly unknown[],
+    model?: string,
+  ): number {
+    let chars = 0;
+    for (const block of system) {
+      if ('text' in block) chars += block.text.length;
+    }
+    for (const msg of messages) {
+      if (typeof msg.content === 'string') {
+        chars += msg.content.length;
+      } else {
+        for (const block of msg.content) {
+          if ('text' in block) chars += block.text.length;
+          if (block.type === 'tool_result' && typeof block.content === 'string') {
+            chars += block.content.length;
+          }
+          if (block.type === 'tool_use') {
+            chars += JSON.stringify(block.input).length;
+          }
+        }
+      }
+    }
+    if (tools) {
+      for (const t of tools) {
+        const tool = t as { inputSchema?: unknown; name?: string; description?: string };
+        if (tool.inputSchema) chars += JSON.stringify(tool.inputSchema).length;
+        if (tool.name) chars += tool.name.length;
+        if (tool.description) chars += tool.description.length;
+      }
+    }
+    const ratio = this.getRatio(model);
+    return Math.max(1, Math.ceil(chars / ratio));
+  }
+
+  account(usage: Usage, model?: string): void {
+    this.cumulativeInput += usage.input;
+    this.cumulativeOutput += usage.output;
+
+    if (model) {
+      const key = model;
+      const bucket = this.calibration.get(key);
+      if (bucket) {
+        const estimated = usage.input + usage.output;
+        const actual = estimated;
+        const newRatio = CALIBRATION_ALPHA * (actual / Math.max(1, estimated)) + (1 - CALIBRATION_ALPHA) * bucket.ratio;
+        bucket.ratio = newRatio;
+        bucket.samples++;
+      }
+    }
+  }
+
+  currentRequestTokens(): number {
+    return this.requestTokens;
+  }
+
+  setRequestTokens(n: number): void {
+    this.requestTokens = n;
+  }
+
+  total(): number {
+    return this.cumulativeInput + this.cumulativeOutput;
+  }
+
+  estimateCost(model: string, usage: Usage): number {
+    const p = this.pricing.get(model);
+    if (!p) return 0;
+    const inputCost = (usage.input / 1_000_000) * p.input;
+    const outputCost = (usage.output / 1_000_000) * p.output;
+    const cacheReadCost = ((usage.cache_read ?? 0) / 1_000_000) * p.cacheRead;
+    const cacheWriteCost = ((usage.cache_creation ?? 0) / 1_000_000) * p.cacheWrite;
+    return inputCost + outputCost + cacheReadCost + cacheWriteCost;
+  }
+
+  private getRatio(model?: string): number {
+    if (!model) return DEFAULT_RATIO;
+    const bucket = this.calibration.get(model);
+    if (bucket && bucket.samples >= CALIBRATION_MIN_SAMPLES) {
+      return bucket.ratio;
+    }
+    if (model.includes('claude') || model.includes('anthropic')) {
+      return ANTHROPIC_RATIO;
+    }
+    return DEFAULT_RATIO;
+  }
+
+  calibrate(model: string, initialRatio?: number): void {
+    if (!this.calibration.has(model)) {
+      this.calibration.set(model, {
+        ratio: initialRatio ?? (model.includes('claude') ? ANTHROPIC_RATIO : DEFAULT_RATIO),
+        samples: 0,
+      });
+    }
+  }
+}

package/src/infrastructure/tracer.ts

@@ -0,0 +1,23 @@
+export interface Span {
+  setAttribute(k: string, v: unknown): this;
+  recordError(err: unknown): void;
+  end(): void;
+}
+
+export interface Tracer {
+  startSpan(name: string, attrs?: Record<string, unknown>): Span;
+}
+
+export class NoopSpan implements Span {
+  setAttribute(_k: string, _v: unknown): this {
+    return this;
+  }
+  recordError(_err: unknown): void {}
+  end(): void {}
+}
+
+export class NoopTracer implements Tracer {
+  startSpan(_name: string, _attrs?: Record<string, unknown>): Span {
+    return new NoopSpan();
+  }
+}

package/src/kernel/container.ts

@@ -0,0 +1,166 @@
+import { FlowCodexError, ERROR_CODES } from '../types/errors.js';
+
+export type Token<T> = symbol & { readonly __type?: T };
+export type Factory<T> = (c: Container) => T;
+export type Decorator<T> = (inner: T, c: Container) => T;
+
+interface Entry<T = unknown> {
+  factory: Factory<T>;
+  singleton: boolean;
+  decorators: Decorator<T>[];
+  cache?: T | undefined;
+  owner: string;
+}
+
+export interface BindOptions {
+  singleton?: boolean | undefined;
+  owner?: string | undefined;
+}
+
+export class Container {
+  private readonly entries = new Map<symbol, Entry>();
+  private readonly resolving = new Set<symbol>();
+
+  bind<T>(token: Token<T>, factory: Factory<T>, opts: BindOptions = {}): void {
+    if (this.entries.has(token)) {
+      throw new FlowCodexError({
+        message: `Container: token "${token.description ?? 'unknown'}" already bound`,
+        code: ERROR_CODES.CONTAINER_TOKEN_ALREADY_BOUND,
+        subsystem: 'container',
+        context: { token: token.description },
+      });
+    }
+    this.entries.set(token, {
+      factory: factory as Factory<unknown>,
+      singleton: opts.singleton ?? true,
+      decorators: [],
+      owner: opts.owner ?? 'core',
+    });
+  }
+
+  override<T>(token: Token<T>, factory: Factory<T>, opts: BindOptions = {}): void {
+    const existing = this.entries.get(token);
+    if (!existing) {
+      throw new FlowCodexError({
+        message: `Container: cannot override "${token.description ?? 'unknown'}" — not bound`,
+        code: ERROR_CODES.CONTAINER_TOKEN_NOT_BOUND,
+        subsystem: 'container',
+        context: { token: token.description },
+      });
+    }
+    this.entries.set(token, {
+      factory: factory as Factory<unknown>,
+      singleton: opts.singleton ?? existing.singleton,
+      decorators: existing.decorators,
+      owner: opts.owner ?? existing.owner,
+    });
+  }
+
+  decorate<T>(token: Token<T>, decorator: Decorator<T>, owner = 'core'): void {
+    const existing = this.entries.get(token);
+    if (!existing) {
+      throw new FlowCodexError({
+        message: `Container: cannot decorate "${token.description ?? 'unknown'}" — not bound`,
+        code: ERROR_CODES.CONTAINER_TOKEN_NOT_BOUND,
+        subsystem: 'container',
+        context: { token: token.description },
+      });
+    }
+    existing.decorators.push(decorator as Decorator<unknown>);
+    existing.cache = undefined;
+    existing.owner = `${existing.owner}+${owner}`;
+  }
+
+  resolve<T>(token: Token<T>): T {
+    const entry = this.entries.get(token);
+    if (!entry) {
+      throw new FlowCodexError({
+        message: `Container: token "${token.description ?? 'unknown'}" not bound`,
+        code: ERROR_CODES.CONTAINER_TOKEN_NOT_BOUND,
+        subsystem: 'container',
+        context: { token: token.description },
+      });
+    }
+    if (entry.singleton && entry.cache !== undefined) {
+      return entry.cache as T;
+    }
+    if (this.resolving.has(token)) {
+      const cycle = this.describeCycle(token);
+      throw new FlowCodexError({
+        message: `Container: circular dependency detected — ${cycle}`,
+        code: ERROR_CODES.CONTAINER_CIRCULAR_DEPENDENCY,
+        subsystem: 'container',
+        context: { token: token.description, cycle },
+      });
+    }
+    this.resolving.add(token);
+    try {
+      let value: unknown = entry.factory(this);
+      for (const d of entry.decorators) {
+        value = d(value, this);
+      }
+      if (entry.singleton) {
+        entry.cache = value;
+      }
+      return value as T;
+    } finally {
+      this.resolving.delete(token);
+    }
+  }
+
+  private describeCycle(reentry: symbol): string {
+    const descs: string[] = [];
+    for (const t of this.resolving) {
+      descs.push(t.description ?? 'unknown');
+    }
+    descs.push(reentry.description ?? 'unknown');
+    return descs.join(' → ');
+  }
+
+  has<T>(token: Token<T>): boolean {
+    return this.entries.has(token);
+  }
+
+  safeResolve<T>(token: Token<T>): T | undefined {
+    return this.has(token) ? this.resolve(token) : undefined;
+  }
+
+  ownerOf<T>(token: Token<T>): string | undefined {
+    return this.entries.get(token)?.owner;
+  }
+
+  unbind<T>(token: Token<T>): boolean {
+    return this.entries.delete(token);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  list(): Array<{ token: symbol; owner: string }> {
+    return Array.from(this.entries.entries()).map(([token, entry]) => ({
+      token,
+      owner: entry.owner,
+    }));
+  }
+
+  inspect<T>(token: Token<T>): {
+    owner: string;
+    singleton: boolean;
+    decoratorCount: number;
+    cached: boolean;
+  } | null {
+    const entry = this.entries.get(token);
+    if (!entry) return null;
+    return {
+      owner: entry.owner,
+      singleton: entry.singleton,
+      decoratorCount: entry.decorators.length,
+      cached: entry.cache !== undefined,
+    };
+  }
+}
+
+export function token<T>(description: string): Token<T> {
+  return Symbol(description) as Token<T>;
+}

package/src/kernel/events.ts

@@ -0,0 +1,323 @@
+import type { SessionSummary } from '../session/types.js';
+
+export interface EventMap {
+  'session.started': { id: string };
+  'session.ended': { id: string; usage: unknown };
+  'session.damaged': { sessionId: string; detail: string };
+  'session.resumed': { sessionId: string; forkedFrom?: string | undefined };
+  'session.summary_written': { sessionId: string; summary: SessionSummary };
+
+  'iteration.started': { index: number };
+  'iteration.completed': { index: number };
+  'iteration.limit_reached': {
+    currentIterations: number;
+    currentLimit: number;
+    grant: (extraIterations: number) => void;
+    deny: () => void;
+  };
+
+  'provider.response': { usage: unknown; stopReason: string };
+  'provider.text_delta': { text: string };
+  'provider.thinking_delta': { text: string };
+  'provider.tool_use_start': { id: string; name: string };
+  'provider.tool_use_input_delta': { id: string; partialJson: string };
+  'provider.tool_use_stop': { id: string; name: string };
+  'provider.stream_error': { eventType: string; msg: string };
+  'provider.retry': {
+    providerId: string;
+    attempt: number;
+    delayMs: number;
+    status: number;
+    description: string;
+  };
+  'provider.error': {
+    providerId: string;
+    status: number;
+    description: string;
+    retryable: boolean;
+  };
+  'provider.fallback': {
+    providerId: string;
+    from: string;
+    to: string;
+    reason: string;
+    status: number;
+  };
+  'provider.fallback_skipped': {
+    providerId: string;
+    reason: 'no_api_key' | 'unsupported_family' | 'not_in_catalog';
+  };
+
+  'tool.started': { name: string; id: string; input?: unknown | undefined };
+  'tool.progress': { name: string; id: string; event: unknown };
+  'tool.confirm_needed': {
+    tool: unknown;
+    input: unknown;
+    toolUseId: string;
+    suggestedPattern: string;
+    resolve: (decision: 'yes' | 'no' | 'always' | 'deny') => void;
+  };
+  'tool.executed': {
+    id?: string | undefined;
+    name: string;
+    durationMs: number;
+    ok: boolean;
+    input?: unknown | undefined;
+    output?: string | undefined;
+    outputBytes?: number | undefined;
+  };
+  'tool.tier_filtered': { total: number; kept: number };
+  'tool.batch_started': { count: number; names: string[] };
+  'tool.batch_completed': { count: number; succeeded: number; failed: number; durationMs: number };
+  'provider.structured_output': { name: string; valid: boolean };
+  'provider.modality_rejected': { provider: string; model: string; modality: string };
+
+  'ctx.pct': { load: number; tokens: number; maxContext: number };
+  'ctx.max_context': { providerId: string; modelId: string; maxContext: number };
+  'token.threshold': { used: number; limit: number };
+  'token.accounted': {
+    usage: unknown;
+    cost: { input: number; output: number; total: number };
+  };
+  'token.cost_estimate_unavailable': { model: string };
+
+  'ssrf.blocked': { url: string; ip: string; reason: string };
+
+  'permission.persisted': {
+    action: 'allow' | 'deny';
+    tool: string;
+    pattern: string;
+    scope: 'session' | 'trust';
+  };
+
+  'compaction.fired': {
+    before: number;
+    after: number;
+    level: 'soft' | 'hard';
+    aggressive: boolean;
+  };
+
+  'compaction.failed': {
+    reason: string;
+    attemptedLevel: 'soft' | 'hard';
+  };
+
+  'error': { err: Error; phase: string };
+}
+
+export type EventName = keyof EventMap;
+export type Listener<E extends EventName> = (payload: EventMap[E]) => void;
+
+export interface EventLogger {
+  error(msg: string, ctx?: unknown): void | undefined;
+}
+
+export class EventBus {
+  private readonly listeners = new Map<EventName, Set<Listener<EventName>>>();
+  private readonly wildcards: Array<{
+    match: (event: string) => boolean;
+    fn: (event: string, payload: unknown) => void;
+  }> = [];
+  private logger?: EventLogger | undefined;
+
+  setLogger(logger: EventLogger): void {
+    this.logger = logger;
+  }
+
+  on<E extends EventName>(event: E, fn: Listener<E>): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn as Listener<EventName>);
+    return () => this.off(event, fn);
+  }
+
+  off<E extends EventName>(event: E, fn: Listener<E>): void {
+    this.listeners.get(event)?.delete(fn as Listener<EventName>);
+  }
+
+  once<E extends EventName>(event: E, fn: Listener<E>): () => void {
+    const wrapper: Listener<E> = (payload) => {
+      this.off(event, wrapper as Listener<EventName>);
+      (fn as Listener<E>)(payload);
+    };
+    this.on(event, wrapper as Listener<E>);
+    return () => {
+      this.off(event, wrapper as Listener<EventName>);
+    };
+  }
+
+  onAny(fn: (event: string, payload: unknown) => void): () => void {
+    return this.onPattern('*', fn);
+  }
+
+  onPattern(pattern: string, fn: (event: string, payload: unknown) => void): () => void {
+    const match = makePatternMatcher(pattern);
+    const entry = { match, fn };
+    this.wildcards.push(entry);
+    return () => {
+      const idx = this.wildcards.indexOf(entry);
+      if (idx >= 0) this.wildcards.splice(idx, 1);
+    };
+  }
+
+  onRegex(regex: RegExp, fn: (event: string, payload: unknown) => void): () => void {
+    const entry = { match: (e: string) => regex.test(e), fn };
+    this.wildcards.push(entry);
+    return () => {
+      const idx = this.wildcards.indexOf(entry);
+      if (idx >= 0) this.wildcards.splice(idx, 1);
+    };
+  }
+
+  emit<E extends EventName>(event: E, payload: EventMap[E]): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      for (const fn of set) {
+        try {
+          (fn as Listener<E>)(payload);
+        } catch (err) {
+          this.logger?.error(`EventBus listener for "${event}" threw`, err);
+        }
+      }
+    }
+    if (this.wildcards.length > 0) {
+      const name = event as string;
+      const snapshot = this.wildcards.slice();
+      for (const { match, fn } of snapshot) {
+        if (!match(name)) continue;
+        try {
+          fn(name, payload);
+        } catch (err) {
+          this.logger?.error(`EventBus wildcard listener for "${name}" threw`, err);
+        }
+      }
+    }
+  }
+
+  emitCustom(event: string, payload: unknown): void {
+    if (this.wildcards.length === 0) return;
+    const snapshot = this.wildcards.slice();
+    for (const { match, fn } of snapshot) {
+      if (!match(event)) continue;
+      try {
+        fn(event, payload);
+      } catch (err) {
+        this.logger?.error(`EventBus wildcard listener for "${event}" threw`, err);
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.clear();
+    this.wildcards.length = 0;
+  }
+
+  listenerCount(event?: EventName): number {
+    if (event !== undefined) return this.listeners.get(event)?.size ?? 0;
+    let total = 0;
+    for (const set of this.listeners.values()) total += set.size;
+    return total;
+  }
+
+  wildcardCount(): number {
+    return this.wildcards.length;
+  }
+
+  hasListenerFor(event: string): boolean {
+    if ((this.listeners.get(event as EventName)?.size ?? 0) > 0) return true;
+    return this.wildcards.some((w) => w.match(event));
+  }
+}
+
+export class ScopedEventBus extends EventBus {
+  private readonly registrations = new Map<number, () => void>();
+  private nextKey = 0;
+
+  override on<E extends EventName>(event: E, fn: Listener<E>): () => void {
+    const key = this.nextKey++;
+    const unsub = super.on(event, fn);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+
+  override once<E extends EventName>(event: E, fn: Listener<E>): () => void {
+    const key = this.nextKey++;
+    const wrapper: Listener<E> = (payload) => {
+      EventBus.prototype.off.call(this, event, wrapper as Listener<EventName>);
+      this.registrations.delete(key);
+      (fn as Listener<E>)(payload);
+    };
+    EventBus.prototype.on.call(this, event, wrapper as Listener<EventName>);
+    const unsub = () => {
+      this.registrations.delete(key);
+      EventBus.prototype.off.call(this, event, wrapper as Listener<EventName>);
+    };
+    this.registrations.set(key, unsub);
+    return unsub;
+  }
+
+  override onAny(fn: (event: string, payload: unknown) => void): () => void {
+    const key = this.nextKey++;
+    const unsub = EventBus.prototype.onPattern.call(this, '*', fn);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+
+  override onPattern(pattern: string, fn: (event: string, payload: unknown) => void): () => void {
+    const key = this.nextKey++;
+    const unsub = super.onPattern(pattern, fn);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+
+  override onRegex(regex: RegExp, fn: (event: string, payload: unknown) => void): () => void {
+    const key = this.nextKey++;
+    const unsub = super.onRegex(regex, fn);
+    this.registrations.set(key, unsub);
+    return () => {
+      this.registrations.delete(key);
+      unsub();
+    };
+  }
+
+  teardown(): void {
+    for (const unsub of this.registrations.values()) {
+      try {
+        unsub();
+      } catch {
+        // best effort
+      }
+    }
+    this.registrations.clear();
+    this.clear();
+  }
+
+  [Symbol.dispose](): void {
+    this.teardown();
+  }
+
+  get scopedListenerCount(): number {
+    return this.registrations.size;
+  }
+}
+
+function makePatternMatcher(pattern: string): (event: string) => boolean {
+  if (pattern === '*') return () => true;
+  if (pattern.endsWith('.*')) {
+    const prefix = pattern.slice(0, -2);
+    return (e: string) => e.startsWith(`${prefix}.`);
+  }
+  return (e: string) => e === pattern;
+}

package/src/kernel/index.ts

@@ -0,0 +1,18 @@
+export { Container, token } from './container.js';
+export type { Token, Factory, Decorator, BindOptions } from './container.js';
+export { Pipeline } from './pipeline.js';
+export type {
+  NextFn,
+  MiddlewareHandler,
+  Middleware,
+  ReadonlyPipeline,
+  PipelineErrorHandler,
+  PipelineErrorEvent,
+  PipelineErrorPolicy,
+  PipelineOptions,
+} from './pipeline.js';
+export { RunController } from './run-controller.js';
+export type { RunControllerOptions } from './run-controller.js';
+export { TOKENS } from './tokens.js';
+export { EventBus, ScopedEventBus } from './events.js';
+export type { EventMap, EventName, Listener, EventLogger } from './events.js';