@seanhogg/builderforce-memory 2026.7.12 → 2026.9.27

package/dist/orchestration/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/orchestration/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,2BAA2B;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,oBAAoB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC;IAC3F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,GAAE,2BAAgC;IAI5C,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAOjF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAIhD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,IAAI,WAAW,IAAI,MAAM,CAA+B;CAC3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IACxC,EAAE,EAAE,YAAY,CAAC;IACjB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,oBAAoB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC;IAC3F,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,2BAA2B;IAMvC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAMvF,oBAAoB;IACd,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAahD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,OAAO,CAAC,IAAI;CAGf"}

package/dist/orchestration/checkpoint.js

@@ -0,0 +1,92 @@
+/**
+ * orchestration/checkpoint.ts — durable state between supersteps.
+ *
+ * Checkpointing is what turns three separate features into one mechanism:
+ * crash recovery, human-in-the-loop approval, and time-travel debugging. All three
+ * are "load the state as of superstep N and continue", so they share an
+ * implementation rather than each growing their own.
+ */
+export class InMemoryCheckpointer {
+    _threads = new Map();
+    _max;
+    constructor(opts = {}) {
+        this._max = Math.max(1, opts.maxPerThread ?? 50);
+    }
+    async save(checkpoint) {
+        const history = this._threads.get(checkpoint.threadId) ?? [];
+        // Same id means the same superstep was re-entered (a resumed run): replace
+        // rather than append, so history stays a line and not a tangle.
+        const existing = history.findIndex((c) => c.id === checkpoint.id);
+        if (existing >= 0)
+            history[existing] = checkpoint;
+        else
+            history.push(checkpoint);
+        history.sort((a, b) => a.step - b.step);
+        if (history.length > this._max)
+            history.splice(0, history.length - this._max);
+        this._threads.set(checkpoint.threadId, history);
+    }
+    async load(threadId, checkpointId) {
+        const history = this._threads.get(threadId);
+        if (!history || history.length === 0)
+            return undefined;
+        if (checkpointId)
+            return history.find((c) => c.id === checkpointId);
+        return history[history.length - 1];
+    }
+    async list(threadId) {
+        return [...(this._threads.get(threadId) ?? [])].reverse();
+    }
+    async clear(threadId) {
+        this._threads.delete(threadId);
+    }
+    get threadCount() { return this._threads.size; }
+}
+export class KeyValueCheckpointer {
+    _kv;
+    _prefix;
+    _max;
+    constructor(opts) {
+        this._kv = opts.kv;
+        this._prefix = opts.prefix ?? 'evermind:ckpt:';
+        this._max = Math.max(1, opts.maxPerThread ?? 50);
+    }
+    async save(checkpoint) {
+        const history = await this.list(checkpoint.threadId);
+        const without = history.filter((c) => c.id !== checkpoint.id);
+        const next = [...without, checkpoint]
+            .sort((a, b) => a.step - b.step)
+            .slice(-this._max);
+        // One key per thread rather than one per checkpoint: a thread's history is
+        // always read whole, and a single round trip beats a list-then-fan-out.
+        await this._kv.put(this._key(checkpoint.threadId), JSON.stringify(next));
+    }
+    async load(threadId, checkpointId) {
+        const history = await this.list(threadId);
+        if (history.length === 0)
+            return undefined;
+        return checkpointId ? history.find((c) => c.id === checkpointId) : history[0];
+    }
+    /** Newest first. */
+    async list(threadId) {
+        const raw = await this._kv.get(this._key(threadId));
+        if (!raw)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? [...parsed].sort((a, b) => b.step - a.step) : [];
+        }
+        catch {
+            // A corrupt entry must not wedge the thread forever; treat it as empty
+            // so the next run rebuilds rather than throwing on every resume.
+            return [];
+        }
+    }
+    async clear(threadId) {
+        await this._kv.delete(this._key(threadId));
+    }
+    _key(threadId) {
+        return `${this._prefix}${threadId}`;
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/orchestration/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/orchestration/checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * orchestration — stateful multi-agent graphs (supersteps, declared channel
+ * merges, checkpointing) plus the three patterns enterprise work reduces to:
+ * ReAct, self-reflection, and hierarchical delegation.
+ */
+export { AgentGraph, appendReducer, mergeReducer, sumReducer, unionReducer, } from './AgentGraph.js';
+export type { AgentGraphOptions, RunOptions } from './AgentGraph.js';
+export { InMemoryCheckpointer, KeyValueCheckpointer } from './checkpoint.js';
+export type { InMemoryCheckpointerOptions, KeyValueCheckpointerOptions, KeyValueLike, } from './checkpoint.js';
+export { createReactAgent, createReflectionAgent, createSupervisor, asWorker, parseReactTurn, renderToolCatalog, renderTranscript, REACT_PROTOCOL, DEFAULT_CRITIC_PROMPT, FINISH, } from './patterns.js';
+export type { AgentTool, AgentTurn, AgentTurnRole, ParsedAction, ReactAgentOptions, ReactState, ReflectionAgentOptions, ReflectionState, SupervisorOptions, SupervisorState, Worker, } from './patterns.js';
+export { START, END } from './types.js';
+export type { ChannelReducer, ChannelSpec, ChannelSpecs, Checkpoint, Checkpointer, EdgeCondition, GraphEndReason, GraphEvent, GraphRunResult, GraphState, NodeContext, NodeFn, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/orchestration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestration/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,GACf,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EACR,2BAA2B,EAC3B,2BAA2B,EAC3B,YAAY,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,MAAM,GACT,MAAM,eAAe,CAAC;AACvB,YAAY,EACR,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,MAAM,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,UAAU,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,MAAM,GACT,MAAM,YAAY,CAAC"}

package/dist/orchestration/index.js

@@ -0,0 +1,10 @@
+/**
+ * orchestration — stateful multi-agent graphs (supersteps, declared channel
+ * merges, checkpointing) plus the three patterns enterprise work reduces to:
+ * ReAct, self-reflection, and hierarchical delegation.
+ */
+export { AgentGraph, appendReducer, mergeReducer, sumReducer, unionReducer, } from './AgentGraph.js';
+export { InMemoryCheckpointer, KeyValueCheckpointer } from './checkpoint.js';
+export { createReactAgent, createReflectionAgent, createSupervisor, asWorker, parseReactTurn, renderToolCatalog, renderTranscript, REACT_PROTOCOL, DEFAULT_CRITIC_PROMPT, FINISH, } from './patterns.js';
+export { START, END } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/orchestration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/orchestration/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACH,UAAU,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAO7E,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,MAAM,GACT,MAAM,eAAe,CAAC;AAevB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC"}

package/dist/orchestration/patterns.d.ts

@@ -0,0 +1,159 @@
+/**
+ * orchestration/patterns.ts — ReAct, self-reflection, hierarchical delegation.
+ *
+ * These are the three patterns enterprise agent work actually reduces to, and each
+ * is a small graph rather than a bespoke loop, so they compose: a supervisor's
+ * worker can be a ReAct agent, and a ReAct agent's answer can be routed through a
+ * reflection pass. That composability is why they are built on {@link AgentGraph}
+ * instead of as three independent classes.
+ *
+ * The bridge port is plain text in, text out, so tool use is expressed as a strict
+ * textual protocol the model is instructed to follow, and violations are handled
+ * as data (an observation telling the model what it got wrong) rather than as
+ * exceptions. A model that emits a malformed action must be able to recover on the
+ * next turn; throwing would end the run over a formatting slip.
+ */
+import type { TransformerBridge } from '../bridges/TransformerBridge.js';
+import type { Tracer } from '../telemetry/Tracer.js';
+import { AgentGraph } from './AgentGraph.js';
+import type { Checkpointer } from './types.js';
+export type AgentTurnRole = 'user' | 'assistant' | 'system' | 'tool';
+export interface AgentTurn {
+    role: AgentTurnRole;
+    content: string;
+    /** Set on `tool` turns — which tool produced this observation. */
+    name?: string;
+}
+/** Renders a transcript for a text-completion bridge. */
+export declare function renderTranscript(turns: readonly AgentTurn[]): string;
+export interface AgentTool {
+    name: string;
+    description: string;
+    /** Parameter documentation, rendered into the prompt. */
+    parameters?: Record<string, string>;
+    run(input: Record<string, unknown>): Promise<string> | string;
+}
+export declare function renderToolCatalog(tools: readonly AgentTool[]): string;
+export interface ParsedAction {
+    kind: 'action' | 'final' | 'malformed';
+    thought?: string;
+    tool?: string;
+    input?: Record<string, unknown>;
+    answer?: string;
+    problem?: string;
+}
+/**
+ * Parses one ReAct turn.
+ *
+ * Tolerant on purpose: models drift on whitespace, casing and code fences far more
+ * often than they drift on intent, and a parser that rejects `**Action:**` burns a
+ * turn for no reason. Genuinely unparseable output returns `malformed` with a
+ * message that is fed back as an observation.
+ */
+export declare function parseReactTurn(text: string): ParsedAction;
+export type ReactState = {
+    task: string;
+    turns: AgentTurn[];
+    /** Tool invocations so far — the loop's own budget meter. */
+    toolCalls: number;
+    answer: string;
+    done: boolean;
+};
+export interface ReactAgentOptions {
+    bridge: TransformerBridge;
+    tools: readonly AgentTool[];
+    /** Prepended to the generated protocol instructions. */
+    systemPrompt?: string;
+    /** Reason/act cycles before the agent must answer. Default 6. */
+    maxIterations?: number;
+    maxTokens?: number;
+    model?: string;
+    tracer?: Tracer;
+    checkpointer?: Checkpointer<ReactState>;
+}
+export declare const REACT_PROTOCOL: string;
+/**
+ * ReAct: interleaved reasoning and tool use.
+ *
+ * Two nodes and a conditional edge — `reason` produces a thought plus either an
+ * action or a final answer; `act` executes the tool and appends an observation;
+ * the edge routes back to `reason` or to END. The iteration cap is enforced in the
+ * routing rather than trusted to the model, because "decide when to stop" is the
+ * one judgement an unconverged agent is worst at.
+ */
+export declare function createReactAgent(opts: ReactAgentOptions): AgentGraph<ReactState>;
+export type ReflectionState = {
+    task: string;
+    draft: string;
+    critique: string;
+    revisions: number;
+    accepted: boolean;
+    history: string[];
+};
+export interface ReflectionAgentOptions {
+    bridge: TransformerBridge;
+    /** Revision rounds allowed after the first draft. Default 2. */
+    maxRevisions?: number;
+    /** Instructions for the drafting pass. */
+    generatorPrompt?: string;
+    /** Instructions for the critic. Must ask for an explicit verdict token. */
+    criticPrompt?: string;
+    /** Decides acceptance from the critique. Default: looks for `APPROVED`. */
+    isAcceptable?: (critique: string) => boolean;
+    maxTokens?: number;
+    model?: string;
+    tracer?: Tracer;
+    checkpointer?: Checkpointer<ReflectionState>;
+}
+export declare const DEFAULT_CRITIC_PROMPT: string;
+/**
+ * Generate → critique → revise, bounded.
+ *
+ * Reflection earns its cost only when the critic is allowed to be harsh and the
+ * loop is allowed to stop: an unbounded critic converges on nitpicking, and a
+ * critic that cannot say APPROVED doubles spend for no quality gain. Both limits
+ * are enforced here rather than requested in the prompt.
+ */
+export declare function createReflectionAgent(opts: ReflectionAgentOptions): AgentGraph<ReflectionState>;
+export interface Worker {
+    name: string;
+    /** What this worker is for — the supervisor routes on this text. */
+    description: string;
+    /** Runs the sub-task and returns its result. May itself be a graph. */
+    run(task: string, context: {
+        transcript: readonly AgentTurn[];
+    }): Promise<string>;
+}
+export type SupervisorState = {
+    task: string;
+    turns: AgentTurn[];
+    /** Worker chosen for the next hop, or `FINISH`. */
+    next: string;
+    handoffs: number;
+    answer: string;
+};
+export interface SupervisorOptions {
+    bridge: TransformerBridge;
+    workers: readonly Worker[];
+    /** Delegations before the supervisor must answer. Default 5. */
+    maxHandoffs?: number;
+    systemPrompt?: string;
+    maxTokens?: number;
+    model?: string;
+    tracer?: Tracer;
+    checkpointer?: Checkpointer<SupervisorState>;
+}
+export declare const FINISH = "FINISH";
+/**
+ * A supervisor that delegates to named workers and then composes the answer.
+ *
+ * Hierarchical delegation is worth its coordination overhead exactly when workers
+ * hold context the supervisor should not — a different tool set, a different
+ * corpus, a different tenant's data. Each worker returns a RESULT rather than its
+ * transcript, which is what keeps the supervisor's context from growing into the
+ * sum of everything its workers read.
+ */
+export declare function createSupervisor(opts: SupervisorOptions): AgentGraph<SupervisorState>;
+/** Adapts a ReAct agent into a {@link Worker}, so hierarchies nest. */
+export declare function asWorker(name: string, description: string, graph: AgentGraph<ReactState>): Worker;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/orchestration/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/orchestration/patterns.ts"],"names":[],"mappings":"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"}