mycomesh-consumer 0.9.13 → 0.9.15

package/networks/mycomesh-v11-sepolia.json

@@ -27,13 +27,14 @@
       "tier_name": "OpenAI frontier",
       "capabilities": {
         "input": [
-          "text"
+          "text",
+          "image"
         ],
         "output": [
           "text"
         ],
         "streaming": true,
-        "tools": false,
+        "tools": true,
         "dialects": [
           "openai-responses",
           "openai-chat",
@@ -50,13 +51,14 @@
       "tier_name": "Anthropic Claude",
       "capabilities": {
         "input": [
-          "text"
+          "text",
+          "image"
         ],
         "output": [
           "text"
         ],
         "streaming": true,
-        "tools": false,
+        "tools": true,
         "dialects": [
           "openai-responses",
           "openai-chat",
@@ -73,13 +75,14 @@
       "tier_name": "Anthropic Claude",
       "capabilities": {
         "input": [
-          "text"
+          "text",
+          "image"
         ],
         "output": [
           "text"
         ],
         "streaming": true,
-        "tools": false,
+        "tools": true,
         "dialects": [
           "openai-responses",
           "openai-chat",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mycomesh-consumer",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "MycoMesh V11 Consumer: a custodied deposit, relay-blind encrypted requests to any Provider, and a local OpenAI-compatible endpoint.",
   "repository": {
     "type": "git",

package/src/consumer.mjs

@@ -14,8 +14,8 @@ import { consoleRoutes, localRequestAllowed } from "./console.mjs";
 import { pinnedOptions, splitPin } from "./tlspin.mjs";
 import { compareRank, rankKey, reputation } from "./reputation.mjs";
 import { hashApiKey } from "./tenants.mjs";
-import { anthropicError, anthropicStream, fromAnthropic, fromGemini, geminiError, geminiRoute, geminiStream,
-  toAnthropic, toGemini } from "./dialects.mjs";
+import { anthropicError, anthropicStream, countAnthropicTokens, countGeminiTokens, fromAnthropic, fromGemini, fromResponses,
+  geminiError, geminiRoute, geminiStream, responsesUsesTools, toAnthropic, toGemini, toResponses } from "./dialects.mjs";
 
 // Discovery is served from cache and refreshed in the background once it is older than its fresh period; only
 // data older than its usable period (or none yet) makes a request wait for it.
@@ -43,6 +43,20 @@ class Cached {
   }
 }
 
+const MAX_REQUEST_BYTES = 7_500_000; // the sealed request must fit the network's 8 MB plaintext limit
+
+/** What a request asks a backend to read besides text: "image", "file". */
+export function inputKinds(content) {
+  const kinds = new Set();
+  for (const message of Array.isArray(content) ? content : []) {
+    for (const part of Array.isArray(message?.content) ? message.content : []) {
+      if (part?.type === "image_url" || part?.type === "input_image") kinds.add("image");
+      if (part?.type === "file" || part?.type === "input_file") kinds.add("file");
+    }
+  }
+  return [...kinds].sort();
+}
+
 // Session affinity: a conversation goes back to the Provider that answered its last turn, whose upstream
 // account holds the conversation's prompt cache (measured: a new Codex thread with the same 10k-token prefix
 // read 9,728 tokens from cache on the same account, none on another).
@@ -397,6 +411,12 @@ export class Consumer {
   async attempt({ endpoint, model, content, maxOutputTokens = 4096, options = {}, provider, session, onDelta }) {
     let lastError;
     let raisedFee = 0;
+    const size = Buffer.byteLength(JSON.stringify({ content, tools: options.tools ?? null }), "utf8");
+    if (size > MAX_REQUEST_BYTES) {
+      throw Object.assign(new Error(`this request is ${(size / 1e6).toFixed(1)} MB; the network carries up to ${MAX_REQUEST_BYTES / 1e6} MB (smaller or fewer images)`), { status: 413 });
+    }
+    const needs = inputKinds(content); // images and files go only to Providers whose backend reads them
+    let unreadable = false;
     const conversation = sessionKey({ endpoint, model, content, options, session });
     const preferred = this.stickyProvider(conversation);
     for (const relay of await this.relays()) {
@@ -404,6 +424,9 @@ export class Consumer {
       try {
         candidates = (await this.providers(relay)).filter((descriptor) => (descriptor.models || []).includes(model)
           && (!provider || descriptor.provider_signer === provider.toLowerCase()));
+        const able = candidates.filter((descriptor) => needs.every((kind) => (descriptor.inputs || ["text"]).includes(kind)));
+        if (able.length < candidates.length && !able.length) unreadable = true;
+        candidates = able;
       }
       catch (error) { lastError = error; continue; }
       const records = await this.reputations({ waitMs: REPUTATION_WAIT_MS }).catch(() => ({}));
@@ -412,7 +435,7 @@ export class Consumer {
       for (let index = 0; index < candidates.length; index += 1) {
         const descriptor = candidates[index];
         // Authorize what this request can really cost, not the Consumer's whole per-request cap.
-        const plan = planRequest(descriptor, endpoint, content, maxOutputTokens, this.maxFee);
+        const plan = planRequest(descriptor, endpoint, content, maxOutputTokens, this.maxFee, options.tools);
         const maxFee = Math.min(Number(this.maxFee), Math.max(raisedFee || 0, plan.maxFee));
         const prepared = prepareRequest({
           descriptor, deployment: this.deployment, keyPrivate: this.keyPrivate, relaySigner: relay.signer,
@@ -478,6 +501,9 @@ export class Consumer {
         if (reply.body?.dispatched !== false || ![502, 503].includes(reply.status)) throw lastError;
       }
     }
+    if (!lastError && unreadable) {
+      throw Object.assign(new Error(`no Provider online for ${model} reads ${needs.join(" and ")} input (Codex Providers read text and images, not files)`), { status: 400 });
+    }
     throw lastError || new Error(`no Provider serves model ${model}`);
   }
 }
@@ -501,14 +527,17 @@ async function readJson(req) {
 async function dialectRequest(req, res, active, path, setWriter) {
   const body = await readJson(req);
   const gemini = geminiRoute(path);
+  // Token counting (Claude Code and the Gemini CLI ask before long requests): an estimate, no request is sent.
+  const json = (value) => { res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" }); return res.end(JSON.stringify(value)); };
+  if (path === "/v1/messages/count_tokens") return json(countAnthropicTokens(body));
+  if (gemini?.count) return json(countGeminiTokens(body, gemini.model));
   const ask = gemini ? fromGemini(body, gemini.model) : fromAnthropic(body);
   const stream = gemini ? gemini.stream : ask.stream;
   const request = { endpoint: "chat", model: ask.model, content: ask.messages, maxOutputTokens: ask.maxOutputTokens, options: ask.options,
     session: ask.session || req.headers["x-claude-code-session-id"] || req.headers["session_id"] || req.headers["x-session-id"] || undefined };
   if (!stream) {
     const { response, receipt } = await active.request(request);
-    const answer = outputText(response.output);
-    const out = gemini ? toGemini(ask.model, answer, receipt.receipt) : toAnthropic(ask.model, answer, receipt.receipt);
+    const out = gemini ? toGemini(ask.model, response.output, receipt.receipt) : toAnthropic(ask.model, response.output, receipt.receipt);
     res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
     return res.end(JSON.stringify(out));
   }
@@ -520,7 +549,32 @@ async function dialectRequest(req, res, active, path, setWriter) {
   setWriter(writer);
   let streamedAny = false;
   const { response, receipt } = await active.request({ ...request, onDelta: (piece) => { streamedAny ||= Boolean(piece); writer.delta(piece); } });
-  writer.finish(outputText(response.output), receipt.receipt, streamedAny);
+  writer.finish(response.output, receipt.receipt, streamedAny);
+  return res.end();
+}
+
+/**
+ * Responses with tools (Codex CLI and other agents): translated to the network's chat shape and back, so the
+ * Provider sees one way of calling tools; the client gets function_call / custom_tool_call items to run.
+ */
+async function responsesWithTools(res, active, body, session, setWriter) {
+  const { model, stream } = body;
+  const { messages, options, custom } = fromResponses(body);
+  const maxOutputTokens = body.max_output_tokens ?? 4096;
+  const request = { endpoint: "chat", model, content: messages, maxOutputTokens, options, session };
+  if (!stream) {
+    const { response, receipt } = await active.request(request);
+    res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+    return res.end(JSON.stringify(toResponses(model, response.output, receipt.receipt, custom)));
+  }
+  const write = (text) => {
+    if (!res.headersSent) res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+    res.write(text);
+  };
+  const writer = responseStream(write, { model });
+  setWriter(writer);
+  const { response, receipt } = await active.request({ ...request, onDelta: (text) => writer.delta(text) });
+  writer.finish(toResponses(model, response.output, receipt.receipt, custom));
   return res.end();
 }
 
@@ -540,7 +594,7 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
     };
     try {
       const path = new URL(req.url, "http://localhost").pathname.replace(/^\/v1\/v1\//, "/v1/");
-      dialect = path === "/v1/messages" ? "anthropic" : geminiRoute(path) ? "gemini" : "openai";
+      dialect = path === "/v1/messages" || path === "/v1/messages/count_tokens" ? "anthropic" : geminiRoute(path) ? "gemini" : "openai";
       // A tenant's API key selects its own payment key and budget; tenants may call from anywhere.
       const tenant = /^\/v1(beta|alpha)?\//.test(path) && bearer(req) ? tenants()[hashApiKey(bearer(req))] : undefined;
       if (!tenant && !localRequestAllowed(req, server.address().port)) {
@@ -570,6 +624,8 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
       }
       const body = await readJson(req);
       const chat = path.endsWith("/chat/completions");
+      const session = req.headers["session_id"] || req.headers["x-session-id"] || undefined;
+      if (!chat && responsesUsesTools(body)) return await responsesWithTools(res, active, body, body.prompt_cache_key || session, (w) => { writer = w; });
       const { model, stream, stream_options: streamOptions, ...rest } = body;
       const content = chat ? rest.messages : rest.input;
       delete rest.messages;
@@ -578,7 +634,6 @@ export function serveConsumer(consumer, { host = "127.0.0.1", port = 8110, apiKe
       delete rest.max_output_tokens;
       delete rest.max_tokens;
       delete rest.max_completion_tokens;
-      const session = req.headers["session_id"] || req.headers["x-session-id"] || undefined;
       if (!stream) {
         const { response } = await active.request({ endpoint: chat ? "chat" : "responses", model, content, maxOutputTokens, options: rest, session });
         return send(200, response.output);

package/src/dialects.mjs

@@ -1,6 +1,7 @@
-// Client dialects for the local endpoint: Anthropic Messages and Gemini generateContent, translated to and
-// from the network's chat requests (OpenAI shape), streaming included. Token counts come from the
-// Provider-signed receipt, so every client sees what it was charged for.
+// Client dialects for the local endpoint: Anthropic Messages, Gemini generateContent and OpenAI Responses with
+// tools, translated to and from the network's one shape (OpenAI Chat Completions: tools, assistant tool_calls,
+// role "tool" results), streaming included. The Consumer's own client runs the tools; the network only carries
+// the calls and their results. Token counts come from the Provider-signed receipt.
 import { randomUUID } from "node:crypto";
 
 const id = (prefix) => `${prefix}${randomUUID().replace(/-/g, "")}`;
@@ -9,109 +10,349 @@ export class DialectError extends Error {
   constructor(message, status = 400) { super(message); this.status = status; }
 }
 
-/** Text of Anthropic or Gemini content: a string or text blocks/parts. Other block kinds are refused. */
+/**
+ * Content in the network's parts (OpenAI Chat): a string when it is all text, else text, image_url (a data: or
+ * https URL) and file (a data: URL and its filename) parts. Anthropic blocks, Responses inputs and Gemini parts
+ * all land here.
+ */
+export function parts(content, where) {
+  if (typeof content === "string" || content === undefined || content === null) return content ?? "";
+  if (!Array.isArray(content)) throw new DialectError(`${where}: content must be text`);
+  const out = [];
+  for (const part of content) {
+    const media = mediaPart(part);
+    if (media) out.push(media);
+    else { const words = text([part], where); if (words) out.push({ type: "text", text: words }); }
+  }
+  return out.every((p) => p.type === "text") ? out.map((p) => p.text).join("") : out;
+}
+
+const dataUrl = (mime, data) => `data:${mime || "application/octet-stream"};base64,${data}`;
+
+/** An image or document block of any dialect as a network part; null for text and the rest. */
+function mediaPart(part) {
+  if (!part || typeof part !== "object") return null;
+  if (part.type === "image" && part.source) {  // Anthropic
+    const url = part.source.type === "base64" ? dataUrl(part.source.media_type, part.source.data) : part.source.url;
+    return url ? { type: "image_url", image_url: { url } } : null;
+  }
+  if (part.type === "document" && part.source?.type === "base64") {
+    return { type: "file", file: { filename: part.title || "document.pdf", file_data: dataUrl(part.source.media_type, part.source.data) } };
+  }
+  if (part.type === "input_image" && (part.image_url || part.url)) return { type: "image_url", image_url: { url: part.image_url || part.url } };  // Responses
+  if (part.type === "input_file" && part.file_data) {
+    return { type: "file", file: { filename: part.filename || "file", file_data: part.file_data.startsWith("data:") ? part.file_data : dataUrl("application/pdf", part.file_data) } };
+  }
+  if (part.type === "image_url" && part.image_url) return { type: "image_url", image_url: { url: part.image_url.url || part.image_url } };  // Chat
+  if (part.type === "file" && part.file) return { type: "file", file: part.file };
+  if (part.inlineData?.data) {  // Gemini
+    const url = dataUrl(part.inlineData.mimeType, part.inlineData.data);
+    return part.inlineData.mimeType?.startsWith("image/") ? { type: "image_url", image_url: { url } }
+      : { type: "file", file: { filename: "file", file_data: url } };
+  }
+  return null;
+}
+
+/** The text of content (images and documents become a note): for places that can hold only text. */
 function text(content, where) {
   if (typeof content === "string") return content;
+  if (content === undefined || content === null) return "";
   if (!Array.isArray(content)) throw new DialectError(`${where}: content must be text`);
   return content.map((part) => {
     if (typeof part === "string") return part;
     if (part && typeof part.text === "string" && (part.type === undefined || part.type === "text")) return part.text;
     if (part?.type === "thinking" || part?.type === "redacted_thinking" || part?.thought) return "";
-    throw new DialectError(`${where}: only text content is supported (got ${part?.type || Object.keys(part || {})[0] || "unknown"})`);
+    if (part?.type === "image" || part?.inlineData || part?.type === "input_image" || part?.type === "image_url") return "[image]";
+    if (part?.type === "document") return part.source?.type === "text" ? String(part.source.data ?? "") : "[document]";
+    if (part?.type === "input_file" || part?.type === "file") return "[file]";
+    if (part?.type === "input_text" || part?.type === "output_text") return String(part.text ?? "");
+    throw new DialectError(`${where}: unsupported content (${part?.type || Object.keys(part || {})[0] || "unknown"})`);
   }).join("");
 }
 
-const unsupportedTools = (present) => {
-  if (present) throw new DialectError("tool use is not supported on this network yet; send text-only requests");
+const parseArguments = (value) => {
+  if (value && typeof value === "object") return value;
+  try { return JSON.parse(value || "{}"); } catch { return { input: String(value) }; }
 };
 
+/** The answer and tool calls of a network response (a chat completion). */
+export function answerOf(output) {
+  const choice = output?.choices?.[0] || {};
+  const message = choice.message || {};
+  return { text: typeof message.content === "string" ? message.content : "", calls: Array.isArray(message.tool_calls) ? message.tool_calls : [],
+    finish: choice.finish_reason || "stop" };
+}
+
 // ---------------- Anthropic Messages ----------------
 
-/** POST /v1/messages body -> { model, messages, maxOutputTokens, options, stream } */
+/** POST /v1/messages body -> { model, messages, maxOutputTokens, options, stream, session } */
 export function fromAnthropic(body) {
   if (typeof body.model !== "string" || !Array.isArray(body.messages)) throw new DialectError("model and messages are required");
-  unsupportedTools(body.tools?.length || body.tool_choice);
   const messages = [];
   if (body.system !== undefined) messages.push({ role: "system", content: text(body.system, "system") });
   for (const message of body.messages) {
-    if (!["user", "assistant"].includes(message?.role)) throw new DialectError("messages alternate user and assistant");
-    messages.push({ role: message.role, content: text(message.content, `${message.role} message`) });
+    if (message?.role === "system") { messages.push({ role: "system", content: text(message.content, "system message") }); continue; }
+    if (!["user", "assistant"].includes(message?.role)) throw new DialectError(`unsupported message role ${message?.role}`);
+    const blocks = typeof message.content === "string" ? [{ type: "text", text: message.content }] : message.content || [];
+    if (message.role === "assistant") {
+      const calls = blocks.filter((b) => b?.type === "tool_use").map((b) => ({ id: b.id, type: "function",
+        function: { name: b.name, arguments: JSON.stringify(b.input ?? {}) } }));
+      const words = text(blocks.filter((b) => b?.type !== "tool_use"), "assistant message");
+      messages.push({ role: "assistant", content: words || (calls.length ? null : ""), ...(calls.length ? { tool_calls: calls } : {}) });
+      continue;
+    }
+    // A user turn: tool results answer the previous assistant's calls; the rest is what the user said. A tool
+    // result can only be text, so images it returned (a screenshot Read) follow in a user message.
+    const shown = [];
+    for (const block of blocks.filter((b) => b?.type === "tool_result")) {
+      const content = Array.isArray(block.content) ? block.content : [{ type: "text", text: String(block.content ?? "") }];
+      const media = content.map(mediaPart).filter(Boolean);
+      const result = text(content.filter((b) => !mediaPart(b)), "tool_result") + (media.length ? `\n[${media.length} attachment(s) follow]` : "");
+      messages.push({ role: "tool", tool_call_id: block.tool_use_id, content: block.is_error ? `Error: ${result}` : result });
+      if (media.length) shown.push({ type: "text", text: `Attachments returned by tool call ${block.tool_use_id}:` }, ...media);
+    }
+    const rest = blocks.filter((b) => b?.type !== "tool_result");
+    const said = rest.length ? parts(rest, "user message") : "";
+    if (shown.length) messages.push({ role: "user", content: [...shown, ...(typeof said === "string" ? (said ? [{ type: "text", text: said }] : []) : said)] });
+    else if (rest.length || !blocks.length) messages.push({ role: "user", content: said });
   }
   const options = {};
   for (const key of ["temperature", "top_p"]) if (body[key] !== undefined) options[key] = body[key];
   if (body.stop_sequences) options.stop = body.stop_sequences;
-  // Claude Code puts its session in metadata.user_id: a conversation's turns share it.
-  const session = typeof body.metadata?.user_id === "string" ? body.metadata.user_id : undefined;
+  // The effort the user chose in the client (Claude Code: output_config.effort) is the model's reasoning effort.
+  const effort = body.output_config?.effort;
+  if (["minimal", "low", "medium", "high"].includes(effort)) options.reasoning_effort = effort;
+  const tools = (body.tools || []).filter((t) => t?.name && (t.type === undefined || t.type === "custom" || t.input_schema));
+  if (tools.length) {
+    options.tools = tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description || "",
+      parameters: t.input_schema || { type: "object", properties: {} } } }));
+    const choice = body.tool_choice;
+    if (choice?.type === "any") options.tool_choice = "required";
+    else if (choice?.type === "tool" && choice.name) options.tool_choice = { type: "function", function: { name: choice.name } };
+    else if (choice?.type === "none") options.tool_choice = "none";
+  }
+  // Claude Code puts its session in metadata.user_id (a JSON string with session_id): a conversation's turns share it.
+  let session = typeof body.metadata?.user_id === "string" ? body.metadata.user_id : undefined;
+  try { session = JSON.parse(session).session_id || session; } catch {}
   return { model: body.model, messages, maxOutputTokens: body.max_tokens ?? 4096, options, stream: body.stream === true, session };
 }
 
-export function toAnthropic(model, answer, receipt) {
+const anthropicStop = (answer) => answer.calls.length ? "tool_use" : answer.finish === "length" ? "max_tokens" : "end_turn";
+
+export function toAnthropic(model, output, receipt) {
+  const answer = answerOf(output);
+  const content = answer.text ? [{ type: "text", text: answer.text }] : [];
+  for (const call of answer.calls) content.push({ type: "tool_use", id: call.id, name: call.function?.name, input: parseArguments(call.function?.arguments) });
   return {
-    id: id("msg_"), type: "message", role: "assistant", model,
-    content: [{ type: "text", text: answer }], stop_reason: "end_turn", stop_sequence: null,
+    id: id("msg_"), type: "message", role: "assistant", model, content: content.length ? content : [{ type: "text", text: "" }],
+    stop_reason: anthropicStop(answer), stop_sequence: null,
     usage: { input_tokens: Number(receipt.input_tokens), output_tokens: Number(receipt.output_tokens) },
   };
 }
 
-/** Anthropic's SSE event sequence, fed with text as it arrives. */
+/** Anthropic's SSE event sequence: text as it arrives, then tool_use blocks when the verified answer is in. */
 export function anthropicStream(write, model) {
   const event = (type, data) => write(`event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`);
   let started = false;
+  let textOpen = false;
+  let index = 0;
   const start = () => {
     if (started) return;
     started = true;
     event("message_start", { message: { id: id("msg_"), type: "message", role: "assistant", model, content: [],
       stop_reason: null, stop_sequence: null, usage: { input_tokens: 0, output_tokens: 0 } } });
-    event("content_block_start", { index: 0, content_block: { type: "text", text: "" } });
+  };
+  const openText = () => {
+    if (textOpen) return;
+    textOpen = true;
+    event("content_block_start", { index, content_block: { type: "text", text: "" } });
   };
   return {
-    delta(piece) { start(); if (piece) event("content_block_delta", { index: 0, delta: { type: "text_delta", text: piece } }); },
-    finish(answer, receipt, streamedAny) {
+    delta(piece) {
       start();
-      if (!streamedAny && answer) event("content_block_delta", { index: 0, delta: { type: "text_delta", text: answer } });
-      event("content_block_stop", { index: 0 });
-      event("message_delta", { delta: { stop_reason: "end_turn", stop_sequence: null },
+      if (!piece) return;
+      openText();
+      event("content_block_delta", { index, delta: { type: "text_delta", text: piece } });
+    },
+    finish(output, receipt, streamedAny) {
+      start();
+      const answer = answerOf(output);
+      if (!streamedAny && answer.text) { openText(); event("content_block_delta", { index, delta: { type: "text_delta", text: answer.text } }); }
+      if (!textOpen && !answer.calls.length) openText();
+      if (textOpen) { event("content_block_stop", { index }); index += 1; }
+      for (const call of answer.calls) {
+        event("content_block_start", { index, content_block: { type: "tool_use", id: call.id, name: call.function?.name, input: {} } });
+        event("content_block_delta", { index, delta: { type: "input_json_delta", partial_json: JSON.stringify(parseArguments(call.function?.arguments)) } });
+        event("content_block_stop", { index });
+        index += 1;
+      }
+      event("message_delta", { delta: { stop_reason: anthropicStop(answer), stop_sequence: null },
         usage: { input_tokens: Number(receipt.input_tokens), output_tokens: Number(receipt.output_tokens) } });
       event("message_stop", {});
     },
-    fail(message) { event("error", { error: { type: "api_error", message } }); },
+    fail(message) { start(); event("error", { error: { type: "api_error", message } }); },
   };
 }
 
+/** /v1/messages/count_tokens: an upper-bound estimate (UTF-8 bytes / 3, as prices are authorized). */
+export function countAnthropicTokens(body) {
+  const ask = fromAnthropic({ max_tokens: 1, ...body });
+  const bytes = Buffer.byteLength(JSON.stringify(ask.messages), "utf8") + Buffer.byteLength(JSON.stringify(ask.options.tools || []), "utf8");
+  return { input_tokens: Math.ceil(bytes / 3) };
+}
+
 export const anthropicError = (message, status) => ({ type: "error", error: {
   type: status === 401 || status === 403 ? "authentication_error" : status === 404 ? "not_found_error"
     : status === 402 ? "billing_error" : status >= 500 ? "api_error" : "invalid_request_error", message } });
 
+// ---------------- OpenAI Responses (with tools) ----------------
+
+/** Whether a Responses request needs the tool translation (tools, or tool calls and results in its input). */
+export function responsesUsesTools(body) {
+  return (Array.isArray(body.tools) && body.tools.length > 0)
+    || (Array.isArray(body.input) && body.input.some((item) => /^(function_call|custom_tool_call)/.test(item?.type || "")));
+}
+
+/** POST /v1/responses body with tools -> { messages, options, custom } (custom: names of freeform tools). */
+export function fromResponses(body) {
+  const messages = [];
+  if (body.instructions) messages.push({ role: "system", content: String(body.instructions) });
+  const custom = new Set();
+  const tools = [];
+  for (const tool of body.tools || []) {
+    if (tool?.type === "function" && tool.name) {
+      tools.push({ type: "function", function: { name: tool.name, description: tool.description || "", parameters: tool.parameters || { type: "object", properties: {} } } });
+    } else if (tool?.type === "custom" && tool.name) {
+      // A freeform tool (Codex's apply_patch): one string argument carries its whole input.
+      custom.add(tool.name);
+      tools.push({ type: "function", function: { name: tool.name, description: `${tool.description || ""}\nPut the tool's complete raw input in the "input" string.`,
+        parameters: { type: "object", properties: { input: { type: "string" } }, required: ["input"] } } });
+    } // hosted tools (web search, file search, ...) cannot run on this network: they are left out
+  }
+  const input = typeof body.input === "string" ? [{ role: "user", content: body.input }] : body.input || [];
+  const assistant = () => {
+    const last = messages.at(-1);
+    if (last?.role === "assistant") return last;
+    const fresh = { role: "assistant", content: null, tool_calls: [] };
+    messages.push(fresh);
+    return fresh;
+  };
+  for (const item of input) {
+    const type = item?.type || (item?.role ? "message" : "");
+    if (type === "message") {
+      const role = item.role === "developer" ? "system" : item.role;
+      if (role === "assistant") { const a = assistant(); a.content = (a.content || "") + text(item.content, "assistant message"); }
+      else messages.push({ role, content: role === "user" ? parts(item.content, "user message") : text(item.content, `${role} message`) });
+    } else if (type === "function_call" || type === "custom_tool_call") {
+      const a = assistant();
+      (a.tool_calls ||= []).push({ id: item.call_id, type: "function", function: { name: item.name,
+        arguments: type === "custom_tool_call" ? JSON.stringify({ input: item.input ?? "" }) : (item.arguments ?? "{}") } });
+    } else if (type === "function_call_output" || type === "custom_tool_call_output") {
+      const media = Array.isArray(item.output) ? item.output.map(mediaPart).filter(Boolean) : [];
+      const output = typeof item.output === "string" ? item.output : text(item.output.filter((b) => !mediaPart(b)), "tool output");
+      messages.push({ role: "tool", tool_call_id: item.call_id, content: output });
+      if (media.length) messages.push({ role: "user", content: [{ type: "text", text: `Attachments returned by tool call ${item.call_id}:` }, ...media] });
+    } // reasoning items and the like stay with the client
+  }
+  for (const message of messages) if (message.role === "assistant" && !message.tool_calls?.length) delete message.tool_calls;
+  const options = {};
+  for (const key of ["temperature", "top_p", "reasoning", "parallel_tool_calls"]) if (body[key] !== undefined) options[key] = body[key];
+  if (tools.length) options.tools = tools;
+  const choice = body.tool_choice;
+  if (choice === "none" || choice === "required" || choice === "auto") options.tool_choice = choice;
+  else if (choice?.name) options.tool_choice = { type: "function", function: { name: choice.name } };
+  return { messages, options, custom };
+}
+
+/** A network answer (chat completion) as a Responses object, freeform tools as custom_tool_call items. */
+export function toResponses(model, output, receipt, custom = new Set()) {
+  const answer = answerOf(output);
+  const items = [];
+  if (answer.text || !answer.calls.length) {
+    items.push({ type: "message", id: id("msg_"), role: "assistant", status: "completed",
+      content: [{ type: "output_text", text: answer.text, annotations: [] }] });
+  }
+  for (const call of answer.calls) {
+    const name = call.function?.name;
+    items.push(custom.has(name)
+      ? { type: "custom_tool_call", id: id("ctc_"), call_id: call.id, name, input: String(parseArguments(call.function?.arguments).input ?? ""), status: "completed" }
+      : { type: "function_call", id: id("fc_"), call_id: call.id, name, arguments: call.function?.arguments || "{}", status: "completed" });
+  }
+  const input = Number(receipt?.input_tokens ?? output?.usage?.prompt_tokens ?? 0);
+  const out = Number(receipt?.output_tokens ?? output?.usage?.completion_tokens ?? 0);
+  return { id: id("resp_"), object: "response", created_at: Math.floor(Date.now() / 1000), model, status: "completed",
+    output: items, output_text: answer.text, usage: { input_tokens: input, output_tokens: out, total_tokens: input + out } };
+}
+
 // ---------------- Gemini generateContent ----------------
 
-const GEMINI_PATH = /^\/(?:v1|v1beta|v1alpha)\/models\/([^/:]+):(generateContent|streamGenerateContent)$/;
+const GEMINI_PATH = /^\/(?:v1|v1beta|v1alpha)\/models\/([^/:]+):(generateContent|streamGenerateContent|countTokens)$/;
 
 /** The model and whether it streams, for a Gemini path; null for any other path. */
 export function geminiRoute(path) {
   const match = GEMINI_PATH.exec(path);
-  return match ? { model: decodeURIComponent(match[1]), stream: match[2] === "streamGenerateContent" } : null;
+  return match ? { model: decodeURIComponent(match[1]), stream: match[2] === "streamGenerateContent", count: match[2] === "countTokens" } : null;
 }
 
+const partsOf = (value, where) => parts(value, where);
+
 export function fromGemini(body, model) {
   if (!Array.isArray(body.contents)) throw new DialectError("contents are required");
-  unsupportedTools(body.tools?.length);
   const messages = [];
   const system = body.systemInstruction || body.system_instruction;
   if (system) messages.push({ role: "system", content: text(system.parts ?? system, "systemInstruction") });
+  // Gemini answers a call by the function's name; the network by an id. Pair each response with the
+  // earliest unanswered call of that name.
+  const open = [];
+  let counter = 0;
   for (const item of body.contents) {
-    const role = item.role === "model" ? "assistant" : "user";
-    messages.push({ role, content: text(item.parts, `${item.role || "user"} content`) });
+    const parts = item.parts || [];
+    const calls = parts.filter((p) => p.functionCall);
+    const results = parts.filter((p) => p.functionResponse);
+    const said = parts.filter((p) => !p.functionCall && !p.functionResponse);
+    const words = item.role === "model" ? text(said, "model content") : partsOf(said, "user content");
+    if (item.role === "model") {
+      const toolCalls = calls.map((p) => {
+        const call = { id: p.functionCall.id || `call_${counter++}`, type: "function",
+          function: { name: p.functionCall.name, arguments: JSON.stringify(p.functionCall.args ?? {}) } };
+        open.push(call);
+        return call;
+      });
+      messages.push({ role: "assistant", content: words || (toolCalls.length ? null : ""), ...(toolCalls.length ? { tool_calls: toolCalls } : {}) });
+      continue;
+    }
+    for (const part of results) {  // results first: they answer the calls the model just made
+      const index = open.findIndex((call) => call.function.name === part.functionResponse.name);
+      const call = index >= 0 ? open.splice(index, 1)[0] : null;
+      messages.push({ role: "tool", tool_call_id: part.functionResponse.id || call?.id || `call_${counter++}`,
+        content: JSON.stringify(part.functionResponse.response ?? {}) });
+    }
+    if ((typeof words === "string" ? words : words.length) || !results.length) messages.push({ role: "user", content: words });
   }
   const config = body.generationConfig || body.generation_config || {};
   const options = {};
   if (config.temperature !== undefined) options.temperature = config.temperature;
   if (config.topP !== undefined) options.top_p = config.topP;
   if (config.stopSequences) options.stop = config.stopSequences;
+  const declarations = (body.tools || []).flatMap((t) => t.functionDeclarations || t.function_declarations || []);
+  if (declarations.length) {
+    options.tools = declarations.map((d) => ({ type: "function", function: { name: d.name, description: d.description || "",
+      parameters: d.parametersJsonSchema || d.parameters || { type: "object", properties: {} } } }));
+    const mode = body.toolConfig?.functionCallingConfig?.mode;
+    if (mode === "NONE") options.tool_choice = "none";
+    else if (mode === "ANY") options.tool_choice = "required";
+  }
   return { model, messages, maxOutputTokens: config.maxOutputTokens ?? 4096, options };
 }
 
-function geminiChunk(model, piece, receipt) {
-  const chunk = { candidates: [{ content: { role: "model", parts: [{ text: piece }] }, index: 0 }], modelVersion: model };
+function geminiParts(piece, calls = []) {
+  const parts = piece ? [{ text: piece }] : [];
+  for (const call of calls) parts.push({ functionCall: { name: call.function?.name, args: parseArguments(call.function?.arguments) } });
+  return parts.length ? parts : [{ text: "" }];
+}
+
+function geminiChunk(model, parts, receipt) {
+  const chunk = { candidates: [{ content: { role: "model", parts }, index: 0 }], modelVersion: model };
   if (receipt) {
     chunk.candidates[0].finishReason = "STOP";
     const input = Number(receipt.input_tokens); const output = Number(receipt.output_tokens);
@@ -120,14 +361,27 @@ function geminiChunk(model, piece, receipt) {
   return chunk;
 }
 
-export const toGemini = (model, answer, receipt) => geminiChunk(model, answer, receipt);
+export const toGemini = (model, output, receipt) => {
+  const answer = answerOf(output);
+  return geminiChunk(model, geminiParts(answer.text, answer.calls), receipt);
+};
 
-/** streamGenerateContent with alt=sse: one JSON chunk per event; the last carries finishReason and usage. */
+/** countTokens: an upper-bound estimate (UTF-8 bytes / 3, as prices are authorized). */
+export function countGeminiTokens(body, model) {
+  const ask = fromGemini({ contents: [], ...body }, model);
+  const bytes = Buffer.byteLength(JSON.stringify(ask.messages), "utf8") + Buffer.byteLength(JSON.stringify(ask.options.tools || []), "utf8");
+  return { totalTokens: Math.ceil(bytes / 3) };
+}
+
+/** streamGenerateContent with alt=sse: one JSON chunk per event; the last carries calls, finishReason and usage. */
 export function geminiStream(write, model) {
   const chunk = (value) => write(`data: ${JSON.stringify(value)}\n\n`);
   return {
-    delta(piece) { if (piece) chunk(geminiChunk(model, piece)); },
-    finish(answer, receipt, streamedAny) { chunk(geminiChunk(model, streamedAny ? "" : answer, receipt)); },
+    delta(piece) { if (piece) chunk(geminiChunk(model, [{ text: piece }])); },
+    finish(output, receipt, streamedAny) {
+      const answer = answerOf(output);
+      chunk(geminiChunk(model, geminiParts(streamedAny ? "" : answer.text, answer.calls), receipt));
+    },
     fail(message) { chunk({ error: { code: 500, message, status: "INTERNAL" } }); },
   };
 }

package/src/protocol.mjs

@@ -117,8 +117,10 @@ export function openResponse(prepared, result, deployment, now = Math.floor(Date
  * (mycomesh/protocol.py worst_case_tokens): content UTF-8 length / 3, plus the backend's own input, plus
  * the full max_output_tokens.
  */
-export function worstCaseTokens(endpoint, content, maxOutputTokens, inputOverheadTokens = 0) {
-  const bytes = Buffer.byteLength(JSON.stringify(content ?? null), "utf8");
+export function worstCaseTokens(endpoint, content, maxOutputTokens, inputOverheadTokens = 0, tools = null) {
+  // Tool definitions are input too, counted as the Provider counts them (protocol.py).
+  const bytes = Buffer.byteLength(JSON.stringify(content ?? null), "utf8")
+    + (Array.isArray(tools) && tools.length ? Buffer.byteLength(JSON.stringify(tools), "utf8") : 0);
   return [Math.ceil(bytes / 3) + Number(inputOverheadTokens || 0), Number(maxOutputTokens)];
 }
 
@@ -129,12 +131,12 @@ export function worstCaseTokens(endpoint, content, maxOutputTokens, inputOverhea
  * many requests share one deposit and one Provider's daily capacity at once. When even the worst case does
  * not fit the cap, the output is trimmed to what the cap pays for, rather than having the Provider refuse.
  */
-export function planRequest(descriptor, endpoint, content, maxOutputTokens, cap) {
+export function planRequest(descriptor, endpoint, content, maxOutputTokens, cap, tools = null) {
   const prices = descriptor.prices || {};
   const inPrice = Number(prices.input_per_1k || 0);
   const outPrice = Number(prices.output_per_1k || 0);
   const floor = Math.max(Number(prices.minimum_fee || 0), 1);
-  const [input] = worstCaseTokens(endpoint, content, 0, descriptor.input_overhead_tokens);
+  const [input] = worstCaseTokens(endpoint, content, 0, descriptor.input_overhead_tokens, tools);
   const worst = (output) => Math.max(Math.ceil((input * inPrice + output * outPrice) / 1000), floor);
   let output = Number(maxOutputTokens);
   if (worst(output) > Number(cap) && outPrice > 0) {

package/src/sse.mjs

@@ -173,7 +173,11 @@ export function chatStream(write, { model }, { includeUsage = false } = {}) {
       const choice = (payload?.choices || [])[0] || {};
       const text = typeof choice.message?.content === "string" ? choice.message.content : "";
       if (text.startsWith(streamed) && text.length > streamed.length) chunk({ content: text.slice(streamed.length) });
-      chunk({}, choice.finish_reason || "stop");
+      // Tool calls come whole, once the answer is verified.
+      const tools = Array.isArray(choice.message?.tool_calls) ? choice.message.tool_calls : [];
+      tools.forEach((tool, index) => chunk({ tool_calls: [{ index, id: tool.id, type: tool.type || "function",
+        function: { name: tool.function?.name || "", arguments: tool.function?.arguments || "" } }] }));
+      chunk({}, choice.finish_reason || (tools.length ? "tool_calls" : "stop"));
       if (includeUsage && payload?.usage) {
         write(`data: ${JSON.stringify({ id, object: "chat.completion.chunk", created, model, choices: [], usage: payload.usage })}\n\n`);
       }