@vauban-org/agent-sdk 0.16.0

package/dist/orchestration/ooda/learn.js

@@ -0,0 +1,94 @@
+/**
+ * Learning loop — shadow mode skill extraction from agent traces.
+ *
+ * Sprint-564: C2 — extractSkillFromTrace via LLM-as-optimizer.
+ *
+ * Trigger composite: toolCallCount >= 4 && roi > 0 && durationMs > 5000 && !wasReplay.
+ * NEVER inject learned skills into prod without explicit feature flag + signal stat sig.
+ * Golden fixtures snapshot tests detect drift in extraction quality.
+ *
+ * ANTI-AUDITABLE: learning loop is opt-in shadow mode only. Never active in production
+ * without explicit founder approval (CH7 Audit safe).
+ */
+/**
+ * Determine if learning should trigger for a completed cycle.
+ */
+export function shouldLearn(trigger) {
+    return (trigger.toolCallCount >= 4 &&
+        trigger.roi > 0 &&
+        trigger.durationMs > 5000 &&
+        !trigger.wasReplay);
+}
+/**
+ * Extract a skill from a completed trace. Uses LLM-as-optimizer (Claude, not GEPA Python).
+ * Returns null if extraction fails or confidence below threshold.
+ * NEVER injects into SkillLedger without feature flag gate.
+ */
+export async function extractSkillFromTrace(events, _ctx, opts) {
+    if (!opts.enabled)
+        return null;
+    if (!opts.extractor)
+        return null;
+    const traceSummary = summarizeTrace(events);
+    if (!traceSummary)
+        return null;
+    try {
+        const skill = await opts.extractor(traceSummary);
+        if (!skill)
+            return null;
+        const minConf = opts.minConfidence ?? 0.85;
+        if (skill.confidence < minConf)
+            return null;
+        // Gate: inject into SkillLedger ONLY if feature flag enabled
+        if (opts.ledger && skill.verified) {
+            opts.ledger.add?.(skill.name, {
+                description: skill.description,
+                chainOfThought: skill.chainOfThought,
+                source: "learning-loop",
+                confidence: skill.confidence,
+            });
+        }
+        return skill;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Summarize a trace into a compact text representation for the LLM extractor.
+ */
+function summarizeTrace(events) {
+    const phaseStarts = events.filter((e) => e.type === "phase_start");
+    const phaseCompletes = events.filter((e) => e.type === "phase_complete");
+    const cycleComplete = events.find((e) => e.type === "cycle_complete");
+    if (phaseStarts.length === 0)
+        return null;
+    const lines = ["Trace summary:"];
+    for (let i = 0; i < phaseStarts.length; i++) {
+        const start = phaseStarts[i];
+        const complete = phaseCompletes.find((e) => "phase" in e && e.phase === ("phase" in start ? start.phase : ""));
+        lines.push(`  ${i + 1}. ${"phase" in start ? start.phase : "unknown"}${complete ? ` (${"durationMs" in complete ? complete.durationMs : "?"}ms)` : ""}`);
+    }
+    if (cycleComplete && "status" in cycleComplete) {
+        lines.push(`Status: ${cycleComplete.status}`);
+        if ("durationMs" in cycleComplete) {
+            lines.push(`Total duration: ${cycleComplete.durationMs}ms`);
+        }
+    }
+    return lines.join("\n");
+}
+// ─── Golden fixtures ─────────────────────────────────────────────────────────
+export const GOLDEN_FIXTURES = [
+    {
+        trace: `Trace summary:
+  1. observe (50ms)
+  2. orient (200ms)
+  3. decide (100ms)
+  4. act (150ms)
+  5. feedback (80ms)
+Status: succeeded
+Total duration: 580ms`,
+        expectedSkillName: "expense_classification",
+    },
+];
+//# sourceMappingURL=learn.js.map

package/dist/orchestration/ooda/learn.js.map

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

package/dist/orchestration/ooda/multimodal.d.ts

@@ -0,0 +1,91 @@
+/**
+ * MultiModalObservation — sprint-525:quick-6
+ *
+ * Typed container for observations that include non-text content (image, audio,
+ * document).  The ORIENT phase detects multimodal observations via `isMultiModal`
+ * and converts them to the Anthropic Messages API content-block format so Claude
+ * Opus 4 can process vision/audio inputs natively.
+ *
+ * Anthropic Messages API reference:
+ * https://docs.anthropic.com/api/messages
+ *
+ * @public
+ */
+/**
+ * A base64-encoded image source (jpg / png / gif / webp) or an external URL.
+ * Matches the Anthropic `image` content block `source` field.
+ */
+export type ImageMediaType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+/**
+ * Audio media types supported by Claude's audio input capability.
+ */
+export type AudioMediaType = "audio/ogg" | "audio/wav" | "audio/mp3" | "audio/mpeg" | "audio/webm";
+/**
+ * A multimodal observation may carry text alongside any combination of image,
+ * audio, and document inputs.  All non-text fields are optional; at least one
+ * must be present for `isMultiModal` to return `true`.
+ */
+export interface MultiModalObservation {
+    /** Plain-text portion of the observation (always included when available). */
+    text?: string;
+    /** Base64-encoded image (jpg / png / gif / webp). */
+    imageBase64?: string;
+    /** MIME type for `imageBase64`. Defaults to `image/jpeg` if absent. */
+    imageMediaType?: ImageMediaType;
+    /** Base64-encoded audio clip (ogg / wav / mp3 / webm). */
+    audioBase64?: string;
+    /** MIME type for `audioBase64`. Defaults to `audio/ogg` if absent. */
+    audioMediaType?: AudioMediaType;
+    /** Publicly accessible URL to a PDF document. */
+    documentUrl?: string;
+}
+/** Plain-text content block. */
+export interface AnthropicTextBlock {
+    type: "text";
+    text: string;
+}
+/** Base64 image content block (Messages API). */
+export interface AnthropicImageBlock {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: ImageMediaType;
+        data: string;
+    };
+}
+/** URL-referenced document content block (Messages API). */
+export interface AnthropicDocumentBlock {
+    type: "document";
+    source: {
+        type: "url";
+        url: string;
+    };
+}
+/** Discriminated union of all supported Anthropic content blocks. */
+export type AnthropicContentBlock = AnthropicTextBlock | AnthropicImageBlock | AnthropicDocumentBlock;
+/**
+ * Returns `true` when the observation contains at least one non-text channel
+ * (image, audio, or document).
+ *
+ * The ORIENT phase calls this before deciding whether to use a vision-capable
+ * model.  Text-only observations short-circuit to a lightweight completion.
+ */
+export declare function isMultiModal(obs: unknown): obs is MultiModalObservation;
+/**
+ * Maps a `MultiModalObservation` to an ordered array of Anthropic Messages API
+ * content blocks suitable for inclusion in a `messages[].content` array.
+ *
+ * Ordering (Anthropic recommends text first, then media):
+ *   1. `text` → `TextBlock`
+ *   2. `imageBase64` → `ImageBlock` (base64 source)
+ *   3. `documentUrl` → `DocumentBlock` (URL source)
+ *
+ * Audio note: the Anthropic Messages API does not yet expose a first-class
+ * audio content block in the public spec (as of April 2026).  Audio is
+ * surfaced as a text block carrying a data-URI so callers can substitute their
+ * own handler when native audio support ships.
+ *
+ * @throws {TypeError} when `obs` carries neither text nor any media field.
+ */
+export declare function multiModalToAnthropicContent(obs: MultiModalObservation): AnthropicContentBlock[];
+//# sourceMappingURL=multimodal.d.ts.map

package/dist/orchestration/ooda/multimodal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multimodal.d.ts","sourceRoot":"","sources":["../../../src/orchestration/ooda/multimodal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAEnG;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,cAAc,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE;QACN,IAAI,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH;AAED,qEAAqE;AACrE,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,mBAAmB,GACnB,sBAAsB,CAAC;AAM3B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,qBAAqB,CAMvE;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,qBAAqB,GACzB,qBAAqB,EAAE,CA+CzB"}

package/dist/orchestration/ooda/multimodal.js

@@ -0,0 +1,88 @@
+/**
+ * MultiModalObservation — sprint-525:quick-6
+ *
+ * Typed container for observations that include non-text content (image, audio,
+ * document).  The ORIENT phase detects multimodal observations via `isMultiModal`
+ * and converts them to the Anthropic Messages API content-block format so Claude
+ * Opus 4 can process vision/audio inputs natively.
+ *
+ * Anthropic Messages API reference:
+ * https://docs.anthropic.com/api/messages
+ *
+ * @public
+ */
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` when the observation contains at least one non-text channel
+ * (image, audio, or document).
+ *
+ * The ORIENT phase calls this before deciding whether to use a vision-capable
+ * model.  Text-only observations short-circuit to a lightweight completion.
+ */
+export function isMultiModal(obs) {
+    return (typeof obs === "object" &&
+        obs !== null &&
+        ("imageBase64" in obs || "audioBase64" in obs || "documentUrl" in obs));
+}
+// ---------------------------------------------------------------------------
+// Conversion
+// ---------------------------------------------------------------------------
+/**
+ * Maps a `MultiModalObservation` to an ordered array of Anthropic Messages API
+ * content blocks suitable for inclusion in a `messages[].content` array.
+ *
+ * Ordering (Anthropic recommends text first, then media):
+ *   1. `text` → `TextBlock`
+ *   2. `imageBase64` → `ImageBlock` (base64 source)
+ *   3. `documentUrl` → `DocumentBlock` (URL source)
+ *
+ * Audio note: the Anthropic Messages API does not yet expose a first-class
+ * audio content block in the public spec (as of April 2026).  Audio is
+ * surfaced as a text block carrying a data-URI so callers can substitute their
+ * own handler when native audio support ships.
+ *
+ * @throws {TypeError} when `obs` carries neither text nor any media field.
+ */
+export function multiModalToAnthropicContent(obs) {
+    const blocks = [];
+    // 1. Text block (always first)
+    if (obs.text !== undefined && obs.text.length > 0) {
+        blocks.push({ type: "text", text: obs.text });
+    }
+    // 2. Image block
+    if (obs.imageBase64 !== undefined) {
+        blocks.push({
+            type: "image",
+            source: {
+                type: "base64",
+                media_type: obs.imageMediaType ?? "image/jpeg",
+                data: obs.imageBase64,
+            },
+        });
+    }
+    // 3. Audio — surfaced as text data-URI pending native API support
+    if (obs.audioBase64 !== undefined) {
+        const mimeType = obs.audioMediaType ?? "audio/ogg";
+        blocks.push({
+            type: "text",
+            text: `data:${mimeType};base64,${obs.audioBase64}`,
+        });
+    }
+    // 4. Document block (URL source)
+    if (obs.documentUrl !== undefined) {
+        blocks.push({
+            type: "document",
+            source: {
+                type: "url",
+                url: obs.documentUrl,
+            },
+        });
+    }
+    if (blocks.length === 0) {
+        throw new TypeError("MultiModalObservation must carry at least one non-empty field (text, imageBase64, audioBase64, or documentUrl)");
+    }
+    return blocks;
+}
+//# sourceMappingURL=multimodal.js.map

package/dist/orchestration/ooda/multimodal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multimodal.js","sourceRoot":"","sources":["../../../src/orchestration/ooda/multimodal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyEH,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,CAAC,aAAa,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC,CACvE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,4BAA4B,CAC1C,GAA0B;IAE1B,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,+BAA+B;IAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,iBAAiB;IACjB,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,OAAO;YACb,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,GAAG,CAAC,cAAc,IAAI,YAAY;gBAC9C,IAAI,EAAE,GAAG,CAAC,WAAW;aACtB;SACF,CAAC,CAAC;IACL,CAAC;IAED,kEAAkE;IAClE,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAmB,GAAG,CAAC,cAAc,IAAI,WAAW,CAAC;QACnE,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ,QAAQ,WAAW,GAAG,CAAC,WAAW,EAAE;SACnD,CAAC,CAAC;IACL,CAAC;IAED,iCAAiC;IACjC,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE;gBACN,IAAI,EAAE,KAAK;gBACX,GAAG,EAAE,GAAG,CAAC,WAAW;aACrB;SACF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CACjB,gHAAgH,CACjH,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/orchestration/ooda/phase-routing.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Phase-level model routing — per-phase model selection with fallback cascade.
+ *
+ * Sprint-563: B4 — PhaseModelConfig + ModelSpec.fallback + resolveForPhase.
+ *
+ * Each OODA phase can specify its own model, independent of other phases.
+ * When a provider fails (429/503), the fallback cascade tries the next model.
+ * resolveForPhase(phaseModels, phase) returns the resolved ModelSpec.
+ */
+import type { OODAPhaseKind } from "./types.js";
+export interface ModelSpec {
+    /** Provider identifier (e.g. "anthropic", "groq", "litellm"). */
+    provider: string;
+    /** Model name (e.g. "claude-sonnet-4-6", "llama-3.3-70b"). */
+    model: string;
+    /** Fallback cascade — tried in order on failure. */
+    fallback?: ModelSpec[];
+    /** Whether to track cost for this spec (default true). */
+    costTracking?: boolean;
+    /** Temperature override for this model. */
+    temperature?: number;
+    /** Top-p override for this model. */
+    topP?: number;
+}
+export interface PhaseModelConfig {
+    /** Per-phase model mapping. Undefined phases use the default model. */
+    phases: Partial<Record<OODAPhaseKind, ModelSpec>>;
+    /** Default model for phases without explicit config. */
+    defaultModel: ModelSpec;
+}
+/**
+ * Resolve the ModelSpec for a given phase. Falls back to defaultModel if
+ * the phase has no explicit config.
+ */
+export declare function resolveForPhase(config: PhaseModelConfig, phase: OODAPhaseKind): ModelSpec;
+/**
+ * Get the full fallback chain for a phase — the primary model first,
+ * then its fallback cascade, then defaultModel + its cascade.
+ */
+export declare function getFallbackChain(config: PhaseModelConfig, phase: OODAPhaseKind): ModelSpec[];
+//# sourceMappingURL=phase-routing.d.ts.map

package/dist/orchestration/ooda/phase-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-routing.d.ts","sourceRoot":"","sources":["../../../src/orchestration/ooda/phase-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC;IAClD,wDAAwD;IACxD,YAAY,EAAE,SAAS,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,aAAa,GACnB,SAAS,CAEX;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,aAAa,GACnB,SAAS,EAAE,CAqBb"}

package/dist/orchestration/ooda/phase-routing.js

@@ -0,0 +1,43 @@
+/**
+ * Phase-level model routing — per-phase model selection with fallback cascade.
+ *
+ * Sprint-563: B4 — PhaseModelConfig + ModelSpec.fallback + resolveForPhase.
+ *
+ * Each OODA phase can specify its own model, independent of other phases.
+ * When a provider fails (429/503), the fallback cascade tries the next model.
+ * resolveForPhase(phaseModels, phase) returns the resolved ModelSpec.
+ */
+/**
+ * Resolve the ModelSpec for a given phase. Falls back to defaultModel if
+ * the phase has no explicit config.
+ */
+export function resolveForPhase(config, phase) {
+    return config.phases[phase] ?? config.defaultModel;
+}
+/**
+ * Get the full fallback chain for a phase — the primary model first,
+ * then its fallback cascade, then defaultModel + its cascade.
+ */
+export function getFallbackChain(config, phase) {
+    const primary = config.phases[phase];
+    const chain = [];
+    if (primary) {
+        chain.push(primary);
+        if (primary.fallback)
+            chain.push(...primary.fallback);
+    }
+    // Always append default as last resort
+    chain.push(config.defaultModel);
+    if (config.defaultModel.fallback)
+        chain.push(...config.defaultModel.fallback);
+    // Deduplicate by provider+model
+    const seen = new Set();
+    return chain.filter((spec) => {
+        const key = `${spec.provider}:${spec.model}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+//# sourceMappingURL=phase-routing.js.map

package/dist/orchestration/ooda/phase-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-routing.js","sourceRoot":"","sources":["../../../src/orchestration/ooda/phase-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0BH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAwB,EACxB,KAAoB;IAEpB,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAwB,EACxB,KAAoB;IAEpB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,KAAK,GAAgB,EAAE,CAAC;IAE9B,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,OAAO,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,uCAAuC;IACvC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,YAAY,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAE9E,gCAAgC;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC3B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/orchestration/ooda/plan-execute.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Plan-and-Execute pattern — decompose a task in `decide`, execute step by step in `act`.
+ *
+ * decomposeTask() converts an orient output into a sequence of ordered steps.
+ * executeStep() runs one step with tool access, producing a step result.
+ *
+ * @public
+ */
+export interface PlanStep {
+    /** Step index (0-based). */
+    index: number;
+    /** Human-readable step description. */
+    description: string;
+    /** Tool expected to be used (optional hint). */
+    tool?: string;
+    /** Step-specific parameters. */
+    params?: Record<string, unknown>;
+}
+export interface Plan {
+    /** Overall goal. */
+    goal: string;
+    /** Ordered execution steps. */
+    steps: PlanStep[];
+    /** Estimated total cost in tokens. */
+    estimatedTokens?: number;
+}
+export interface StepResult {
+    stepIndex: number;
+    status: "completed" | "failed" | "skipped";
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+}
+export interface PlanExecutionResult {
+    plan: Plan;
+    results: StepResult[];
+    completedSteps: number;
+    failedSteps: number;
+    totalDurationMs: number;
+}
+/**
+ * Convert a task description into a structured plan.
+ *
+ * The `decomposer` function is an LLM call that takes a task description
+ * and returns a Plan with ordered steps. Implementations should use
+ * structured output (Zod schema) for reliable parsing.
+ */
+export declare function decomposeTask(task: string, decomposer: (task: string) => Promise<Plan>): Promise<Plan>;
+/**
+ * Execute a single plan step.
+ *
+ * Returns a StepResult with status, output, and timing.
+ */
+export declare function executeStep(step: PlanStep, executor: (step: PlanStep) => Promise<unknown>): Promise<StepResult>;
+//# sourceMappingURL=plan-execute.d.ts.map

package/dist/orchestration/ooda/plan-execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-execute.d.ts","sourceRoot":"","sources":["../../../src/orchestration/ooda/plan-execute.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,QAAQ;IACvB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,IAAI;IACnB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAID;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAC1C,OAAO,CAAC,IAAI,CAAC,CAEf;AAID;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GAC7C,OAAO,CAAC,UAAU,CAAC,CAarB"}

package/dist/orchestration/ooda/plan-execute.js

@@ -0,0 +1,41 @@
+/**
+ * Plan-and-Execute pattern — decompose a task in `decide`, execute step by step in `act`.
+ *
+ * decomposeTask() converts an orient output into a sequence of ordered steps.
+ * executeStep() runs one step with tool access, producing a step result.
+ *
+ * @public
+ */
+// ─── Decompose ──────────────────────────────────────────────────────────────────
+/**
+ * Convert a task description into a structured plan.
+ *
+ * The `decomposer` function is an LLM call that takes a task description
+ * and returns a Plan with ordered steps. Implementations should use
+ * structured output (Zod schema) for reliable parsing.
+ */
+export async function decomposeTask(task, decomposer) {
+    return decomposer(task);
+}
+// ─── Execute ────────────────────────────────────────────────────────────────────
+/**
+ * Execute a single plan step.
+ *
+ * Returns a StepResult with status, output, and timing.
+ */
+export async function executeStep(step, executor) {
+    const start = Date.now();
+    try {
+        const output = await executor(step);
+        return { stepIndex: step.index, status: "completed", output, durationMs: Date.now() - start };
+    }
+    catch (err) {
+        return {
+            stepIndex: step.index,
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            durationMs: Date.now() - start,
+        };
+    }
+}
+//# sourceMappingURL=plan-execute.js.map

package/dist/orchestration/ooda/plan-execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-execute.js","sourceRoot":"","sources":["../../../src/orchestration/ooda/plan-execute.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwCH,mFAAmF;AAEnF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,UAA2C;IAE3C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,mFAAmF;AAEnF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAc,EACd,QAA8C;IAE9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IAChG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,KAAK;YACrB,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YACvD,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;SAC/B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/orchestration/ooda/react-loop.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ReactLoop — Reason + Act tool-calling loop for the act phase.
+ *
+ * Thought → Action → Observation loop with maxStep guard. Model-agnostic:
+ * accepts an `LLMCompletionFn` that decouples from any specific provider.
+ *
+ * Used within the `act` phase of an OODA cycle when the agent needs multi-step
+ * reasoning with tool calls (ReAct pattern).
+ *
+ * Loop stops on:
+ *   - Final answer (no tool call in response)
+ *   - maxSteps reached
+ *   - LLM error
+ *   - AbortSignal fired
+ *
+ * @public
+ */
+export interface ToolCall {
+    /** Tool name. */
+    tool: string;
+    /** Tool arguments — arbitrary JSON-serializable value. */
+    args: Record<string, unknown>;
+}
+export interface ReactStep {
+    /** Step index (0-based). */
+    index: number;
+    /** The LLM's reasoning / thought before the tool call. */
+    thought: string;
+    /** The tool call extracted from the LLM response, if any. */
+    action?: ToolCall;
+    /** The result of executing the tool, if a tool was called. */
+    observation?: string;
+    /** Error message if the tool call failed. */
+    error?: string;
+}
+export interface ReactResult {
+    /** Final answer from the LLM. */
+    answer: string;
+    /** All steps taken during the loop. */
+    steps: ReactStep[];
+    /** Total steps executed. */
+    totalSteps: number;
+    /** Whether the loop was stopped by maxSteps. */
+    truncated: boolean;
+}
+/**
+ * LLM completion function — model-agnostic interface.
+ *
+ * Accepts a list of messages and returns the LLM's response text.
+ * Tool calls are parsed from the response text (JSON blocks or structured
+ * API tool calls — implementation decides).
+ */
+export type LLMCompletionFn = (messages: ReactMessage[]) => Promise<LLMReactResponse>;
+export interface ReactMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    /** Tool call ID (for 'tool' role messages). */
+    tool_call_id?: string;
+    /** Tool name (for 'assistant' messages with tool calls). */
+    name?: string;
+}
+export interface LLMReactResponse {
+    /** The full response text. */
+    content: string;
+    /** Parsed tool calls, if any. */
+    toolCalls?: ToolCall[];
+    /** Whether this is a final answer (no tool calls). */
+    isFinal: boolean;
+}
+export interface ReactLoopOptions {
+    /** Max steps before forced stop (default: 10). */
+    maxSteps?: number;
+    /** System prompt for the LLM. */
+    systemPrompt: string;
+    /** Initial user message / task description. */
+    task: string;
+    /** LLM completion function. */
+    llm: LLMCompletionFn;
+    /** Execute a tool call and return the result. */
+    executeTool: (call: ToolCall) => Promise<string>;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+    /** 10KB limit on parsed tool call JSON to prevent DoS. */
+    maxToolCallSize?: number;
+    /** Allowed tool names. Unlisted tools get an error feedback. */
+    allowedTools?: string[];
+}
+/**
+ * Run a ReAct (Reasoning + Acting) loop.
+ *
+ * ```
+ * Thought → Action → Observation → Thought → ... → Final Answer
+ * ```
+ */
+export declare function reactLoop(opts: ReactLoopOptions): Promise<ReactResult>;
+//# sourceMappingURL=react-loop.d.ts.map

package/dist/orchestration/ooda/react-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-loop.d.ts","sourceRoot":"","sources":["../../../src/orchestration/ooda/react-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,QAAQ;IACvB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,QAAQ,EAAE,YAAY,EAAE,KACrB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,eAAe,CAAC;IACrB,iDAAiD;IACjD,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AASD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CA8E5E"}