@flowcodex/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowCodex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @flowcodex/core
+
+The FlowCodex core — kernel primitives (Container, Pipeline, EventBus, RunController) and the agent system (Agent, Context, ToolExecutor).
+
+## Usage
+
+```typescript
+import { Container, Pipeline, EventBus, RunController } from '@flowcodex/core';
+```

package/dist/index-LbxYtxxS.d.ts

@@ -0,0 +1,560 @@
+type Token<T> = symbol & {
+    readonly __type?: T;
+};
+type Factory<T> = (c: Container) => T;
+type Decorator<T> = (inner: T, c: Container) => T;
+interface BindOptions {
+    singleton?: boolean | undefined;
+    owner?: string | undefined;
+}
+declare class Container {
+    private readonly entries;
+    private readonly resolving;
+    bind<T>(token: Token<T>, factory: Factory<T>, opts?: BindOptions): void;
+    override<T>(token: Token<T>, factory: Factory<T>, opts?: BindOptions): void;
+    decorate<T>(token: Token<T>, decorator: Decorator<T>, owner?: string): void;
+    resolve<T>(token: Token<T>): T;
+    private describeCycle;
+    has<T>(token: Token<T>): boolean;
+    safeResolve<T>(token: Token<T>): T | undefined;
+    ownerOf<T>(token: Token<T>): string | undefined;
+    unbind<T>(token: Token<T>): boolean;
+    clear(): void;
+    list(): Array<{
+        token: symbol;
+        owner: string;
+    }>;
+    inspect<T>(token: Token<T>): {
+        owner: string;
+        singleton: boolean;
+        decoratorCount: number;
+        cached: boolean;
+    } | null;
+}
+declare function token<T>(description: string): Token<T>;
+
+type NextFn<T> = (value: T) => Promise<T>;
+type MiddlewareHandler<T> = (value: T, next: NextFn<T>) => Promise<T>;
+type PipelineErrorPolicy = 'rethrow' | 'swallow';
+interface PipelineErrorEvent {
+    middleware: string;
+    owner?: string | undefined;
+    err: unknown;
+}
+type PipelineErrorHandler = (ev: PipelineErrorEvent) => PipelineErrorPolicy | Promise<PipelineErrorPolicy>;
+interface Middleware<T> {
+    name: string;
+    handler: MiddlewareHandler<T>;
+    owner?: string | undefined;
+}
+interface PipelineOptions {
+    optional?: boolean | undefined;
+}
+interface ReadonlyPipeline<T> {
+    readonly size: number;
+    list(): readonly string[];
+    run(input: T): Promise<T>;
+}
+declare class Pipeline<T> {
+    private readonly chain;
+    private errorHandler?;
+    setErrorHandler(handler: PipelineErrorHandler | undefined): this;
+    use(mw: Middleware<T> | Middleware<unknown>): this;
+    prepend(mw: Middleware<T>): this;
+    insertAt(index: number, mw: Middleware<T>): this;
+    insertBefore(target: string, mw: Middleware<T>, opts?: PipelineOptions): this;
+    insertAfter(target: string, mw: Middleware<T>, opts?: PipelineOptions): this;
+    replace(target: string, mw: Middleware<T>, opts?: PipelineOptions): this;
+    remove(name: string, opts?: PipelineOptions): this;
+    list(): readonly string[];
+    size(): number;
+    asReadonly(): ReadonlyPipeline<T>;
+    run(input: T): Promise<T>;
+    private indexOf;
+    private ensureUnique;
+}
+
+interface RunControllerOptions {
+    parentSignal?: AbortSignal | undefined;
+    errorSink?: (err: unknown, where: string) => void;
+}
+declare class RunController {
+    private readonly ctrl;
+    private readonly hooks;
+    private disposed;
+    private hooksDrained;
+    private readonly errorSink;
+    constructor(opts?: RunControllerOptions);
+    get signal(): AbortSignal;
+    get aborted(): boolean;
+    abort(reason?: unknown): void;
+    onAbort(fn: () => void | Promise<void>): () => void;
+    dispose(): Promise<void>;
+    private runHooks;
+}
+
+declare const TOKENS: {
+    readonly Logger: Token<unknown>;
+    readonly TokenCounter: Token<unknown>;
+    readonly SessionStore: Token<unknown>;
+    readonly ConfigStore: Token<unknown>;
+    readonly ConfigLoader: Token<unknown>;
+    readonly PermissionPolicy: Token<unknown>;
+    readonly Compactor: Token<unknown>;
+    readonly PathResolver: Token<unknown>;
+    readonly Renderer: Token<unknown>;
+    readonly InputReader: Token<unknown>;
+    readonly ErrorHandler: Token<unknown>;
+    readonly RetryPolicy: Token<unknown>;
+    readonly SystemPromptBuilder: Token<unknown>;
+    readonly SecretScrubber: Token<unknown>;
+    readonly ProviderRunner: Token<unknown>;
+};
+
+type ImageSource = {
+    type: 'base64';
+    media_type: string;
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+};
+interface CacheControl {
+    type: 'ephemeral';
+    ttl?: '5m' | '1h' | undefined;
+}
+interface TextBlock {
+    type: 'text';
+    text: string;
+    cache_control?: CacheControl | undefined;
+}
+type ContentBlock = TextBlock | {
+    type: 'thinking';
+    text: string;
+    signature?: string | undefined;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | ContentBlock[];
+    is_error?: boolean | undefined;
+} | {
+    type: 'image';
+    source: ImageSource;
+} | {
+    type: 'pdf';
+    source: {
+        type: 'base64';
+        media_type: 'application/pdf';
+        data: string;
+    };
+};
+type Role = 'system' | 'user' | 'assistant';
+interface Message {
+    role: Role;
+    content: ContentBlock[] | string;
+}
+type ModelId = string;
+type ModelRef = {
+    provider: string;
+    model: ModelId;
+};
+
+interface Usage {
+    input: number;
+    output: number;
+    cache_read?: number | undefined;
+    cache_creation?: number | undefined;
+}
+interface ModelPricing {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+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;
+}
+declare class DefaultTokenCounter implements TokenCounter {
+    private cumulativeInput;
+    private cumulativeOutput;
+    private requestTokens;
+    private readonly pricing;
+    private readonly calibration;
+    setPricing(model: string, pricing: ModelPricing): void;
+    estimate(text: string, model?: string): number;
+    estimateRequestTokens(system: readonly ContentBlock[], messages: readonly Message[], tools?: readonly unknown[], model?: string): number;
+    account(usage: Usage, model?: string): void;
+    currentRequestTokens(): number;
+    setRequestTokens(n: number): void;
+    total(): number;
+    estimateCost(model: string, usage: Usage): number;
+    private getRatio;
+    calibrate(model: string, initialRatio?: number): void;
+}
+
+type SessionEvent = {
+    type: 'session_start';
+    ts: string;
+    id: string;
+    model: string;
+    cwd: string;
+} | {
+    type: 'session_resumed';
+    ts: string;
+    id: string;
+    model: string;
+} | {
+    type: 'user_input';
+    ts: string;
+    content: string | ContentBlock[];
+} | {
+    type: 'llm_request';
+    ts: string;
+    model: string;
+    messageCount: number;
+    estimatedInputTokens?: number | undefined;
+    toolCount?: number | undefined;
+} | {
+    type: 'llm_response';
+    ts: string;
+    content: ContentBlock[];
+    stopReason: string;
+    usage: Usage;
+} | {
+    type: 'tool_use';
+    ts: string;
+    name: string;
+    id: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    ts: string;
+    id: string;
+    content: unknown;
+    isError: boolean;
+} | {
+    type: 'compaction';
+    ts: string;
+    before: number;
+    after: number;
+    level: string;
+    aggressive: boolean;
+} | {
+    type: 'ctx_pct';
+    ts: string;
+    pct: number;
+} | {
+    type: 'in_flight_start';
+    ts: string;
+    kind: 'tool_batch' | 'llm_call';
+} | {
+    type: 'in_flight_end';
+    ts: string;
+    kind: 'tool_batch' | 'llm_call';
+} | {
+    type: 'checkpoint';
+    ts: string;
+    label?: string | undefined;
+} | {
+    type: 'error';
+    ts: string;
+    error: unknown;
+} | {
+    type: 'session_end';
+    ts: string;
+    reason: 'normal' | 'aborted' | 'error' | 'crashed';
+};
+interface AuditEntry {
+    index: number;
+    id: string;
+    ts: string;
+    prevHash: string;
+    hash: string;
+    toolName: string;
+    toolUseId: string;
+    input: unknown;
+    output: unknown;
+    isError: boolean;
+}
+type VerifyResult = {
+    ok: true;
+    entries: number;
+} | {
+    ok: false;
+    brokenAt: number;
+    reason: string;
+};
+interface SessionSummary {
+    id: string;
+    title: string;
+    model: string;
+    provider: string;
+    startedAt: string;
+    endedAt: string;
+    messageCount: number;
+    iterationCount: number;
+    toolCallCount: number;
+    toolErrorCount: number;
+    totalTokens: number;
+    totalCost: number;
+    outcome: 'completed' | 'error' | 'aborted';
+}
+interface SessionStore {
+    append(event: SessionEvent): Promise<void>;
+    readAll(): Promise<SessionEvent[]>;
+    close(reason?: 'normal' | 'aborted' | 'error' | 'crashed'): Promise<void>;
+    writeSummary(summary: SessionSummary): Promise<void>;
+    readonly sessionId: string;
+    readonly filePath: string;
+}
+interface SecretVault {
+    isEncrypted(value: string): boolean;
+    encrypt(plaintext: string): string;
+    decrypt(value: string): string;
+}
+interface AuditLog {
+    record(input: {
+        sessionId: string;
+        toolName: string;
+        toolUseId: string;
+        input: unknown;
+        output: unknown;
+        isError: boolean;
+    }): Promise<AuditEntry>;
+    verify(sessionId: string): Promise<VerifyResult>;
+    load(sessionId: string): Promise<AuditEntry[]>;
+    flush(sessionId: string): Promise<void>;
+}
+
+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;
+    };
+}
+type EventName = keyof EventMap;
+type Listener<E extends EventName> = (payload: EventMap[E]) => void;
+interface EventLogger {
+    error(msg: string, ctx?: unknown): void | undefined;
+}
+declare class EventBus {
+    private readonly listeners;
+    private readonly wildcards;
+    private logger?;
+    setLogger(logger: EventLogger): void;
+    on<E extends EventName>(event: E, fn: Listener<E>): () => void;
+    off<E extends EventName>(event: E, fn: Listener<E>): void;
+    once<E extends EventName>(event: E, fn: Listener<E>): () => void;
+    onAny(fn: (event: string, payload: unknown) => void): () => void;
+    onPattern(pattern: string, fn: (event: string, payload: unknown) => void): () => void;
+    onRegex(regex: RegExp, fn: (event: string, payload: unknown) => void): () => void;
+    emit<E extends EventName>(event: E, payload: EventMap[E]): void;
+    emitCustom(event: string, payload: unknown): void;
+    clear(): void;
+    listenerCount(event?: EventName): number;
+    wildcardCount(): number;
+    hasListenerFor(event: string): boolean;
+}
+declare class ScopedEventBus extends EventBus {
+    private readonly registrations;
+    private nextKey;
+    on<E extends EventName>(event: E, fn: Listener<E>): () => void;
+    once<E extends EventName>(event: E, fn: Listener<E>): () => void;
+    onAny(fn: (event: string, payload: unknown) => void): () => void;
+    onPattern(pattern: string, fn: (event: string, payload: unknown) => void): () => void;
+    onRegex(regex: RegExp, fn: (event: string, payload: unknown) => void): () => void;
+    teardown(): void;
+    [Symbol.dispose](): void;
+    get scopedListenerCount(): number;
+}
+
+export { type AuditLog as A, type BindOptions as B, type ContentBlock as C, type Decorator as D, EventBus as E, type Factory as F, token as G, type Listener as L, type Message as M, type NextFn as N, Pipeline as P, type ReadonlyPipeline as R, type SecretVault as S, type TokenCounter as T, type Usage as U, type VerifyResult as V, type ModelRef as a, type SessionStore as b, type SessionEvent as c, type SessionSummary as d, type AuditEntry as e, type CacheControl as f, Container as g, DefaultTokenCounter as h, type EventLogger as i, type EventMap as j, type EventName as k, type Middleware as l, type MiddlewareHandler as m, type ModelId as n, type ModelPricing as o, type PipelineErrorEvent as p, type PipelineErrorHandler as q, type PipelineErrorPolicy as r, type PipelineOptions as s, type Role as t, RunController as u, type RunControllerOptions as v, ScopedEventBus as w, TOKENS as x, type TextBlock as y, type Token as z };