@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/server/src/model-proxy/auth-gate.ts

@@ -0,0 +1,116 @@
+/**
+ * Fastify onRequest hook for /v1/* proxy routes.
+ *
+ * Uniform API-key auth — no JWT, no bypass inheritance.
+ * See design.md Decision 2.
+ *
+ * See change: add-dashboard-model-proxy.
+ */
+import type { FastifyRequest, FastifyReply } from "fastify";
+import type { ModelProxyConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { findApiKey, keyHasScope, recordKeyUsage, type ProxyScope } from "./api-key-store.js";
+import { FailedAuthBackoff } from "./failed-auth-backoff.js";
+
+export interface AuthGateDeps {
+  getConfig: () => ModelProxyConfig;
+  persistKeyUsage?: (apiKeys: import("@blackbelt-technology/pi-dashboard-shared/config.js").ProxyApiKey[]) => void;
+}
+
+const PROXY_KEY_PREFIX = "pi-proxy-";
+
+function scopeForPath(url: string): ProxyScope {
+  if (url.startsWith("/v1/models")) return "models:list";
+  if (url.startsWith("/v1/messages")) return "messages";
+  return "chat"; // /v1/chat/completions and fallback
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function createModelProxyAuthGate(deps: AuthGateDeps) {
+  const backoff = new FailedAuthBackoff();
+
+  return async function modelProxyAuthGate(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    const url = request.url;
+    if (!url.startsWith("/v1/")) return; // not a proxy route
+
+    const authHeader = request.headers.authorization;
+
+    // Apply backoff delay before verification
+    const ip = request.ip;
+    const delay = backoff.getDelayMs(ip);
+    if (delay > 0) await sleep(delay);
+
+    // Missing authorization
+    if (!authHeader) {
+      backoff.record(ip);
+      return reply.code(401).send({ code: "AUTH_REQUIRED", message: "Authorization header required" });
+    }
+
+    // Extract bearer token
+    if (!authHeader.startsWith("Bearer ")) {
+      backoff.record(ip);
+      return reply.code(401).send({ code: "AUTH_MALFORMED", message: "Authorization must be Bearer token" });
+    }
+
+    const token = authHeader.slice(7);
+    if (!token) {
+      backoff.record(ip);
+      return reply.code(401).send({ code: "AUTH_MALFORMED", message: "Empty bearer token" });
+    }
+
+    // Reject non-proxy-key tokens (JWT or arbitrary)
+    if (!token.startsWith(PROXY_KEY_PREFIX)) {
+      backoff.record(ip);
+      return reply.code(401).send({
+        code: "PROXY_KEY_REQUIRED",
+        message: "Only proxy API keys (pi-proxy-*) are accepted for /v1/* routes",
+      });
+    }
+
+    // Look up the key
+    const config = deps.getConfig();
+    const result = findApiKey(token, config);
+
+    switch (result.kind) {
+      case "revoked":
+        backoff.record(ip);
+        return reply.code(401).send({ code: "AUTH_REVOKED", message: "API key has been revoked" });
+      case "expired":
+        backoff.record(ip);
+        return reply.code(401).send({ code: "AUTH_EXPIRED", message: "API key has expired" });
+      case "miss":
+        backoff.record(ip);
+        return reply.code(401).send({ code: "AUTH_REQUIRED", message: "Invalid API key" });
+      case "valid": {
+        // Scope check
+        const requiredScope = scopeForPath(url);
+        if (!keyHasScope(result.entry, requiredScope)) {
+          return reply.code(403).send({
+            code: "SCOPE_INSUFFICIENT",
+            required: requiredScope,
+            granted: result.entry.scopes ?? ["all"],
+          });
+        }
+
+        // Success — reset backoff + record usage
+        backoff.reset(ip);
+
+        // Record usage (debounced, fire-and-forget)
+        if (deps.persistKeyUsage) {
+          const { updated, apiKeys } = recordKeyUsage(result.entry.id, config.apiKeys);
+          if (updated) deps.persistKeyUsage(apiKeys);
+        }
+
+        // Attach key info to request for downstream handlers
+        (request as any).proxyApiKeyId = result.entry.id;
+        (request as any).proxyApiKeyLabel = result.entry.label;
+        return;
+      }
+    }
+  };
+}

package/packages/server/src/model-proxy/concurrency.ts

@@ -0,0 +1,76 @@
+/**
+ * Nested concurrency caps for the model proxy.
+ *
+ * Three levels: server-wide, per-API-key, per-upstream-provider.
+ * Caps read from config at acquire time so live config updates take effect.
+ *
+ * See change: add-dashboard-model-proxy.
+ */
+import type { ModelProxyConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+export type ConcurrencyErrorCode = "SERVER_FULL" | "KEY_FULL" | "PROVIDER_FULL";
+
+export class ConcurrencyError extends Error {
+  public readonly code: ConcurrencyErrorCode;
+  public readonly retryAfterMs: number;
+
+  constructor(code: ConcurrencyErrorCode, retryAfterMs = 1000) {
+    super(`Concurrency limit exceeded: ${code}`);
+    this.name = "ConcurrencyError";
+    this.code = code;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class ConcurrencyTracker {
+  private serverCount = 0;
+  private perKey = new Map<string, number>();
+  private perProvider = new Map<string, number>();
+
+  /**
+   * Acquire a concurrency slot. Returns a release() callback.
+   * Throws ConcurrencyError if any cap is exceeded.
+   */
+  acquire(
+    opts: { apiKeyId: string; provider: string },
+    config: ModelProxyConfig,
+  ): () => void {
+    const { apiKeyId, provider } = opts;
+
+    // Server-wide check
+    if (this.serverCount >= config.maxConcurrentStreams) {
+      throw new ConcurrencyError("SERVER_FULL");
+    }
+
+    // Per-key check
+    const keyCount = this.perKey.get(apiKeyId) ?? 0;
+    if (keyCount >= config.perKeyConcurrentStreams) {
+      throw new ConcurrencyError("KEY_FULL");
+    }
+
+    // Per-provider check
+    const providerCount = this.perProvider.get(provider) ?? 0;
+    const providerCap = config.perProviderCaps?.[provider] ?? 4;
+    if (providerCount >= providerCap) {
+      throw new ConcurrencyError("PROVIDER_FULL");
+    }
+
+    // Acquire all three
+    this.serverCount++;
+    this.perKey.set(apiKeyId, keyCount + 1);
+    this.perProvider.set(provider, providerCount + 1);
+
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.serverCount = Math.max(0, this.serverCount - 1);
+      const newKeyCount = Math.max(0, (this.perKey.get(apiKeyId) ?? 1) - 1);
+      if (newKeyCount === 0) this.perKey.delete(apiKeyId);
+      else this.perKey.set(apiKeyId, newKeyCount);
+      const newProviderCount = Math.max(0, (this.perProvider.get(provider) ?? 1) - 1);
+      if (newProviderCount === 0) this.perProvider.delete(provider);
+      else this.perProvider.set(provider, newProviderCount);
+    };
+  }
+}

package/packages/server/src/model-proxy/convert/UPSTREAM.md

@@ -0,0 +1,13 @@
+# Upstream Source
+
+Lifted from [BlackBeltTechnology/pi-model-proxy](https://github.com/BlackBeltTechnology/pi-model-proxy), MIT licensed.
+
+- **Commit:** 179d450 (v0.40.1)
+- **Lift date:** 2026-05-07
+- **pi-ai types version:** 0.73.0
+
+## Local Divergences
+
+1. **Type imports**: Upstream uses `import type { ... } from "@earendil-works/pi-ai"` — replaced with `any` since pi-ai is runtime-resolved. Local `types.ts` mirrors upstream's `../types.js` shapes.
+2. **Tab → 2-space indentation**: Matches dashboard's `.editorconfig`.
+3. **Lint**: Minor adjustments for dashboard's stricter `tsconfig` (no implicit any on some paths).

package/packages/server/src/model-proxy/convert/__tests__/anthropic-in.test.ts

@@ -0,0 +1,137 @@
+/* Ported from BlackBeltTechnology/pi-model-proxy@179d450 test suite.
+ * See model-proxy/convert/UPSTREAM.md for divergences.
+ */
+import { describe, it, expect } from "vitest";
+import { convertAnthropicMessages, convertAnthropicTools } from "../anthropic-in.js";
+
+describe("convertAnthropicMessages", () => {
+  it("string system prompt", () => {
+    const req = { system: "You are helpful.", messages: [{ role: "user", content: "hi" }] };
+    const { systemPrompt, messages } = convertAnthropicMessages(req as any);
+    expect(systemPrompt).toBe("You are helpful.");
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe("user");
+  });
+
+  it("array system prompt extracted as text", () => {
+    const req = {
+      system: [{ type: "text", text: "Part 1" }, { type: "text", text: "Part 2" }],
+      messages: [],
+    };
+    const { systemPrompt } = convertAnthropicMessages(req as any);
+    expect(systemPrompt).toBe("Part 1\nPart 2");
+  });
+
+  it("no system prompt", () => {
+    const req = { messages: [{ role: "user", content: "hi" }] };
+    const { systemPrompt } = convertAnthropicMessages(req as any);
+    expect(systemPrompt).toBeUndefined();
+  });
+
+  it("string user message", () => {
+    const req = { messages: [{ role: "user", content: "hello" }] };
+    const { messages } = convertAnthropicMessages(req as any);
+    expect(messages[0].role).toBe("user");
+    expect(messages[0].content).toBe("hello");
+  });
+
+  it("user message with text content blocks", () => {
+    const req = {
+      messages: [
+        { role: "user", content: [{ type: "text", text: "hello" }] },
+      ],
+    };
+    const { messages } = convertAnthropicMessages(req as any);
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe("user");
+    expect(messages[0].content).toBe("hello");
+  });
+
+  it("user message with image block", () => {
+    const req = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "what is this?" },
+            { type: "image", source: { media_type: "image/png", data: "abc123" } },
+          ],
+        },
+      ],
+    };
+    const { messages } = convertAnthropicMessages(req as any);
+    expect(Array.isArray(messages[0].content)).toBe(true);
+    const imgPart = (messages[0].content as any[]).find((p: any) => p.type === "image");
+    expect(imgPart?.mimeType).toBe("image/png");
+  });
+
+  it("tool_result block splits into toolResult message", () => {
+    const req = {
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "tool_result",
+              tool_use_id: "tu1",
+              content: "result",
+              is_error: false,
+            },
+          ],
+        },
+      ],
+    };
+    const { messages } = convertAnthropicMessages(req as any);
+    const toolResult = messages.find((m: any) => m.role === "toolResult");
+    expect(toolResult).toBeDefined();
+    expect(toolResult.toolCallId).toBe("tu1");
+    expect(toolResult.content[0].text).toBe("result");
+  });
+
+  it("assistant message with text", () => {
+    const req = {
+      messages: [
+        { role: "user", content: "hi" },
+        { role: "assistant", content: "hey there" },
+      ],
+    };
+    const { messages } = convertAnthropicMessages(req as any);
+    const assistant = messages.find((m: any) => m.role === "assistant");
+    expect(assistant).toBeDefined();
+    const textPart = assistant.content.find((c: any) => c.type === "text");
+    expect(textPart?.text).toBe("hey there");
+  });
+
+  it("assistant message with tool_use block", () => {
+    const req = {
+      messages: [
+        {
+          role: "assistant",
+          content: [
+            { type: "tool_use", id: "tu1", name: "my_fn", input: { x: 1 } },
+          ],
+        },
+      ],
+    };
+    const { messages } = convertAnthropicMessages(req as any);
+    const toolCall = messages[0].content.find((c: any) => c.type === "toolCall");
+    expect(toolCall).toBeDefined();
+    expect(toolCall.name).toBe("my_fn");
+    expect(toolCall.arguments).toEqual({ x: 1 });
+  });
+});
+
+describe("convertAnthropicTools", () => {
+  it("converts tool definitions", () => {
+    const tools = convertAnthropicTools([
+      { name: "search", description: "Search the web", input_schema: { type: "object", properties: {} } },
+    ]);
+    expect(tools[0].name).toBe("search");
+    expect(tools[0].description).toBe("Search the web");
+  });
+
+  it("handles missing description", () => {
+    const tools = convertAnthropicTools([{ name: "no_desc" } as any]);
+    expect(tools[0].description).toBe("");
+  });
+});

package/packages/server/src/model-proxy/convert/__tests__/anthropic-out.test.ts

@@ -0,0 +1,183 @@
+/* Ported from BlackBeltTechnology/pi-model-proxy@179d450 test suite.
+ * See model-proxy/convert/UPSTREAM.md for divergences.
+ */
+import { describe, it, expect } from "vitest";
+import { AnthropicBlockTracker, eventToAnthropicSSE, eventToAnthropicResponse } from "../anthropic-out.js";
+
+const MODEL = "anthropic/claude-3-5-sonnet";
+const MSG_ID = "msg_test";
+
+function parseSSELine(line: string): { eventType: string; data: any } {
+  const eventMatch = line.match(/^event: (.+)/m);
+  const dataMatch = line.match(/^data: (.+)/m);
+  const eventType = eventMatch?.[1] ?? "unknown";
+  const data = dataMatch ? JSON.parse(dataMatch[1]) : null;
+  return { eventType, data };
+}
+
+function makeTracker() {
+  return new AnthropicBlockTracker();
+}
+
+describe("AnthropicBlockTracker", () => {
+  it("starts at -1", () => {
+    const t = makeTracker();
+    expect(t.getCurrentIndex()).toBe(-1);
+  });
+
+  it("nextIndex increments and returns", () => {
+    const t = makeTracker();
+    expect(t.nextIndex()).toBe(0);
+    expect(t.nextIndex()).toBe(1);
+    expect(t.getCurrentIndex()).toBe(1);
+  });
+});
+
+describe("eventToAnthropicSSE", () => {
+  it("start emits message_start", () => {
+    const chunks = eventToAnthropicSSE({ type: "start" }, MODEL, MSG_ID, makeTracker());
+    expect(chunks).toHaveLength(1);
+    const { eventType, data } = parseSSELine(chunks[0]);
+    expect(eventType).toBe("message_start");
+    expect(data.message.id).toBe(MSG_ID);
+    expect(data.message.role).toBe("assistant");
+  });
+
+  it("text_delta without prior block emits content_block_start then delta", () => {
+    const tracker = makeTracker();
+    const chunks = eventToAnthropicSSE({ type: "text_delta", delta: "hello" }, MODEL, MSG_ID, tracker);
+    expect(chunks).toHaveLength(2);
+    const { eventType: et0 } = parseSSELine(chunks[0]);
+    const { eventType: et1, data: d1 } = parseSSELine(chunks[1]);
+    expect(et0).toBe("content_block_start");
+    expect(et1).toBe("content_block_delta");
+    expect(d1.delta.text).toBe("hello");
+  });
+
+  it("text_delta with existing block emits only delta", () => {
+    const tracker = makeTracker();
+    tracker.nextIndex(); // simulate existing block at index 0
+    const chunks = eventToAnthropicSSE({ type: "text_delta", delta: "more" }, MODEL, MSG_ID, tracker);
+    expect(chunks).toHaveLength(1);
+    const { eventType, data } = parseSSELine(chunks[0]);
+    expect(eventType).toBe("content_block_delta");
+    expect(data.delta.text).toBe("more");
+  });
+
+  it("thinking_delta emits thinking content_block_start + delta", () => {
+    const tracker = makeTracker();
+    const chunks = eventToAnthropicSSE({ type: "thinking_delta", delta: "hmm" }, MODEL, MSG_ID, tracker);
+    expect(chunks).toHaveLength(2);
+    const { data: startData } = parseSSELine(chunks[0]);
+    expect(startData.content_block.type).toBe("thinking");
+    const { data: deltaData } = parseSSELine(chunks[1]);
+    expect(deltaData.delta.type).toBe("thinking_delta");
+    expect(deltaData.delta.thinking).toBe("hmm");
+  });
+
+  it("toolcall_start closes prior block and opens tool_use block", () => {
+    const tracker = makeTracker();
+    tracker.nextIndex(); // prior block at 0
+    const event = {
+      type: "toolcall_start",
+      contentIndex: 0,
+      partial: { content: [{ type: "toolCall", id: "tc1", name: "my_fn" }] },
+    };
+    const chunks = eventToAnthropicSSE(event, MODEL, MSG_ID, tracker);
+    // Should emit content_block_stop + content_block_start
+    expect(chunks).toHaveLength(2);
+    const { eventType: et0 } = parseSSELine(chunks[0]);
+    const { eventType: et1, data: d1 } = parseSSELine(chunks[1]);
+    expect(et0).toBe("content_block_stop");
+    expect(et1).toBe("content_block_start");
+    expect(d1.content_block.type).toBe("tool_use");
+    expect(d1.content_block.name).toBe("my_fn");
+  });
+
+  it("toolcall_delta emits input_json_delta", () => {
+    const tracker = makeTracker();
+    tracker.nextIndex(); // block at 0
+    const chunks = eventToAnthropicSSE({ type: "toolcall_delta", delta: '{"x":' }, MODEL, MSG_ID, tracker);
+    expect(chunks).toHaveLength(1);
+    const { data } = parseSSELine(chunks[0]);
+    expect(data.delta.type).toBe("input_json_delta");
+    expect(data.delta.partial_json).toBe('{"x":');
+  });
+
+  it("done emits content_block_stop + message_delta + message_stop", () => {
+    const tracker = makeTracker();
+    tracker.nextIndex(); // block at 0
+    const msg = { stopReason: "stop", usage: { input: 10, output: 5 }, content: [] };
+    const chunks = eventToAnthropicSSE({ type: "done", message: msg }, MODEL, MSG_ID, tracker);
+    expect(chunks).toHaveLength(3);
+    const { eventType: et0 } = parseSSELine(chunks[0]);
+    const { eventType: et1, data: d1 } = parseSSELine(chunks[1]);
+    const { eventType: et2 } = parseSSELine(chunks[2]);
+    expect(et0).toBe("content_block_stop");
+    expect(et1).toBe("message_delta");
+    expect(d1.delta.stop_reason).toBe("end_turn");
+    expect(d1.usage.output_tokens).toBe(5);
+    expect(et2).toBe("message_stop");
+  });
+
+  it("done with stopReason=toolUse → stop_reason=tool_use", () => {
+    const tracker = makeTracker();
+    const msg = { stopReason: "toolUse", usage: { input: 0, output: 0 }, content: [] };
+    const chunks = eventToAnthropicSSE({ type: "done", message: msg }, MODEL, MSG_ID, tracker);
+    const messageDelta = chunks.find((c) => c.includes("message_delta"));
+    expect(messageDelta).toBeDefined();
+    const { data } = parseSSELine(messageDelta!);
+    expect(data.delta.stop_reason).toBe("tool_use");
+  });
+
+  it("done with stopReason=length → stop_reason=max_tokens", () => {
+    const tracker = makeTracker();
+    const msg = { stopReason: "length", usage: { input: 0, output: 0 }, content: [] };
+    const chunks = eventToAnthropicSSE({ type: "done", message: msg }, MODEL, MSG_ID, tracker);
+    const messageDelta = chunks.find((c) => c.includes("message_delta"));
+    const { data } = parseSSELine(messageDelta!);
+    expect(data.delta.stop_reason).toBe("max_tokens");
+  });
+
+  it("error emits error event", () => {
+    const chunks = eventToAnthropicSSE({ type: "error", error: { errorMessage: "fail" } }, MODEL, MSG_ID, makeTracker());
+    expect(chunks).toHaveLength(1);
+    const { eventType, data } = parseSSELine(chunks[0]);
+    expect(eventType).toBe("error");
+    expect(data.error.message).toBe("fail");
+  });
+});
+
+describe("eventToAnthropicResponse", () => {
+  it("text response", () => {
+    const msg = {
+      content: [{ type: "text", text: "hello" }],
+      stopReason: "stop",
+      usage: { input: 5, output: 3 },
+    };
+    const response = eventToAnthropicResponse(msg, MODEL, MSG_ID);
+    expect(response.id).toBe(MSG_ID);
+    expect(response.role).toBe("assistant");
+    expect(response.content[0]).toEqual({ type: "text", text: "hello" });
+    expect(response.stop_reason).toBe("end_turn");
+    expect(response.usage.input_tokens).toBe(5);
+  });
+
+  it("tool_use response", () => {
+    const msg = {
+      content: [{ type: "toolCall", id: "tc1", name: "fn", arguments: { x: 1 } }],
+      stopReason: "toolUse",
+      usage: { input: 5, output: 3 },
+    };
+    const response = eventToAnthropicResponse(msg, MODEL, MSG_ID);
+    expect(response.stop_reason).toBe("tool_use");
+    expect(response.content[0].type).toBe("tool_use");
+    expect(response.content[0].input).toEqual({ x: 1 });
+  });
+
+  it("max_tokens stop reason", () => {
+    const msg = { content: [], stopReason: "length", usage: { input: 1, output: 1 } };
+    const response = eventToAnthropicResponse(msg, MODEL, MSG_ID);
+    expect(response.stop_reason).toBe("max_tokens");
+  });
+});

package/packages/server/src/model-proxy/convert/__tests__/openai-in.test.ts

@@ -0,0 +1,134 @@
+/* Ported from BlackBeltTechnology/pi-model-proxy@179d450 test suite.
+ * See model-proxy/convert/UPSTREAM.md for divergences.
+ */
+import { describe, it, expect } from "vitest";
+import { convertOpenAIMessages, convertOpenAITools } from "../openai-in.js";
+
+describe("convertOpenAIMessages", () => {
+  it("plain user message", () => {
+    const { systemPrompt, messages } = convertOpenAIMessages([
+      { role: "user", content: "hello" },
+    ]);
+    expect(systemPrompt).toBeUndefined();
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe("user");
+    expect(messages[0].content).toBe("hello");
+  });
+
+  it("system message extracted as systemPrompt", () => {
+    const { systemPrompt, messages } = convertOpenAIMessages([
+      { role: "system", content: "You are helpful." },
+      { role: "user", content: "hi" },
+    ]);
+    expect(systemPrompt).toBe("You are helpful.");
+    expect(messages).toHaveLength(1);
+    expect(messages[0].role).toBe("user");
+  });
+
+  it("multiple system messages joined with newline", () => {
+    const { systemPrompt } = convertOpenAIMessages([
+      { role: "system", content: "Part 1." },
+      { role: "system", content: "Part 2." },
+    ]);
+    expect(systemPrompt).toBe("Part 1.\nPart 2.");
+  });
+
+  it("assistant message with text", () => {
+    const { messages } = convertOpenAIMessages([
+      { role: "user", content: "hi" },
+      { role: "assistant", content: "hey" },
+    ]);
+    expect(messages).toHaveLength(2);
+    expect(messages[1].role).toBe("assistant");
+    const textPart = messages[1].content.find((c: any) => c.type === "text");
+    expect(textPart?.text).toBe("hey");
+  });
+
+  it("assistant message with tool_calls", () => {
+    const { messages } = convertOpenAIMessages([
+      {
+        role: "assistant",
+        content: null,
+        tool_calls: [
+          { id: "tc1", type: "function", function: { name: "my_tool", arguments: '{"x":1}' } },
+        ],
+      },
+    ]);
+    expect(messages[0].role).toBe("assistant");
+    const toolCall = messages[0].content.find((c: any) => c.type === "toolCall");
+    expect(toolCall).toBeDefined();
+    expect(toolCall.name).toBe("my_tool");
+    expect(toolCall.arguments).toEqual({ x: 1 });
+    expect(toolCall.id).toBe("tc1");
+  });
+
+  it("tool result message", () => {
+    const { messages } = convertOpenAIMessages([
+      { role: "tool", content: "result text", tool_call_id: "tc1", name: "my_tool" },
+    ]);
+    expect(messages[0].role).toBe("toolResult");
+    expect(messages[0].toolCallId).toBe("tc1");
+    expect(messages[0].content[0].text).toBe("result text");
+  });
+
+  it("user message with image content part", () => {
+    const { messages } = convertOpenAIMessages([
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "what is this?" },
+          { type: "image_url", image_url: { url: "data:image/png;base64,abc123" } },
+        ],
+      },
+    ]);
+    const content = messages[0].content;
+    expect(Array.isArray(content)).toBe(true);
+    const imgPart = (content as any[]).find((p: any) => p.type === "image");
+    expect(imgPart).toBeDefined();
+    expect(imgPart.mimeType).toBe("image/png");
+    expect(imgPart.data).toBe("abc123");
+  });
+
+  it("user message with text-only content parts collapses to string", () => {
+    const { messages } = convertOpenAIMessages([
+      {
+        role: "user",
+        content: [{ type: "text", text: "just text" }],
+      },
+    ]);
+    expect(messages[0].content).toBe("just text");
+  });
+});
+
+describe("convertOpenAITools", () => {
+  it("converts tool definitions", () => {
+    const tools = convertOpenAITools([
+      {
+        type: "function",
+        function: {
+          name: "get_weather",
+          description: "Get the weather",
+          parameters: { type: "object", properties: { city: { type: "string" } } },
+        },
+      },
+    ]);
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe("get_weather");
+    expect(tools[0].description).toBe("Get the weather");
+    expect(tools[0].parameters.properties.city).toBeDefined();
+  });
+
+  it("handles missing description", () => {
+    const tools = convertOpenAITools([
+      { type: "function", function: { name: "no_desc" } },
+    ]);
+    expect(tools[0].description).toBe("");
+  });
+
+  it("handles missing parameters", () => {
+    const tools = convertOpenAITools([
+      { type: "function", function: { name: "no_params" } },
+    ]);
+    expect(tools[0].parameters).toEqual({ type: "object", properties: {} });
+  });
+});