wotann 0.5.0

package/dist/orchestration/flowise-canvas/canvas.js

@@ -0,0 +1,137 @@
+/**
+ * Flowise visual canvas validator —
+ * inspired by https://github.com/FlowiseAI/Flowise.
+ *
+ * WHAT
+ *   Typed canvas document `{nodes, edges, viewport}` with a
+ *   STRUCTURAL validator that checks node-type whitelist, edge
+ *   connectivity, no orphan nodes (every non-utility node must be
+ *   reachable from a starting node), and unique ids.
+ *
+ * WHY
+ *   Flowise canvases ship as JSON; users want to import them into
+ *   WOTANN without wiring the Flowise runtime. Distinct from
+ *   dify-flow (different node taxonomy, no socket templates) and
+ *   coze-flow (different edge semantics).
+ *
+ * QUALITY BARS
+ *   QB #6  honest validation — never throws on bad input.
+ *   QB #7  zero module-level state.
+ */
+// ── Types ─────────────────────────────────────────────────
+const KNOWN_NODE_TYPES = new Set([
+    "ChatInput",
+    "ChatOutput",
+    "ChatPromptTemplate",
+    "ConversationChain",
+    "LLMChain",
+    "Agent",
+    "Tool",
+    "VectorStore",
+    "Embeddings",
+    "DocumentLoader",
+    "TextSplitter",
+    "Memory",
+    "OutputParser",
+    "Retriever",
+    "If",
+    "Switch",
+]);
+const STARTING_TYPES = new Set(["ChatInput", "DocumentLoader"]);
+/**
+ * Validate the structure of a Flowise canvas document. Confirms ids are
+ * unique, node types are recognized (warning for unknowns), edges
+ * reference existing nodes, no edge-loops on a single node, viewport
+ * is finite, and no node is orphaned (every non-starting node is
+ * reachable from at least one starting node via incoming edges).
+ */
+export function validateCanvas(c) {
+    const issues = [];
+    if (typeof c.id !== "string" || c.id.length === 0) {
+        issues.push({ severity: "error", message: "Canvas id must be non-empty" });
+    }
+    // Unique node ids + type whitelist
+    const nodeIds = new Set();
+    for (const n of c.nodes) {
+        if (nodeIds.has(n.id)) {
+            issues.push({
+                severity: "error",
+                message: `Duplicate node id: ${n.id}`,
+                nodeId: n.id,
+            });
+        }
+        else {
+            nodeIds.add(n.id);
+        }
+        if (!KNOWN_NODE_TYPES.has(n.type)) {
+            issues.push({
+                severity: "warning",
+                message: `Unknown node type "${n.type}" — may be a custom node`,
+                nodeId: n.id,
+            });
+        }
+    }
+    // Unique edges + edge node references + no self-loops
+    const edgeIds = new Set();
+    const incoming = new Map();
+    for (const e of c.edges) {
+        if (edgeIds.has(e.id)) {
+            issues.push({
+                severity: "error",
+                message: `Duplicate edge id: ${e.id}`,
+                edgeId: e.id,
+            });
+        }
+        else {
+            edgeIds.add(e.id);
+        }
+        if (!nodeIds.has(e.source)) {
+            issues.push({
+                severity: "error",
+                message: `Edge ${e.id} source ${e.source} does not exist`,
+                edgeId: e.id,
+            });
+        }
+        if (!nodeIds.has(e.target)) {
+            issues.push({
+                severity: "error",
+                message: `Edge ${e.id} target ${e.target} does not exist`,
+                edgeId: e.id,
+            });
+        }
+        if (e.source === e.target) {
+            issues.push({
+                severity: "error",
+                message: `Edge ${e.id} is a self-loop on ${e.source}`,
+                edgeId: e.id,
+            });
+        }
+        incoming.set(e.target, (incoming.get(e.target) ?? 0) + 1);
+    }
+    // Orphan nodes: any non-starting node with no incoming edges
+    for (const n of c.nodes) {
+        if (STARTING_TYPES.has(n.type))
+            continue;
+        if ((incoming.get(n.id) ?? 0) === 0) {
+            issues.push({
+                severity: "warning",
+                message: `Orphan node ${n.id} (type ${n.type}) has no incoming edges`,
+                nodeId: n.id,
+            });
+        }
+    }
+    // Viewport
+    if (!Number.isFinite(c.viewport.zoom) || c.viewport.zoom <= 0) {
+        issues.push({
+            severity: "error",
+            message: `viewport.zoom must be > 0, got ${c.viewport.zoom}`,
+        });
+    }
+    const hasErrors = issues.some((i) => i.severity === "error");
+    return { ok: !hasErrors, issues };
+}
+/** Returns the set of recognized node type names for inspection/UI. */
+export function listKnownNodeTypes() {
+    return Array.from(KNOWN_NODE_TYPES.values());
+}
+//# sourceMappingURL=canvas.js.map

package/dist/orchestration/flowise-canvas/canvas.js.map

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

package/dist/orchestration/generative-agents-deep/observation-stream.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Smallville observation -> memory pipeline —
+ * inspired by https://github.com/joonspk-research/generative_agents.
+ *
+ * WHAT
+ *   Pure-function pipeline that ingests `Observation` records and
+ *   stores them as `MemoryRecord`s scored by importance. Retrieves
+ *   memories by Smallville's exact composite formula:
+ *      score = recency × relevance × importance
+ *   where:
+ *      recency   = exp(-decayRate × deltaTicks)     (exponential decay)
+ *      relevance = cosine of pre-supplied query vec & memory vec
+ *      importance= scalar in [0,1] from {@link scoreImportance}
+ *
+ * WHY
+ *   src/orchestration/multi-agent-society stores memories but does
+ *   NOT implement Smallville's exact retrieval scoring. This module
+ *   adds it as a separate, side-effect-free pipeline. Distinct from
+ *   src/orchestration/reflection-stream (which is reflection-only).
+ *
+ * QUALITY BARS
+ *   QB #6  honest stubs — empty memory returns empty retrieval,
+ *          never a fake "default" record.
+ *   QB #7  zero module-level state.
+ */
+export interface Observation {
+    readonly tick: number;
+    readonly content: string;
+    /** Embedding vector. Caller-provided; this module does not embed. */
+    readonly embedding: readonly number[];
+}
+export interface MemoryRecord {
+    readonly tick: number;
+    readonly content: string;
+    readonly embedding: readonly number[];
+    /** Importance scalar in [0, 1]. */
+    readonly importance: number;
+}
+export interface RetrievalQuery {
+    readonly embedding: readonly number[];
+    readonly currentTick: number;
+    /** Decay rate per tick, e.g. 0.01 (slow), 0.5 (fast). Must be > 0. */
+    readonly decayRate: number;
+    readonly topK: number;
+}
+export interface RetrievalResult {
+    readonly memory: MemoryRecord;
+    readonly score: number;
+    readonly recency: number;
+    readonly relevance: number;
+}
+/**
+ * Smallville's importance scoring — heuristic without LLM. Returns a
+ * scalar in [0, 1] based on content cues. NOT a substitute for an
+ * LLM rater; this is the offline / fixture path so tests are
+ * deterministic and tokens are not burned.
+ */
+export declare function scoreImportance(content: string): number;
+/** Convert an observation into a memory record by attaching importance. */
+export declare function ingest(obs: Observation): MemoryRecord;
+/**
+ * Retrieve memories scored by Smallville's exact formula:
+ *    score = recency × relevance × importance
+ *
+ * Returns top-K results sorted by score descending. Empty input
+ * yields empty output.
+ */
+export declare function retrieve(memories: readonly MemoryRecord[], query: RetrievalQuery): readonly RetrievalResult[];
+//# sourceMappingURL=observation-stream.d.ts.map

package/dist/orchestration/generative-agents-deep/observation-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-stream.d.ts","sourceRoot":"","sources":["../../../src/orchestration/generative-agents-deep/observation-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAYvD;AAED,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY,CAUrD;AAID;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,EAAE,cAAc,GACpB,SAAS,eAAe,EAAE,CAqB5B"}

package/dist/orchestration/generative-agents-deep/observation-stream.js

@@ -0,0 +1,115 @@
+/**
+ * Smallville observation -> memory pipeline —
+ * inspired by https://github.com/joonspk-research/generative_agents.
+ *
+ * WHAT
+ *   Pure-function pipeline that ingests `Observation` records and
+ *   stores them as `MemoryRecord`s scored by importance. Retrieves
+ *   memories by Smallville's exact composite formula:
+ *      score = recency × relevance × importance
+ *   where:
+ *      recency   = exp(-decayRate × deltaTicks)     (exponential decay)
+ *      relevance = cosine of pre-supplied query vec & memory vec
+ *      importance= scalar in [0,1] from {@link scoreImportance}
+ *
+ * WHY
+ *   src/orchestration/multi-agent-society stores memories but does
+ *   NOT implement Smallville's exact retrieval scoring. This module
+ *   adds it as a separate, side-effect-free pipeline. Distinct from
+ *   src/orchestration/reflection-stream (which is reflection-only).
+ *
+ * QUALITY BARS
+ *   QB #6  honest stubs — empty memory returns empty retrieval,
+ *          never a fake "default" record.
+ *   QB #7  zero module-level state.
+ */
+// ── Importance scoring ────────────────────────────────────
+/**
+ * Smallville's importance scoring — heuristic without LLM. Returns a
+ * scalar in [0, 1] based on content cues. NOT a substitute for an
+ * LLM rater; this is the offline / fixture path so tests are
+ * deterministic and tokens are not burned.
+ */
+export function scoreImportance(content) {
+    if (typeof content !== "string" || content.length === 0)
+        return 0;
+    const lc = content.toLowerCase();
+    // Strong cues that indicate emotional/social/goal-relevant events.
+    const strong = ["died", "marriage", "fired", "fight", "love", "breakthrough"];
+    const medium = ["meeting", "promised", "decided", "argued", "celebrated"];
+    const weak = ["walked", "saw", "ate", "slept", "passed by"];
+    let s = 0.1;
+    for (const w of strong)
+        if (lc.includes(w))
+            s = Math.max(s, 0.9);
+    for (const w of medium)
+        if (lc.includes(w))
+            s = Math.max(s, 0.55);
+    for (const w of weak)
+        if (lc.includes(w))
+            s = Math.max(s, 0.2);
+    return Math.min(1, s);
+}
+/** Convert an observation into a memory record by attaching importance. */
+export function ingest(obs) {
+    if (!Number.isFinite(obs.tick) || obs.tick < 0) {
+        throw new Error(`observation.tick must be finite >=0, got ${obs.tick}`);
+    }
+    return Object.freeze({
+        tick: obs.tick,
+        content: obs.content,
+        embedding: Object.freeze([...obs.embedding]),
+        importance: scoreImportance(obs.content),
+    });
+}
+// ── Retrieval ─────────────────────────────────────────────
+/**
+ * Retrieve memories scored by Smallville's exact formula:
+ *    score = recency × relevance × importance
+ *
+ * Returns top-K results sorted by score descending. Empty input
+ * yields empty output.
+ */
+export function retrieve(memories, query) {
+    // Validate query BEFORE the empty-memory short-circuit so callers
+    // that pass garbage parameters fail loudly even when the memory
+    // store happens to be empty.
+    if (!Number.isFinite(query.decayRate) || query.decayRate <= 0) {
+        throw new Error(`decayRate must be > 0, got ${query.decayRate}`);
+    }
+    if (!Number.isFinite(query.topK) || query.topK < 1) {
+        throw new Error(`topK must be >=1, got ${query.topK}`);
+    }
+    if (memories.length === 0)
+        return [];
+    const out = [];
+    for (const m of memories) {
+        const delta = Math.max(0, query.currentTick - m.tick);
+        const recency = Math.exp(-query.decayRate * delta);
+        const relevance = cosine(query.embedding, m.embedding);
+        const score = recency * relevance * m.importance;
+        out.push({ memory: m, score, recency, relevance });
+    }
+    out.sort((a, b) => b.score - a.score);
+    return out.slice(0, query.topK);
+}
+// ── Internals ─────────────────────────────────────────────
+function cosine(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ai = a[i] ?? 0;
+        const bi = b[i] ?? 0;
+        dot += ai * bi;
+        na += ai * ai;
+        nb += bi * bi;
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}
+//# sourceMappingURL=observation-stream.js.map

package/dist/orchestration/generative-agents-deep/observation-stream.js.map

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

package/dist/orchestration/generator-agent-loop.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Generator Agent Loop — pure generator-driven agent harness.
+ *
+ * Ported from lsdefine/GenericAgent (`agent_loop.py:agent_runner_loop`):
+ * the original is a Python yield-from generator that lets a caller drive
+ * an LLM agent turn by turn — each yield is a chunk of UI output, each
+ * tool dispatch is awaited, each turn ends with a callback that decides
+ * whether to terminate or feed the next prompt back in.
+ *
+ * Why this matters: most agent loops in this repo are imperative
+ * (coordinator.ts, autonomous.ts, long-horizon-orchestrator.ts) and
+ * produce side effects internally. This adapter keeps the *iteration*
+ * pure — the iterator yields {@link StepOutcome} values, the *caller*
+ * threads I/O. That makes:
+ *   - Pause/resume trivial (just stop iterating)
+ *   - Test fixtures dead simple (no LLM mocks, just feed responses)
+ *   - Composition with existing context-shrinkers automatic (the caller
+ *     can run shrinkTranscript() between turns without poking inside
+ *     this module)
+ *
+ * Quality bars:
+ *   - QB#7: every state lives in the closure created by
+ *     {@link runGeneratorAgentLoop} — no module-globals, two concurrent
+ *     loops cannot poison each other.
+ *   - QB#3: when `should_exit` flips, we yield exactly one terminal
+ *     outcome and stop. We never silently swallow exit reasons.
+ *   - All public types are `readonly`.
+ */
+/** A single tool call request from the model, normalised. */
+export interface ToolCallRequest {
+    readonly id: string;
+    readonly toolName: string;
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/** Outcome of dispatching one tool. Caller-controlled flow. */
+export interface StepOutcome {
+    /** Result data from the tool — fed back to the model. */
+    readonly data: unknown;
+    /** Optional next prompt; if absent, current task is done. */
+    readonly nextPrompt?: string;
+    /** Hard exit — overrides everything else. */
+    readonly shouldExit?: boolean;
+    /** Optional structured exit reason for telemetry. */
+    readonly exitReason?: string;
+}
+/** Function the caller supplies to dispatch a single tool call. */
+export type ToolDispatcher = (request: ToolCallRequest, turn: number) => Promise<StepOutcome>;
+/** Function the caller supplies to fetch the next LLM response. */
+export interface LLMTurnResponse {
+    readonly toolCalls: readonly ToolCallRequest[];
+    /** Plaintext content from the model (for UI display). */
+    readonly content?: string;
+}
+export type LLMRunner = (input: {
+    readonly turn: number;
+    readonly userInput: string;
+    readonly history: readonly LoopHistoryEntry[];
+}) => Promise<LLMTurnResponse>;
+/** Optional hook called after every turn — can rewrite the next prompt. */
+export type TurnEndCallback = (input: {
+    readonly turn: number;
+    readonly response: LLMTurnResponse;
+    readonly toolCalls: readonly ToolCallRequest[];
+    readonly toolOutcomes: readonly StepOutcome[];
+    readonly proposedNextPrompt: string;
+    readonly exitReason: string | null;
+}) => string | null;
+/** History entry — what the caller can inspect between turns. */
+export interface LoopHistoryEntry {
+    readonly turn: number;
+    readonly userInput: string;
+    readonly response: LLMTurnResponse;
+    readonly toolOutcomes: readonly StepOutcome[];
+}
+/** Reason the loop terminated — mirrors agent_loop.py's exit_reason dict. */
+export type LoopExitReason = "EXITED" | "CURRENT_TASK_DONE" | "MAX_TURNS_EXCEEDED" | "NO_TOOL_CALLS";
+/** Shape yielded by the iterator at each step. */
+export type LoopEvent = {
+    readonly kind: "turn_start";
+    readonly turn: number;
+} | {
+    readonly kind: "model_response";
+    readonly turn: number;
+    readonly content: string;
+} | {
+    readonly kind: "tool_dispatch";
+    readonly turn: number;
+    readonly request: ToolCallRequest;
+} | {
+    readonly kind: "tool_result";
+    readonly turn: number;
+    readonly outcome: StepOutcome;
+} | {
+    readonly kind: "turn_end";
+    readonly turn: number;
+    readonly nextPrompt: string | null;
+} | {
+    readonly kind: "exit";
+    readonly reason: LoopExitReason;
+    readonly data?: unknown;
+};
+/** Configuration for {@link runGeneratorAgentLoop}. */
+export interface GeneratorAgentLoopOptions {
+    readonly userInput: string;
+    readonly llm: LLMRunner;
+    readonly dispatch: ToolDispatcher;
+    readonly maxTurns?: number;
+    readonly turnEndCallback?: TurnEndCallback;
+    /**
+     * Optional hook invoked once a turn's outcomes are aggregated, just
+     * before turnEndCallback runs. Lets the caller inject middleware
+     * (transcript shrinkers, cost trackers, observers) without modifying
+     * this module — composition over inheritance.
+     */
+    readonly observeTurn?: (entry: LoopHistoryEntry) => void;
+}
+/**
+ * Drive an agent loop as a pure async generator. The caller iterates
+ * via `for await (const event of runGeneratorAgentLoop(...))` and
+ * decides what to do with each event (render, log, persist).
+ *
+ * The iterator never throws on "expected" exits — it yields a terminal
+ * `exit` event and returns. Genuine errors from `llm` or `dispatch`
+ * propagate out (the caller's responsibility to catch).
+ */
+export declare function runGeneratorAgentLoop(options: GeneratorAgentLoopOptions): AsyncGenerator<LoopEvent, LoopExitReason, void>;
+/**
+ * Drain a {@link runGeneratorAgentLoop} into an array of events. Useful
+ * for tests — callers that just want the final outcome can `await`
+ * this and inspect `events[events.length - 1]`.
+ */
+export declare function collectLoopEvents(options: GeneratorAgentLoopOptions): Promise<{
+    readonly events: readonly LoopEvent[];
+    readonly reason: LoopExitReason;
+}>;
+//# sourceMappingURL=generator-agent-loop.d.ts.map

package/dist/orchestration/generator-agent-loop.d.ts.map

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

package/dist/orchestration/generator-agent-loop.js

@@ -0,0 +1,144 @@
+/**
+ * Generator Agent Loop — pure generator-driven agent harness.
+ *
+ * Ported from lsdefine/GenericAgent (`agent_loop.py:agent_runner_loop`):
+ * the original is a Python yield-from generator that lets a caller drive
+ * an LLM agent turn by turn — each yield is a chunk of UI output, each
+ * tool dispatch is awaited, each turn ends with a callback that decides
+ * whether to terminate or feed the next prompt back in.
+ *
+ * Why this matters: most agent loops in this repo are imperative
+ * (coordinator.ts, autonomous.ts, long-horizon-orchestrator.ts) and
+ * produce side effects internally. This adapter keeps the *iteration*
+ * pure — the iterator yields {@link StepOutcome} values, the *caller*
+ * threads I/O. That makes:
+ *   - Pause/resume trivial (just stop iterating)
+ *   - Test fixtures dead simple (no LLM mocks, just feed responses)
+ *   - Composition with existing context-shrinkers automatic (the caller
+ *     can run shrinkTranscript() between turns without poking inside
+ *     this module)
+ *
+ * Quality bars:
+ *   - QB#7: every state lives in the closure created by
+ *     {@link runGeneratorAgentLoop} — no module-globals, two concurrent
+ *     loops cannot poison each other.
+ *   - QB#3: when `should_exit` flips, we yield exactly one terminal
+ *     outcome and stop. We never silently swallow exit reasons.
+ *   - All public types are `readonly`.
+ */
+/**
+ * Drive an agent loop as a pure async generator. The caller iterates
+ * via `for await (const event of runGeneratorAgentLoop(...))` and
+ * decides what to do with each event (render, log, persist).
+ *
+ * The iterator never throws on "expected" exits — it yields a terminal
+ * `exit` event and returns. Genuine errors from `llm` or `dispatch`
+ * propagate out (the caller's responsibility to catch).
+ */
+export async function* runGeneratorAgentLoop(options) {
+    const maxTurns = options.maxTurns ?? 40;
+    const history = [];
+    let userInput = options.userInput;
+    let turn = 0;
+    while (turn < maxTurns) {
+        turn++;
+        yield { kind: "turn_start", turn };
+        const response = await options.llm({
+            turn,
+            userInput,
+            history,
+        });
+        if (response.content) {
+            yield { kind: "model_response", turn, content: response.content };
+        }
+        // No tool calls — model is signalling end-of-task.
+        if (response.toolCalls.length === 0) {
+            const entry = {
+                turn,
+                userInput,
+                response,
+                toolOutcomes: [],
+            };
+            history.push(entry);
+            options.observeTurn?.(entry);
+            yield { kind: "exit", reason: "NO_TOOL_CALLS" };
+            return "NO_TOOL_CALLS";
+        }
+        // Dispatch each tool call sequentially. agent_loop.py walks tool calls
+        // in order and breaks on the first should_exit / no-next-prompt — we
+        // mirror that semantics so callers can rely on linear ordering.
+        const outcomes = [];
+        const nextPrompts = new Set();
+        let exitData = undefined;
+        let exitReason = null;
+        for (const request of response.toolCalls) {
+            yield { kind: "tool_dispatch", turn, request };
+            const outcome = await options.dispatch(request, turn);
+            outcomes.push(outcome);
+            yield { kind: "tool_result", turn, outcome };
+            if (outcome.shouldExit) {
+                exitData = outcome.data;
+                exitReason = "EXITED";
+                break;
+            }
+            if (outcome.nextPrompt === undefined || outcome.nextPrompt === "") {
+                // Per Python loop: empty next_prompt means CURRENT_TASK_DONE.
+                exitData = outcome.data;
+                exitReason = "CURRENT_TASK_DONE";
+                break;
+            }
+            nextPrompts.add(outcome.nextPrompt);
+        }
+        const proposedNext = Array.from(nextPrompts).join("\n");
+        const entry = {
+            turn,
+            userInput,
+            response,
+            toolOutcomes: outcomes,
+        };
+        history.push(entry);
+        options.observeTurn?.(entry);
+        // Caller-supplied turn-end hook can rewrite the next prompt or
+        // veto continuation by returning null. This is the place to plug
+        // in transcript-shrinker, deferred-tool-filter, etc.
+        const callbackResult = options.turnEndCallback?.({
+            turn,
+            response,
+            toolCalls: response.toolCalls,
+            toolOutcomes: outcomes,
+            proposedNextPrompt: proposedNext,
+            exitReason,
+        });
+        if (exitReason !== null) {
+            yield { kind: "turn_end", turn, nextPrompt: null };
+            yield { kind: "exit", reason: exitReason, data: exitData };
+            return exitReason;
+        }
+        const finalNextPrompt = callbackResult !== undefined ? callbackResult : proposedNext;
+        if (finalNextPrompt === null || finalNextPrompt === "") {
+            yield { kind: "turn_end", turn, nextPrompt: null };
+            yield { kind: "exit", reason: "CURRENT_TASK_DONE" };
+            return "CURRENT_TASK_DONE";
+        }
+        yield { kind: "turn_end", turn, nextPrompt: finalNextPrompt };
+        userInput = finalNextPrompt;
+    }
+    yield { kind: "exit", reason: "MAX_TURNS_EXCEEDED" };
+    return "MAX_TURNS_EXCEEDED";
+}
+/**
+ * Drain a {@link runGeneratorAgentLoop} into an array of events. Useful
+ * for tests — callers that just want the final outcome can `await`
+ * this and inspect `events[events.length - 1]`.
+ */
+export async function collectLoopEvents(options) {
+    const events = [];
+    const iter = runGeneratorAgentLoop(options);
+    let result = await iter.next();
+    while (!result.done) {
+        events.push(result.value);
+        result = await iter.next();
+    }
+    return { events, reason: result.value };
+}
+//# sourceMappingURL=generator-agent-loop.js.map

package/dist/orchestration/generator-agent-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-agent-loop.js","sourceRoot":"","sources":["../../src/orchestration/generator-agent-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAuFH;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,qBAAqB,CAC1C,OAAkC;IAElC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,IAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAClC,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,OAAO,IAAI,GAAG,QAAQ,EAAE,CAAC;QACvB,IAAI,EAAE,CAAC;QACP,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAEnC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACjC,IAAI;YACJ,SAAS;YACT,OAAO;SACR,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACpE,CAAC;QAED,mDAAmD;QACnD,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,KAAK,GAAqB;gBAC9B,IAAI;gBACJ,SAAS;gBACT,QAAQ;gBACR,YAAY,EAAE,EAAE;aACjB,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;YAC7B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YAChD,OAAO,eAAe,CAAC;QACzB,CAAC;QAED,uEAAuE;QACvE,qEAAqE;QACrE,gEAAgE;QAChE,MAAM,QAAQ,GAAkB,EAAE,CAAC;QACnC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;QACtC,IAAI,QAAQ,GAAY,SAAS,CAAC;QAClC,IAAI,UAAU,GAA0B,IAAI,CAAC;QAE7C,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;YAC/C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACtD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACvB,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;YAE7C,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACvB,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;gBACxB,UAAU,GAAG,QAAQ,CAAC;gBACtB,MAAM;YACR,CAAC;YACD,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,CAAC,UAAU,KAAK,EAAE,EAAE,CAAC;gBAClE,8DAA8D;gBAC9D,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;gBACxB,UAAU,GAAG,mBAAmB,CAAC;gBACjC,MAAM;YACR,CAAC;YACD,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxD,MAAM,KAAK,GAAqB;YAC9B,IAAI;YACJ,SAAS;YACT,QAAQ;YACR,YAAY,EAAE,QAAQ;SACvB,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC;QAE7B,+DAA+D;QAC/D,iEAAiE;QACjE,qDAAqD;QACrD,MAAM,cAAc,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;YAC/C,IAAI;YACJ,QAAQ;YACR,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,YAAY,EAAE,QAAQ;YACtB,kBAAkB,EAAE,YAAY;YAChC,UAAU;SACX,CAAC,CAAC;QAEH,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;YACnD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3D,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,MAAM,eAAe,GAAG,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC;QAErF,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,EAAE,EAAE,CAAC;YACvD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;YACnD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;YACpD,OAAO,mBAAmB,CAAC;QAC7B,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;QAC9D,SAAS,GAAG,eAAe,CAAC;IAC9B,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACrD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAkC;IAElC,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/B,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AAC1C,CAAC"}