@vauban-org/agent-sdk 0.16.0

package/dist/orchestration/ooda/structured-output.d.ts

@@ -0,0 +1,46 @@
+/**
+ * withStructuredOutput<T>() — Zod schema-enforced LLM output with auto-retry.
+ *
+ * Sprint-562: A5 — Structured Output
+ *
+ * Zod validation failures are injected into the messages[] thread so the LLM
+ * sees its mistake and corrects it on the next attempt. TInput is NEVER mutated
+ * (new messages are appended to a copy).
+ *
+ * Each retry produces a TraceStep with type='llm_call' and output.zodError
+ * so auditors can see the correction path.
+ */
+import type { ZodSchema, ZodError } from "zod";
+import type { OODAContext } from "./types.js";
+export interface StructuredOutputOptions<T> {
+    /** Zod schema to validate against. */
+    schema: ZodSchema<T>;
+    /** LLM call function that returns a raw string. */
+    fn: (input: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+    }, ctx: OODAContext) => Promise<string>;
+    /** Max Zod retries before throwing (default 2). */
+    maxRetries?: number;
+}
+export interface StructuredOutputResult<T> {
+    parsed: T;
+    rawMessages: Array<{
+        role: string;
+        content: string;
+    }>;
+    retries: number;
+}
+export declare class StructuredOutputError extends Error {
+    readonly zodError: ZodError;
+    constructor(message: string, zodError: ZodError);
+}
+/**
+ * Calls an LLM with Zod schema enforcement. On Zod failure, injects the
+ * error into the messages thread and retries. TInput messages are never
+ * mutated — each retry appends to a copy.
+ */
+export declare function withStructuredOutput<T>(opts: StructuredOutputOptions<T>): Promise<StructuredOutputResult<T>>;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/orchestration/ooda/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../../../src/orchestration/ooda/structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,sCAAsC;IACtC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACrB,mDAAmD;IACnD,EAAE,EAAE,CACF,KAAK,EAAE;QAAE,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,EAC7D,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,QAAQ,EAAE,QAAQ;gBADlC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,QAAQ;CAKrC;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAyCpC"}

package/dist/orchestration/ooda/structured-output.js

@@ -0,0 +1,60 @@
+/**
+ * withStructuredOutput<T>() — Zod schema-enforced LLM output with auto-retry.
+ *
+ * Sprint-562: A5 — Structured Output
+ *
+ * Zod validation failures are injected into the messages[] thread so the LLM
+ * sees its mistake and corrects it on the next attempt. TInput is NEVER mutated
+ * (new messages are appended to a copy).
+ *
+ * Each retry produces a TraceStep with type='llm_call' and output.zodError
+ * so auditors can see the correction path.
+ */
+export class StructuredOutputError extends Error {
+    zodError;
+    constructor(message, zodError) {
+        super(message);
+        this.zodError = zodError;
+        this.name = "StructuredOutputError";
+    }
+}
+/**
+ * Calls an LLM with Zod schema enforcement. On Zod failure, injects the
+ * error into the messages thread and retries. TInput messages are never
+ * mutated — each retry appends to a copy.
+ */
+export async function withStructuredOutput(opts) {
+    const maxRetries = opts.maxRetries ?? 2;
+    const rawMessages = [];
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const messages = [...rawMessages];
+        const raw = await opts.fn({ messages }, undefined);
+        rawMessages.push({ role: "assistant", content: raw });
+        // Try to extract JSON from the response
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            const fixPrompt = `Your previous response was not valid JSON. Please respond ONLY with a valid JSON object matching the schema.`;
+            rawMessages.push({ role: "user", content: fixPrompt });
+            continue;
+        }
+        const result = opts.schema.safeParse(parsed);
+        if (result.success) {
+            return { parsed: result.data, rawMessages, retries: attempt };
+        }
+        if (attempt < maxRetries) {
+            const fixPrompt = `Your response failed Zod validation:\n${result.error.message}\n\nPlease fix the errors and return a valid JSON object.`;
+            rawMessages.push({ role: "user", content: fixPrompt });
+        }
+        else {
+            throw new StructuredOutputError(`Structured output validation failed after ${maxRetries} retries`, result.error);
+        }
+    }
+    // Unreachable — but TypeScript needs it
+    throw new StructuredOutputError(`Structured output exhausted ${maxRetries} retries`, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    { issues: [] });
+}
+//# sourceMappingURL=structured-output.js.map

package/dist/orchestration/ooda/structured-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.js","sourceRoot":"","sources":["../../../src/orchestration/ooda/structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAG5B;IAFlB,YACE,OAAe,EACC,QAAkB;QAElC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,aAAQ,GAAR,QAAQ,CAAU;QAGlC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAgC;IAEhC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IACxC,MAAM,WAAW,GAA6C,EAAE,CAAC;IAEjE,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,SAAmC,CAAC,CAAC;QAC7E,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QAEtD,wCAAwC;QACxC,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,SAAS,GAAG,8GAA8G,CAAC;YACjI,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;YACvD,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAChE,CAAC;QAED,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;YACzB,MAAM,SAAS,GAAG,yCAAyC,MAAM,CAAC,KAAK,CAAC,OAAO,2DAA2D,CAAC;YAC3I,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACzD,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,qBAAqB,CAC7B,6CAA6C,UAAU,UAAU,EACjE,MAAM,CAAC,KAAK,CACb,CAAC;QACJ,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,MAAM,IAAI,qBAAqB,CAC7B,+BAA+B,UAAU,UAAU;IACnD,8DAA8D;IAC9D,EAAE,MAAM,EAAE,EAAE,EAAqB,CAClC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,463 @@
+/**
+ * OODA Orchestration — Public Types (sprint-525:quick-1 foundation).
+ *
+ * The OODA primitive is the single, opinionated agent lifecycle for CC v2:
+ *   observe → orient → decide → act → feedback
+ *
+ * 10 anti-patterns are enforced **by-design** through the API surface and
+ * runtime validation in `OODAAgentImpl`:
+ *
+ *   1. Sequential `while + sleep` cycle loop — never `setInterval`.
+ *   2. Each phase persists `pending` → `done` via `insertStep` + `completeStep`.
+ *   3. Optional `hitlGate` on `act` — gates execution until human approval.
+ *   4. Risk guards have NO TTL bypass — each cycle re-checks.
+ *   5. Session guards checked once per cycle; cycle SKIPPED if any false.
+ *   6. `executionMode` is REQUIRED at construction — no implicit default.
+ *   7. `observe` and `orient` MUST be `readOnly: true`.
+ *   8. On any guard tripped, the cycle aborts cleanly — no LLM/skill calls.
+ *   9. Resource limits (`phaseTimeoutMs`, `maxStepsPerCycle`, `maxHeapMb`)
+ *      are configurable with sane defaults (60s / 200 / 256MB).
+ *  10. Heap & step usage are monitored and exceeding limits is logged + aborted.
+ *
+ * Replay safety: every `OODAContext` carries `isReplay`. Skills and phase
+ * functions MUST honor it (no observable side effects when true).
+ *
+ * Type-safe phase chaining: each phase's `TOutput` becomes the next phase's
+ * `TInput`, providing compile-time guarantees on the data flow.
+ *
+ * @public
+ */
+import type { DbClient } from "../../tracking/agent-run-tracker.js";
+import type { LoggerPort } from "../../ports/logger.js";
+import type { SkillRegistry } from "./skills.js";
+import type { AgentConfigLoader } from "./agent-config-loader.js";
+import type { TimestampPort } from "../../ports/timestamp.js";
+import type { ReceiptQueue } from "../../proof/receipt-queue.js";
+import type { KeyProvider } from "../../ports/key-provider.js";
+import type { LLMProviderPort } from "../../ports/llm-provider.js";
+import type { EventBusPort } from "../../ports/event-bus.js";
+import type { HITLPort } from "../../ports/hitl.js";
+import type { MessagingChannelPort } from "../../ports/messaging.js";
+import type { BrainPort } from "../../ports/brain.js";
+import type { AgentRegistryPort } from "../../ports/agent-registry.js";
+/**
+ * OODA dependency bundle — BYOM (Bring Your Own Model) injection contract.
+ *
+ * Plan v6 §3.7: all port dependencies are injected at construction, never
+ * resolved internally. Enables BYOM adapters, testability, and isolation.
+ *
+ * In SDK 0.17: `deps` is optional for backward compat with legacy configs.
+ * In SDK 1.0: `deps` will be required and `deps.llm` must be present.
+ *
+ * Strict mode (default): `SDK_STRICT_DEPS !== "false"` → throws
+ * `MissingDependencyError` if `deps.llm` is absent at boot.
+ *
+ * @public
+ */
+export interface OODAAgentDeps {
+    /** REQUIRED in strict mode. The LLM provider used by phases for completions. */
+    llm: LLMProviderPort;
+    /** Optional. Event bus for inter-agent and cross-product events (ADR-ECO-017). Will be required in 1.0. */
+    eventBus?: EventBusPort;
+    /** Optional. Human-in-the-loop state machine. Will be required in 1.0. */
+    hitl?: HITLPort;
+    /** Optional. Messaging channels (Slack, Telegram, Discord, Console, MCP). */
+    messaging?: MessagingChannelPort;
+    /** Optional. Brain memory tiers (working, episodic, semantic, procedural). */
+    memory?: BrainPort;
+    /** Optional. Agent discovery registry. */
+    registry?: AgentRegistryPort;
+}
+/**
+ * The five OODA phase kinds. Mirrors the four `RunStep.type` values in
+ * `proof/types.ts` plus the `observation` legacy variant — kept aligned so
+ * step rows persisted through `OODAContext.insertStep` flow cleanly into
+ * the proof certificate pipeline.
+ */
+export type OODAPhaseKind = "retrieval" | "decision" | "execution" | "feedback" | "observation";
+/**
+ * Execution mode — REQUIRED at construction. Anti-pattern #6: no default.
+ *
+ * - `dry-run`: phases run, skills consult `dryRunMocks`, no production
+ *   side-effects (no Brain writes, no on-chain tx, no Slack live).
+ * - `live`: full production execution.
+ */
+export type ExecutionMode = "dry-run" | "live";
+/**
+ * OODAContext — passed to every phase function and every skill invocation.
+ *
+ * Strictly read-only (`readonly` on all fields) so phase functions cannot
+ * mutate it. Mutation helpers (`insertStep`, `completeStep`, `errorStep`,
+ * `notifySlack`) are the ONLY sanctioned side-effect path.
+ *
+ * `isReplay` flag enables replay-safe execution: skills/phases MUST
+ * short-circuit observable side-effects when true.
+ */
+export interface OODAContext<TConfig = unknown> {
+    readonly agentId: string;
+    readonly runId: string;
+    /** Zero-indexed cycle counter (0 for first cycle of a `start()` session). */
+    readonly cycleIndex: number;
+    readonly executionMode: ExecutionMode;
+    readonly isReplay: boolean;
+    readonly config: TConfig;
+    /**
+     * Optional hot-reload config loader. When present, `OODAAgentImpl` calls
+     * `configLoader.get(agentId)` at the start of each cycle and surfaces the
+     * result as `ctx.config` for that cycle. Change config in DB → next cycle
+     * after TTL expiry picks it up without restart.
+     */
+    readonly configLoader?: AgentConfigLoader<TConfig>;
+    readonly db: DbClient;
+    readonly skills: SkillRegistry;
+    readonly logger: LoggerPort;
+    /**
+     * Injected dependencies (BYOM — plan v6 §3.7).
+     * Phases access ports via `ctx.deps.llm.complete(...)` etc.
+     * Empty object `{}` in legacy mode (when `config.deps` is absent).
+     */
+    readonly deps: Partial<OODAAgentDeps>;
+    /** Persist a `pending` step row — anti-pattern #2 first half. */
+    readonly insertStep: (input: {
+        type: OODAPhaseKind;
+        phase: string;
+        payload?: Record<string, unknown>;
+    }) => Promise<{
+        stepId: string;
+    }>;
+    /** Mark a step `done` and emit `leafHash` — anti-pattern #2 second half. */
+    readonly completeStep: (stepId: string, payload: Record<string, unknown>) => Promise<{
+        leafHash: string;
+    }>;
+    /** Mark a step `error` (no leaf hash). */
+    readonly errorStep: (stepId: string, error: Error) => Promise<void>;
+    /** Routed Slack notification (no-op in dry-run / replay). */
+    readonly notifySlack: (channel: string, text: string) => Promise<void>;
+}
+/**
+ * PhaseDef — pure(ish) function from `TInput` to `TOutput` plus metadata.
+ *
+ * Constructor enforces `readOnly: true` on `observe` and `orient` phases.
+ * The `hitlGate` flag is only meaningful on `act`; ignored elsewhere.
+ */
+export interface PhaseDef<TInput, TOutput> {
+    readonly type: OODAPhaseKind;
+    /** When true, phase is forbidden to call mutation helpers / live skills. */
+    readonly readOnly?: boolean;
+    /** Only respected on `act`. When true, awaits HITL approval. */
+    readonly hitlGate?: boolean;
+    readonly fn: (input: TInput, ctx: OODAContext) => Promise<TOutput>;
+}
+/**
+ * SessionGuard — gates whether a cycle should run at all (e.g. market
+ * sessions, business hours). `isActive(now)` returning false → cycle skipped.
+ */
+export interface SessionGuard {
+    readonly name: string;
+    isActive(at: Date): Promise<boolean>;
+}
+/**
+ * RiskGuard — per-cycle adversarial check (e.g. circuit breaker tripped,
+ * KYC stale, budget exhausted). `proceed: false` → cycle skipped.
+ *
+ * Anti-pattern #4: NO TTL bypass — guards are consulted on EVERY cycle.
+ */
+export interface RiskGuard {
+    readonly name: string;
+    check(ctx: OODAContext): Promise<{
+        proceed: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * OutcomeRecord — optional output of `outcomeMapping(feedback)`. Persisted
+ * as an outcome row attributable to this run.
+ */
+export interface OutcomeRecord {
+    readonly outcome_type: string;
+    readonly value_cents: number;
+    /** Confidence score (0.0 - 1.0). EconomicObserver weights ROI by confidence. */
+    readonly confidence?: number;
+    readonly is_pending_backfill?: boolean;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Resource limits — anti-pattern #9 + #10. Defaults applied when omitted.
+ */
+export interface ResourceLimits {
+    /** Per-phase wall-clock timeout. Default: 60_000 ms. */
+    readonly phaseTimeoutMs?: number;
+    /** Hard cap on `insertStep` calls per cycle. Default: 200. */
+    readonly maxStepsPerCycle?: number;
+    /** Soft heap watermark — log+abort if exceeded. Default: 256 MB. */
+    readonly maxHeapMb?: number;
+}
+/**
+ * Default resource limits — exported for tests and host wiring.
+ */
+export declare const DEFAULT_RESOURCE_LIMITS: Required<ResourceLimits>;
+/**
+ * Full configuration for an OODA agent. Type parameters chain phase
+ * input/output to enforce compile-time data flow correctness.
+ */
+export interface OODAAgentConfig<TConfig = unknown, TObs = unknown, TOrient = unknown, TDecision = unknown, TAction = unknown, TFeedback = unknown> {
+    readonly agentId: string;
+    /** Agent version string for OTel spans. Defaults to "0.0.0" if omitted. */
+    readonly agentVersion?: string;
+    /** Cycle interval (ms). Sequential `while+sleep` loop. */
+    readonly intervalMs: number;
+    /** REQUIRED. Anti-pattern #6 — no implicit default. */
+    readonly executionMode: ExecutionMode;
+    readonly config?: TConfig;
+    /**
+     * Optional hot-reload config loader. When provided, each cycle refreshes
+     * `ctx.config` by calling `configLoader.get(agentId)` before phase
+     * execution. Static `config` above serves as the initial/fallback value.
+     */
+    readonly configLoader?: AgentConfigLoader<TConfig>;
+    readonly db: DbClient;
+    readonly logger: LoggerPort;
+    readonly skills?: SkillRegistry;
+    /**
+     * Port dependencies injected at boot (BYOM — plan v6 §3.7).
+     *
+     * Optional in SDK 0.17 for backward compatibility.
+     * Will be required in SDK 1.0.
+     *
+     * When `SDK_STRICT_DEPS !== "false"` (default), boot validation throws
+     * `MissingDependencyError` if this field is absent or `deps.llm` is missing.
+     *
+     * @deprecated Omitting `deps` is supported only in legacy mode. Will be required in 1.0.
+     */
+    readonly deps?: OODAAgentDeps;
+    readonly phases: {
+        readonly observe: PhaseDef<void, TObs>;
+        readonly orient: PhaseDef<TObs, TOrient>;
+        readonly decide: PhaseDef<TOrient, TDecision>;
+        readonly act: PhaseDef<TDecision, TAction>;
+        /**
+         * Optional 6th phase — self-critique between act and feedback.
+         *
+         * Receives `{ action, decision }` and produces a self-critique.
+         * Rule-based agents skip this phase. When omitted, the OODA loop
+         * moves directly from act to feedback with no reflection.
+         */
+        readonly reflect?: PhaseDef<TAction & {
+            decision: TDecision;
+        }, TFeedback>;
+        readonly feedback: PhaseDef<TAction, TFeedback>;
+    };
+    readonly sessionGuards?: readonly SessionGuard[];
+    readonly riskGuards?: readonly RiskGuard[];
+    readonly outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+    readonly resourceLimits?: ResourceLimits;
+    /** Side-effecting helpers injected by host. */
+    readonly insertStepImpl?: OODAContext["insertStep"];
+    readonly completeStepImpl?: OODAContext["completeStep"];
+    readonly errorStepImpl?: OODAContext["errorStep"];
+    readonly notifySlackImpl?: OODAContext["notifySlack"];
+    /**
+     * Optional HITL gate awaiter. Called when `act` phase has
+     * `hitlGate: true`. Resolves when human approves; rejects to abort.
+     */
+    readonly waitForHITL?: (ctx: {
+        runId: string;
+        stepId: string;
+        payload: unknown;
+    }) => Promise<void>;
+    /**
+     * Optional TSA timestamping configuration (A4 — sprint-561).
+     *
+     * When `when` is `'on-cycle-complete'`, the agent calls `port.request(rootHash)`
+     * after each successful cycle. On TSA failure, a `timestamp_pending` event is
+     * emitted and — if `queue` is configured — the entry is added to the queue for
+     * later retry.
+     *
+     * When `when` is `'disabled'` (default when absent), no timestamping occurs
+     * and no existing cycle behavior changes.
+     *
+     * NOTE: `rootHash` must be provided externally (via A-DEMO consolidation of
+     * the Trace). Until A-DEMO wires the Trace builder, this is a no-op silently
+     * when `rootHash` is undefined — the config is accepted at construction but
+     * the port is not called.
+     */
+    readonly timestamping?: {
+        /** TimestampPort adapter (e.g. FreeTSAAdapter or NullTimestampPort). */
+        readonly port: TimestampPort;
+        /** Optional receipt queue for retry on failure. */
+        readonly queue?: ReceiptQueue;
+        /** KeyProvider for queue HMAC (required when queue is set). */
+        readonly queueHmacKeyProvider?: KeyProvider;
+        /** Key identifier for queueHmacKeyProvider (required when queue is set). */
+        readonly queueHmacKeyId?: string;
+        /**
+         * Trigger mode.
+         * - `'on-cycle-complete'`: timestamp after each successful cycle.
+         * - `'on-demand'`: caller manages invocation (not yet implemented).
+         * - `'disabled'`: no-op (default when `timestamping` is absent).
+         */
+        readonly when: "on-cycle-complete" | "on-demand" | "disabled";
+    };
+}
+/**
+ * OODAAgent — public handle returned by `createOODAAgent`.
+ */
+export interface OODAAgent {
+    /** Begin sequential cycle loop. Resolves once `stop()` is called. */
+    start(): Promise<void>;
+    /** Signal the loop to exit after the current cycle finishes. */
+    stop(): Promise<void>;
+    /**
+     * One-shot cycle. `dryRun` flag is REQUIRED (audit-ready contract).
+     * Throws `MissingDryRunFlagError` if `opts.dryRun` is `undefined` or `opts` is omitted.
+     *
+     * `initialContext` injects initial observation/context for event-driven
+     * activation — enables agents to react to external events without a
+     * full observe phase.
+     */
+    triggerCycle(opts: {
+        dryRun: boolean;
+        initialContext?: Record<string, unknown>;
+    }): Promise<{
+        runId: string;
+        status: CycleStatus;
+    }>;
+    /**
+     * Execute one cycle and stream `CycleEvent` events as they occur.
+     * `dryRun: true` overrides `executionMode` to `dry-run`.
+     *
+     * @public @experimental
+     */
+    streamCycle(opts: {
+        dryRun: boolean;
+        initialContext?: Record<string, unknown>;
+    }): AsyncIterable<CycleEvent>;
+    getStatus(): {
+        running: boolean;
+        lastCycleAt?: string;
+        nextCycleAt?: string;
+        cyclesCompleted: number;
+    };
+}
+/**
+ * Terminal cycle outcomes. `skipped` = guard tripped, no work done.
+ */
+export type CycleStatus = "succeeded" | "failed" | "skipped";
+/**
+ * CycleEventV010 — 10 variants emitted by `streamCycle()`.
+ *
+ * All variants are discriminated by `type`. The `timestamp_pending` variant
+ * is typed here but NOT emitted by `streamCycle()` — it is reserved for A4
+ * (proof timestamping pipeline).
+ *
+ * @public @experimental
+ */
+export type CycleEventV010 = {
+    type: "phase_start";
+    runId: string;
+    cycleIndex: number;
+    phase: string;
+    ts: number;
+} | {
+    type: "phase_complete";
+    runId: string;
+    cycleIndex: number;
+    phase: string;
+    durationMs: number;
+    ts: number;
+} | {
+    type: "phase_error";
+    runId: string;
+    cycleIndex: number;
+    phase: string;
+    error: {
+        message: string;
+    };
+    ts: number;
+} | {
+    type: "guard_tripped";
+    runId: string;
+    cycleIndex: number;
+    guard: string;
+    reason: string;
+    ts: number;
+} | {
+    type: "hitl_waiting";
+    runId: string;
+    cycleIndex: number;
+    stepId: string;
+    payloadHash: string;
+    ts: number;
+} | {
+    type: "hitl_approved";
+    runId: string;
+    cycleIndex: number;
+    stepId: string;
+    ts: number;
+} | {
+    type: "cycle_complete";
+    runId: string;
+    cycleIndex: number;
+    status: CycleStatus;
+    durationMs: number;
+    ts: number;
+} | {
+    type: "cycle_skipped";
+    runId: string;
+    cycleIndex: number;
+    reason: string;
+    ts: number;
+} | {
+    type: "cycle_error";
+    runId: string;
+    cycleIndex: number;
+    error: {
+        message: string;
+    };
+    ts: number;
+} | {
+    type: "timestamp_pending";
+    runId: string;
+    cycleIndex: number;
+    rootHash: string;
+    ts: number;
+};
+/**
+ * CycleEventV011 — 3 variants typed for B1 (handoff/guardrail/cycle_proven).
+ * Typed but NOT emitted yet — reserved for sprint-562 B1.
+ *
+ * @public @experimental
+ */
+export type CycleEventV011 = {
+    type: "guardrail_violated";
+    runId: string;
+    cycleIndex: number;
+    phase: string;
+    timing: "pre-phase" | "post-phase";
+    proofHash: string;
+    reason: string;
+    ts: number;
+} | {
+    type: "handoff_initiated";
+    runId: string;
+    cycleIndex: number;
+    targetAgentId: string;
+    childRunId: string;
+    handoffChain: string[];
+    ts: number;
+} | {
+    type: "cycle_proven";
+    runId: string;
+    cycleIndex: number;
+    rootHash: string;
+    entriesCount: number;
+    proofChainRef: string;
+    ts: number;
+};
+/**
+ * CycleEvent — full discriminated union (V010 | V011).
+ *
+ * @public @experimental
+ */
+export type CycleEvent = CycleEventV010 | CycleEventV011;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/orchestration/ooda/types.js

@@ -0,0 +1,38 @@
+/**
+ * OODA Orchestration — Public Types (sprint-525:quick-1 foundation).
+ *
+ * The OODA primitive is the single, opinionated agent lifecycle for CC v2:
+ *   observe → orient → decide → act → feedback
+ *
+ * 10 anti-patterns are enforced **by-design** through the API surface and
+ * runtime validation in `OODAAgentImpl`:
+ *
+ *   1. Sequential `while + sleep` cycle loop — never `setInterval`.
+ *   2. Each phase persists `pending` → `done` via `insertStep` + `completeStep`.
+ *   3. Optional `hitlGate` on `act` — gates execution until human approval.
+ *   4. Risk guards have NO TTL bypass — each cycle re-checks.
+ *   5. Session guards checked once per cycle; cycle SKIPPED if any false.
+ *   6. `executionMode` is REQUIRED at construction — no implicit default.
+ *   7. `observe` and `orient` MUST be `readOnly: true`.
+ *   8. On any guard tripped, the cycle aborts cleanly — no LLM/skill calls.
+ *   9. Resource limits (`phaseTimeoutMs`, `maxStepsPerCycle`, `maxHeapMb`)
+ *      are configurable with sane defaults (60s / 200 / 256MB).
+ *  10. Heap & step usage are monitored and exceeding limits is logged + aborted.
+ *
+ * Replay safety: every `OODAContext` carries `isReplay`. Skills and phase
+ * functions MUST honor it (no observable side effects when true).
+ *
+ * Type-safe phase chaining: each phase's `TOutput` becomes the next phase's
+ * `TInput`, providing compile-time guarantees on the data flow.
+ *
+ * @public
+ */
+/**
+ * Default resource limits — exported for tests and host wiring.
+ */
+export const DEFAULT_RESOURCE_LIMITS = {
+    phaseTimeoutMs: 60_000,
+    maxStepsPerCycle: 200,
+    maxHeapMb: 256,
+};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/orchestration/ooda/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAsLH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA6B;IAC/D,cAAc,EAAE,MAAM;IACtB,gBAAgB,EAAE,GAAG;IACrB,SAAS,EAAE,GAAG;CACf,CAAC"}