@vauban-org/agent-sdk 0.16.0

package/dist/evals/harness.js

@@ -0,0 +1,108 @@
+/**
+ * Eval harness — strategy × dataset → {accuracy, cost, latency, rationale}.
+ *
+ * Sprint-579: eval-harness. Product-agnostic; consumer apps supply their own datasets.
+ *
+ * Usage:
+ *   const result = await evalSuite(singleShotStrategy, EVAL_DATASET_30);
+ *   console.log(result.accuracy); // 0.73
+ */
+// ─── Scorers ─────────────────────────────────────────────────────────────────
+function scoreExact(output, groundTruth) {
+    const normalized = output.trim().toLowerCase();
+    const truths = Array.isArray(groundTruth) ? groundTruth : [groundTruth];
+    return truths.some((gt) => normalized === gt.trim().toLowerCase()) ? 1 : 0;
+}
+function scoreContains(output, groundTruth) {
+    const normalized = output.toLowerCase();
+    const truths = Array.isArray(groundTruth) ? groundTruth : [groundTruth];
+    return truths.some((gt) => normalized.includes(gt.trim().toLowerCase())) ? 1 : 0;
+}
+function scoreNumericTolerance(output, groundTruth, tolerance) {
+    const truths = Array.isArray(groundTruth) ? groundTruth : [groundTruth];
+    const outputNum = parseFloat(output.replace(/[^0-9.\-]/g, ""));
+    if (Number.isNaN(outputNum))
+        return 0;
+    return truths.some((gt) => {
+        const gtNum = parseFloat(gt.replace(/[^0-9.\-]/g, ""));
+        return !Number.isNaN(gtNum) && Math.abs(outputNum - gtNum) <= tolerance;
+    })
+        ? 1
+        : 0;
+}
+export function scoreTask(task, output) {
+    switch (task.scorer ?? "contains") {
+        case "exact":
+            return scoreExact(output, task.groundTruth);
+        case "contains":
+            return scoreContains(output, task.groundTruth);
+        case "numeric_tolerance":
+            return scoreNumericTolerance(output, task.groundTruth, task.tolerance ?? 0);
+        case "code_output":
+            // Placeholder: falls back to contains for now.
+            return scoreContains(output, task.groundTruth);
+        default:
+            return scoreContains(output, task.groundTruth);
+    }
+}
+// ─── Main harness ─────────────────────────────────────────────────────────────
+/**
+ * Run a strategy against a dataset of eval tasks.
+ * Returns accuracy (0-1), total cost in USD, median latency in ms,
+ * and per-task rationale.
+ */
+export async function evalSuite(strategy, dataset) {
+    const t0 = Date.now();
+    const results = [];
+    for (const task of dataset) {
+        const taskT0 = Date.now();
+        let output = "";
+        let costUsd = 0;
+        let latencyMs = 0;
+        let rationale;
+        try {
+            const stratOut = await strategy.run(task.prompt);
+            output = stratOut.output;
+            costUsd = stratOut.costUsd ?? 0;
+            latencyMs = stratOut.latencyMs ?? Date.now() - taskT0;
+        }
+        catch (err) {
+            output = "";
+            rationale = `strategy.run threw: ${err instanceof Error ? err.message : String(err)}`;
+            latencyMs = Date.now() - taskT0;
+        }
+        const score = scoreTask(task, output);
+        results.push({
+            taskId: task.id,
+            category: task.category,
+            difficulty: task.difficulty,
+            passed: score >= 1,
+            output,
+            score,
+            latencyMs,
+            costUsd,
+            rationale,
+        });
+    }
+    const passed = results.filter((r) => r.passed).length;
+    const accuracy = dataset.length > 0 ? passed / dataset.length : 0;
+    const totalCost = results.reduce((s, r) => s + r.costUsd, 0);
+    const sortedLatencies = results.map((r) => r.latencyMs).sort((a, b) => a - b);
+    const medianLatency = sortedLatencies.length > 0
+        ? (sortedLatencies[Math.floor((sortedLatencies.length - 1) / 2)] ?? 0)
+        : 0;
+    return {
+        strategy: strategy.name,
+        accuracy,
+        costUsd: totalCost,
+        latencyMs: medianLatency,
+        rationale: results,
+        meta: {
+            totalTasks: dataset.length,
+            passedTasks: passed,
+            failedTasks: dataset.length - passed,
+            durationMs: Date.now() - t0,
+        },
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/evals/harness.js.map

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

package/dist/evals/index.d.ts

@@ -0,0 +1,5 @@
+export { evalSuite, scoreTask } from "./harness.js";
+export type { EvalStrategy, StrategyOutput, EvalTaskResult, EvalSuiteResult } from "./harness.js";
+export { EVAL_DATASET_30, getTasksByCategory, getTasksByDifficulty } from "./datasets/index.js";
+export type { EvalTask, EvalCategory, EvalDifficulty } from "./datasets/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/evals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChG,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/evals/index.js

@@ -0,0 +1,3 @@
+export { evalSuite, scoreTask } from "./harness.js";
+export { EVAL_DATASET_30, getTasksByCategory, getTasksByDifficulty } from "./datasets/index.js";
+//# sourceMappingURL=index.js.map

package/dist/evals/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/evals/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/factory/agent-factory.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 type { OODAAgent, OODAAgentConfig, 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";
+/**
+ * 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;
+}
+/**
+ * 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;
+    };
+}
+/**
+ * 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 declare 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>;
+//# sourceMappingURL=agent-factory.d.ts.map

package/dist/factory/agent-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-factory.d.ts","sourceRoot":"","sources":["../../src/factory/agent-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EAEf,YAAY,EACZ,SAAS,EACT,aAAa,EACd,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EAChB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAIlE;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAC3C;AAID;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CACjC,OAAO,GAAG,OAAO,EACjB,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,SAAS,GAAG,OAAO,EACnB,OAAO,GAAG,OAAO,EACjB,SAAS,GAAG,OAAO;IAEnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,MAAM,EAAE,eAAe,CACrB,OAAO,EACP,IAAI,EACJ,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS,CACV,CAAC,QAAQ,CAAC,CAAC;IACZ,iDAAiD;IACjD,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,mBAAmB;IACnB,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,yEAAyE;IACzE,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,aAAa,GAAG,IAAI,CAAC;IAC/D,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACzC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,GAAG,OAAO,EACjB,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,SAAS,GAAG,OAAO,EACnB,OAAO,GAAG,OAAO,EACjB,SAAS,GAAG,OAAO,EAEnB,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,kBAAkB,CACxB,OAAO,EACP,IAAI,EACJ,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS,CACV,GACA,OAAO,CAAC,SAAS,CAAC,CA4HpB"}

package/dist/factory/agent-factory.js

@@ -0,0 +1,119 @@
+/**
+ * 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";
+// ─── 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(deps, config) {
+    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) => {
+            // 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 = {
+        eventBus: deps.eventBus,
+        memory: deps.brain,
+        messaging: deps.messaging,
+    };
+    // 3. Build HITL waiter if messaging channel available and in live mode
+    let waitForHITL;
+    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) => {
+            const decisionPayload = ctx.payload ?? {};
+            // Skip HITL when act phase produced no actionable output
+            const hasActions = (Array.isArray(decisionPayload["actions"]) &&
+                decisionPayload["actions"].length > 0) ||
+                (typeof decisionPayload["action"] === "string" &&
+                    decisionPayload["action"].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"];
+            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) => {
+                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 = {
+        agentId,
+        agentVersion,
+        intervalMs,
+        executionMode: deps.executionMode,
+        config: config.defaults,
+        db: deps.db,
+        logger: deps.logger,
+        skills: deps.skills,
+        deps: oodaDeps,
+        phases,
+        sessionGuards: sessionGuards ?? [alwaysOn()],
+        riskGuards: riskGuards ?? [],
+        outcomeMapping,
+        resourceLimits: { phaseTimeoutMs: 300_000, maxStepsPerCycle: 20 },
+        waitForHITL,
+    };
+    // 5. Create and return agent
+    return createOODAAgent(oodaConfig);
+}
+//# sourceMappingURL=agent-factory.js.map

package/dist/factory/agent-factory.js.map

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

package/dist/hitl/api.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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";
+/** Framework-agnostic result returned by all HITL callback handlers. */
+export interface HITLHandlerResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Read the full body from a Node.js `IncomingMessage` stream.
+ * Returns the raw UTF-8 string (required for HMAC verification).
+ */
+export declare function collectBody(req: IncomingMessage): Promise<string>;
+/**
+ * Extract all headers from a Node `IncomingMessage` as a flat string map.
+ * Multi-value headers are joined with `, `.
+ */
+export declare function extractHeaders(req: IncomingMessage): Record<string, string>;
+/** 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 declare function parseCallbackData(raw: string): HITLCallbackData | null;
+//# sourceMappingURL=api.d.ts.map

package/dist/hitl/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/hitl/api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAIjD,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAOjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO3E;AAID,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAetE"}

package/dist/hitl/api.js

@@ -0,0 +1,58 @@
+/**
+ * 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
+ */
+// ─── 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) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => 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) {
+    const out = {};
+    for (const [key, val] of Object.entries(req.headers)) {
+        if (val == null)
+            continue;
+        out[key] = Array.isArray(val) ? val.join(", ") : val;
+    }
+    return out;
+}
+/**
+ * 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) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    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 };
+}
+//# sourceMappingURL=api.js.map

package/dist/hitl/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/hitl/api.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAoB;IAC9C,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACtE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAoB;IACjD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACrD,IAAI,GAAG,IAAI,IAAI;YAAE,SAAS;QAC1B,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEhE,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEnE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC3C,CAAC"}

package/dist/hitl/approval-channel.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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>;
+}
+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 declare class InMemoryApprovalStore implements ApprovalStore {
+    private readonly entries;
+    create(entry: PendingApproval): Promise<void>;
+    get(id: string): Promise<PendingApproval | null>;
+    resolve(id: string, verdict: Approval): Promise<boolean>;
+    cancel(id: string): Promise<boolean>;
+    expireOverdue(now?: number): Promise<number>;
+    /**
+     * 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, ...).
+     */
+    listAll(): Promise<readonly PendingApproval[]>;
+}
+//# sourceMappingURL=approval-channel.d.ts.map

package/dist/hitl/approval-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-channel.d.ts","sourceRoot":"","sources":["../../src/hitl/approval-channel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,2EAA2E;IAC3E,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC3C,wEAAwE;IACxE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAID,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAE/E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,eAAe,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,CAAC,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACjD,qEAAqE;IACrE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,0EAA0E;IAC1E,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAExD,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAKhD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAQxD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOpC,aAAa,CAAC,GAAG,SAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAWtD;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC;CAGrD"}

package/dist/hitl/approval-channel.js

@@ -0,0 +1,59 @@
+/**
+ * HITL approval-channel contract + in-memory store.
+ *
+ * Transport-agnostic: concrete transports live in concrete channel
+ * implementations (email, telegram, etc.).
+ */
+/**
+ * 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 {
+    entries = new Map();
+    async create(entry) {
+        if (this.entries.has(entry.id)) {
+            throw new Error(`approval: duplicate id ${entry.id}`);
+        }
+        this.entries.set(entry.id, { ...entry });
+    }
+    async get(id) {
+        const e = this.entries.get(id);
+        return e ? { ...e } : null;
+    }
+    async resolve(id, verdict) {
+        const e = this.entries.get(id);
+        if (!e || e.status !== "pending")
+            return false;
+        e.status = "resolved";
+        e.verdict = verdict;
+        return true;
+    }
+    async cancel(id) {
+        const e = this.entries.get(id);
+        if (!e || e.status !== "pending")
+            return false;
+        e.status = "cancelled";
+        return true;
+    }
+    async expireOverdue(now = Date.now()) {
+        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() {
+        return Array.from(this.entries.values(), (e) => ({ ...e }));
+    }
+}
+//# sourceMappingURL=approval-channel.js.map

package/dist/hitl/approval-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-channel.js","sourceRoot":"","sources":["../../src/hitl/approval-channel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmEH;;;;GAIG;AACH,MAAM,OAAO,qBAAqB;IACf,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE9D,KAAK,CAAC,MAAM,CAAC,KAAsB;QACjC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAU;QAClB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/B,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,OAAiB;QACzC,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAC/C,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC;QACtB,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAC/C,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;QAClC,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;gBAChD,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC;gBACtB,CAAC,IAAI,CAAC,CAAC;YACT,CAAC;QACH,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/hitl/callback-handlers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { 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 declare function createNodeSlackCallbackHandler(opts: SlackCallbackHandlerOpts): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=callback-handlers.d.ts.map

package/dist/hitl/callback-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-handlers.d.ts","sourceRoot":"","sources":["../../src/hitl/callback-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,KAAK,wBAAwB,EAC7B,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,KAAK,2BAA2B,GACjC,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAIlB,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,wBAAwB,GAC7B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAY9D"}