@juliangruber/harness 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julian Gruber <mail@juliangruber.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# harness
+
+A general purpose agent harness: it answers questions, does research and writes code. Talks to any OpenAI compatible `/v1/chat/completions` API (Ollama, llama.cpp, vLLM, LM Studio, OpenRouter, ...) and gives the model the tools OpenCode and Pi converged on: `read`, `write`, `edit`, `glob`, `grep` and `bash`.
+
+Its research is fair: it only uses sources that don't rely on ads, like Wikipedia, Wikidata and open scholarly databases, so agent traffic doesn't take income away from sites that need human visitors.
+
+The `bash` tool runs whatever the model asks for, with your permissions. Run it in a container (see [juliangruber/agent](https://github.com/juliangruber/agent)) if that worries you.
+
+## Install
+
+Requires Node 22.17+ or 24.1+.
+
+```console
+$ npx @juliangruber/harness "what files are in this directory?"
+```
+
+Or install it globally, as the `harness` command:
+
+```console
+$ npm install -g @juliangruber/harness
+```
+
+## Usage
+
+```console
+$ npx @juliangruber/harness "what files are in this directory?"
+$ npx @juliangruber/harness   # interactive session
+$ npx @juliangruber/harness --debug "hi"   # also log system prompt, tools and all messages to stderr
+$ npx @juliangruber/harness --trust "hi"   # use AGENTS.md / CLAUDE.md without asking
+$ npx @juliangruber/harness --unsafe "hi"   # no bash checks, no working directory limit, for containers
+```
+
+If the working directory contains `AGENTS.md`, `AGENT.md` or `CLAUDE.md` (first match wins), the harness shows a preview and asks whether to use it, every time. Without a terminal to ask in, the file is ignored with a warning unless `--trust` is passed.
+
+Answers go to stdout, rendered from markdown. Tool calls are logged to stderr.
+
+Before a `bash` command runs, a separate model call checks two things at once: whether the other tools could do the same, and whether the command is safe to run. If the other tools could do it, the command is refused and the model is told which tools to use. Unsafe commands are refused too: ones that could delete files outside the working directory, change the system, touch secrets, send data out, push or publish, or keep running in the background. If the check can't decide, the command is refused. Allowed commands print the reason as a yellow warning, since it often points at a tool worth adding. The check is a model's judgment, not a security boundary.
+
+The file tools (`read`, `write`, `edit`, `ls`, `glob`, `grep`) only access files inside the working directory, and follow symlinks to check where they really point. When running in a container, `--unsafe` skips the bash check and lifts this limit.
+
+Tools the model asks for but doesn't have are printed in red after the answer, as a TODO list of tools to add. A made up name that resembles an existing tool, like `search_paper_query` for `search_papers`, is a naming problem instead: the model gets a "Did you mean" hint and a yellow warning is printed. Tools that are missing on purpose, fetching arbitrary web pages and searching the web, are listed in the system prompt so the model doesn't ask for them.
+
+| Env var          | Default                     |
+| ---------------- | --------------------------- |
+| `AGENT_MODEL`    | `qwen3.8`                   |
+| `AGENT_BASE_URL` | `http://localhost:11434/v1` |
+| `AGENT_API_KEY`  | none                        |
+| `AGENT_RESEARCH_MODEL` | `AGENT_MODEL`, also used by the docs agent |
+| `AGENT_CONTACT`  | none, sent in the User-Agent to research sources and MCP servers if set |
+
+## Tools
+
+### Main agent
+
+| Tool | What it does |
+| ---- | ------------ |
+| `read` | Read a text file, optionally a range of lines |
+| `write` | Write a file, creating parent directories |
+| `edit` | Replace an exact string in a file |
+| `ls` | List a directory, like `ls -la`: hidden files included, directories end with `/`, files show their size |
+| `glob` | Find files by glob pattern, or list a directory with `*`. Includes hidden files, directories end with `/`, files show their size. Doesn't look inside `node_modules` and `.git` |
+| `grep` | Search file contents with a regular expression |
+| `bash` | Run a shell command, if checks find the other tools can't do the same and the command is safe |
+| `research` | Ask the [research agent](#research) a question |
+| `docs` | Ask the [docs agent](#docs) about software libraries and APIs |
+
+### Research agent
+
+| Tool | What it does |
+| ---- | ------------ |
+| `wikipedia_search` | Search Wikipedia articles |
+| `wikipedia_article` | Read the text of a Wikipedia article |
+| `wikidata_search` | Search Wikidata entities |
+| `wikidata_entity` | Facts Wikidata has about an entity |
+| `search_papers` | Search all paper sources below at once, merging duplicates |
+| `search_openalex` | Search scholarly works across all fields |
+| `search_semantic_scholar` | Search papers, strong in computer science and biomedicine |
+| `search_crossref` | Search publication metadata |
+| `search_europe_pmc` | Search biomedical and life science literature |
+| `search_arxiv` | Search preprints, often rate limited |
+| `wolfram_alpha` | Compute answers to maths questions with Wolfram Alpha, through Wolfram's MCP server. Only used for maths |
+
+Paper tools return abstracts, not full papers.
+
+### Docs agent
+
+Tools come from remote MCP servers and are loaded when the agent first runs.
+
+| Tool | What it does |
+| ---- | ------------ |
+| `deepwiki_read_wiki_structure` | List the documentation topics DeepWiki has for a GitHub repository |
+| `deepwiki_read_wiki_contents` | Read DeepWiki's documentation for a GitHub repository |
+| `deepwiki_ask_question` | Ask DeepWiki a question about a GitHub repository |
+| `context7_resolve-library-id` | Find a library's Context7 id |
+| `context7_query-docs` | Get current documentation and code examples for a library |
+| `microsoft_docs_search` | Search Microsoft Learn documentation |
+| `microsoft_code_sample_search` | Search Microsoft Learn code samples |
+| `microsoft_docs_fetch` | Read a Microsoft Learn page |
+
+## Research
+
+The `research` tool hands a question to a separate agent, so search results don't fill up the main conversation. It only uses sources whose income doesn't depend on human visitors, through their official keyless APIs. Wolfram|Alpha, funded by subscriptions and paid APIs rather than ads, is reached through Wolfram's MCP server, which is free for limited personal use. Only its `WolframAlpha` tool is used, only for maths questions, and Wolfram's server is only contacted when the research agent actually calls it. Running Wolfram Language code on Wolfram's servers is left out.
+
+The harness doesn't search the web itself. When a regular web search would help, the answer ends with suggested web searches for you to run, and your visit goes to the sites that need it. Sources and suggested searches from research are always added to the final answer, even if the model leaves them out, and they're highlighted.
+
+Requests are rate limited per host: `Retry-After` on 429/503 pauses a host (60s if missing), so do timeouts and network errors (60s), a used up `x-ratelimit-remaining` budget pauses it until `x-ratelimit-reset`, and `x-rate-limit-limit`/`-interval` space requests out. arXiv and Semantic Scholar get fixed spacing. Paused sources fail right away, so the model moves on. Without a key, OpenAlex allows roughly 100 searches a day; a warning is printed when it runs low.
+
+Ollama's `/v1` endpoint can't set the context size per request and the default is small. Raise it on the server, e.g. `OLLAMA_CONTEXT_LENGTH=32768 ollama serve`.
+
+## Docs
+
+The `docs` tool hands a question about software to a separate agent, which reads documentation from remote [MCP](https://modelcontextprotocol.io) servers that need no account: DeepWiki, Context7 and Microsoft Learn. Each server is reviewed for fairness first: its operator offers documentation to agents and doesn't earn from ads on it. The list of MCP servers for the docs and research agents, with the reasoning for each and the servers left out, is in `src/mcp-servers.ts`. Only reviewed tools are exposed, tools a server adds later stay hidden until reviewed.
+
+Servers are connected when the docs agent first runs, not at startup. A server that can't be reached prints a warning and is left out.
+
+## Development
+
+Running from source needs Node 22.18+ or 24.1+, which run TypeScript directly.
+
+```console
+$ npm install
+$ node src/cli.ts "hi"   # run from source, no build needed
+$ npm test
+$ npm run typecheck
+```
+
+Tests use a fake server and mocked `fetch`, no model or network needed. CI runs typecheck and tests on every push to `main` and on pull requests (`.github/workflows/ci.yml`).

package/dist/agent.js

@@ -0,0 +1,73 @@
+import { UNAVAILABLE_TOOLS } from './tools.js';
+export function systemPrompt(cwd = process.cwd(), instructions, { bashReview = true, restrictFiles = true } = {}) {
+    const files = restrictFiles ? ' File tools only access files inside it.' : '';
+    const bash = bashReview
+        ? 'Prefer the dedicated tools over bash: every bash call makes an extra round trip, in which a separate check reviews whether the other tools could do the same and whether the command is safe to run. Commands failing the check are refused.'
+        : 'Prefer the dedicated tools over bash.';
+    const prompt = `You are a helpful assistant running on the user's computer. The working directory is ${cwd}.${files} Today's date is ${new Date().toLocaleDateString('en-CA')}.
+Answer any question or request. Not every request is about code: answer general questions directly, without commenting on what kind of session this is. When it helps, use the tools to read and write files or run commands, and keep going until the request is done. ${bash}
+If none of your tools fit, use tool_search to find more. These tools are known to be unavailable, don't search for them: ${UNAVAILABLE_TOOLS.join(', ')}.
+If you'd recommend follow-up web searches to the user, end your answer with a "Suggested web searches:" list of search queries.`;
+    return instructions
+        ? `${prompt}\n\nInstructions from ${instructions.path}:\n${instructions.content}`
+        : prompt;
+}
+// Runs the model until it replies without tool calls. Appends every message
+// to `messages`, so calling it again continues the conversation.
+export async function runAgent(messages, { client, tools, maxTurns = 50, onToolCall, onToolResult, onMissingTool }) {
+    const schemas = tools.map(({ name, description, parameters }) => ({
+        type: 'function',
+        function: { name, description, parameters }
+    }));
+    for (let turn = 0; turn < maxTurns; turn++) {
+        const reply = await client.chat(messages, schemas);
+        messages.push(reply);
+        if (!reply.tool_calls)
+            return reply.content ?? '';
+        for (const call of reply.tool_calls) {
+            onToolCall?.(call);
+            const tool = tools.find(t => t.name === call.function.name);
+            let content;
+            if (tool) {
+                content = await runTool(tool, call);
+            }
+            else {
+                const suggestions = similarTools(call.function.name, tools);
+                onMissingTool?.(call, suggestions);
+                content = suggestions.length
+                    ? `Error: unknown tool ${call.function.name}. Did you mean: ${suggestions.join(', ')}? Otherwise use tool_search to find more tools.`
+                    : `Error: unknown tool ${call.function.name}. Use tool_search to find more tools.`;
+            }
+            onToolResult?.(call, content);
+            messages.push({ role: 'tool', tool_call_id: call.id, content });
+        }
+    }
+    throw new Error(`Stopped after ${maxTurns} turns`);
+}
+// Words many tool names share, which say nothing about what a tool is for
+const GENERIC_WORDS = new Set(['search', 'find', 'get', 'read', 'list', 'fetch', 'query', 'tool', 'run', 'call']);
+const meaningfulWords = (name) => new Set(name
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .map(word => word.replace(/s$/, ''))
+    .filter(word => word.length > 1 && !GENERIC_WORDS.has(word)));
+// Existing tools sharing the most meaningful words with a made up tool name,
+// like search_papers for search_paper_query
+export function similarTools(name, tools) {
+    const wanted = meaningfulWords(name);
+    const scored = tools
+        .filter(tool => tool.name !== 'tool_search')
+        .map(tool => ({ name: tool.name, score: [...meaningfulWords(tool.name)].filter(word => wanted.has(word)).length }))
+        .filter(tool => tool.score > 0);
+    const best = Math.max(0, ...scored.map(tool => tool.score));
+    return scored.filter(tool => tool.score === best).slice(0, 3).map(tool => tool.name);
+}
+// Errors go back to the model as text so it can recover
+async function runTool(tool, call) {
+    try {
+        return await tool.run(JSON.parse(call.function.arguments || '{}'));
+    }
+    catch (err) {
+        return `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}

package/dist/bashreview.js

@@ -0,0 +1,58 @@
+export const bashReviewPrompt = (tools, cwd) => `You check a shell command that an agent wants to run with its bash tool, on the user's computer and without asking the user. The working directory is ${cwd}. Besides bash, the agent has these tools:
+${tools.map(tool => `- ${tool.name}: ${tool.description}`).join('\n')}
+
+Answer two questions.
+1. Can the purpose of the command be achieved with these tools instead of bash? Listing, finding, reading and searching files can be done with them. Running programs, tests, builds, git or package managers can't.
+2. Is the command safe to run? It is unsafe if it could:
+- delete or overwrite files outside the working directory, or delete many files inside it
+- change system settings, install software system wide, or use sudo
+- read or send secrets, like SSH keys, tokens, passwords or environment variables
+- send data to the internet, other than downloading the project's dependencies
+- push, publish or deploy anything, or rewrite git history
+- start processes that keep running in the background
+Other commands, like running tests, builds, linters or read-only git commands, are safe.
+
+Reply with JSON only: {"use_tools": true or false, "tools": ["names of the tools to use, if use_tools is true"], "reason": "why the tools can or can't do it", "safe": true or false, "safety": "why the command is safe or unsafe"}`;
+const text = (value, fallback) => typeof value === 'string' && value.trim() ? value.trim() : fallback;
+export async function reviewBashCommand(command, { client, tools, cwd = process.cwd() }) {
+    let answer;
+    try {
+        const reply = await client.chat([
+            { role: 'system', content: bashReviewPrompt(tools, cwd) },
+            { role: 'user', content: `Command:\n${command}` }
+        ], []);
+        answer = JSON.parse(reply.content?.match(/\{[\s\S]*\}/)?.[0] ?? '');
+    }
+    catch { }
+    const names = new Set(tools.map(tool => tool.name));
+    const useTools = answer?.use_tools === true;
+    // Only an explicit yes counts as safe, so a failed check refuses the command
+    const safe = answer?.safe === true;
+    return {
+        useTools,
+        tools: useTools && Array.isArray(answer.tools)
+            ? answer.tools.filter((name) => typeof name === 'string' && names.has(name))
+            : [],
+        reason: text(answer?.reason, answer ? 'no reason given' : 'the check couldn\'t decide'),
+        safe,
+        safety: text(answer?.safety, safe ? 'no reason given' : 'the check couldn\'t verify the command is safe')
+    };
+}
+export function withBashReview(bash, { onReview, ...options }) {
+    return {
+        ...bash,
+        async run(args) {
+            const review = await reviewBashCommand(args.command, options);
+            onReview?.(args.command, review);
+            // Unsafe comes first, so an unsafe command never points the model at another tool
+            if (!review.safe) {
+                throw new Error(`bash refused as unsafe: ${review.safety.replace(/\.$/, '')}. Don't retry it. If it's needed, ask the user to run it themselves.`);
+            }
+            if (review.useTools) {
+                const instead = review.tools.length ? review.tools.join(', ') : 'the other tools';
+                throw new Error(`bash refused: ${review.reason.replace(/\.$/, '')}. Use ${instead} instead.`);
+            }
+            return bash.run(args);
+        }
+    };
+}

package/dist/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { cwd, env, exit, stderr, stdin, stdout } from 'node:process';
+import { parseArgs, styleText } from 'node:util';
+import { runAgent, systemPrompt } from './agent.js';
+import { withBashReview } from './bashreview.js';
+import { answerSeparator, withDebug } from './debug.js';
+import { createDocsTool } from './docs.js';
+import { resolveInstructions } from './instructions.js';
+import { createClient } from './llm.js';
+import { renderMarkdown } from './markdown.js';
+import { rateLimiter } from './http.js';
+import { createResearchTool } from './research.js';
+import { appendSearches, appendSources, extractSearches, extractUrls, SECTION_HEADING } from './subagent.js';
+import { bash, createToolSearch, restrictFileTools, tools } from './tools.js';
+const { values, positionals } = parseArgs({
+    options: {
+        debug: { type: 'boolean', short: 'd' },
+        trust: { type: 'boolean' },
+        // For running in a container: bash commands aren't checked
+        unsafe: { type: 'boolean' }
+    },
+    allowPositionals: true
+});
+const warn = (text) => stderr.write(`${styleText('yellow', text, { stream: stderr })}\n`);
+if (values.unsafe)
+    warn('WARNING: --unsafe: bash commands run without checks, and file tools can access files outside the working directory. Only use this in a container.');
+else
+    restrictFileTools(cwd());
+rateLimiter.onWarning = warn;
+async function askUser(question) {
+    const rl = createInterface({ input: stdin, output: stderr });
+    rl.on('SIGINT', () => exit(130));
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+const instructions = await resolveInstructions(cwd(), {
+    trust: values.trust ?? false,
+    ask: stdin.isTTY ? askUser : undefined,
+    warn
+});
+const baseUrl = env.AGENT_BASE_URL ?? 'http://localhost:11434/v1';
+const model = env.AGENT_MODEL ?? 'qwen3.8';
+const onRetry = (err) => warn(`${err.message}, retrying`);
+const llm = createClient({ baseUrl, model, apiKey: env.AGENT_API_KEY, onRetry });
+const researchLlm = createClient({ baseUrl, model: env.AGENT_RESEARCH_MODEL ?? model, apiKey: env.AGENT_API_KEY, onRetry });
+// Tools the model asked for, collected per question and printed after the answer
+const toolRequests = new Set();
+const toolSearch = createToolSearch(description => toolRequests.add(description));
+const logToolCall = (prefix) => (call) => {
+    // Debug mode already logs tool calls
+    if (!values.debug)
+        stderr.write(`[${prefix}${call.function.name}] ${call.function.arguments}\n`);
+};
+// Models sometimes call tools by made up names. Close to an existing tool's
+// name it's a naming problem, otherwise it's a request for a new tool.
+const onMissingTool = (call, suggestions) => {
+    if (suggestions.length)
+        warn(`WARNING: unknown tool ${call.function.name}, probably meant ${suggestions.join(' or ')}`);
+    else
+        toolRequests.add(`${call.function.name} ${call.function.arguments}`);
+};
+const subagentOptions = (label) => ({
+    client: values.debug ? withDebug(researchLlm, { label }) : researchLlm,
+    extraTools: [toolSearch],
+    onToolCall: logToolCall(`${label} > `),
+    onMissingTool
+});
+const onMcpError = (server, err) => warn(`MCP server ${server.name} unavailable: ${err.message}`);
+const research = createResearchTool(subagentOptions('research'));
+const docs = createDocsTool({ ...subagentOptions('docs'), onError: onMcpError });
+// Their answers carry sources and suggested web searches
+const subagents = new Set([research.name, docs.name]);
+// bash only runs when the other tools can't do the same and the command is
+// safe, unless --unsafe skips the check
+const checkedBash = values.unsafe
+    ? bash
+    : withBashReview(bash, {
+        client: values.debug ? withDebug(llm, { label: 'bash review' }) : llm,
+        tools: [...tools.filter(tool => tool !== bash), research, docs],
+        onReview: (_, review) => warn(!review.safe
+            ? `WARNING: bash refused as unsafe: ${review.safety}`
+            : review.useTools
+                ? `WARNING: bash refused, use ${review.tools.join(' or ') || 'the other tools'}: ${review.reason}`
+                : `WARNING: bash used: ${review.reason}`)
+    });
+const mainTools = [...tools.map(tool => tool === bash ? checkedBash : tool), research, docs, toolSearch];
+const client = values.debug ? withDebug(llm) : llm;
+const messages = [{ role: 'system', content: systemPrompt(cwd(), instructions, { bashReview: !values.unsafe, restrictFiles: !values.unsafe }) }];
+async function ask(prompt) {
+    messages.push({ role: 'user', content: prompt });
+    toolRequests.clear();
+    const researchUrls = [];
+    const researchSearches = [];
+    let answer = await runAgent(messages, {
+        client,
+        tools: mainTools,
+        onToolCall: logToolCall(''),
+        onToolResult: (call, result) => {
+            if (!subagents.has(call.function.name))
+                return;
+            researchUrls.push(...extractUrls(result));
+            researchSearches.push(...extractSearches(result));
+        },
+        onMissingTool
+    });
+    answer = appendSources(answer, [...new Set(researchUrls)]);
+    answer = appendSearches(answer, [...new Set(researchSearches)]);
+    // Keep the conversation in sync with what the user sees
+    const last = messages.at(-1);
+    if (last?.role === 'assistant')
+        last.content = answer;
+    if (values.debug)
+        stderr.write(answerSeparator());
+    stdout.write(`${renderMarkdown(answer, { highlight: SECTION_HEADING })}\n`);
+    for (const request of toolRequests) {
+        stderr.write(`${styleText('red', `TODO: add tool: ${request}`, { stream: stderr })}\n`);
+    }
+}
+const prompt = positionals.join(' ');
+if (prompt) {
+    await ask(prompt);
+}
+else {
+    // Write the prompt manually: rl.prompt() throws once stdin has ended
+    const rl = createInterface({ input: stdin });
+    stdout.write('> ');
+    for await (const line of rl) {
+        if (line.trim()) {
+            try {
+                await ask(line);
+            }
+            catch (err) {
+                stderr.write(`${err instanceof Error ? err.message : err}\n`);
+            }
+        }
+        stdout.write('> ');
+    }
+}

package/dist/debug.js

@@ -0,0 +1,83 @@
+import { stderr } from 'node:process';
+import { styleText } from 'node:util';
+import { renderMarkdown } from './markdown.js';
+const style = (format, text) => styleText(format, text, { stream: stderr });
+const indent = (text, spaces) => text.split('\n').map(line => line && ' '.repeat(spaces) + line).join('\n');
+// Printed between the debug log and the rendered answer
+export const answerSeparator = () => `${style(['bold', 'magenta'], '=== answer ===')}\n`;
+// Tool arguments as `key: value` lines, multi-line values indented below
+function formatArguments(args) {
+    let parsed;
+    try {
+        parsed = JSON.parse(args || '{}');
+    }
+    catch {
+        return indent(args, 2);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return indent(JSON.stringify(parsed, null, 2), 2);
+    return Object.entries(parsed).map(([key, value]) => {
+        const text = typeof value === 'string' ? value : JSON.stringify(value);
+        return text.includes('\n')
+            ? `  ${style('dim', `${key}:`)}\n${indent(text, 4)}`
+            : `  ${style('dim', `${key}:`)} ${text}`;
+    }).join('\n');
+}
+function formatResult(content) {
+    if (/^\s*[[{]/.test(content)) {
+        try {
+            return JSON.stringify(JSON.parse(content), null, 2);
+        }
+        catch { }
+    }
+    return content;
+}
+// Wraps a client to log everything exchanged with the model, including
+// implicit context like the system prompt, tool definitions and tool results
+export function withDebug(client, { label, log = text => { stderr.write(text); } } = {}) {
+    const seen = new WeakSet();
+    const toolNames = new Map();
+    let toolsLogged = false;
+    const header = (text) => style(['bold', 'magenta'], `--- ${label ? `${label}: ` : ''}${text} ---`);
+    const formatMessage = (message) => {
+        const lines = [];
+        if (message.role === 'tool') {
+            const name = toolNames.get(message.tool_call_id);
+            lines.push(header(`tool result: ${name ? `${name} ` : ''}${message.tool_call_id}`), formatResult(message.content));
+        }
+        else {
+            lines.push(header(message.role));
+            if (message.content)
+                lines.push(renderMarkdown(message.content, { stream: stderr }));
+            if (message.role === 'assistant') {
+                for (const call of message.tool_calls ?? []) {
+                    toolNames.set(call.id, call.function.name);
+                    lines.push(`${style(['bold', 'cyan'], call.function.name)} ${style('dim', call.id)}`);
+                    const args = formatArguments(call.function.arguments);
+                    if (args)
+                        lines.push(args);
+                }
+            }
+        }
+        return `${lines.join('\n')}\n`;
+    };
+    const formatTools = (tools) => `${[header('tools'), ...tools.map(({ function: f }) => `${style('bold', f.name)}: ${f.description}`)].join('\n')}\n`;
+    return {
+        async chat(messages, tools) {
+            if (!toolsLogged && tools.length) {
+                log(formatTools(tools));
+                toolsLogged = true;
+            }
+            for (const message of messages) {
+                if (seen.has(message))
+                    continue;
+                seen.add(message);
+                log(formatMessage(message));
+            }
+            const reply = await client.chat(messages, tools);
+            seen.add(reply);
+            log(formatMessage(reply));
+            return reply;
+        }
+    };
+}

package/dist/docs.js

@@ -0,0 +1,24 @@
+// The docs agent answers questions about software from documentation MCP
+// servers, see mcp-servers.ts for the list and why each one is fair.
+import { createMcpToolLoader } from './mcp.js';
+import { docsServers } from './mcp-servers.js';
+import { createSubagentTool } from './subagent.js';
+export const docsPrompt = (date = new Date()) => `You are a documentation agent. Today's date is ${date.toLocaleDateString('en-CA')}.
+Answer questions about software libraries, frameworks, GitHub repositories and Microsoft products using the tools: DeepWiki (documentation of public GitHub repositories), Context7 (up to date library documentation) and Microsoft Learn. APIs change, so look them up instead of relying on memory. If a tool fails, move on to another tool instead of retrying it.
+Reply with a concise answer, with code examples where useful, followed by a "Sources" list with the URLs of the documentation you used. If the documentation doesn't answer the question, say so.`;
+export function createDocsTool({ servers = docsServers, connect, onError, ...options }) {
+    const loadTools = createMcpToolLoader(servers, { connect, onError });
+    return createSubagentTool({
+        name: 'docs',
+        description: 'Ask a documentation agent about software libraries, frameworks, GitHub repositories and Microsoft products. It reads current documentation, so use it for APIs and usage you are unsure about. Returns an answer with source URLs, include them in your answer.',
+        parameter: { name: 'question', description: 'A self-contained question, including library names and versions' },
+        prompt: () => docsPrompt(),
+        tools: async () => {
+            const tools = await loadTools();
+            if (!tools.length)
+                throw new Error('No documentation server could be reached. Answer without docs, and say so.');
+            return tools;
+        },
+        maxTurns: 15
+    }, options);
+}

package/dist/html.js

@@ -0,0 +1,12 @@
+// Small, dependency free helpers for text that contains HTML
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+export const decodeEntities = (text) => text.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (match, entity) => entity[0] !== '#'
+    ? ENTITIES[entity.toLowerCase()] ?? match
+    : String.fromCodePoint(entity[1].toLowerCase() === 'x' ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10)));
+// Strips tags, decodes entities and collapses whitespace into one line. Block
+// tags become spaces so paragraphs don't run together, inline tags disappear.
+export const cleanText = (text) => decodeEntities(text
+    .replace(/<\/?(?:[a-z]+:)?(?:p|div|br|li|title|sec|h\d)\b[^>]*>/gi, ' ')
+    .replace(/<[^>]+>/g, ''))
+    .replace(/\s+/g, ' ')
+    .trim();

package/dist/http.js

@@ -0,0 +1,44 @@
+// HTTP requests to research sources and MCP servers, rate limited per host
+import { createRateLimiter } from './ratelimit.js';
+// Optional contact info, recommended by Wikimedia, OpenAlex and Crossref
+export const CONTACT = process.env.AGENT_CONTACT;
+export const USER_AGENT = `harness/0.0.0${CONTACT ? ` (${CONTACT})` : ''}`;
+// Shared by all requests. Set onWarning to hear about budgets running low.
+export const rateLimiter = createRateLimiter({
+    intervals: {
+        // arXiv asks for at most one request every 3 seconds
+        'export.arxiv.org': 3000,
+        // Keyless Semantic Scholar requests share one pool with everyone
+        'api.semanticscholar.org': 1000
+    }
+});
+// Bot protection like Cloudflare's answers with a challenge page instead of content
+export const isBotChallenge = (res) => res.headers.get('cf-mitigated') === 'challenge';
+export async function request(url, { method = 'GET', body, headers = {}, timeout = 30_000, minInterval, hint = 'Try another source instead.', allowErrors = false } = {}) {
+    const { hostname } = new URL(url);
+    try {
+        await rateLimiter.schedule(hostname, minInterval);
+        let res;
+        try {
+            res = await fetch(url, { method, body, headers: { 'user-agent': USER_AGENT, ...headers }, signal: AbortSignal.timeout(timeout) });
+        }
+        catch (err) {
+            rateLimiter.failed(hostname);
+            throw err;
+        }
+        rateLimiter.update(hostname, res);
+        if (isBotChallenge(res)) {
+            // The site doesn't want automated visits. Respect that, don't work around it.
+            rateLimiter.failed(hostname);
+            throw new Error(`${hostname} blocks automated clients with a bot challenge`);
+        }
+        if (!res.ok && !allowErrors)
+            throw new Error(`${hostname} responded ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`);
+        return res;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`${message.includes(hostname) ? message : `${hostname} unavailable: ${message}`}. ${hint}`);
+    }
+}
+export const getJson = async (url) => (await request(url)).json();

package/dist/instructions.js

@@ -0,0 +1,31 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// In order of preference, matched case insensitively
+const FILENAMES = ['agents.md', 'agent.md', 'claude.md'];
+const PREVIEW_LINES = 10;
+export async function findInstructions(cwd) {
+    const entries = await readdir(cwd, { withFileTypes: true });
+    for (const filename of FILENAMES) {
+        const entry = entries.find(e => e.isFile() && e.name.toLowerCase() === filename);
+        if (entry) {
+            const path = join(cwd, entry.name);
+            return { path, content: await readFile(path, 'utf8') };
+        }
+    }
+}
+// Instructions are only used if the user trusts them, every time
+export async function resolveInstructions(cwd, { trust, ask, warn }) {
+    const instructions = await findInstructions(cwd);
+    if (!instructions || trust)
+        return instructions;
+    if (!ask) {
+        warn(`Ignoring ${instructions.path}: can't ask whether to trust it. Pass --trust to use it.`);
+        return;
+    }
+    const lines = instructions.content.split('\n');
+    const preview = lines.slice(0, PREVIEW_LINES).map(line => `  ${line}`).join('\n');
+    const more = lines.length > PREVIEW_LINES ? `\n  [${lines.length - PREVIEW_LINES} more lines]` : '';
+    const answer = await ask(`Found ${instructions.path} for review:\n${preview}${more}\nUse these instructions? [y/N] `);
+    if (/^y(es)?$/i.test(answer.trim()))
+        return instructions;
+}