ravensight-playtest 0.1.0

package/src/run/profile.js

@@ -0,0 +1,214 @@
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { callStepWithRetry, STEPS } from './model.js';
+import { JOB_FILES } from './paths.js';
+import { parseJsonObject } from './json.js';
+import { createRepoTools, PROFILE_TOOLS, READ_ONLY_TOOLS } from './repoTools.js';
+import { assertNoSecrets } from './secretScan.js';
+
+/**
+ * The `game_profile` module: read the developer's repository and answer what
+ * Ravensight Playtest can and cannot do for this game, before they spend
+ * money on a run.
+ *
+ * Two steps, because they are priced and tooled differently:
+ *
+ * - `game_profile.triage` (cheap tier, `read_file` / `glob` / `grep`) walks
+ *   the repository and gathers facts. This is the loop, and it is where
+ *   nearly all the turns go.
+ * - `game_profile.synthesis` (frontier tier, `read_file` only) turns those
+ *   facts into `capability-report.json`.
+ *
+ * Neither step has a `write_file` tool, so the report comes back as text and
+ * is parsed here. That is the routing table's decision, not a shortcut:
+ * profiling reads a repository, and a step that can read a repository is the
+ * last one that should also be able to write to it.
+ *
+ * The source never leaves the machine. What goes over the wire is whatever
+ * the model quotes into its own reasoning, which is why ./repoTools.js
+ * withholds any file that trips the secret scan rather than trusting the
+ * prompt's "never read .env".
+ */
+
+/** Turns the triage loop may spend before it has to synthesise with what it has. */
+export const MAX_TRIAGE_TURNS = 40;
+
+export const TRIAGE_MAX_TOKENS = 1024;
+export const SYNTHESIS_MAX_TOKENS = 4096;
+
+/**
+ * @param {Array<{name: string, content: Object}>} schemas
+ */
+export function createCapabilityValidator(schemas) {
+  const entry = (schemas || []).find(schema => schema.name === 'capability-report');
+  if (!entry) throw new Error('the content pack has no capability-report schema; run a pack sync');
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const compiled = ajv.compile(entry.content);
+  return {
+    validate(report) {
+      const ok = compiled(report);
+      return {
+        ok: Boolean(ok),
+        details: (compiled.errors || []).map(error => ({
+          instancePath: error.instancePath || `/${(error.params && (error.params.missingProperty || error.params.additionalProperty)) || ''}`,
+          message: error.message
+        }))
+      };
+    }
+  };
+}
+
+/**
+ * @param {Object} args
+ * @returns {Promise<{report: Object, lint: Array<string>, turns: number}>}
+ */
+export async function runGameProfile({
+  client,
+  jobId,
+  runId,
+  repoRoot,
+  skill,
+  schemas,
+  codeBrief = null,
+  brief = null,
+  engine = null,
+  commit = null,
+  dirty = false,
+  ledger = null,
+  log = () => {},
+  onProgress = () => {},
+  maxTriageTurns = MAX_TRIAGE_TURNS
+}) {
+  const validator = createCapabilityValidator(schemas);
+  const repo = createRepoTools({ root: repoRoot, tools: PROFILE_TOOLS });
+  const system = [
+    { type: 'text', text: skill },
+    {
+      type: 'text',
+      text: [
+        `job_id: ${jobId}`,
+        `repository root: the paths you read are relative to it; never absolute`,
+        `engine recorded on this game: ${engine || 'unknown'}`,
+        `commit: ${commit || 'unknown'}${dirty ? ' (working tree is dirty)' : ''}`,
+        codeBrief ? `<code_brief>\n${JSON.stringify(codeBrief).slice(0, 4000)}\n</code_brief>` : '<code_brief>null</code_brief>',
+        // The brief, when the game already has one. A profile is often the
+        // first thing a developer runs, in which case there is none, which is
+        // why it is optional rather than required.
+        brief ? `<expectations_brief>\n${JSON.stringify({ version: brief.version ?? null, ...(brief.fields || {}) }, null, 2).slice(0, 4000)}\n</expectations_brief>` : '<expectations_brief>null</expectations_brief>'
+      ].join('\n'),
+      cache_control: { type: 'ephemeral' }
+    }
+  ];
+
+  const messages = [{
+    role: 'user',
+    content: [{
+      type: 'text',
+      text: 'Profile this repository. Work through the procedure in order and read only what you need. When you have the facts you need, stop calling tools and say so in one line: the next step writes the report.'
+    }]
+  }];
+
+  let turns = 0;
+  while (turns < maxTriageTurns) {
+    turns += 1;
+    const answer = await callStepWithRetry({
+      client,
+      jobId,
+      runId,
+      step: STEPS.profileTriage,
+      system,
+      messages,
+      tools: repo.tools,
+      maxTokens: TRIAGE_MAX_TOKENS
+    });
+    if (ledger) ledger.record({ model: answer.model, usage: answer.usage });
+    if (answer.budget === 'warn') log('budget warning: the profile has used at least 80 percent of its model budget. Synthesising now.');
+
+    if (answer.toolUses.length === 0) {
+      messages.push({ role: 'assistant', content: [{ type: 'text', text: answer.text || '(done)' }] });
+      break;
+    }
+
+    messages.push({
+      role: 'assistant',
+      content: [
+        ...(answer.text.trim() ? [{ type: 'text', text: answer.text }] : []),
+        ...answer.toolUses.map(toolUse => ({ type: 'tool_use', id: toolUse.id, name: toolUse.name, input: toolUse.malformed ? {} : toolUse.input }))
+      ]
+    });
+    const results = [];
+    for (const toolUse of answer.toolUses) {
+      const executed = await repo.execute(toolUse);
+      results.push(executed.result);
+      onProgress({ phase: 'triage', turn: turns, tool: toolUse.name, target: toolUse.input && (toolUse.input.path || toolUse.input.pattern) });
+    }
+    messages.push({ role: 'user', content: results });
+    if (answer.budget === 'warn') break;
+  }
+
+  messages.push({
+    role: 'user',
+    content: [{
+      type: 'text',
+      text: 'Now write the capability report. Answer with the JSON object only, nothing before or after it. Underpromise: every eligible row needs a concrete reason taken from a file you actually read.'
+    }]
+  });
+
+  let report = null;
+  let lint = [];
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    const answer = await callStepWithRetry({
+      client,
+      jobId,
+      runId,
+      step: STEPS.profileSynthesis,
+      system,
+      messages,
+      tools: READ_ONLY_TOOLS,
+      maxTokens: SYNTHESIS_MAX_TOKENS
+    });
+    if (ledger) ledger.record({ model: answer.model, usage: answer.usage });
+
+    const parsed = parseJsonObject(answer.text);
+    const candidate = parsed ? { ...parsed, schema_version: parsed.schema_version || '1.0', job_id: jobId } : null;
+    const validation = candidate
+      ? validator.validate(candidate)
+      : { ok: false, details: [{ instancePath: '/', message: 'the answer was not a JSON object' }] };
+
+    if (validation.ok) {
+      report = candidate;
+      lint = [];
+      break;
+    }
+    lint = validation.details.map(detail => `${detail.instancePath}: ${detail.message}`);
+    if (attempt === 2) throw new Error(`the capability report did not validate after one repair: ${lint.join('; ')}`);
+
+    messages.push({ role: 'assistant', content: [{ type: 'text', text: answer.text.slice(0, 2000) }] });
+    messages.push({
+      role: 'user',
+      content: [{ type: 'text', text: `That did not match capability-report.schema.json. Fix exactly these and answer with the JSON only:\n${lint.join('\n')}` }]
+    });
+  }
+
+  return { report, lint, turns };
+}
+
+/**
+ * @param {string} jobDirectory
+ * @param {Object} report
+ * @returns {Promise<string>}
+ */
+export async function writeCapabilityReport(jobDirectory, report) {
+  const body = `${JSON.stringify(report, null, 2)}\n`;
+  assertNoSecrets('capability-report.json', body);
+  const target = path.join(jobDirectory, JOB_FILES.capabilityReport);
+  await writeFile(target, body, 'utf8');
+  return target;
+}
+
+export { parseJsonObject };
+
+export default { runGameProfile, writeCapabilityReport, createCapabilityValidator, parseJsonObject };

package/src/run/regenerate.js

@@ -0,0 +1,149 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { RUN_FILES } from './paths.js';
+
+/**
+ * Rebuilding a report from what a run already wrote down, with the game not
+ * running and no model turn spent.
+ *
+ * This is the point of the transcript. A run that got a long way in and then
+ * lost its heartbeat has real observations, real notes and real screenshots on
+ * disk; replaying it from the start throws all of that away, spends the action
+ * budget again, and gets a different playthrough (live game state cannot be
+ * restored, so it is not even the same run). Past a few actions, finalising
+ * what happened is worth more than starting over.
+ *
+ * What comes out is deliberately modest: a schema-valid `report.json` with no
+ * findings and a `report.md` carrying the notes. It invents no sentiment scores
+ * and no verdicts, because nobody gave any. The narrative and the findings are
+ * a model's job, and this path exists precisely because there is no model turn
+ * to spend on it.
+ */
+
+/** How far a run has to have got before finalising beats replaying it. */
+export const PARTIAL_CHECKPOINT_FLOOR = 5;
+
+/**
+ * Whether this journal entry is worth finalising rather than replaying.
+ *
+ * @param {Object} entry a journal run entry
+ * @param {{restartInterrupted?: boolean}} [options]
+ * @returns {boolean}
+ */
+export function shouldFinalize(entry, options = {}) {
+  if (options.restartInterrupted) return false;
+  if (!entry) return false;
+  return Number(entry.checkpoint_step || 0) >= PARTIAL_CHECKPOINT_FLOOR;
+}
+
+/**
+ * Read back what a run recorded.
+ *
+ * @param {string} runDirectory
+ * @returns {Promise<{header: Object|null, notes: Array, screenshots: Array, observations: number, actions: number}>}
+ */
+export async function readTranscript(runDirectory) {
+  let text = '';
+  try {
+    text = await readFile(path.join(runDirectory, RUN_FILES.transcript), 'utf8');
+  } catch {
+    return { header: null, notes: [], screenshots: [], observations: 0, actions: 0 };
+  }
+
+  let header = null;
+  const notes = [];
+  const screenshots = [];
+  let observations = 0;
+  let actions = 0;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      // A half written last line is what a killed process leaves behind. Skip
+      // it rather than refusing to read the whole transcript.
+      continue;
+    }
+    if (entry.kind === 'header') header = entry;
+    else if (entry.kind === 'note' && entry.note) notes.push(entry.note);
+    else if (entry.kind === 'screenshot' && entry.path) screenshots.push({ relativePath: entry.path, reason: entry.reason || '' });
+    else if (entry.kind === 'observation') observations += 1;
+    else if (entry.kind === 'action' && Number.isFinite(Number(entry.actions))) actions = Math.max(actions, Number(entry.actions));
+  }
+  return { header, notes, screenshots, observations, actions };
+}
+
+/**
+ * A schema-valid partial report built from a transcript.
+ *
+ * @param {Object} args
+ * @returns {{report: Object, markdown: string, actions: number}}
+ */
+export function buildPartialReport({ runId, jobId, persona, driver, target, transcript, promptVersion, usage }) {
+  const started = transcript.header && transcript.header.t ? new Date(transcript.header.t).toISOString() : new Date().toISOString();
+  const report = {
+    schema_version: '1.0',
+    run_id: runId,
+    job_id: jobId,
+    prompt_version: (transcript.header && transcript.header.prompt_version) || promptVersion || 'persona-playtest@0.1.0',
+    persona,
+    driver,
+    target,
+    started_at: started,
+    ended_at: new Date().toISOString(),
+    actions_taken: transcript.actions,
+    quit_reason: 'error',
+    quit_detail: 'the run was interrupted; this report was rebuilt from its transcript without replaying the game',
+    // No findings: a finding needs a judgement, and there was no model turn to
+    // make one. The notes are in the markdown so nothing is lost.
+    findings: [],
+    // Neutral rather than invented. The persona never gave a verdict, and a
+    // made-up 3 is still a made-up number; the markdown says so in words.
+    sentiment: { fun: 3, clarity: 3, frustration: 3 },
+    would_continue: false,
+    usage
+  };
+  return { report, markdown: renderPartialMarkdown({ persona, driver, target, transcript }), actions: transcript.actions };
+}
+
+/**
+ * The markdown, carrying the four headings the server lints for.
+ *
+ * @param {Object} args
+ * @returns {string}
+ */
+export function renderPartialMarkdown({ persona, driver, target, transcript }) {
+  const good = transcript.notes.filter(note => note.kind === 'good');
+  const bad = transcript.notes.filter(note => note.kind === 'bug' || note.kind === 'confusing');
+  const list = entries => (entries.length > 0
+    ? entries.map(note => `- **${note.kind}${note.severity ? `/${note.severity}` : ''}**: ${note.text}`).join('\n')
+    : '- Nothing was logged.');
+
+  return [
+    `# Playtest: ${persona} (rebuilt from transcript)`,
+    `**Driver:** ${driver} - **Target:** ${target}`,
+    `**Session length:** ${transcript.actions} actions over ${transcript.observations} observations, then interrupted`,
+    '',
+    '## Why this report is partial',
+    'The run was interrupted before it could write a report. This was rebuilt from its transcript with the game not running, so it carries what the persona saw and noted but no narrative and no scored findings: nobody was there to judge them.',
+    '',
+    '## What worked',
+    list(good),
+    '',
+    '## Top issues',
+    list(bad),
+    '',
+    "## What this run didn't cover",
+    `Everything after action ${transcript.actions}. No persona verdict was recorded, so the sentiment scores in report.json are placeholders rather than judgements.`,
+    '',
+    '## Suggested next step',
+    'Re-run this persona to get a full report, or pass --restart-interrupted to replay it now.',
+    '',
+    '## Evidence',
+    transcript.screenshots.length > 0 ? transcript.screenshots.map(shot => `- ${shot.relativePath}`).join('\n') : '- (none)',
+    ''
+  ].join('\n');
+}
+
+export default { shouldFinalize, readTranscript, buildPartialReport, renderPartialMarkdown, PARTIAL_CHECKPOINT_FLOOR };

package/src/run/repoTools.js

@@ -0,0 +1,286 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { scanForSecrets } from './secretScan.js';
+
+/**
+ * The read-only source tools for `game_profile`: `read_file`, `glob` and
+ * `grep`, which are exactly the three names
+ * `routing.json`'s `game_profile.triage` allows (and `read_file` alone on
+ * `game_profile.synthesis` and `aggregate.synthesis`).
+ *
+ * Read-only is enforced here, not asked for in a prompt. There is no write,
+ * no shell, no network, and:
+ *
+ * - every path is resolved and refused if it leaves the root, so `../../`
+ *   and a symlink out of the tree both fail;
+ * - `.env*`, key material and credential stores are refused by name,
+ *   because "never read .env" is a rule the model should not be the last
+ *   line of defence for;
+ * - anything whose content trips the secret scan comes back as a count of
+ *   shapes instead of the content, so a key in a checked-in config never
+ *   reaches the model and therefore can never be quoted into a report. Spec
+ *   02 asks for a warning without the value; this is that, enforced.
+ *
+ * Vendored directories are skipped, which is both a cost and a quality
+ * decision: `node_modules` is not the developer's game, and profiling it
+ * would spend the triage budget on somebody else's code.
+ */
+
+/** Directories never walked. */
+export const SKIP_DIRS = Object.freeze([
+  '.git', '.godot', '.ravensight', 'node_modules', 'dist', 'build', 'out',
+  'Library', 'Temp', 'Logs', 'obj', 'bin', 'ThirdParty', 'godot-cpp',
+  '.venv', 'venv', '__pycache__', '.next', '.cache', 'coverage'
+]);
+
+/** Files never read, whatever asks for them. */
+export const SECRET_FILE_PATTERNS = Object.freeze([
+  /(^|\/)\.env($|\.)/i,
+  /(^|\/)\.npmrc$/i,
+  /(^|\/)id_(rsa|dsa|ecdsa|ed25519)$/i,
+  /(^|\/)credentials$/i,
+  /\.(pem|key|p12|pfx|keystore|jks)$/i
+]);
+
+/** How much of one file a single read returns. */
+export const MAX_READ_BYTES = 120000;
+
+/** How many paths a glob answers with. */
+export const MAX_GLOB_RESULTS = 400;
+
+/** How many matching lines a grep answers with. */
+export const MAX_GREP_RESULTS = 200;
+
+/** The tool definitions for `game_profile.triage`. */
+export const PROFILE_TOOLS = Object.freeze([
+  {
+    name: 'read_file',
+    description: 'Read a text file from the repository. Paths are relative to the repository root. Read-only.',
+    input_schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: { type: 'string' },
+        start_line: { type: 'integer', minimum: 1 },
+        limit: { type: 'integer', minimum: 1, maximum: 2000 }
+      }
+    }
+  },
+  {
+    name: 'glob',
+    description: 'List repository paths matching a glob such as **/*.gd or project.godot. Vendored directories are skipped.',
+    input_schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['pattern'],
+      properties: { pattern: { type: 'string' } }
+    }
+  },
+  {
+    name: 'grep',
+    description: 'Search the repository for a regular expression. Answers path, line number and the matching line.',
+    input_schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['pattern'],
+      properties: {
+        pattern: { type: 'string' },
+        glob: { type: 'string', description: 'restrict to paths matching this glob' }
+      }
+    }
+  }
+]);
+
+/** The subset allowed on the synthesis steps. */
+export const READ_ONLY_TOOLS = Object.freeze(PROFILE_TOOLS.filter(tool => tool.name === 'read_file'));
+
+/**
+ * Compile a glob into a regular expression. Supports `**`, `*` and `?`,
+ * which covers every pattern the profile skill actually asks for
+ * (`project.godot`, `**\/*.gd`, `src/**`) without taking on a dependency.
+ *
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+export function globToRegExp(pattern) {
+  let source = '';
+  const value = String(pattern);
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (char === '*') {
+      if (value[i + 1] === '*') {
+        // `**/` matches zero or more directories, so `**/x` also matches a
+        // bare `x` at the root.
+        if (value[i + 2] === '/') {
+          source += '(?:.*/)?';
+          i += 2;
+        } else {
+          source += '.*';
+          i += 1;
+        }
+      } else {
+        source += '[^/]*';
+      }
+      continue;
+    }
+    if (char === '?') {
+      source += '[^/]';
+      continue;
+    }
+    source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * @param {string} relativePath
+ * @returns {boolean}
+ */
+export function isSecretPath(relativePath) {
+  const normalized = String(relativePath).split(path.sep).join('/');
+  return SECRET_FILE_PATTERNS.some(pattern => pattern.test(normalized));
+}
+
+/**
+ * Resolve a model-supplied path against the root, refusing anything that
+ * escapes it.
+ *
+ * @param {string} root
+ * @param {string} candidate
+ * @returns {string} an absolute path
+ */
+export function resolveInside(root, candidate) {
+  const base = path.resolve(root);
+  const target = path.resolve(base, String(candidate));
+  if (target !== base && !target.startsWith(base + path.sep)) {
+    throw new Error(`${candidate} is outside the repository`);
+  }
+  return target;
+}
+
+/**
+ * @param {string} root
+ * @param {Object} [opts]
+ * @returns {Promise<Array<string>>} repository-relative paths
+ */
+export async function listFiles(root, { limit = 20000 } = {}) {
+  const out = [];
+  /** @param {string} dir */
+  async function walk(dir) {
+    if (out.length >= limit) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (out.length >= limit) return;
+      if (entry.isSymbolicLink()) continue;
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.includes(entry.name)) continue;
+        await walk(absolute);
+        continue;
+      }
+      const relative = path.relative(root, absolute).split(path.sep).join('/');
+      if (isSecretPath(relative)) continue;
+      out.push(relative);
+    }
+  }
+  await walk(path.resolve(root));
+  return out.sort();
+}
+
+/**
+ * @param {Object} args
+ * @param {string} args.root the repository root
+ * @returns {{tools: Array, execute: (toolUse: Object) => Promise<{result: Object}>}}
+ */
+export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
+  let cachedFiles = null;
+
+  async function files() {
+    if (!cachedFiles) cachedFiles = await listFiles(root);
+    return cachedFiles;
+  }
+
+  return {
+    tools,
+
+    /**
+     * @param {Object} toolUse
+     */
+    async execute(toolUse) {
+      const input = toolUse.input || {};
+      try {
+        if (toolUse.name === 'read_file') return { result: ok(toolUse.id, await doRead(root, input)) };
+        if (toolUse.name === 'glob') {
+          const matcher = globToRegExp(input.pattern);
+          const matched = (await files()).filter(file => matcher.test(file)).slice(0, MAX_GLOB_RESULTS);
+          return { result: ok(toolUse.id, matched.length > 0 ? matched.join('\n') : '(no matches)') };
+        }
+        if (toolUse.name === 'grep') return { result: ok(toolUse.id, await doGrep(root, await files(), input)) };
+        return { result: ok(toolUse.id, `There is no tool called ${toolUse.name}.`, true) };
+      } catch (error) {
+        return { result: ok(toolUse.id, String(error && error.message ? error.message : error), true) };
+      }
+    }
+  };
+}
+
+async function doRead(root, input) {
+  const relative = String(input.path || '');
+  if (isSecretPath(relative)) {
+    return `Refused: ${relative} is a credential file and is never read. Note in warnings that credentials are checked into the repository, without quoting anything.`;
+  }
+  const absolute = resolveInside(root, relative);
+  const info = await stat(absolute);
+  if (!info.isFile()) throw new Error(`${relative} is not a file`);
+  const text = await readFile(absolute, 'utf8');
+  const secrets = scanForSecrets(text);
+  if (secrets.length > 0) {
+    // The content is withheld rather than redacted: a partial redaction of
+    // an unknown format is a guess, and the shapes are what the warning
+    // needs anyway.
+    return `Withheld: ${relative} contains ${secrets.map(s => `${s.type} (${s.count})`).join(', ')}. Record a warning that this file holds secret shaped strings. Do not quote it and do not ask for it again.`;
+  }
+  const lines = text.split('\n');
+  const start = Math.max(1, Number(input.start_line) || 1);
+  const limit = Number(input.limit) || lines.length;
+  const slice = lines.slice(start - 1, start - 1 + limit).join('\n');
+  return slice.length > MAX_READ_BYTES ? `${slice.slice(0, MAX_READ_BYTES)}\n... [truncated]` : slice;
+}
+
+async function doGrep(root, all, input) {
+  const regex = new RegExp(String(input.pattern), 'i');
+  const matcher = input.glob ? globToRegExp(input.glob) : null;
+  const hits = [];
+  for (const relative of all) {
+    if (hits.length >= MAX_GREP_RESULTS) break;
+    if (matcher && !matcher.test(relative)) continue;
+    let text;
+    try {
+      const info = await stat(path.join(root, relative));
+      if (info.size > MAX_READ_BYTES) continue;
+      text = await readFile(path.join(root, relative), 'utf8');
+    } catch {
+      continue;
+    }
+    // A file with secrets in it is not searched either: a grep result is a
+    // quoted line, and a quoted line from such a file is the leak.
+    if (scanForSecrets(text).length > 0) continue;
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length && hits.length < MAX_GREP_RESULTS; i += 1) {
+      if (regex.test(lines[i])) hits.push(`${relative}:${i + 1}: ${lines[i].trim().slice(0, 300)}`);
+    }
+  }
+  return hits.length > 0 ? hits.join('\n') : '(no matches)';
+}
+
+function ok(id, text, isError = false) {
+  return { type: 'tool_result', tool_use_id: id, content: [{ type: 'text', text }], ...(isError ? { is_error: true } : {}) };
+}
+
+export default { createRepoTools, PROFILE_TOOLS, READ_ONLY_TOOLS, globToRegExp, listFiles, resolveInside, isSecretPath };