@azmxailabs/agent-sdk 0.1.0

package/dist/audit/log.js

@@ -0,0 +1,160 @@
+/**
+ * HashChainedAuditLog — append-only log where each entry's hash includes
+ * the previous entry's hash. Tampering with any past entry breaks the
+ * chain at that point and every entry after it.
+ *
+ * Format: JSON Lines (one entry per line). Each line is:
+ *   { "seq": N, "ts": "...", "prevHash": "...", "hash": "...", "data": {...} }
+ *
+ * Genesis entry has prevHash = "0".repeat(64).
+ *
+ * Storage adapters: file (Node only, default) or in-memory (for tests).
+ * Verify with verify() — walks from genesis, recomputes every hash.
+ */
+import { createHash } from "node:crypto";
+export class InMemoryStorage {
+    buf = "";
+    async read() {
+        return this.buf;
+    }
+    async append(line) {
+        this.buf += line + "\n";
+    }
+    /** Test helper — corrupts an existing entry to verify detection works. */
+    tamper(replacer) {
+        this.buf = replacer(this.buf);
+    }
+}
+export class FileStorage {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async read() {
+        const { readFile } = await import("node:fs/promises");
+        try {
+            return await readFile(this.path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return "";
+            throw err;
+        }
+    }
+    async append(line) {
+        const { appendFile, mkdir } = await import("node:fs/promises");
+        const { dirname } = await import("node:path");
+        await mkdir(dirname(this.path), { recursive: true });
+        await appendFile(this.path, line + "\n", { mode: 0o600 });
+    }
+}
+const GENESIS = "0".repeat(64);
+export class HashChainedAuditLog {
+    storage;
+    nextSeq = 0;
+    lastHash = GENESIS;
+    bootstrapped = false;
+    constructor(opts = {}) {
+        if (opts.storage) {
+            this.storage = opts.storage;
+        }
+        else if (opts.path) {
+            this.storage = new FileStorage(opts.path);
+        }
+        else {
+            this.storage = new InMemoryStorage();
+        }
+    }
+    /** Append a new entry, returning the resulting entry. Thread-safe per instance. */
+    async append(data) {
+        await this.bootstrap();
+        const seq = this.nextSeq;
+        const ts = new Date().toISOString();
+        const prevHash = this.lastHash;
+        const hash = hashEntry({ seq, ts, prevHash, data });
+        const entry = { seq, ts, prevHash, hash, data };
+        await this.storage.append(JSON.stringify(entry));
+        this.nextSeq = seq + 1;
+        this.lastHash = hash;
+        return entry;
+    }
+    /**
+     * Walk every entry from genesis and recompute hashes. Returns:
+     *   { ok: true, count }  on success
+     *   { ok: false, brokenAtSeq, expected, found } on first breakage
+     */
+    async verify() {
+        const text = await this.storage.read();
+        const lines = text.split("\n").filter((l) => l.trim().length > 0);
+        let prevHash = GENESIS;
+        let expectedSeq = 0;
+        for (const line of lines) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                return { ok: false, brokenAtSeq: expectedSeq, reason: "invalid JSON" };
+            }
+            if (entry.seq !== expectedSeq) {
+                return { ok: false, brokenAtSeq: expectedSeq, reason: `seq mismatch (got ${entry.seq})` };
+            }
+            if (entry.prevHash !== prevHash) {
+                return {
+                    ok: false,
+                    brokenAtSeq: entry.seq,
+                    reason: "prevHash mismatch",
+                    expected: prevHash,
+                    found: entry.prevHash,
+                };
+            }
+            const recomputed = hashEntry({
+                seq: entry.seq,
+                ts: entry.ts,
+                prevHash: entry.prevHash,
+                data: entry.data,
+            });
+            if (recomputed !== entry.hash) {
+                return {
+                    ok: false,
+                    brokenAtSeq: entry.seq,
+                    reason: "hash mismatch (entry was modified)",
+                    expected: recomputed,
+                    found: entry.hash,
+                };
+            }
+            prevHash = entry.hash;
+            expectedSeq += 1;
+        }
+        return { ok: true, count: expectedSeq };
+    }
+    /** Read everything as parsed entries. Convenience for callers that need to display the log. */
+    async entries() {
+        const text = await this.storage.read();
+        return text
+            .split("\n")
+            .filter((l) => l.trim().length > 0)
+            .map((l) => JSON.parse(l));
+    }
+    async bootstrap() {
+        if (this.bootstrapped)
+            return;
+        const text = await this.storage.read();
+        const lines = text.split("\n").filter((l) => l.trim().length > 0);
+        if (lines.length > 0) {
+            const last = JSON.parse(lines[lines.length - 1]);
+            this.nextSeq = last.seq + 1;
+            this.lastHash = last.hash;
+        }
+        this.bootstrapped = true;
+    }
+}
+function hashEntry(input) {
+    const canonical = JSON.stringify({
+        seq: input.seq,
+        ts: input.ts,
+        prevHash: input.prevHash,
+        data: input.data,
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @azmxailabs/agent-sdk — build approval-gated AI agents with the same
+ * primitives that power AZMX AI.
+ *
+ * Modular barrel: pull from sub-paths to keep your bundle tight.
+ *   import { ApprovalGate, standardPolicy } from "@azmxailabs/agent-sdk/approval";
+ *   import { DenyList, denyListPolicy } from "@azmxailabs/agent-sdk/security";
+ *   import { HashChainedAuditLog } from "@azmxailabs/agent-sdk/audit";
+ *   import { ProviderRouter, AnthropicProvider, OllamaProvider } from "@azmxailabs/agent-sdk/providers";
+ *
+ * Or import the everything-bundle from the root:
+ *   import { ApprovalGate, DenyList, ProviderRouter, ... } from "@azmxailabs/agent-sdk";
+ */
+export * from "./approval/index.js";
+export * from "./security/index.js";
+export * from "./audit/index.js";
+export * from "./providers/index.js";
+export declare const SDK_VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @azmxailabs/agent-sdk — build approval-gated AI agents with the same
+ * primitives that power AZMX AI.
+ *
+ * Modular barrel: pull from sub-paths to keep your bundle tight.
+ *   import { ApprovalGate, standardPolicy } from "@azmxailabs/agent-sdk/approval";
+ *   import { DenyList, denyListPolicy } from "@azmxailabs/agent-sdk/security";
+ *   import { HashChainedAuditLog } from "@azmxailabs/agent-sdk/audit";
+ *   import { ProviderRouter, AnthropicProvider, OllamaProvider } from "@azmxailabs/agent-sdk/providers";
+ *
+ * Or import the everything-bundle from the root:
+ *   import { ApprovalGate, DenyList, ProviderRouter, ... } from "@azmxailabs/agent-sdk";
+ */
+export * from "./approval/index.js";
+export * from "./security/index.js";
+export * from "./audit/index.js";
+export * from "./providers/index.js";
+export const SDK_VERSION = "0.1.0";

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,34 @@
+import type { ChatRequest, ChatResponse, Provider, StreamChunk } from "./types.js";
+export interface AnthropicProviderOptions {
+    apiKey: string;
+    /** Provider model id, e.g. "claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5". */
+    model: string;
+    /** Override the API host. Useful for proxies / on-prem gateways. */
+    baseUrl?: string;
+    /** Anthropic API version header. */
+    version?: string;
+    /** Default max_tokens — Anthropic requires this; caller can still override per-request. */
+    defaultMaxTokens?: number;
+    /** Custom fetch (for testing). */
+    fetch?: typeof fetch;
+}
+/**
+ * Anthropic Messages API adapter — POST /v1/messages.
+ *
+ * BYOK direct: requests go from the caller's machine straight to
+ * api.anthropic.com (or a custom baseUrl). No proxy via AZMX servers.
+ */
+export declare class AnthropicProvider implements Provider {
+    readonly name = "anthropic";
+    private apiKey;
+    private model;
+    private baseUrl;
+    private version;
+    private defaultMaxTokens;
+    private fetch;
+    constructor(opts: AnthropicProviderOptions);
+    complete(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): AsyncIterable<StreamChunk>;
+    private buildBody;
+    private headers;
+}

package/dist/providers/anthropic.js

@@ -0,0 +1,159 @@
+/**
+ * Anthropic Messages API adapter — POST /v1/messages.
+ *
+ * BYOK direct: requests go from the caller's machine straight to
+ * api.anthropic.com (or a custom baseUrl). No proxy via AZMX servers.
+ */
+export class AnthropicProvider {
+    name = "anthropic";
+    apiKey;
+    model;
+    baseUrl;
+    version;
+    defaultMaxTokens;
+    fetch;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error("AnthropicProvider: apiKey is required");
+        if (!opts.model)
+            throw new Error("AnthropicProvider: model is required");
+        this.apiKey = opts.apiKey;
+        this.model = opts.model;
+        this.baseUrl = (opts.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
+        this.version = opts.version ?? "2023-06-01";
+        this.defaultMaxTokens = opts.defaultMaxTokens ?? 4096;
+        this.fetch = opts.fetch ?? fetch;
+    }
+    async complete(req) {
+        const body = this.buildBody(req, false);
+        const res = await this.fetch(`${this.baseUrl}/v1/messages`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            signal: req.signal,
+        });
+        if (!res.ok)
+            throw await httpError(res);
+        const data = (await res.json());
+        const text = (data.content ?? [])
+            .filter((b) => b.type === "text")
+            .map((b) => b.text ?? "")
+            .join("");
+        return {
+            text,
+            finishReason: data.stop_reason ?? "stop",
+            usage: data.usage
+                ? {
+                    inputTokens: data.usage.input_tokens ?? 0,
+                    outputTokens: data.usage.output_tokens ?? 0,
+                    cacheReadTokens: data.usage.cache_read_input_tokens,
+                    cacheCreationTokens: data.usage.cache_creation_input_tokens,
+                }
+                : undefined,
+            raw: data,
+        };
+    }
+    async *stream(req) {
+        const body = this.buildBody(req, true);
+        const res = await this.fetch(`${this.baseUrl}/v1/messages`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+            signal: req.signal,
+        });
+        if (!res.ok)
+            throw await httpError(res);
+        if (!res.body)
+            throw new Error("AnthropicProvider: streaming response had no body");
+        let usage;
+        let finishReason;
+        for await (const event of sseLines(res.body)) {
+            if (!event.data)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(event.data);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.type === "content_block_delta" && parsed.delta?.type === "text_delta") {
+                yield { delta: parsed.delta.text ?? "" };
+            }
+            else if (parsed.type === "message_delta") {
+                if (parsed.delta?.stop_reason)
+                    finishReason = parsed.delta.stop_reason;
+                if (parsed.usage) {
+                    usage = {
+                        inputTokens: parsed.usage.input_tokens ?? 0,
+                        outputTokens: parsed.usage.output_tokens ?? 0,
+                        cacheReadTokens: parsed.usage.cache_read_input_tokens,
+                        cacheCreationTokens: parsed.usage.cache_creation_input_tokens,
+                    };
+                }
+            }
+            else if (parsed.type === "message_stop") {
+                yield { delta: "", done: true, finishReason: finishReason ?? "stop", usage };
+                return;
+            }
+        }
+        yield { delta: "", done: true, finishReason: finishReason ?? "stop", usage };
+    }
+    buildBody(req, stream) {
+        const system = req.messages.filter((m) => m.role === "system").map((m) => m.content).join("\n\n");
+        const messages = req.messages
+            .filter((m) => m.role !== "system")
+            .map((m) => ({ role: m.role, content: m.content }));
+        return {
+            model: this.model,
+            max_tokens: req.maxTokens ?? this.defaultMaxTokens,
+            temperature: req.temperature,
+            stop_sequences: req.stop,
+            system: system || undefined,
+            messages,
+            stream,
+            ...(req.providerOptions ?? {}),
+        };
+    }
+    headers() {
+        return {
+            "Content-Type": "application/json",
+            "x-api-key": this.apiKey,
+            "anthropic-version": this.version,
+        };
+    }
+}
+async function httpError(res) {
+    let body = "";
+    try {
+        body = await res.text();
+    }
+    catch {
+        /* ignore */
+    }
+    return new Error(`Anthropic HTTP ${res.status}: ${body.slice(0, 500)}`);
+}
+async function* sseLines(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buf.indexOf("\n\n")) !== -1) {
+            const chunk = buf.slice(0, nl);
+            buf = buf.slice(nl + 2);
+            const ev = { data: "" };
+            for (const line of chunk.split("\n")) {
+                if (line.startsWith("event:"))
+                    ev.event = line.slice(6).trim();
+                else if (line.startsWith("data:"))
+                    ev.data += line.slice(5).trim();
+            }
+            yield ev;
+        }
+    }
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./router.js";
+export * from "./anthropic.js";
+export * from "./ollama.js";

package/dist/providers/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./router.js";
+export * from "./anthropic.js";
+export * from "./ollama.js";

package/dist/providers/ollama.d.ts

@@ -0,0 +1,27 @@
+import type { ChatRequest, ChatResponse, Provider, StreamChunk } from "./types.js";
+export interface OllamaProviderOptions {
+    /** Provider model id, e.g. "llama3.2", "qwen2.5-coder:14b", "deepseek-r1". */
+    model: string;
+    /** Ollama server base URL. Default http://localhost:11434. */
+    baseUrl?: string;
+    /** Default options forwarded to Ollama's "options" field per request. */
+    defaultOptions?: Record<string, unknown>;
+    /** Custom fetch (for testing). */
+    fetch?: typeof fetch;
+}
+/**
+ * Ollama adapter — POST /api/chat.
+ *
+ * Fully local: no API key, no telemetry, no network leaves the box.
+ */
+export declare class OllamaProvider implements Provider {
+    readonly name = "ollama";
+    private model;
+    private baseUrl;
+    private defaultOptions;
+    private fetch;
+    constructor(opts: OllamaProviderOptions);
+    complete(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): AsyncIterable<StreamChunk>;
+    private buildBody;
+}

package/dist/providers/ollama.js

@@ -0,0 +1,125 @@
+/**
+ * Ollama adapter — POST /api/chat.
+ *
+ * Fully local: no API key, no telemetry, no network leaves the box.
+ */
+export class OllamaProvider {
+    name = "ollama";
+    model;
+    baseUrl;
+    defaultOptions;
+    fetch;
+    constructor(opts) {
+        if (!opts.model)
+            throw new Error("OllamaProvider: model is required");
+        this.model = opts.model;
+        this.baseUrl = (opts.baseUrl ?? "http://localhost:11434").replace(/\/+$/, "");
+        this.defaultOptions = opts.defaultOptions ?? {};
+        this.fetch = opts.fetch ?? fetch;
+    }
+    async complete(req) {
+        const body = this.buildBody(req, false);
+        const res = await this.fetch(`${this.baseUrl}/api/chat`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: req.signal,
+        });
+        if (!res.ok)
+            throw await httpError(res);
+        const data = (await res.json());
+        return {
+            text: data.message?.content ?? "",
+            finishReason: data.done_reason ?? (data.done ? "stop" : "length"),
+            usage: data.prompt_eval_count != null || data.eval_count != null
+                ? {
+                    inputTokens: data.prompt_eval_count ?? 0,
+                    outputTokens: data.eval_count ?? 0,
+                }
+                : undefined,
+            raw: data,
+        };
+    }
+    async *stream(req) {
+        const body = this.buildBody(req, true);
+        const res = await this.fetch(`${this.baseUrl}/api/chat`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: req.signal,
+        });
+        if (!res.ok)
+            throw await httpError(res);
+        if (!res.body)
+            throw new Error("OllamaProvider: streaming response had no body");
+        for await (const line of ndjsonLines(res.body)) {
+            let evt;
+            try {
+                evt = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const delta = evt.message?.content ?? "";
+            if (evt.done) {
+                yield {
+                    delta,
+                    done: true,
+                    finishReason: evt.done_reason ?? "stop",
+                    usage: evt.prompt_eval_count != null || evt.eval_count != null
+                        ? { inputTokens: evt.prompt_eval_count ?? 0, outputTokens: evt.eval_count ?? 0 }
+                        : undefined,
+                };
+                return;
+            }
+            else if (delta) {
+                yield { delta };
+            }
+        }
+    }
+    buildBody(req, stream) {
+        return {
+            model: this.model,
+            messages: req.messages.map((m) => ({ role: m.role, content: m.content })),
+            stream,
+            options: {
+                ...(this.defaultOptions ?? {}),
+                ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
+                ...(req.maxTokens !== undefined ? { num_predict: req.maxTokens } : {}),
+                ...(req.stop ? { stop: req.stop } : {}),
+                ...(req.providerOptions?.options ?? {}),
+            },
+            ...(req.providerOptions ?? {}),
+        };
+    }
+}
+async function httpError(res) {
+    let body = "";
+    try {
+        body = await res.text();
+    }
+    catch {
+        /* ignore */
+    }
+    return new Error(`Ollama HTTP ${res.status}: ${body.slice(0, 500)}`);
+}
+async function* ndjsonLines(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (line)
+                yield line;
+        }
+    }
+    if (buf.trim())
+        yield buf.trim();
+}

package/dist/providers/router.d.ts

@@ -0,0 +1,32 @@
+import type { ChatRequest, ChatResponse, Provider, StreamChunk } from "./types.js";
+/**
+ * ProviderRouter — register providers under stable alias names; route
+ * each ChatRequest to the right one. Keeps the rest of your code
+ * independent of which model you're using.
+ *
+ * Example:
+ *   const router = new ProviderRouter();
+ *   router.register("claude-fast", new AnthropicProvider({ apiKey: ..., model: "claude-haiku-4-5" }));
+ *   router.register("claude-smart", new AnthropicProvider({ apiKey: ..., model: "claude-opus-4-7" }));
+ *   router.register("local",        new OllamaProvider({ model: "qwen2.5-coder:14b" }));
+ *
+ *   const r = await router.complete({ model: "claude-fast", messages: [...] });
+ *   for await (const c of router.stream({ model: "local", messages: [...] })) { ... }
+ */
+export declare class ProviderRouter {
+    private providers;
+    private default?;
+    /** Register a provider under an alias used by ChatRequest.model. */
+    register(alias: string, provider: Provider, opts?: {
+        default?: boolean;
+    }): this;
+    /** Make `alias` the default. Used when ChatRequest.model is omitted. */
+    setDefault(alias: string): this;
+    /** All registered aliases. */
+    list(): string[];
+    /** Direct access to a registered provider. */
+    get(alias: string): Provider | undefined;
+    complete(req: ChatRequest): Promise<ChatResponse>;
+    stream(req: ChatRequest): AsyncIterable<StreamChunk>;
+    private resolve;
+}

package/dist/providers/router.js

@@ -0,0 +1,59 @@
+/**
+ * ProviderRouter — register providers under stable alias names; route
+ * each ChatRequest to the right one. Keeps the rest of your code
+ * independent of which model you're using.
+ *
+ * Example:
+ *   const router = new ProviderRouter();
+ *   router.register("claude-fast", new AnthropicProvider({ apiKey: ..., model: "claude-haiku-4-5" }));
+ *   router.register("claude-smart", new AnthropicProvider({ apiKey: ..., model: "claude-opus-4-7" }));
+ *   router.register("local",        new OllamaProvider({ model: "qwen2.5-coder:14b" }));
+ *
+ *   const r = await router.complete({ model: "claude-fast", messages: [...] });
+ *   for await (const c of router.stream({ model: "local", messages: [...] })) { ... }
+ */
+export class ProviderRouter {
+    providers = new Map();
+    default;
+    /** Register a provider under an alias used by ChatRequest.model. */
+    register(alias, provider, opts = {}) {
+        this.providers.set(alias, provider);
+        if (opts.default || this.providers.size === 1) {
+            this.default = alias;
+        }
+        return this;
+    }
+    /** Make `alias` the default. Used when ChatRequest.model is omitted. */
+    setDefault(alias) {
+        if (!this.providers.has(alias)) {
+            throw new Error(`ProviderRouter: cannot set default to "${alias}" — not registered`);
+        }
+        this.default = alias;
+        return this;
+    }
+    /** All registered aliases. */
+    list() {
+        return [...this.providers.keys()];
+    }
+    /** Direct access to a registered provider. */
+    get(alias) {
+        return this.providers.get(alias);
+    }
+    async complete(req) {
+        return this.resolve(req).complete(req);
+    }
+    async *stream(req) {
+        yield* this.resolve(req).stream(req);
+    }
+    resolve(req) {
+        const alias = req.model || this.default;
+        if (!alias) {
+            throw new Error("ProviderRouter: no model specified and no default registered");
+        }
+        const p = this.providers.get(alias);
+        if (!p) {
+            throw new Error(`ProviderRouter: no provider registered for "${alias}". Registered: ${this.list().join(", ") || "(none)"}`);
+        }
+        return p;
+    }
+}