@vauban-org/agent-sdk 0.16.0

package/dist/tracking/gen-ai.js

@@ -0,0 +1,101 @@
+/**
+ * tracking/gen-ai — OpenTelemetry GenAI semantic conventions wrapper.
+ *
+ * https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *
+ * Scope: thin helpers that create spans with the standard `gen_ai.*`
+ * attribute set. Each helper returns the span so the caller can add
+ * provider-specific attributes and call `.end()` when done — mirrors the
+ * `@opentelemetry/api` ergonomics.
+ *
+ * Custom Vauban attributes (not in spec):
+ *   - gen_ai.agent.run_id     (our runId; used for replay linkage)
+ *   - gen_ai.agent.compacted  (event marker — emitted by AgentLoop)
+ */
+import { trace } from "@opentelemetry/api";
+const TRACER_VERSION = "0.10.0";
+export function getTracer(name = "vauban-agent-sdk") {
+    return trace.getTracer(name, TRACER_VERSION);
+}
+// ─── LLM span ─────────────────────────────────────────────────────────────
+export function llmSpan(tracer, request) {
+    const span = tracer.startSpan(`gen_ai.${request.provider}.chat`);
+    span.setAttribute("gen_ai.operation.name", "chat");
+    span.setAttribute("gen_ai.system", request.provider);
+    span.setAttribute("gen_ai.request.model", request.model);
+    if (request.maxTokens !== undefined) {
+        span.setAttribute("gen_ai.request.max_tokens", request.maxTokens);
+    }
+    if (request.messageCount !== undefined) {
+        span.setAttribute("gen_ai.request.message_count", request.messageCount);
+    }
+    if (request.temperature !== undefined) {
+        span.setAttribute("gen_ai.request.temperature", request.temperature);
+    }
+    if (request.topP !== undefined) {
+        span.setAttribute("gen_ai.request.top_p", request.topP);
+    }
+    if (request.seed !== undefined) {
+        span.setAttribute("gen_ai.request.seed", request.seed);
+    }
+    return span;
+}
+export function recordLlmUsage(span, usage) {
+    span.setAttribute("gen_ai.usage.input_tokens", usage.inputTokens);
+    span.setAttribute("gen_ai.usage.output_tokens", usage.outputTokens);
+    span.setAttribute("gen_ai.latency_ms", usage.latencyMs);
+    if (usage.finishReason) {
+        span.setAttribute("gen_ai.response.finish_reasons", [usage.finishReason]);
+    }
+    if (usage.responseId) {
+        span.setAttribute("gen_ai.response.id", usage.responseId);
+    }
+}
+// ─── Tool span ────────────────────────────────────────────────────────────
+export function toolSpan(tracer, toolName, args) {
+    const span = tracer.startSpan(`gen_ai.tool.${toolName}`);
+    span.setAttribute("gen_ai.operation.name", "tool");
+    span.setAttribute("gen_ai.tool.name", toolName);
+    try {
+        const serialized = JSON.stringify(args);
+        if (typeof serialized === "string") {
+            // Cap to avoid attribute bloat.
+            span.setAttribute("gen_ai.tool.args_preview", serialized.slice(0, 500));
+        }
+    }
+    catch {
+        // Unserialisable args — skip the preview rather than fail the span.
+    }
+    return span;
+}
+export function recordToolResult(span, result) {
+    span.setAttribute("gen_ai.tool.success", result.success);
+    if (result.errorMessage) {
+        span.setAttribute("gen_ai.tool.error_message", result.errorMessage);
+    }
+    if (result.outputSizeBytes !== undefined) {
+        span.setAttribute("gen_ai.tool.output_size_bytes", result.outputSizeBytes);
+    }
+}
+// ─── Agent span ───────────────────────────────────────────────────────────
+export function agentSpan(tracer, opts) {
+    const span = tracer.startSpan(`gen_ai.agent.${opts.agentId}`);
+    span.setAttribute("gen_ai.operation.name", "agent");
+    span.setAttribute("gen_ai.agent.id", opts.agentId);
+    span.setAttribute("gen_ai.agent.version", opts.agentVersion);
+    span.setAttribute("gen_ai.agent.run_id", opts.runId);
+    return span;
+}
+/**
+ * recordOutcome — convenience helper to stamp the final outcome of an agent
+ * run onto an existing span. Call from the loop's finally block.
+ */
+export function recordOutcome(span, outcome) {
+    span.setAttribute("gen_ai.agent.stop_reason", outcome.stopReason);
+    span.setAttribute("gen_ai.usage.input_tokens", outcome.inputTokens);
+    span.setAttribute("gen_ai.usage.output_tokens", outcome.outputTokens);
+    if (outcome.stepCount !== undefined) {
+        span.setAttribute("gen_ai.agent.step_count", outcome.stepCount);
+    }
+}
+//# sourceMappingURL=gen-ai.js.map

package/dist/tracking/gen-ai.js.map

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

package/dist/tracking/index.d.ts

@@ -0,0 +1,4 @@
+export { createAgentRunTracker } from "./agent-run-tracker.js";
+export type { AgentRunTracker, AgentRunStartInput, AgentRunStepDelta, AgentRunFinish, AgentRunFinalStatus, DbClient, } from "./agent-run-tracker.js";
+export { getTracer, llmSpan, recordLlmUsage, toolSpan, recordToolResult, agentSpan, recordOutcome, } from "./gen-ai.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracking/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,QAAQ,GACT,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,SAAS,EACT,OAAO,EACP,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,SAAS,EACT,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/tracking/index.js

@@ -0,0 +1,3 @@
+export { createAgentRunTracker } from "./agent-run-tracker.js";
+export { getTracer, llmSpan, recordLlmUsage, toolSpan, recordToolResult, agentSpan, recordOutcome, } from "./gen-ai.js";
+//# sourceMappingURL=index.js.map

package/dist/tracking/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tracking/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAU/D,OAAO,EACL,SAAS,EACT,OAAO,EACP,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,SAAS,EACT,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/types/agent.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared agent types — promoted from Forge to SDK (Vague 1.B.1).
+ *
+ * These types are generic (no Forge-specific business logic) and safe to
+ * consume from any SDK consumer (CC, Forge, other agents).
+ *
+ * Forge-specific types (CitadelContactsPort outcome types, platform clients)
+ * remain in `forge/src/agents/shared/types.ts`.
+ *
+ * @public @since 0.17.0
+ */
+import type { BrainPort } from "../ports/brain.js";
+import type { LoggerPort } from "../ports/logger.js";
+import type { DbClient } from "../tracking/agent-run-tracker.js";
+import type { SkillRegistry } from "../orchestration/ooda/skills.js";
+import type { ExecutionMode } from "../orchestration/ooda/types.js";
+import type { EventBusPort } from "../ports/event-bus.js";
+/**
+ * EscalationLevel — four-tier escalation pyramid for agent actions.
+ *
+ * - `L0`: Fully autonomous, no human review.
+ * - `L1`: Autonomous with local audit log (L1_autonomous in CC SDK).
+ * - `L2`: Async review by a human before irreversible effects.
+ * - `L3`: Synchronous HITL (Human-In-The-Loop) approval required.
+ *
+ * Aligned with CC SDK EscalationPyramid terminology via `toSdkEscalationLevel()`.
+ */
+export type EscalationLevel = "L0" | "L1" | "L2" | "L3";
+/**
+ * AgentAction — declared in the OODA decide phase, consumed by EscalationPyramid.
+ *
+ * `estimatedCostCents` MUST be an integer (centimes). Never a float.
+ *
+ * @public
+ */
+export interface AgentAction {
+    /** Discriminant for the action type (e.g. "post_tweet", "record_outcome"). */
+    readonly type: string;
+    /** Escalation tier required before execution. */
+    readonly escalationLevel: EscalationLevel;
+    /** Whether this action can be undone after execution. */
+    readonly reversible: boolean;
+    /** Estimated cost in integer centimes (never float). Optional. */
+    readonly estimatedCostCents?: number;
+    /** Free-form action payload, validated by the consumer. */
+    readonly payload: Record<string, unknown>;
+}
+/**
+ * AgentDependencies — generic dependency bundle injected at agent construction.
+ *
+ * Only generic, host-level dependencies are included here. Forge-specific
+ * dependencies (xClient, farcasterClient, rempartClient, citadelContacts,
+ * platform webhooks) remain in Forge's local type extension.
+ *
+ * Consumer agents may extend this interface for their own extras:
+ * ```ts
+ * interface MyAgentDeps extends AgentDependencies {
+ *   myClient: MyClient;
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface AgentDependencies {
+    /** Brain memory port (working + episodic + semantic + procedural tiers). */
+    readonly brain: BrainPort;
+    /** Database client for run tracking and persistence. */
+    readonly db: DbClient;
+    /** Structured logger (Pino-compatible). */
+    readonly logger: LoggerPort;
+    /** Redis client (untyped — consumers cast to their redis client type). */
+    readonly redis: unknown;
+    /** Skill registry for OODA phases. */
+    readonly skills: SkillRegistry;
+    /** Execution mode: "dry-run" (no side-effects) or "live". */
+    readonly executionMode: ExecutionMode;
+    /** LiteLLM base URL for BYOM model routing. Optional. */
+    readonly litellmUrl?: string;
+    /** Database URL for direct Postgres access. Optional. */
+    readonly databaseUrl?: string;
+    /** Event bus for cross-product HMAC-signed events (ADR-ECO-017). Optional. */
+    readonly eventBus?: EventBusPort;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1D;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAIxD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAID;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;CAClC"}

package/dist/types/agent.js

@@ -0,0 +1,13 @@
+/**
+ * Shared agent types — promoted from Forge to SDK (Vague 1.B.1).
+ *
+ * These types are generic (no Forge-specific business logic) and safe to
+ * consume from any SDK consumer (CC, Forge, other agents).
+ *
+ * Forge-specific types (CitadelContactsPort outcome types, platform clients)
+ * remain in `forge/src/agents/shared/types.ts`.
+ *
+ * @public @since 0.17.0
+ */
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/types/agent.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for shared agent types (Vague 1.B.1).
+ *
+ * Verifies:
+ * - EscalationLevel exhaustiveness
+ * - AgentAction shape (no floats for cost)
+ * - AgentDependencies structural compatibility
+ * - toSdkEscalationLevel mapping correctness
+ */
+export {};
+//# sourceMappingURL=agent.test.d.ts.map

package/dist/types/agent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.test.d.ts","sourceRoot":"","sources":["../../src/types/agent.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/types/agent.test.js

@@ -0,0 +1,144 @@
+/**
+ * Tests for shared agent types (Vague 1.B.1).
+ *
+ * Verifies:
+ * - EscalationLevel exhaustiveness
+ * - AgentAction shape (no floats for cost)
+ * - AgentDependencies structural compatibility
+ * - toSdkEscalationLevel mapping correctness
+ */
+import { describe, expect, test } from "vitest";
+import { toSdkEscalationLevel, } from "./escalation-mapping.js";
+// ─── EscalationLevel ──────────────────────────────────────────────────────────
+describe("EscalationLevel", () => {
+    const allLevels = ["L0", "L1", "L2", "L3"];
+    test("covers 4 levels", () => {
+        expect(allLevels).toHaveLength(4);
+    });
+    test("all levels are strings", () => {
+        for (const level of allLevels) {
+            expect(typeof level).toBe("string");
+        }
+    });
+});
+// ─── toSdkEscalationLevel ─────────────────────────────────────────────────────
+describe("toSdkEscalationLevel", () => {
+    test("L0 → L1_autonomous", () => {
+        expect(toSdkEscalationLevel("L0")).toBe("L1_autonomous");
+    });
+    test("L1 → L1_autonomous (audit-logged, still autonomous)", () => {
+        expect(toSdkEscalationLevel("L1")).toBe("L1_autonomous");
+    });
+    test("L2 → L2_async_review", () => {
+        expect(toSdkEscalationLevel("L2")).toBe("L2_async_review");
+    });
+    test("L3 → L3_hitl_required", () => {
+        expect(toSdkEscalationLevel("L3")).toBe("L3_hitl_required");
+    });
+    test("return type is SdkEscalationLevel", () => {
+        const result = toSdkEscalationLevel("L2");
+        expect(result).toBe("L2_async_review");
+    });
+    test("exhaustive: all 4 levels map without throwing", () => {
+        const levels = ["L0", "L1", "L2", "L3"];
+        const validOutputs = [
+            "L1_autonomous",
+            "L2_async_review",
+            "L3_hitl_required",
+        ];
+        for (const level of levels) {
+            expect(validOutputs).toContain(toSdkEscalationLevel(level));
+        }
+    });
+});
+// ─── AgentAction ──────────────────────────────────────────────────────────────
+describe("AgentAction", () => {
+    test("minimal valid action (no optional fields)", () => {
+        const action = {
+            type: "post_tweet",
+            escalationLevel: "L1",
+            reversible: false,
+            payload: { text: "Hello" },
+        };
+        expect(action.type).toBe("post_tweet");
+        expect(action.escalationLevel).toBe("L1");
+        expect(action.reversible).toBe(false);
+        expect(action.payload).toEqual({ text: "Hello" });
+    });
+    test("action with estimatedCostCents (integer centimes)", () => {
+        const action = {
+            type: "record_outcome",
+            escalationLevel: "L0",
+            reversible: true,
+            estimatedCostCents: 100, // 1 EUR in centimes
+            payload: { outcome: "conversion" },
+        };
+        // Must be integer — verify no float slips through
+        expect(Number.isInteger(action.estimatedCostCents)).toBe(true);
+        expect(action.estimatedCostCents).toBe(100);
+    });
+    test("action with L3 escalation requires HITL", () => {
+        const action = {
+            type: "deploy_contract",
+            escalationLevel: "L3",
+            reversible: false,
+            payload: { contractAddress: "0x123" },
+        };
+        const sdkLevel = toSdkEscalationLevel(action.escalationLevel);
+        expect(sdkLevel).toBe("L3_hitl_required");
+    });
+});
+// ─── AgentDependencies structural test ───────────────────────────────────────
+describe("AgentDependencies", () => {
+    test("minimal implementation satisfies interface", () => {
+        // Build a minimal mock that satisfies the interface at type level.
+        // BrainPort requires only archiveKnowledge; optional tiers are omitted.
+        const mockDeps = {
+            brain: {
+                archiveKnowledge: async () => null,
+            },
+            db: {
+                query: async () => ({ rows: [] }),
+            },
+            logger: {
+                debug: () => { },
+                info: () => { },
+                warn: () => { },
+                error: () => { },
+            },
+            redis: null,
+            skills: {},
+            executionMode: "dry-run",
+        };
+        expect(mockDeps.executionMode).toBe("dry-run");
+        expect(mockDeps.redis).toBeNull();
+    });
+    test("optional fields can be omitted", () => {
+        const deps = {
+            brain: {},
+            db: {},
+            logger: {},
+            redis: null,
+            skills: {},
+            executionMode: "live",
+        };
+        expect(deps.litellmUrl).toBeUndefined();
+        expect(deps.databaseUrl).toBeUndefined();
+        expect(deps.eventBus).toBeUndefined();
+    });
+    test("optional fields can be provided", () => {
+        const deps = {
+            brain: {},
+            db: {},
+            logger: {},
+            redis: null,
+            skills: {},
+            executionMode: "live",
+            litellmUrl: "http://localhost:4000",
+            databaseUrl: "postgres://localhost/test",
+        };
+        expect(deps.litellmUrl).toBe("http://localhost:4000");
+        expect(deps.databaseUrl).toBe("postgres://localhost/test");
+    });
+});
+//# sourceMappingURL=agent.test.js.map

package/dist/types/agent.test.js.map

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

package/dist/types/escalation-mapping.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Escalation mapping helpers — Forge EscalationLevel → CC SDK pyramid levels.
+ *
+ * Promoted from Forge (Vague 1.B.1). Pure mapping, no external dependencies.
+ *
+ * @public @since 0.17.0
+ */
+import type { EscalationLevel } from "./agent.js";
+/**
+ * CC SDK EscalationPyramid level strings.
+ *
+ * - `L1_autonomous`: Fully autonomous execution (L0/L1 Forge).
+ * - `L2_async_review`: Async human review before irreversible effects (L2 Forge).
+ * - `L3_hitl_required`: Synchronous HITL approval required (L3 Forge).
+ */
+export type SdkEscalationLevel = "L1_autonomous" | "L2_async_review" | "L3_hitl_required";
+/**
+ * Map a Forge `EscalationLevel` to the CC SDK `EscalationPyramid` level.
+ *
+ * Both L0 and L1 map to `L1_autonomous` because Forge uses L0 for truly
+ * unchecked actions and L1 for audit-logged autonomous actions — both
+ * are autonomous from the CC SDK pyramid perspective.
+ *
+ * @example
+ * ```ts
+ * const sdkLevel = toSdkEscalationLevel("L2"); // "L2_async_review"
+ * ```
+ */
+export declare function toSdkEscalationLevel(level: EscalationLevel): SdkEscalationLevel;
+//# sourceMappingURL=escalation-mapping.d.ts.map

package/dist/types/escalation-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-mapping.d.ts","sourceRoot":"","sources":["../../src/types/escalation-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,GACrB,kBAAkB,CAWpB"}

package/dist/types/escalation-mapping.js

@@ -0,0 +1,32 @@
+/**
+ * Escalation mapping helpers — Forge EscalationLevel → CC SDK pyramid levels.
+ *
+ * Promoted from Forge (Vague 1.B.1). Pure mapping, no external dependencies.
+ *
+ * @public @since 0.17.0
+ */
+/**
+ * Map a Forge `EscalationLevel` to the CC SDK `EscalationPyramid` level.
+ *
+ * Both L0 and L1 map to `L1_autonomous` because Forge uses L0 for truly
+ * unchecked actions and L1 for audit-logged autonomous actions — both
+ * are autonomous from the CC SDK pyramid perspective.
+ *
+ * @example
+ * ```ts
+ * const sdkLevel = toSdkEscalationLevel("L2"); // "L2_async_review"
+ * ```
+ */
+export function toSdkEscalationLevel(level) {
+    switch (level) {
+        case "L0":
+            return "L1_autonomous";
+        case "L1":
+            return "L1_autonomous";
+        case "L2":
+            return "L2_async_review";
+        case "L3":
+            return "L3_hitl_required";
+    }
+}
+//# sourceMappingURL=escalation-mapping.js.map

package/dist/types/escalation-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation-mapping.js","sourceRoot":"","sources":["../../src/types/escalation-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAsB;IAEtB,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,IAAI;YACP,OAAO,eAAe,CAAC;QACzB,KAAK,IAAI;YACP,OAAO,eAAe,CAAC;QACzB,KAAK,IAAI;YACP,OAAO,iBAAiB,CAAC;QAC3B,KAAK,IAAI;YACP,OAAO,kBAAkB,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/docs/byom.md

@@ -0,0 +1,106 @@
+# BYOM — Bring Your Own Model
+
+The SDK ships **zero default LLM provider**. Every agent injects the concrete adapter it needs at boot via `AgentFactoryDeps.deps.llm`. This design is called the BYOM (Bring Your Own Model) axiom.
+
+**Why BYOM?** No model name is hardcoded in SDK source. Consumers can swap providers (LiteLLM, Anthropic Direct, custom) without touching agent logic. All cost accounting, circuit breaking, and streaming remain generic.
+
+## The `LLMProviderPort` interface
+
+```typescript
+import type { LLMProviderPort, ChatRequest, ChatResponse, StreamDelta } from "@vauban-org/agent-sdk";
+
+interface LLMProviderPort {
+  complete(req: ChatRequest): Promise<ChatResponse>;
+  stream?(req: ChatRequest): AsyncIterable<StreamDelta>;
+  estimateCost?(req: ChatRequest): { usd: number };
+}
+```
+
+See [ports/llm-provider.md](ports/llm-provider.md) for the full interface.
+
+---
+
+## LiteLLMAdapter
+
+Use when you self-host an LLM proxy (recommended for on-prem deployments, cost control, or model fallback).
+
+```typescript
+import { LiteLLMAdapter } from "@vauban-org/agent-sdk";
+import type { LiteLLMAdapterConfig } from "@vauban-org/agent-sdk";
+
+const llm = new LiteLLMAdapter({
+  baseUrl: process.env["LITELLM_URL"]!,
+  apiKey: process.env["LITELLM_API_KEY"],   // optional, defaults to "sk-sdk"
+  defaultModel: "qwen3-8b",                 // used when ChatRequest.model is absent
+} satisfies LiteLLMAdapterConfig);
+```
+
+**Features:**
+- OpenAI-compatible `/v1/chat/completions` endpoint
+- Retry on 429 with exponential back-off + jitter (max 3 attempts, no external dep)
+- Cost estimation from `usage.total_cost` when LiteLLM returns it
+
+---
+
+## AnthropicDirectAdapter
+
+Use for direct Anthropic API access (`@anthropic-ai/sdk` peer dep required).
+
+```typescript
+import { AnthropicDirectAdapter } from "@vauban-org/agent-sdk";
+import type { AnthropicDirectAdapterConfig } from "@vauban-org/agent-sdk";
+
+const llm = new AnthropicDirectAdapter({
+  apiKey: process.env["ANTHROPIC_API_KEY"]!,
+  defaultModel: "claude-sonnet-4-6",        // used when ChatRequest.model is absent
+} satisfies AnthropicDirectAdapterConfig);
+```
+
+**Features:**
+- Maps Anthropic `MessageParam` ↔ `ChatMessage` canonical format
+- Streaming via `AnthropicStream` → `StreamDelta`
+- Cost estimation at $3/MTok input, $15/MTok output (approximation)
+
+---
+
+## CascadeAdapter
+
+Use when you want automatic fallback across multiple providers.
+
+```typescript
+import { CascadeAdapter, LiteLLMAdapter, AnthropicDirectAdapter } from "@vauban-org/agent-sdk";
+import type { CascadeAdapterConfig } from "@vauban-org/agent-sdk";
+
+const llm = new CascadeAdapter({
+  providers: [
+    new LiteLLMAdapter({ baseUrl: process.env["LITELLM_URL"]! }),
+    new AnthropicDirectAdapter({ apiKey: process.env["ANTHROPIC_API_KEY"]! }),
+  ],
+} satisfies CascadeAdapterConfig);
+```
+
+The cascade tries each provider in order. On non-retryable error it falls through to the next. All providers return the same `ChatResponse` shape.
+
+---
+
+## Custom adapter
+
+Implement `LLMProviderPort` directly for any custom backend:
+
+```typescript
+import type { LLMProviderPort, ChatRequest, ChatResponse } from "@vauban-org/agent-sdk";
+
+class MyCustomLLM implements LLMProviderPort {
+  async complete(req: ChatRequest): Promise<ChatResponse> {
+    // ... call your API
+    return {
+      content: "response text",
+      usage: { inputTokens: 10, outputTokens: 20 },
+      model: "my-model-v1",
+      finishReason: "stop",
+    };
+  }
+}
+```
+
+**Rule:** Never implement `LLMProviderPort` by re-exporting a provider SDK directly in agent business logic. Always wrap in an adapter that conforms to this port.