@vauban-org/agent-sdk 0.16.0

package/src/factory/agent-factory.ts

@@ -0,0 +1,261 @@
+/**
+ * AgentFactory — universal wiring of OODA agents from AgentFactoryConfig.
+ *
+ * Promoted from forge/src/agents/shared/agent-factory.ts (Vague 1.B.2).
+ * Forge-specific business logic (Slack/Telegram HITL channels, buildRevenueSkills,
+ * etc.) is NOT promoted — only the generic wiring pattern.
+ *
+ * Neutralized Forge couplings:
+ * - HITL channels injected via deps.messaging (not hardcoded Telegram bot tokens)
+ * - "FORGE.md" hardcoded string → parameterizable via loadAgentContext options
+ * - Forge-specific metrics not promoted — consumers add via optional peer dep
+ *
+ * @public @since 0.17.0
+ */
+
+import { createOODAAgent } from "../orchestration/ooda/factory.js";
+import { alwaysOn } from "../orchestration/ooda/guards/always-on.js";
+import { waitForHITLApproval } from "../orchestration/ooda/hitl-gate.js";
+import type {
+  OODAAgent,
+  OODAAgentConfig,
+  OODAAgentDeps,
+  SessionGuard,
+  RiskGuard,
+  OutcomeRecord,
+} from "../orchestration/ooda/types.js";
+import type { AgentDependencies } from "../types/agent.js";
+import type {
+  AgentRegistryPort,
+  AgentDescriptor,
+} from "../ports/agent-registry.js";
+import type { MessagingChannelPort } from "../ports/messaging.js";
+
+// ─── AgentFactoryDeps ─────────────────────────────────────────────────────────
+
+/**
+ * AgentDependencies extended with optional fields used by the factory.
+ * Consumers may pass registry and messaging via this extension.
+ *
+ * @public
+ */
+export interface AgentFactoryDeps extends AgentDependencies {
+  /** Optional AgentRegistryPort for auto-registration at boot. */
+  readonly registry?: AgentRegistryPort;
+  /** Optional messaging channel for HITL notifications. */
+  readonly messaging?: MessagingChannelPort;
+}
+
+// ─── AgentFactoryConfig ───────────────────────────────────────────────────────
+
+/**
+ * Generic factory configuration. Type parameters chain OODA phase I/O.
+ *
+ * @public
+ */
+export interface AgentFactoryConfig<
+  TConfig = unknown,
+  TObs = unknown,
+  TOrient = unknown,
+  TDecision = unknown,
+  TAction = unknown,
+  TFeedback = unknown
+> {
+  /** Agent identifier (e.g. "forge-revenue", "cc-sentinel"). */
+  agentId: string;
+  /** Agent semver string. */
+  agentVersion: string;
+  /** Cycle interval in milliseconds. */
+  intervalMs: number;
+  /** Default config merged with deps at boot. */
+  defaults?: TConfig;
+  /** OODA phase definitions. */
+  phases: OODAAgentConfig<
+    TConfig,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  >["phases"];
+  /** Session guards (defaults to [alwaysOn()]). */
+  sessionGuards?: SessionGuard[];
+  /** Risk guards. */
+  riskGuards?: RiskGuard[];
+  /** Outcome mapping: feedback → outcome record (null skips recording). */
+  outcomeMapping?: (feedback: TFeedback) => OutcomeRecord | null;
+  /** HITL escalation level for actions requiring human review. */
+  hitlEscalationLevel?: "L1" | "L2" | "L3";
+  /**
+   * Registry descriptor for auto-registration in AgentRegistryPort.
+   * When provided AND deps.registry is set, the agent registers itself on boot.
+   */
+  registryDescriptor?: Omit<AgentDescriptor, "id"> & { product: string };
+}
+
+// ─── createAgentFromConfig ────────────────────────────────────────────────────
+
+/**
+ * Create an OODAAgent from a generic config + dependency bundle.
+ *
+ * Handles:
+ * - Strict deps validation (SDK_STRICT_DEPS gate via createOODAAgent)
+ * - Auto-registration in AgentRegistryPort when deps.registry is set
+ * - HITL wiring via MessagingChannelPort (not Forge-specific Slack/Telegram)
+ * - Resource limits with production-safe defaults
+ *
+ * @example
+ * ```ts
+ * const agent = await createAgentFromConfig(deps, {
+ *   agentId: "my-agent",
+ *   agentVersion: "1.0.0",
+ *   intervalMs: 60_000,
+ *   phases: { observe, orient, decide, act, feedback },
+ * });
+ * await agent.start();
+ * ```
+ *
+ * @public
+ */
+export async function createAgentFromConfig<
+  TConfig = unknown,
+  TObs = unknown,
+  TOrient = unknown,
+  TDecision = unknown,
+  TAction = unknown,
+  TFeedback = unknown
+>(
+  deps: AgentFactoryDeps,
+  config: AgentFactoryConfig<
+    TConfig,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  >
+): Promise<OODAAgent> {
+  const {
+    agentId,
+    agentVersion,
+    intervalMs,
+    phases,
+    sessionGuards,
+    riskGuards,
+    outcomeMapping,
+    hitlEscalationLevel = "L2",
+    registryDescriptor,
+  } = config;
+
+  // 1. Auto-register in AgentRegistryPort if descriptor + registry provided
+  if (registryDescriptor && deps.registry) {
+    await deps.registry
+      .register({
+        id: `${registryDescriptor.product}:${agentId}`,
+        ...registryDescriptor,
+      })
+      .catch((err: unknown) => {
+        // Non-fatal: registration failure should not block agent boot
+        deps.logger.warn(
+          { err },
+          `[${agentId}] AgentRegistry.register failed — agent may not appear in discovery`
+        );
+      });
+  }
+
+  // 2. Build OODA deps bundle from AgentFactoryDeps
+  const oodaDeps: Partial<OODAAgentDeps> = {
+    eventBus: deps.eventBus,
+    memory: deps.brain,
+    messaging: deps.messaging,
+  };
+
+  // 3. Build HITL waiter if messaging channel available and in live mode
+  let waitForHITL: OODAAgentConfig["waitForHITL"] | undefined;
+
+  if (deps.messaging && deps.executionMode === "live") {
+    const messaging = deps.messaging;
+    const onTimeout = hitlEscalationLevel === "L3" ? "reject" : "approve";
+    const timeoutMs = hitlEscalationLevel === "L3" ? 10 * 60_000 : 5 * 60_000;
+
+    waitForHITL = async (ctx: {
+      runId: string;
+      stepId: string;
+      payload: unknown;
+    }) => {
+      const decisionPayload = (ctx.payload as Record<string, unknown>) ?? {};
+
+      // Skip HITL when act phase produced no actionable output
+      const hasActions =
+        (Array.isArray(decisionPayload["actions"]) &&
+          (decisionPayload["actions"] as unknown[]).length > 0) ||
+        (typeof decisionPayload["action"] === "string" &&
+          (decisionPayload["action"] as string).length > 0) ||
+        decisionPayload["estimatedCostCents"] !== undefined;
+
+      if (!hasActions) return;
+
+      const verdictPromise = waitForHITLApproval(
+        deps.db,
+        {
+          runId: ctx.runId,
+          agentId,
+          decisionPayload,
+          executionMode: deps.executionMode,
+        },
+        { onTimeout, timeoutMs }
+      );
+
+      // Fire-and-forget notification via messaging channel
+      const costCents = decisionPayload["estimatedCostCents"] as
+        | number
+        | undefined;
+      const costLabel =
+        costCents !== undefined ? ` — estimated cost: ${costCents}¢` : "";
+      messaging
+        .sendAlert(
+          "warn",
+          `[HITL] ${agentId} requires approval (${hitlEscalationLevel})`,
+          `runId=${ctx.runId} stepId=${ctx.stepId}${costLabel}\n` +
+            `Payload: ${JSON.stringify(decisionPayload).slice(0, 500)}`
+        )
+        .catch((err: unknown) => {
+          deps.logger.warn({ err }, `[${agentId}] HITL notification failed`);
+        });
+
+      const verdict = await verdictPromise;
+      if (!verdict.approved) {
+        throw new Error(verdict.rationale ?? "HITL: rejected");
+      }
+    };
+  }
+
+  // 4. Assemble OODAAgentConfig
+  const oodaConfig: OODAAgentConfig<
+    TConfig,
+    TObs,
+    TOrient,
+    TDecision,
+    TAction,
+    TFeedback
+  > = {
+    agentId,
+    agentVersion,
+    intervalMs,
+    executionMode: deps.executionMode,
+    config: config.defaults,
+    db: deps.db,
+    logger: deps.logger,
+    skills: deps.skills,
+    deps: oodaDeps as OODAAgentDeps,
+    phases,
+    sessionGuards: sessionGuards ?? [alwaysOn()],
+    riskGuards: riskGuards ?? [],
+    outcomeMapping,
+    resourceLimits: { phaseTimeoutMs: 300_000, maxStepsPerCycle: 20 },
+    waitForHITL,
+  };
+
+  // 5. Create and return agent
+  return createOODAAgent(oodaConfig);
+}

package/src/hitl/api.ts

@@ -0,0 +1,78 @@
+/**
+ * HITL HTTP API helpers — framework-agnostic request body reader and
+ * shared types used by both Slack and Telegram callback handlers.
+ *
+ * Plan v6 §1.7: state lives in HITLPort; this module is pure transport plumbing.
+ *
+ * @public
+ */
+
+import type { IncomingMessage } from "node:http";
+
+// ─── Shared handler result type ──────────────────────────────────────────────
+
+/** Framework-agnostic result returned by all HITL callback handlers. */
+export interface HITLHandlerResult {
+  status: number;
+  body: unknown;
+}
+
+// ─── Raw request adapter for Node HTTP ──────────────────────────────────────
+
+/**
+ * Read the full body from a Node.js `IncomingMessage` stream.
+ * Returns the raw UTF-8 string (required for HMAC verification).
+ */
+export function collectBody(req: IncomingMessage): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+/**
+ * Extract all headers from a Node `IncomingMessage` as a flat string map.
+ * Multi-value headers are joined with `, `.
+ */
+export function extractHeaders(req: IncomingMessage): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, val] of Object.entries(req.headers)) {
+    if (val == null) continue;
+    out[key] = Array.isArray(val) ? val.join(", ") : val;
+  }
+  return out;
+}
+
+// ─── Common button-value parsing ────────────────────────────────────────────
+
+/** Compact callback_data format used by both Slack (button value) and Telegram. */
+export interface HITLCallbackData {
+  approvalId: string;
+  action: "approve" | "reject";
+}
+
+/**
+ * Parse a HITL button value that may use either:
+ * - compact format: `{ a: "<id>", v: "approve"|"reject" }`
+ * - legacy format:  `{ approval_id: "<id>", action: "approve"|"reject" }`
+ *
+ * Returns null on any parsing failure.
+ */
+export function parseCallbackData(raw: string): HITLCallbackData | null {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  const approvalId = String(parsed["a"] ?? parsed["approval_id"] ?? "");
+  const actionRaw = String(parsed["v"] ?? parsed["action"] ?? "");
+
+  if (!approvalId) return null;
+  if (actionRaw !== "approve" && actionRaw !== "reject") return null;
+
+  return { approvalId, action: actionRaw };
+}

package/src/hitl/approval-channel.ts

@@ -0,0 +1,128 @@
+/**
+ * HITL approval-channel contract + in-memory store.
+ *
+ * Transport-agnostic: concrete transports live in concrete channel
+ * implementations (email, telegram, etc.).
+ */
+
+/** Metadata supplied when an agent requests human authorisation. */
+export interface ApprovalRequest {
+  /** Stable agent identifier (e.g. `market-radar`). */
+  agentId: string;
+  /** Short action description shown to the approver (e.g. `anchor_seal`). */
+  action: string;
+  /** Extra context (tool name, arguments, rationale). */
+  context: string;
+  /** Hard wait timeout in milliseconds before falling back to deny. */
+  timeoutMs: number;
+}
+
+/** Verdict returned by a human approver. */
+export interface Approval {
+  approved: boolean;
+  rationale?: string;
+  /** Identifier of the approver (e.g. Slack user id or email). */
+  by: string;
+  /** ISO 8601 timestamp of the verdict. */
+  at: string;
+}
+
+/**
+ * Transport-agnostic HITL channel. Concrete impls (Email, Telegram, ...) must
+ * satisfy `send → poll → (resolve ∨ cancel)` semantics.
+ */
+export interface ApprovalChannel {
+  /** Dispatch an approval request and return an opaque request id. */
+  send(req: ApprovalRequest): Promise<string>;
+  /** Poll for a verdict. Returns null while the request is still pending. */
+  poll(id: string): Promise<Approval | null>;
+  /** Cancel a pending request (e.g. on agent timeout or cancellation). */
+  cancel(id: string): Promise<void>;
+}
+
+// ─── Store contract ────────────────────────────────────────────────────────
+
+export type ApprovalStatus = "pending" | "resolved" | "cancelled" | "timedout";
+
+export interface PendingApproval {
+  id: string;
+  req: ApprovalRequest;
+  createdAt: number;
+  expiresAt: number;
+  status: ApprovalStatus;
+  verdict?: Approval;
+}
+
+/**
+ * Pluggable storage for pending approvals. Channels use it to persist state
+ * between `send()` and callback resolution (e.g. HTTP click from email).
+ *
+ * `resolve` uses optimistic CAS: returns `false` if entry is missing or not
+ * pending (race-safe — first caller wins).
+ */
+export interface ApprovalStore {
+  create(entry: PendingApproval): Promise<void>;
+  get(id: string): Promise<PendingApproval | null>;
+  /** First writer wins. Returns true on transition, false on no-op. */
+  resolve(id: string, verdict: Approval): Promise<boolean>;
+  cancel(id: string): Promise<boolean>;
+  /** Mark overdue pending entries as `timedout`. Returns count affected. */
+  expireOverdue(now?: number): Promise<number>;
+}
+
+/**
+ * Process-local in-memory store. Suitable for CI tests and single-instance
+ * deployments. Multi-instance prod deployments should plug a Redis/Postgres
+ * impl behind this interface.
+ */
+export class InMemoryApprovalStore implements ApprovalStore {
+  private readonly entries = new Map<string, PendingApproval>();
+
+  async create(entry: PendingApproval): Promise<void> {
+    if (this.entries.has(entry.id)) {
+      throw new Error(`approval: duplicate id ${entry.id}`);
+    }
+    this.entries.set(entry.id, { ...entry });
+  }
+
+  async get(id: string): Promise<PendingApproval | null> {
+    const e = this.entries.get(id);
+    return e ? { ...e } : null;
+  }
+
+  async resolve(id: string, verdict: Approval): Promise<boolean> {
+    const e = this.entries.get(id);
+    if (!e || e.status !== "pending") return false;
+    e.status = "resolved";
+    e.verdict = verdict;
+    return true;
+  }
+
+  async cancel(id: string): Promise<boolean> {
+    const e = this.entries.get(id);
+    if (!e || e.status !== "pending") return false;
+    e.status = "cancelled";
+    return true;
+  }
+
+  async expireOverdue(now = Date.now()): Promise<number> {
+    let n = 0;
+    for (const e of this.entries.values()) {
+      if (e.status === "pending" && now > e.expiresAt) {
+        e.status = "timedout";
+        n += 1;
+      }
+    }
+    return n;
+  }
+
+  /**
+   * Enumerate all entries. Not part of the `ApprovalStore` contract — used
+   * by dashboard routes to render the HITL queue and history.
+   * Multi-instance prod deployments must replace this with a paginated
+   * backing query (Redis ZRANGE, Postgres, ...).
+   */
+  async listAll(): Promise<readonly PendingApproval[]> {
+    return Array.from(this.entries.values(), (e) => ({ ...e }));
+  }
+}

package/src/hitl/callback-handlers.ts

@@ -0,0 +1,61 @@
+/**
+ * HITL callback handlers — unified re-export of Slack + Telegram handlers.
+ *
+ * Consumers can import from this module or directly from slack.ts / telegram.ts.
+ * Also provides a combined Node HTTP handler for Slack interactive payloads.
+ *
+ * @public
+ */
+
+export {
+  createSlackCallbackHandler,
+  verifySlackSignature,
+  type SlackCallbackHandlerOpts,
+  type RawRequest,
+  type HandlerResult,
+} from "./slack.js";
+
+export {
+  createTelegramCallbackHandler,
+  verifyTelegramSignature,
+  type TelegramCallbackHandlerOpts,
+} from "./telegram.js";
+
+export {
+  collectBody,
+  extractHeaders,
+  parseCallbackData,
+  type HITLHandlerResult,
+  type HITLCallbackData,
+} from "./api.js";
+
+// ─── Node HTTP convenience adapter ──────────────────────────────────────────
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { collectBody, extractHeaders } from "./api.js";
+import {
+  createSlackCallbackHandler,
+  type SlackCallbackHandlerOpts,
+} from "./slack.js";
+
+/**
+ * Create a Node.js `http.IncomingMessage` handler for Slack interactive payloads.
+ *
+ * Wire to: POST /slack/interactive
+ * Reads the raw body (required for HMAC), verifies signature, resolves HITLPort.
+ */
+export function createNodeSlackCallbackHandler(
+  opts: SlackCallbackHandlerOpts
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  const handler = createSlackCallbackHandler(opts);
+
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const rawBody = await collectBody(req);
+    const headers = extractHeaders(req);
+
+    const result = await handler({ rawBody, headers });
+
+    res.writeHead(result.status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(result.body));
+  };
+}

package/src/hitl/index.ts

@@ -0,0 +1,9 @@
+export { InMemoryApprovalStore } from "./approval-channel.js";
+export type {
+  ApprovalChannel,
+  ApprovalRequest,
+  Approval,
+  ApprovalStore,
+  ApprovalStatus,
+  PendingApproval,
+} from "./approval-channel.js";