@vauban-org/agent-sdk 0.16.0

package/dist/templates/complex-agent.js

@@ -0,0 +1,94 @@
+/**
+ * ComplexAgent Template — Tier 3 (Supervisor-Worker + Plan-and-Execute + Debate).
+ *
+ * Promoted from forge/src/agents/shared/templates/complex-agent.ts (Vague 1.B.7).
+ *
+ * For agents that need multi-agent coordination, step-by-step planning,
+ * and adversarial debate:
+ *   - Orchestrateur Central, Treasury Agent, DevOps Agent, Security Auditor,
+ *     Contract Reviewer.
+ *
+ * Pattern: observe → orient (LLM + Debate) → decide (Plan decomposition) →
+ *          act (execute steps) → reflect (self-critique, optional) → feedback.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl) removed
+ * - hitlEscalationLevel wired to AgentFactoryConfig (not Forge-specific gate)
+ *
+ * @public @since 0.20.0
+ */
+import { createAgentFromConfig } from "../factory/agent-factory.js";
+// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create a Tier 3 (complex, supervisor-worker, debate-capable) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - HITL wiring handled automatically when `hitlEscalationLevel` is set
+ * - Optional `reflect` phase wired correctly between act and feedback
+ * - Phase `type` codes and `readOnly` flags set automatically
+ *
+ * @example
+ * ```ts
+ * const agent = await createComplexAgent<Obs, Orient, Plan, ExecResult, Feedback>(deps, {
+ *   agentId: "treasury-agent",
+ *   intervalMs: 3_600_000,
+ *   observe: async () => ({ balance: 1000, pendingTx: [] }),
+ *   orient: async (obs) => ({ recommendation: "hold", risk: "low" }),
+ *   decide: async (orient) => ({ steps: [{ action: "record", data: orient }] }),
+ *   act: async (plan) => ({ stepsExecuted: plan.steps.length }),
+ *   feedback: async (result) => ({ success: result.stepsExecuted > 0 }),
+ *   hitlEscalationLevel: "L3",
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createComplexAgent(deps, opts) {
+    return createAgentFromConfig(deps, {
+        agentId: opts.agentId,
+        agentVersion: opts.agentVersion ?? "0.1.0",
+        intervalMs: opts.intervalMs,
+        hitlEscalationLevel: opts.hitlEscalationLevel ?? "L3",
+        sessionGuards: opts.sessionGuards,
+        riskGuards: opts.riskGuards,
+        outcomeMapping: opts.outcomeMapping,
+        phases: {
+            observe: {
+                type: "observation",
+                readOnly: true,
+                fn: opts.observe,
+            },
+            orient: {
+                type: "retrieval",
+                readOnly: true,
+                fn: opts.orient,
+            },
+            decide: {
+                type: "decision",
+                fn: opts.decide,
+            },
+            act: {
+                type: "execution",
+                hitlGate: opts.hitlEscalationLevel !== undefined,
+                fn: opts.act,
+            },
+            ...(opts.reflect !== undefined
+                ? {
+                    reflect: {
+                        type: "feedback",
+                        readOnly: true,
+                        fn: opts.reflect,
+                    },
+                }
+                : {}),
+            feedback: {
+                type: "feedback",
+                fn: opts.feedback,
+            },
+        },
+    });
+}
+//# sourceMappingURL=complex-agent.js.map

package/dist/templates/complex-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complex-agent.js","sourceRoot":"","sources":["../../src/templates/complex-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AA0EpE,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAOtC,IAAsB,EACtB,IAAuE;IAEvE,OAAO,qBAAqB,CAO1B,IAAI,EAAE;QACN,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,OAAO;QAC1C,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI;QACrD,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,MAAM,EAAE;YACN,OAAO,EAAE;gBACP,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,IAAI;gBACd,EAAE,EAAE,IAAI,CAAC,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,IAAI;gBACd,EAAE,EAAE,IAAI,CAAC,MAAM;aAChB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,IAAI,CAAC,MAAM;aAChB;YACD,GAAG,EAAE;gBACH,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,IAAI,CAAC,mBAAmB,KAAK,SAAS;gBAChD,EAAE,EAAE,IAAI,CAAC,GAAG;aACb;YACD,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS;gBAC5B,CAAC,CAAC;oBACE,OAAO,EAAE;wBACP,IAAI,EAAE,UAAmB;wBACzB,QAAQ,EAAE,IAAI;wBACd,EAAE,EAAE,IAAI,CAAC,OAAO;qBACjB;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,QAAQ,EAAE;gBACR,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,IAAI,CAAC,QAGc;aACxB;SACF;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/templates/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent tier templates — SDK-distributable factory helpers.
+ *
+ * Three tiers promoted from Forge (Vague 1.B.7):
+ * - Tier 1 — SimpleAgent: rule-based, no LLM debate
+ * - Tier 2 — ReasoningAgent: LLM + Reflexion + Inner Monologue
+ * - Tier 3 — ComplexAgent: Supervisor-Worker + Debate + HITL gate
+ *
+ * @public @since 0.20.0
+ */
+export { createSimpleAgent } from "./simple-agent.js";
+export type { SimpleAgentOptions, SimpleAction, SimpleDecision, SimpleExecutionResult, } from "./simple-agent.js";
+export { createComplexAgent } from "./complex-agent.js";
+export type { ComplexAgentOptions } from "./complex-agent.js";
+export { createReasoningAgent } from "./reasoning-agent.js";
+export type { ReasoningAgentOptions, ReasoningAgentConfig, } from "./reasoning-agent.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC"}

package/dist/templates/index.js

@@ -0,0 +1,14 @@
+/**
+ * Agent tier templates — SDK-distributable factory helpers.
+ *
+ * Three tiers promoted from Forge (Vague 1.B.7):
+ * - Tier 1 — SimpleAgent: rule-based, no LLM debate
+ * - Tier 2 — ReasoningAgent: LLM + Reflexion + Inner Monologue
+ * - Tier 3 — ComplexAgent: Supervisor-Worker + Debate + HITL gate
+ *
+ * @public @since 0.20.0
+ */
+export { createSimpleAgent } from "./simple-agent.js";
+export { createComplexAgent } from "./complex-agent.js";
+export { createReasoningAgent } from "./reasoning-agent.js";
+//# sourceMappingURL=index.js.map

package/dist/templates/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAQtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/templates/reasoning-agent.d.ts

@@ -0,0 +1,160 @@
+/**
+ * ReasoningAgent Template — Tier 2 (LLM + Reflexion + Inner Monologue).
+ *
+ * Promoted from forge/src/agents/shared/templates/reasoning-agent.ts (Vague 1.B.7).
+ *
+ * For agents that need reasoning but not multi-agent debate or supervisor-worker:
+ *   - CFO IA, Chief of Staff IA, Prospector, Lead Qualifier, Outreach Writer,
+ *     Churn Predictor, Contract Generator.
+ *
+ * Pattern: observe → orient (LLM + Reflexion) → decide (LLM) →
+ *          act → reflect (self-critique, optional) → feedback.
+ *
+ * Extended thinking (Anthropic): pass `thinkingBudget` to enable budget_tokens
+ * in orient/decide phases via `deps.llm` with extended thinking support.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - `thinkingBudget` is an SDK-native concept (Anthropic extended thinking)
+ *   exposed via `ctx.deps.llm` metadata — no hardcoded model names here
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl) removed
+ *
+ * @public @since 0.20.0
+ */
+import type { AgentFactoryDeps } from "../factory/agent-factory.js";
+import type { OODAAgent, OODAContext } from "../orchestration/ooda/types.js";
+import type { SessionGuard, RiskGuard, OutcomeRecord } from "../orchestration/ooda/types.js";
+/**
+ * ReasoningAgentOptions — typed configuration for Tier 2 agents.
+ *
+ * Type parameters chain OODA phase I/O:
+ * - `TObs`      — observation output
+ * - `TOrient`   — orientation output (after LLM + Reflexion)
+ * - `TDecision` — decision output (LLM-powered)
+ * - `TAction`   — action output
+ * - `TFeedback` — feedback output
+ *
+ * @public
+ */
+export interface ReasoningAgentOptions<TObs, TOrient, TDecision, TAction, TFeedback> {
+    /** Agent identifier (e.g. "cfo-agent"). */
+    agentId: string;
+    /** Agent semver string. */
+    agentVersion?: string;
+    /** Cycle interval in milliseconds. */
+    intervalMs: number;
+    /**
+     * Agent role description used in LLM prompts (system prompt context).
+     * Example: "You are the CFO agent responsible for financial oversight."
+     */
+    agentRole: string;
+    /**
+     * Extended thinking budget in tokens (Anthropic extended thinking).
+     * When set, phases should pass `thinkingBudget` to `deps.llm.complete()`
+     * via the `metadata` field or a custom wrapper.
+     *
+     * Recommended: 1024–8192 for reasoning tasks.
+     * Only effective when `deps.llm` is an AnthropicDirectAdapter with an
+     * extended-thinking-capable model (claude-3-7-sonnet or newer).
+     */
+    thinkingBudget?: number;
+    /** Observe phase: read data from Brain/APIs (readOnly). */
+    observe: (_: void, ctx: OODAContext) => Promise<TObs>;
+    /** Orient phase: LLM-powered analysis + Reflexion memory (readOnly). */
+    orient: (obs: TObs, ctx: OODAContext) => Promise<TOrient>;
+    /** Decide phase: LLM-powered decision making. */
+    decide: (orient: TOrient, ctx: OODAContext) => Promise<TDecision>;
+    /** Act phase: execute decisions via skills. */
+    act: (decision: TDecision, ctx: OODAContext) => Promise<TAction>;
+    /**
+     * Optional reflect phase: self-critique on the action (Reflexion pattern).
+     * Strongly recommended for reasoning agents to improve over time.
+     */
+    reflect?: (input: TAction & {
+        decision: TDecision;
+    }, ctx: OODAContext) => Promise<TFeedback>;
+    /** Feedback phase: log outcome, archive to Brain. */
+    feedback: (input: TAction & {
+        decision?: TDecision;
+    }, ctx: OODAContext) => Promise<TFeedback>;
+    /**
+     * HITL escalation level.
+     * - "L2": async review (default for reasoning agents).
+     * - "L3": synchronous HITL approval.
+     * When absent, no HITL gate is applied.
+     */
+    hitlEscalationLevel?: "L2" | "L3";
+    /** Optional session guards. Defaults to alwaysOn. */
+    sessionGuards?: SessionGuard[];
+    /** Optional risk guards. */
+    riskGuards?: RiskGuard[];
+    /** Optional outcome mapping for Economic Observer. */
+    outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+}
+/**
+ * Create a Tier 2 (reasoning, LLM-powered, Reflexion-capable) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - `agentRole` and `thinkingBudget` surfaced as first-class options
+ * - Optional `reflect` phase wired correctly between act and feedback
+ * - Phase `type` codes and `readOnly` flags set automatically
+ * - HITL wiring handled when `hitlEscalationLevel` is set
+ *
+ * The `agentRole` and `thinkingBudget` values are accessible in every phase
+ * via closure — pass them to `buildOrientPrompt` or `deps.llm.complete()` as
+ * needed in your phase implementations.
+ *
+ * @example
+ * ```ts
+ * const agent = await createReasoningAgent<Obs, Orient, Decision, Action, Feedback>(deps, {
+ *   agentId: "cfo-agent",
+ *   intervalMs: 3_600_000,
+ *   agentRole: "You are the CFO agent. Analyze financial data and provide recommendations.",
+ *   thinkingBudget: 4096,
+ *   observe: async () => ({ revenue: 10000, expenses: 8000 }),
+ *   orient: async (obs, ctx) => {
+ *     const { system, user } = buildOrientPrompt({
+ *       systemPrompt: ctx.config.agentRole ?? "",
+ *       userContext: JSON.stringify(obs),
+ *     });
+ *     const response = await ctx.deps.llm?.complete({ messages: [
+ *       { role: "system", content: system },
+ *       { role: "user", content: user },
+ *     ]});
+ *     return parseStructuredOutput(response?.content ?? "{}");
+ *   },
+ *   decide: async (orient) => ({ recommendation: orient.recommendation }),
+ *   act: async (decision) => ({ executed: true, decision }),
+ *   feedback: async (result) => ({ success: result.executed }),
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export declare function createReasoningAgent<TObs, TOrient, TDecision, TAction, TFeedback>(deps: AgentFactoryDeps, opts: ReasoningAgentOptions<TObs, TOrient, TDecision, TAction, TFeedback>): Promise<OODAAgent>;
+/**
+ * ReasoningAgentConfig — the shape of `ctx.config` for reasoning agents.
+ * Cast `ctx.config` to this type in your phase implementations:
+ *
+ * ```ts
+ * orient: async (obs, ctx) => {
+ *   const cfg = ctx.config as ReasoningAgentConfig;
+ *   const { system, user } = buildOrientPrompt({
+ *     systemPrompt: cfg.agentRole,
+ *     userContext: JSON.stringify(obs),
+ *   });
+ *   // ...
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface ReasoningAgentConfig {
+    /** System prompt role description for LLM calls. */
+    readonly agentRole: string;
+    /** Extended thinking budget in tokens (optional). */
+    readonly thinkingBudget?: number;
+}
+//# sourceMappingURL=reasoning-agent.d.ts.map

package/dist/templates/reasoning-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-agent.d.ts","sourceRoot":"","sources":["../../src/templates/reasoning-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACd,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB,CACpC,IAAI,EACJ,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS;IAET,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,wEAAwE;IACxE,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,iDAAiD;IACjD,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAClE,+CAA+C;IAC/C,GAAG,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE;;;OAGG;IACH,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,OAAO,GAAG;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,EACxC,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,qDAAqD;IACrD,QAAQ,EAAE,CACR,KAAK,EAAE,OAAO,GAAG;QAAE,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,EACzC,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAClC,qDAAqD;IACrD,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,4BAA4B;IAC5B,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,sDAAsD;IACtD,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,aAAa,GAAG,IAAI,CAAC;CAChE;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EACJ,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS,EAET,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,GACxE,OAAO,CAAC,SAAS,CAAC,CA4DpB;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/templates/reasoning-agent.js

@@ -0,0 +1,119 @@
+/**
+ * ReasoningAgent Template — Tier 2 (LLM + Reflexion + Inner Monologue).
+ *
+ * Promoted from forge/src/agents/shared/templates/reasoning-agent.ts (Vague 1.B.7).
+ *
+ * For agents that need reasoning but not multi-agent debate or supervisor-worker:
+ *   - CFO IA, Chief of Staff IA, Prospector, Lead Qualifier, Outreach Writer,
+ *     Churn Predictor, Contract Generator.
+ *
+ * Pattern: observe → orient (LLM + Reflexion) → decide (LLM) →
+ *          act → reflect (self-critique, optional) → feedback.
+ *
+ * Extended thinking (Anthropic): pass `thinkingBudget` to enable budget_tokens
+ * in orient/decide phases via `deps.llm` with extended thinking support.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - `thinkingBudget` is an SDK-native concept (Anthropic extended thinking)
+ *   exposed via `ctx.deps.llm` metadata — no hardcoded model names here
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl) removed
+ *
+ * @public @since 0.20.0
+ */
+import { createAgentFromConfig } from "../factory/agent-factory.js";
+// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create a Tier 2 (reasoning, LLM-powered, Reflexion-capable) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - `agentRole` and `thinkingBudget` surfaced as first-class options
+ * - Optional `reflect` phase wired correctly between act and feedback
+ * - Phase `type` codes and `readOnly` flags set automatically
+ * - HITL wiring handled when `hitlEscalationLevel` is set
+ *
+ * The `agentRole` and `thinkingBudget` values are accessible in every phase
+ * via closure — pass them to `buildOrientPrompt` or `deps.llm.complete()` as
+ * needed in your phase implementations.
+ *
+ * @example
+ * ```ts
+ * const agent = await createReasoningAgent<Obs, Orient, Decision, Action, Feedback>(deps, {
+ *   agentId: "cfo-agent",
+ *   intervalMs: 3_600_000,
+ *   agentRole: "You are the CFO agent. Analyze financial data and provide recommendations.",
+ *   thinkingBudget: 4096,
+ *   observe: async () => ({ revenue: 10000, expenses: 8000 }),
+ *   orient: async (obs, ctx) => {
+ *     const { system, user } = buildOrientPrompt({
+ *       systemPrompt: ctx.config.agentRole ?? "",
+ *       userContext: JSON.stringify(obs),
+ *     });
+ *     const response = await ctx.deps.llm?.complete({ messages: [
+ *       { role: "system", content: system },
+ *       { role: "user", content: user },
+ *     ]});
+ *     return parseStructuredOutput(response?.content ?? "{}");
+ *   },
+ *   decide: async (orient) => ({ recommendation: orient.recommendation }),
+ *   act: async (decision) => ({ executed: true, decision }),
+ *   feedback: async (result) => ({ success: result.executed }),
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createReasoningAgent(deps, opts) {
+    return createAgentFromConfig(deps, {
+        agentId: opts.agentId,
+        agentVersion: opts.agentVersion ?? "0.1.0",
+        intervalMs: opts.intervalMs,
+        hitlEscalationLevel: opts.hitlEscalationLevel,
+        sessionGuards: opts.sessionGuards,
+        riskGuards: opts.riskGuards,
+        outcomeMapping: opts.outcomeMapping,
+        // Expose agentRole + thinkingBudget via config so phases can access them
+        // via ctx.config (cast to ReasoningAgentConfig by the phase implementation)
+        defaults: {
+            agentRole: opts.agentRole,
+            thinkingBudget: opts.thinkingBudget,
+        },
+        phases: {
+            observe: {
+                type: "observation",
+                readOnly: true,
+                fn: opts.observe,
+            },
+            orient: {
+                type: "retrieval",
+                readOnly: true,
+                fn: opts.orient,
+            },
+            decide: {
+                type: "decision",
+                fn: opts.decide,
+            },
+            act: {
+                type: "execution",
+                hitlGate: opts.hitlEscalationLevel !== undefined,
+                fn: opts.act,
+            },
+            ...(opts.reflect !== undefined
+                ? {
+                    reflect: {
+                        type: "feedback",
+                        readOnly: true,
+                        fn: opts.reflect,
+                    },
+                }
+                : {}),
+            feedback: {
+                type: "feedback",
+                fn: opts.feedback,
+            },
+        },
+    });
+}
+//# sourceMappingURL=reasoning-agent.js.map

package/dist/templates/reasoning-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-agent.js","sourceRoot":"","sources":["../../src/templates/reasoning-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAuFpE,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAOxC,IAAsB,EACtB,IAAyE;IAEzE,OAAO,qBAAqB,CAO1B,IAAI,EAAE;QACN,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,OAAO;QAC1C,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,yEAAyE;QACzE,4EAA4E;QAC5E,QAAQ,EAAE;YACR,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,cAAc,EAAE,IAAI,CAAC,cAAc;SACpC;QACD,MAAM,EAAE;YACN,OAAO,EAAE;gBACP,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,IAAI;gBACd,EAAE,EAAE,IAAI,CAAC,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,IAAI;gBACd,EAAE,EAAE,IAAI,CAAC,MAAM;aAChB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,IAAI,CAAC,MAAM;aAChB;YACD,GAAG,EAAE;gBACH,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,IAAI,CAAC,mBAAmB,KAAK,SAAS;gBAChD,EAAE,EAAE,IAAI,CAAC,GAAG;aACb;YACD,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS;gBAC5B,CAAC,CAAC;oBACE,OAAO,EAAE;wBACP,IAAI,EAAE,UAAmB;wBACzB,QAAQ,EAAE,IAAI;wBACd,EAAE,EAAE,IAAI,CAAC,OAAO;qBACjB;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,QAAQ,EAAE;gBACR,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,IAAI,CAAC,QAGc;aACxB;SACF;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/templates/simple-agent.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SimpleAgent Template — Tier 1 (rule-based, no LLM debate).
+ *
+ * Promoted from forge/src/agents/shared/templates/simple-agent.ts (Vague 1.B.7).
+ *
+ * For agents that don't need LLM reasoning, Reflexion, or supervisor-worker:
+ *   - Validator Monitor, KPI Dashboard, deadLetterAgent, Support Tier 1,
+ *     Invoice & Facturation, Staking/Validator Monitor.
+ *
+ * Pattern: observe → orient (rules) → decide (threshold-based) → act → feedback.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl in skill wiring) removed
+ *
+ * @public @since 0.20.0
+ */
+import type { AgentFactoryDeps } from "../factory/agent-factory.js";
+import type { OODAAgent, OODAContext } from "../orchestration/ooda/types.js";
+import type { SessionGuard, RiskGuard, OutcomeRecord } from "../orchestration/ooda/types.js";
+export interface SimpleAction {
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+}
+export interface SimpleDecision {
+    readonly actions: SimpleAction[];
+    readonly rationale: string;
+}
+export interface SimpleExecutionResult {
+    readonly executed: Array<{
+        readonly type: string;
+        readonly success: boolean;
+        readonly details: string;
+    }>;
+}
+/**
+ * SimpleAgentOptions — typed configuration for Tier 1 agents.
+ *
+ * Type parameters:
+ * - `TContext`  — observation output type
+ * - `TOrient`   — orientation output type
+ * - `TFeedback` — feedback output type
+ *
+ * @public
+ */
+export interface SimpleAgentOptions<TContext, TOrient, TFeedback> {
+    /** Agent identifier (e.g. "validator-monitor"). */
+    agentId: string;
+    /** Agent semver string. */
+    agentVersion?: string;
+    /** Cycle interval in milliseconds. */
+    intervalMs: number;
+    /** Observe phase: reads data from Brain/APIs (readOnly). */
+    observe: (_: void, ctx: OODAContext) => Promise<TContext>;
+    /** Orient phase: rule-based analysis on observation (readOnly). */
+    orient: (obs: TContext, ctx: OODAContext) => Promise<TOrient>;
+    /**
+     * Decide phase: threshold-based decision on orient output.
+     * Returns a SimpleDecision with actions list and rationale.
+     */
+    decide: (orient: TOrient, ctx: OODAContext) => Promise<SimpleDecision>;
+    /**
+     * Act phase: executes actions declared by decide.
+     */
+    act: (decision: SimpleDecision, ctx: OODAContext) => Promise<SimpleExecutionResult>;
+    /**
+     * Feedback phase: log outcome, optionally archive to Brain.
+     */
+    feedback: (result: SimpleExecutionResult, ctx: OODAContext) => Promise<TFeedback>;
+    /** Optional session guards (e.g. market hours). Defaults to alwaysOn. */
+    sessionGuards?: SessionGuard[];
+    /** Optional risk guards (e.g. circuit breaker). */
+    riskGuards?: RiskGuard[];
+    /** Optional outcome mapping for Economic Observer. */
+    outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+}
+/**
+ * Create a Tier 1 (simple, rule-based) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - No `readOnly` flags to specify manually (observe + orient always readOnly)
+ * - No phase `type` codes to remember
+ * - Strongly-typed phase chain enforced by TypeScript
+ *
+ * @example
+ * ```ts
+ * const agent = await createSimpleAgent<Observation, Orientation, Feedback>(deps, {
+ *   agentId: "kpi-monitor",
+ *   intervalMs: 300_000,
+ *   observe: async () => ({ cpu: 0.42, memory: 0.8 }),
+ *   orient: async (obs) => ({ critical: obs.memory > 0.9 }),
+ *   decide: async (orient) => ({
+ *     actions: orient.critical ? [{ type: "alert", payload: {} }] : [],
+ *     rationale: orient.critical ? "Memory critical" : "All good",
+ *   }),
+ *   act: async (decision) => ({
+ *     executed: decision.actions.map((a) => ({ type: a.type, success: true, details: "" })),
+ *   }),
+ *   feedback: async (result) => ({ actionsExecuted: result.executed.length }),
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export declare function createSimpleAgent<TContext, TOrient, TFeedback>(deps: AgentFactoryDeps, opts: SimpleAgentOptions<TContext, TOrient, TFeedback>): Promise<OODAAgent>;
+//# sourceMappingURL=simple-agent.d.ts.map

package/dist/templates/simple-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-agent.d.ts","sourceRoot":"","sources":["../../src/templates/simple-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACd,MAAM,gCAAgC,CAAC;AAIxC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC,CAAC;CACJ;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS;IAC9D,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1D,mEAAmE;IACnE,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE;;OAEG;IACH,GAAG,EAAE,CACH,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC;;OAEG;IACH,QAAQ,EAAE,CACR,MAAM,EAAE,qBAAqB,EAC7B,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,SAAS,CAAC,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,mDAAmD;IACnD,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,sDAAsD;IACtD,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,aAAa,GAAG,IAAI,CAAC;CAChE;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAClE,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,GACrD,OAAO,CAAC,SAAS,CAAC,CAwCpB"}

package/dist/templates/simple-agent.js

@@ -0,0 +1,84 @@
+/**
+ * SimpleAgent Template — Tier 1 (rule-based, no LLM debate).
+ *
+ * Promoted from forge/src/agents/shared/templates/simple-agent.ts (Vague 1.B.7).
+ *
+ * For agents that don't need LLM reasoning, Reflexion, or supervisor-worker:
+ *   - Validator Monitor, KPI Dashboard, deadLetterAgent, Support Tier 1,
+ *     Invoice & Facturation, Staking/Validator Monitor.
+ *
+ * Pattern: observe → orient (rules) → decide (threshold-based) → act → feedback.
+ *
+ * Differences from Forge template:
+ * - AgentDependencies removed — uses AgentFactoryDeps (SDK-native)
+ * - buildSkills / createForgeAgent replaced by createAgentFromConfig (SDK)
+ * - Forge-specific couplings (slackWebhookUrl, litellmUrl in skill wiring) removed
+ *
+ * @public @since 0.20.0
+ */
+import { createAgentFromConfig } from "../factory/agent-factory.js";
+// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create a Tier 1 (simple, rule-based) OODA agent.
+ *
+ * Boilerplate reduction vs. raw `createAgentFromConfig`:
+ * - No `readOnly` flags to specify manually (observe + orient always readOnly)
+ * - No phase `type` codes to remember
+ * - Strongly-typed phase chain enforced by TypeScript
+ *
+ * @example
+ * ```ts
+ * const agent = await createSimpleAgent<Observation, Orientation, Feedback>(deps, {
+ *   agentId: "kpi-monitor",
+ *   intervalMs: 300_000,
+ *   observe: async () => ({ cpu: 0.42, memory: 0.8 }),
+ *   orient: async (obs) => ({ critical: obs.memory > 0.9 }),
+ *   decide: async (orient) => ({
+ *     actions: orient.critical ? [{ type: "alert", payload: {} }] : [],
+ *     rationale: orient.critical ? "Memory critical" : "All good",
+ *   }),
+ *   act: async (decision) => ({
+ *     executed: decision.actions.map((a) => ({ type: a.type, success: true, details: "" })),
+ *   }),
+ *   feedback: async (result) => ({ actionsExecuted: result.executed.length }),
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createSimpleAgent(deps, opts) {
+    return createAgentFromConfig(deps, {
+        agentId: opts.agentId,
+        agentVersion: opts.agentVersion ?? "0.1.0",
+        intervalMs: opts.intervalMs,
+        sessionGuards: opts.sessionGuards,
+        riskGuards: opts.riskGuards,
+        outcomeMapping: opts.outcomeMapping,
+        phases: {
+            observe: {
+                type: "observation",
+                readOnly: true,
+                fn: opts.observe,
+            },
+            orient: {
+                type: "retrieval",
+                readOnly: true,
+                fn: opts.orient,
+            },
+            decide: {
+                type: "decision",
+                fn: opts.decide,
+            },
+            act: {
+                type: "execution",
+                fn: opts.act,
+            },
+            feedback: {
+                type: "feedback",
+                fn: opts.feedback,
+            },
+        },
+    });
+}
+//# sourceMappingURL=simple-agent.js.map

package/dist/templates/simple-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-agent.js","sourceRoot":"","sources":["../../src/templates/simple-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AA+EpE,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAsB,EACtB,IAAsD;IAEtD,OAAO,qBAAqB,CAO1B,IAAI,EAAE;QACN,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,OAAO;QAC1C,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,MAAM,EAAE;YACN,OAAO,EAAE;gBACP,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,IAAI;gBACd,EAAE,EAAE,IAAI,CAAC,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,IAAI;gBACd,EAAE,EAAE,IAAI,CAAC,MAAM;aAChB;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,IAAI,CAAC,MAAM;aAChB;YACD,GAAG,EAAE;gBACH,IAAI,EAAE,WAAW;gBACjB,EAAE,EAAE,IAAI,CAAC,GAAG;aACb;YACD,QAAQ,EAAE;gBACR,IAAI,EAAE,UAAU;gBAChB,EAAE,EAAE,IAAI,CAAC,QAAQ;aAClB;SACF;KACF,CAAC,CAAC;AACL,CAAC"}