@octocodeai/freellama-mcp-server 0.5.0 → 0.6.1

package/dist/research/bash-agent.js

@@ -0,0 +1,2435 @@
+// src/research/bash-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 { performance } from "node:perf_hooks";
+import { setTimeout as sleep } from "node:timers/promises";
+
+// src/research/canonical-json.ts
+function canonicalJson(value, options = {}) {
+  const { sortKeys = true, ensureAscii = true, separators: [item, colon] = [", ", ": "], floatKeys } = options;
+  const quote = (text) => {
+    const json = JSON.stringify(text);
+    return ensureAscii ? json.replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`) : json;
+  };
+  const render = (node, float) => {
+    if (node === null) return "null";
+    if (typeof node === "string") return quote(node);
+    if (typeof node === "boolean") return String(node);
+    if (typeof node === "number") return numberText(node, float);
+    if (Array.isArray(node)) return `[${node.map((entry) => render(entry, false)).join(item)}]`;
+    if (typeof node === "object") {
+      const record = node;
+      const keys = Object.keys(record).filter((key) => record[key] !== void 0);
+      if (sortKeys) keys.sort();
+      return `{${keys.map((key) => `${quote(key)}${colon}${render(record[key], floatKeys?.has(key) ?? false)}`).join(item)}}`;
+    }
+    throw new TypeError(`cannot serialize a ${typeof node} as JSON`);
+  };
+  return render(value, false);
+}
+function numberText(value, float) {
+  if (!Number.isFinite(value)) throw new RangeError(`cannot serialize ${value} as JSON`);
+  if (Number.isInteger(value) && !float) return Math.abs(value) < 1e21 ? String(value) : BigInt(value).toString();
+  const [mantissa, power] = value.toExponential().split("e");
+  const exponent = Number(power);
+  if (value !== 0 && (exponent < -4 || exponent >= 16)) {
+    return `${mantissa}e${exponent < 0 ? "-" : "+"}${String(Math.abs(exponent)).padStart(2, "0")}`;
+  }
+  const text = String(value);
+  return Number.isInteger(value) ? `${text}.0` : text;
+}
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// src/research/errors.ts
+var ValidationError = class extends Error {
+  name = "ValidationError";
+};
+function isSystemError(error) {
+  return error instanceof Error && typeof error.errno === "number";
+}
+var ToolTimeoutError = class extends Error {
+  name = "ToolTimeoutError";
+};
+function isToolError(error) {
+  return error instanceof ValidationError || error instanceof ToolTimeoutError || error instanceof SyntaxError || isSystemError(error);
+}
+
+// src/research/actions.ts
+function objectAt(text, start) {
+  let depth = 0;
+  let inString = false;
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (char === "\\") index += 1;
+      else if (char === '"') inString = false;
+    } else if (char === '"') {
+      inString = true;
+    } else if (char === "{" || char === "[") {
+      depth += 1;
+    } else if (char === "}" || char === "]") {
+      depth -= 1;
+      if (depth === 0) return JSON.parse(text.slice(start, index + 1));
+    }
+  }
+  throw new SyntaxError("unterminated JSON object");
+}
+function parseJsonAction(content) {
+  let text = content.trim();
+  if (text.startsWith("```")) text = text.split(/\r\n|\r|\n/).slice(1, -1).join("\n").trim();
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    const start = text.indexOf("{");
+    if (start < 0) throw new ValidationError("model did not return a JSON action");
+    try {
+      value = objectAt(text, start);
+    } catch (inner) {
+      if (!(inner instanceof SyntaxError)) throw inner;
+      throw new ValidationError("model did not return a valid JSON action");
+    }
+  }
+  if (!isRecord(value) || typeof value.action !== "string") throw new ValidationError("model action must be a JSON object with an action");
+  return value;
+}
+function callSignature(payload) {
+  return canonicalJson(payload, { ensureAscii: false });
+}
+var REPEAT_NOTICE = "(identical call already made this run \u2014 its result is above and was not re-executed. Use a different call, or finish now with the evidence already collected.)";
+var PARSE_REPAIR_NOTICE = "Your last reply was not a valid JSON action, so it was discarded. Reply with EXACTLY one JSON object and nothing else \u2014 no prose before or after, no markdown fence. Use the action shapes given in your instructions. If you already have enough evidence, send the finish action now.";
+
+// src/research/context-manager.ts
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+// src/research/context-policy.ts
+var CHARS_PER_TOKEN = 4;
+var SAFETY_MARGIN_TOKENS = 256;
+var IMAGE_TOKEN_ESTIMATE = 1024;
+var DEFAULT_KEEP_RECENT = 2;
+var COMPACT_PREVIEW_CHARS = 180;
+var COMPACT_RETAIN_RATIO = 0.8;
+var CLIP_HEAD_RATIO = 2 / 3;
+var OBSERVATION_PAGE_CHARS = 3e3;
+var COMPACTION_TARGET_RATIO = 0.9;
+var MAX_PARSE_REPAIRS = 2;
+var INTEGER = /^[+-]?[0-9]+$/;
+var DECIMAL = /^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/;
+function envInt(env, name, defaultValue, minimum = 0) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  if (!INTEGER.test(raw.trim())) throw new ValidationError(`${name} must be an integer, got ${JSON.stringify(raw)}`);
+  const value = Number(raw.trim());
+  if (value < minimum) throw new ValidationError(`${name} must be >= ${minimum}, got ${value}`);
+  return value;
+}
+function envFloat(env, name, defaultValue, minimum = 0) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  const value = Number(raw.trim());
+  if (!DECIMAL.test(raw.trim())) throw new ValidationError(`${name} must be a number, got ${JSON.stringify(raw)}`);
+  if (!Number.isFinite(value) || value < minimum) {
+    throw new ValidationError(`${name} must be finite and >= ${minimum}, got ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+function envBool(env, name, defaultValue) {
+  const raw = env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  const normalized = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new ValidationError(`${name} must be true/false, got ${JSON.stringify(raw)}`);
+}
+function contextBudget(numCtx, numPredict, safetyMarginTokens = SAFETY_MARGIN_TOKENS) {
+  return Math.max(numCtx - numPredict - safetyMarginTokens, 0);
+}
+var ContextPolicy = class _ContextPolicy {
+  fields;
+  /**
+   * Fields configured from the environment. They are floats, so canonical JSON (calibration keys)
+   * renders them as floats: `FREELLAMA_AGENT_CHARS_PER_TOKEN=8` gives `8.0`, the default gives `4`.
+   */
+  floatKeys;
+  constructor(fields = {}, floatKeys = []) {
+    this.fields = {
+      chars_per_token: fields.chars_per_token ?? CHARS_PER_TOKEN,
+      safety_margin_tokens: fields.safety_margin_tokens ?? SAFETY_MARGIN_TOKENS,
+      image_token_estimate: fields.image_token_estimate ?? IMAGE_TOKEN_ESTIMATE,
+      keep_recent: fields.keep_recent ?? DEFAULT_KEEP_RECENT,
+      compact_preview_chars: fields.compact_preview_chars ?? COMPACT_PREVIEW_CHARS,
+      compact_retain_ratio: fields.compact_retain_ratio ?? COMPACT_RETAIN_RATIO,
+      clip_head_ratio: fields.clip_head_ratio ?? CLIP_HEAD_RATIO,
+      observation_page_chars: fields.observation_page_chars ?? OBSERVATION_PAGE_CHARS,
+      pinned_overflow: fields.pinned_overflow ?? "error"
+    };
+    this.floatKeys = new Set(floatKeys);
+    const f = this.fields;
+    if (!Number.isFinite(f.chars_per_token) || f.chars_per_token <= 0) throw new ValidationError("chars_per_token must be finite and > 0");
+    if (f.safety_margin_tokens < 0 || f.image_token_estimate < 0 || f.keep_recent < 0) {
+      throw new ValidationError("context token estimates and keep_recent must be >= 0");
+    }
+    if (f.compact_preview_chars <= 0 || f.observation_page_chars <= 0) throw new ValidationError("preview and page sizes must be > 0");
+    if (!(f.compact_retain_ratio > 0 && f.compact_retain_ratio < 1)) throw new ValidationError("compact_retain_ratio must be between 0 and 1");
+    if (!(f.clip_head_ratio > 0 && f.clip_head_ratio < 1)) throw new ValidationError("clip_head_ratio must be between 0 and 1");
+    if (f.pinned_overflow !== "error" && f.pinned_overflow !== "clip") throw new ValidationError("pinned_overflow must be 'error' or 'clip'");
+  }
+  get chars_per_token() {
+    return this.fields.chars_per_token;
+  }
+  get safety_margin_tokens() {
+    return this.fields.safety_margin_tokens;
+  }
+  get image_token_estimate() {
+    return this.fields.image_token_estimate;
+  }
+  get keep_recent() {
+    return this.fields.keep_recent;
+  }
+  get compact_preview_chars() {
+    return this.fields.compact_preview_chars;
+  }
+  get compact_retain_ratio() {
+    return this.fields.compact_retain_ratio;
+  }
+  get clip_head_ratio() {
+    return this.fields.clip_head_ratio;
+  }
+  get observation_page_chars() {
+    return this.fields.observation_page_chars;
+  }
+  get pinned_overflow() {
+    return this.fields.pinned_overflow;
+  }
+  static fromEnv(env = process.env) {
+    const floats = [
+      ["chars_per_token", "FREELLAMA_AGENT_CHARS_PER_TOKEN"],
+      ["compact_retain_ratio", "FREELLAMA_AGENT_COMPACT_RETAIN_RATIO"],
+      ["clip_head_ratio", "FREELLAMA_AGENT_CLIP_HEAD_RATIO"]
+    ];
+    return new _ContextPolicy({
+      chars_per_token: envFloat(env, "FREELLAMA_AGENT_CHARS_PER_TOKEN", CHARS_PER_TOKEN, 1e-6),
+      safety_margin_tokens: envInt(env, "FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS", SAFETY_MARGIN_TOKENS),
+      image_token_estimate: envInt(env, "FREELLAMA_AGENT_IMAGE_TOKEN_ESTIMATE", IMAGE_TOKEN_ESTIMATE),
+      keep_recent: envInt(env, "FREELLAMA_AGENT_KEEP_RECENT", DEFAULT_KEEP_RECENT),
+      compact_preview_chars: envInt(env, "FREELLAMA_AGENT_COMPACT_PREVIEW_CHARS", COMPACT_PREVIEW_CHARS, 1),
+      compact_retain_ratio: envFloat(env, "FREELLAMA_AGENT_COMPACT_RETAIN_RATIO", COMPACT_RETAIN_RATIO, 1e-6),
+      clip_head_ratio: envFloat(env, "FREELLAMA_AGENT_CLIP_HEAD_RATIO", CLIP_HEAD_RATIO, 1e-6),
+      observation_page_chars: envInt(env, "FREELLAMA_AGENT_OBSERVATION_PAGE_CHARS", OBSERVATION_PAGE_CHARS, 1),
+      pinned_overflow: (env.FREELLAMA_AGENT_PINNED_OVERFLOW ?? "error").trim().toLowerCase()
+    }, floats.filter(([, name]) => env[name] !== void 0 && env[name] !== "").map(([key]) => key));
+  }
+  metadata() {
+    return { ...this.fields };
+  }
+};
+var AgentRuntimeConfig = class _AgentRuntimeConfig {
+  constructor(fields) {
+    this.fields = fields;
+  }
+  fields;
+  get max_turns() {
+    return this.fields.max_turns;
+  }
+  get num_ctx() {
+    return this.fields.num_ctx;
+  }
+  get num_predict() {
+    return this.fields.num_predict;
+  }
+  get temperature() {
+    return this.fields.temperature;
+  }
+  get seed() {
+    return this.fields.seed;
+  }
+  get request_timeout_seconds() {
+    return this.fields.request_timeout_seconds;
+  }
+  get retry_attempts() {
+    return this.fields.retry_attempts;
+  }
+  get retry_backoff_seconds() {
+    return this.fields.retry_backoff_seconds;
+  }
+  get tool_timeout_seconds() {
+    return this.fields.tool_timeout_seconds;
+  }
+  get keep_alive() {
+    return this.fields.keep_alive;
+  }
+  get think() {
+    return this.fields.think;
+  }
+  get max_parse_repairs() {
+    return this.fields.max_parse_repairs;
+  }
+  get parse_repair_echo_chars() {
+    return this.fields.parse_repair_echo_chars;
+  }
+  get context() {
+    return this.fields.context;
+  }
+  static fromEnv(options) {
+    const env = options.env ?? process.env;
+    const context = ContextPolicy.fromEnv(env);
+    const config = new _AgentRuntimeConfig({
+      max_turns: envInt(env, "FREELLAMA_AGENT_MAX_TURNS", 10, 1),
+      num_ctx: envInt(env, "FREELLAMA_AGENT_NUM_CTX", 8192, 1),
+      num_predict: envInt(env, "FREELLAMA_AGENT_NUM_PREDICT", 512, 1),
+      temperature: envFloat(env, "FREELLAMA_AGENT_TEMPERATURE", 0),
+      seed: envInt(env, "FREELLAMA_AGENT_SEED", 42),
+      request_timeout_seconds: envFloat(env, "FREELLAMA_AGENT_REQUEST_TIMEOUT_SECONDS", 600, 1e-3),
+      retry_attempts: envInt(env, "FREELLAMA_AGENT_RETRY_ATTEMPTS", 2, 1),
+      retry_backoff_seconds: envFloat(env, "FREELLAMA_AGENT_RETRY_BACKOFF_SECONDS", 5),
+      tool_timeout_seconds: envFloat(env, "FREELLAMA_AGENT_TOOL_TIMEOUT_SECONDS", options.defaultToolTimeoutSeconds, 1e-3),
+      keep_alive: (env.FREELLAMA_AGENT_KEEP_ALIVE ?? "5m").trim(),
+      think: envBool(env, "FREELLAMA_AGENT_THINK", false),
+      max_parse_repairs: envInt(env, "FREELLAMA_AGENT_MAX_PARSE_REPAIRS", MAX_PARSE_REPAIRS, 0),
+      parse_repair_echo_chars: envInt(env, "FREELLAMA_AGENT_PARSE_REPAIR_ECHO_CHARS", 500, 1),
+      context
+    });
+    if (contextBudget(config.num_ctx, config.num_predict, context.safety_margin_tokens) <= 0) {
+      throw new ValidationError("FREELLAMA_AGENT_NUM_CTX must exceed FREELLAMA_AGENT_NUM_PREDICT plus FREELLAMA_AGENT_SAFETY_MARGIN_TOKENS");
+    }
+    if (!config.keep_alive) throw new ValidationError("FREELLAMA_AGENT_KEEP_ALIVE must not be empty");
+    return config;
+  }
+  metadata() {
+    const { context: _context, ...rest } = this.fields;
+    return { ...rest };
+  }
+};
+
+// src/research/text.ts
+var SPACE_CLASS = "\\p{White_Space}\\x1c-\\x1f";
+var SPACE = new RegExp(`^[${SPACE_CLASS}]$`, "u");
+var EDGE_SPACE = new RegExp(`^[${SPACE_CLASS}]+|[${SPACE_CLASS}]+$`, "gu");
+var isSpace = (char) => char !== void 0 && SPACE.test(char);
+var trimSpace = (text) => text.replace(EDGE_SPACE, "");
+var ASTRAL = /[\uD800-\uDBFF][\uDC00-\uDFFF]/;
+function cpLength(text) {
+  if (!ASTRAL.test(text)) return text.length;
+  let count = 0;
+  for (const _ of text) count += 1;
+  return count;
+}
+function cpAdvance(text, start, count) {
+  let index = start;
+  for (let step = 0; step < count && index < text.length; step += 1) {
+    const code = text.charCodeAt(index);
+    const pair = code >= 55296 && code <= 56319 && index + 1 < text.length && text.charCodeAt(index + 1) >= 56320 && text.charCodeAt(index + 1) <= 57343;
+    index += pair ? 2 : 1;
+  }
+  return index;
+}
+function cpSlice(text, start, end) {
+  if (!ASTRAL.test(text)) return text.slice(start, end);
+  const from = cpAdvance(text, 0, start);
+  if (end === void 0) return text.slice(from);
+  if (end <= start) return "";
+  return text.slice(from, cpAdvance(text, from, end - start));
+}
+function cpTail(text, count) {
+  const length = cpLength(text);
+  return count >= length ? text : cpSlice(text, length - count);
+}
+var UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function decodeUtf8(bytes, source) {
+  try {
+    return UTF8.decode(bytes);
+  } catch {
+    throw new ValidationError(`${source} is not valid UTF-8`);
+  }
+}
+function normalizeNewlines(text) {
+  return text.replace(/\r\n?/g, "\n");
+}
+
+// src/research/fit.ts
+var COMPACT_MARKER = "[earlier observation compacted to save context";
+var estimateText = (value) => canonicalJson(value, { sortKeys: false, ensureAscii: false });
+function estimateTokens(text, charsPerToken = CHARS_PER_TOKEN) {
+  return Math.floor(cpLength(text) / charsPerToken) + 1;
+}
+function messagesTokens(messages, policy = new ContextPolicy()) {
+  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);
+    if (Array.isArray(images)) total += images.length * policy.image_token_estimate;
+    total += estimateTokens(estimateText(metadata), policy.chars_per_token);
+  }
+  return total;
+}
+var ContextBudgeter = class {
+  policy;
+  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);
+  }
+  estimate = (messages) => Math.ceil(messagesTokens(messages, this.policy) * this.scale);
+  observe(messages, promptEvalCount) {
+    if (typeof promptEvalCount !== "number" || !Number.isFinite(promptEvalCount)) return false;
+    const actual = Math.trunc(promptEvalCount);
+    if (actual <= 0) return false;
+    const baseline = Math.max(messagesTokens(messages, this.policy), 1);
+    const previous = this.scale;
+    this.scale = Math.max(this.scale, actual / baseline);
+    this.calibration_samples += 1;
+    return this.scale > previous;
+  }
+  metadata() {
+    return {
+      token_counting: this.calibration_samples ? "model_calibrated_estimate" : "configured_estimate",
+      estimate_scale: Math.round(this.scale * 1e6) / 1e6,
+      calibration_samples: this.calibration_samples
+    };
+  }
+};
+function clip(text, limit, headRatio = CLIP_HEAD_RATIO) {
+  if (!(headRatio > 0 && headRatio < 1)) throw new ValidationError("head_ratio must be between 0 and 1");
+  const length = cpLength(text);
+  if (limit <= 0 || length <= limit) return text;
+  const marker = (dropped2) => `
+\u2026 [${dropped2} characters elided] \u2026
+`;
+  const usable = Math.max(limit - cpLength(marker(length)), 0);
+  if (usable === 0) return cpSlice(text, 0, limit);
+  const headChars = Math.trunc(usable * headRatio);
+  const tailChars = usable - headChars;
+  const dropped = length - headChars - tailChars;
+  const tail = tailChars ? cpTail(text, tailChars) : "";
+  return cpSlice(text, 0, headChars) + marker(dropped) + tail;
+}
+var STEP_HEADER = /^Observation \(step ([0-9]+)\):\n/;
+var LOOP_REMINDER = /\n\n(?:Commands|Tool calls) remaining: [0-9]+\. Finish now if the task is answerable; do not repeat prior (?:commands|calls)\.(?=\n?$)/g;
+var PAGE_FOOTER = /\n\n\[page ([0-9]+) of ([0-9]+) — [0-9]+ characters total, nothing discarded\. /;
+var decimal = (digits) => BigInt(digits).toString();
+function compact(content, policy) {
+  if (content.startsWith(COMPACT_MARKER)) return content;
+  const stepMatch = STEP_HEADER.exec(content);
+  let recovery = "";
+  let body = content;
+  if (stepMatch) {
+    const step = decimal(stepMatch[1]);
+    body = content.slice(stepMatch[0].length);
+    const newline = body.indexOf("\n");
+    const ledgerLine = newline < 0 ? body : body.slice(0, newline);
+    const ledger = ledgerLine.startsWith("[evidence ledger: ") && ledgerLine.endsWith("]") ? ledgerLine : "";
+    if (ledger && newline >= 0) body = body.slice(newline + 1);
+    body = body.replace(LOOP_REMINDER, "");
+    const footer = PAGE_FOOTER.exec(body);
+    const page = footer ? decimal(footer[1]) : "1";
+    const total = footer ? decimal(footer[2]) : "1";
+    if (footer) body = body.slice(0, footer.index);
+    recovery = `; step ${step}, page ${page} of ${total}; retrieve stored output: {"action":"page","step":${step},"page":${page}}`;
+    if (ledger) recovery += `; ${ledger}`;
+  }
+  const preview = clip(body, policy.compact_preview_chars, policy.clip_head_ratio);
+  return `${COMPACT_MARKER}${recovery}] ${preview}`;
+}
+var textContent = (message) => typeof message?.content === "string" ? message.content : null;
+var contentLength = (message) => cpLength(textContent(message) ?? "");
+function widestIndex(indexes, messages) {
+  let best;
+  let bestLength = -1;
+  for (const index of indexes) {
+    const length = contentLength(messages[index]);
+    if (length > bestLength) {
+      best = index;
+      bestLength = length;
+    }
+  }
+  return best;
+}
+function textCandidates(messages, from, to, minimum) {
+  const result = [];
+  for (let index = from; index < to; index += 1) {
+    if (textContent(messages[index]) !== null && contentLength(messages[index]) > minimum) result.push(index);
+  }
+  return result;
+}
+function fitToContext(messages, options) {
+  const policy = options.policy ?? new ContextPolicy();
+  const keepRecent = options.keepRecent ?? policy.keep_recent;
+  const budget = contextBudget(options.numCtx, options.numPredict, policy.safety_margin_tokens);
+  const count = options.tokenCounter ?? ((value) => messagesTokens(value, policy));
+  if (count(messages) <= budget) return [messages, false];
+  const pinned = Math.min(2, messages.length);
+  const trimmed = messages.map((message) => ({ ...message }));
+  const observations = [];
+  for (let index = pinned; index < trimmed.length; index += 1) {
+    const role = trimmed[index].role;
+    if ((role === "user" || role === "tool") && textContent(trimmed[index]) !== null) observations.push(index);
+  }
+  const protectedIndexes = new Set(keepRecent ? observations.slice(-keepRecent) : []);
+  let compacted = false;
+  const target = Math.floor(budget * COMPACTION_TARGET_RATIO);
+  for (const index of observations) {
+    if (count(trimmed) <= target) break;
+    if (protectedIndexes.has(index)) continue;
+    const content = textContent(trimmed[index]);
+    const replacement = compact(content, policy);
+    if (cpLength(replacement) < cpLength(content)) {
+      trimmed[index].content = replacement;
+      compacted = true;
+    }
+  }
+  const shrinkWidest = (candidates) => {
+    const widest = widestIndex(candidates, trimmed);
+    if (widest === void 0) return false;
+    const content = textContent(trimmed[widest]) ?? "";
+    const keep = Math.max(Math.trunc(cpLength(content) * policy.compact_retain_ratio), policy.compact_preview_chars);
+    if (keep >= cpLength(content)) return false;
+    trimmed[widest].content = clip(content, keep, policy.clip_head_ratio);
+    compacted = true;
+    return true;
+  };
+  for (let guard = 0; count(trimmed) > budget && guard < 200; guard += 1) {
+    if (!shrinkWidest(observations)) break;
+  }
+  for (const message of trimmed.slice(pinned, Math.max(trimmed.length - 2, pinned))) {
+    const thinking = message.thinking;
+    if (count(trimmed) <= budget) break;
+    if (typeof thinking === "string" && cpLength(thinking) > policy.compact_preview_chars) {
+      message.thinking = compact(thinking, policy);
+      compacted = true;
+    }
+  }
+  for (let guard = 0; count(trimmed) > budget && guard < 200; guard += 1) {
+    const candidates = textCandidates(trimmed, pinned, trimmed.length, policy.compact_preview_chars);
+    if (candidates.length === 0 || !shrinkWidest(candidates)) break;
+  }
+  for (let guard = 0; policy.pinned_overflow === "clip" && count(trimmed) > budget && guard < 200; guard += 1) {
+    const candidates = textCandidates(trimmed, 0, pinned, policy.compact_preview_chars);
+    if (candidates.length === 0 || !shrinkWidest(candidates)) break;
+  }
+  if (count(trimmed) > budget) {
+    throw new ValidationError(
+      `pinned system/question content and minimum history exceed context budget: ${count(trimmed)} > ${budget} estimated tokens. Increase FREELLAMA_AGENT_NUM_CTX, reduce the task/instructions, or explicitly set FREELLAMA_AGENT_PINNED_OVERFLOW=clip.`
+    );
+  }
+  return [trimmed, compacted];
+}
+
+// src/research/context-manager.ts
+function timeNs() {
+  const subMillis = process.hrtime.bigint() % 1000000n;
+  return (BigInt(Date.now()) * 1000000n + subMillis).toString();
+}
+var AgentContextManager = class {
+  runtime;
+  model;
+  calibrationDir;
+  calibrationIdentity;
+  budgeter;
+  calibrationSource;
+  compactions = 0;
+  constructor(runtime, options = {}) {
+    this.runtime = runtime;
+    this.model = options.model ?? "";
+    this.calibrationDir = 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";
+  }
+  modelKey() {
+    return createHash("sha256").update(this.calibrationContractJson(), "utf8").digest("hex").slice(0, 24);
+  }
+  calibrationContract() {
+    return {
+      schema_version: 2,
+      model: this.model,
+      identity: this.calibrationIdentity,
+      estimator_version: 1,
+      chars_per_token: this.runtime.context.chars_per_token,
+      image_token_estimate: this.runtime.context.image_token_estimate
+    };
+  }
+  /** The canonical JSON the model key hashes. */
+  calibrationContractJson() {
+    return canonicalJson(this.calibrationContract(), { floatKeys: this.runtime.context.floatKeys });
+  }
+  /** One persisted calibration record: the contract plus the float `scale` and integer `samples`. */
+  calibrationRecordJson(scale, samples) {
+    const floatKeys = /* @__PURE__ */ new Set([...this.runtime.context.floatKeys, "scale"]);
+    return `${canonicalJson({ ...this.calibrationContract(), scale, samples }, { floatKeys })}
+`;
+  }
+  /** Record files `<key>-*.json`; the key is hexadecimal, so only the literal affixes matter. */
+  records(directory, key) {
+    const prefix = `${key}-`;
+    return readdirSync(directory).filter((name) => name.startsWith(prefix) && name.endsWith(".json") && name.length >= prefix.length + 5);
+  }
+  loadCalibration() {
+    if (!this.model || this.calibrationDir === null || !existsSync(this.calibrationDir)) return null;
+    let bestScale = 1;
+    let samples = 0;
+    const contract = this.calibrationContract();
+    for (const name of this.records(this.calibrationDir, this.modelKey())) {
+      let record;
+      try {
+        record = JSON.parse(readFileSync(path.join(this.calibrationDir, name), "utf8"));
+      } catch {
+        continue;
+      }
+      if (!isRecord(record)) continue;
+      if (Object.entries(contract).some(([key, value]) => record[key] !== value)) continue;
+      const scale = record.scale ?? 1;
+      const recordSamples = record.samples ?? 0;
+      if (typeof scale !== "number" || typeof recordSamples !== "number") continue;
+      if (!Number.isFinite(scale) || scale < 1 || !(Math.trunc(recordSamples) > 0)) continue;
+      bestScale = Math.max(bestScale, scale);
+      samples = Math.max(samples, Math.trunc(recordSamples));
+    }
+    return samples ? { scale: bestScale, samples } : null;
+  }
+  persistCalibration() {
+    if (!this.model || this.calibrationDir === null) return;
+    mkdirSync(this.calibrationDir, { recursive: true });
+    const key = this.modelKey();
+    const stem = `${key}-${timeNs()}-${process.pid}`;
+    const temporary = path.join(this.calibrationDir, `${stem}.tmp`);
+    writeFileSync(temporary, this.calibrationRecordJson(this.budgeter.scale, this.budgeter.calibration_samples), "utf8");
+    renameSync(temporary, path.join(this.calibrationDir, `${stem}.json`));
+    const records = this.records(this.calibrationDir, key).sort();
+    for (const stale of records.slice(0, Math.max(records.length - 32, 0))) {
+      try {
+        unlinkSync(path.join(this.calibrationDir, stale));
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+  }
+  fit(messages) {
+    const [fitted, compacted] = fitToContext(messages, {
+      numCtx: this.runtime.num_ctx,
+      numPredict: this.runtime.num_predict,
+      policy: this.runtime.context,
+      tokenCounter: this.budgeter.estimate
+    });
+    this.compactions += compacted ? 1 : 0;
+    return fitted;
+  }
+  observe(messages, promptEvalCount) {
+    if (this.budgeter.observe(messages, promptEvalCount)) this.persistCalibration();
+  }
+  metadata() {
+    return {
+      ...this.runtime.context.metadata(),
+      ...this.budgeter.metadata(),
+      calibration_source: this.calibrationSource,
+      calibration_scope: this.calibrationIdentity ? "provided_identity_and_estimator" : "model_tag_and_estimator",
+      compaction_target_ratio: COMPACTION_TARGET_RATIO,
+      estimated_input_budget: contextBudget(this.runtime.num_ctx, this.runtime.num_predict, this.runtime.context.safety_margin_tokens),
+      compactions: this.compactions
+    };
+  }
+};
+function writeFailureResult(resultPath, answer) {
+  mkdirSync(path.dirname(resultPath), { recursive: true });
+  writeFileSync(resultPath, `${JSON.stringify({ final_answer: answer, tool_calls: [], usage: {} }, null, 2)}
+`, "utf8");
+}
+
+// src/research/observations.ts
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync as existsSync2, mkdirSync as mkdirSync2, mkdtempSync, openSync, readFileSync as readFileSync2, readSync, renameSync as renameSync2, rmSync, unlinkSync as unlinkSync2, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path2 from "node:path";
+function pageFooter(step, page, total, totalChars) {
+  if (total <= 1) return "";
+  const head = `
+
+[page ${page} of ${total} \u2014 ${totalChars} characters total, nothing discarded. `;
+  if (page >= total) return `${head}End of stored output.]`;
+  return `${head}For the next page send exactly: {"action":"page","step":${step},"page":${page + 1}} \u2014 that re-reads stored output and does NOT re-run the command.]`;
+}
+function encodeStrict(text) {
+  if (/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(text)) {
+    throw new ValidationError("observation contains a lone surrogate and cannot be encoded as UTF-8");
+  }
+  return Buffer.from(text, "utf8");
+}
+function writeAll(fd, data) {
+  let offset = 0;
+  while (offset < data.length) offset += writeSync(fd, data, offset, data.length - offset);
+}
+function readAt(file, position, length) {
+  const fd = openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    let read = 0;
+    while (read < length) {
+      const count = readSync(fd, buffer, read, length - read, position + read);
+      if (count === 0) break;
+      read += count;
+    }
+    return buffer.subarray(0, read);
+  } finally {
+    closeSync(fd);
+  }
+}
+var utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+var ObservationStore = class {
+  directory;
+  pageSize;
+  byStep = /* @__PURE__ */ new Map();
+  constructor(pageSize = OBSERVATION_PAGE_CHARS) {
+    if (pageSize <= 0) throw new ValidationError("observation page size must be > 0");
+    this.directory = mkdtempSync(path2.join(path2.resolve(tmpdir()), "freellama-observations-"));
+    this.pageSize = pageSize;
+  }
+  close() {
+    this.byStep.clear();
+    rmSync(this.directory, { recursive: true, force: true });
+  }
+  put(step, text, metadata = {}) {
+    if (step < 1) throw new ValidationError("observation step must be positive");
+    const file = path2.join(this.directory, `${step}.utf8`);
+    const indexPath = path2.join(this.directory, `${step}.index`);
+    let start = 0;
+    let offset = 0;
+    let pages = 0;
+    let characters = 0;
+    const output = openSync(file, "w");
+    const index = openSync(indexPath, "w");
+    try {
+      while (start < text.length) {
+        let end = cpAdvance(text, start, this.pageSize);
+        if (end < text.length) {
+          const newline = text.lastIndexOf("\n", end - 1);
+          if (newline >= start) end = newline + 1;
+        }
+        const slice = text.slice(start, end);
+        characters += cpLength(slice);
+        const encoded = encodeStrict(slice);
+        writeAll(output, encoded);
+        const nextOffset = offset + encoded.length;
+        const record = Buffer.alloc(16);
+        record.writeBigUInt64BE(BigInt(offset), 0);
+        record.writeBigUInt64BE(BigInt(nextOffset), 8);
+        writeAll(index, record);
+        offset = nextOffset;
+        pages += 1;
+        start = end;
+      }
+      if (!pages) {
+        writeAll(index, Buffer.alloc(16));
+        pages = 1;
+      }
+    } finally {
+      closeSync(output);
+      closeSync(index);
+    }
+    const bounded = {};
+    for (const [key, value] of Object.entries(metadata)) {
+      if (key === "action" || key === "status" || key === "source") bounded[key] = clip(String(value), 240);
+    }
+    this.byStep.set(step, { path: file, indexPath, characters, pages, metadata: bounded });
+  }
+  /** Explicit full materialization for consumers that need it; adapters use view/writeResult. */
+  get(step) {
+    const record = this.byStep.get(step);
+    return record ? utf8.decode(readFileSync2(record.path)) : null;
+  }
+  pageCount(step) {
+    const record = this.byStep.get(step);
+    if (!record) throw new Error(`no stored observation for step ${step}`);
+    return record.pages;
+  }
+  /** Return `[body, footer]` for one page of a stored observation. */
+  view(step, page = 1) {
+    const record = this.byStep.get(step);
+    if (!record) {
+      const known = [...this.byStep.keys()].sort((a, b) => a - b).join(", ") || "none yet";
+      return [`no stored output for step ${step} (known steps: ${known})`, ""];
+    }
+    const chosen = Math.max(1, Math.min(page, record.pages));
+    const entry = readAt(record.indexPath, (chosen - 1) * 16, 16);
+    const start = Number(entry.readBigUInt64BE(0));
+    const end = Number(entry.readBigUInt64BE(8));
+    const chunk = utf8.decode(readAt(record.path, start, end - start));
+    return [chunk, pageFooter(step, chosen, record.pages, record.characters)];
+  }
+  message(step, page = 1) {
+    const [body, footer] = this.view(step, page);
+    const record = this.byStep.get(step);
+    if (!record) return `Observation (step ${step}):
+${body}`;
+    const chosen = Math.max(1, Math.min(page, record.pages));
+    const ledger = { ...record.metadata, step, page: chosen, total_pages: record.pages, trust: "untrusted_tool_output" };
+    return `Observation (step ${step}):
+[evidence ledger: ${JSON.stringify(ledger)}]
+${body}${footer}`;
+  }
+  /** Decode a stored UTF-8 file in 64 KiB reads, never splitting a code point across chunks. */
+  streamStored(file, consume) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    const fd = openSync(file, "r");
+    try {
+      const buffer = Buffer.alloc(65536);
+      for (; ; ) {
+        const count = readSync(fd, buffer, 0, buffer.length, null);
+        if (count === 0) break;
+        const chunk = decoder.decode(buffer.subarray(0, count), { stream: true });
+        if (chunk) consume(chunk);
+      }
+      const rest = decoder.decode();
+      if (rest) consume(rest);
+    } finally {
+      closeSync(fd);
+    }
+  }
+  /** Atomically write the public JSON result, restoring full call results from disk. */
+  writeResult(resultPath, result) {
+    const directory = path2.dirname(resultPath);
+    mkdirSync2(directory, { recursive: true });
+    const temporary = path2.join(directory, `.${path2.basename(resultPath)}.${randomBytes(6).toString("hex")}.tmp`);
+    let fd = null;
+    try {
+      fd = openSync(temporary, "wx", 384);
+      const out = fd;
+      const emit = (text) => writeAll(out, Buffer.from(text, "utf8"));
+      emit("{");
+      Object.entries(result).forEach(([key, value], fieldIndex) => {
+        if (fieldIndex) emit(",");
+        emit(`${JSON.stringify(key)}:`);
+        if (key !== "tool_calls") {
+          emit(JSON.stringify(value) ?? "null");
+          return;
+        }
+        emit("[");
+        value.forEach((call, callIndex) => {
+          const step = callIndex + 1;
+          if (step > 1) emit(",");
+          const metadata = {};
+          for (const [name, item] of Object.entries(call)) if (name !== "result") metadata[name] = item;
+          const encoded = JSON.stringify(metadata);
+          emit(encoded.slice(0, -1) + (Object.keys(metadata).length ? "," : "") + '"result":"');
+          const record = this.byStep.get(step);
+          if (!record) throw new Error(`no stored observation for step ${step}`);
+          this.streamStored(record.path, (chunk) => emit(JSON.stringify(chunk).slice(1, -1)));
+          emit('"}');
+        });
+        emit("]");
+      });
+      emit("}\n");
+      closeSync(fd);
+      fd = null;
+      renameSync2(temporary, resultPath);
+    } finally {
+      if (fd !== null) closeSync(fd);
+      if (existsSync2(temporary)) unlinkSync2(temporary);
+    }
+  }
+};
+
+// src/research/transport.ts
+import { createHash as createHash2 } from "node:crypto";
+
+// src/research/transport-http.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+var RECEIPT_BODY_LIMIT = 64 * 1024;
+var HTTPError = class extends Error {
+  constructor(code, reason, body = Buffer.alloc(0)) {
+    super(`HTTP Error ${code}: ${reason}`);
+    this.code = code;
+    this.reason = reason;
+    this.body = body;
+  }
+  code;
+  reason;
+  body;
+  name = "HTTPError";
+};
+var URLError = class extends Error {
+  constructor(reason) {
+    super(`request not sent: ${reason.message}`);
+    this.reason = reason;
+  }
+  reason;
+  name = "URLError";
+};
+var RequestTimeoutError = class extends Error {
+  name = "RequestTimeoutError";
+  constructor(message = "timed out") {
+    super(message);
+  }
+};
+function requestHeaders(env = process.env) {
+  const headers = { "content-type": "application/json" };
+  const tokenFile = trimSpace(env.FREELLAMA_AUTH_TOKEN_FILE ?? "");
+  if (!tokenFile) return headers;
+  const token = trimSpace(decodeUtf8(readFileSync3(tokenFile), "FREELLAMA_AUTH_TOKEN_FILE"));
+  if (cpLength(token) < 32 || [...token].some((character) => isSpace(character))) {
+    throw new ValidationError("FREELLAMA_AUTH_TOKEN_FILE must contain one token of at least 32 bytes");
+  }
+  headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+function httpRequest(url, options) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      reject(new ValidationError(`unknown url type: ${JSON.stringify(url)}`));
+      return;
+    }
+    const client = parsed.protocol === "https:" ? https : parsed.protocol === "http:" ? http : null;
+    if (client === null) {
+      reject(new URLError(new Error(`unknown url type: ${parsed.protocol.replace(/:$/, "")}`)));
+      return;
+    }
+    const headers = { ...options.headers, connection: "close" };
+    if (options.body) headers["content-length"] = String(options.body.length);
+    let sent = false;
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      request.destroy();
+      reject(error);
+    };
+    const request = client.request(parsed, { method: options.method, headers });
+    request.setTimeout(Math.max(options.timeoutSeconds * 1e3, 1), () => {
+      fail(sent ? new RequestTimeoutError() : new URLError(new RequestTimeoutError()));
+    });
+    request.on("finish", () => {
+      sent = true;
+    });
+    request.on("error", (error) => fail(sent ? error : new URLError(error)));
+    request.on("response", (response) => {
+      const chunks = [];
+      let size = 0;
+      const status = response.statusCode ?? 0;
+      const ok = status >= 200 && status < 300;
+      const limit = ok ? options.limit : RECEIPT_BODY_LIMIT + 1;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        const body = Buffer.concat(chunks);
+        request.destroy();
+        if (ok) resolve(body);
+        else reject(new HTTPError(status, response.statusMessage ?? "", body));
+      };
+      response.on("data", (chunk) => {
+        if (limit !== void 0 && size >= limit) return;
+        const piece = limit !== void 0 ? chunk.subarray(0, limit - size) : chunk;
+        chunks.push(piece);
+        size += piece.length;
+        if (limit !== void 0 && size >= limit) finish();
+      });
+      response.on("error", (error) => fail(error));
+      response.on("end", finish);
+    });
+    request.end(options.body);
+  });
+}
+function parseJsonBody(body, source) {
+  return JSON.parse(decodeUtf8(body, source));
+}
+async function requestJson(url, payload, timeoutSeconds) {
+  const body = Buffer.from(JSON.stringify(payload), "utf8");
+  const response = await httpRequest(url, { method: "POST", headers: requestHeaders(), body, timeoutSeconds });
+  return parseJsonBody(response, "chat response");
+}
+
+// src/research/transport.ts
+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 });
+  if (payload.length > IDENTITY_LIMIT) throw new ValidationError("model identity catalog exceeds size limit");
+  return parseJsonBody(payload, "model identity catalog");
+}
+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 = {}) {
+  const endpoint = trimSlashes(endpointInput);
+  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 digestValue = entry?.digest;
+    if (typeof digestValue !== "string" || !DIGEST.test(digestValue)) return unknown;
+    const digest = (digestValue.startsWith("sha256:") ? digestValue.slice("sha256:".length) : digestValue).toLowerCase();
+    const contract = { endpoint, model, digest, system_hash: sha256(systemPrompt) };
+    return {
+      identity: sha256(canonicalJson(contract)),
+      verified: true,
+      scope: "manifest_digest_and_system_prompt",
+      digest
+    };
+  } catch (error) {
+    if (isTransportError(error) || isSystemError(error) || error instanceof ValidationError || error instanceof SyntaxError || error instanceof TypeError) {
+      return unknown;
+    }
+    throw error;
+  }
+}
+function isTransportError(error) {
+  return error instanceof HTTPError || error instanceof URLError || error instanceof RequestTimeoutError;
+}
+function retryableChatError(error) {
+  if (error instanceof HTTPError) return error.code === 503;
+  return error instanceof URLError && error.reason.code === "ECONNREFUSED";
+}
+var RECEIPT_FIELDS = /* @__PURE__ */ new Set([
+  "error",
+  "code",
+  "reason",
+  "retry_after_seconds",
+  "resource_admission",
+  "lifecycle",
+  "placement",
+  "execution",
+  "admission",
+  "route",
+  "decision",
+  "quality",
+  "feedback"
+]);
+var PAYLOAD_FIELDS = /* @__PURE__ */ new Set([
+  "prompt",
+  "system",
+  "system_prompt",
+  "messages",
+  "content",
+  "input",
+  "images",
+  "tools",
+  "request",
+  "request_options",
+  "headers",
+  "authorization",
+  "token",
+  "api_key",
+  "auth_token"
+]);
+function receiptValue(value) {
+  if (isRecord(value)) {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (!PAYLOAD_FIELDS.has(key.toLowerCase())) result[key] = receiptValue(item);
+    }
+    return result;
+  }
+  if (Array.isArray(value)) return value.map(receiptValue);
+  return value;
+}
+function errorDiagnostic(error) {
+  if (error instanceof Error) return `${error.name}: ${error.message}`;
+  return String(error);
+}
+function chatErrorDetails(error) {
+  let diagnostic = errorDiagnostic(error);
+  if (!(error instanceof HTTPError)) return [diagnostic, null];
+  const details = { status: error.code };
+  try {
+    const body = error.body.subarray(0, RECEIPT_BODY_LIMIT + 1);
+    if (body.length > RECEIPT_BODY_LIMIT) return [diagnostic, details];
+    const payload = parseJsonBody(body, "refusal body");
+    if (!isRecord(payload) || typeof payload.error !== "string") return [diagnostic, details];
+    const receipt = {};
+    for (const [key, value] of Object.entries(payload)) {
+      if (RECEIPT_FIELDS.has(key)) receipt[key] = receiptValue(value);
+    }
+    details.receipt = receipt;
+    diagnostic = `HTTP ${error.code}: ${receipt.error}`;
+  } catch (failure) {
+    if (!(failure instanceof SyntaxError || failure instanceof ValidationError || failure instanceof RangeError)) throw failure;
+  }
+  return [diagnostic, details];
+}
+var PromptCacheUsage = class {
+  calls = 0;
+  reportedCalls = 0;
+  reportedTokens = 0;
+  reportedPromptTokens = 0;
+  observe(response) {
+    this.calls += 1;
+    const cached = response.prompt_eval_cached_count;
+    const prompt = response.prompt_eval_count;
+    if (Number.isInteger(cached) && Number.isInteger(prompt) && cached >= 0 && cached <= prompt) {
+      this.reportedCalls += 1;
+      this.reportedTokens += cached;
+      this.reportedPromptTokens += prompt;
+    }
+  }
+  get tokens() {
+    return this.calls > 0 && this.calls === this.reportedCalls ? this.reportedTokens : null;
+  }
+  metadata() {
+    const tokens = this.tokens;
+    return {
+      status: tokens !== null ? "reported" : this.reportedCalls ? "partially_reported" : "not_reported",
+      calls: this.calls,
+      reported_calls: this.reportedCalls,
+      reported_tokens: this.reportedCalls ? this.reportedTokens : null,
+      hit_ratio: tokens !== null && this.reportedPromptTokens ? this.reportedTokens / this.reportedPromptTokens : null
+    };
+  }
+};
+function chatRequest(endpointInput, model, messages, options, think, keepAlive, executionPreference = "auto", minPlacementEvidence = "configured") {
+  const endpoint = trimSlashes(endpointInput);
+  if (endpoint.endsWith(MANAGED_SUFFIX)) {
+    const managedOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (key !== "num_ctx") managedOptions[key] = value;
+    }
+    if (!Object.hasOwn(options, "num_ctx")) throw new ValidationError("managed chat request requires num_ctx");
+    return [endpoint, {
+      task: "coding",
+      objective: "fastest",
+      model,
+      context_tokens: options.num_ctx,
+      execution_preference: executionPreference,
+      min_placement_evidence: minPlacementEvidence,
+      messages,
+      keep_alive: keepAlive,
+      request_options: { format: "json", think, options: managedOptions }
+    }];
+  }
+  return [`${endpoint}/api/chat`, {
+    model,
+    messages,
+    stream: false,
+    truncate: false,
+    shift: false,
+    format: "json",
+    think,
+    keep_alive: keepAlive,
+    options
+  }];
+}
+function unwrapChatResponse(payload, executionReceipts) {
+  if (!isRecord(payload)) throw new TypeError("chat response must be a JSON object");
+  const { response } = payload;
+  if (!isRecord(response)) return payload;
+  const route = payload.route ?? {};
+  if (!isRecord(route)) throw new TypeError("managed chat response route must be a JSON object");
+  executionReceipts.push({
+    model: route.selected_model ?? null,
+    execution: payload.execution ?? null,
+    admission: payload.admission ?? null,
+    feedback: payload.feedback ?? null
+  });
+  return response;
+}
+
+// src/research/workspace-path.ts
+import { lstatSync, readlinkSync, statSync } from "node:fs";
+import path3 from "node:path";
+var SymlinkLoopError = class extends ValidationError {
+  name = "SymlinkLoopError";
+};
+var hasNul = (text) => text.includes("\0");
+function cleanPath(text) {
+  const parts = text.split("/").filter((part) => part !== "" && part !== ".");
+  if (text.startsWith("/")) return `/${parts.join("/")}`;
+  return parts.join("/") || ".";
+}
+function joinPath(base, child) {
+  return cleanPath(child.startsWith("/") ? child : `${base}/${child}`);
+}
+function escapesRoot(resolved, root) {
+  const a = cleanPath(resolved);
+  const b = cleanPath(root);
+  return a !== b && !a.startsWith(b === "/" ? "/" : `${b}/`);
+}
+var IGNORED = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR", "EBADF", "ELOOP"]);
+function probe(read, fallback) {
+  try {
+    return read();
+  } catch (error) {
+    if (IGNORED.has(error.code ?? "")) return fallback;
+    throw error;
+  }
+}
+function exists(target) {
+  return !hasNul(target) && probe(() => (statSync(target), true), false);
+}
+function isSymlink(target) {
+  return !hasNul(target) && probe(() => lstatSync(target).isSymbolicLink(), false);
+}
+function lexists(target) {
+  if (hasNul(target)) return false;
+  try {
+    lstatSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isDir(target) {
+  if (hasNul(target)) return false;
+  try {
+    return statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function readlink(target) {
+  if (hasNul(target)) throw new ValidationError("embedded null byte");
+  try {
+    return readlinkSync(target);
+  } catch {
+    return null;
+  }
+}
+function resolvePath(target, cwd = process.cwd()) {
+  const seen = /* @__PURE__ */ new Map();
+  const walk = (start, rest) => {
+    let current = rest.startsWith("/") ? "" : start;
+    for (const name of rest.split("/")) {
+      if (!name || name === ".") continue;
+      if (name === "..") {
+        current = current.slice(0, Math.max(current.lastIndexOf("/"), 0));
+        continue;
+      }
+      const next = `${current}/${name}`;
+      if (seen.has(next)) {
+        const cached = seen.get(next);
+        if (cached === null || cached === void 0) throw new SymlinkLoopError(`symlink loop at ${JSON.stringify(next)}`);
+        current = cached;
+        continue;
+      }
+      const link = readlink(next);
+      if (link === null) {
+        current = next;
+      } else {
+        seen.set(next, null);
+        current = walk(current, link);
+        seen.set(next, current);
+      }
+    }
+    return current;
+  };
+  const text = cleanPath(target);
+  return path3.posix.normalize(walk(text.startsWith("/") ? "" : cwd, text) || "/");
+}
+
+// src/research/agent-loop.ts
+var isValidationError = (error) => error instanceof ValidationError;
+function requireEnv(env, name) {
+  const value = env[name];
+  if (value === void 0) throw new Error(`${name} is not set`);
+  return value;
+}
+var readText = (file) => normalizeNewlines(decodeUtf8(readFileSync4(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 });
+async function runAdapter(spec, hooks = {}) {
+  const env = hooks.env ?? process.env;
+  let resultPath = null;
+  try {
+    const model = env.FREELLAMA_TARGET_MODEL || requireEnv(env, "FREELLAMA_BENCH_MODEL");
+    const workspace = resolvePath(pathOf(requireEnv(env, "FREELLAMA_BENCH_WORKSPACE")));
+    const prompt = readText(pathOf(requireEnv(env, "FREELLAMA_BENCH_PROMPT")));
+    resultPath = pathOf(requireEnv(env, "FREELLAMA_AGENT_RESULT"));
+    return await runLoop(spec, hooks, env, { model, workspace, prompt, resultPath });
+  } catch (error) {
+    const answer = `unexpected adapter error: ${errorDiagnostic(error)}`;
+    process.stderr.write(`${error instanceof Error ? error.stack ?? answer : answer}
+`);
+    if (resultPath !== null) {
+      try {
+        writeFailureResult(resultPath, answer);
+      } catch {
+      }
+    }
+    return 1;
+  }
+}
+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 endpoint = (env.FREELLAMA_OLLAMA_ENDPOINT ?? "http://127.0.0.1:11434").replace(/\/+$/, "");
+  const managedEndpoint = (env.FREELLAMA_AGENT_MANAGED_ENDPOINT ?? "").replace(/\/+$/, "");
+  const executionPreference = env.FREELLAMA_AGENT_EXECUTION_PREFERENCE ?? "auto";
+  const minPlacementEvidence = env.FREELLAMA_AGENT_MIN_PLACEMENT_EVIDENCE ?? "configured";
+  let runtime;
+  try {
+    runtime = AgentRuntimeConfig.fromEnv({ defaultToolTimeoutSeconds: spec.defaultToolTimeoutSeconds, env });
+  } catch (error) {
+    if (!isValidationError(error)) throw error;
+    const answer2 = `invalid research adapter configuration: ${error.message}`;
+    writeFailureResult(resultPath, answer2);
+    print(answer2);
+    return 1;
+  }
+  let messages = [
+    { role: "system", content: spec.systemPrompt(workspace) },
+    { role: "user", content: prompt }
+  ];
+  const calls = [];
+  const usage = { input_tokens: 0, output_tokens: 0, cache_read_tokens: null, cache_write_tokens: null };
+  const cacheUsage = new PromptCacheUsage();
+  const metrics = { load_ms: 0, prompt_eval_ms: 0, eval_ms: 0 };
+  const executionReceipts = [];
+  let answer = "";
+  let failure = null;
+  let transportError = 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 contextManager = new AgentContextManager(runtime, {
+    model,
+    calibrationIdentity: calibrationModelIdentity.identity,
+    calibrationDir: calibrationDir && calibrationModelIdentity.verified ? calibrationDir : null
+  });
+  try {
+    messages = contextManager.fit(messages);
+  } catch (error) {
+    if (!isValidationError(error)) throw error;
+    answer = `research task does not fit the configured context safely: ${error.message}`;
+    writeFailureResult(resultPath, answer);
+    print(answer);
+    return 1;
+  }
+  const chatOptions = {
+    temperature: runtime.temperature,
+    seed: runtime.seed,
+    num_ctx: runtime.num_ctx,
+    num_predict: runtime.num_predict
+  };
+  const callModel = async () => {
+    let lastError = null;
+    let response = null;
+    for (let attempt = 0; attempt < runtime.retry_attempts; attempt += 1) {
+      try {
+        const transportEndpoint = managedEndpoint ? `${managedEndpoint}/_freellama/v1/tasks` : endpoint;
+        const [url, payload] = chatRequest(
+          transportEndpoint,
+          model,
+          messages,
+          chatOptions,
+          runtime.think,
+          runtime.keep_alive,
+          executionPreference,
+          minPlacementEvidence
+        );
+        response = unwrapChatResponse(await sendJson(url, payload, runtime.request_timeout_seconds), executionReceipts);
+        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 (response === null) throw lastError;
+    usage.input_tokens = usage.input_tokens + Math.trunc(numberOr(response.prompt_eval_count, 0));
+    cacheUsage.observe(response);
+    usage.cache_read_tokens = cacheUsage.tokens;
+    usage.output_tokens = usage.output_tokens + Math.trunc(numberOr(response.eval_count, 0));
+    metrics.load_ms += numberOr(response.load_duration, 0) / 1e6;
+    metrics.prompt_eval_ms += numberOr(response.prompt_eval_duration, 0) / 1e6;
+    metrics.eval_ms += numberOr(response.eval_duration, 0) / 1e6;
+    contextManager.observe(messages, response.prompt_eval_count);
+    return response;
+  };
+  const refit = () => {
+    try {
+      messages = contextManager.fit(messages);
+      return true;
+    } catch (error) {
+      if (!isValidationError(error)) throw error;
+      failure = `research context cannot be fitted safely: ${error.message}`;
+      return false;
+    }
+  };
+  const content = (response) => {
+    const message = response.message ?? {};
+    if (!isRecord(message)) throw new TypeError("chat response message must be a JSON object");
+    const text = message.content ?? "";
+    return typeof text === "string" ? text : JSON.stringify(text);
+  };
+  const seenCalls = /* @__PURE__ */ new Map();
+  const pageSize = runtime.context.observation_page_chars;
+  const observations = hooks.observationStore ? hooks.observationStore(pageSize) : new ObservationStore(pageSize);
+  let session;
+  try {
+    session = spec.open ? await spec.open(workspace) : void 0;
+    let parseFailures = 0;
+    let exhausted = true;
+    for (let turn = 0; turn < runtime.max_turns; turn += 1) {
+      let response;
+      try {
+        response = await callModel();
+      } catch (error) {
+        if (!isTransportError(error)) throw error;
+        let diagnostic;
+        [diagnostic, transportError] = chatErrorDetails(error);
+        failure = `agent response failed: ${diagnostic}`;
+        exhausted = false;
+        break;
+      }
+      const raw = content(response);
+      let action;
+      try {
+        action = spec.parseAction(raw);
+      } catch (error) {
+        if (!isValidationError(error)) throw error;
+        parseFailures += 1;
+        if (parseFailures > runtime.max_parse_repairs) {
+          failure = `agent gave ${parseFailures} unparseable replies: ${errorDiagnostic(error)}`;
+          exhausted = false;
+          break;
+        }
+        messages.push({ role: "assistant", content: cpSlice(raw, 0, runtime.parse_repair_echo_chars) });
+        messages.push({ role: "user", content: PARSE_REPAIR_NOTICE });
+        if (!refit()) {
+          exhausted = false;
+          break;
+        }
+        continue;
+      }
+      parseFailures = 0;
+      if (action.action === "page") {
+        const wantStep = Math.trunc(numberOr(action.step, 0));
+        const wantPage = Math.trunc(numberOr(action.page, 1));
+        messages.push({ role: "assistant", content: echo(action) });
+        messages.push({ role: "user", content: observations.message(wantStep, wantPage) });
+        if (!refit()) {
+          exhausted = false;
+          break;
+        }
+        continue;
+      }
+      if (action.action === "finish") {
+        answer = trimSpace(String(action.answer ?? ""));
+        exhausted = false;
+        break;
+      }
+      const started = performance.now();
+      const call = session.toolCall(action, workspace, runtime);
+      const signature = callSignature(call.signature);
+      let observation;
+      let status;
+      if (seenCalls.has(signature)) {
+        observation = REPEAT_NOTICE;
+        status = "repeat";
+      } else {
+        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";
+        }
+        seenCalls.set(signature, calls.length + 1);
+      }
+      calls.push({
+        ...call.record,
+        status,
+        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));
+      messages.push({ role: "user", content: observations.message(step) + spec.remaining(remaining) });
+      if (!refit()) {
+        exhausted = false;
+        break;
+      }
+    }
+    if (exhausted) {
+      messages.push({ role: "user", content: spec.exhausted });
+      if (refit()) {
+        try {
+          const response = await callModel();
+          const finalAction = spec.parseAction(content(response));
+          if (finalAction.action !== "finish") throw new ValidationError("forced final response was not finish");
+          answer = trimSpace(String(finalAction.answer ?? ""));
+        } catch (error) {
+          if (!isTransportError(error) && !isValidationError(error)) throw error;
+          let diagnostic;
+          [diagnostic, transportError] = chatErrorDetails(error);
+          failure = `agent exceeded ${runtime.max_turns} turns and finalization failed: ${diagnostic}`;
+        }
+      }
+    }
+    if (!answer) answer = failure ?? "agent stopped without a final answer";
+    const result = {
+      final_answer: answer,
+      tool_calls: calls,
+      usage,
+      provider_metrics: {
+        load_ms: metrics.load_ms,
+        prompt_eval_ms: metrics.prompt_eval_ms,
+        eval_ms: metrics.eval_ms
+      },
+      model_metadata: {
+        ...spec.adapterMetadata(session),
+        temperature: chatOptions.temperature,
+        seed: chatOptions.seed,
+        num_ctx: chatOptions.num_ctx,
+        num_predict: chatOptions.num_predict,
+        max_turns: runtime.max_turns,
+        runtime_config: runtime.metadata(),
+        context_management: contextManager.metadata(),
+        context_compactions: contextManager.compactions,
+        transport: managedEndpoint ? "managed" : "direct_ollama",
+        execution_preference: executionPreference,
+        min_placement_evidence: minPlacementEvidence,
+        execution_receipts: executionReceipts,
+        ...transportError ? { transport_error: transportError } : {},
+        cache_token_metrics: cacheUsage.metadata(),
+        calibration_model_identity: calibrationModelIdentity
+      }
+    };
+    observations.writeResult(resultPath, result);
+    print(answer);
+    return failure ? 1 : 0;
+  } finally {
+    session?.close?.();
+    observations.close();
+  }
+}
+
+// src/research/prompts.ts
+var BASH_SYSTEM_PROMPT = 'You are a local code-research agent in a read-only workspace rooted at the current directory. Use raw POSIX shell commands without editors, special tools, or network access. Return exactly one JSON object per turn:\n\n{"action":"shell","command":"one shell command, e.g. grep -n \\"class Group\\" click/src/click/core.py"}\n{"action":"page","step":2,"page":2}\n{"action":"finish","answer":"concise final answer with repository-relative evidence"}\n\nThese are the complete action schemas. Use only `shell`, `page`, or `finish`; every shown field is\nrequired with the shown type. An invalid shape is rejected and costs one bounded repair turn.\n\nFull command 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 command. Claim "not found" only after checking the relevant search scope and pages.\n\nThe shell is READ-ONLY and restricted. Available tools: ls, find, grep, rg, cat, head, tail, wc,\nsort, uniq, cut, tr, nl, sed (bounded read-only inline programs), jq, diff, xargs\n(only echo, printf, true, or false targets), tree, file, stat, and read-only git\n(log, show, grep, ls-files, diff, blame, status). There is no awk, python, network, output\nredirection, script-file loading, recursive symlink following, paths outside the workspace,\n$(...) substitution, $VARIABLES, or loops: write paths and patterns literally and\nchain tools with pipes, one pipeline per turn. A refused command costs a turn, so follow these\nrules. Be decisive: most tasks need 2-6 commands. Call finish as soon as the requested facts are\nestablished.\n\nSCOPE YOUR SEARCHES. A real workspace holds far more than its source, and an unscoped grep drowns\nthe answer in vendored and generated files. Always exclude them:\n  grep -rn "PATTERN" . --exclude-dir={node_modules,target,.venv,venv,dist,build,.git,vendor,__pycache__,.octocode,site-packages}\nFor implementation questions, prefer src/, packages/*/src/, lib/ and the repo root before fixtures,\nmocks, or examples. If the question targets tests or examples, inspect those files. Name the file\nthat supplies the answer.\nIf a search returns nothing, widen the pattern before concluding the thing does not exist: absence\nof a grep hit is weak evidence, and "not found" is only a real answer once you have looked in the\nsource directories.\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.';
+
+// src/research/sandbox.ts
+import { accessSync, constants as fsConstants, mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, realpathSync, rmSync as rmSync2, symlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import path4 from "node:path";
+
+// src/research/proc.ts
+import { spawn, spawnSync } from "node:child_process";
+import { constants } from "node:os";
+function decodeText(bytes, source = "command output") {
+  return normalizeNewlines(decodeUtf8(bytes, source));
+}
+function runProcess(argv, options) {
+  const timeoutMs = Math.max(options.timeoutSeconds * 1e3, 0);
+  return new Promise((resolve, reject) => {
+    const child = spawn(argv[0], argv.slice(1), {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    const finish = (action) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      action();
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      const fail = () => finish(() => reject(new ToolTimeoutError(
+        `command ${JSON.stringify(argv.at(-1))} timed out after ${options.timeoutSeconds} seconds`
+      )));
+      if (child.exitCode !== null || child.signalCode !== null) fail();
+      else child.once("exit", fail);
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.once("error", (error) => finish(() => reject(error)));
+    child.once("close", (code, signal) => finish(() => {
+      try {
+        resolve({
+          stdout: decodeText(Buffer.concat(stdout)),
+          stderr: decodeText(Buffer.concat(stderr)),
+          returncode: code ?? -(signal ? constants.signals[signal] ?? 1 : 1)
+        });
+      } catch (error) {
+        reject(error);
+      }
+    }));
+  });
+}
+function probe2(argv, env) {
+  const result = spawnSync(argv[0], argv.slice(1), { env, stdio: ["ignore", "pipe", "pipe"], timeout: 1e4, killSignal: "SIGKILL" });
+  return !result.error && result.status === 0;
+}
+
+// src/research/glob.ts
+import { readdirSync as readdirSync2 } from "node:fs";
+var GlobPatternError = class extends ValidationError {
+  name = "GlobPatternError";
+};
+var hasGlobMagic = (text) => /[*?[]/.test(text);
+var isHidden = (name) => name.startsWith(".");
+function globPaths(pattern) {
+  const split = pattern.lastIndexOf("/") + 1;
+  const basename = pattern.slice(split);
+  let dirname = pattern.slice(0, split);
+  if (/[^/]/.test(dirname)) dirname = dirname.replace(/\/+$/, "");
+  if (!hasGlobMagic(pattern)) return (basename ? lexists(pattern) : isDir(dirname)) ? [pattern] : [];
+  if (!dirname) return matchNames("", basename);
+  const directories = dirname !== pattern && hasGlobMagic(dirname) ? globDirectories(dirname) : [dirname];
+  const results = [];
+  for (const directory of directories) {
+    const names = hasGlobMagic(basename) ? matchNames(directory, basename) : (basename ? lexists(join(directory, basename)) : isDir(directory)) ? [basename] : [];
+    for (const name of names) results.push(join(directory, name));
+  }
+  return results;
+}
+function globDirectories(pattern) {
+  return globPaths(pattern).filter((match) => isDir(match));
+}
+function join(directory, name) {
+  if (name.startsWith("/")) return name;
+  return !directory || directory.endsWith("/") ? directory + name : `${directory}/${name}`;
+}
+function matchNames(directory, pattern) {
+  const where = directory || ".";
+  if (where.includes("\0")) throw new ValidationError("embedded null byte");
+  let names;
+  try {
+    names = readdirSync2(where);
+  } catch {
+    names = [];
+  }
+  if (!isHidden(pattern)) names = names.filter((name) => !isHidden(name));
+  const matches = compileGlob(pattern);
+  return names.filter(matches);
+}
+function compileGlob(pattern) {
+  const chars = Array.from(pattern);
+  const items = [];
+  for (let index = 0; index < chars.length; ) {
+    const char = chars[index++];
+    if (char === "*") {
+      if (items.at(-1)?.kind !== "star") items.push({ kind: "star" });
+    } else if (char === "?") {
+      items.push({ kind: "any" });
+    } else if (char === "[") {
+      const parsed = parseClass(chars, index, pattern);
+      if (parsed) {
+        items.push(parsed.item);
+        index = parsed.end;
+      } else {
+        items.push({ kind: "char", char: char.codePointAt(0) });
+      }
+    } else {
+      items.push({ kind: "char", char: char.codePointAt(0) });
+    }
+  }
+  return (name) => matchItems(items, Array.from(name, (char) => char.codePointAt(0)));
+}
+function parseClass(chars, start, pattern) {
+  let close = start;
+  if (chars[close] === "!") close += 1;
+  if (chars[close] === "]") close += 1;
+  while (close < chars.length && chars[close] !== "]") close += 1;
+  if (close >= chars.length) return null;
+  const body = chars.slice(start, close);
+  const negate = body[0] === "!";
+  const first = negate ? 1 : 0;
+  const tokens = body.map((char) => ({ char, operator: char === "-" }));
+  if (body.join("").includes("--")) {
+    for (const token of tokens) token.operator = false;
+    for (let hyphen = body.indexOf("-", first + 1); hyphen >= 0; hyphen = body.indexOf("-", hyphen + 3)) {
+      tokens[hyphen].operator = true;
+    }
+  }
+  const ranges = [];
+  const point = (char) => char.codePointAt(0);
+  for (let index = first; index < tokens.length; ) {
+    const low = tokens[index++].char;
+    if (!tokens[index]?.operator || index + 1 >= tokens.length) {
+      ranges.push([point(low), point(low)]);
+      continue;
+    }
+    const high = tokens[index + 1].char;
+    index += 2;
+    if (point(high) < point(low)) {
+      throw new GlobPatternError(`bad character range ${low}-${high} in glob pattern ${JSON.stringify(pattern)}`);
+    }
+    ranges.push([point(low), point(high)]);
+  }
+  return { item: { kind: "class", negate, ranges }, end: close + 1 };
+}
+function matchOne(item, char) {
+  if (item.kind === "any") return true;
+  if (item.kind === "char") return item.char === char;
+  if (item.kind === "class") return item.ranges.some(([low, high]) => char >= low && char <= high) !== item.negate;
+  return false;
+}
+function matchItems(items, name) {
+  let item = 0;
+  let char = 0;
+  let starItem = -1;
+  let starChar = 0;
+  while (char < name.length) {
+    if (item < items.length && items[item].kind !== "star" && matchOne(items[item], name[char])) {
+      item += 1;
+      char += 1;
+    } else if (item < items.length && items[item].kind === "star") {
+      starItem = item;
+      starChar = char;
+      item += 1;
+    } else if (starItem >= 0) {
+      item = starItem + 1;
+      starChar += 1;
+      char = starChar;
+    } else {
+      return false;
+    }
+  }
+  while (item < items.length && items[item].kind === "star") item += 1;
+  return item === items.length;
+}
+
+// src/research/sandbox-sed.ts
+var DIGIT = /^[\p{Nd}\u{b2}-\u{b3}\u{b9}\u{1369}-\u{1371}\u{19da}\u{2070}\u{2074}-\u{2079}\u{2080}-\u{2089}\u{2460}-\u{2468}\u{2474}-\u{247c}\u{2488}-\u{2490}\u{24ea}\u{24f5}-\u{24fd}\u{24ff}\u{2776}-\u{277e}\u{2780}-\u{2788}\u{278a}-\u{2792}\u{10a40}-\u{10a43}\u{10e60}-\u{10e68}\u{11052}-\u{1105a}\u{1f100}-\u{1f10a}]$/u;
+var isDigit = (char) => char !== void 0 && DIGIT.test(char);
+var within = (char, set) => set.includes(char ?? "");
+function checkSed(args) {
+  for (const program of sedPrograms(args)) checkSedProgram(program);
+}
+function checkSedProgram(text) {
+  const program = Array.from(text);
+  const length = program.length;
+  let index = 0;
+  const delimited = (start) => {
+    const delimiter = program[start];
+    let cursor = start + 1;
+    while (cursor < length) {
+      if (program[cursor] === "\\") cursor += 2;
+      else if (program[cursor] === delimiter) return cursor + 1;
+      else cursor += 1;
+    }
+    throw new ValidationError("command blocked: unterminated sed expression");
+  };
+  while (index < length) {
+    while (index < length && (isSpace(program[index]) || within(program[index], ";{}"))) index += 1;
+    if (index === length) return;
+    for (let address = 0; address < 2; address += 1) {
+      if (index < length && isDigit(program[index])) {
+        while (index < length && isDigit(program[index])) index += 1;
+      } else if (index < length && program[index] === "$") {
+        index += 1;
+      } else if (index < length && program[index] === "/") {
+        index = delimited(index);
+      } else if (index + 1 < length && program[index] === "\\") {
+        index = delimited(index + 1);
+      } else {
+        break;
+      }
+      while (index < length && isSpace(program[index])) index += 1;
+      if (address === 0 && index < length && program[index] === ",") {
+        index += 1;
+        continue;
+      }
+      break;
+    }
+    while (index < length && (isSpace(program[index]) || program[index] === "!")) index += 1;
+    if (index === length) throw new ValidationError("command blocked: sed command is missing");
+    const command = program[index];
+    index += 1;
+    if (command === "s" && index < length) {
+      index = delimited(index);
+      index = delimited(index - 1);
+      const flagsStart = index;
+      while (index < length && !within(program[index], ";}\n")) index += 1;
+      const flags = Array.from(trimSpace(program.slice(flagsStart, index).join("")));
+      if (flags.some((flag) => !within(flag, "gIp0123456789"))) {
+        throw new ValidationError("command blocked: sed substitution flags can read, write or execute");
+      }
+    } else if (!within(command, "pPdDqQnNhHgGx={}")) {
+      throw new ValidationError("command blocked: sed command can read, write or execute files");
+    }
+    if (!within(command, "{}") && index < length && !(isSpace(program[index]) || within(program[index], ";{}"))) {
+      throw new ValidationError("command blocked: unsupported sed command argument");
+    }
+  }
+}
+function sedPrograms(args) {
+  const programs = [];
+  let index = 0;
+  while (index < args.length) {
+    const arg = args[index];
+    if (arg === "--") {
+      programs.push(...args.slice(index + 1));
+      break;
+    }
+    if (arg === "--file" || arg.startsWith("--file=")) {
+      throw new ValidationError("command blocked: sed script files can read, write or execute");
+    }
+    if (arg === "--expression") {
+      index += 1;
+      if (index >= args.length) throw new ValidationError("command blocked: sed expression is missing");
+      programs.push(args[index]);
+    } else if (arg.startsWith("--expression=")) {
+      programs.push(arg.slice(arg.indexOf("=") + 1));
+    } else if (arg.startsWith("-") && !arg.startsWith("--")) {
+      const short = Array.from(arg).slice(1);
+      for (let offset = 0; offset < short.length; offset += 1) {
+        const option = short[offset];
+        if (option === "f") throw new ValidationError("command blocked: sed script files can read, write or execute");
+        if (option === "e") {
+          let program = short.slice(offset + 1).join("");
+          if (!program) {
+            index += 1;
+            if (index >= args.length) throw new ValidationError("command blocked: sed expression is missing");
+            program = args[index];
+          }
+          programs.push(program);
+          break;
+        }
+        if (!within(option, "nEr")) throw new ValidationError("command blocked: unsupported sed option");
+      }
+    } else if (!arg.startsWith("--")) {
+      if (programs.length === 0) programs.push(arg);
+    } else {
+      throw new ValidationError("command blocked: unsupported sed option");
+    }
+    index += 1;
+  }
+  return programs;
+}
+
+// src/research/shlex.ts
+var ASCII_WORDCHARS = "abcdfeghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_";
+var POSIX_WORDCHARS = "\xDF\xE0\xE1\xE2\xE3\xE4\xE5\xE6\xE7\xE8\xE9\xEA\xEB\xEC\xED\xEE\xEF\xF0\xF1\xF2\xF3\xF4\xF5\xF6\xF8\xF9\xFA\xFB\xFC\xFD\xFE\xFF\xC0\xC1\xC2\xC3\xC4\xC5\xC6\xC7\xC8\xC9\xCA\xCB\xCC\xCD\xCE\xCF\xD0\xD1\xD2\xD3\xD4\xD5\xD6\xD8\xD9\xDA\xDB\xDC\xDD\xDE";
+function within2(char, set) {
+  return set.includes(char);
+}
+function* shlexIter(text, options) {
+  const posix = options.posix;
+  const punctuation = options.punctuationChars ?? "";
+  const whitespaceSplit = options.whitespaceSplit ?? false;
+  const commenters = options.commenters ?? "#";
+  let wordchars = ASCII_WORDCHARS + (posix ? POSIX_WORDCHARS : "");
+  if (punctuation) {
+    wordchars += "~-./*?=";
+    wordchars = [...wordchars].filter((char) => !punctuation.includes(char)).join("");
+  }
+  const whitespace = " 	\r\n";
+  const quotes = `'"`;
+  const escape = "\\";
+  const escapedquotes = '"';
+  const eof = posix ? null : "";
+  const chars = Array.from(text);
+  let cursor = 0;
+  const pushbackChars = [];
+  const pushback = [];
+  let state = " ";
+  let token = "";
+  const readChar = () => {
+    if (punctuation && pushbackChars.length > 0) return pushbackChars.pop();
+    if (cursor < chars.length) return chars[cursor++];
+    return "";
+  };
+  const skipLine = () => {
+    while (cursor < chars.length) {
+      const char = chars[cursor++];
+      if (char === "\n") break;
+    }
+  };
+  const readToken = () => {
+    let quoted = false;
+    let escapedstate = " ";
+    for (; ; ) {
+      const nextchar = readChar();
+      if (state === null) {
+        token = "";
+        break;
+      } else if (state === " ") {
+        if (!nextchar) {
+          state = null;
+          break;
+        } else if (within2(nextchar, whitespace)) {
+          if (token || posix && quoted) break;
+          continue;
+        } else if (within2(nextchar, commenters)) {
+          skipLine();
+        } else if (posix && within2(nextchar, escape)) {
+          escapedstate = "a";
+          state = nextchar;
+        } else if (within2(nextchar, wordchars)) {
+          token = nextchar;
+          state = "a";
+        } else if (within2(nextchar, punctuation)) {
+          token = nextchar;
+          state = "c";
+        } else if (within2(nextchar, quotes)) {
+          if (!posix) token = nextchar;
+          state = nextchar;
+        } else if (whitespaceSplit) {
+          token = nextchar;
+          state = "a";
+        } else {
+          token = nextchar;
+          if (token || posix && quoted) break;
+          continue;
+        }
+      } else if (within2(state, quotes)) {
+        quoted = true;
+        if (!nextchar) throw new ValidationError("No closing quotation");
+        if (nextchar === state) {
+          if (!posix) {
+            token += nextchar;
+            state = " ";
+            break;
+          }
+          state = "a";
+        } else if (posix && within2(nextchar, escape) && within2(state, escapedquotes)) {
+          escapedstate = state;
+          state = nextchar;
+        } else {
+          token += nextchar;
+        }
+      } else if (within2(state, escape)) {
+        if (!nextchar) throw new ValidationError("No escaped character");
+        if (within2(escapedstate, quotes) && nextchar !== state && nextchar !== escapedstate) {
+          token += state;
+        }
+        token += nextchar;
+        state = escapedstate;
+      } else if (state === "a" || state === "c") {
+        if (!nextchar) {
+          state = null;
+          break;
+        } else if (within2(nextchar, whitespace)) {
+          state = " ";
+          if (token || posix && quoted) break;
+          continue;
+        } else if (within2(nextchar, commenters)) {
+          skipLine();
+          if (posix) {
+            state = " ";
+            if (token || posix && quoted) break;
+            continue;
+          }
+        } else if (state === "c") {
+          if (within2(nextchar, punctuation)) {
+            token += nextchar;
+          } else {
+            if (!within2(nextchar, whitespace)) pushbackChars.push(nextchar);
+            state = " ";
+            break;
+          }
+        } else if (posix && within2(nextchar, quotes)) {
+          state = nextchar;
+        } else if (posix && within2(nextchar, escape)) {
+          escapedstate = "a";
+          state = nextchar;
+        } else if (within2(nextchar, wordchars) || within2(nextchar, quotes) || whitespaceSplit && !within2(nextchar, punctuation)) {
+          token += nextchar;
+        } else {
+          if (punctuation) pushbackChars.push(nextchar);
+          else pushback.unshift(nextchar);
+          state = " ";
+          if (token || posix && quoted) break;
+          continue;
+        }
+      }
+    }
+    const result = token;
+    token = "";
+    if (posix && !quoted && result === "") return null;
+    return result;
+  };
+  for (; ; ) {
+    const next = pushback.length > 0 ? pushback.shift() : readToken();
+    if (next === eof) return;
+    yield next;
+  }
+}
+
+// src/research/sandbox-validate.ts
+var READ_ONLY_TOOLS = [
+  "ls",
+  "find",
+  "grep",
+  "egrep",
+  "fgrep",
+  "rg",
+  "cat",
+  "head",
+  "tail",
+  "wc",
+  "sort",
+  "uniq",
+  "cut",
+  "tr",
+  "nl",
+  "file",
+  "stat",
+  "du",
+  "tree",
+  "basename",
+  "dirname",
+  "realpath",
+  "readlink",
+  "sed",
+  "jq",
+  "diff",
+  "cmp",
+  "column",
+  "xargs",
+  "git",
+  "tac",
+  "fold",
+  "paste",
+  "comm",
+  "od",
+  "strings",
+  "seq",
+  "expr"
+];
+var SAFE_BUILTINS = /* @__PURE__ */ new Set(["echo", "printf", "true", "false", "test", "[", "pwd"]);
+var READ_ONLY_GIT = /* @__PURE__ */ new Set([
+  "log",
+  "show",
+  "grep",
+  "ls-files",
+  "ls-tree",
+  "diff",
+  "blame",
+  "status",
+  "rev-parse",
+  "cat-file",
+  "shortlog",
+  "describe",
+  "rev-list",
+  "name-rev",
+  "annotate"
+]);
+var READ_ONLY_TOOL_SET = new Set(READ_ONLY_TOOLS);
+var FORBIDDEN_FLAGS = {
+  find: ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"],
+  sort: ["-o", "--output", "--compress-program", "--files0-from"],
+  wc: ["--files0-from"],
+  grep: ["-f", "--file"],
+  egrep: ["-f", "--file"],
+  fgrep: ["-f", "--file"],
+  rg: ["--pre", "--pre-glob", "--search-zip", "-z", "-f", "--file"],
+  tree: ["-o"],
+  file: ["-C", "--compile", "-f", "--files-from"],
+  jq: ["-f", "--from-file", "-L", "--library-path"],
+  git: ["-C", "-c", "--config-env", "--exec-path", "--output", "-o", "--ext-diff", "--textconv", "--open-files-in-pager", "-O"],
+  diff: ["--to-file"]
+};
+var SED_IN_PLACE = /^(?:-[a-zA-Z]*i|--in-place)/;
+var S = SPACE_CLASS;
+var W = "\\p{L}\\p{N}_";
+var HIDDEN_EXPANSION = /\$\(|`|<\(|>\(|\$'|\$\{|\$[A-Za-z_0-9@*#?!$-]/;
+var ALLOWED_STDERR_REDIRECT = new RegExp(`(?<![${W}>&])2>[${S}]*/dev/null|(?<![${W}>&])2>&1`, "gu");
+var HOME_ESCAPE = new RegExp(`(?:^|[${S}="'])(?:~|\\$HOME(?![${W}])|\\$\\{HOME\\})`, "u");
+var ABS_PATH = new RegExp(`(?:^|[${S}="'(:,])(/[^${S}"';|&)]*)`, "gu");
+var DOTDOT_PATH = new RegExp(`(?:^|[${S}="'/])\\.\\.(?:/|[${S}"']|$)`, "u");
+var FS_ABS_PREFIX = /^\/(?:etc|usr|home|Users|var|tmp|private|opt|root|System|Library|bin|sbin|dev|proc|sys|Applications|Volumes|mnt|media|srv|run|nix|snap)(?:\/|$)/;
+function outsideSingleQuotes(command) {
+  const out = [];
+  let quoted = false;
+  let escaped = false;
+  for (const char of command) {
+    if (quoted) {
+      quoted = char !== "'";
+      out.push(" ");
+      continue;
+    }
+    if (escaped) {
+      escaped = false;
+      out.push(" ");
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      out.push(" ");
+      continue;
+    }
+    if (char === "'") {
+      quoted = true;
+      out.push(out.length > 0 && out[out.length - 1] === "$" ? "'" : " ");
+      continue;
+    }
+    out.push(char);
+  }
+  return out.join("");
+}
+function assertCommandConfined(root, commandText) {
+  if (HOME_ESCAPE.test(commandText)) {
+    throw new ValidationError("command blocked: home-directory path is outside the workspace");
+  }
+  if (DOTDOT_PATH.test(commandText)) {
+    throw new ValidationError("command blocked: '..' walks outside the workspace");
+  }
+  const resolvedRoot = resolvePath(root);
+  for (const match of commandText.matchAll(ABS_PATH)) {
+    const raw = match[1];
+    let candidates;
+    if (hasGlobMagic(raw)) {
+      const matches = globPaths(raw).map(cleanPath);
+      if (matches.length === 0 && !raw.startsWith(resolvedRoot)) {
+        throw new ValidationError(`command blocked: path pattern escapes workspace: ${raw}`);
+      }
+      candidates = matches;
+    } else {
+      const candidate = cleanPath(raw);
+      if (FS_ABS_PREFIX.exec(raw) === null && !exists(candidate)) continue;
+      candidates = [candidate];
+    }
+    for (const candidate of candidates) {
+      if (escapesRoot(resolvePath(candidate), resolvedRoot)) {
+        throw new ValidationError(`command blocked: path escapes workspace: ${raw}`);
+      }
+    }
+  }
+}
+var OPERATOR_CHARS = new Set(";&|()<>");
+var SEPARATORS = /* @__PURE__ */ new Set(["|", "||", "&&", ";"]);
+function segments(commandText) {
+  const tokens = shlexIter(commandText, { posix: true, punctuationChars: ";&|()<>", whitespaceSplit: true, commenters: "" });
+  const result = [[]];
+  for (const token of tokens) {
+    if (SEPARATORS.has(token)) {
+      result.push([]);
+    } else if (token && [...token].every((char) => OPERATOR_CHARS.has(char))) {
+      if (token === "<") {
+        result[result.length - 1].push(token);
+        continue;
+      }
+      throw new ValidationError(
+        `command blocked: shell operator '${token}' is not allowed (read-only research: no output redirection, background jobs or subshells)`
+      );
+    } else {
+      result[result.length - 1].push(token);
+    }
+  }
+  return result.filter((segment) => segment.length > 0);
+}
+var inShortCluster = (arg, letters) => arg.startsWith("-") && !arg.startsWith("--") && arg.slice(1).includes(letters);
+function checkTool(words) {
+  if (words.length === 0) return;
+  const name = words[0];
+  const args = words.slice(1);
+  if (name.includes("/")) throw new ValidationError(`command blocked: run tools by name, not path: ${name}`);
+  if (SAFE_BUILTINS.has(name)) return;
+  if (!READ_ONLY_TOOL_SET.has(name)) {
+    throw new ValidationError(
+      `command blocked: '${name}' is not a read-only research tool (allowed: ${READ_ONLY_TOOLS.join(", ")})`
+    );
+  }
+  for (const flag of FORBIDDEN_FLAGS[name] ?? []) {
+    if (args.some((arg) => arg === flag || arg.startsWith(`${flag}=`) || flag.length === 2 && flag.startsWith("-") && inShortCluster(arg, flag[1]))) {
+      throw new ValidationError(`command blocked: \`${name} ${flag}\` loads external arguments, writes or executes`);
+    }
+  }
+  if (name === "sed") {
+    for (const arg of args) {
+      if (SED_IN_PLACE.test(arg)) throw new ValidationError("command blocked: sed -i edits files");
+    }
+    checkSed(args);
+  }
+  if (name === "git") {
+    const allowed = [...READ_ONLY_GIT].sort().join(", ");
+    const subcommand = args.find((arg) => !arg.startsWith("-"));
+    if (subcommand === void 0) {
+      throw new ValidationError(`command blocked: \`git\` needs a read-only subcommand (allowed: ${allowed})`);
+    }
+    if (!READ_ONLY_GIT.has(subcommand)) {
+      throw new ValidationError(`command blocked: \`git ${subcommand}\` is not read-only (allowed: ${allowed})`);
+    }
+  }
+  if (name === "xargs") {
+    if (args.some((arg) => arg === "--arg-file" || arg.startsWith("--arg-file=") || arg.startsWith("-a") && !arg.startsWith("--"))) {
+      throw new ValidationError("command blocked: xargs argument files cannot be confined");
+    }
+    const target = xargsCommand(args);
+    if (!["echo", "printf", "true", "false"].includes(target[0])) {
+      throw new ValidationError("command blocked: xargs filesystem arguments cannot be confined");
+    }
+    checkTool(target);
+  }
+}
+var XARGS_WITH_VALUE = /* @__PURE__ */ new Set(["-n", "-I", "-d", "-P", "-L", "-s", "-E", "-a", "--arg-file", "--delimiter", "--max-args", "--max-procs"]);
+function xargsCommand(args) {
+  let index = 0;
+  while (index < args.length && args[index].startsWith("-")) index += XARGS_WITH_VALUE.has(args[index]) ? 2 : 1;
+  const command = args.slice(index);
+  return command.length > 0 ? command : ["echo"];
+}
+var FOLLOW_FLAGS = { rg: "L", grep: "R", egrep: "R", fgrep: "R", find: "L", tree: "l", du: "L" };
+var SHELL_CONSTRUCTS = /* @__PURE__ */ new Set(["for", "while", "until", "if", "case", "function", "{", "eval", "exec", "source", "."]);
+function validateCommand(root, commandTextInput) {
+  if (!trimSpace(commandTextInput)) throw new ValidationError("empty shell command");
+  if (trimSpace(commandTextInput).includes("\n")) throw new ValidationError("command blocked: send one command line per turn");
+  const commandText = trimSpace(commandTextInput.replace(ALLOWED_STDERR_REDIRECT, " "));
+  if (HIDDEN_EXPANSION.test(outsideSingleQuotes(commandText))) {
+    throw new ValidationError(
+      "command blocked: command substitution, process substitution and $-expansion are not allowed; write paths and patterns literally"
+    );
+  }
+  for (const token of shlexIter(commandText, { posix: false, whitespaceSplit: true, commenters: "" })) {
+    if (token.startsWith("'") || token.startsWith('"') || token.startsWith("--exclude-dir=")) continue;
+    if (token.includes("{") || token.includes("}")) {
+      throw new ValidationError("command blocked: brace-expanded paths cannot be confined");
+    }
+  }
+  const resolvedRoot = () => resolvePath(root);
+  for (const segment of segments(commandText)) {
+    for (let word of segment.slice(1)) {
+      if (word.startsWith("--exclude-dir=")) continue;
+      if (word === "<") continue;
+      if (word.startsWith("-")) {
+        if (!word.includes("=")) continue;
+        word = word.slice(word.indexOf("=") + 1);
+      }
+      const candidate = joinPath(root, word);
+      const candidates = hasGlobMagic(word) ? globPaths(candidate).map(cleanPath) : [candidate];
+      for (const item of candidates) {
+        if ((exists(item) || isSymlink(item)) && escapesRoot(resolvePath(item), resolvedRoot())) {
+          throw new ValidationError("command blocked: relative path escapes workspace");
+        }
+      }
+    }
+    const tool = segment[0];
+    const followFlags = Object.hasOwn(FOLLOW_FLAGS, tool) ? FOLLOW_FLAGS[tool] : void 0;
+    if (followFlags && segment.slice(1).some((arg) => arg === "--follow" || arg === "--dereference" || arg === "--dereference-recursive" || inShortCluster(arg, followFlags))) {
+      throw new ValidationError("command blocked: recursive symlink following cannot be confined");
+    }
+    if (tool.includes("=") && !tool.startsWith("=")) {
+      throw new ValidationError("command blocked: variable assignment is not allowed");
+    }
+    if (SHELL_CONSTRUCTS.has(tool)) {
+      throw new ValidationError(`command blocked: shell construct '${tool}' is not allowed; use one pipeline`);
+    }
+    checkTool(segment.filter((word) => word !== "<"));
+  }
+  assertCommandConfined(root, commandText);
+  return commandText;
+}
+
+// src/research/sandbox.ts
+function macosProfile(workspace, scratch) {
+  const quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  return `(version 1)
+(allow default)
+(deny network*)
+(deny file-write*)
+(allow file-write* (literal "/dev/null") (literal "/dev/tty") (literal "/dev/dtracehelper") (subpath ${quote(scratch)}))
+(deny file-read-data (subpath "/Users") (subpath "/Volumes") (subpath "/private/var/root"))
+(allow file-read-data (subpath ${quote(workspace)}) (subpath ${quote(scratch)}))
+`;
+}
+function which(name, envPath = process.env.PATH) {
+  const searchPath = envPath ?? "/bin:/usr/bin";
+  if (!searchPath) return null;
+  const seen = /* @__PURE__ */ new Set();
+  for (const directory of searchPath.split(":")) {
+    if (seen.has(directory)) continue;
+    seen.add(directory);
+    const candidate = directory ? directory.endsWith("/") ? directory + name : `${directory}/${name}` : name;
+    try {
+      accessSync(candidate, fsConstants.X_OK);
+    } catch {
+      continue;
+    }
+    if (!isDir(candidate)) return candidate;
+  }
+  return null;
+}
+var KEPT_ENV = /* @__PURE__ */ new Set(["LANG", "LC_ALL", "LC_CTYPE", "TZ"]);
+var ReadOnlyShell = class {
+  workspace;
+  kind = "restricted-bash";
+  prefix = [];
+  env = {};
+  bash = "/bin/bash";
+  scratch = null;
+  constructor(workspace) {
+    this.workspace = workspace;
+  }
+  enter() {
+    this.workspace = resolvePath(this.workspace);
+    const scratch = mkdtempSync2(path4.join(path4.resolve(tmpdir2()), "freellama-shell-"));
+    this.scratch = scratch;
+    const binDir = path4.join(scratch, "bin");
+    mkdirSync3(binDir);
+    for (const tool of READ_ONLY_TOOLS) {
+      const located = which(tool);
+      if (located) symlinkSync(realpathSync(located), path4.join(binDir, tool));
+    }
+    this.bash = which("bash") ?? "/bin/bash";
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (KEPT_ENV.has(key) && value !== void 0) env[key] = value;
+    }
+    Object.assign(env, {
+      PATH: binDir,
+      HOME: this.workspace,
+      TMPDIR: scratch,
+      TERM: "dumb",
+      PAGER: "cat",
+      GIT_PAGER: "cat",
+      GIT_CONFIG_NOSYSTEM: "1",
+      GIT_CONFIG_GLOBAL: "/dev/null",
+      GIT_OPTIONAL_LOCKS: "0",
+      // `git status` otherwise rewrites the index
+      GIT_TERMINAL_PROMPT: "0"
+    });
+    this.env = env;
+    this.prefix = this.osSandbox(scratch, binDir);
+    return this;
+  }
+  close() {
+    if (this.scratch !== null) {
+      rmSync2(this.scratch, { recursive: true, force: true });
+      this.scratch = null;
+    }
+  }
+  osSandbox(scratch, binDir) {
+    if ((process.env.FREELLAMA_AGENT_OS_SANDBOX ?? "auto") === "off") return [];
+    const sandboxExec = which("sandbox-exec");
+    if (sandboxExec) {
+      const profile = path4.join(scratch, "profile.sb");
+      writeFileSync2(profile, macosProfile(this.workspace, scratch), "utf8");
+      const prefix = [sandboxExec, "-f", profile];
+      if (probe2([...prefix, this.bash, "-c", "true"], this.env)) {
+        this.kind = "sandbox-exec+restricted-bash";
+        return prefix;
+      }
+    }
+    const bwrap = which("bwrap");
+    if (bwrap) {
+      const prefix = [bwrap, "--unshare-all", "--die-with-parent", "--new-session", "--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp"];
+      for (const systemDir of ["/usr", "/bin", "/sbin", "/lib", "/lib32", "/lib64", "/etc/alternatives", "/etc/ld.so.cache", "/etc/localtime", "/nix/store"]) {
+        prefix.push("--ro-bind-try", systemDir, systemDir);
+      }
+      prefix.push(
+        "--ro-bind",
+        this.workspace,
+        this.workspace,
+        "--ro-bind",
+        binDir,
+        binDir,
+        "--bind",
+        scratch,
+        scratch,
+        "--chdir",
+        this.workspace,
+        "--"
+      );
+      if (probe2([...prefix, this.bash, "-c", "true"], this.env)) {
+        this.kind = "bwrap+restricted-bash";
+        return prefix;
+      }
+    }
+    return [];
+  }
+  async run(commandText, timeoutSeconds) {
+    const command = validateCommand(this.workspace, commandText);
+    const result = await runProcess(
+      [...this.prefix, this.bash, "--restricted", "--noprofile", "--norc", "-c", command],
+      { cwd: this.workspace, env: this.env, timeoutSeconds }
+    );
+    let output = result.stdout + result.stderr;
+    if (!trimSpace(output)) output = `(no output, exit code ${result.returncode})`;
+    return output;
+  }
+};
+
+// src/research/bash-agent.ts
+function parseAction(content) {
+  const value = parseJsonAction(content);
+  const action = value.action;
+  if (action === "shell") {
+    const command = value.command;
+    if (typeof command !== "string" || !trimSpace(command)) throw new ValidationError("shell action requires a non-empty string command");
+  }
+  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 !== "shell" && action !== "page" && action !== "finish") {
+    throw new ValidationError(`unsupported action for bash adapter: ${String(action)}`);
+  }
+  return value;
+}
+async function runShell(root, commandText, timeoutSeconds, shell) {
+  if (shell) return shell.run(commandText, timeoutSeconds);
+  const scoped = new ReadOnlyShell(root).enter();
+  try {
+    return await scoped.run(commandText, timeoutSeconds);
+  } finally {
+    scoped.close();
+  }
+}
+var BASH_ADAPTER = {
+  defaultToolTimeoutSeconds: 30,
+  systemPrompt: () => BASH_SYSTEM_PROMPT,
+  parseAction,
+  open: (workspace) => {
+    const shell = new ReadOnlyShell(workspace).enter();
+    return {
+      shell,
+      toolCall: (action, _workspace, runtime) => {
+        const commandText = String(action.command ?? "");
+        return {
+          signature: { command: commandText },
+          run: () => shell.run(commandText, runtime.tool_timeout_seconds),
+          record: { name: "shell", raw_name: action.action ?? "", arguments: { command: commandText } },
+          ledger: (status) => ({ action: "shell", status, source: commandText })
+        };
+      },
+      close: () => shell.close()
+    };
+  },
+  remaining: (count) => `
+
+Commands remaining: ${count}. Finish now if the task is answerable; do not repeat prior commands.`,
+  exhausted: "Command budget is exhausted. Return exactly a finish JSON action now using the evidence collected. Do not request another command.",
+  adapterMetadata: (session) => ({
+    adapter: "bash_shell_agent_v1",
+    sandbox: session?.shell?.kind ?? "restricted-bash"
+  })
+};
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await runAdapter(BASH_ADAPTER);
+}
+export {
+  BASH_ADAPTER,
+  assertCommandConfined,
+  parseAction,
+  runShell
+};