@azmxailabs/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AZMX AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @azmxailabs/agent-sdk
+
+> Build approval-gated AI agents with the same primitives that power **[AZMX AI](https://azmx.ai)** — BYOK provider router, approval gate, deny-list, hash-chained audit log. Secure by default. BYOK direct (no proxy). No telemetry.
+
+```bash
+npm install @azmxailabs/agent-sdk
+```
+
+## Why this exists
+
+Most "AI agent" frameworks bolt safety on as middleware. AZMX builds it in. This SDK ships the four primitives that make that possible as standalone, dependency-free TypeScript so you can use them in your own agent — whether that's a CI script, a CLI, a desktop app, or a server.
+
+- **Approval gate** — every side-effecting action passes through a configurable policy chain before it runs.
+- **Deny-list** — refuses `.env`, `.ssh`, credentials, and any other path you care about by glob.
+- **Hash-chained audit log** — every entry includes the previous entry's hash; tampering breaks the chain detectably.
+- **Provider router** — one ergonomic interface across Anthropic, Ollama, and any other backend you plug in.
+
+Zero runtime dependencies. Node ≥ 18. ESM.
+
+## Quick start
+
+```ts
+import {
+  ApprovalGate,
+  standardPolicy,
+  destructiveShellDenyPolicy,
+  DenyList,
+  denyListPolicy,
+  HashChainedAuditLog,
+  ProviderRouter,
+  AnthropicProvider,
+  OllamaProvider,
+} from "@azmxailabs/agent-sdk";
+
+// 1. Audit log (hash-chained, tamper-evident)
+const log = new HashChainedAuditLog({ path: "./agent-audit.jsonl" });
+
+// 2. Deny-list (refuses sensitive paths)
+const deny = new DenyList(); // ships with sensible defaults
+
+// 3. Approval gate (the heart of the safety model)
+const gate = new ApprovalGate({
+  policies: [
+    denyListPolicy(deny),
+    destructiveShellDenyPolicy(),
+    standardPolicy(),
+  ],
+  onPrompt: async ({ action, reasons }) => {
+    // Your UI shows the action; user picks. Reasons = the policies that asked.
+    console.log(`\n[approval needed] ${action.kind}: ${action.summary}`);
+    console.log(`reasons: ${reasons.join(", ")}`);
+    // Real code: prompt the user. Here we auto-approve for the example.
+    return "approve";
+  },
+  onDecision: (event) => log.append({ type: "approval", ...event }),
+});
+
+// 4. Provider router (BYOK — direct, no proxy)
+const router = new ProviderRouter()
+  .register("claude", new AnthropicProvider({
+    apiKey: process.env.ANTHROPIC_API_KEY!,
+    model: "claude-opus-4-7",
+  }))
+  .register("local", new OllamaProvider({ model: "qwen2.5-coder:14b" }));
+
+// Use it
+const decision = await gate.check({
+  kind: "shell",
+  summary: "ls -la /tmp",
+  target: "/tmp",
+});
+
+if (decision === "approved") {
+  const result = await router.complete({
+    model: "claude",
+    messages: [{ role: "user", content: "Summarize what `ls -la` shows." }],
+  });
+  console.log(result.text);
+}
+
+// Verify the audit log later
+const verification = await log.verify();
+if (!verification.ok) {
+  console.error("Audit log tampered at seq", verification.brokenAtSeq);
+}
+```
+
+## API
+
+### `ApprovalGate`
+
+Every side-effecting action passes through here. Policies vote (`auto` / `ask` / `deny`); most-restrictive wins.
+
+```ts
+const gate = new ApprovalGate({
+  policies: [denyListPolicy(), destructiveShellDenyPolicy(), standardPolicy()],
+  onPrompt: async ({ action, reasons }) => "approve" | "approve-and-trust" | "reject",
+  onDecision: (event) => auditLog.append(event), // optional sink
+});
+
+const decision = await gate.check({
+  kind: "shell" | "file:write" | "file:read" | "file:delete" | "network" | "git" | "process:spawn" | "tool" | (string & {}),
+  summary: "human-readable one-liner",
+  target: "/path or URL",
+  payload: anyObject, // optional structured verb
+});
+// → "approved" | "denied"
+```
+
+**Built-in policies** (importable from `@azmxailabs/agent-sdk/approval`):
+
+| Policy | Behavior |
+|---|---|
+| `standardPolicy()` | The AZMX default. Reads auto; writes / deletes / shell / spawns ask; destructive shell verbs always ask. |
+| `paranoidPolicy()` | Asks for everything — even reads. For untrusted code, classified work, compliance demos. |
+| `permissivePolicy()` | Auto-approves everything. For trusted CI agents with their own external guardrails. |
+| `destructiveShellDenyPolicy(extra?)` | Hard-blocks `rm`, `dd`, `shutdown`, etc. — no prompt. Adds your verbs to the list. |
+
+### `DenyList` + `denyListPolicy`
+
+```ts
+import { DenyList, DEFAULT_DENY_LIST, denyListPolicy } from "@azmxailabs/agent-sdk/security";
+
+const deny = new DenyList(); // defaults: .env, .ssh, credentials, .aws/credentials, .kube/config, cookies, keychain files, ...
+deny.add("**/proprietary/**");
+deny.matches("/Users/me/.ssh/id_rsa"); // true
+deny.matching("/Users/me/.ssh/id_rsa"); // ["**/.ssh/**", "**/id_rsa"]
+
+// Plug into the gate:
+const policy = denyListPolicy(deny);
+```
+
+Globs: `*` (any chars except `/`), `**` (any chars), `?` (single char), `[abc]` (char class).
+
+### `HashChainedAuditLog`
+
+Append-only log where each entry's hash includes the previous entry's hash. Tampering with any past entry breaks the chain.
+
+```ts
+import { HashChainedAuditLog, FileStorage, InMemoryStorage } from "@azmxailabs/agent-sdk/audit";
+
+const log = new HashChainedAuditLog({ path: "./audit.jsonl" }); // FileStorage by default
+await log.append({ type: "shell", cmd: "ls -la /tmp" });
+await log.append({ type: "approval", decision: "approve" });
+
+const v = await log.verify();
+// v.ok === true  → all entries valid
+// v.ok === false → { brokenAtSeq, reason, expected?, found? }
+```
+
+Genesis prevHash = 64 zero bytes. Each entry's hash = `sha256(JSON.stringify({seq, ts, prevHash, data}))`. File mode is 0600.
+
+### `ProviderRouter`
+
+```ts
+import {
+  ProviderRouter,
+  AnthropicProvider,
+  OllamaProvider,
+} from "@azmxailabs/agent-sdk/providers";
+
+const router = new ProviderRouter()
+  .register("claude-fast", new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-haiku-4-5" }))
+  .register("claude-smart", new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-opus-4-7" }))
+  .register("local", new OllamaProvider({ model: "qwen2.5-coder:14b" }));
+
+const r = await router.complete({
+  model: "claude-fast",
+  messages: [
+    { role: "system", content: "You are concise." },
+    { role: "user", content: "Hello" },
+  ],
+  temperature: 0.2,
+  maxTokens: 200,
+});
+console.log(r.text, r.usage);
+
+// Streaming
+for await (const chunk of router.stream({ model: "local", messages: [...] })) {
+  process.stdout.write(chunk.delta);
+  if (chunk.done) console.log("\n[finishReason]", chunk.finishReason);
+}
+```
+
+**Built-in adapters:**
+
+| Adapter | API | BYOK / local |
+|---|---|---|
+| `AnthropicProvider` | POST `/v1/messages` | BYOK direct |
+| `OllamaProvider` | POST `/api/chat` | Local |
+
+**Adding your own:** implement the `Provider` interface — `name`, `complete`, `stream`. ~50 lines of code per provider; see `src/providers/ollama.ts` for a minimal reference.
+
+## Design choices
+
+- **No runtime dependencies.** Provider adapters call HTTP via `fetch` directly. Adding the official SDK for any provider is a 5-line wrapper at most — but the SDK doesn't need it.
+- **Approval is the first-class concept.** Every other primitive plugs into the gate (deny-list → policy; audit log → onDecision sink). The brand-DNA path is "gate then act."
+- **BYOK direct.** Provider adapters take an `apiKey` and call the provider's own endpoint. AZMX servers never see your prompts or tokens.
+- **Audit log is tamper-evident, not tamper-proof.** Hash chains prove that something changed — they don't prevent change. Pair with append-only storage (immutable S3 bucket, WORM volume) for hard guarantees.
+
+## Roadmap (v0.2+)
+
+- Tool / function-calling support across the provider interface
+- `OpenAIProvider` (covers OpenAI + most OpenAI-compatible APIs: Groq, Cerebras, xAI, DeepSeek, Azure, NVIDIA NIM)
+- `GoogleProvider` (Gemini)
+- An `MCPClient` for talking to MCP servers (`@modelcontextprotocol/sdk` wrapper)
+- Streaming tool calls
+- Cost tracking middleware
+
+File an issue at https://github.com/AzmxAI/azmx/issues if you want any of these prioritized — or open a PR.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## About AZMX AI
+
+AZMX AI is a native (~7 MB) AI coding agent that runs on your machine, with your keys (BYOK across 11+ providers, or fully offline via Ollama / LM Studio). Every write is gated by per-call approval. No account, no telemetry. Free forever for individuals.
+
+- Homepage: https://azmx.ai
+- Docs: https://azmx.ai/docs
+- MCP server: https://www.npmjs.com/package/@azmxailabs/mcp
+- Source: https://github.com/AzmxAI/azmx

package/dist/approval/gate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * ApprovalGate — every side-effecting action passes through here.
+ *
+ * The pattern AZMX uses in its desktop app: the agent never executes a
+ * shell command, writes a file, or hits the network until the action
+ * has been classified by every registered policy and approved by the
+ * user (or auto-approved if every policy returns "auto").
+ *
+ * Policies are pure functions: action → "auto" | "ask" | "deny". The
+ * gate aggregates them with the most-restrictive-wins rule: any "deny"
+ * blocks; any "ask" prompts the user; "auto" only fires if every
+ * policy agreed.
+ */
+export type ActionKind = "shell" | "file:write" | "file:read" | "file:delete" | "network" | "git" | "process:spawn" | "tool" | (string & {});
+export interface AgentAction {
+    /** Coarse category — used by policies for fast routing. */
+    kind: ActionKind;
+    /** One-line human summary shown to the user in the approval UI. */
+    summary: string;
+    /** Optional path / URL / target the action touches. */
+    target?: string;
+    /** Optional structured payload (the verb the agent staged). */
+    payload?: unknown;
+    /** Arbitrary metadata; passed through to policies + onPrompt. */
+    meta?: Record<string, unknown>;
+}
+export type PolicyDecision = "auto" | "ask" | "deny";
+export interface Policy {
+    /** Short stable identifier — appears in audit log + denial reason. */
+    name: string;
+    /** Pure classifier. Sync or async. Throw nothing. */
+    classify(action: AgentAction): PolicyDecision | Promise<PolicyDecision>;
+}
+export type UserDecision = "approve" | "approve-and-trust" | "reject";
+export interface PromptContext {
+    action: AgentAction;
+    /** Names of policies that returned "ask" — the reason we're prompting. */
+    reasons: string[];
+}
+export type PromptHandler = (ctx: PromptContext) => UserDecision | Promise<UserDecision>;
+export interface GateOptions {
+    policies?: Policy[];
+    /** Required when any policy returns "ask". */
+    onPrompt?: PromptHandler;
+    /** Optional sink — called on every decision (for audit log wiring). */
+    onDecision?: (event: DecisionEvent) => void | Promise<void>;
+}
+export interface DecisionEvent {
+    action: AgentAction;
+    classifications: Array<{
+        policy: string;
+        decision: PolicyDecision;
+    }>;
+    finalDecision: "approved" | "denied";
+    reason?: string;
+    timestamp: string;
+}
+export declare class ApprovalGate {
+    private policies;
+    private onPrompt?;
+    private onDecision?;
+    private trustedActions;
+    constructor(opts?: GateOptions);
+    /** Add a policy at runtime. Order doesn't matter — all policies vote. */
+    use(policy: Policy): void;
+    /**
+     * Classify + (if needed) prompt + return the final decision.
+     *
+     * Most-restrictive-wins:
+     *   any "deny" → "denied" without prompting.
+     *   any "ask"  → call onPrompt; user's reject → "denied".
+     *   all "auto" → "approved" without prompting.
+     */
+    check(action: AgentAction): Promise<"approved" | "denied">;
+    private finalize;
+    private trustKeyFor;
+}

package/dist/approval/gate.js

@@ -0,0 +1,92 @@
+/**
+ * ApprovalGate — every side-effecting action passes through here.
+ *
+ * The pattern AZMX uses in its desktop app: the agent never executes a
+ * shell command, writes a file, or hits the network until the action
+ * has been classified by every registered policy and approved by the
+ * user (or auto-approved if every policy returns "auto").
+ *
+ * Policies are pure functions: action → "auto" | "ask" | "deny". The
+ * gate aggregates them with the most-restrictive-wins rule: any "deny"
+ * blocks; any "ask" prompts the user; "auto" only fires if every
+ * policy agreed.
+ */
+export class ApprovalGate {
+    policies;
+    onPrompt;
+    onDecision;
+    trustedActions = new Set();
+    constructor(opts = {}) {
+        this.policies = opts.policies ?? [];
+        this.onPrompt = opts.onPrompt;
+        this.onDecision = opts.onDecision;
+    }
+    /** Add a policy at runtime. Order doesn't matter — all policies vote. */
+    use(policy) {
+        this.policies.push(policy);
+    }
+    /**
+     * Classify + (if needed) prompt + return the final decision.
+     *
+     * Most-restrictive-wins:
+     *   any "deny" → "denied" without prompting.
+     *   any "ask"  → call onPrompt; user's reject → "denied".
+     *   all "auto" → "approved" without prompting.
+     */
+    async check(action) {
+        const trustKey = this.trustKeyFor(action);
+        if (this.trustedActions.has(trustKey)) {
+            return this.finalize(action, [], "approved", "trusted-by-user");
+        }
+        const classifications = [];
+        for (const p of this.policies) {
+            const d = await p.classify(action);
+            classifications.push({ policy: p.name, decision: d });
+        }
+        const denials = classifications.filter((c) => c.decision === "deny");
+        if (denials.length > 0) {
+            const reason = `denied by policy: ${denials.map((d) => d.policy).join(", ")}`;
+            return this.finalize(action, classifications, "denied", reason);
+        }
+        const asks = classifications.filter((c) => c.decision === "ask");
+        if (asks.length === 0) {
+            return this.finalize(action, classifications, "approved", "auto-approved");
+        }
+        if (!this.onPrompt) {
+            const reason = `no onPrompt handler registered; asks=${asks.map((a) => a.policy).join(", ")}`;
+            return this.finalize(action, classifications, "denied", reason);
+        }
+        const user = await this.onPrompt({
+            action,
+            reasons: asks.map((a) => a.policy),
+        });
+        if (user === "reject") {
+            return this.finalize(action, classifications, "denied", "rejected by user");
+        }
+        if (user === "approve-and-trust") {
+            this.trustedActions.add(trustKey);
+        }
+        return this.finalize(action, classifications, "approved", `${user}-by-user`);
+    }
+    async finalize(action, classifications, finalDecision, reason) {
+        const event = {
+            action,
+            classifications,
+            finalDecision,
+            reason,
+            timestamp: new Date().toISOString(),
+        };
+        if (this.onDecision) {
+            try {
+                await this.onDecision(event);
+            }
+            catch {
+                // never let an audit sink failure mask the user's decision
+            }
+        }
+        return finalDecision;
+    }
+    trustKeyFor(action) {
+        return `${action.kind}::${action.target ?? ""}::${action.summary}`;
+    }
+}

package/dist/approval/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./gate.js";
+export * from "./policies.js";

package/dist/approval/index.js

@@ -0,0 +1,2 @@
+export * from "./gate.js";
+export * from "./policies.js";

package/dist/approval/policies.d.ts

@@ -0,0 +1,24 @@
+import type { Policy } from "./gate.js";
+/**
+ * Standard mode — the AZMX default.
+ *
+ * Reads (file:read, network GET-like) are auto-approved.
+ * Writes, deletes, shell, process spawns ask once per category-target.
+ * Destructive shell verbs (rm, dd, shutdown, etc.) always ask.
+ */
+export declare function standardPolicy(): Policy;
+/**
+ * Paranoid mode — ask for everything, even reads.
+ * Suitable for: untrusted codebases, classified work, compliance demos.
+ */
+export declare function paranoidPolicy(): Policy;
+/**
+ * Default-allow — opposite of paranoid. Useful for trusted CI agents
+ * with their own external guardrails. Use with deliberation.
+ */
+export declare function permissivePolicy(): Policy;
+/**
+ * Auto-deny a list of dangerous shell verbs regardless of approval flow.
+ * Use as an early stop-gap before standardPolicy / paranoidPolicy vote.
+ */
+export declare function destructiveShellDenyPolicy(extraVerbs?: string[]): Policy;

package/dist/approval/policies.js

@@ -0,0 +1,95 @@
+/**
+ * Standard mode — the AZMX default.
+ *
+ * Reads (file:read, network GET-like) are auto-approved.
+ * Writes, deletes, shell, process spawns ask once per category-target.
+ * Destructive shell verbs (rm, dd, shutdown, etc.) always ask.
+ */
+export function standardPolicy() {
+    return {
+        name: "standard",
+        classify(action) {
+            switch (action.kind) {
+                case "file:read":
+                    return "auto";
+                case "file:write":
+                case "file:delete":
+                case "git":
+                case "process:spawn":
+                    return "ask";
+                case "shell":
+                    return isDestructiveShell(action) ? "ask" : "ask";
+                case "network":
+                    return isReadOnlyNetwork(action) ? "auto" : "ask";
+                case "tool":
+                    return "ask";
+                default:
+                    return "ask";
+            }
+        },
+    };
+}
+/**
+ * Paranoid mode — ask for everything, even reads.
+ * Suitable for: untrusted codebases, classified work, compliance demos.
+ */
+export function paranoidPolicy() {
+    return {
+        name: "paranoid",
+        classify() {
+            return "ask";
+        },
+    };
+}
+/**
+ * Default-allow — opposite of paranoid. Useful for trusted CI agents
+ * with their own external guardrails. Use with deliberation.
+ */
+export function permissivePolicy() {
+    return {
+        name: "permissive",
+        classify() {
+            return "auto";
+        },
+    };
+}
+/**
+ * Auto-deny a list of dangerous shell verbs regardless of approval flow.
+ * Use as an early stop-gap before standardPolicy / paranoidPolicy vote.
+ */
+export function destructiveShellDenyPolicy(extraVerbs = []) {
+    const dangerous = new Set([
+        "rm",
+        "dd",
+        "mkfs",
+        "shutdown",
+        "reboot",
+        "halt",
+        "poweroff",
+        "fdisk",
+        "shred",
+        "chown",
+        "chmod",
+        ...extraVerbs.map((v) => v.toLowerCase()),
+    ]);
+    return {
+        name: "destructive-shell-deny",
+        classify(action) {
+            if (action.kind !== "shell")
+                return "auto";
+            const cmd = String(action.summary || "").trim().toLowerCase();
+            const first = cmd.split(/\s+/)[0] || "";
+            const verb = first.split("/").pop() || "";
+            return dangerous.has(verb) ? "deny" : "auto";
+        },
+    };
+}
+function isDestructiveShell(action) {
+    const cmd = String(action.summary || "").toLowerCase();
+    return /\b(rm|dd|shred|mkfs|shutdown|reboot|halt|poweroff|fdisk|chown|chmod)\b/.test(cmd);
+}
+function isReadOnlyNetwork(action) {
+    const meta = action.meta;
+    const method = String(meta?.method ?? "GET").toUpperCase();
+    return method === "GET" || method === "HEAD";
+}

package/dist/audit/index.d.ts

@@ -0,0 +1 @@
+export * from "./log.js";

package/dist/audit/index.js

@@ -0,0 +1 @@
+export * from "./log.js";

package/dist/audit/log.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+export interface AuditEntry {
+    seq: number;
+    ts: string;
+    prevHash: string;
+    hash: string;
+    data: unknown;
+}
+export interface AuditStorage {
+    read(): Promise<string>;
+    append(line: string): Promise<void>;
+}
+export declare class InMemoryStorage implements AuditStorage {
+    private buf;
+    read(): Promise<string>;
+    append(line: string): Promise<void>;
+    /** Test helper — corrupts an existing entry to verify detection works. */
+    tamper(replacer: (existing: string) => string): void;
+}
+export declare class FileStorage implements AuditStorage {
+    private path;
+    constructor(path: string);
+    read(): Promise<string>;
+    append(line: string): Promise<void>;
+}
+export interface AuditLogOptions {
+    storage?: AuditStorage;
+    /** File path; ignored if storage is provided. */
+    path?: string;
+}
+export declare class HashChainedAuditLog {
+    private storage;
+    private nextSeq;
+    private lastHash;
+    private bootstrapped;
+    constructor(opts?: AuditLogOptions);
+    /** Append a new entry, returning the resulting entry. Thread-safe per instance. */
+    append(data: unknown): Promise<AuditEntry>;
+    /**
+     * Walk every entry from genesis and recompute hashes. Returns:
+     *   { ok: true, count }  on success
+     *   { ok: false, brokenAtSeq, expected, found } on first breakage
+     */
+    verify(): Promise<VerifyResult>;
+    /** Read everything as parsed entries. Convenience for callers that need to display the log. */
+    entries(): Promise<AuditEntry[]>;
+    private bootstrap;
+}
+export type VerifyResult = {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    brokenAtSeq: number;
+    reason: string;
+    expected?: string;
+    found?: string;
+};