oh-my-fable 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,380 @@
+interface Goal {
+    description: string;
+    /** "don't do X" style guardrails. */
+    constraints?: string[];
+    /** Completion criteria the reflector checks against. */
+    successCriteria?: string[];
+}
+type StepStatus = "pending" | "running" | "done" | "failed" | "skipped";
+interface Step {
+    id: string;
+    /** What this step is trying to achieve (natural language). */
+    intent: string;
+    dependsOn?: string[];
+    status: StepStatus;
+    attempts: number;
+    /** Short summary of what the step produced, once done. */
+    result?: string;
+}
+type PlanStatus = "active" | "done" | "failed";
+interface Plan {
+    goal: string;
+    steps: Step[];
+    status: PlanStatus;
+    /** Bumped on every replan. */
+    revision: number;
+}
+interface Observation {
+    stepId: string;
+    ok: boolean;
+    output: string;
+    toolCalls?: ToolCall[];
+    error?: string;
+    tokensUsed: number;
+}
+type Progress = "on_track" | "needs_replan" | "blocked" | "goal_met";
+interface Reflection {
+    progress: Progress;
+    notes: string;
+    confidence?: number;
+}
+type Role = "system" | "user" | "assistant";
+interface Message {
+    role: Role;
+    content: string;
+}
+interface ToolSchema {
+    name: string;
+    description: string;
+    /** JSON-schema object describing the parameters. */
+    parameters: Record<string, unknown>;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+}
+interface ToolResult {
+    ok: boolean;
+    output: string;
+    error?: string;
+}
+interface CompletionRequest {
+    messages: Message[];
+    tools?: ToolSchema[];
+    maxTokens?: number;
+    temperature?: number;
+    responseFormat?: "text" | "json";
+}
+type StopReason = "end" | "tool_use" | "max_tokens" | "error";
+interface CompletionResult {
+    content: string;
+    toolCalls?: ToolCall[];
+    tokensIn: number;
+    tokensOut: number;
+    stopReason: StopReason;
+}
+interface BudgetState {
+    steps: number;
+    tokens: number;
+    startedAtMs: number;
+    /** Separate counter so a replan storm can't run forever. */
+    replans: number;
+}
+interface Digest {
+    summary: string;
+    /** ISO timestamp this digest covers up to. */
+    coversUntil: string;
+}
+interface RunContext {
+    runId: string;
+    goal: Goal;
+    plan: Plan;
+    /** Conversation handed to the model (the thing that gets compacted). */
+    history: Message[];
+    /** Compacted summaries of folded-away history. */
+    digests: Digest[];
+    budget: BudgetState;
+    config: SerializableConfig;
+    createdAt: string;
+    updatedAt: string;
+    /** Extension slot — modules attach state without touching the core. */
+    meta: Record<string, unknown>;
+}
+/** The subset of config that is data (persisted in RunContext). */
+interface SerializableConfig {
+    maxSteps: number;
+    maxTokens: number;
+    maxWallClockMs: number;
+    maxStepAttempts: number;
+    maxReplans: number;
+    contextTokenLimit: number;
+    keepRecent: number;
+    temperature: number;
+    maxStepTokens: number;
+}
+type RunStatus = "done" | "halted" | "failed";
+interface RunResult {
+    status: RunStatus;
+    reason?: string;
+    ctx: RunContext;
+}
+interface RunSummary {
+    runId: string;
+    goal: string;
+    planStatus: PlanStatus;
+    steps: number;
+    updatedAt: string;
+}
+interface Provider {
+    name: string;
+    complete(req: CompletionRequest): Promise<CompletionResult>;
+    /** Cheap token estimate (chars/4 is fine) — only used to decide compaction. */
+    estimateTokens(messages: Message[]): number;
+}
+interface Store {
+    save(ctx: RunContext): Promise<void>;
+    load(runId: string): Promise<RunContext | null>;
+    list(): Promise<RunSummary[]>;
+}
+interface Tool {
+    name: string;
+    description: string;
+    schema: ToolSchema;
+    handler(input: unknown): Promise<ToolResult> | ToolResult;
+}
+type RunEvent = {
+    type: "plan_created";
+    plan: Plan;
+} | {
+    type: "step_start";
+    step: Step;
+} | {
+    type: "step_done";
+    step: Step;
+    observation: Observation;
+} | {
+    type: "reflection";
+    reflection: Reflection;
+    step: Step;
+} | {
+    type: "replan";
+    revision: number;
+    reason: string;
+} | {
+    type: "compaction";
+    foldedMessages: number;
+    digestChars: number;
+} | {
+    type: "checkpoint";
+    runId: string;
+} | {
+    type: "halted";
+    reason: string;
+} | {
+    type: "done";
+    reason: string;
+} | {
+    type: "escalation";
+    step: Step;
+    notes: string;
+};
+/** Full run config: data fields + injected dependencies. */
+interface RunConfig extends Partial<SerializableConfig> {
+    provider: Provider;
+    store?: Store;
+    tools?: Tool[];
+    /** Where the default FileStore writes. */
+    runsDir?: string;
+    /** Observe everything the loop does. */
+    onEvent?: (event: RunEvent) => void;
+}
+
+declare const DEFAULT_CONFIG: SerializableConfig;
+/** Merge user config over defaults and pull out the serializable subset. */
+declare function resolveSerializable(config: Partial<SerializableConfig>): SerializableConfig;
+
+/** A short, sortable, dependency-free id. */
+declare function genId(prefix?: string): string;
+/** Create a fresh, fully-initialized (and serializable) RunContext. */
+declare function createContext(goal: Goal, config: SerializableConfig): RunContext;
+/** The next pending step whose dependencies are all satisfied. */
+declare function nextPendingStep(ctx: RunContext): Step | null;
+
+interface BudgetVerdict {
+    exceeded: boolean;
+    reason?: string;
+}
+/**
+ * The three top-level guards, checked at the very top of every loop turn. The
+ * per-step (attempts) and replan guards live alongside the reflector; this is the
+ * hard ceiling that stops a runaway run from spending forever.
+ */
+declare function checkBudget(ctx: RunContext): BudgetVerdict;
+
+/**
+ * The default persistence: one JSON file per run. Zero dependencies, and the
+ * whole point of the harness — a checkpoint after every step means "resume from
+ * exactly where it died". Swap in SQLite/Redis by implementing the same Store.
+ */
+declare class FileStore implements Store {
+    private readonly dir;
+    constructor(dir?: string);
+    private ensureDir;
+    private path;
+    save(ctx: RunContext): Promise<void>;
+    load(runId: string): Promise<RunContext | null>;
+    list(): Promise<RunSummary[]>;
+}
+/** An in-memory store — handy for tests and ephemeral runs. */
+declare class MemoryStore implements Store {
+    private map;
+    save(ctx: RunContext): Promise<void>;
+    load(runId: string): Promise<RunContext | null>;
+    list(): Promise<RunSummary[]>;
+}
+
+/**
+ * Keeps the model's context inside its window by folding old, completed turns
+ * into a running digest. The plan is NEVER touched here — it lives outside
+ * history precisely so compaction can't blur "where we are".
+ */
+declare class ContextManager {
+    private readonly provider;
+    private readonly config;
+    constructor(provider: Provider, config: SerializableConfig);
+    overBudget(ctx: RunContext): boolean;
+    /** Fold all but the most recent K messages into a digest; return the new (short) history. */
+    compact(ctx: RunContext): Promise<Message[]>;
+}
+
+declare class ToolRegistry {
+    private map;
+    constructor(tools?: Tool[]);
+    register(tool: Tool): void;
+    get(name: string): Tool | undefined;
+    schemas(): ToolSchema[];
+    get size(): number;
+    /** Run a tool, turning any thrown error into a ToolResult — the loop never dies on a tool. */
+    run(name: string, input: unknown): Promise<ToolResult>;
+}
+/** Define a tool with less ceremony. */
+declare function defineTool(name: string, description: string, parameters: Record<string, unknown>, handler: (input: unknown) => Promise<ToolResult> | ToolResult): Tool;
+
+declare class Planner {
+    private readonly provider;
+    private readonly temperature;
+    constructor(provider: Provider, temperature: number);
+    plan(goal: Goal): Promise<Plan>;
+    /**
+     * Accumulate, never reset: completed steps are preserved verbatim; only the
+     * remaining work is regenerated from the point of failure. This is what lets
+     * a long task make forward progress instead of restarting forever.
+     */
+    replan(plan: Plan, obs: Observation, ctx: RunContext): Promise<Plan>;
+}
+
+declare class Executor {
+    private readonly provider;
+    private readonly opts;
+    private registry;
+    constructor(provider: Provider, registry: ToolRegistry, opts: {
+        temperature: number;
+        maxStepTokens: number;
+    });
+    execute(step: Step, ctx: RunContext): Promise<Observation>;
+}
+
+declare class Reflector {
+    private readonly provider;
+    constructor(provider: Provider);
+    reflect(plan: Plan, obs: Observation, ctx: RunContext): Promise<Reflection>;
+}
+
+interface LoopDeps {
+    planner: Planner;
+    executor: Executor;
+    reflector: Reflector;
+    contextManager: ContextManager;
+    store: Store;
+    onEvent: (e: RunEvent) => void;
+}
+/**
+ * The plan ↔ execute ↔ reflect loop. Its one invariant: at the end of every
+ * iteration, `ctx` equals what's on disk — so a crash anywhere resumes from the
+ * last checkpoint with zero lost progress.
+ */
+declare function runLoop(ctx: RunContext, deps: LoopDeps): Promise<RunResult>;
+
+/** chars/4 — deliberately rough; only used to decide when to compact. */
+declare function estimateTokens(messages: Message[]): number;
+interface RetryOptions {
+    retries?: number;
+    baseDelayMs?: number;
+    /** Decide whether an error is worth retrying (429/5xx/network). */
+    isRetryable?: (err: unknown) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Wrap a flaky async call with exponential backoff. Lives in the provider layer, not the loop. */
+declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+type ScriptedResponse = Partial<CompletionResult> | ((req: CompletionRequest) => Partial<CompletionResult>);
+/**
+ * A provider that replays a fixed script of responses in order. The thing that
+ * makes an agent built on this harness *deterministically testable* — script the
+ * model and assert the loop's behavior, no network, no flakiness.
+ */
+declare class ScriptedProvider implements Provider {
+    private readonly responses;
+    readonly name = "scripted";
+    private index;
+    /** Every request the loop made — handy for assertions. */
+    readonly requests: CompletionRequest[];
+    constructor(responses: ScriptedResponse[]);
+    complete(req: CompletionRequest): Promise<CompletionResult>;
+    estimateTokens(messages: Message[]): number;
+}
+declare const reply: {
+    plan(steps: Array<{
+        id: string;
+        intent: string;
+        dependsOn?: string[];
+    }>): ScriptedResponse;
+    reflection(progress: string, notes?: string, confidence?: number): ScriptedResponse;
+    text(content: string): ScriptedResponse;
+    toolUse(calls: ToolCall[], content?: string): ScriptedResponse;
+};
+
+interface AnthropicOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    /** anthropic-version header. */
+    version?: string;
+    maxRetries?: number;
+    defaultMaxTokens?: number;
+}
+/**
+ * The default provider — talks to the Anthropic Messages API over `fetch`, no
+ * SDK, no dependencies. Swap in any other `Provider` to go model-agnostic.
+ */
+declare class AnthropicProvider implements Provider {
+    readonly name = "anthropic";
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly version;
+    private readonly maxRetries;
+    private readonly defaultMaxTokens;
+    constructor(opts?: AnthropicOptions);
+    estimateTokens(messages: Message[]): number;
+    complete(req: CompletionRequest): Promise<CompletionResult>;
+}
+
+/** Run an agent to completion (or to a budget halt). The whole run is checkpointed every step. */
+declare function run(goal: Goal | string, config: RunConfig): Promise<RunResult>;
+/** Resume a run from its last checkpoint — same plan, same progress, continues where it died. */
+declare function resume(runId: string, config: RunConfig): Promise<RunResult>;
+/** Continue a RunContext you already hold in memory (advanced; same as resume without the store load). */
+declare function runWith(ctx: RunContext, config: RunConfig): Promise<RunResult>;
+
+export { type AnthropicOptions, AnthropicProvider, type BudgetState, type CompletionRequest, type CompletionResult, ContextManager, DEFAULT_CONFIG, type Digest, Executor, FileStore, type Goal, type LoopDeps, MemoryStore, type Message, type Observation, type Plan, type PlanStatus, Planner, type Progress, type Provider, type Reflection, Reflector, type Role, type RunConfig, type RunContext, type RunEvent, type RunResult, type RunStatus, type RunSummary, ScriptedProvider, type ScriptedResponse, type SerializableConfig, type Step, type StepStatus, type StopReason, type Store, type Tool, type ToolCall, ToolRegistry, type ToolResult, type ToolSchema, checkBudget, createContext, defineTool, estimateTokens, genId, nextPendingStep, reply, resolveSerializable, resume, run, runLoop, runWith, withRetry };