@octocodeai/freellama-mcp-server 0.7.0 → 0.9.0

package/dist/research/octocode-agent.js

@@ -1,13 +1,10 @@
-// src/research/octocode-agent.ts
-import { pathToFileURL } from "node:url";
-
 // src/research/adapter.ts
 function isPositiveInt(value) {
   return (typeof value === "boolean" || typeof value === "number" && Number.isInteger(value)) && Number(value) >= 1;
 }
 
 // src/research/agent-loop.ts
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { performance } from "node:perf_hooks";
 import { setTimeout as sleep } from "node:timers/promises";
 
@@ -57,8 +54,21 @@ function isSystemError(error) {
 var ToolTimeoutError = class extends Error {
   name = "ToolTimeoutError";
 };
+var ToolExitError = class extends Error {
+  constructor(exitCode, output, status = "error") {
+    super(`${status === "empty" ? "nothing found" : "command failed"} (exit code ${exitCode})` + (output ? `
+${output}` : ""));
+    this.exitCode = exitCode;
+    this.output = output;
+    this.status = status;
+  }
+  exitCode;
+  output;
+  status;
+  name = "ToolExitError";
+};
 function isToolError(error) {
-  return error instanceof ValidationError || error instanceof ToolTimeoutError || error instanceof SyntaxError || isSystemError(error);
+  return error instanceof ValidationError || error instanceof ToolTimeoutError || error instanceof ToolExitError || error instanceof SyntaxError || isSystemError(error);
 }
 
 // src/research/actions.ts
@@ -362,27 +372,44 @@ var estimateText = (value) => canonicalJson(value, { sortKeys: false, ensureAsci
 function estimateTokens(text, charsPerToken = CHARS_PER_TOKEN) {
   return Math.floor(cpLength(text) / charsPerToken) + 1;
 }
-function messagesTokens(messages, policy = new ContextPolicy()) {
+var UNMEASURED_BYTES_PER_TOKEN_MILLI = 3e3;
+function platformBytesPerTokenMilli(learnedMilli) {
+  if (learnedMilli === null || learnedMilli === void 0) return UNMEASURED_BYTES_PER_TOKEN_MILLI;
+  return Math.min(Math.max(Math.floor(learnedMilli / 10) * 9, 1e3), 8e3);
+}
+function platformTextTokens(text, learnedMilli) {
+  return Math.ceil(Buffer.byteLength(text, "utf8") * 1e3 / platformBytesPerTokenMilli(learnedMilli));
+}
+function messagesTokens(messages, policy = new ContextPolicy(), learnedMilli = null) {
   let total = 0;
   for (const message of messages) {
-    const { content = "", images = [], ...metadata } = message;
-    total += estimateTokens(typeof content === "string" ? content : estimateText(content), policy.chars_per_token);
+    const { images = [], ...text } = message;
     if (Array.isArray(images)) total += images.length * policy.image_token_estimate;
+    if (learnedMilli !== null) {
+      total += platformTextTokens(JSON.stringify(text), learnedMilli) + 1;
+      continue;
+    }
+    const { content = "", ...metadata } = text;
+    total += estimateTokens(typeof content === "string" ? content : estimateText(content), policy.chars_per_token);
     total += estimateTokens(estimateText(metadata), policy.chars_per_token);
   }
   return total;
 }
 var ContextBudgeter = class {
   policy;
+  platformRatio;
   scale;
   calibration_samples;
   constructor(policy = new ContextPolicy(), options = {}) {
     this.policy = policy;
-    this.scale = Math.max(options.initialScale ?? 1, 1);
-    this.calibration_samples = Math.max(Math.trunc(options.calibrationSamples ?? 0), 0);
+    this.platformRatio = options.platformRatio ?? null;
+    this.scale = this.platformRatio ? 1 : Math.max(options.initialScale ?? 1, 1);
+    this.calibration_samples = this.platformRatio ? 0 : Math.max(Math.trunc(options.calibrationSamples ?? 0), 0);
   }
-  estimate = (messages) => Math.ceil(messagesTokens(messages, this.policy) * this.scale);
+  estimate = (messages) => this.platformRatio ? messagesTokens(messages, this.policy, this.platformRatio.bytes_per_token_milli) : Math.ceil(messagesTokens(messages, this.policy) * this.scale);
+  /** Calibrate the fallback estimate; returns whether the multiplier rose (and should persist). */
   observe(messages, promptEvalCount) {
+    if (this.platformRatio) return false;
     if (typeof promptEvalCount !== "number" || !Number.isFinite(promptEvalCount)) return false;
     const actual = Math.trunc(promptEvalCount);
     if (actual <= 0) return false;
@@ -393,10 +420,14 @@ var ContextBudgeter = class {
     return this.scale > previous;
   }
   metadata() {
+    const ratio = this.platformRatio;
     return {
-      token_counting: this.calibration_samples ? "model_calibrated_estimate" : "configured_estimate",
+      token_counting: ratio ? "platform_learned_ratio" : "local_chars_per_token",
       estimate_scale: Math.round(this.scale * 1e6) / 1e6,
-      calibration_samples: this.calibration_samples
+      calibration_samples: this.calibration_samples,
+      bytes_per_token_milli: ratio?.bytes_per_token_milli ?? null,
+      bytes_per_token_milli_with_margin: ratio ? platformBytesPerTokenMilli(ratio.bytes_per_token_milli) : null,
+      bytes_per_token_samples: ratio?.bytes_per_token_samples ?? null
     };
   }
 };
@@ -542,11 +573,16 @@ var AgentContextManager = class {
   constructor(runtime, options = {}) {
     this.runtime = runtime;
     this.model = options.model ?? "";
-    this.calibrationDir = options.calibrationDir ?? null;
+    const platformRatio = options.platformRatio ?? null;
+    this.calibrationDir = platformRatio ? null : options.calibrationDir ?? null;
     this.calibrationIdentity = options.calibrationIdentity ?? "";
     const loaded = this.loadCalibration();
-    this.budgeter = new ContextBudgeter(runtime.context, { initialScale: loaded?.scale ?? 1, calibrationSamples: loaded?.samples ?? 0 });
-    this.calibrationSource = loaded ? "persistent_model_cache" : "current_process";
+    this.budgeter = new ContextBudgeter(runtime.context, {
+      initialScale: loaded?.scale ?? 1,
+      calibrationSamples: loaded?.samples ?? 0,
+      platformRatio
+    });
+    this.calibrationSource = platformRatio ? "not_applied" : loaded ? "persistent_model_cache" : "current_process";
   }
   modelKey() {
     return createHash("sha256").update(this.calibrationContractJson(), "utf8").digest("hex").slice(0, 24);
@@ -840,8 +876,27 @@ ${body}${footer}`;
   }
 };
 
+// src/research/progress-events.ts
+var PROGRESS_ENV = "FREELLAMA_AGENT_PROGRESS";
+var PROGRESS_PREFIX = "@freellama-progress ";
+function progressEmitter(env, write = (line) => {
+  process.stderr.write(line);
+}) {
+  if (env[PROGRESS_ENV] !== "stderr") return void 0;
+  return (event) => {
+    try {
+      write(`${PROGRESS_PREFIX}${JSON.stringify(event)}
+`);
+    } catch {
+    }
+  };
+}
+
 // src/research/transport.ts
 import { createHash as createHash2 } from "node:crypto";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { homedir } from "node:os";
+import path3 from "node:path";
 
 // src/research/transport-http.ts
 import { readFileSync as readFileSync3 } from "node:fs";
@@ -903,13 +958,21 @@ function httpRequest(url, options) {
     if (options.body) headers["content-length"] = String(options.body.length);
     let sent = false;
     let settled = false;
+    const { signal } = options;
+    const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error("request aborted"));
     const fail = (error) => {
       if (settled) return;
       settled = true;
+      signal?.removeEventListener("abort", onAbort);
       request.destroy();
       reject(error);
     };
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("request aborted"));
+      return;
+    }
     const request = client.request(parsed, { method: options.method, headers });
+    signal?.addEventListener("abort", onAbort, { once: true });
     request.setTimeout(Math.max(options.timeoutSeconds * 1e3, 1), () => {
       fail(sent ? new RequestTimeoutError() : new URLError(new RequestTimeoutError()));
     });
@@ -926,6 +989,7 @@ function httpRequest(url, options) {
       const finish = () => {
         if (settled) return;
         settled = true;
+        signal?.removeEventListener("abort", onAbort);
         const body = Buffer.concat(chunks);
         request.destroy();
         if (ok) resolve(body);
@@ -957,11 +1021,25 @@ async function requestJson(url, payload, timeoutSeconds) {
 var MANAGED_SUFFIX = "/_freellama/v1/tasks";
 var IDENTITY_LIMIT = 1024 * 1024;
 var trimSlashes = (text) => text.replace(/\/+$/, "");
-async function readIdentityJson(url) {
-  const payload = await httpRequest(url, { method: "GET", headers: requestHeaders(), timeoutSeconds: 5, limit: IDENTITY_LIMIT + 1 });
+async function readCatalogJson(url, request = httpRequest) {
+  const payload = await request(url, { method: "GET", headers: requestHeaders(), timeoutSeconds: 5, limit: IDENTITY_LIMIT + 1 });
   if (payload.length > IDENTITY_LIMIT) throw new ValidationError("model identity catalog exceeds size limit");
   return parseJsonBody(payload, "model identity catalog");
 }
+function catalogEntry(payload, model) {
+  const entries = isRecord(payload) ? payload.models ?? [] : [];
+  if (!Array.isArray(entries)) return null;
+  const names = /* @__PURE__ */ new Set([model]);
+  const lastSegment = model.slice(model.lastIndexOf("/") + 1);
+  if (!lastSegment.includes(":")) names.add(model + ":latest");
+  for (const item of entries) {
+    if (!isRecord(item)) continue;
+    const name = Object.hasOwn(item, "name") ? item.name : item.model;
+    if (typeof name === "object" && name !== null) return "ambiguous";
+    if (typeof name === "string" && names.has(name)) return item;
+  }
+  return null;
+}
 var DIGEST = /^(?:sha256:)?[0-9a-fA-F]{64}$/;
 var sha256 = (data) => createHash2("sha256").update(data, "utf8").digest("hex");
 async function resolveModelIdentity(endpointInput, model, systemPrompt, options = {}) {
@@ -969,22 +1047,8 @@ async function resolveModelIdentity(endpointInput, model, systemPrompt, options
   const url = endpoint.endsWith(MANAGED_SUFFIX) ? endpoint.slice(0, -MANAGED_SUFFIX.length) + "/_freellama/v1/models" : endpoint + "/api/tags";
   const unknown = { identity: "", verified: false, scope: "current_process_only" };
   try {
-    const payload = await (options.readJson ?? readIdentityJson)(url);
-    const entries = isRecord(payload) ? payload.models ?? [] : [];
-    if (!Array.isArray(entries)) return unknown;
-    const names = /* @__PURE__ */ new Set([model]);
-    const lastSegment = model.slice(model.lastIndexOf("/") + 1);
-    if (!lastSegment.includes(":")) names.add(model + ":latest");
-    let entry = null;
-    for (const item of entries) {
-      if (!isRecord(item)) continue;
-      const name = Object.hasOwn(item, "name") ? item.name : item.model;
-      if (typeof name === "object" && name !== null) return unknown;
-      if (typeof name === "string" && names.has(name)) {
-        entry = item;
-        break;
-      }
-    }
+    const entry = catalogEntry(await (options.readJson ?? readCatalogJson)(url), model);
+    if (entry === "ambiguous") return unknown;
     const digestValue = entry?.digest;
     if (typeof digestValue !== "string" || !DIGEST.test(digestValue)) return unknown;
     const digest = (digestValue.startsWith("sha256:") ? digestValue.slice("sha256:".length) : digestValue).toLowerCase();
@@ -1002,11 +1066,36 @@ async function resolveModelIdentity(endpointInput, model, systemPrompt, options
     throw error;
   }
 }
+async function resolvePlatformTokenRatio(serveEndpoint, model, options = {}) {
+  try {
+    const url = `${trimSlashes(serveEndpoint)}/_freellama/v1/models`;
+    const entry = catalogEntry(await (options.readJson ?? readCatalogJson)(url), model);
+    if (entry === null || entry === "ambiguous") return null;
+    const milli = entry.bytes_per_token_milli;
+    if (typeof milli !== "number" || !Number.isSafeInteger(milli) || milli <= 0) return null;
+    const samples = entry.bytes_per_token_samples;
+    return {
+      bytes_per_token_milli: milli,
+      bytes_per_token_samples: typeof samples === "number" && Number.isSafeInteger(samples) && samples > 0 ? samples : 1
+    };
+  } catch {
+    return null;
+  }
+}
 function isTransportError(error) {
   return error instanceof HTTPError || error instanceof URLError || error instanceof RequestTimeoutError;
 }
 function retryableChatError(error) {
-  if (error instanceof HTTPError) return error.code === 503;
+  if (error instanceof HTTPError) {
+    if (error.code !== 503 || error.body.length > RECEIPT_BODY_LIMIT) return false;
+    try {
+      const body = parseJsonBody(error.body, "retry receipt");
+      if (!isRecord(body) || body.retry_safe === false || body.execution_outcome !== void 0 && body.execution_outcome !== "not_started") return false;
+      return body.retry_safe === true && body.execution_outcome === "not_started" || ["admission_timeout", "resource_admission_unavailable", "upstream_circuit_open", "model_lifecycle_busy"].includes(String(body.code));
+    } catch {
+      return false;
+    }
+  }
   return error instanceof URLError && error.reason.code === "ECONNREFUSED";
 }
 var RECEIPT_FIELDS = /* @__PURE__ */ new Set([
@@ -1022,7 +1111,12 @@ var RECEIPT_FIELDS = /* @__PURE__ */ new Set([
   "route",
   "decision",
   "quality",
-  "feedback"
+  "feedback",
+  "execution_outcome",
+  "retry_safe",
+  "result_recoverable",
+  "job_id",
+  "last_observed_status"
 ]);
 var PAYLOAD_FIELDS = /* @__PURE__ */ new Set([
   "prompt",
@@ -1105,6 +1199,22 @@ var PromptCacheUsage = class {
     };
   }
 };
+var resolvedShift;
+function contextShift(env = process.env, reset = false) {
+  if (resolvedShift !== void 0 && !reset) return resolvedShift;
+  const read = (value2) => value2 === "ollama_default" || value2 === "off" ? value2 : void 0;
+  let value = read(env.FREELLAMA_CONTEXT_SHIFT?.trim());
+  if (!value) {
+    const file = env.FREELLAMA_RUNTIME_CONFIG || path3.join(env.FREELLAMA_HOME || path3.join(homedir(), ".octocode", "freellama"), "runtime.toml");
+    try {
+      const topLevel = readFileSync4(file, "utf8").split(/^\s*\[/m)[0] ?? "";
+      value = read(/^\s*context_shift\s*=\s*"([^"]*)"/m.exec(topLevel)?.[1]);
+    } catch {
+    }
+  }
+  resolvedShift = value ?? "off";
+  return resolvedShift;
+}
 function chatRequest(endpointInput, model, messages, options, think, keepAlive, executionPreference = "auto", minPlacementEvidence = "configured") {
   const endpoint = trimSlashes(endpointInput);
   if (endpoint.endsWith(MANAGED_SUFFIX)) {
@@ -1130,7 +1240,7 @@ function chatRequest(endpointInput, model, messages, options, think, keepAlive,
     messages,
     stream: false,
     truncate: false,
-    shift: false,
+    ...contextShift() === "ollama_default" ? {} : { shift: false },
     format: "json",
     think,
     keep_alive: keepAlive,
@@ -1152,9 +1262,322 @@ function unwrapChatResponse(payload, executionReceipts) {
   return response;
 }
 
+// src/research/transport-jobs.ts
+import { STATUS_CODES } from "node:http";
+
+// src/job-progress.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "expired"]);
+var SUBMIT_FALLBACK_CODES = /* @__PURE__ */ new Set(["task_job_input_too_large", "task_jobs_full", "task_jobs_input_budget"]);
+var RETENTION_FAILURE_CODES = /* @__PURE__ */ new Set(["task_job_result_too_large", "task_job_error_too_large"]);
+var FIRST_POLL_MS = 250;
+var HEARTBEAT_MS = 1e4;
+var MAX_POLL_MS = 2e3;
+var MAX_POLL_FAILURES = 5;
+var CANCEL_ATTEMPTS = 3;
+var CANCEL_BACKOFF_MS = 250;
+var CANCEL_REPORT_MS = 5e3;
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+var number = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var gigabytes = (bytes) => `${(bytes / 1e9).toFixed(1)} GB`;
+var seconds = (ms) => ms < 1e4 ? `${(ms / 1e3).toFixed(1)} s` : `${Math.round(ms / 1e3)} s`;
+function modelNames(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (typeof item === "string") return [item];
+    const named = object(item)?.model ?? object(item)?.name;
+    return typeof named === "string" ? [named] : [];
+  });
+}
+function evictedSuffix(detail) {
+  const evicted = modelNames(detail?.evicted ?? detail?.evicted_idle_models);
+  return evicted.length > 0 ? `, evicted ${evicted.join(", ")}` : "";
+}
+function holdersSuffix(detail) {
+  const holders = Array.isArray(detail?.memory_holders) ? detail.memory_holders : [];
+  const named = holders.map((holder) => holder).filter((holder) => typeof holder.name === "string" && typeof holder.resident_bytes === "number").slice(0, 3).map((holder) => {
+    const count = typeof holder.processes === "number" && holder.processes > 1 ? ` \xD7${holder.processes}` : "";
+    return `${holder.name}${count} ${gigabytes(holder.resident_bytes)}`;
+  });
+  return named.length > 0 ? `; largest memory users: ${named.join(", ")}` : "";
+}
+function jobProgressMessage(job) {
+  const status = typeof job.status === "string" ? job.status : "queued";
+  const reason = typeof job.reason === "string" ? job.reason : "";
+  const detail = object(job.detail);
+  const model = typeof job.selected_model === "string" && job.selected_model ? job.selected_model : void 0;
+  switch (status) {
+    case "queued":
+      return "queued";
+    case "waiting_for_admission":
+      return reason === "resources_reserved_waiting_for_backend_capacity" ? "memory reserved; waiting for backend capacity" : "waiting for backend capacity";
+    case "waiting_for_resources": {
+      const need = number(detail?.required_available_bytes);
+      const available = number(detail?.effective_available_bytes);
+      if (need === void 0 && available === void 0) {
+        return (reason === "checking_host_resources" ? "checking host memory" : "waiting for memory") + evictedSuffix(detail);
+      }
+      const sizes = [need !== void 0 ? `need ${gigabytes(need)}` : void 0, available !== void 0 ? `${gigabytes(available)} available` : void 0].filter(Boolean).join(", ");
+      const pressure = Array.isArray(detail?.pressure_reasons) ? detail.pressure_reasons.map((item) => typeof item === "string" ? item : JSON.stringify(item)) : [];
+      return `waiting for memory: ${sizes}${pressure.length > 0 ? ` (host: ${pressure.join(", ")})` : ""}${holdersSuffix(detail)}${evictedSuffix(detail)}`;
+    }
+    case "waiting_for_runner":
+      return "waiting for runner";
+    case "loading": {
+      const expected = number(detail?.expected_load_ms);
+      return `loading ${model ?? "model"}${expected !== void 0 ? ` (~${seconds(expected)})` : ""}${evictedSuffix(detail)}`;
+    }
+    case "running":
+      return model ? `running ${model}` : "running";
+    default:
+      return status.replace(/_/g, " ");
+  }
+}
+function errorBody(error) {
+  try {
+    return object(JSON.parse(error instanceof Error ? error.message : String(error)));
+  } catch {
+    return void 0;
+  }
+}
+function describeNapiError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const missing = /does not exist or has expired|\bHTTP 404\b|^\s*(?:404\b|Not Found\s*$)/i.test(message);
+  return { body: errorBody(error), ...missing ? { status: 404 } : {} };
+}
+function unconfirmedSubmission(error, body) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (body && (typeof body.code === "string" || "execution_outcome" in body || "retry_safe" in body)) {
+    return error instanceof Error ? error : new Error(message);
+  }
+  return new Error(JSON.stringify({
+    ...body,
+    error: typeof body?.error === "string" ? body.error : message,
+    execution_outcome: "unknown",
+    retry_safe: false
+  }));
+}
+function submissionRefused({ body }) {
+  const code = body?.code;
+  return typeof code === "string" && SUBMIT_FALLBACK_CODES.has(code);
+}
+var defaultWait = (ms, signal) => new Promise((resolve) => {
+  if (signal?.aborted) return resolve();
+  const done = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", done);
+    resolve();
+  };
+  const timer = setTimeout(done, ms);
+  signal?.addEventListener("abort", done, { once: true });
+});
+async function runWithJobProgress(calls, report, options = {}) {
+  const { signal, wait = defaultWait, describe = describeNapiError, onJob } = options;
+  const aborted = (id2, cancellation2) => options.aborted?.(id2, cancellation2) ?? new Error(id2 ? cancellation2 === "unknown" ? `run_task was cancelled by the client; cancellation acknowledgement is unknown for deferred job ${id2}, which may still be running. Upstream stop is not confirmed.` : `run_task was cancelled by the client; cancellation was requested for deferred job ${id2}${cancellation2 === "acknowledged" ? " and acknowledged by serve" : ""}. Upstream stop is not confirmed.` : "run_task was cancelled by the client before a job handle was received; execution outcome is unknown. The task was not replayed.");
+  if (signal?.aborted) throw options.aborted?.() ?? new Error("run_task was cancelled by the client before submission; no task was submitted.");
+  let raw;
+  try {
+    raw = await calls.submit();
+  } catch (error) {
+    if (signal?.aborted) throw aborted();
+    const described = describe(error);
+    if (submissionRefused(described)) return calls.sync(described.body);
+    throw options.unconfirmed?.(error, described.body) ?? unconfirmedSubmission(error, described.body);
+  }
+  let submitted;
+  try {
+    submitted = object(JSON.parse(raw));
+  } catch {
+    return raw;
+  }
+  let job = object(submitted?.job);
+  const id = typeof job?.id === "string" ? job.id : void 0;
+  if (submitted?.deferred !== true || !job || !id) return raw;
+  onJob?.(id, true);
+  let open = true;
+  const settled = () => {
+    if (open) onJob?.(id, false);
+    open = false;
+  };
+  let cancellation;
+  const requestCancellation = async () => {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        const reply = object(JSON.parse(await calls.cancel(id)));
+        const status = object(reply?.job)?.status ?? reply?.status;
+        if (!TERMINAL.has(String(status))) return "requested";
+        settled();
+        return "acknowledged";
+      } catch (error) {
+        if (describe(error).status === 404) {
+          settled();
+          return "unknown";
+        }
+        if (attempt >= CANCEL_ATTEMPTS) return "unknown";
+        await wait(CANCEL_BACKOFF_MS * 2 ** (attempt - 1));
+      }
+    }
+  };
+  const cancel = () => {
+    cancellation ??= requestCancellation();
+  };
+  const cancellationState = async () => {
+    if (!cancellation) return void 0;
+    let timer;
+    const capped = new Promise((resolve) => {
+      timer = setTimeout(() => resolve("unknown"), CANCEL_REPORT_MS);
+    });
+    try {
+      return await Promise.race([cancellation, capped]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  try {
+    let lastMessage = "";
+    let lastPhase = "";
+    let lastReportAt = Date.now();
+    let phaseStartedAt = lastReportAt;
+    let delay = FIRST_POLL_MS;
+    let failures = 0;
+    for (; ; ) {
+      if (signal?.aborted) {
+        cancel();
+        throw aborted(id, await cancellationState());
+      }
+      const now = Date.now();
+      const phase = `${String(job.status)}|${String(job.reason)}`;
+      if (phase !== lastPhase) {
+        lastPhase = phase;
+        phaseStartedAt = now;
+        delay = FIRST_POLL_MS;
+      }
+      const message = jobProgressMessage(job);
+      if (message !== lastMessage) {
+        report(message);
+        lastMessage = message;
+        lastReportAt = now;
+      } else if (now - lastReportAt >= HEARTBEAT_MS && !TERMINAL.has(String(job.status))) {
+        report(`${message} (${seconds(now - phaseStartedAt)})`);
+        lastReportAt = now;
+      }
+      if (TERMINAL.has(String(job.status))) break;
+      await wait(delay, signal);
+      if (signal?.aborted) {
+        cancel();
+        throw aborted(id, await cancellationState());
+      }
+      delay = Math.min(MAX_POLL_MS, Math.round(delay * 1.5));
+      try {
+        const polled = object(object(JSON.parse(await calls.get(id)))?.job);
+        if (polled) job = polled;
+        failures = 0;
+      } catch (error) {
+        if (describe(error).status === 404) {
+          settled();
+          const failure2 = {
+            code: "task_job_unavailable",
+            error: `Deferred job ${id} is no longer available; its execution outcome is unknown. The task was not run again. Its result cannot be recovered from the missing job record; verify the original execution before submitting new work.`,
+            job_id: id,
+            last_observed_status: job.status,
+            execution_outcome: "unknown",
+            result_recoverable: false,
+            retry_safe: false
+          };
+          throw options.failure?.(failure2, 404) ?? new Error(JSON.stringify(failure2));
+        }
+        failures += 1;
+        if (failures >= MAX_POLL_FAILURES) {
+          cancel();
+          throw error;
+        }
+      }
+    }
+    settled();
+    if (job.status === "completed") return JSON.stringify(job.result ?? {});
+    const failure = { ...object(job.error) ?? { error: `deferred job ${id} ended ${String(job.status)}` } };
+    if (typeof failure.code === "string" && RETENTION_FAILURE_CODES.has(failure.code)) {
+      const lost = failure.code === "task_job_result_too_large" ? "result" : "error";
+      failure.error = `${String(failure.error)} Deferred job ${id} was not run again. Its original ${lost} was not retained and cannot be recovered from this job; resubmission would execute new work.`;
+      failure.job_id = id;
+      failure.result_recoverable = false;
+      failure.retry_safe = false;
+    }
+    const status = typeof failure.status === "number" ? failure.status : void 0;
+    delete failure.id;
+    delete failure.ok;
+    if (status !== void 0) delete failure.status;
+    throw options.failure?.(failure, status) ?? new Error(JSON.stringify(failure));
+  } finally {
+    signal?.removeEventListener("abort", cancel);
+  }
+}
+
+// src/research/transport-jobs.ts
+var TASKS_SUFFIX = "/_freellama/v1/tasks";
+function describeHttpError(error) {
+  if (!(error instanceof HTTPError)) return {};
+  try {
+    const body = parseJsonBody(error.body.subarray(0, RECEIPT_BODY_LIMIT), "error body");
+    return { status: error.code, ...isRecord(body) ? { body } : {} };
+  } catch {
+    return { status: error.code };
+  }
+}
+function syncError(body, status) {
+  const code = status ?? 500;
+  return new HTTPError(code, STATUS_CODES[code] ?? "", Buffer.from(JSON.stringify(body), "utf8"));
+}
+async function requestJsonAsJob(url, payload, timeoutSeconds, options) {
+  const request = options.request ?? httpRequest;
+  const headers = requestHeaders();
+  const call = async (method, target, body, signal) => {
+    const sent = body === void 0 ? void 0 : Buffer.from(JSON.stringify(body), "utf8");
+    const response = await request(target, { method, headers, body: sent, timeoutSeconds, signal });
+    return decodeUtf8(response, "managed task response");
+  };
+  const sync = () => call("POST", url, payload);
+  if (!url.endsWith(TASKS_SUFFIX)) return parseJsonBody(Buffer.from(await sync(), "utf8"), "chat response");
+  const jobs = `${url.slice(0, -TASKS_SUFFIX.length)}/_freellama/v1/jobs`;
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(), Math.max(timeoutSeconds * 1e3, 1));
+  try {
+    const raw = await runWithJobProgress({
+      submit: () => call("POST", url, { ...payload, defer: true }),
+      get: (id) => call("GET", `${jobs}/${encodeURIComponent(id)}`, void 0, deadline.signal),
+      cancel: (id) => call("POST", `${jobs}/${encodeURIComponent(id)}/cancel`, null),
+      sync: async () => {
+        throw syncError({
+          code: "cancellable_task_unavailable",
+          error: "Serve refused job submission before execution; cancellable research requires available job capacity and a supported request size.",
+          execution_outcome: "not_started",
+          retry_safe: true
+        }, 409);
+      }
+    }, options.report, {
+      signal: deadline.signal,
+      wait: options.wait,
+      describe: describeHttpError,
+      failure: syncError,
+      aborted: () => new RequestTimeoutError(),
+      // Keep transport types, but do not let an arbitrary 503 erase an uncertain submission.
+      unconfirmed: (error, body) => error instanceof HTTPError && !retryableChatError(error) ? syncError({
+        ...body,
+        error: typeof body?.error === "string" ? body.error : error.message,
+        execution_outcome: body?.execution_outcome ?? "unknown",
+        retry_safe: false
+      }, error.code) : error,
+      onJob: options.onJob
+    });
+    return parseJsonBody(Buffer.from(raw, "utf8"), "chat response");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/research/workspace-path.ts
 import { lstatSync, readlinkSync, statSync } from "node:fs";
-import path3 from "node:path";
+import path4 from "node:path";
 var SymlinkLoopError = class extends ValidationError {
   name = "SymlinkLoopError";
 };
@@ -1209,7 +1632,47 @@ function resolvePath(target, cwd = process.cwd()) {
     return current;
   };
   const text = cleanPath(target);
-  return path3.posix.normalize(walk(text.startsWith("/") ? "" : cwd, text) || "/");
+  return path4.posix.normalize(walk(text.startsWith("/") ? "" : cwd, text) || "/");
+}
+
+// src/research/grounding.ts
+import { existsSync as existsSync3 } from "node:fs";
+import path5 from "node:path";
+var PATH_TOKEN = /(?<![\w@/.-])(?:\.\/)?[\w@-][\w@.-]*(?:\/[\w@.-]+)+\.[A-Za-z][A-Za-z0-9]{0,5}(?=$|[\s:`'"),.;\]])/g;
+function clean(token) {
+  return token.replace(/^\.\//, "").replace(/[.,;]+$/, "");
+}
+function pathsIn(text) {
+  return [...new Set([...text.matchAll(PATH_TOKEN)].map((match) => clean(match[0])))];
+}
+function missingPaths(answer, workspace) {
+  return pathsIn(answer).filter((candidate) => !existsSync3(path5.join(workspace, candidate)));
+}
+function evidencePaths(observations, workspace, limit = 10) {
+  const found = [];
+  for (const text of observations) {
+    for (const candidate of pathsIn(text)) {
+      if (!found.includes(candidate) && existsSync3(path5.join(workspace, candidate))) found.push(candidate);
+      if (found.length >= limit) return found;
+    }
+  }
+  return found;
+}
+function groundingRepairNotice(missing, evidence) {
+  return `These paths in your answer do not exist in the workspace: ${missing.join(", ")}. ` + (evidence.length > 0 ? `Paths your own commands returned: ${evidence.join(", ")}. ` : "") + "Return a finish action again that cites only paths that exist; if the evidence does not establish the answer, say so.";
+}
+function groundingNote(missing) {
+  return `
+[freellama: cited path(s) not found in the workspace: ${missing.join(", ")}; treat this answer as unverified]`;
+}
+function toolErrorHint(message) {
+  if (/rg: unrecognized flag --(?:exclude-dir|include)/.test(message)) {
+    return "\nHint: rg excludes directories with --glob '!node_modules' and filters types with -t ts; or use grep -rn PATTERN . --exclude-dir=node_modules.";
+  }
+  return "";
+}
+function sourceRepairNotice(evidence) {
+  return `Your answer names no source file. Keep the answer and end it with "Source: path:line" copied from your results, for example one of: ${evidence.slice(0, 6).join(", ")}.`;
 }
 
 // src/research/agent-loop.ts
@@ -1219,7 +1682,7 @@ function requireEnv(env, name) {
   if (value === void 0) throw new Error(`${name} is not set`);
   return value;
 }
-var readText = (file) => normalizeNewlines(decodeUtf8(readFileSync4(file), file));
+var readText = (file) => normalizeNewlines(decodeUtf8(readFileSync5(file), file));
 var pathOf = (value) => value === "" ? "." : value;
 var numberOr = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : typeof value === "boolean" ? Number(value) : fallback;
 var echo = (action) => canonicalJson(action, { sortKeys: false, ensureAscii: false });
@@ -1249,9 +1712,15 @@ async function runLoop(spec, hooks, env, inputs) {
   const { model, workspace, prompt, resultPath } = inputs;
   const print = hooks.print ?? ((line) => process.stdout.write(`${line}
 `));
-  const sendJson = hooks.requestJson ?? requestJson;
+  const progress = hooks.progress ?? progressEmitter(env);
   const endpoint = (env.FREELLAMA_OLLAMA_ENDPOINT ?? "http://127.0.0.1:11434").replace(/\/+$/, "");
   const managedEndpoint = (env.FREELLAMA_AGENT_MANAGED_ENDPOINT ?? "").replace(/\/+$/, "");
+  let phaseAt = { maxTurns: 0 };
+  const sendJson = hooks.requestJson ?? (managedEndpoint ? (url, payload, timeoutSeconds) => requestJsonAsJob(url, payload, timeoutSeconds, {
+    report: (message) => progress?.({ event: "job_phase", ...phaseAt, message }),
+    onJob: (id, open) => progress?.({ event: open ? "job_open" : "job_closed", id }),
+    request: hooks.httpRequest
+  }) : requestJson);
   const executionPreference = env.FREELLAMA_AGENT_EXECUTION_PREFERENCE ?? "auto";
   const minPlacementEvidence = env.FREELLAMA_AGENT_MIN_PLACEMENT_EVIDENCE ?? "configured";
   let runtime;
@@ -1266,7 +1735,7 @@ async function runLoop(spec, hooks, env, inputs) {
   }
   let messages = [
     { role: "system", content: spec.systemPrompt(workspace) },
-    { role: "user", content: prompt }
+    { role: "user", content: withBriefing(prompt, spec, workspace) }
   ];
   const calls = [];
   const usage = { input_tokens: 0, output_tokens: 0, cache_read_tokens: null, cache_write_tokens: null };
@@ -1276,12 +1745,20 @@ async function runLoop(spec, hooks, env, inputs) {
   let answer = "";
   let failure = null;
   let transportError = null;
+  const readCatalog = (url) => readCatalogJson(url, hooks.httpRequest);
+  const platformRatio = managedEndpoint ? await (hooks.resolvePlatformTokenRatio ?? resolvePlatformTokenRatio)(managedEndpoint, model, { readJson: readCatalog }) : null;
   const calibrationDir = trimSpace(env.FREELLAMA_AGENT_TOKEN_CALIBRATION_DIR ?? "");
-  const calibrationModelIdentity = calibrationDir ? await (hooks.resolveModelIdentity ?? resolveModelIdentity)(managedEndpoint || endpoint, model, messages[0].content) : { verified: false, scope: "persistence_disabled", identity: "" };
+  const calibrationModelIdentity = calibrationDir ? await (hooks.resolveModelIdentity ?? resolveModelIdentity)(
+    managedEndpoint || endpoint,
+    model,
+    messages[0].content,
+    { readJson: readCatalog }
+  ) : { verified: false, scope: "persistence_disabled", identity: "" };
   const contextManager = new AgentContextManager(runtime, {
     model,
     calibrationIdentity: calibrationModelIdentity.identity,
-    calibrationDir: calibrationDir && calibrationModelIdentity.verified ? calibrationDir : null
+    calibrationDir: calibrationDir && calibrationModelIdentity.verified ? calibrationDir : null,
+    platformRatio
   });
   try {
     messages = contextManager.fit(messages);
@@ -1314,12 +1791,19 @@ async function runLoop(spec, hooks, env, inputs) {
           executionPreference,
           minPlacementEvidence
         );
+        const recorded = executionReceipts.length;
         response = unwrapChatResponse(await sendJson(url, payload, runtime.request_timeout_seconds), executionReceipts);
+        if (managedEndpoint && executionReceipts.length === recorded) {
+          executionReceipts.push({ model: null, execution: null, reason: "managed_execution_receipt_missing" });
+        }
         break;
       } catch (error) {
         if (!isTransportError(error) || !retryableChatError(error)) throw error;
         lastError = error;
-        if (attempt + 1 < runtime.retry_attempts) await sleep(runtime.retry_backoff_seconds * 1e3);
+        if (attempt + 1 < runtime.retry_attempts) {
+          progress?.({ event: "retry", attempt: attempt + 2, attempts: runtime.retry_attempts });
+          await sleep(runtime.retry_backoff_seconds * 1e3);
+        }
       }
     }
     if (response === null) throw lastError;
@@ -1354,10 +1838,26 @@ async function runLoop(spec, hooks, env, inputs) {
   const observations = hooks.observationStore ? hooks.observationStore(pageSize) : new ObservationStore(pageSize);
   let session;
   try {
-    session = spec.open ? await spec.open(workspace) : void 0;
+    try {
+      session = spec.open ? await spec.open(workspace) : void 0;
+    } catch (error) {
+      if (!isValidationError(error)) throw error;
+      answer = `research adapter could not start: ${error.message}`;
+      writeFailureResult(resultPath, answer);
+      print(answer);
+      return 1;
+    }
+    const root = session?.workspace ?? workspace;
     let parseFailures = 0;
     let exhausted = true;
+    let repeats = 0;
+    let groundingRepaired = false;
+    let sourceRepaired = false;
+    const seenOutputs = [];
     for (let turn = 0; turn < runtime.max_turns; turn += 1) {
+      const at = { turn: turn + 1, maxTurns: runtime.max_turns };
+      phaseAt = at;
+      progress?.({ event: "model", ...at });
       let response;
       try {
         response = await callModel();
@@ -1381,6 +1881,7 @@ async function runLoop(spec, hooks, env, inputs) {
           exhausted = false;
           break;
         }
+        progress?.({ event: "repair", ...at });
         messages.push({ role: "assistant", content: cpSlice(raw, 0, runtime.parse_repair_echo_chars) });
         messages.push({ role: "user", content: PARSE_REPAIR_NOTICE });
         if (!refit()) {
@@ -1393,6 +1894,7 @@ async function runLoop(spec, hooks, env, inputs) {
       if (action.action === "page") {
         const wantStep = Math.trunc(numberOr(action.step, 0));
         const wantPage = Math.trunc(numberOr(action.page, 1));
+        progress?.({ event: "action", ...at, action });
         messages.push({ role: "assistant", content: echo(action) });
         messages.push({ role: "user", content: observations.message(wantStep, wantPage) });
         if (!refit()) {
@@ -1402,45 +1904,83 @@ async function runLoop(spec, hooks, env, inputs) {
         continue;
       }
       if (action.action === "finish") {
-        answer = trimSpace(String(action.answer ?? ""));
+        const proposed = trimSpace(String(action.answer ?? ""));
+        const missing = missingPaths(proposed, root);
+        if (missing.length > 0 && !groundingRepaired) {
+          groundingRepaired = true;
+          progress?.({ event: "repair", ...at });
+          messages.push({ role: "assistant", content: echo(action) });
+          messages.push({ role: "user", content: groundingRepairNotice(missing, evidencePaths(seenOutputs, root)) });
+          if (!refit()) {
+            answer = proposed + groundingNote(missing);
+            exhausted = false;
+            break;
+          }
+          continue;
+        }
+        const evidence = spec.requireSource !== false && missing.length === 0 && !sourceRepaired && pathsIn(proposed).length === 0 ? evidencePaths(seenOutputs, root) : [];
+        if (evidence.length > 0) {
+          sourceRepaired = true;
+          progress?.({ event: "repair", ...at });
+          messages.push({ role: "assistant", content: echo(action) });
+          messages.push({ role: "user", content: sourceRepairNotice(evidence) });
+          if (!refit()) {
+            answer = proposed;
+            exhausted = false;
+            break;
+          }
+          continue;
+        }
+        progress?.({ event: "finish", ...at });
+        answer = missing.length > 0 ? proposed + groundingNote(missing) : proposed;
         exhausted = false;
         break;
       }
       const started = performance.now();
-      const call = session.toolCall(action, workspace, runtime);
+      const call = session.toolCall(action, root, runtime);
       const signature = callSignature(call.signature);
       let observation;
       let status;
+      let exitCode;
       if (seenCalls.has(signature)) {
+        progress?.({ event: "action", ...at, action, repeat: true });
         observation = REPEAT_NOTICE;
         status = "repeat";
+        repeats += 1;
       } else {
+        progress?.({ event: "action", ...at, action });
         try {
           observation = hooks.runTool ? await hooks.runTool(call.record.arguments) : await call.run();
           status = "ok";
         } catch (error) {
           if (!isToolError(error)) throw error;
-          observation = `tool error: ${error.message}`;
-          status = "error";
+          status = error instanceof ToolExitError ? error.status : "error";
+          exitCode = error instanceof ToolExitError ? error.exitCode : void 0;
+          observation = `${status === "empty" ? "tool search" : "tool error"}: ${error.message}${toolErrorHint(error.message)}`;
         }
         seenCalls.set(signature, calls.length + 1);
       }
       calls.push({
         ...call.record,
         status,
+        ...exitCode === void 0 ? {} : { exit_code: exitCode },
         duration_ms: Math.round((performance.now() - started) * 1e3) / 1e3
       });
       messages.push({ role: "assistant", content: echo(action) });
       const remaining = runtime.max_turns - calls.length;
       const step = calls.length;
       observations.put(step, observation, call.ledger(status));
+      seenOutputs.push(observation);
       messages.push({ role: "user", content: observations.message(step) + spec.remaining(remaining) });
       if (!refit()) {
         exhausted = false;
         break;
       }
+      if (repeats >= 2) break;
     }
     if (exhausted) {
+      progress?.({ event: "finalize", maxTurns: runtime.max_turns });
+      phaseAt = { maxTurns: runtime.max_turns };
       messages.push({ role: "user", content: spec.exhausted });
       if (refit()) {
         try {
@@ -1448,6 +1988,8 @@ async function runLoop(spec, hooks, env, inputs) {
           const finalAction = spec.parseAction(content(response));
           if (finalAction.action !== "finish") throw new ValidationError("forced final response was not finish");
           answer = trimSpace(String(finalAction.answer ?? ""));
+          const missing = missingPaths(answer, root);
+          if (missing.length > 0) answer += groundingNote(missing);
         } catch (error) {
           if (!isTransportError(error) && !isValidationError(error)) throw error;
           let diagnostic;
@@ -1457,7 +1999,9 @@ async function runLoop(spec, hooks, env, inputs) {
       }
     }
     if (!answer) answer = failure ?? "agent stopped without a final answer";
+    const report = spec.report ? await spec.report(session) : {};
     const result = {
+      ...report,
       final_answer: answer,
       tool_calls: calls,
       usage,
@@ -1493,6 +2037,16 @@ async function runLoop(spec, hooks, env, inputs) {
     observations.close();
   }
 }
+function withBriefing(prompt, spec, workspace) {
+  try {
+    const briefing = spec.briefing?.(workspace);
+    return briefing ? `${prompt}
+
+${briefing}` : prompt;
+  } catch {
+    return prompt;
+  }
+}
 
 // src/research/proc.ts
 import { spawn, spawnSync } from "node:child_process";
@@ -1542,98 +2096,835 @@ function runProcess(argv, options) {
   });
 }
 
-// src/research/prompts.ts
+// ../rust-core/src/model_catalog.json
+var model_catalog_default = {
+  snapshot: "2026-11-01",
+  measured_on: "Apple M2 Pro, 32 GB, Ollama 0.40.13, with other work running",
+  how_to_read: "quality is measured (run here with known answers), published (the publisher's figure), or untested. memory_gb is what FreeLlama asks to have available, including its reserve; null means not previewed. Discovery never authorizes a pull: ask for one exact tag and its size first.",
+  jobs: [
+    { job: "classify", title: "Classify, triage, yes/no", call: 'run_task {task:"decision"}', cookbook: "cookbooks/classify", picks: [
+      { tag: "strands-decider:2b-nvfp4", role: "default", file_gb: 1.3, memory_gb: 3.8, quality: "measured", evidence: "53/56 in all 3 rounds, 7 ms median; published 182/231 JevBench" },
+      { tag: "nimble-v3:9b-q4_K_M", role: "alternative", file_gb: 5.6, memory_gb: 11.5, quality: "measured", evidence: "51/56 in all 3 rounds, 1.5 s median: no better here despite published 198/231 JevBench" }
+    ] },
+    { job: "find-code", title: "Find the code for an issue", call: 'run_task {task:"embedding", nearest:{query}}', cookbook: "cookbooks/find-code", picks: [
+      { tag: "embeddinggemma-2:740m-q8_0", role: "default", file_gb: 1.3, memory_gb: 1.4, quality: "measured", evidence: "right file first 9/10, top 3 9/10; 899 chunks indexed in 67 s" },
+      { tag: "nomic-embed-text:v1.5", role: "alternative", file_gb: 0.3, memory_gb: 1.4, quality: "measured", evidence: "right file first 6/10, top 3 8/10; faster, 881 chunks in 42 s" }
+    ] },
+    { job: "duplicates", title: "Find duplicates", call: 'run_task {task:"embedding", nearest:{}}', cookbook: "cookbooks/duplicates", picks: [
+      { tag: "nomic-embed-text:v1.5", role: "default", file_gb: 0.3, memory_gb: 1.4, quality: "measured", evidence: "8/12 real issue pairs" }
+    ] },
+    { job: "ocr", title: "Read text from an image", call: 'run_task {task:"vision", files:[path]}', cookbook: "cookbooks/ocr", picks: [
+      { tag: "hf.co/openbmb/MiniCPM-OCR-1.0-gguf:Q4_K_M", role: "default", file_gb: 1.4, memory_gb: 3.8, quality: "measured", evidence: "30/30 in all 3 rounds, 257 ms median, clean rendered text" },
+      { tag: "glm-ocr:latest", role: "alternative", file_gb: 2.2, memory_gb: 5.8, quality: "measured", evidence: "30/30 in all 3 rounds, 1,885 ms median" }
+    ] },
+    { job: "image-recognition", title: "Understand what an image shows", call: 'run_task {task:"vision", files:[path], prompt}', cookbook: "cookbooks/image-recognition", picks: [
+      { tag: "lfm3-vl:2b-q4_K_M", role: "default", file_gb: 1.5, memory_gb: 4.1, quality: "measured", evidence: "20/20 drawn images in all 3 rounds, 299 ms median" },
+      { tag: "lfm3-omni:2b-q4_K_M", role: "alternative", file_gb: 2, memory_gb: 5.5, quality: "measured", evidence: "18/20 in all 3 rounds, 269 ms median; also does audio" },
+      { tag: "bonsai-2:9b", role: "alternative", file_gb: 3.2, memory_gb: 10.3, quality: "measured", evidence: "17/20 in all 3 rounds, 1.4 s median" }
+    ] },
+    { job: "image-search", title: "Find an image by describing it", call: 'run_task {task:"embedding", files:[images], nearest:{query}}', cookbook: "cookbooks/image-search", picks: [
+      { tag: "embeddinggemma-2:740m-q8_0", role: "default", file_gb: 1.3, memory_gb: 1.4, quality: "measured", evidence: "5/5 on five drawn screens" }
+    ] },
+    { job: "speech-to-text", title: "Recording to text", call: 'audio {action:"transcribe", file}', cookbook: "cookbooks/speech-to-text", picks: [
+      { tag: "lfm3-audio:2b-q4_K_M", role: "default", file_gb: 1.7, memory_gb: 5.5, quality: "measured", evidence: "1.7% word error on generated speech, 276 ms median, translation worked" },
+      { tag: "lfm3-omni:2b-q4_K_M", role: "alternative", file_gb: 2, memory_gb: 5.5, quality: "measured", evidence: "1.7% word error, 280 ms median, translation worked, also does images" }
+    ] },
+    { job: "text-to-speech", title: "Text to speech", call: 'audio {action:"speak", text}', cookbook: "cookbooks/text-to-speech", picks: [
+      { tag: "phonon:en", role: "default", file_gb: 0.1, memory_gb: null, quality: "measured", evidence: "0.8-1.7% word error when transcribed back, 102 ms median: about 9x faster" },
+      { tag: "lfm3-audio:2b-q4_K_M", role: "alternative", file_gb: 1.7, memory_gb: 5.5, quality: "measured", evidence: "0% word error, 950 ms median; the judge is an LFM3 model and may favour it" },
+      { tag: "lfm3-omni:2b-q4_K_M", role: "alternative", file_gb: 2, memory_gb: 5.5, quality: "measured", evidence: "0% word error, 950 ms median; same judge caveat" }
+    ] },
+    { job: "coding", title: "Small coding tasks", call: 'run_task {task:"coding", files:[path]}', cookbook: "cookbooks/coding", picks: [
+      { tag: "lfm3:1.7b-q4_K_M", role: "default", file_gb: 1.1, memory_gb: 3.3, quality: "measured", evidence: "21, 20, 20 of 25 small questions, 579 ms median" },
+      { tag: "hf.co/nvidia/NVIDIA-Nemotron-3.5-Bolt-E4B-4GB:Q4_K_M", role: "stronger", file_gb: 6.2, memory_gb: 13.5, quality: "measured", evidence: "23, 22, 23 of 25, 267 ms median" },
+      { tag: "bonsai-2:9b", role: "alternative", file_gb: 3.2, memory_gb: 10.3, quality: "measured", evidence: "19, 19, 17 of 25, 475 ms median" },
+      { tag: "bonsai-2:27b", role: "stronger", file_gb: 8.3, memory_gb: 16.3, quality: "published", evidence: "publisher: SWE-bench Verified 60.8%, LiveCodeBench 90.1%; not measured here, never had 16.3 GB available" }
+    ] },
+    { job: "research-agent", title: "Research a repository", call: 'delegate_research {adapter:"octocode" or "github"}', cookbook: "cookbooks/research-agent", picks: [
+      { tag: "bonsai-2:9b", role: "default", file_gb: 3.2, memory_gb: 10.3, quality: "measured", evidence: "4, 5, 5 of 8 local and 3, 5, 5 of 6 GitHub over 3 rounds, 82 s median per question" },
+      { tag: "hf.co/nvidia/NVIDIA-Nemotron-3.5-Bolt-E4B-4GB:Q4_K_M", role: "stronger", file_gb: 6.2, memory_gb: 13.5, quality: "measured", evidence: "6/8 local and 5/6 GitHub in all 3 rounds, 96 s median per question" },
+      { tag: "lfm3:1.7b-q4_K_M", role: "small", file_gb: 1.1, memory_gb: 3.3, quality: "measured", evidence: "6, 5, 5 of 8 local but 1/6 GitHub, 20 s median per question" }
+    ] }
+  ]
+};
+
+// src/research/octocode-instructions.ts
+var OCTOCODE_LOCAL_INSTRUCTIONS = `Octocode is a read-only code research CLI: it finds code in a directory so you read a few exact lines, not whole files.
+Call: octocode <tool> '{"queries":[{...}]}'  (1-5 queries per call; paths relative to the working directory)
+Result: lines of findings, then "#" notes. Exit 0 found, 1 nothing found, 2 bad input (the message names the field), 3 path not found.
+More: copy a printed {"cursor":"..."} as the whole input. No cursor means the result is complete.
+
+structureSearch: see the layout or list files, when you do not know where to look.
+  {"operation":"tree","path":".","maxDepth":2}
+  {"operation":"files","path":".","include":["**/*.rs"],"view":"paths"}
+localSearch: find a word, name or error text, when you do not know the file.
+  {"path":".","matchString":["memory_holders"],"view":"files"}  which files
+  {"path":".","matchString":["memory_holders","holders"]}  matching lines with line numbers; several words mean any of them
+localFetch: read a file an earlier result named (src/a.rs below is a placeholder); ask for the least that answers.
+  {"path":"src/a.rs","view":"symbols"}  outline with line numbers
+  {"path":"src/a.rs","ranges":[{"startLine":40,"endLine":90}]}
+  {"path":"src/a.rs","matchString":["fn run"],"contextLines":{"before":2,"after":15}}
+astSearch: find code by shape, not by text. Use it to find where something is declared.
+  {"operation":"symbols","path":".","symbolFilter":{"terms":["run"],"mode":"exact"}}  declarations named run
+  {"operation":"match","path":".","rule":{"pattern":"eval($X)"}}  every call of this shape
+lspSearch: who defines, uses or calls a symbol; exact where text search only guesses. Take path and line from an earlier result, never guess them.
+  {"path":"src/a.rs","symbolName":"run","line":35}  its definition
+  {"operation":"references","path":"src/a.rs","symbolName":"run","line":35,"view":"files"}  where it is used
+  {"operation":"callers","path":"src/a.rs","symbolName":"run","line":35}  also callees, hover, documentSymbols
+
+Work smart:
+1. Narrow before reading: list files or matching lines first, then read only those ranges.
+2. Try several words at once: put synonyms in one matchString, or several queries in one call.
+3. Build and dependency folders are skipped already; add "testCode":"exclude" to skip tests.
+4. Nothing found proves little: widen the words or the path before saying something does not exist. If lspSearch is empty, use localSearch.
+5. Answer with file:line evidence, and stop as soon as the question is answered.
+`;
+var OCTOCODE_GITHUB_INSTRUCTIONS = `Octocode's GitHub tools research public and private repositories without cloning them: find a repo, its code, its history, and its packages.
+Call: octocode <tool> '{"queries":[{...}]}'  (1-5 queries per call)
+Result: JSON with results[].data. Exit 0 found, 1 nothing found, 2 bad input (the message names the field), 3 not found, 4 not logged in (octocode auth login), 7 rate limited (wait).
+More: follow a printed next or {"cursor":"..."}; no next and no hasMore means the result is complete.
+
+ghSearchRepo: find a repository when you do not know its owner or name.
+  {"operation":"search","keywords":["local llm router"],"filters":{"language":"Rust"}}
+  {"operation":"get","owner":"ollama","repo":"ollama"}  one repo: description, stars, default branch
+artifactSearch: find a package's repository and versions.
+  {"operation":"resolve","ecosystem":"npm","packageName":"zod"}  also pypi, maven
+ghStructure: see a repo's layout; operation "refs" lists branches, "languages" its languages.
+  {"operation":"tree","owner":"ollama","repo":"ollama","path":"server","maxDepth":2}
+ghSearchCode: find a word or name inside a repo when you do not know the file.
+  {"owner":"ollama","repo":"ollama","keywords":["SystemOneRequest"]}  returns paths, lines and a commitSha
+ghGetFileContent: read a file you found; ask for the least that answers.
+  {"owner":"ollama","repo":"ollama","path":"api/types.go","view":"symbols"}  outline
+  {"owner":"ollama","repo":"ollama","path":"api/types.go","ranges":[{"startLine":600,"endLine":640}]}
+  {"owner":"ollama","repo":"ollama","path":"api/types.go","matchString":["type SystemOneRequest"]}
+ghSearchHistory: find why something changed: pull requests, issues, commits.
+  {"operation":"pullRequest","owner":"ollama","repo":"ollama","keywords":["systemone"]}
+  {"operation":"commit","owner":"ollama","repo":"ollama","keywords":["decision"]}  or operation "issue" with "filters":{"state":"open"}
+ghGetHistoryItem: read one pull request, or issue, you found.
+  {"operation":"pullRequest","owner":"ollama","repo":"ollama","number":18606,"sections":["body","files"]}
+
+Work smart:
+1. Narrow: repo, then search, then read only the ranges you need. Never read whole files first.
+2. Reuse what a result returns: its path, commitSha (as ref) and the next step it suggests.
+3. Search words are exact code words, not sentences: one to three identifiers beat a question.
+4. Nothing found proves little: try another word or check the repo name before saying it does not exist.
+5. Answer with owner/repo, path:line or PR number as evidence, and stop as soon as the question is answered.
+`;
+
+// src/local-prompts.ts
+var catalog = model_catalog_default;
+function picksOf(job) {
+  return catalog.jobs.find((entry) => entry.job === job)?.picks.map((pick) => pick.tag) ?? [];
+}
+var cookbook = (name) => `docs/cookbooks/${name}.md`;
+var SOURCES = {
+  miniCpmOcr: ["https://huggingface.co/openbmb/MiniCPM-OCR-1.0", "https://huggingface.co/openbmb/MiniCPM-OCR-1.0-gguf"],
+  glmOcr: ["https://ollama.com/library/glm-ocr", "https://huggingface.co/zai-org/GLM-OCR"],
+  lfm3Vl: ["https://huggingface.co/LiquidAI/LFM3-VL-2B", "https://huggingface.co/LiquidAI/LFM3-VL-2B-GGUF", "https://ollama.com/library/lfm3-vl"],
+  lfm3Omni: ["https://huggingface.co/LiquidAI/LFM3-Omni-2B", "https://ollama.com/library/lfm3-omni"],
+  embeddingGemma: ["https://huggingface.co/google/embeddinggemma-2", "https://ai.google.dev/gemma/docs/embeddinggemma/inference-embeddinggemma-with-sentence-transformers"],
+  nomic: ["https://huggingface.co/nomic-ai/nomic-embed-text-v1.5"],
+  strandsDecider: ["https://ollama.com/library/strands-decider", "https://raw.githubusercontent.com/strands-labs/strands-decider/main/README.md"],
+  nimble: ["https://ollama.com/library/nimble-v3:latest"],
+  bonsai9b: ["https://huggingface.co/prism-ml/Ternary-Bonsai-2-9B-gguf", "https://ollama.com/library/bonsai-2:9b"],
+  bonsai27b: ["https://huggingface.co/prism-ml/Ternary-Bonsai-2-27B-gguf", "https://ollama.com/library/bonsai-2"],
+  lfm3: ["https://huggingface.co/LiquidAI/LFM3-1.7B", "https://ollama.com/library/lfm3"],
+  nemotronBolt: ["https://huggingface.co/nvidia/NVIDIA-Nemotron-3.5-Bolt-E4B-4GB"],
+  lfm3Audio: ["https://huggingface.co/LiquidAI/LFM3-Audio-2B", "https://ollama.com/library/lfm3-audio"],
+  qwen38: ["https://huggingface.co/Qwen/Qwen3.8-27B", "https://ollama.com/library/qwen3.8"],
+  qwen35: ["https://huggingface.co/Qwen/Qwen3.5-4B", "https://ollama.com/library/qwen3.5"],
+  phonon: ["https://ollama.com/library/phonon:en"]
+};
+var EMBEDDING_PREFIXES = {
+  embeddinggemma: {
+    query: "task: search result | query: ",
+    document: "title: none | text: ",
+    codeQuery: "task: code retrieval | query: ",
+    similarity: "task: sentence similarity | query: ",
+    clustering: "task: clustering | query: ",
+    classification: "task: classification | query: "
+  },
+  // A prefix is required; the card names clustering: for removing semantic duplicates.
+  "nomic-embed-text": { query: "search_query: ", document: "search_document: ", clustering: "clustering: ", classification: "classification: " }
+};
+var GEMMA = EMBEDDING_PREFIXES.embeddinggemma;
+var NOMIC = EMBEDDING_PREFIXES["nomic-embed-text"];
+var OCR_PROMPTS = { text: "Text Recognition:", table: "Table Recognition:", formula: "Formula Recognition:" };
+var OCR_TRAINED = ["minicpm-ocr", "glm-ocr"];
+var OCR_PLAIN = {
+  text: "Transcribe all text in the image exactly, line by line. Output only the text.",
+  table: "Transcribe the table in the image as a Markdown table. Output only the table."
+};
+var ocrPrompt = (kind, model) => {
+  const name = (model ?? "").toLowerCase().replace(/^(?:hf\.co|huggingface\.co)\/[^/]+\//, "");
+  return model === void 0 || OCR_TRAINED.some((family) => name.startsWith(family)) ? OCR_PROMPTS[kind] : OCR_PLAIN[kind];
+};
+var EDIT_FORMAT = `Return each change to an existing file as the file's path (copied from its "--- file:" line), then:
+<<<<<<< SEARCH
+exact current lines (5 to 30, unique in the file, indentation exact)
+=======
+replacement lines
+>>>>>>> REPLACE
+Copy SEARCH lines character for character; prefer several small blocks to one large one. For a new file, or one under 30 lines, give its path on one line and the whole file in one fenced block. If the file was not shown, give the code in one fenced block and say which file and function it belongs in.`;
+var NO_TOOLS = "You have no tools and cannot open files: everything you need is in this message. Answer in plain text.";
+var WORKFLOWS = {
+  "read-text": {
+    job: "ocr",
+    title: "Read all text in an image, exactly",
+    input: "files: the images",
+    prompt: (_request, model) => ocrPrompt("text", model)
+  },
+  "read-table": {
+    job: "ocr",
+    title: "Read a table in an image as Markdown",
+    input: "files: the images",
+    prompt: (_request, model) => ocrPrompt("table", model)
+  },
+  "read-fields": {
+    job: "ocr",
+    title: "Pull named fields from a receipt, invoice or form image as JSON",
+    input: "files: the images; prompt: the field names",
+    prompt: (request) => `Extract these fields from the image: ${request ?? "all labelled fields"}. Format the output as a JSON object with these keys, values exactly as printed; use "###" for a field the image does not show.`
+  },
+  "answer-image": {
+    job: "image-recognition",
+    title: "Answer a question about an image",
+    input: "files: the images; prompt: the question",
+    system: `Answer the question about the image.
+1. Find the part of the image the question is about.
+2. Read any text there exactly as printed.
+3. Answer with just the value or label, or one or two sentences.
+If the image does not show it, answer "not visible". Never guess at what is cut off.`
+  },
+  "describe-screen": {
+    job: "image-recognition",
+    title: "Describe a screenshot for a developer: text, errors, state",
+    input: "files: the screenshot; prompt: what to look for (optional)",
+    system: `You describe a software screenshot for a developer, in short bullets, in this order:
+- the app or page shown;
+- headings and main text, quoted exactly;
+- any error, warning or empty state, quoted exactly;
+- the state of the controls that matter (selected, disabled, filled in);
+- anything that looks broken or misaligned.
+Describe only what is visible.`
+  },
+  "change-code": {
+    job: "coding",
+    title: "Make one small code change",
+    input: "files: the file to change; prompt: the change",
+    system: `${NO_TOOLS}
+You make one small code change.
+1. Find where the change belongs in the code shown.
+2. Follow the file's existing names, style and error handling.
+3. Change as few lines as the task needs; touch nothing else.
+${EDIT_FORMAT}
+Explain nothing unless asked. If the task is a question, answer it in a few lines.`
+  },
+  "fix-bug": {
+    prefer: "capable",
+    job: "coding",
+    title: "Fix a bug with the smallest change",
+    input: "files: the suspect code; prompt: the error message or symptom",
+    system: `${NO_TOOLS}
+You fix one bug with the smallest change.
+1. Read the error or symptom, then the code shown.
+2. Name the cause in one sentence, quoting the line that causes it.
+3. Change only what the fix needs.
+Answer with the cause line, then the edits.
+${EDIT_FORMAT}
+If the code shown cannot cause the symptom, say so and name the file or function to look at instead.`
+  },
+  implement: {
+    prefer: "capable",
+    job: "coding",
+    title: "Add a small feature to existing code",
+    input: "files: the code; prompt: the feature",
+    system: `${NO_TOOLS}
+You add one small feature to the code shown.
+1. Find the function or place it belongs; reuse helpers the file already has.
+2. Follow the file's names, style and error handling.
+3. Handle the empty and error cases the feature can meet.
+${EDIT_FORMAT}
+End with one line: what to test.`
+  },
+  "write-tests": {
+    prefer: "capable",
+    job: "coding",
+    title: "Write unit tests for the code shown",
+    input: "files: the code (and an existing test, for style); prompt: what to cover (optional)",
+    system: `${NO_TOOLS}
+You write unit tests for the code shown; you never change that code.
+1. List the behaviours: the normal case, edge cases (empty, zero, missing, boundary) and one failure case.
+2. Use the test framework and import style the project already uses; copy them from the files shown.
+3. Write one small test per behaviour, named after it, with literal expected values.
+Answer with the test file's path on one line, then the whole file in one fenced block.`
+  },
+  "review-code": {
+    prefer: "capable",
+    job: "coding",
+    title: "Find real defects in code (not style)",
+    input: "files: the code; prompt: what to focus on (optional)",
+    system: `${NO_TOOLS}
+You review the code shown for real defects only: wrong logic, unhandled errors, off-by-one, null or undefined access, leaks, injection, races. Ignore style and naming.
+For each defect write one line: path:line - the problem - the fix.
+Report at most 5, the surest first. If you find none, answer "no defects found". Never invent a line you did not see.`
+  },
+  "explain-code": {
+    job: "coding",
+    title: "Explain code to someone about to change it",
+    input: "files: the code; prompt: what to explain (optional)",
+    system: `${NO_TOOLS}
+Explain the code shown to a developer who is about to change it, in at most 6 bullets:
+what it does (one sentence); its inputs and outputs; side effects (files, network, shared state); what calls it, if visible; the one thing most likely to break when it changes.
+Name functions and variables exactly.`
+  },
+  "summarize-log": {
+    think: false,
+    prefer: "capable",
+    job: "summarize",
+    title: "Summarize a log: errors grouped, counted, first failure",
+    input: "files: the log; prompt: what you are investigating (optional)",
+    system: `${NO_TOOLS}
+You read a log for a developer. Report:
+1. Errors and warnings, grouped by message, each with its count and first and last timestamp.
+2. The first error in time order, quoted exactly.
+3. The likely cause, only if the log shows it.
+Quote messages exactly, skip routine lines, at most 10 bullets.`
+  },
+  "summarize-text": {
+    think: false,
+    job: "summarize",
+    title: "Summarize text for someone who will act on it",
+    input: "files: the text; prompt: what you need from it (optional)",
+    system: `${NO_TOOLS}
+Summarize the text for someone who will act on it, in short bullets: the decisions, the numbers, the deadlines and the open questions, plus whatever the request asks for.
+Quote numbers, names, versions and paths exactly. Write "not stated" when the text does not say; never guess. No introduction or closing.`
+  },
+  "summarize-diff": {
+    think: false,
+    prefer: "capable",
+    job: "summarize",
+    title: "Summarize a diff for a reviewer: changes and risks",
+    input: "files: the diff or patch",
+    system: `${NO_TOOLS}
+You summarize a code diff for a reviewer, in at most 8 bullets:
+one line per file on what changed; any change in behaviour; risks such as a removed check, a changed default, a new dependency or a missing test.
+Name files, functions and settings exactly.`
+  },
+  "extract-json": {
+    think: false,
+    job: "summarize",
+    title: "Extract named fields from text into JSON",
+    input: "files: the text; prompt: the field names (or a JSON schema)",
+    system: `${NO_TOOLS}
+Extract the fields the request names from the text into one JSON object.
+Use the values exactly as written in the text; use null for a field the text does not give; never invent a value.
+Output only the JSON object.`,
+    format: "json"
+  }
+};
+var WORKFLOW_NAMES = Object.keys(WORKFLOWS);
+var BONSAI_9B = {
+  think: false,
+  options: { temperature: 0.7, top_p: 0.8, top_k: 20, min_p: 0, presence_penalty: 1.5, repeat_penalty: 1 },
+  notes: "With think:true use the card's thinking preset (temperature 1.0, top_p 0.95, presence_penalty 1.0) and allow at least 8,192 output tokens; never greedy decoding with thinking on.",
+  sources: SOURCES.bonsai9b
+};
+var qwenNonThinking = (sources) => ({
+  think: false,
+  options: { temperature: 0.7, top_p: 0.8, top_k: 20, min_p: 0, presence_penalty: 1.5, repeat_penalty: 1 },
+  notes: "Thinks by default; with think:true use the card's thinking preset (temperature 1.0, top_p 0.95, top_k 20; Qwen3.8 presence_penalty 0, Qwen3.5 1.5, or 0 with temperature 0.6 for precise coding) and a large output budget (Qwen3.5 32,768 tokens). Raise presence_penalty (up to 2) if it repeats.",
+  sources
+});
+var CHAT_MODELS = {
+  lfm3: {
+    options: { temperature: 0.1, top_k: 50, repeat_penalty: 1.1 },
+    notes: "Thinks by default; its card calls thinking off inconsistent, so it stays on. Not for agentic coding or multi-step reasoning.",
+    sources: SOURCES.lfm3
+  },
+  "nvidia-nemotron-3.5-bolt": {
+    options: { temperature: 1, top_p: 0.95 },
+    // `ollama show` of the hf.co Q4_K_M tag, 2026-11-08: no thinking capability, and the template
+    // defaults enable_thinking to false.
+    notes: "The card says it reasons by default, but its GGUF template turns thinking off and Ollama reports no thinking capability, so it answers directly; think:true is refused.",
+    sources: SOURCES.nemotronBolt
+  },
+  "bonsai-2": BONSAI_9B,
+  // The card documents the same instruct (non-thinking) preset as the 9B; Ollama lists think
+  // values false, low, medium and xhigh for this tag.
+  "bonsai-2:27b": {
+    ...BONSAI_9B,
+    notes: "With think:true (or low, medium, xhigh) use the card's thinking preset (temperature 1.0, top_p 0.95, top_k 20, min_p 0.05, presence_penalty 0) and allow about 16,384 output tokens.",
+    sources: SOURCES.bonsai27b
+  },
+  "qwen3.8": qwenNonThinking(SOURCES.qwen38),
+  "qwen3.5": qwenNonThinking(SOURCES.qwen35)
+};
+var CHAT_SOURCES = [...SOURCES.lfm3, ...SOURCES.nemotronBolt, ...SOURCES.bonsai9b, ...SOURCES.bonsai27b, ...SOURCES.qwen38, ...SOURCES.qwen35];
+var LOCAL_JOBS = {
+  classify: {
+    job: "classify",
+    task: "decision",
+    catalogJob: "classify",
+    defaultPicks: picksOf("classify"),
+    models: {
+      "strands-decider": { notes: "State and questions together must fit 4,096 tokens; weak on long, multi-step documents. Its README: answers at confidence 0.9 or more are right about 95% of the time; confirm the rest.", sources: SOURCES.strandsDecider },
+      "nimble-v3": { notes: "Documents num_ctx 32768 (routing sizes it here); CC BY-NC 4.0, noncommercial.", sources: SOURCES.nimble }
+    },
+    notes: "A decision model reads state and questions, no prompt. Ask short questions about the state, one concern each, and give a choice question an explicit fallback option such as other.",
+    sources: [...SOURCES.strandsDecider, ...SOURCES.nimble, cookbook("classify")]
+  },
+  "find-code": {
+    job: "find-code",
+    task: "embedding",
+    catalogJob: "find-code",
+    defaultPicks: picksOf("find-code"),
+    needs: "nearest.query: the issue, or what the code does",
+    prefixes: { embeddinggemma: { query: GEMMA.codeQuery, document: GEMMA.document }, "nomic-embed-text": { query: NOMIC.query, document: NOMIC.document } },
+    // Measured 2026-11-08 on the find-code set (10 questions, 1,039 chunks): code retrieval with
+    // title: none 8 first / 9 in top 3; search result 8/8; code retrieval with the file as title 7/9.
+    notes: "task: code retrieval (EmbeddingGemma's code-search prefix) measured best here: right file first 8/10, in the top 3 9/10. Read the top ranges before relying on them.",
+    sources: [...SOURCES.embeddingGemma, ...SOURCES.nomic, cookbook("find-code")]
+  },
+  duplicates: {
+    job: "duplicates",
+    task: "embedding",
+    catalogJob: "duplicates",
+    defaultPicks: picksOf("duplicates"),
+    // Symmetric: every item, the query included, takes the same prefix.
+    prefixes: {
+      // The measured 8/12 used search_document:; the card's clustering: is documented but unmeasured here.
+      "nomic-embed-text": { query: NOMIC.document, document: NOMIC.document },
+      embeddinggemma: { query: GEMMA.similarity, document: GEMMA.similarity }
+    },
+    notes: "Uses the measured search_document: (8/12 real issue pairs); nomic's card also documents clustering: for deduplication, unmeasured here. A high score is a candidate, never a verdict.",
+    sources: [...SOURCES.nomic, ...SOURCES.embeddingGemma, cookbook("duplicates")]
+  },
+  ocr: {
+    job: "ocr",
+    task: "vision",
+    catalogJob: "ocr",
+    defaultPicks: picksOf("ocr"),
+    prompt: ({ model }) => ocrPrompt("text", model),
+    // Both publishers' Ollama Modelfiles set temperature 0; the hf.co MiniCPM tag ships no parameters.
+    models: {
+      "minicpm-ocr": {
+        options: { temperature: 0 },
+        notes: "Chinese and English; tables come back as HTML. Its Modelfile sets num_ctx 8192.",
+        sources: [...SOURCES.miniCpmOcr, "https://raw.githubusercontent.com/OpenBMB/MiniCPM-OCR/main/docs/ollama_deploy.md"]
+      },
+      "glm-ocr": {
+        options: { temperature: 0 },
+        notes: "Also documents Figure Recognition:.",
+        sources: [...SOURCES.glmOcr, "https://github.com/zai-org/GLM-OCR/blob/main/examples/ollama-deploy/README.md"]
+      }
+    },
+    notes: "The OCR picks were trained on Text Recognition:, Table Recognition: and Formula Recognition:; a general vision model gets the same request in plain words. Crop to the text first.",
+    sources: [...SOURCES.miniCpmOcr, ...SOURCES.glmOcr, cookbook("ocr")]
+  },
+  "image-recognition": {
+    job: "image-recognition",
+    task: "vision",
+    catalogJob: "image-recognition",
+    defaultPicks: picksOf("image-recognition"),
+    needs: "prompt: your question about the image",
+    systemPrompt: WORKFLOWS["answer-image"].system,
+    models: {
+      "lfm3-vl": {
+        options: { temperature: 0.1, top_p: 1, top_k: 50, min_p: 0, repeat_penalty: 1.1 },
+        notes: "Thinks before it answers by default (Ollama lists think values true and false; off is unmeasured here); images go in at native resolution, so a large one costs many tokens.",
+        sources: SOURCES.lfm3Vl
+      },
+      "lfm3-omni": {
+        systemPrompt: "Answer questions about the provided image. Base every answer only on what can be seen.",
+        options: { temperature: 0 },
+        notes: "Non-reasoning: never send think:true. Up to 2,048 tokens per image. The card gives 32K context; the Ollama tag advertises 128K.",
+        sources: SOURCES.lfm3Omni
+      },
+      "bonsai-2": BONSAI_9B,
+      "qwen3.8": qwenNonThinking(SOURCES.qwen38),
+      "qwen3.5": qwenNonThinking(SOURCES.qwen35)
+    },
+    notes: 'Ask a specific question, not "describe this". Tested on drawn images only.',
+    sources: [...SOURCES.lfm3Vl, ...SOURCES.lfm3Omni, ...SOURCES.bonsai9b, cookbook("image-recognition")]
+  },
+  "image-search": {
+    job: "image-search",
+    task: "embedding",
+    catalogJob: "image-search",
+    defaultPicks: picksOf("image-search"),
+    needs: "nearest.query: a description of the image",
+    prefixes: { embeddinggemma: { query: GEMMA.query, document: GEMMA.document } },
+    notes: "Images are embedded bare: the prefixes apply to text only. Open the top match.",
+    sources: [...SOURCES.embeddingGemma, cookbook("image-search")]
+  },
+  coding: {
+    job: "coding",
+    task: "coding",
+    catalogJob: "coding",
+    defaultPicks: picksOf("coding"),
+    needs: "prompt: the change to make",
+    systemPrompt: WORKFLOWS["change-code"].system,
+    models: CHAT_MODELS,
+    notes: "The answer is SEARCH/REPLACE blocks: apply one only where its SEARCH text matches exactly once, then run the tests.",
+    sources: [...CHAT_SOURCES, cookbook("coding")]
+  },
+  summarize: {
+    job: "summarize",
+    task: "completion",
+    catalogJob: "coding",
+    defaultPicks: picksOf("coding"),
+    prompt: () => "Summarize the text below.",
+    systemPrompt: WORKFLOWS["summarize-text"].system,
+    models: CHAT_MODELS,
+    notes: "The coding picks: the same chat models apply (docs/cookbooks/batch-text.md). Check every number and name you reuse.",
+    sources: [...CHAT_SOURCES, cookbook("batch-text")]
+  }
+};
+var TOOL_JOBS = {
+  "speech-to-text": {
+    tool: "audio",
+    defaultPicks: picksOf("speech-to-text"),
+    // The audio tool calls Ollama's transcription endpoint, which builds the model's prompt; these
+    // are lfm3-audio's documented prompts for a direct chat call.
+    systemPrompts: {
+      transcribe: (language) => language ? `Perform ASR in ${language}.` : "Perform ASR.",
+      translate: (source, target) => `Translate the following speech from ${source} to ${target} in text form.`
+    },
+    notes: "WAV input only. Numbers and names are the usual misses; translation works best to or from English.",
+    sources: [...SOURCES.lfm3Audio, cookbook("speech-to-text")]
+  },
+  "text-to-speech": {
+    tool: "audio",
+    defaultPicks: picksOf("text-to-speech"),
+    notes: "Send plain text: Markdown marks may be read aloud. One voice (default); 24 kHz mono WAV.",
+    sources: [...SOURCES.phonon, cookbook("text-to-speech")]
+  },
+  "research-agent": {
+    tool: "delegate_research",
+    defaultPicks: picksOf("research-agent"),
+    notes: "The adapters' system prompts are below. Discard an escalate verdict and verify the citations.",
+    sources: [cookbook("research-agent")]
+  },
+  sweep: {
+    tool: "sweep",
+    defaultPicks: picksOf("classify"),
+    /** The decision state of one chunk, and the explain step's user message for a confirmed flag. */
+    state: (label, text) => `Source: ${label}
+
+${text}`,
+    explain: (prompt, label, text) => `${prompt}
+
+Source: ${label}
+
+${text}`,
+    // FreeLlama's own setting for the short explain note, not a model's documented value.
+    explainControls: { think: false, temperature: 0 },
+    notes: 'One yes/no question per concern, phrased about one chunk ("Does this code ..."); a noul answer flags at p >= 0.5.',
+    sources: [cookbook("sweep")]
+  }
+};
+var ACTION_PROTOCOL = (example) => `You do not run a shell: ignore the "Call: octocode ..." form, the exit codes and the login hint above. Put "cursor" inside a query to read more of a tool's result; use the page action only for stored output of your own earlier step.
+Return exactly one JSON object per turn, and nothing else:
+Run a tool, in place of the shell command above: {"action":"octocode","tool":"${example}","queries":[{...}]}
+Read another page of an earlier step's stored output: {"action":"page","step":2,"page":2}
+Finish: {"action":"finish","answer":"concise answer with its evidence"}
+You see page 1 of each result and the total; a shortened observation is recoverable with page, so never re-run a tool for it.
+Most questions need 2 to 6 calls. An invalid action is rejected and costs a turn. Never edit or write anything.`;
 function octocodeSystemPrompt(workspace) {
-  return "You are a local code-research agent in a read-only workspace at " + workspace + '. Read or search files only through the `octocode` local tools below. Return exactly one JSON object per turn.\n\nTools (call as {"action":"octocode","tool":"<name>","queries":{...}}):\n\nlocalViewStructure - browse a directory tree, no content loaded; cheapest first orientation step.\n  path (string, required, absolute), maxDepth (int), recursive (bool), filesOnly (bool),\n  directoriesOnly (bool), pattern (glob/substring filter).\n\nlocalFindFiles - find files/dirs by name, glob, regex, or type; returns paths only, not content.\n  path (string, required, absolute), names (array of globs), pathPattern (glob over full path),\n  regex (basename regex), entryType ("f"|"d"), excludeDir (array, e.g. ["node_modules",".git"]).\n\nlocalSearchCode - search file contents for text/regex; returns file+line matches. Your main tool.\n  path (string, required, absolute), keywords (string; literal or regex search term),\n  mode ("paginated"|"discovery"|"detailed"), include/exclude (glob arrays),\n  caseInsensitive (bool), maxFiles (int).\n  Do NOT pass mode "structural" with keywords \u2014 structural (AST) search takes `pattern`/`rule`\n  instead and hard-errors on keywords, costing you a turn for nothing.\n\nlocalGetFileContent - read one file or a line range/matched slice of it.\n  path (string, required, absolute), fullContent (bool; small files only), startLine +\n  endLine (ints, both required together), matchString (anchor text/regex), minify\n  ("none"|"standard"|"symbols" \u2014 "symbols" gives a cheap outline first).\n\nlspGetSemantics - LSP semantic queries: definitions, references, callers/callees, symbol outline.\n  uri (string, required, absolute path), type ("definition"|"references"|"callers"|\n  "callees"|"documentSymbols"|"hover"), symbolName (exact name), lineHint (int from a prior\n  search result \u2014 never guess it).\n  An empty result is ambiguous: indexing or unavailable analysis can produce no symbols.\n  Retry once or use localSearchCode; an empty LSP result alone does not prove absence.\n\nRead another page of an earlier step: {"action":"page","step":2,"page":2}\nFull tool output is stored in pages; you see page 1 and the total. Context fitting can shorten\nan observation in the conversation. Request its stored page to recover the evidence without\nre-running the tool. Claim "not found" only after checking the relevant search scope and pages.\n\nFinish with: {"action":"finish","answer":"concise final answer with repository-relative evidence"}\n\nThese are the complete action schemas. Use only `octocode`, `page`, or `finish`; every shown field\nis required with the shown type, and `tool` must be one of the five names above. An invalid shape\nis rejected and costs one bounded repair turn.\n\nSCOPE YOUR SEARCHES. Pass excludeDir/exclude on every search in a real workspace \u2014\n["node_modules","target",".venv","dist","build",".git","vendor","__pycache__",".octocode"] \u2014 or\nvendored and generated files will bury the answer. For implementation questions, prefer src/,\npackages/*/src/ and lib/ before fixtures, mocks, or examples. If the question targets tests or examples,\ninspect those files. Name the file that supplies the answer. Absence of a match is weak evidence: widen the pattern before concluding\nsomething does not exist.\nFor a production default, find its declaration before relying on test occurrences. Declarations look like\n`default=`, `unwrap_or(`, `const `, `static `, or a settings schema initializer.\nFor a test-specific default or fixture, inspect its test declaration.\n\nAll paths you pass must resolve inside the workspace; relative paths are resolved against the\nworkspace root automatically. Orient cheap (localViewStructure) before reading in\nfull. Be decisive: most tasks need 2-6 tool calls. Never edit or write files \u2014 you only have\nread-only tools. Call finish as soon as the requested facts are established.';
+  return `You are a local code-research agent in a read-only workspace at ${workspace}. Paths are relative to it.
+
+${OCTOCODE_LOCAL_INSTRUCTIONS}
+${ACTION_PROTOCOL("localSearch")}`;
+}
+var GH_ACTION = `You may also run the GitHub CLI, read-only, as {"action":"gh","args":[...]} (arguments as an array; no shell):
+{"action":"gh","args":["search","code","SystemOneRequest","--repo","ollama/ollama"]} finds code; add "--filename","types.go" or "--language","go" to narrow it.
+{"action":"gh","args":["api","repos/ollama/ollama/contents/api/types.go","--jq",".content"]} reads a file (base64), or use ghGetFileContent for decoded text.
+{"action":"gh","args":["repo","view","colinhacks/zod","--json","name,description,primaryLanguage"]}, ["pr","view","18606","--repo","ollama/ollama"], ["issue","list","--repo","owner/repo","--search","keyword"], ["release","list","--repo","owner/repo"].
+Only search, repo view/list, pr view/list/diff/checks, issue view/list, release view/list and api (GET) run. Finish with the direct answer first, then "Source: owner/repo/path" or the PR or issue URL.`;
+var CODER_SYSTEM_PROMPT = [
+  "You change code in an isolated copy of the user's project (the current directory) and test the change. The user's own files are never touched: they review your diff afterwards. Reply with exactly one JSON object per turn and nothing else.",
+  "",
+  "Actions, in order of preference:",
+  '{"action":"search","pattern":"parsePort"} finds text in files and prints path:line:text. Literal and case-sensitive; add "regex":true, "ignoreCase":true, "glob":"*.ts" or "path":"src" to narrow it.',
+  '{"action":"read","path":"src/config.ts","start":40,"end":70} shows numbered lines of one file.',
+  '{"action":"edit","path":"src/config.ts","search":"  const port = 8080;\\n  return port;","replace":"  const port = Number(env.PORT ?? 8080);\\n  return port;"} replaces text that occurs exactly once in the file. Copy "search" from the read output without the line numbers and with its exact indentation: 5 to 30 lines, enough to be unique.',
+  '{"action":"write","path":"src/limits.ts","content":"export const MAX = 10;\\n"} creates a file, or replaces a whole small file.',
+  '{"action":"run","command":"yarn test"} runs one of the allowed commands listed with the task, exactly as written there, and shows its exit code and output.',
+  '{"action":"list","path":"src"} shows files and folders two levels deep.',
+  '{"action":"shell","command":"git diff --stat"} runs one read-only pipeline (rg, grep, find, head, sed -n, wc, git log/diff/show). It cannot change files; edit and write do.',
+  '{"action":"page","step":2,"page":2} shows the next page of a long earlier result.',
+  '{"action":"finish","answer":"Changed src/config.ts to read PORT from the environment, because the port was fixed. Test: yarn test passed."} ends the task.',
+  "",
+  "How to work:",
+  "1. Search for the names in the task, then read the lines you will change.",
+  "2. Edit with a search block copied exactly from the read output. If an edit fails, read those lines again and copy them; never guess.",
+  "3. Run an allowed command to test the change. If it fails, read the error, fix the code and run it again.",
+  "4. Finish with what changed, why, and the last test result. With no allowed command, say the change is untested.",
+  "Keep results small: read line ranges, not whole files, and end long shell output with | head -n 40."
+].join("\n");
+function githubSystemPrompt() {
+  return `You are a code-research agent that answers questions about GitHub repositories and packages, read-only.
+
+${OCTOCODE_GITHUB_INSTRUCTIONS}
+${ACTION_PROTOCOL("ghSearchCode")}
+${GH_ACTION}`;
+}
+var APPLY_EDITS = "Apply the edits yourself: for each block, check that its SEARCH text occurs exactly once in the named file, indentation included; replace it with the REPLACE text; skip a block that matches zero or several times. A path followed by one fenced block is a whole new file. Then run the tests: the edits are a small model's candidates.";
+var AGENT_GUIDE = `Use FreeLlama to run bounded work on local models and keep it out of your context.
+
+Offload when the answer is cheap to check and the work is 10 or more similar items, or an input over about 2,000 tokens you would otherwise read whole. Do it yourself: judgment you must stand behind, edits across files, one short item.
+
+Name a workflow and run_task does the rest: it picks the first catalog model for the job that is installed and fits now and gives it step-by-step instructions for the task. Workflows: read-text, read-table, read-fields (images); answer-image, describe-screen; change-code, fix-bug, implement, write-tests, review-code, explain-code; summarize-log, summarize-text, summarize-diff, extract-json. For labels, code search and duplicates use job classify, find-code or duplicates. Any field you pass wins; job_profile says what was filled in. Name inputs with files; for one answer per file send tasks:[{id, independent:true, task:{files:[path]}}] with job at the top level. For a whole code tree, log or site use sweep; for a question about a repository, delegate_research.
+
+Verify: local answers are candidates. Each run_task result ends with check: lines worked out from it (uncertain answers, close matches, facts not in the source, edits that do not match the file); act on those first, and discard a research result whose verification.recommendation is "escalate".
+
+Coding: the answer is SEARCH/REPLACE blocks. ${APPLY_EDITS}
+
+Hand a result on: saveAs:"<name>" writes the answer to handoffs/<name>.md and returns handoff_file; a later run_task reads it with files:[handoff_file].
+
+Approval: pull a model only after the user approves one exact tag and its size (ollama_pull approvedSizeBytes). Unload only a model you warmed or the user named; delete only a tag the user names. A memory refusal names what holds memory: tell the user and never stop their processes.`;
+
+// src/research/workspace-overview.ts
+import { readdirSync as readdirSync2 } from "node:fs";
+import path6 from "node:path";
+var SKIP = /* @__PURE__ */ new Set(["node_modules", "target", ".git", "dist", "build", ".venv", "venv", "vendor", "__pycache__", ".octocode", "site-packages", "coverage"]);
+var MAX_ENTRIES = 2e4;
+var MAX_DEPTH = 8;
+var SOURCE_DIRS = /* @__PURE__ */ new Set(["src", "lib", "app", "source", "pkg", "cmd", "internal", "crates"]);
+function workspaceOverview(root) {
+  let top;
+  try {
+    top = readdirSync2(root, { withFileTypes: true });
+  } catch {
+    return "";
+  }
+  const extensions = /* @__PURE__ */ new Map();
+  const sourceRoots = /* @__PURE__ */ new Map();
+  let files = 0;
+  let seen = 0;
+  const walk = (dir, depth, sourceRoot) => {
+    if (depth > MAX_DEPTH || seen > MAX_ENTRIES) return;
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (++seen > MAX_ENTRIES) return;
+      if (entry.isDirectory()) {
+        if (SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+        const child = path6.join(dir, entry.name);
+        walk(child, depth + 1, sourceRoot ?? (SOURCE_DIRS.has(entry.name) ? path6.relative(root, child) : void 0));
+      } else if (entry.isFile()) {
+        files += 1;
+        const extension = path6.extname(entry.name).toLowerCase() || "(none)";
+        extensions.set(extension, (extensions.get(extension) ?? 0) + 1);
+        if (sourceRoot) sourceRoots.set(sourceRoot, (sourceRoots.get(sourceRoot) ?? 0) + 1);
+      }
+    }
+  };
+  walk(root, 0);
+  const listing = top.filter((entry) => !SKIP.has(entry.name) && !entry.name.startsWith(".")).sort((left, right) => Number(right.isDirectory()) - Number(left.isDirectory()) || left.name.localeCompare(right.name)).slice(0, 25).map((entry) => entry.isDirectory() ? `${entry.name}/` : entry.name);
+  const types = [...extensions.entries()].sort((left, right) => right[1] - left[1]).slice(0, 8).map(([extension, count]) => `${extension} ${count}`);
+  const sources = [...sourceRoots.entries()].sort((left, right) => right[1] - left[1]).slice(0, 8).map(([dir, count]) => `${dir}/ (${count})`);
+  return `Workspace overview (generated, not a search result): top level: ${listing.join(", ") || "(empty)"}${top.length > 25 ? ", \u2026" : ""}. ${files}${seen > MAX_ENTRIES ? "+" : ""} files; most common types: ${types.join(", ") || "none"}. ` + (sources.length > 0 ? `Source folders: ${sources.join(", ")}. Paths are relative to the workspace root. ` : "") + "Search the file types that exist here, and search contents before concluding something is absent.";
+}
+
+// src/research/gh-action.ts
+var READ_ONLY = {
+  search: /* @__PURE__ */ new Set(["code", "repos", "issues", "prs", "commits"]),
+  repo: /* @__PURE__ */ new Set(["view", "list"]),
+  pr: /* @__PURE__ */ new Set(["view", "list", "diff", "checks"]),
+  issue: /* @__PURE__ */ new Set(["view", "list"]),
+  release: /* @__PURE__ */ new Set(["view", "list"]),
+  api: /* @__PURE__ */ new Set()
+};
+var FORBIDDEN = /^(?:-X|--method|-f|-F|--field|--raw-field|--input|-H|--header|-w|--web|--browser|-e|--edit|--hostname|--paginate-all)(?:=|$)/;
+var MAX_ARGS = 40;
+function validateGhArgs(args) {
+  if (!Array.isArray(args) || args.length === 0 || args.length > MAX_ARGS || !args.every((arg) => typeof arg === "string" && !arg.includes("\n"))) {
+    throw new ValidationError(`gh action requires "args": an array of 1-${MAX_ARGS} strings, e.g. ["search","code","SystemOneRequest","--repo","ollama/ollama"]`);
+  }
+  const words = args;
+  const [group, sub] = words;
+  const allowed = READ_ONLY[group];
+  if (!allowed) throw new ValidationError(`gh ${group} is not allowed; read-only commands: search, repo view/list, pr view/list/diff/checks, issue view/list, release view/list, api (GET)`);
+  if (allowed.size > 0 && !allowed.has(sub ?? "")) {
+    throw new ValidationError(`gh ${group} ${sub ?? ""} is not read-only; allowed: ${[...allowed].map((name) => `gh ${group} ${name}`).join(", ")}`);
+  }
+  const bad = words.find((word) => FORBIDDEN.test(word));
+  if (bad) throw new ValidationError(`gh flag ${bad} is not allowed: the gh action only reads`);
+  if (group === "api" && (!sub || sub.startsWith("-") || /graphql/i.test(sub))) {
+    throw new ValidationError("gh api needs a REST path such as repos/ollama/ollama/contents/api/types.go (GET only; no graphql)");
+  }
+  return words;
+}
+async function runGh(args, cwd, timeoutSeconds) {
+  const result = await runProcess(["gh", ...validateGhArgs(args)], {
+    cwd,
+    // gh reads its login from the operator's config and keychain; nothing prompts.
+    env: { ...process.env, GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", NO_COLOR: "1", GH_PAGER: "cat" },
+    timeoutSeconds
+  });
+  const output = trimSpace(result.stdout);
+  if (result.returncode !== 0) throw new ToolExitError(result.returncode, `${output}
+${trimSpace(result.stderr)}`.trim());
+  return output || "(no results)";
+}
+
+// src/research/entry.ts
+import path7 from "node:path";
+import { pathToFileURL } from "node:url";
+function isEntry(moduleUrl, name, script = process.argv[1]) {
+  if (!script || moduleUrl !== pathToFileURL(script).href) return false;
+  return path7.basename(script).replace(/\.[cm]?[jt]s$/, "") === name;
 }
 
 // src/research/octocode-agent.ts
 var OCTOCODE_TOOLS = /* @__PURE__ */ new Set([
-  "localViewStructure",
-  "localFindFiles",
-  "localSearchCode",
-  "localGetFileContent",
-  "lspGetSemantics"
+  "structureSearch",
+  "localSearch",
+  "localFetch",
+  "astSearch",
+  "lspSearch"
 ]);
-var PATH_KEYS = ["path", "uri"];
-var OCTOCODE_PACKAGE = process.env.FREELLAMA_AGENT_OCTOCODE_PACKAGE ?? "octocode@19.1.0";
-var SORTED_TOOLS = [...OCTOCODE_TOOLS].sort().join(", ");
+var GITHUB_TOOLS = /* @__PURE__ */ new Set([
+  "ghSearchRepo",
+  "artifactSearch",
+  "ghStructure",
+  "ghSearchCode",
+  "ghGetFileContent",
+  "ghSearchHistory",
+  "ghGetHistoryItem"
+]);
+var MAX_QUERIES = 5;
+var OCTOCODE_BIN = process.env.FREELLAMA_AGENT_OCTOCODE_BIN ?? "octocode";
 function safeResolve(root, value) {
   const candidate = resolvePath(joinPath(root, value));
   if (escapesRoot(candidate, root)) throw new ValidationError(`path escapes benchmark workspace: ${value}`);
   if (candidate.split("/").includes(".git")) throw new ValidationError("git metadata is outside the task surface");
   return candidate;
 }
-function parseAction(content) {
-  const value = parseJsonAction(content);
-  const action = value.action;
-  if (action === "octocode") {
-    const tool = value.tool;
-    if (typeof tool !== "string" || !OCTOCODE_TOOLS.has(tool)) {
-      throw new ValidationError(`octocode action requires one supported tool: ${SORTED_TOOLS}`);
+function queryList(queries) {
+  if (isRecord(queries)) return [queries];
+  return Array.isArray(queries) ? queries.filter(isRecord) : [];
+}
+function normalizeAction(value, tools) {
+  const named = typeof value.action === "string" && tools.has(value.action) ? value.action : void 0;
+  if (named === void 0 && value.action !== "octocode") return value;
+  const { action: _action, tool: named2, queries, ...fields } = value;
+  const tool = named ?? named2;
+  if (tool === void 0) return value;
+  const query = queries ?? (Object.keys(fields).length > 0 ? fields : void 0);
+  return { action: "octocode", tool, ...query === void 0 ? {} : { queries: query } };
+}
+function actionParser(tools, gh = false) {
+  const names = [...tools].sort().join(", ");
+  return (content) => {
+    const value = normalizeAction(parseJsonAction(content), tools);
+    const action = value.action;
+    if (gh && action === "gh") {
+      validateGhArgs(value.args);
+      return value;
     }
-    if (!isRecord(value.queries)) throw new ValidationError("octocode action requires a queries object");
-  }
-  if (action === "page" && (!isPositiveInt(value.step) || !isPositiveInt(value.page))) {
-    throw new ValidationError("page action requires positive integer step and page");
-  }
-  if (action === "finish" && typeof value.answer !== "string") {
-    throw new ValidationError("finish action requires a string answer");
-  }
-  if (action !== "octocode" && action !== "page" && action !== "finish") {
-    throw new ValidationError(`unsupported action for octocode adapter: ${String(action)}`);
+    if (action === "octocode") {
+      const tool = value.tool;
+      if (typeof tool !== "string" || !tools.has(tool)) {
+        throw new ValidationError(`octocode action requires one supported tool: ${names}`);
+      }
+      const queries = queryList(value.queries);
+      if (queries.length === 0 || queries.length > MAX_QUERIES) {
+        throw new ValidationError(`octocode action requires queries: 1 to ${MAX_QUERIES} query objects`);
+      }
+    }
+    if (action === "page" && (!isPositiveInt(value.step) || !isPositiveInt(value.page))) {
+      throw new ValidationError("page action requires positive integer step and page");
+    }
+    if (action === "finish" && typeof value.answer !== "string") {
+      throw new ValidationError("finish action requires a string answer");
+    }
+    if (action !== "octocode" && action !== "page" && action !== "finish") {
+      throw new ValidationError(`unsupported action for octocode adapter: ${String(action)}${gh ? " (use octocode, gh, page or finish)" : ""}`);
+    }
+    return value;
+  };
+}
+var parseAction = actionParser(OCTOCODE_TOOLS);
+async function runCli(root, tool, queries, timeoutSeconds) {
+  const result = await runProcess([OCTOCODE_BIN, tool, JSON.stringify({ queries })], { cwd: root, timeoutSeconds });
+  const parts = [trimSpace(result.stdout), trimSpace(result.stderr)].filter(Boolean);
+  const output = parts.join("\n") || "(empty result)";
+  if (result.returncode !== 0) {
+    throw new ToolExitError(result.returncode, output, result.returncode === 1 ? "empty" : "error");
   }
-  return value;
+  return output;
 }
 async function runOctocode(root, toolName, queries, timeoutSeconds) {
   if (!OCTOCODE_TOOLS.has(toolName)) throw new ValidationError(`unsupported octocode tool: ${toolName}`);
-  const resolved = { ...queries };
-  for (const key of PATH_KEYS) {
-    const value = resolved[key];
-    if (typeof value === "string") resolved[key] = safeResolve(root, value);
-  }
-  const command = ["npx", "--yes", OCTOCODE_PACKAGE, "tools", toolName, "--queries", JSON.stringify(resolved), "--compact"];
-  const result = await runProcess(command, { cwd: root, timeoutSeconds });
-  let output = result.stdout + (result.returncode !== 0 ? `
-STDERR:
-${result.stderr}` : "");
-  if (!trimSpace(output)) output = "(empty result)";
-  return output;
+  const list = queryList(queries);
+  for (const query of list) {
+    if (typeof query.path === "string") safeResolve(root, query.path);
+  }
+  return runCli(root, toolName, list, timeoutSeconds);
 }
-var OCTOCODE_ADAPTER = {
-  defaultToolTimeoutSeconds: 45,
-  systemPrompt: (workspace) => octocodeSystemPrompt(workspace),
-  parseAction,
-  open: () => ({
-    toolCall: (action, workspace, runtime) => {
-      const toolName = String(action.tool ?? "");
-      const queries = isRecord(action.queries) ? action.queries : {};
-      return {
-        signature: { tool: toolName, queries },
-        run: () => runOctocode(workspace, toolName, queries, runtime.tool_timeout_seconds),
-        record: {
-          name: toolName ? `mcp.octocode.${toolName}` : "mcp.octocode.unknown",
-          raw_name: action.action ?? "",
-          arguments: { tool: toolName, queries }
-        },
-        ledger: (status) => ({ action: toolName, status, source: canonicalJson(queries, { sortKeys: false, ensureAscii: false }) })
-      };
-    }
-  }),
-  remaining: (count) => `
+async function runGithub(root, toolName, queries, timeoutSeconds) {
+  if (!GITHUB_TOOLS.has(toolName)) throw new ValidationError(`unsupported GitHub tool: ${toolName}`);
+  return runCli(root, toolName, queryList(queries), timeoutSeconds);
+}
+function adapterFor(options) {
+  return {
+    defaultToolTimeoutSeconds: 45,
+    systemPrompt: options.prompt,
+    ...options.briefing ? { briefing: options.briefing } : {},
+    parseAction: actionParser(options.tools, options.gh),
+    open: () => ({
+      toolCall: (action, workspace, runtime) => {
+        if (options.gh && action.action === "gh") {
+          const args = validateGhArgs(action.args);
+          return {
+            signature: { gh: args },
+            run: () => runGh(args, workspace, runtime.tool_timeout_seconds),
+            record: { name: "gh", raw_name: "gh", arguments: { args } },
+            ledger: (status) => ({ action: "gh", status, source: args.join(" ") })
+          };
+        }
+        const toolName = String(action.tool ?? "");
+        const queries = queryList(action.queries);
+        return {
+          signature: { tool: toolName, queries },
+          run: () => options.run(workspace, toolName, queries, runtime.tool_timeout_seconds),
+          record: {
+            name: toolName ? `mcp.octocode.${toolName}` : "mcp.octocode.unknown",
+            raw_name: action.action ?? "",
+            arguments: { tool: toolName, queries }
+          },
+          ledger: (status) => ({ action: toolName, status, source: canonicalJson(queries, { sortKeys: false, ensureAscii: false }) })
+        };
+      }
+    }),
+    remaining: (count) => `
 
 Tool calls remaining: ${count}. Finish now if the task is answerable; do not repeat prior calls.`,
-  exhausted: "Tool budget is exhausted. Return exactly a finish JSON action now using the evidence collected. Do not request another tool.",
-  adapterMetadata: () => ({ adapter: "octocode_cli_agent_v1" })
-};
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    exhausted: "Tool budget is exhausted. Return exactly a finish JSON action now using the evidence collected. Do not request another tool.",
+    adapterMetadata: () => ({ adapter: options.metadata })
+  };
+}
+var OCTOCODE_ADAPTER = adapterFor({ tools: OCTOCODE_TOOLS, prompt: octocodeSystemPrompt, run: runOctocode, metadata: "octocode_cli_agent_v2", briefing: workspaceOverview });
+var GITHUB_ADAPTER = adapterFor({ tools: GITHUB_TOOLS, prompt: githubSystemPrompt, run: runGithub, metadata: "octocode_github_agent_v2", gh: true });
+if (isEntry(import.meta.url, "octocode-agent")) {
   process.exitCode = await runAdapter(OCTOCODE_ADAPTER);
 }
 export {
+  GITHUB_ADAPTER,
+  GITHUB_TOOLS,
   OCTOCODE_ADAPTER,
-  OCTOCODE_PACKAGE,
+  OCTOCODE_BIN,
   OCTOCODE_TOOLS,
   parseAction,
+  queryList,
+  runGithub,
   runOctocode,
   safeResolve
 };