@agentprojectcontext/apx 1.25.0 → 1.27.1

package/src/core/desktop/autostart.js

@@ -0,0 +1,162 @@
+// Per-user "launch APX Desktop at login" wiring. Used by BOTH the CLI
+// (`apx desktop install` / `uninstall`) and the daemon's
+// /desktop/autostart endpoint so the web admin can toggle the same setting
+// without shelling out.
+//
+// Per-user, never sudo, fully reversible. Three platforms supported:
+//
+//   macOS  → ~/Library/LaunchAgents/dev.apx.desktop.plist + launchctl load -w
+//   win32  → HKCU\Software\Microsoft\Windows\CurrentVersion\Run\APXDesktop
+//   linux  → ~/.config/autostart/apx-desktop.desktop
+//
+// Functions return plain { ok, message? } / boolean results — never throw,
+// never process.exit — so the daemon's HTTP layer can map them to status
+// codes and the CLI can render them as ANSI lines.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+export const AUTOSTART_LABEL      = "dev.apx.desktop";
+export const MAC_PLIST_PATH       = path.join(os.homedir(), "Library", "LaunchAgents", `${AUTOSTART_LABEL}.plist`);
+export const LINUX_DESKTOP_PATH   = path.join(os.homedir(), ".config", "autostart", "apx-desktop.desktop");
+export const WIN_RUN_KEY          = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+export const WIN_RUN_NAME         = "APXDesktop";
+const AUTOSTART_LOG_PATH          = path.join(os.homedir(), ".apx", "desktop-autostart.log");
+
+// ── runner resolution ────────────────────────────────────────────────────
+
+/**
+ * Returns the [bin, ...args] tuple a launchd plist / Windows Run / Linux
+ * .desktop entry should invoke. We DO NOT use the `apx` shim — pnpm/npm
+ * shims are shell scripts that `exec node`, and launchd's PATH is minimal
+ * (no nvm, often no /usr/local/bin), so they fail at boot with
+ * "exec: node: not found". Using `process.execPath` (absolute path of the
+ * node binary currently running this process) + the absolute CLI script is
+ * launchctl-safe on every platform.
+ */
+export function getApxRunner() {
+  // From core/desktop/ → up 2 to project root → src/interfaces/cli/index.js.
+  const cli = path.resolve(__dirname, "..", "..", "interfaces", "cli", "index.js");
+  return [process.execPath, cli];
+}
+
+// ── XML helpers ──────────────────────────────────────────────────────────
+
+function escapeXml(s) {
+  return String(s).replace(/[<>&'"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "'": "&apos;", '"': "&quot;" }[c]));
+}
+
+export function buildPlist(runner, logFile) {
+  const args = [...runner, "desktop", "start"];
+  const argsXml = args.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${AUTOSTART_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argsXml}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><false/>
+  <key>ProcessType</key><string>Interactive</string>
+  <key>StandardOutPath</key><string>${escapeXml(logFile)}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+// ── public API ───────────────────────────────────────────────────────────
+
+/** Boolean: is the autostart entry currently registered on this platform? */
+export function autostartIsOn() {
+  try {
+    if (process.platform === "darwin") return fs.existsSync(MAC_PLIST_PATH);
+    if (process.platform === "linux")  return fs.existsSync(LINUX_DESKTOP_PATH);
+    if (process.platform === "win32") {
+      const out = execFileSync("reg", ["query", WIN_RUN_KEY, "/v", WIN_RUN_NAME], {
+        stdio: ["ignore", "pipe", "ignore"],
+      }).toString();
+      return new RegExp(WIN_RUN_NAME).test(out);
+    }
+  } catch {}
+  return false;
+}
+
+/**
+ * Enable autostart. Idempotent — running twice is safe.
+ * @returns {{ ok: boolean, message?: string, error?: string, runs?: string, path?: string }}
+ */
+export function autostartInstall() {
+  const runner = getApxRunner();
+  const sh = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
+  const cmdline = [...runner, "desktop", "start"].map(sh).join(" ");
+
+  if (process.platform === "darwin") {
+    try {
+      fs.mkdirSync(path.dirname(MAC_PLIST_PATH), { recursive: true });
+      fs.mkdirSync(path.dirname(AUTOSTART_LOG_PATH), { recursive: true });
+      fs.writeFileSync(MAC_PLIST_PATH, buildPlist(runner, AUTOSTART_LOG_PATH), "utf8");
+      try { execFileSync("launchctl", ["unload", MAC_PLIST_PATH], { stdio: "ignore" }); } catch {}
+      execFileSync("launchctl", ["load", "-w", MAC_PLIST_PATH], { stdio: "ignore" });
+      return { ok: true, runs: cmdline, path: MAC_PLIST_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+  if (process.platform === "win32") {
+    try {
+      execFileSync("reg", [
+        "add", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/t", "REG_SZ", "/d", cmdline, "/f",
+      ], { stdio: "ignore" });
+      return { ok: true, runs: cmdline, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}` };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+  if (process.platform === "linux") {
+    try {
+      fs.mkdirSync(path.dirname(LINUX_DESKTOP_PATH), { recursive: true });
+      fs.writeFileSync(LINUX_DESKTOP_PATH,
+        `[Desktop Entry]\nType=Application\nName=APX Desktop\nExec=${cmdline}\nX-GNOME-Autostart-enabled=true\nTerminal=false\n`,
+        "utf8");
+      return { ok: true, runs: cmdline, path: LINUX_DESKTOP_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+  return { ok: false, error: `autostart not supported on platform: ${process.platform}` };
+}
+
+/**
+ * Disable autostart. Idempotent — no-op if not installed.
+ * @returns {{ ok: boolean, removed?: boolean, path?: string, error?: string }}
+ */
+export function autostartUninstall() {
+  if (process.platform === "darwin") {
+    if (!fs.existsSync(MAC_PLIST_PATH)) return { ok: true, removed: false };
+    try {
+      try { execFileSync("launchctl", ["unload", "-w", MAC_PLIST_PATH], { stdio: "ignore" }); } catch {}
+      fs.unlinkSync(MAC_PLIST_PATH);
+      return { ok: true, removed: true, path: MAC_PLIST_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+  if (process.platform === "win32") {
+    try {
+      execFileSync("reg", ["delete", WIN_RUN_KEY, "/v", WIN_RUN_NAME, "/f"], { stdio: "ignore" });
+      return { ok: true, removed: true, path: `${WIN_RUN_KEY}\\${WIN_RUN_NAME}` };
+    } catch {
+      return { ok: true, removed: false };
+    }
+  }
+  if (process.platform === "linux") {
+    if (!fs.existsSync(LINUX_DESKTOP_PATH)) return { ok: true, removed: false };
+    try {
+      fs.unlinkSync(LINUX_DESKTOP_PATH);
+      return { ok: true, removed: true, path: LINUX_DESKTOP_PATH };
+    } catch (e) { return { ok: false, error: e.message }; }
+  }
+  return { ok: false, error: `autostart not supported on platform: ${process.platform}` };
+}

package/src/core/engines/_health.js

@@ -0,0 +1,63 @@
+// Shared probes used by engine adapters to implement their own `.health()`.
+// These used to live inline in model-router.js, which had a switch statement
+// per provider — moved here so each adapter owns its own health logic.
+
+/**
+ * Reachability ping. Returns { ok, status?, reason? }. Catches abort/timeout
+ * cleanly so callers can present a consistent shape.
+ */
+export async function pingUrl(url, { timeoutMs = 800, headers = {} } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await Promise.race([
+      fetch(url, { signal: ctrl.signal, headers }),
+      new Promise((_, reject) => {
+        setTimeout(() => reject(new Error("timeout")), timeoutMs);
+      }),
+    ]);
+    return { ok: res.ok, status: res.status };
+  } catch (e) {
+    const msg = e?.message || "unreachable";
+    return { ok: false, reason: /abort|timeout/i.test(msg) ? "timeout" : msg };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Same as pingUrl but parses the response body when 2xx. Returns
+ * { ok, status?, reason?, json? }.
+ */
+export async function fetchJsonWithTimeout(url, { timeoutMs = 800, headers = {} } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, headers });
+    if (!res.ok) return { ok: false, status: res.status, reason: `HTTP ${res.status}` };
+    const json = await res.json().catch(() => null);
+    return { ok: true, status: res.status, json };
+  } catch (e) {
+    const msg = e?.message || "unreachable";
+    return { ok: false, reason: /abort|timeout/i.test(msg) ? "timeout" : msg };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Build a "model is loaded?" predicate for Ollama-style `/api/tags` payloads.
+ * Matches by exact name first, then by "name:" prefix so `qwen3` matches
+ * `qwen3:32b`. Returns { present, available }.
+ */
+export function modelInOllamaTags(tagsJson, candidateModel) {
+  const list = Array.isArray(tagsJson?.models) ? tagsJson.models : [];
+  const names = list.map((m) => m?.name).filter((n) => typeof n === "string");
+  if (!candidateModel) return { present: true, available: names };
+  const wanted = String(candidateModel).trim();
+  if (!wanted) return { present: true, available: names };
+  if (names.includes(wanted)) return { present: true, available: names };
+  const prefix = wanted + ":";
+  if (names.some((n) => n.startsWith(prefix))) return { present: true, available: names };
+  return { present: false, available: names };
+}

package/src/{daemon → core}/engines/anthropic.js

@@ -10,6 +10,22 @@ function getKey(config) {
 
 export default {
   id: "anthropic",
+  needsApiKey: true,
+  apiKeyEnv: "ANTHROPIC_API_KEY",
+  defaultFallbackModel: "anthropic:claude-haiku-4-5",
+
+  /**
+   * Anthropic doesn't expose a cheap "/health" surface and `/v1/messages` is
+   * billed. We treat "have an api_key" as the gate; the actual call surfaces
+   * 401s if the key is bad. Marked `soft: true` so callers know this is a
+   * presence check, not a real probe.
+   */
+  async health(config = {}) {
+    const key = getKey(config);
+    return key
+      ? { ok: true, provider: "anthropic", soft: true }
+      : { ok: false, provider: "anthropic", reason: "no api_key" };
+  },
 
   async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal, onToken }) {
     const key = getKey(config);

package/src/core/engines/gemini.js

@@ -0,0 +1,168 @@
+// Google Gemini adapter (https://ai.google.dev/api/generate-content).
+// Direct fetch, no SDK. Supports function calling (Gemini's name for tool
+// use) so it can drive the super-agent loop on parity with Groq / OpenAI.
+import { randomUUID } from "node:crypto";
+
+const API_BASE = "https://generativelanguage.googleapis.com/v1beta/models";
+
+function getKey(config) {
+  return config.api_key || process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || "";
+}
+
+// Convert OpenAI-style tool schemas (`{ type: "function", function: { name,
+// description, parameters } }`) into Gemini's `functionDeclarations` shape.
+function toGeminiTools(toolSchemas) {
+  if (!Array.isArray(toolSchemas) || toolSchemas.length === 0) return undefined;
+  return [
+    {
+      functionDeclarations: toolSchemas
+        .map((t) => t.function || t)
+        .filter((fn) => fn?.name)
+        .map((fn) => ({
+          name: fn.name,
+          description: fn.description || "",
+          parameters: fn.parameters || { type: "object", properties: {} },
+        })),
+    },
+  ];
+}
+
+// Map our message history into Gemini's `contents` array. Tool results land
+// as `role: "function"` parts with a `functionResponse`. Function calls
+// emitted by the model in earlier turns become `functionCall` parts under
+// `role: "model"`.
+function toGeminiContents(messages) {
+  const out = [];
+  for (const m of messages) {
+    if (m.role === "tool") {
+      out.push({
+        role: "function",
+        parts: [
+          {
+            functionResponse: {
+              name: m.name || m.tool_name || "tool",
+              response: { content: m.content },
+            },
+          },
+        ],
+      });
+      continue;
+    }
+    if (m.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+      out.push({
+        role: "model",
+        parts: m.tool_calls.map((tc) => ({
+          functionCall: {
+            name: tc.function?.name || tc.name,
+            args:
+              typeof tc.function?.arguments === "string"
+                ? safeParseJson(tc.function.arguments)
+                : tc.function?.arguments || tc.arguments || {},
+          },
+        })),
+      });
+      continue;
+    }
+    out.push({
+      role: m.role === "assistant" ? "model" : "user",
+      parts: [{ text: typeof m.content === "string" ? m.content : JSON.stringify(m.content) }],
+    });
+  }
+  return out;
+}
+
+function safeParseJson(s) {
+  try { return JSON.parse(s); } catch { return {}; }
+}
+
+export default {
+  id: "gemini",
+  needsApiKey: true,
+  apiKeyEnv: "GEMINI_API_KEY",
+  defaultFallbackModel: "gemini:gemini-2.5-flash",
+
+  async health(config = {}) {
+    const key = getKey(config);
+    return key
+      ? { ok: true, provider: "gemini", soft: true }
+      : { ok: false, provider: "gemini", reason: "no api_key" };
+  },
+
+  async chat({
+    system,
+    messages,
+    model,
+    temperature = 0.7,
+    maxTokens = 1024,
+    tools,
+    toolChoice,
+    config = {},
+    signal,
+  }) {
+    const key = getKey(config);
+    if (!key) throw new Error("gemini: no api_key (set GEMINI_API_KEY or engines.gemini.api_key)");
+    if (!model) throw new Error("gemini: model required");
+
+    const body = {
+      contents: toGeminiContents(messages),
+      generationConfig: { temperature, maxOutputTokens: maxTokens },
+    };
+    if (system) body.systemInstruction = { parts: [{ text: system }] };
+
+    const fnTools = toGeminiTools(tools);
+    if (fnTools) {
+      body.tools = fnTools;
+      // Gemini's toolConfig.functionCallingConfig.mode:
+      //   AUTO (default), ANY (force a call), NONE (text only).
+      if (toolChoice === "required" || toolChoice === "any") {
+        body.toolConfig = { functionCallingConfig: { mode: "ANY" } };
+      } else if (toolChoice === "none") {
+        body.toolConfig = { functionCallingConfig: { mode: "NONE" } };
+      }
+    }
+
+    const url = `${API_BASE}/${encodeURIComponent(model)}:generateContent?key=${key}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal,
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      throw new Error(
+        `gemini ${res.status}: ${json?.error?.message || JSON.stringify(json)}`
+      );
+    }
+
+    const parts = json.candidates?.[0]?.content?.parts || [];
+    const text = parts.map((p) => p.text || "").join("");
+    // Extract function calls and translate them into the OpenAI-shaped
+    // tool_calls the run-agent loop expects.
+    const toolCalls = [];
+    for (const p of parts) {
+      const fc = p.functionCall || p.function_call;
+      if (fc?.name) {
+        toolCalls.push({
+          id: `gemini_${randomUUID().slice(0, 8)}`,
+          type: "function",
+          function: {
+            name: fc.name,
+            arguments: typeof fc.args === "string" ? fc.args : JSON.stringify(fc.args || {}),
+          },
+        });
+      }
+    }
+
+    return {
+      text,
+      tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+      finish_reason: json.candidates?.[0]?.finishReason || null,
+      usage: {
+        input_tokens: json.usageMetadata?.promptTokenCount || 0,
+        output_tokens: json.usageMetadata?.candidatesTokenCount || 0,
+      },
+      raw: json,
+    };
+  },
+};

package/src/core/engines/groq.js

@@ -0,0 +1,8 @@
+import { createOpenAiCompatibleEngine } from "./openai-compatible.js";
+
+export default createOpenAiCompatibleEngine({
+  id: "groq",
+  defaultBaseUrl: "https://api.groq.com/openai/v1",
+  apiKeyEnv: "GROQ_API_KEY",
+  defaultFallbackModel: "groq:llama-3.3-70b-versatile",
+});

package/src/{daemon → core}/engines/index.js

@@ -13,11 +13,13 @@
 
 import anthropic from "./anthropic.js";
 import openai from "./openai.js";
+import groq from "./groq.js";
+import openrouter from "./openrouter.js";
 import ollama from "./ollama.js";
 import gemini from "./gemini.js";
 import mock from "./mock.js";
 
-const ADAPTERS = { anthropic, openai, ollama, gemini, mock };
+const ADAPTERS = { anthropic, openai, groq, openrouter, ollama, gemini, mock };
 
 export function resolveProvider(modelId) {
   if (typeof modelId !== "string" || !modelId) {

package/src/{daemon → core}/engines/mock.js

@@ -4,12 +4,34 @@
 
 export default {
   id: "mock",
+  needsApiKey: false,
+
+  async health() {
+    return { ok: true, soft: true };
+  },
 
   async chat({ system, messages, model = "mock" }) {
     const last = [...messages].reverse().find((m) => m.role === "user");
     const userText = last?.content || "";
     const requestedTool = userText.match(/\[mock:tool:([a-z_]+)\]/)?.[1];
+    const finishSummary = userText.match(/\[mock:finish:([^\]]*)\]/)?.[1];
     const hasToolResult = messages.some((m) => m.role === "tool");
+    // Completion-contract path: once a tool has run, emit a `finish` call with
+    // the requested summary so tests can exercise the loop's graceful exit.
+    if (finishSummary != null && hasToolResult) {
+      const toolCall = {
+        id: "mock-finish-1",
+        type: "function",
+        function: { name: "finish", arguments: JSON.stringify({ summary: finishSummary }) },
+      };
+      return {
+        text: "",
+        tool_calls: [toolCall],
+        message: { tool_calls: [toolCall] },
+        usage: { input_tokens: userText.length, output_tokens: 4 },
+        raw: { model, mock: true },
+      };
+    }
     if (requestedTool && !hasToolResult) {
       const toolCall = {
         id: "mock-call-1",

package/src/{daemon → core}/engines/ollama.js

@@ -1,5 +1,6 @@
 // Ollama adapter (https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-chat-completion).
 // Local-only. No API key. Default base_url http://localhost:11434.
+import { pingUrl, fetchJsonWithTimeout, modelInOllamaTags } from "./_health.js";
 
 function baseUrl(config) {
   return config.base_url || process.env.OLLAMA_HOST || "http://localhost:11434";
@@ -7,6 +8,40 @@ function baseUrl(config) {
 
 export default {
   id: "ollama",
+  needsApiKey: false,
+  defaultBaseUrl: "http://localhost:11434",
+
+  /**
+   * Health check. Two modes:
+   *  - Loose (no candidateModel): just confirm `/api/tags` answers — useful
+   *    for "is the host reachable" diagnostics in `apx status`.
+   *  - Strict (candidateModel given): confirm the model is actually pulled
+   *    on this host. Otherwise the chat call would fail with a confusing
+   *    "model not found" mid-conversation; better to fall through to the
+   *    next fallback now.
+   */
+  async health(config = {}, { timeoutMs = 800, candidateModel = null } = {}) {
+    const base = baseUrl(config).replace(/\/$/, "");
+    if (!candidateModel) {
+      const res = await pingUrl(`${base}/api/tags`, { timeoutMs });
+      return res.ok
+        ? { ok: true, provider: "ollama", detail: base }
+        : { ok: false, provider: "ollama", reason: res.reason || `HTTP ${res.status}`, detail: base };
+    }
+    const res = await fetchJsonWithTimeout(`${base}/api/tags`, { timeoutMs });
+    if (!res.ok) {
+      return { ok: false, provider: "ollama", reason: res.reason || `HTTP ${res.status}`, detail: base };
+    }
+    const { present, available } = modelInOllamaTags(res.json, candidateModel);
+    if (present) return { ok: true, provider: "ollama", detail: base };
+    return {
+      ok: false,
+      provider: "ollama",
+      reason: `model "${candidateModel}" not loaded on this host`,
+      detail: base,
+      available,
+    };
+  },
 
   async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, toolChoice, config = {}, signal, onToken }) {
     if (!model) throw new Error("ollama: model required");

package/src/core/engines/openai-compatible.js

@@ -0,0 +1,145 @@
+// Shared OpenAI-compatible chat adapter (OpenAI, Groq, OpenRouter, …).
+import { pingUrl } from "./_health.js";
+
+export function createOpenAiCompatibleEngine({
+  id,
+  defaultBaseUrl,
+  apiKeyEnv,
+  defaultFallbackModel = null,
+}) {
+  function getKey(config) {
+    return config?.api_key || process.env[apiKeyEnv] || "";
+  }
+
+  function getBaseUrl(config) {
+    const raw = config?.base_url || defaultBaseUrl || "https://api.openai.com/v1";
+    return String(raw).replace(/\/$/, "");
+  }
+
+  return {
+    id,
+    needsApiKey: true,
+    apiKeyEnv,
+    defaultBaseUrl,
+    defaultFallbackModel,
+
+    /**
+     * Health: confirm we have a key and the `/models` catalog answers.
+     * Returns `soft: true` when /models fails — some keys are limited to
+     * /chat/completions only, so we allow the chain to proceed but flag it.
+     */
+    async health(config = {}, { timeoutMs = 800 } = {}) {
+      if (!getKey(config)) {
+        return { ok: false, provider: id, reason: "no api_key" };
+      }
+      const base = getBaseUrl(config);
+      const res = await pingUrl(`${base}/models`, {
+        timeoutMs: Math.max(timeoutMs, 1200),
+        headers: { authorization: `Bearer ${getKey(config)}` },
+      });
+      if (res.ok) return { ok: true, provider: id, detail: base };
+      // Key present but catalog ping failed — keep going, the chat call will
+      // either succeed or surface its own error. See backlog 13 (lazy retry).
+      return {
+        ok: true,
+        provider: id,
+        detail: base,
+        soft: true,
+        reason: res.reason || `HTTP ${res.status}`,
+      };
+    },
+
+    async chat({
+      system,
+      messages,
+      model,
+      temperature = 1.0,
+      maxTokens = 1024,
+      config = {},
+      tools,
+      toolChoice,
+      signal,
+    }) {
+      const key = getKey(config);
+      if (!key) {
+        throw new Error(`${id}: no api_key (set ${apiKeyEnv} or engines.${id}.api_key)`);
+      }
+      if (!model) throw new Error(`${id}: model required`);
+
+      // Serialise messages for the OpenAI Chat Completions wire format.
+      //
+      // We preserve four optional fields the loop relies on:
+      //   - tool_calls  (assistant turns that emit a structured call)
+      //   - tool_call_id (tool result turns — Groq / OpenAI strict require
+      //                   this to match the assistant's tool_call id)
+      //   - name         (some providers prefer it on tool messages)
+      //
+      // Dropping any of these is the cause of the
+      //   "messages.N.tool_call_id: property 'tool_call_id' is missing"
+      // 400 we saw on Groq when llama-3.3 emitted a pseudo-tool call.
+      const fullMessages = [];
+      if (system) fullMessages.push({ role: "system", content: system });
+      for (const m of messages) {
+        const entry = {
+          role: m.role,
+          content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+        };
+        if (m.tool_calls)    entry.tool_calls   = m.tool_calls;
+        if (m.tool_call_id)  entry.tool_call_id = m.tool_call_id;
+        // Some adapters expect `name` on tool messages; we map from tool_name
+        // (what run-agent.js writes) to be safe.
+        if (m.role === "tool" && (m.tool_name || m.name)) {
+          entry.name = m.name || m.tool_name;
+        }
+        fullMessages.push(entry);
+      }
+
+      const body = {
+        model,
+        messages: fullMessages,
+        temperature,
+        max_tokens: maxTokens,
+      };
+
+      if (tools && tools.length > 0) {
+        body.tools = tools;
+        if (toolChoice === "required" || toolChoice === "any") {
+          body.tool_choice = "required";
+        } else if (toolChoice && typeof toolChoice === "object") {
+          body.tool_choice = toolChoice;
+        }
+      }
+
+      const res = await fetch(`${getBaseUrl(config)}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${key}`,
+        },
+        body: JSON.stringify(body),
+        signal,
+      });
+      const json = await res.json();
+      if (!res.ok) {
+        throw new Error(
+          `${id} ${res.status}: ${json?.error?.message || JSON.stringify(json)}`
+        );
+      }
+
+      const choice = json.choices?.[0];
+      const text = choice?.message?.content || "";
+      const toolCalls = choice?.message?.tool_calls;
+
+      return {
+        text,
+        tool_calls: toolCalls?.length > 0 ? toolCalls : undefined,
+        finish_reason: choice?.finish_reason,
+        usage: {
+          input_tokens: json.usage?.prompt_tokens || 0,
+          output_tokens: json.usage?.completion_tokens || 0,
+        },
+        raw: json,
+      };
+    },
+  };
+}

package/src/core/engines/openai.js

@@ -0,0 +1,8 @@
+import { createOpenAiCompatibleEngine } from "./openai-compatible.js";
+
+export default createOpenAiCompatibleEngine({
+  id: "openai",
+  defaultBaseUrl: "https://api.openai.com/v1",
+  apiKeyEnv: "OPENAI_API_KEY",
+  defaultFallbackModel: "openai:gpt-4o-mini",
+});