@diabolicallabs/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @diabolicallabs/agent-sdk
+
+Cost-tracking middleware for `@diabolicallabs/llm-client`. Drop-in wrapper that captures call records and dispatches them asynchronously to the Agent Spend Dashboard. © Diabolical Labs
+
+**Pre-1.0. APIs may change between minor versions.**
+
+## Status
+
+**Scaffolded.** Types and public API surface are defined. Full implementation ships Week 4.
+
+## Install
+
+```bash
+pnpm add @diabolicallabs/agent-sdk @diabolicallabs/llm-client
+```
+
+## Usage
+
+```typescript
+import { createClientFromEnv } from '@diabolicallabs/llm-client';
+import { instrumentClient } from '@diabolicallabs/agent-sdk';
+
+const base = createClientFromEnv('anthropic', 'claude-sonnet-4-6');
+
+const client = instrumentClient(base, {
+  identity: { agentId: process.env.AGENT_ID!, taskLabel: 'geo-audit' },
+  ingestionUrl: process.env.SPEND_INGESTION_URL!,
+  ingestionKey: process.env.SPEND_INGESTION_KEY!,
+});
+
+// Identical API to LlmClient — instrumentation is invisible to the caller
+const response = await client.complete([
+  { role: 'user', content: 'Hello' },
+]);
+// CallRecord dispatched asynchronously — response returned immediately
+```
+
+## API
+
+### `instrumentClient(client, config): InstrumentedLlmClient`
+
+Wraps any `LlmClient` with cost-tracking middleware. The returned `InstrumentedLlmClient` is a drop-in replacement — it implements the same interface.
+
+**Config:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `identity.agentId` | `string` | required | UUID from Spend Dashboard agent registry |
+| `identity.taskLabel` | `string?` | — | Optional label for this call (max 200 chars) |
+| `identity.projectId` | `string?` | — | Optional project override |
+| `ingestionUrl` | `string` | required | Agent Spend Dashboard `/api/ingest` endpoint |
+| `ingestionKey` | `string` | required | Agent-scoped bearer token |
+| `maxIngestionRetries` | `number` | `3` | Retries before dropping the record |
+| `ingestionTimeoutMs` | `number` | `5000` | Ingestion request timeout — never blocks the LLM call |
+| `disabled` | `boolean` | `false` | Set `true` in test/dev to skip all instrumentation |
+
+## Ingestion contract
+
+Every LLM call produces a `CallRecord` dispatched to the ingestion URL:
+
+```typescript
+interface CallRecord {
+  agent_id: string;
+  model: string;
+  prompt_tokens: number;
+  completion_tokens: number;
+  cache_creation_tokens?: number; // Anthropic prompt cache only
+  cache_read_tokens?: number;     // Anthropic prompt cache only
+  latency_ms: number;
+  task_label?: string;
+  project_id?: string;
+  timestamp: string; // ISO 8601 UTC
+  call_id: string;   // UUID v4 — idempotency key
+}
+```
+
+## Failure behavior
+
+Ingestion failures are **always silent** — they never surface to the LLM caller.
+
+- Endpoint down or slow: retried up to `maxIngestionRetries` with exponential backoff
+- Retries exhausted: record dropped, structured warning logged (includes `call_id` for audit)
+- `disabled: true`: all instrumentation skipped, underlying client returned directly

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+import { LlmClient } from '@diabolicallabs/llm-client';
+
+/**
+ * Core type definitions for @diabolicallabs/agent-sdk.
+ * Matches the spec in briefs/brief-platform.md §4.2.
+ */
+
+interface AgentIdentity {
+    agentId: string;
+    taskLabel?: string;
+    projectId?: string;
+}
+interface AgentSdkConfig {
+    identity: AgentIdentity;
+    ingestionUrl: string;
+    ingestionKey: string;
+    maxIngestionRetries?: number;
+    ingestionTimeoutMs?: number;
+    disabled?: boolean;
+}
+interface InstrumentedLlmClient extends LlmClient {
+    readonly sdkConfig: Readonly<AgentSdkConfig>;
+}
+interface CallRecord {
+    agent_id: string;
+    model: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    cache_creation_tokens?: number;
+    cache_read_tokens?: number;
+    latency_ms: number;
+    task_label?: string;
+    project_id?: string;
+    timestamp: string;
+    call_id: string;
+}
+
+/**
+ * instrumentClient — wraps an LlmClient with cost-tracking middleware.
+ *
+ * Each call to complete(), stream(), or structured() is intercepted:
+ *  1. The LLM call executes normally.
+ *  2. A CallRecord is built from the response (tokens, latency, identifiers).
+ *  3. The record is dispatched to config.ingestionUrl asynchronously — the LLM
+ *     response is returned to the caller before ingestion completes.
+ *  4. Failed dispatches retry with exponential backoff up to maxIngestionRetries.
+ *  5. If all retries fail, the record is dropped and a structured warning is logged.
+ *     The error is never propagated to the LLM caller.
+ */
+
+/**
+ * Wraps an existing LlmClient with cost-tracking middleware.
+ * Returns an InstrumentedLlmClient that is a drop-in replacement for LlmClient.
+ *
+ * When config.disabled is true, the underlying client is returned directly
+ * with sdkConfig attached — no instrumentation overhead, no fetch calls.
+ */
+declare function instrumentClient(client: LlmClient, config: AgentSdkConfig): InstrumentedLlmClient;
+
+export { type AgentIdentity, type AgentSdkConfig, type CallRecord, type InstrumentedLlmClient, instrumentClient };

package/dist/index.js

@@ -0,0 +1,120 @@
+// src/sdk.ts
+function buildCallRecord(usage, model, latencyMs, config) {
+  return {
+    agent_id: config.identity.agentId,
+    model,
+    prompt_tokens: usage.inputTokens,
+    completion_tokens: usage.outputTokens,
+    ...usage.cacheCreationTokens !== void 0 && {
+      cache_creation_tokens: usage.cacheCreationTokens
+    },
+    ...usage.cacheReadTokens !== void 0 && {
+      cache_read_tokens: usage.cacheReadTokens
+    },
+    latency_ms: latencyMs,
+    ...config.identity.taskLabel !== void 0 && {
+      task_label: config.identity.taskLabel
+    },
+    ...config.identity.projectId !== void 0 && {
+      project_id: config.identity.projectId
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    call_id: crypto.randomUUID()
+  };
+}
+async function dispatchOnce(record, ingestionUrl, ingestionKey, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(ingestionUrl, {
+      method: "POST",
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${ingestionKey}`
+      },
+      body: JSON.stringify(record)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function dispatchWithRetry(record, config) {
+  const maxRetries = config.maxIngestionRetries ?? 3;
+  const timeoutMs = config.ingestionTimeoutMs ?? 5e3;
+  const baseDelayMs = 500;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const success = await dispatchOnce(record, config.ingestionUrl, config.ingestionKey, timeoutMs);
+    if (success) return;
+    if (attempt < maxRetries) {
+      const delay = baseDelayMs * 2 ** attempt;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  console.warn(
+    JSON.stringify({
+      level: "warn",
+      pkg: "@diabolicallabs/agent-sdk",
+      event: "ingestion_exhausted",
+      call_id: record.call_id,
+      agent_id: record.agent_id,
+      model: record.model,
+      message: `Ingestion dispatch failed after ${maxRetries + 1} attempts. Record dropped.`
+    })
+  );
+}
+function instrumentClient(client, config) {
+  if (config.disabled === true) {
+    return { ...client, sdkConfig: config };
+  }
+  async function complete(...args) {
+    const start = Date.now();
+    const response = await client.complete(...args);
+    const latencyMs = Date.now() - start;
+    const record = buildCallRecord(response.usage, response.model, latencyMs, config);
+    void dispatchWithRetry(record, config);
+    return response;
+  }
+  async function* stream(...args) {
+    let finalUsage;
+    const model = client.config.model;
+    const start = Date.now();
+    try {
+      for await (const chunk of client.stream(...args)) {
+        if (chunk.usage !== void 0) {
+          finalUsage = chunk.usage;
+        }
+        yield chunk;
+      }
+    } catch (err) {
+      throw err;
+    }
+    if (finalUsage !== void 0) {
+      const latencyMs = Date.now() - start;
+      const record = buildCallRecord(finalUsage, model, latencyMs, config);
+      void dispatchWithRetry(record, config);
+    }
+  }
+  async function structured(messages, schema, options) {
+    const start = Date.now();
+    const response = await client.structured(messages, schema, options);
+    const latencyMs = Date.now() - start;
+    const record = buildCallRecord(response.usage, client.config.model, latencyMs, config);
+    void dispatchWithRetry(record, config);
+    return response;
+  }
+  return {
+    config: client.config,
+    sdkConfig: config,
+    complete,
+    stream,
+    structured
+  };
+}
+export {
+  instrumentClient
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["/**\n * instrumentClient — wraps an LlmClient with cost-tracking middleware.\n *\n * Each call to complete(), stream(), or structured() is intercepted:\n *  1. The LLM call executes normally.\n *  2. A CallRecord is built from the response (tokens, latency, identifiers).\n *  3. The record is dispatched to config.ingestionUrl asynchronously — the LLM\n *     response is returned to the caller before ingestion completes.\n *  4. Failed dispatches retry with exponential backoff up to maxIngestionRetries.\n *  5. If all retries fail, the record is dropped and a structured warning is logged.\n *     The error is never propagated to the LLM caller.\n */\n\nimport type {\n  LlmClient,\n  LlmResponse,\n  LlmStreamChunk,\n  LlmStructuredResponse,\n  LlmUsage,\n} from '@diabolicallabs/llm-client';\nimport type { AgentSdkConfig, CallRecord, InstrumentedLlmClient } from './types.js';\n\n// ---------------------------------------------------------------------------\n// CallRecord builder\n// ---------------------------------------------------------------------------\n\n/**\n * Builds a CallRecord from normalized LlmUsage data.\n * call_id uses crypto.randomUUID() — Node 20 built-in, no external package.\n */\nfunction buildCallRecord(\n  usage: LlmUsage,\n  model: string,\n  latencyMs: number,\n  config: AgentSdkConfig\n): CallRecord {\n  return {\n    agent_id: config.identity.agentId,\n    model,\n    prompt_tokens: usage.inputTokens,\n    completion_tokens: usage.outputTokens,\n    ...(usage.cacheCreationTokens !== undefined && {\n      cache_creation_tokens: usage.cacheCreationTokens,\n    }),\n    ...(usage.cacheReadTokens !== undefined && {\n      cache_read_tokens: usage.cacheReadTokens,\n    }),\n    latency_ms: latencyMs,\n    ...(config.identity.taskLabel !== undefined && {\n      task_label: config.identity.taskLabel,\n    }),\n    ...(config.identity.projectId !== undefined && {\n      project_id: config.identity.projectId,\n    }),\n    timestamp: new Date().toISOString(),\n    call_id: crypto.randomUUID(),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Ingestion dispatch with retry\n// ---------------------------------------------------------------------------\n\n/**\n * Dispatches a single attempt to the ingestion endpoint.\n * Returns true on HTTP 2xx, false on any error (network, timeout, non-2xx).\n * Never throws — all errors are caught internally.\n */\nasync function dispatchOnce(\n  record: CallRecord,\n  ingestionUrl: string,\n  ingestionKey: string,\n  timeoutMs: number\n): Promise<boolean> {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), timeoutMs);\n  try {\n    const response = await fetch(ingestionUrl, {\n      method: 'POST',\n      signal: controller.signal,\n      headers: {\n        'Content-Type': 'application/json',\n        Authorization: `Bearer ${ingestionKey}`,\n      },\n      body: JSON.stringify(record),\n    });\n    return response.ok;\n  } catch {\n    // Network errors, AbortError (timeout), JSON stringify errors — all treated as failure\n    return false;\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Dispatches a CallRecord with exponential backoff retry.\n * On exhaustion, logs a structured warning and drops the record.\n * Never throws — ingestion errors are always silent to the LLM caller.\n */\nasync function dispatchWithRetry(record: CallRecord, config: AgentSdkConfig): Promise<void> {\n  const maxRetries = config.maxIngestionRetries ?? 3;\n  const timeoutMs = config.ingestionTimeoutMs ?? 5000;\n  const baseDelayMs = 500;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    const success = await dispatchOnce(record, config.ingestionUrl, config.ingestionKey, timeoutMs);\n    if (success) return;\n\n    if (attempt < maxRetries) {\n      // Exponential backoff: 500ms, 1000ms, 2000ms, ...\n      const delay = baseDelayMs * 2 ** attempt;\n      await new Promise<void>((resolve) => setTimeout(resolve, delay));\n    }\n  }\n\n  // All retries exhausted — drop the record and warn\n  // Structured log: include call_id for audit trail but never log ingestionKey\n  console.warn(\n    JSON.stringify({\n      level: 'warn',\n      pkg: '@diabolicallabs/agent-sdk',\n      event: 'ingestion_exhausted',\n      call_id: record.call_id,\n      agent_id: record.agent_id,\n      model: record.model,\n      message: `Ingestion dispatch failed after ${maxRetries + 1} attempts. Record dropped.`,\n    })\n  );\n}\n\n// ---------------------------------------------------------------------------\n// instrumentClient\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps an existing LlmClient with cost-tracking middleware.\n * Returns an InstrumentedLlmClient that is a drop-in replacement for LlmClient.\n *\n * When config.disabled is true, the underlying client is returned directly\n * with sdkConfig attached — no instrumentation overhead, no fetch calls.\n */\nexport function instrumentClient(client: LlmClient, config: AgentSdkConfig): InstrumentedLlmClient {\n  // Disabled mode: skip all instrumentation, expose underlying client directly\n  if (config.disabled === true) {\n    return { ...client, sdkConfig: config };\n  }\n\n  // complete() — non-streaming, usage available on the response\n  async function complete(...args: Parameters<LlmClient['complete']>): Promise<LlmResponse> {\n    const start = Date.now();\n    const response = await client.complete(...args);\n    const latencyMs = Date.now() - start;\n\n    const record = buildCallRecord(response.usage, response.model, latencyMs, config);\n    // Dispatch non-blocking — do not await\n    void dispatchWithRetry(record, config);\n\n    return response;\n  }\n\n  // stream() — async generator passthrough; usage arrives on final chunk\n  async function* stream(...args: Parameters<LlmClient['stream']>): AsyncGenerator<LlmStreamChunk> {\n    let finalUsage: LlmUsage | undefined;\n    const model = client.config.model;\n    const start = Date.now();\n\n    try {\n      for await (const chunk of client.stream(...args)) {\n        if (chunk.usage !== undefined) {\n          finalUsage = chunk.usage;\n        }\n        yield chunk; // pass through immediately — never buffer\n      }\n    } catch (err) {\n      // Stream error: no usage data, no record. Propagate to caller.\n      throw err;\n    }\n\n    // Stream completed — dispatch if usage was captured\n    if (finalUsage !== undefined) {\n      const latencyMs = Date.now() - start;\n      const record = buildCallRecord(finalUsage, model, latencyMs, config);\n      // Non-blocking — void the promise\n      void dispatchWithRetry(record, config);\n    }\n  }\n\n  // structured() — same pattern as complete(), usage on the structured response\n  async function structured<T>(\n    messages: Parameters<LlmClient['complete']>[0],\n    schema: { parse: (data: unknown) => T },\n    options?: Parameters<LlmClient['complete']>[1]\n  ): Promise<LlmStructuredResponse<T>> {\n    const start = Date.now();\n    const response = await client.structured<T>(messages, schema, options);\n    const latencyMs = Date.now() - start;\n\n    const record = buildCallRecord(response.usage, client.config.model, latencyMs, config);\n    void dispatchWithRetry(record, config);\n\n    return response;\n  }\n\n  return {\n    config: client.config,\n    sdkConfig: config,\n    complete,\n    stream,\n    structured,\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@diabolicallabs/agent-sdk",
+  "version": "0.1.0",
+  "description": "Cost-tracking middleware for @diabolicallabs/llm-client. Async fire-and-forget ingestion to Agent Spend Dashboard. © Diabolical Labs",
+  "author": "Diana Ismail <diana@deeismail.com> (https://deeismail.com)",
+  "publisher": "Diabolical Labs",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mannism/dlabs-toolkit.git",
+    "directory": "packages/agent-sdk"
+  },
+  "homepage": "https://github.com/mannism/dlabs-toolkit#readme",
+  "bugs": {
+    "url": "https://github.com/mannism/dlabs-toolkit/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@diabolicallabs/llm-client": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "tsup": "^8.3.5",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check ./src && eslint ./src",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}