@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/scripts/hooks/validate-state-yaml.sh

@@ -0,0 +1,190 @@
+#!/bin/sh
+# validate-state-yaml.sh — PostToolUse backstop: re-parse agent-authored state YAML after any write.
+#
+# Why: hand-edited queue YAML gets corrupted by ordinary edits (unquoted colons in plain
+# scalars, duplicate keys, a heredoc that clobbers a header). Every downstream reader — the
+# index regenerator, the dashboards, the daemon's queue sweeps — fails on the first bad file,
+# and the failure surfaces hours later in a different session. The standing rule
+# ("parse-validate after every YAML write") lived only in prose; this hook makes the harness
+# do it. It is the BACKSTOP behind scripts/hooks/pre-write-yaml-validate.mjs (the PreToolUse
+# gate on Write|Edit): that gate cannot see a Bash heredoc or a scripted write, this one can.
+#
+# Contract: reads the PostToolUse payload on stdin. For Edit/Write it validates the touched
+# file if it is a .yaml under state/queues, state/dashboards or state/indexes. For Bash it
+# re-parses the whole set whenever the command text mentions one of those directories. It
+# exits 2 with a blocking message on stderr for:
+#   1. a parse failure (duplicate mapping keys are rejected too — PyYAML silently keeps the
+#      last one while js-yaml throws, so a duplicate `history:` passes here and hard-fails
+#      every Node reader);
+#   2. a silently truncated provenance field — a provenance-keyed value ending on a dangling
+#      connector (" in", " to", " the", " and", " of", " for", " by" ...), the one signature an
+#      unquoted " #" in a plain scalar leaves behind after the comment ate the rest;
+#   3. a record-of-the-past stamp (timestamp:, last_updated:, ...) more than 10 minutes in the
+#      future — almost always local wall-clock written with a Z suffix.
+# Otherwise exits 0. Never crashes the session: every tooling gap (no python3, no PyYAML,
+# unreadable payload) fails open.
+#
+# Paths are resolved relative to the agent root: $CLAUDE_PROJECT_DIR when the harness sets
+# it, else the hook's working directory (Claude Code runs hooks from the project dir).
+AGENT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+PAYLOAD=$(cat 2>/dev/null)
+command -v python3 >/dev/null 2>&1 || exit 0
+
+HOOK_PAYLOAD="$PAYLOAD" python3 - "$AGENT_DIR" <<'PY'
+import datetime
+import glob
+import json
+import os
+import re
+import sys
+
+agent_dir = sys.argv[1]
+try:
+    payload = json.loads(os.environ.get("HOOK_PAYLOAD") or "{}")
+except Exception:
+    sys.exit(0)
+if not isinstance(payload, dict):
+    sys.exit(0)
+try:
+    import yaml
+except ImportError:
+    sys.exit(0)
+
+
+class StrictLoader(yaml.SafeLoader):
+    """SafeLoader that rejects duplicate mapping keys (PyYAML accepts them; js-yaml throws)."""
+
+
+def _no_duplicate_keys(loader, node, deep=False):
+    mapping = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if key in mapping:
+            raise yaml.constructor.ConstructorError(
+                "while constructing a mapping", node.start_mark,
+                "duplicate key %r — a writer appended to the wrong block" % (key,),
+                key_node.start_mark)
+        mapping[key] = loader.construct_object(value_node, deep=deep)
+    return mapping
+
+
+StrictLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _no_duplicate_keys)
+
+tool = payload.get("tool_name", "")
+ti = payload.get("tool_input") or {}
+if not isinstance(ti, dict):
+    ti = {}
+WATCH = ("state/queues/", "state/dashboards/", "state/indexes/")
+
+
+def in_scope(path):
+    rel = os.path.relpath(path, agent_dir) if os.path.isabs(path) else path
+    rel = rel.replace(os.sep, "/")
+    return rel.endswith((".yaml", ".yml")) and rel.startswith(WATCH)
+
+
+targets = []
+if tool in ("Edit", "Write", "MultiEdit", "NotebookEdit"):
+    fp = ti.get("file_path") or ""
+    if isinstance(fp, str) and fp and in_scope(fp):
+        targets = [fp if os.path.isabs(fp) else os.path.join(agent_dir, fp)]
+elif tool == "Bash":
+    cmd = ti.get("command") or ""
+    if isinstance(cmd, str) and any(w in cmd for w in WATCH):
+        for p in ("state/queues/*.yaml", "state/dashboards/*.yaml", "state/indexes/*.yaml"):
+            targets += glob.glob(os.path.join(agent_dir, p))
+targets = [t for t in targets if os.path.isfile(t)]
+if not targets:
+    sys.exit(0)
+
+
+def rel(t):
+    return os.path.relpath(t, agent_dir)
+
+
+# --- 1. parse failures ------------------------------------------------------------------
+bad = []
+docs = {}
+for t in targets:
+    try:
+        with open(t, encoding="utf-8") as fh:
+            docs[t] = yaml.load(fh, StrictLoader)
+    except Exception as e:  # report every failure, never swallow
+        lines = str(e).split("\n")
+        bad.append((rel(t), lines[0][:200] + (" | " + " ".join(lines[1:4]) if len(lines) > 1 else "")))
+if bad:
+    sys.stderr.write("YAML PARSE FAILURE after %s — fix before anything reads these files:\n" % tool)
+    for f, e in bad:
+        sys.stderr.write("  %s: %s\n" % (f, e))
+    sys.exit(2)
+
+# --- 2. silently truncated provenance fields --------------------------------------------
+# An unquoted " #" inside a plain scalar with no continuation line parses cleanly and drops
+# the rest of the value; a later load/dump round trip writes the surviving prefix back as
+# literal text, so the "#" is gone and a hash scan cannot find it. The only signature left is
+# a provenance-shaped field ending on a dangling connector ("... @mention in"). Scanned over
+# short provenance keys only, where it is close to exact.
+PROV_KEYS = {"origin", "source", "source_ref", "sourceRef", "raised_by", "counterparty", "channel",
+             "via", "provenance", "escalated_to", "reported_by", "requested_by", "decided_by",
+             "decision_owner", "owner", "reviewer", "notify"}
+CONNECTOR_RE = re.compile(r"\s(in|to|at|on|from|with|the|and|of|for|by)$", re.I)
+trunc = []
+
+
+def _walk(node, path):
+    if isinstance(node, dict):
+        rid = node.get("id") if isinstance(node.get("id"), str) else None
+        for k, v in node.items():
+            if isinstance(v, str) and k in PROV_KEYS and len(v) < 300 and CONNECTOR_RE.search(v.rstrip()):
+                trunc.append((path, rid or "?", k, v[-60:]))
+            elif isinstance(v, (dict, list)):
+                _walk(v, path)
+    elif isinstance(node, list):
+        for it in node:
+            _walk(it, path)
+
+
+for t, doc in docs.items():
+    _walk(doc, rel(t))
+if trunc:
+    sys.stderr.write("TRUNCATED PROVENANCE FIELD after %s (value ends on a dangling connector; an unquoted ' #' at write time silently cut it). Quote the scalar and restore the rest, or record that it is unrecoverable:\n" % tool)
+    for f, rid, k, v in trunc:
+        sys.stderr.write("  %s  %s  %s: ...%s\n" % (f, rid, k, v))
+    sys.exit(2)
+
+# --- 3. future-dated record stamps ------------------------------------------------------
+# A past-tense stamp can never be in the future, so any such value later than now+10min is
+# wrong by construction. Deadline-shaped keys (due:, target_date:, evaluate_after:) are
+# deliberately NOT checked — future instants are legitimate there.
+RECORD_KEYS = ("timestamp", "last_updated", "generated", "created", "created_at", "updated",
+               "updated_at", "resolved_at", "closed_at", "checked_at", "ts", "last_reset",
+               "last_direct_interaction", "last_outbound", "last_touched", "last_interaction",
+               "last_daily_sweep", "decided_at", "sent_at", "date", "resolved")
+STAMP_RE = re.compile(r"^\s*-?\s*(%s):\s*['\"]?(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?Z)" % "|".join(RECORD_KEYS))
+now = datetime.datetime.now(datetime.timezone.utc)
+limit = now + datetime.timedelta(minutes=10)
+future = []
+for t in targets:
+    try:
+        with open(t, encoding="utf-8") as fh:
+            for n, line in enumerate(fh, 1):
+                m = STAMP_RE.match(line)
+                if not m:
+                    continue
+                raw = m.group(2)
+                try:
+                    fmt = "%Y-%m-%dT%H:%M:%S" if len(raw) >= 20 else "%Y-%m-%dT%H:%M"
+                    val = datetime.datetime.strptime(raw[:19] if len(raw) >= 20 else raw[:16], fmt).replace(tzinfo=datetime.timezone.utc)
+                except Exception:
+                    continue
+                if val > limit:
+                    future.append((rel(t), n, m.group(1), raw))
+    except Exception:
+        continue
+if future:
+    sys.stderr.write("FUTURE-DATED RECORD STAMP after %s (now %s). A past-tense field cannot be later than now; this is almost always local wall-clock written with a Z suffix — restamp from `date -u`:\n" % (tool, now.strftime("%Y-%m-%dT%H:%M:%SZ")))
+    for f, n, k, raw in future:
+        sys.stderr.write("  %s:%d  %s: %s\n" % (f, n, k, raw))
+    sys.exit(2)
+sys.exit(0)
+PY

package/scripts/huddle/huddle-llm.mjs

@@ -0,0 +1,361 @@
+/**
+ * scripts/huddle/huddle-llm.mjs — every model call the huddle server makes, behind the runtime seam (conformance row 36).
+ *
+ * The legacy huddle brain (HUDDLE_BRAIN=legacy) answers a participant in one of
+ * two ways, and both used to reach Anthropic on their own:
+ *
+ *   CLI lane (default)   `claude --print --model sonnet -p <prompt>`. The binary,
+ *                        argv and env came from the runtime adapter only when the
+ *                        adapter happened to load; otherwise a bare `claude`
+ *                        (ENOENT under launchd). The seat's engine was never read.
+ *   API lane             (HUDDLE_USE_API=1) `@anthropic-ai/sdk` `messages.create`
+ *                        with the seat's ANTHROPIC_API_KEY and the huddle tools,
+ *                        up to three tool rounds.
+ *
+ * Both now ask the seat's engine (config/agent.json `runtime.engine`) on every
+ * call, so flipping the flag back is the rollback:
+ *
+ *   engine claude  CLI: `buildSpawn({lane:"huddle", model:"sonnet", prompt, env})`
+ *                  — the input, and so the binary (claude-bin), argv and env, are
+ *                  exactly what the server built before. API: the same SDK
+ *                  request, the same tool loop, the same client options.
+ *   engine cohort  CLI: the same buildSpawn input plus the seat's engine fields
+ *                  (`resolveSeatSpawn`): `node lib/engine/cli.mjs run -p --model
+ *                  cohort-agentic -- <prompt>` with the seat token and every
+ *                  Anthropic/Claude credential scrubbed. API: the engine wire
+ *                  (`createModelCaller`) against the seat's cohort-llm gateway,
+ *                  authenticated by the seat token manager. The Anthropic SDK is
+ *                  never loaded and ANTHROPIC_API_KEY is never read. No token →
+ *                  a returned failure, never a claude fallback.
+ *
+ * Decisions (`buildHuddleCliPrompt`, `huddleApiRequest`, `toCanonicalHistory`,
+ * `huddleLlmModeLabel`, `refuseAnthropicHost`) are pure; the rest take their
+ * edges as injectable deps. Expected failures are returned values; a model call
+ * that throws (the SDK) still throws, as it always did, into the server's catch.
+ *
+ * @module scripts/huddle/huddle-llm
+ */
+
+"use strict";
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { buildSpawn, readSeatEngine, DEFAULT_COHORT_TIER_MAP } from "../../lib/runtime/adapter.mjs";
+import { resolveSeatSpawn } from "../../lib/runtime/seat-engine.mjs";
+import { createModelCaller } from "../../lib/engine/wire/index.mjs";
+import { cohortTierFor } from "../../lib/model-router/catalog.mjs";
+import { DEFAULT_LLM_BASE_URL } from "../../lib/org/llm-token.mjs";
+
+/** The CLI lane's model slot and limits (unchanged from the inline spawn). */
+export const HUDDLE_CLI_MODEL = "sonnet";
+export const HUDDLE_CLI_TIMEOUT_MS = 30000;
+export const HUDDLE_CLI_MAX_BUFFER = 1024 * 1024;
+
+/** The API lane's request constants (unchanged from the inline SDK call). */
+export const HUDDLE_API_MODEL = "claude-sonnet-4-20250514";
+export const HUDDLE_MAX_TOKENS = 300;
+export const HUDDLE_MAX_TOOL_ROUNDS = 3;
+
+/** Engine cohort, API lane: the engine's default wire, and the attribution the gateway sees. */
+export const HUDDLE_COHORT_WIRE = "openai";
+export const HUDDLE_COHORT_HEADERS = Object.freeze({ "x-cohort-surface": "huddle" });
+
+/** The tool-result text when no action executor is loaded (unchanged). */
+export const HUDDLE_NO_EXECUTOR_RESULT = "Tool execution not available in this session.";
+
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+
+// ---------------------------------------------------------------------------
+// Pure decisions
+// ---------------------------------------------------------------------------
+
+/**
+ * The `[INIT] LLM mode` line. A claude seat's two labels are the historical ones. PURE.
+ * @param {{useCli:boolean, engine:string}} o
+ */
+export function huddleLlmModeLabel({ useCli, engine }) {
+  if (engine === "cohort") return useCli ? "Cohort engine (cohort-llm, seat token)" : "cohort-llm API (seat token)";
+  return useCli ? "Claude Code CLI (Max subscription)" : "Anthropic API (pay-per-token)";
+}
+
+/**
+ * The CLI lane's single prompt: the system prompt, then each turn under its
+ * speaker, then the agent's open turn. Byte-for-byte the inline builder. PURE.
+ * @param {string} systemPrompt
+ * @param {Array<{role:string, content:any}>} messages
+ * @param {string} agentName
+ */
+export function buildHuddleCliPrompt(systemPrompt, messages, agentName) {
+  const parts = [`[System]\n${systemPrompt}\n`];
+  for (const msg of messages || []) {
+    const role = msg.role === "assistant" ? agentName : "Participant";
+    const content = typeof msg.content === "string"
+      ? msg.content
+      : msg.content?.map((b) => b.text || "").join("") || "";
+    if (content.trim()) {
+      parts.push(`[${role}]\n${content}`);
+    }
+  }
+  parts.push(`[${agentName}]`);
+  return parts.join("\n\n");
+}
+
+/**
+ * The API lane's first request, as the inline SDK call built it. PURE.
+ * @param {{systemPrompt:string, messages:any[], tools?:any[]}} o
+ */
+export function huddleApiRequest({ systemPrompt, messages, tools = [] }) {
+  const apiParams = {
+    model: HUDDLE_API_MODEL,
+    max_tokens: HUDDLE_MAX_TOKENS,
+    system: systemPrompt,
+    messages: [...messages],
+  };
+  if (tools.length > 0) {
+    apiParams.tools = tools;
+  }
+  return apiParams;
+}
+
+/**
+ * The huddle's Messages-shaped history as the engine's canonical history
+ * (lib/engine/messages.mjs): string content becomes a text block, a tool
+ * result's content becomes a string. PURE.
+ * @param {Array<{role:string, content:any}>} messages
+ */
+export function toCanonicalHistory(messages) {
+  const block = (b) => {
+    if (!b || typeof b !== "object") return null;
+    if (b.type === "text") return { type: "text", text: String(b.text ?? "") };
+    if (b.type === "tool_use") return { type: "tool_use", id: b.id, name: b.name, input: b.input && typeof b.input === "object" ? b.input : {} };
+    if (b.type === "tool_result") {
+      const content = typeof b.content === "string" ? b.content : JSON.stringify(b.content ?? "");
+      return { type: "tool_result", tool_use_id: b.tool_use_id, content, ...(b.is_error ? { is_error: true } : {}) };
+    }
+    return null;
+  };
+  return (messages || []).map((m) => ({
+    role: m.role,
+    content: typeof m.content === "string" ? [{ type: "text", text: m.content }] : (Array.isArray(m.content) ? m.content.map(block).filter(Boolean) : []),
+  }));
+}
+
+/**
+ * A cohort-llm base URL must not be an Anthropic host: a mis-set
+ * COHORT_LLM_BASE_URL would otherwise send the huddle's conversation there. PURE.
+ * @param {string} baseUrl
+ * @returns {null|{code:string, message:string}}
+ */
+export function refuseAnthropicHost(baseUrl) {
+  let host = "";
+  try { host = new URL(String(baseUrl)).hostname.toLowerCase(); } catch {
+    return { code: "cohort_base_url_invalid", message: `cohort-llm base URL ${JSON.stringify(String(baseUrl))} is not a URL` };
+  }
+  if (host === "anthropic.com" || host.endsWith(".anthropic.com")) {
+    return { code: "cohort_base_url_refused", message: `cohort-llm base URL points at ${host}; an engine-cohort seat never calls Anthropic` };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// CLI lane
+// ---------------------------------------------------------------------------
+
+/**
+ * The CLI lane's spawn for this seat.
+ * @param {{agentRoot:string, prompt:string, env:object}} o
+ * @param {{resolveSeatSpawn?:Function, buildSpawn?:Function, adapterDeps?:object}} [deps]
+ */
+export async function huddleCliSpawn({ agentRoot, prompt, env }, deps = {}) {
+  const seat = await (deps.resolveSeatSpawn || resolveSeatSpawn)(agentRoot);
+  return (deps.buildSpawn || buildSpawn)({ lane: "huddle", model: HUDDLE_CLI_MODEL, prompt, env, ...seat.fields }, deps.adapterDeps);
+}
+
+/**
+ * One CLI-lane answer.
+ * @param {{agentRoot:string, prompt:string, env:object}} o
+ * @param {{execFile?:(bin:string, argv:string[], opts:object)=>Promise<{stdout:string}>, resolveSeatSpawn?:Function, buildSpawn?:Function, adapterDeps?:object}} [deps]
+ * @returns {Promise<{ok:true, engine:string, text:string}|{ok:false, engine:string, error:{code:string, message:string}}>}
+ */
+export async function runHuddleCli(o, deps = {}) {
+  const spec = await huddleCliSpawn(o, deps);
+  if (!spec.ok) {
+    const what = spec.error.engine === "cohort" ? "cohort engine unavailable" : "claude CLI unavailable";
+    return { ok: false, engine: spec.error.engine, error: { code: spec.error.code, message: `${what}: ${spec.error.message}` } };
+  }
+  const exec = deps.execFile || promisify(execFile);
+  try {
+    const { stdout } = await exec(spec.bin, spec.argv, {
+      timeout: HUDDLE_CLI_TIMEOUT_MS,
+      maxBuffer: HUDDLE_CLI_MAX_BUFFER,
+      env: spec.env,
+    });
+    return { ok: true, engine: spec.engine, text: (stdout || "").trim() };
+  } catch (err) {
+    return { ok: false, engine: spec.engine, error: { code: "huddle_cli_failed", message: String(err && err.message ? err.message : err) } };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API lane
+// ---------------------------------------------------------------------------
+
+/**
+ * A memoised Anthropic SDK client, built on first use with the options the
+ * server always passed. Loaded lazily so an engine-cohort seat never imports it.
+ * @param {object} env
+ * @param {() => Promise<any>} [load]
+ */
+export function createAnthropicClientFactory(env, load = () => import("@anthropic-ai/sdk")) {
+  let client = null;
+  return async () => {
+    if (!client) {
+      const mod = await load();
+      const Anthropic = mod.default || mod.Anthropic || mod;
+      client = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });
+    }
+    return client;
+  };
+}
+
+/**
+ * The engine-cohort turn caller: the engine wire against the seat's gateway.
+ * @returns {Promise<{ok:true, call:(apiParams:object)=>Promise<any[]>, baseUrl:string, model:string}|{ok:false, error:{code:string, message:string}}>}
+ */
+async function cohortTurnCaller(agentRoot, apiParams, deps) {
+  let manager = null;
+  try {
+    manager = deps.tokenManager ? deps.tokenManager(agentRoot) : (await import("../../lib/org/llm-token.mjs")).seatTokenManager({ agentRoot });
+  } catch (err) {
+    return { ok: false, error: { code: "cohort_token_unavailable", message: `no cohort-llm seat token manager: ${err && err.message ? err.message : err}` } };
+  }
+  if (!manager || typeof manager.getToken !== "function") {
+    return { ok: false, error: { code: "cohort_token_unavailable", message: "no cohort-llm seat token manager" } };
+  }
+  const baseUrl = String(nonEmpty(manager.baseUrl) ? manager.baseUrl : DEFAULT_LLM_BASE_URL).replace(/\/+$/, "");
+  const refused = refuseAnthropicHost(baseUrl);
+  if (refused) return { ok: false, error: refused };
+  const model = cohortTierFor(apiParams.model, DEFAULT_COHORT_TIER_MAP);
+  if (!model) return { ok: false, error: { code: "engine_model_unmapped", message: `${apiParams.model} has no Cohort tier` } };
+
+  const callModel = createModelCaller({
+    wire: HUDDLE_COHORT_WIRE,
+    baseUrl,
+    model,
+    maxTokens: apiParams.max_tokens,
+    headers: { ...HUDDLE_COHORT_HEADERS },
+    fetchImpl: deps.fetchImpl,
+    token: async ({ refresh, rejected }) => {
+      // A 401 names the refused token: a replacement is served, else one capped re-mint.
+      const t = await manager.getToken(refresh ? { force: true, ...(rejected ? { rejected } : {}) } : {});
+      if (!t || t.ok === false || !nonEmpty(t.token)) {
+        throw new Error(`cohort-llm seat token unavailable (${(t && t.error && t.error.code) || "no token"})`);
+      }
+      return t.token;
+    },
+  });
+  const call = async (p) => {
+    const r = await callModel({ system: p.system, messages: toCanonicalHistory(p.messages), tools: Array.isArray(p.tools) ? p.tools : [] });
+    if (!r.ok) {
+      const e = r.error || {};
+      const err = new Error(`cohort-llm request failed: ${e.code || e.kind || "unknown"}${e.message ? ` — ${e.message}` : ""}`);
+      /** @type any */ (err).cohortError = e;
+      throw err;
+    }
+    return r.value.message.content;
+  };
+  return { ok: true, call, baseUrl, model };
+}
+
+/**
+ * One API-lane answer: up to {@link HUDDLE_MAX_TOOL_ROUNDS} rounds, speaking any
+ * text a tool round carries before its tools run, exactly as the inline loop did.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {string} o.systemPrompt
+ * @param {any[]} o.messages
+ * @param {any[]} [o.tools]
+ * @param {(filler:string)=>Promise<void>} o.onFiller   speak + transcript
+ * @param {(toolUse:{id:string, name:string, input:any})=>Promise<any>} o.runTool  the tool_result content
+ * @param {object} [deps]
+ * @param {()=>Promise<any>} [deps.anthropicClient]  engine claude
+ * @param {(root:string)=>string} [deps.readSeatEngine]
+ * @param {(root:string)=>any} [deps.tokenManager]    engine cohort
+ * @param {typeof fetch} [deps.fetchImpl]            engine cohort
+ * @returns {Promise<{ok:true, engine:string, text:string}|{ok:false, engine:string, error:{code:string, message:string}}>}
+ */
+export async function runHuddleApiTurn(o, deps = {}) {
+  let engine = "claude";
+  try {
+    engine = (deps.readSeatEngine || readSeatEngine)(o.agentRoot) === "cohort" ? "cohort" : "claude";
+  } catch {
+    engine = "claude"; // unreadable config: the default engine, as readSeatEngine answers
+  }
+  const apiParams = huddleApiRequest({ systemPrompt: o.systemPrompt, messages: o.messages, tools: o.tools || [] });
+
+  let callTurn;
+  if (engine === "cohort") {
+    const c = await cohortTurnCaller(o.agentRoot, apiParams, deps);
+    if (!c.ok) return { ok: false, engine, error: c.error };
+    callTurn = c.call;
+  } else {
+    if (typeof deps.anthropicClient !== "function") {
+      return { ok: false, engine, error: { code: "anthropic_client_unavailable", message: "no Anthropic client for the huddle API lane" } };
+    }
+    const anthropic = await deps.anthropicClient();
+    callTurn = async (p) => (await anthropic.messages.create(p)).content;
+  }
+
+  let fullResponse = "";
+  let round = 0;
+
+  while (round < HUDDLE_MAX_TOOL_ROUNDS) {
+    round++;
+    const content = await callTurn(apiParams);
+
+    const textParts = [];
+    const toolUseBlocks = [];
+
+    for (const block of content) {
+      if (block.type === "text") {
+        textParts.push(block.text);
+      } else if (block.type === "tool_use") {
+        toolUseBlocks.push(block);
+      }
+    }
+
+    const roundText = textParts.join("");
+    fullResponse += roundText;
+
+    if (toolUseBlocks.length === 0) break;
+
+    if (roundText.trim()) {
+      const filler = roundText.replace(/\s*END_HUDDLE\s*/g, "").trim();
+      if (filler) await o.onFiller(filler);
+    }
+
+    const assistantContent = [];
+    if (roundText.trim()) {
+      assistantContent.push({ type: "text", text: roundText });
+    }
+    for (const tb of toolUseBlocks) {
+      assistantContent.push({ type: "tool_use", id: tb.id, name: tb.name, input: tb.input });
+    }
+    apiParams.messages.push({ role: "assistant", content: assistantContent });
+
+    const toolResults = [];
+    for (const tb of toolUseBlocks) {
+      toolResults.push({ type: "tool_result", tool_use_id: tb.id, content: await o.runTool(tb) });
+    }
+
+    apiParams.messages.push({ role: "user", content: toolResults });
+  }
+
+  return { ok: true, engine, text: fullResponse.trim() };
+}
+
+export default {
+  huddleLlmModeLabel, buildHuddleCliPrompt, huddleApiRequest, toCanonicalHistory, refuseAnthropicHost,
+  huddleCliSpawn, runHuddleCli, createAnthropicClientFactory, runHuddleApiTurn,
+};