agentlas 0.4.0

package/engine/agentlas-api-agent.cjs

@@ -0,0 +1,451 @@
+"use strict";
+/*
+ * agentlas-api-agent: BYOK(Anthropic/OpenAI/Google) + Ollama 위에서 도는 agentlas 자체 에이전트 루프.
+ * openclaw가 pi-agent-core로 하는 일을 CJS로: SSE 스트리밍 + provider별 tool-use 프로토콜 + 로컬 툴 실행.
+ * byok.ts(electron)의 SSE 패턴을 이식했다. 외부 SDK 의존성 없음 (Node 20 fetch/ReadableStream).
+ *
+ *   anthropic / openai / ollama → 스트리밍 + 툴 루프 (read/write/full 권한 게이트)
+ *   google                      → 스트리밍 채팅 (툴은 후속 — 우아하게 chat-only)
+ */
+const tools = require("./agentlas-tools.cjs");
+
+const MAX_ITERS = 12;
+const IDLE_MS = Number(process.env.AGENTLAS_IDLE_TIMEOUT_MS) || 180000;
+
+// 스트림이 IDLE_MS 동안 한 바이트도 안 오면 중단(provider가 SSE를 열고 멈추는 hang 방지).
+// 부모 signal(사용자 Ctrl-C)과 결합한다. timer는 unref이라 프로세스 종료를 막지 않는다.
+function idleAbort(parentSignal, ms) {
+  const ctrl = new AbortController();
+  let timer = null;
+  const onParent = () => ctrl.abort();
+  if (parentSignal) {
+    if (parentSignal.aborted) ctrl.abort();
+    else parentSignal.addEventListener("abort", onParent, { once: true });
+  }
+  const bump = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => ctrl.abort(), ms);
+    if (timer.unref) timer.unref();
+  };
+  const clear = () => {
+    if (timer) clearTimeout(timer);
+    if (parentSignal && parentSignal.removeEventListener) parentSignal.removeEventListener("abort", onParent);
+  };
+  bump();
+  return { signal: ctrl.signal, bump, clear };
+}
+
+async function* iterSse(resp, idle) {
+  if (!resp.body) return;
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (idle) idle.bump();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let nl;
+    while ((nl = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line) yield line;
+    }
+  }
+  if (buffer.trim()) yield buffer.trim();
+}
+
+function sseData(line) {
+  if (!line.startsWith("data:")) return null;
+  const p = line.slice(5).trim();
+  return p === "[DONE]" ? "[DONE]" : p;
+}
+
+// ── Anthropic ────────────────────────────────────────────
+async function streamAnthropic({ apiKey, model, system, messages, permission, ui, signal }) {
+  const body = {
+    model,
+    max_tokens: 8192,
+    stream: true,
+    system,
+    messages,
+  };
+  const toolDefs = tools.anthropicTools(permission);
+  if (toolDefs.length) body.tools = toolDefs;
+
+  const idle = idleAbort(signal, IDLE_MS);
+  const resp = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+    signal: idle.signal,
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    idle.clear();
+    throw new Error(`Anthropic ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 300)}`);
+  }
+
+  const blocks = {}; // index → {type, text, name, id, inputJson}
+  let stopReason = null;
+  let usage = null;
+  for await (const line of iterSse(resp, idle)) {
+    const data = sseData(line);
+    if (!data || data === "[DONE]") continue;
+    let ev;
+    try {
+      ev = JSON.parse(data);
+    } catch {
+      continue;
+    }
+    if (ev.type === "content_block_start") {
+      const cb = ev.content_block || {};
+      blocks[ev.index] = { type: cb.type, text: "", name: cb.name, id: cb.id, inputJson: "" };
+      if (cb.type === "tool_use") ui.tool(cb.name, "");
+      else ui.streamStart();
+    } else if (ev.type === "content_block_delta") {
+      const b = blocks[ev.index] || (blocks[ev.index] = { type: "text", text: "", inputJson: "" });
+      if (ev.delta.type === "text_delta") {
+        b.text += ev.delta.text;
+        ui.streamDelta(ev.delta.text);
+      } else if (ev.delta.type === "input_json_delta") {
+        b.inputJson += ev.delta.partial_json || "";
+      }
+    } else if (ev.type === "content_block_stop") {
+      const b = blocks[ev.index];
+      if (b && b.type === "tool_use") {
+        const arg = safeArg(b.inputJson);
+        if (arg) ui.info(ui.c.dim("  " + arg));
+      }
+      // 텍스트 블록 stop에서는 streamEnd를 호출하지 않는다 — 메모리 가드 중간 flush 방지(턴 끝에서만 flush).
+    } else if (ev.type === "message_start") {
+      const u = ev.message && ev.message.usage;
+      if (u) usage = { input_tokens: u.input_tokens || 0, output_tokens: u.output_tokens || 0 };
+    } else if (ev.type === "message_delta") {
+      if (ev.delta && ev.delta.stop_reason) stopReason = ev.delta.stop_reason;
+      if (ev.usage) usage = { input_tokens: (usage && usage.input_tokens) || 0, output_tokens: ev.usage.output_tokens };
+    }
+  }
+  ui.streamEnd();
+  idle.clear();
+
+  // 어셈블
+  const ordered = Object.keys(blocks)
+    .sort((a, b) => a - b)
+    .map((k) => blocks[k]);
+  const assistantContent = [];
+  const toolUses = [];
+  let text = "";
+  for (const b of ordered) {
+    if (b.type === "text" && b.text) {
+      assistantContent.push({ type: "text", text: b.text });
+      text += b.text;
+    } else if (b.type === "tool_use") {
+      let input = {};
+      try {
+        input = JSON.parse(b.inputJson || "{}");
+      } catch {
+        input = {};
+      }
+      assistantContent.push({ type: "tool_use", id: b.id, name: b.name, input });
+      toolUses.push({ id: b.id, name: b.name, input });
+    }
+  }
+  return { text, assistantContent, toolUses, stopReason, usage };
+}
+
+async function runAnthropicLoop(req) {
+  const { ctx, ui } = req;
+  const messages = req.messages.slice();
+  let finalText = "";
+  let inTok = 0, outTok = 0;
+  for (let i = 0; i < MAX_ITERS; i++) {
+    if (req.signal && req.signal.aborted) break;
+    const r = await streamAnthropic({
+      apiKey: req.apiKey,
+      model: req.model,
+      system: req.system,
+      messages,
+      permission: ctx.permission,
+      ui,
+      signal: req.signal,
+    });
+    finalText = r.text || finalText;
+    if (r.usage) { inTok += r.usage.input_tokens || 0; outTok += r.usage.output_tokens || 0; }
+    if (!r.toolUses.length) break;
+    messages.push({ role: "assistant", content: r.assistantContent });
+    const results = [];
+    for (const tu of r.toolUses) {
+      const out = tools.runTool(tu.name, tu.input, ctx);
+      ui.toolResult(out.content, out.ok);
+      results.push({ type: "tool_result", tool_use_id: tu.id, content: out.content, is_error: !out.ok });
+    }
+    messages.push({ role: "user", content: results });
+  }
+  if (inTok || outTok) ui.cost({ input_tokens: inTok, output_tokens: outTok });
+  return { text: finalText };
+}
+
+// ── OpenAI ───────────────────────────────────────────────
+async function streamOpenAI({ apiKey, model, messages, permission, ui, signal, baseUrl }) {
+  const body = { model, stream: true, stream_options: { include_usage: true }, messages };
+  const toolDefs = tools.openaiTools(permission);
+  if (toolDefs.length) body.tools = toolDefs;
+
+  const idle = idleAbort(signal, IDLE_MS);
+  const resp = await fetch(`${baseUrl || "https://api.openai.com/v1"}/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+    signal: idle.signal,
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    idle.clear();
+    throw new Error(`OpenAI ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 300)}`);
+  }
+
+  let text = "";
+  let started = false;
+  const toolCalls = {}; // index → {id, name, args}
+  let finish = null;
+  let usage = null;
+  for await (const line of iterSse(resp, idle)) {
+    const data = sseData(line);
+    if (!data || data === "[DONE]") continue;
+    let ev;
+    try {
+      ev = JSON.parse(data);
+    } catch {
+      continue;
+    }
+    if (ev.usage) usage = { input_tokens: ev.usage.prompt_tokens || 0, output_tokens: ev.usage.completion_tokens || 0 };
+    const choice = ev.choices && ev.choices[0];
+    if (!choice) continue;
+    const delta = choice.delta || {};
+    if (delta.content) {
+      if (!started) {
+        ui.streamStart();
+        started = true;
+      }
+      text += delta.content;
+      ui.streamDelta(delta.content);
+    }
+    if (Array.isArray(delta.tool_calls)) {
+      for (const tc of delta.tool_calls) {
+        const idx = tc.index ?? 0;
+        const cur = toolCalls[idx] || (toolCalls[idx] = { id: "", name: "", args: "" });
+        if (tc.id) cur.id = tc.id;
+        if (tc.function && tc.function.name) {
+          if (!cur.name) ui.tool(tc.function.name, "");
+          cur.name = tc.function.name;
+        }
+        if (tc.function && tc.function.arguments) cur.args += tc.function.arguments;
+      }
+    }
+    if (choice.finish_reason) finish = choice.finish_reason;
+  }
+  if (started) ui.streamEnd();
+  idle.clear();
+
+  const calls = Object.keys(toolCalls)
+    .sort((a, b) => a - b)
+    .map((k) => toolCalls[k])
+    .filter((c) => c.name);
+  return { text, toolCalls: calls, finish, usage };
+}
+
+async function runOpenAILoop(req) {
+  const { ctx, ui } = req;
+  const messages = req.messages.slice();
+  // OpenAI는 system을 messages[0]로.
+  if (!messages.length || messages[0].role !== "system") messages.unshift({ role: "system", content: req.system });
+  let finalText = "";
+  let inTok = 0, outTok = 0;
+  for (let i = 0; i < MAX_ITERS; i++) {
+    if (req.signal && req.signal.aborted) break;
+    const r = await streamOpenAI({
+      apiKey: req.apiKey,
+      model: req.model,
+      messages,
+      permission: ctx.permission,
+      ui,
+      signal: req.signal,
+      baseUrl: req.baseUrl,
+    });
+    finalText = r.text || finalText;
+    if (r.usage) { inTok += r.usage.input_tokens || 0; outTok += r.usage.output_tokens || 0; }
+    if (!r.toolCalls.length) break;
+    messages.push({
+      role: "assistant",
+      content: r.text || null,
+      tool_calls: r.toolCalls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.args } })),
+    });
+    for (const c of r.toolCalls) {
+      let args = {};
+      try {
+        args = JSON.parse(c.args || "{}");
+      } catch {
+        args = {};
+      }
+      const arg = safeArgObj(args);
+      if (arg) ui.info(ui.c.dim("  " + arg));
+      const out = tools.runTool(c.name, args, ctx);
+      ui.toolResult(out.content, out.ok);
+      messages.push({ role: "tool", tool_call_id: c.id, content: out.content });
+    }
+  }
+  if (inTok || outTok) ui.cost({ input_tokens: inTok, output_tokens: outTok });
+  return { text: finalText };
+}
+
+// ── Ollama (openai 스타일 tools, /api/chat) ──────────────
+async function runOllamaLoop(req) {
+  const { ctx, ui } = req;
+  const host = process.env.OLLAMA_HOST || "http://127.0.0.1:11434";
+  const messages = req.messages.slice();
+  if (!messages.length || messages[0].role !== "system") messages.unshift({ role: "system", content: req.system });
+  const toolDefs = tools.openaiTools(ctx.permission);
+  let finalText = "";
+  for (let i = 0; i < MAX_ITERS; i++) {
+    if (req.signal && req.signal.aborted) break;
+    const idle = idleAbort(req.signal, IDLE_MS);
+    let resp;
+    try {
+      resp = await fetch(`${host}/api/chat`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        signal: idle.signal,
+        body: JSON.stringify({ model: req.model, stream: true, messages, tools: toolDefs.length ? toolDefs : undefined }),
+      });
+    } catch (e) {
+      idle.clear();
+      throw new Error(`Ollama connection failed (${host}) — is 'ollama serve' running? ${e.message}`);
+    }
+    if (!resp.ok) {
+      idle.clear();
+      throw new Error(`Ollama ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
+    }
+    let text = "";
+    let started = false;
+    let toolCalls = [];
+    for await (const line of iterSse(resp, idle)) {
+      let ev;
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const msg = ev.message || {};
+      if (msg.content) {
+        if (!started) {
+          ui.streamStart();
+          started = true;
+        }
+        text += msg.content;
+        ui.streamDelta(msg.content);
+      }
+      if (Array.isArray(msg.tool_calls)) toolCalls = toolCalls.concat(msg.tool_calls);
+    }
+    if (started) ui.streamEnd();
+    idle.clear();
+    finalText = text || finalText;
+    if (!toolCalls.length) break;
+    messages.push({ role: "assistant", content: text, tool_calls: toolCalls });
+    for (const c of toolCalls) {
+      const fn = c.function || {};
+      const args = typeof fn.arguments === "string" ? safeParse(fn.arguments) : fn.arguments || {};
+      ui.tool(fn.name || "tool", safeArgObj(args));
+      const out = tools.runTool(fn.name, args, ctx);
+      ui.toolResult(out.content, out.ok);
+      // Ollama tool 결과는 tool_call_id가 없으므로 tool_name으로 상관관계를 보존 (병렬 호출 시 중요)
+      messages.push({ role: "tool", tool_name: fn.name, content: out.content });
+    }
+  }
+  return { text: finalText };
+}
+
+// ── Google (chat-only 스트리밍) ──────────────────────────
+async function runGoogleChat(req) {
+  const { ui } = req;
+  const contents = [];
+  for (const m of req.messages) {
+    if (m.role === "user") contents.push({ role: "user", parts: [{ text: textOf(m.content) }] });
+    else if (m.role === "assistant") contents.push({ role: "model", parts: [{ text: textOf(m.content) }] });
+  }
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${req.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(req.apiKey)}`;
+  const idle = idleAbort(req.signal, IDLE_MS);
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    signal: idle.signal,
+    body: JSON.stringify({ systemInstruction: { parts: [{ text: req.system }] }, contents }),
+  });
+  if (!resp.ok) {
+    idle.clear();
+    throw new Error(`Google ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 300)}`);
+  }
+  let text = "";
+  let started = false;
+  for await (const line of iterSse(resp, idle)) {
+    const data = sseData(line);
+    if (!data || data === "[DONE]") continue;
+    let ev;
+    try {
+      ev = JSON.parse(data);
+    } catch {
+      continue;
+    }
+    const t = ev.candidates && ev.candidates[0] && ev.candidates[0].content && ev.candidates[0].content.parts && ev.candidates[0].content.parts[0] && ev.candidates[0].content.parts[0].text;
+    if (t) {
+      if (!started) {
+        ui.streamStart();
+        started = true;
+      }
+      text += t;
+      ui.streamDelta(t);
+    }
+  }
+  if (started) ui.streamEnd();
+  idle.clear();
+  return { text };
+}
+
+// ── 엔트리 ───────────────────────────────────────────────
+// req = { backend, model, apiKey, system, messages([{role,content}]), ctx({cwd,permission}), ui, signal }
+async function runApiTurn(req) {
+  switch (req.backend) {
+    case "anthropic":
+      return runAnthropicLoop(req);
+    case "openai":
+      return runOpenAILoop(req);
+    case "upstage":
+      return runOpenAILoop({ ...req, baseUrl: "https://api.upstage.ai/v1" });
+    case "ollama":
+      return runOllamaLoop(req);
+    case "google":
+      return runGoogleChat(req);
+    default:
+      throw new Error(`unsupported backend: ${req.backend}`);
+  }
+}
+
+function safeParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return {};
+  }
+}
+function safeArg(json) {
+  return safeArgObj(safeParse(json || "{}"));
+}
+function safeArgObj(o) {
+  if (!o || typeof o !== "object") return "";
+  return o.file_path || o.path || o.command || o.pattern || o.query || "";
+}
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((b) => (b.type === "text" ? b.text : "")).join("");
+  return "";
+}
+
+module.exports = { runApiTurn, MAX_ITERS };

package/engine/agentlas-banner.cjs

@@ -0,0 +1,108 @@
+"use strict";
+/*
+ * Agentlas terminal splash — small dinosaur mascot (Chrome-dino style) + wordmark + status.
+ */
+const path = require("node:path");
+const os = require("node:os");
+
+// Small T-Rex (side view, facing right) — eye is ●.
+const DINO_ART = [
+  "          ▟████▙",
+  "          █●  ▜█▙",
+  "   ▖      ████████",
+  "   ▜█▄▄▄▄▄███",
+  "    ▀▀▀█▌ █▌",
+];
+
+function readVersion() {
+  try {
+    return require(path.join(__dirname, "..", "package.json")).version || "";
+  } catch {
+    return "";
+  }
+}
+
+function shorten(p) {
+  if (!p) return "";
+  const home = os.homedir();
+  return p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}
+
+// Just the mascot lines (used by the onboarding wizard header).
+function renderMascot(ui) {
+  const c = ui.c;
+  if (!ui.enabled) {
+    ui.line("  Agentlas");
+    return;
+  }
+  for (let i = 0; i < DINO_ART.length; i++) {
+    const row = DINO_ART[i];
+    ui.line("   " + (i === 1 ? c.text(row).split("●").join(c.emerald("●")) : c.text(row)));
+  }
+}
+
+function stripAnsi(s) {
+  return String(s || "").replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function fit(value, width) {
+  let s = stripAnsi(value);
+  if (s.length > width) {
+    if (width <= 1) return "…";
+    s = s.slice(0, Math.max(0, width - 1)) + "…";
+  }
+  return s + " ".repeat(Math.max(0, width - s.length));
+}
+
+function row(ui, width, text) {
+  const inner = Math.max(10, width - 4);
+  ui.line(ui.c.faint("│ ") + ui.c.text(fit(text, inner)) + ui.c.faint(" │"));
+}
+
+function renderStatusCard(ctx, opts = {}) {
+  const ui = ctx.ui;
+  const c = ui.c;
+  const cols = ui.out.columns || 80;
+  const width = Math.max(54, Math.min(cols - 2, 78));
+  const version = ctx.version || readVersion();
+  const subject = ctx.subjectLabel || "Pick an agent, choose a company, or type a task";
+  const permission = ctx.permission || "write";
+  const runtime = ctx.runtimeLabel || "(not configured)";
+  const cwd = ctx.cwd ? shorten(ctx.cwd) : process.cwd();
+
+  ui.line("");
+  ui.line(c.faint("╭" + "─".repeat(width - 2) + "╮"));
+  row(ui, width, `>_ Agentlas${version ? " (v" + version + ")" : ""}`);
+  row(ui, width, "");
+  row(ui, width, `model:       ${runtime}`);
+  row(ui, width, `agent:       ${subject}`);
+  row(ui, width, `directory:   ${cwd}`);
+  row(ui, width, `permissions: ${permission}`);
+  ui.line(c.faint("╰" + "─".repeat(width - 2) + "╯"));
+  if (!opts.noTip) {
+    ui.line(
+      "  " +
+        c.bold(c.text("Tip:")) +
+        c.dim(" Type ") +
+        c.faint("/help") +
+        c.dim(" for commands, ") +
+        c.faint("/status") +
+        c.dim(" for session state, ") +
+        c.faint("/exit") +
+        c.dim(" to quit."),
+    );
+  }
+}
+
+// Main splash. ctx = { ui, version, runtimeLabel, subjectLabel, permission, cwd }
+function renderBanner(ctx) {
+  renderStatusCard(ctx);
+  ctx.ui.line("");
+}
+
+// runtime · subject · permission · working folder
+function renderStatus(ctx) {
+  renderStatusCard(ctx, { noTip: true });
+}
+
+module.exports = { renderBanner, renderStatus, renderMascot, readVersion, shorten, DINO_ART, fit };

package/engine/agentlas-capabilities.cjs

@@ -0,0 +1,72 @@
+"use strict";
+/*
+ * Runtime capability registry (core) + capability-aware auto-routing.
+ *
+ * User-verified (2026-05): images are produced by the native CLIs themselves —
+ *   codex  → Imagen,  gemini → nano-banana (Gemini 2.5 Flash Image),  claude → NO image gen.
+ * BYOK: openai (gpt-image) and google (imagen) can do images; anthropic/ollama cannot.
+ *
+ * So a multi-LLM team = each agent runs on a runtime whose capabilities match its job:
+ * an image/design agent auto-routes to gemini/codex, a coding agent to claude/codex.
+ */
+
+// keyed by runtime "spec": cli kind (claude-code|codex|gemini) or api backend (anthropic|openai|google|ollama)
+const RUNTIME_CAPS = {
+  "claude-code": { code: true, image: false, label: "claude" },
+  codex: { code: true, image: true, label: "codex" }, // Imagen
+  gemini: { code: true, image: true, label: "gemini" }, // nano-banana
+  anthropic: { code: true, image: false, label: "anthropic" },
+  openai: { code: true, image: true, label: "openai" }, // gpt-image
+  google: { code: true, image: true, label: "google" }, // imagen
+  ollama: { code: true, image: false, label: "ollama" },
+  upstage: { code: true, image: false, label: "solar" }, // Upstage Solar — Korean sovereign LLM (OpenAI-compatible)
+};
+
+const CLI_KINDS = ["claude-code", "codex", "gemini"];
+
+function capsFor(spec) {
+  return RUNTIME_CAPS[spec] || { code: true, image: false, label: spec || "?" };
+}
+
+// runtime object ⇄ spec string
+function specOf(rt) {
+  if (!rt) return "";
+  return rt.mode === "cli" ? rt.kind : rt.backend;
+}
+function runtimeFromSpec(spec) {
+  return CLI_KINDS.includes(spec) ? { mode: "cli", kind: spec } : { mode: "api", backend: spec, model: null };
+}
+
+// Does this agent's job involve generating/handling images?
+const IMAGE_HINTS = [
+  /image/i, /이미지/, /그림/, /\bdesign\b/i, /디자인/, /쇼핑몰/, /상품\s*(사진|이미지|상세)/, /상세\s*페이지/,
+  /thumbnail/i, /썸네일/, /banner/i, /배너/, /poster/i, /포스터/, /visual/i, /비주얼/, /illustrat/i, /일러스트/,
+  /로고/, /\blogo\b/i, /사진/, /photo/i, /nano-?banana/i, /imagen/i, /이미지\s*생성/, /그래픽/, /graphic/i,
+];
+// 빌더/메타/조율/거버넌스 역할은 (이미지 에이전트를 *만들* 수는 있어도) 스스로 이미지를 생산하지 않는다.
+// 이런 역할이 system_prompt에 "이미지/디자인"을 언급한다는 이유로 gemini로 끌려가면 코드/빌드 품질이 떨어진다.
+const NON_IMAGE_ROLES = new Set(["meta", "builder", "orchestrator", "pm", "curator", "governance"]);
+function needsImage(agent) {
+  if (!agent) return false;
+  if (NON_IMAGE_ROLES.has(String(agent.role || "").toLowerCase())) return false;
+  const hay = `${agent.name || ""} ${agent.name_en || ""} ${agent.tagline || ""} ${agent.tagline_en || ""} ${agent.system_prompt || ""}`;
+  return IMAGE_HINTS.some((re) => re.test(hay));
+}
+
+// Auto-pick a runtime spec for an agent given installed CLI kinds and the session default spec.
+// Image agents route to an installed image-capable runtime; otherwise keep the session default.
+function autoRuntimeFor(agent, { installedKinds, activeSpec }) {
+  if (needsImage(agent)) {
+    if (capsFor(activeSpec).image) return activeSpec;
+    for (const k of ["gemini", "codex"]) if ((installedKinds || []).includes(k)) return k;
+  }
+  return activeSpec;
+}
+
+// short capability badge for display
+function badge(spec) {
+  const c = capsFor(spec);
+  return c.image ? "🖼" : "";
+}
+
+module.exports = { RUNTIME_CAPS, CLI_KINDS, capsFor, specOf, runtimeFromSpec, needsImage, autoRuntimeFor, badge };