flashlite 0.0.0-stage → 0.1.1

package/dist/researchweb.js

@@ -0,0 +1,87 @@
+// Research-only public HTTPS reader. Not a general-purpose network/command grant.
+import https from 'node:https';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+const MAX_BYTES = 32 * 1024;
+const MAX_URL = 2048;
+const TIMEOUT_MS = 10000;
+function publicAddress(address) {
+    if (net.isIP(address) === 4) {
+        const [a, b, c] = address.split('.').map(Number);
+        return a !== 0 && a !== 10 && a !== 127 && a < 224 &&
+            !(a === 169 && b === 254) && !(a === 172 && b >= 16 && b <= 31) &&
+            !(a === 192 && b === 168) && !(a === 100 && b >= 64 && b <= 127) &&
+            !(a === 192 && b === 0 && c === 0) && !(a === 192 && b === 0 && c === 2) &&
+            !(a === 198 && (b === 18 || b === 19 || b === 51 && c === 100)) &&
+            !(a === 203 && b === 0 && c === 113) && !(a === 192 && b === 88 && c === 99);
+    }
+    // Deliberately conservative: IPv6 research uses IPv4 instead. This excludes
+    // loopback, ULA, link-local and IPv4-mapped IPv6 addresses.
+    return false;
+}
+export async function fetchPublicPage(raw, signal) {
+    if (typeof raw !== 'string' || raw.length > MAX_URL)
+        throw new Error('invalid research URL');
+    const url = new URL(raw);
+    if (url.protocol !== 'https:' || url.port && url.port !== '443' || url.username || url.password || url.hash ||
+        net.isIP(url.hostname) || !url.hostname.includes('.') || url.hostname.endsWith('.local')) {
+        throw new Error('research only permits public HTTPS hostnames on port 443 (no credentials or IP literals)');
+    }
+    if (/^(?:localhost|[^.]+\.localhost|[^.]+\.internal|[^.]+\.test|[^.]+\.invalid|metadata\.google\.internal)$/i.test(url.hostname))
+        throw new Error('research endpoint is not public');
+    signal?.throwIfAborted();
+    const addresses = await dns.lookup(url.hostname, { all: true, family: 4 });
+    const address = addresses.find((entry) => entry.family === 4 && publicAddress(entry.address))?.address;
+    if (!addresses.length || addresses.some((entry) => !publicAddress(entry.address)) || !address)
+        throw new Error('research endpoint is not public');
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error, body) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolve(body ?? '');
+        };
+        const abort = () => { request.destroy(signal?.reason instanceof Error ? signal.reason : new Error('research cancelled')); };
+        const request = https.request(url, {
+            method: 'GET', timeout: TIMEOUT_MS, headers: { 'User-Agent': 'flashlite-research/1', Accept: 'text/plain, text/html, application/json' },
+            lookup: (_hostname, _options, callback) => callback(null, address, 4),
+            agent: false, minVersion: 'TLSv1.2',
+        }, (response) => {
+            if (response.statusCode !== 200) {
+                response.destroy();
+                finish(new Error(`research HTTP ${response.statusCode ?? 'unknown'} (redirects are not followed)`));
+                return;
+            }
+            const type = response.headers['content-type'] ?? '';
+            if (!/^(text\/plain|text\/html|application\/json)(;|$)/i.test(type)) {
+                response.destroy();
+                finish(new Error('research supports only text, HTML or JSON'));
+                return;
+            }
+            const chunks = [];
+            let bytes = 0;
+            response.on('data', (chunk) => {
+                bytes += chunk.length;
+                if (bytes > MAX_BYTES) {
+                    response.destroy();
+                    finish(new Error('research response exceeds 32 KiB; use a narrower URL'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('end', () => finish(undefined, Buffer.concat(chunks).toString('utf8')));
+            response.on('error', (err) => finish(err));
+        });
+        request.on('timeout', () => request.destroy(new Error('research request timed out')));
+        request.on('error', (err) => finish(err));
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        request.end();
+    });
+}

package/dist/sanitize.js

@@ -0,0 +1,89 @@
+// Recovers tool calls that leaked into assistant *text* as vendor chat-template
+// markup instead of structured tool_calls.
+//
+// Some OpenAI-compatible routers are thin proxies: the upstream model emits its
+// native control tokens — several tokenizers fence them with the fullwidth vertical
+// bar U+FF5C, e.g. ｜｜DSML｜｜invoke name="read_file"｜｜DSML｜｜ — and the router does
+// not translate them into tool_calls. They arrive as ordinary content, so the turn
+// carries no usable calls and dead-ends. We parse the common shape (a sequence of
+// `invoke name="..."` blocks with `parameter name="...">value` children) back into
+// calls and strip the rest so the prose survives. Other shapes are stripped but not
+// executed — a stray delimiter must never silently kill a turn.
+const MARK = '\u0001';
+/** True when the text carries leaked tool-call control tokens. */
+export function hasLeakedToolMarkup(text) {
+    if (!text.includes('｜'))
+        return false;
+    return text.includes('｜｜') || text.includes('<｜');
+}
+/** Collapse every control-token delimiter down to a single sentinel marker. */
+function normalize(text) {
+    return text
+        .replace(/<｜/g, MARK)
+        .replace(/｜>/g, MARK)
+        .replace(/｜+/g, MARK)
+        .replace(/\u0001(?:DSML)?\u0001/g, MARK)
+        .replace(/\u0001{2,}/g, MARK);
+}
+/** Parse vendor-markup tool calls out of leaked text ([] when none are recoverable). */
+export function parseLeakedToolCalls(text) {
+    if (!hasLeakedToolMarkup(text))
+        return [];
+    const src = normalize(text);
+    const calls = [];
+    const invokes = [...src.matchAll(/\u0001\s*(?:tool)?[_▁]*invoke\s+name\s*=\s*["']?([^"'\s>]+)["']?\s*>/g)];
+    for (let index = 0; index < invokes.length; index += 1) {
+        const start = (invokes[index].index ?? 0) + invokes[index][0].length;
+        const end = index + 1 < invokes.length ? (invokes[index + 1].index ?? src.length) : src.length;
+        const body = src.slice(start, end);
+        const params = [...body.matchAll(/\u0001\s*(?:tool)?[_▁]*parameter\s+name\s*=\s*["']?([^"'\s>]+)["']?\s*>/g)];
+        const args = {};
+        for (let p = 0; p < params.length; p += 1) {
+            const valueStart = (params[p].index ?? 0) + params[p][0].length;
+            const valueEnd = p + 1 < params.length ? (params[p + 1].index ?? body.length) : body.length;
+            let value = body.slice(valueStart, valueEnd);
+            const cut = value.indexOf(MARK); // the closing control token starts here
+            if (cut >= 0)
+                value = value.slice(0, cut);
+            args[params[p][1]] = value.trim();
+        }
+        calls.push({ name: invokes[index][1], arguments: args });
+    }
+    return calls;
+}
+/** Drop leaked markup, keeping any surrounding prose. */
+export function stripLeakedToolMarkup(text) {
+    if (!hasLeakedToolMarkup(text))
+        return text;
+    return normalize(text)
+        .split('\n')
+        .map((line) => {
+        const at = line.indexOf(MARK);
+        return at >= 0 ? line.slice(0, at) : line;
+    })
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/**
+ * Recover leaked calls in place: parse what is usable into `message.toolCalls` and
+ * strip the markup from `message.content`. Returns the recovered calls and whether
+ * anything was stripped.
+ */
+export function recoverLeakedToolCalls(message) {
+    const text = message.content;
+    if (!hasLeakedToolMarkup(text))
+        return { calls: [], stripped: false };
+    const parsed = parseLeakedToolCalls(text);
+    message.content = stripLeakedToolMarkup(text);
+    if (!parsed.length)
+        return { calls: [], stripped: true };
+    const calls = parsed.map((call, index) => ({
+        id: `leaked-call-${index + 1}`,
+        name: call.name,
+        arguments: { ...call.arguments },
+        argumentsJson: JSON.stringify(call.arguments),
+    }));
+    message.toolCalls = calls;
+    return { calls, stripped: true };
+}

package/dist/sessions.js

@@ -0,0 +1,209 @@
+// sessions.ts — private append-only transcripts under ~/.config/flashlite/sessions/.
+import fs from 'node:fs';
+import path from 'node:path';
+import { configDir } from "./config.js";
+const SESSION_ID = /^sess-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
+const MAX_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+const MAX_RESUME_BYTES = 24 * 1024 * 1024;
+const MAX_RESUME_TURNS = 200;
+export function sessionsDir() {
+    return path.join(configDir(), 'sessions');
+}
+let lastStamp = 0;
+function stamp() {
+    lastStamp = Math.max(Date.now(), lastStamp + 1);
+    return new Date(lastStamp).toISOString().replace(/[:.]/g, '-');
+}
+function sessionPaths(id, dir) {
+    if (!SESSION_ID.test(id))
+        throw new Error('invalid session ID');
+    return { id, mdPath: path.join(dir, `${id}.md`), jsonlPath: path.join(dir, `${id}.jsonl`) };
+}
+/** Create a new session transcript (files are chmod 600 like the config). */
+export function startSession(dir = sessionsDir(), cwd = process.cwd()) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    let id = `sess-${stamp()}`;
+    let session = sessionPaths(id, dir);
+    while (fs.existsSync(session.mdPath) || fs.existsSync(session.jsonlPath)) {
+        id = `sess-${stamp()}`;
+        session = sessionPaths(id, dir);
+    }
+    fs.appendFileSync(session.mdPath, `# flashlite session ${id}\n\nstarted: ${new Date().toISOString()}\n\n`, { mode: 0o600 });
+    fs.appendFileSync(session.jsonlPath, JSON.stringify({ type: 'session', version: 1, workspace: fs.realpathSync(cwd), ts: new Date().toISOString() }) + '\n', { mode: 0o600 });
+    fs.chmodSync(session.mdPath, 0o600);
+    fs.chmodSync(session.jsonlPath, 0o600);
+    return session;
+}
+/** Append a markdown block to the session log. */
+export function appendMarkdown(session, block) {
+    fs.appendFileSync(session.mdPath, block + '\n', { mode: 0o600 });
+}
+/** Append one JSON record to the transcript (one line per record). */
+export function appendRecord(session, record) {
+    // A separator first isolates any torn prior append, so a later recovery checkpoint remains readable.
+    fs.appendFileSync(session.jsonlPath, '\n' + JSON.stringify(record) + '\n', { mode: 0o600 });
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isMessage(value) {
+    if (!isObject(value) || !['user', 'assistant', 'tool'].includes(String(value.role)) || typeof value.content !== 'string')
+        return false;
+    if (value.images !== undefined && (!Array.isArray(value.images) || value.images.some((image) => !isObject(image) || typeof image.name !== 'string' || typeof image.data !== 'string' ||
+        !['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(String(image.mediaType)))))
+        return false;
+    if (value.toolCalls !== undefined && (!Array.isArray(value.toolCalls) || value.toolCalls.some((call) => !isObject(call) || typeof call.id !== 'string' || typeof call.name !== 'string' ||
+        typeof call.argumentsJson !== 'string' || !isObject(call.arguments))))
+        return false;
+    if (value.thinkingBlocks !== undefined && (!Array.isArray(value.thinkingBlocks) || value.thinkingBlocks.some((block) => !isObject(block) || block.type !== 'thinking' && block.type !== 'redacted_thinking' ||
+        typeof (block.type === 'thinking' ? block.thinking : block.data) !== 'string' ||
+        block.type === 'thinking' && typeof block.signature !== 'string')))
+        return false;
+    return true;
+}
+/** Block mismatched workspaces; old sessions require a separate explicit acknowledgement. */
+export function sessionWorkspaceIssue(summary, cwd = process.cwd()) {
+    if (!summary.workspace)
+        return 'legacy';
+    let current;
+    try {
+        current = fs.realpathSync(cwd);
+    }
+    catch {
+        return 'Current workspace is unavailable.';
+    }
+    if (current === summary.workspace)
+        return undefined;
+    return `Session belongs to workspace ${JSON.stringify(summary.workspace)}, not ${JSON.stringify(current)}. Launch flash from that workspace (cd ${JSON.stringify(summary.workspace)}), then use --resume ${summary.id}. No session permissions are restored.`;
+}
+function readRecords(session) {
+    try {
+        const mdStat = fs.lstatSync(session.mdPath);
+        const transcriptStat = fs.lstatSync(session.jsonlPath);
+        if (!mdStat.isFile() || !transcriptStat.isFile() || transcriptStat.size > MAX_TRANSCRIPT_BYTES)
+            return null;
+        const lines = fs.readFileSync(session.jsonlPath, 'utf8').split('\n');
+        const records = [];
+        let summary = { id: session.id, model: '', ts: '', turns: 0 };
+        for (const line of lines) {
+            if (!line)
+                continue;
+            let raw;
+            try {
+                raw = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (isObject(raw) && raw.type === 'session') {
+                // Only the first valid header may establish identity; later records cannot retarget it.
+                if (!summary.workspace && !records.length && raw.version === 1 && typeof raw.workspace === 'string' && path.isAbsolute(raw.workspace))
+                    summary.workspace = raw.workspace;
+                continue;
+            }
+            if (!isObject(raw) || typeof raw.ts !== 'string' || typeof raw.model !== 'string' ||
+                !Array.isArray(raw.messages) || !raw.messages.every(isMessage) ||
+                Buffer.byteLength(line) > MAX_RESUME_BYTES)
+                continue;
+            if (raw.type === 'compaction') {
+                if (raw.messages.length)
+                    records.push({ type: 'compaction', ts: raw.ts, model: raw.model, messages: raw.messages });
+                continue;
+            }
+            if (raw.type === 'checkpoint' && raw.messages.length && ['failed', 'interrupted', 'recovered'].includes(String(raw.reason))) {
+                records.push({ type: 'checkpoint', ts: raw.ts, model: raw.model, reason: raw.reason, messages: raw.messages });
+                summary = { ...summary, model: raw.model, ts: raw.ts, turns: summary.turns + 1 };
+                continue;
+            }
+            if (raw.type !== 'turn')
+                continue;
+            const record = {
+                type: 'turn', ts: raw.ts, model: raw.model,
+                stopReason: ['stop', 'tool_calls', 'length', 'refusal', 'unknown', 'context_limit', 'invalid_tool_calls'].includes(String(raw.stopReason))
+                    ? raw.stopReason : 'unknown',
+                rounds: typeof raw.rounds === 'number' && Number.isSafeInteger(raw.rounds) && raw.rounds >= 0 ? raw.rounds : 0,
+                messages: raw.messages,
+                ...(isObject(raw.usage) && Number.isFinite(raw.usage.inputTokens) && Number.isFinite(raw.usage.outputTokens)
+                    ? {
+                        usage: {
+                            inputTokens: raw.usage.inputTokens,
+                            outputTokens: raw.usage.outputTokens,
+                            ...(Number.isFinite(raw.usage.cachedInputTokens) ? { cachedInputTokens: raw.usage.cachedInputTokens } : {}),
+                        },
+                    } : {}),
+            };
+            records.push(record);
+            summary = { ...summary, model: record.model, ts: record.ts, turns: summary.turns + 1 };
+        }
+        return summary.turns ? { summary, records } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** List recent valid sessions without reading or returning their message content. */
+export function listSessions(dir = sessionsDir()) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const summaries = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+            continue;
+        const id = entry.name.slice(0, -'.jsonl'.length);
+        if (!SESSION_ID.test(id))
+            continue;
+        const result = readRecords(sessionPaths(id, dir));
+        if (result)
+            summaries.push(result.summary);
+    }
+    return summaries.sort((a, b) => b.id.localeCompare(a.id));
+}
+/** Load bounded, validated completed-turn context from one local session. */
+export function loadSession(id, dir = sessionsDir()) {
+    let session;
+    try {
+        session = sessionPaths(id, dir);
+    }
+    catch {
+        return null;
+    }
+    const result = readRecords(session);
+    if (!result)
+        return null;
+    const latestCompaction = result.records.findLastIndex((record) => record.type === 'compaction' || record.type === 'checkpoint');
+    let messages;
+    if (latestCompaction >= 0) {
+        const checkpoint = result.records[latestCompaction];
+        messages = checkpoint.messages.slice();
+        for (const record of result.records.slice(latestCompaction + 1))
+            if (record.type === 'turn')
+                messages.push(...record.messages);
+        while (messages.length > 1 && (Buffer.byteLength(JSON.stringify(messages)) > MAX_RESUME_BYTES ||
+            messages.filter((message) => message.role === 'user').length > MAX_RESUME_TURNS)) {
+            const nextUser = messages.findIndex((message, index) => index > 0 && message.role === 'user');
+            if (nextUser < 0)
+                break;
+            messages = messages.slice(nextUser);
+        }
+    }
+    else {
+        const turns = result.records.filter((record) => record.type === 'turn');
+        const selected = [];
+        let bytes = 0;
+        for (const turn of turns.toReversed()) {
+            const size = Buffer.byteLength(JSON.stringify(turn.messages));
+            if (selected.length && (selected.length >= MAX_RESUME_TURNS || bytes + size > MAX_RESUME_BYTES))
+                break;
+            selected.push(turn);
+            bytes += size;
+        }
+        selected.reverse();
+        messages = selected.flatMap((turn) => turn.messages);
+    }
+    return { session, summary: result.summary, messages };
+}

package/dist/sse.js

@@ -0,0 +1,80 @@
+// Dialect-blind SSE frame parser over a fetch body stream.
+// Handles lines split across chunk boundaries, multi-line data, event: names, and
+// CRLF endings. [DONE] and message_stop are handled by the callers/adapters.
+export async function* sseFrames(body, signal) {
+    const reader = body.getReader();
+    let finished = false;
+    let cancelled = false;
+    const cancel = () => {
+        if (finished || cancelled)
+            return;
+        cancelled = true;
+        // A failed or slow upstream cleanup must not mask the terminal frame/error.
+        void reader.cancel().catch(() => { });
+    };
+    signal?.addEventListener('abort', cancel, { once: true });
+    const decoder = new TextDecoder('utf-8');
+    let pending = '';
+    let dataParts = [];
+    let eventName;
+    const finishFrame = () => {
+        if (dataParts.length === 0)
+            return null;
+        const frame = { data: dataParts.join('\n') };
+        if (eventName)
+            frame.event = eventName;
+        dataParts = [];
+        eventName = undefined;
+        return frame;
+    };
+    // One complete line. Returns a finished frame, or null.
+    const processLine = (line) => {
+        if (line.startsWith('data:')) {
+            const payload = line.slice(5).trimStart().replace(/\r$/, '');
+            if (payload)
+                dataParts.push(payload); // empty payloads are heartbeats — skip
+            return null;
+        }
+        if (line.startsWith('event:')) {
+            eventName = line.slice(6).trim();
+            return null;
+        }
+        if (line === '' || line === '\r') {
+            return finishFrame(); // only a truly blank line terminates a frame
+        }
+        return null; // comments (": keepalive") and id:/retry: fields are ignored
+    };
+    try {
+        while (true) {
+            signal?.throwIfAborted();
+            const { value, done } = await reader.read();
+            signal?.throwIfAborted();
+            if (done)
+                finished = true;
+            pending += decoder.decode(value, { stream: !done });
+            const lines = pending.split('\n');
+            if (done) {
+                pending = ''; // every line is complete at EOF
+            }
+            else {
+                pending = lines.pop() ?? ''; // keep the trailing partial line
+            }
+            for (const line of lines) {
+                signal?.throwIfAborted();
+                const frame = processLine(line);
+                if (frame)
+                    yield frame;
+            }
+            if (done)
+                break;
+        }
+        const leftover = finishFrame(); // a final data line with no blank terminator
+        if (leftover)
+            yield leftover;
+    }
+    finally {
+        signal?.removeEventListener('abort', cancel);
+        cancel();
+        reader.releaseLock();
+    }
+}

package/dist/subagents.js

@@ -0,0 +1,182 @@
+// Background read-only helpers. No permission bypass, shell, edits, or shared history.
+import { runAgentTurn } from "./loop.js";
+import { TOOL_DEFINITIONS, executeTool } from "./tools.js";
+import { agentSystemPrompt } from "./systemprompt.js";
+import { sanitizeCommandOutput } from "./terminal.js";
+import { configPath } from "./config.js";
+import path from 'node:path';
+import { fetchPublicPage } from "./researchweb.js";
+export const SUBAGENT_ROLES = ['ui-ux', 'code', 'minor', 'oracle', 'reviewer', 'coder', 'researcher'];
+const MAX_JOBS = 3;
+const MAX_PROMPT = 4000;
+const MAX_RESULT = 12000;
+const MAX_ROUNDS = 8;
+const MAX_JOBS_TOTAL = 12;
+const READ_TOOLS = new Set(['read_file', 'read_files', 'list_dir', 'grep', 'find_files', 'file_info']);
+const tools = TOOL_DEFINITIONS.filter((tool) => READ_TOOLS.has(tool.name));
+const webTool = {
+    name: 'research_fetch', description: 'Read a public HTTPS text/HTML/JSON page (32 KiB max). No IP literals, local/private network, credentials, redirects or non-HTTPS. Only available to researchers.',
+    parameters: { type: 'object', properties: { url: { type: 'string', description: 'public HTTPS URL' } }, required: ['url'] }, requiresApproval: false,
+};
+const guidance = {
+    'ui-ux': 'Review UI/UX, interaction, accessibility and terminal layout. Give concise evidence and actionable recommendations; do not edit files.',
+    code: 'Review the delegated coding problem independently. Inspect relevant code and return specific findings; do not edit files.',
+    minor: 'Handle a narrow delegated research or verification task proportionally. Do not edit files.',
+    oracle: 'Independently reason about architecture, correctness and tradeoffs. Give a concise second opinion with assumptions and risks; do not edit files.',
+    reviewer: 'Review existing code for correctness, safety, regressions and missing tests. Cite exact files and actionable findings; do not edit files.',
+    coder: 'Inspect relevant code and propose a focused patch strategy and tests. Do not edit files or run commands.',
+    researcher: 'Research the delegated question using read-only project tools and public HTTPS pages. Cite source URLs, distinguish evidence from inference, and do not access credentials, local network, shell or file writes.',
+};
+export class SubagentManager {
+    jobs = new Map();
+    nextId = 1;
+    overrides = new Map();
+    mainSettings;
+    roleSettings;
+    client;
+    cwd;
+    onChange;
+    redactValues;
+    constructor(client, cwd, onChange, redactValues, mainSettings, roleSettings) {
+        this.client = client;
+        this.cwd = cwd;
+        this.onChange = onChange;
+        this.redactValues = redactValues;
+        this.mainSettings = mainSettings;
+        this.roleSettings = roleSettings;
+    }
+    list() { return [...this.jobs.values()].map(({ id, role, status, result, model, effort }) => ({ id, role, status, result, model, effort })); }
+    settings(role) { return this.roleSettings?.(role) ?? { ...this.mainSettings(), ...this.overrides.get(role) }; }
+    override(role) { return { ...this.overrides.get(role) }; }
+    configure(role, settings) {
+        if (!SUBAGENT_ROLES.includes(role))
+            throw new Error('unknown subagent role');
+        const next = { ...this.overrides.get(role), ...settings };
+        if (next.model !== undefined && !next.model.trim())
+            throw new Error('model must not be blank');
+        this.overrides.set(role, next);
+    }
+    reset(role) { this.overrides.delete(role); }
+    get(id) { return this.list().find((job) => job.id === id); }
+    transcript(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return [];
+        const lines = job.history.map((message) => {
+            const text = message.role === 'assistant' && message.toolCalls?.length
+                ? `tools: ${message.toolCalls.map((call) => call.name).join(', ')}${message.content ? ` · ${message.content}` : ''}` : message.content;
+            return `${message.role}: ${sanitizeCommandOutput(text, this.redactValues).slice(0, 2000)}`;
+        });
+        return lines;
+    }
+    start(role, prompt, parent) {
+        if (!SUBAGENT_ROLES.includes(role))
+            throw new Error('unknown subagent role');
+        if (!prompt.trim() || prompt.length > MAX_PROMPT)
+            throw new Error(`subagent prompt must be 1–${MAX_PROMPT} characters`);
+        if (this.jobs.size >= MAX_JOBS_TOTAL || [...this.jobs.values()].filter((job) => job.status === 'running').length >= MAX_JOBS)
+            throw new Error('subagent limit reached (3 concurrent, 12 total per turn)');
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(parent?.reason);
+        if (parent?.aborted)
+            onAbort();
+        else
+            parent?.addEventListener('abort', onAbort, { once: true });
+        const job = { id: this.nextId++, role, status: 'running', controller, task: Promise.resolve(),
+            history: [{ role: 'user', content: prompt }], ...this.settings(role) };
+        this.jobs.set(job.id, job);
+        this.onChange?.(job);
+        job.task = (async () => {
+            const history = job.history;
+            try {
+                const result = await runAgentTurn({
+                    client: this.client, model: job.model, effort: job.effort,
+                    history, system: `${agentSystemPrompt(this.cwd, this.redactValues)}\nSubagent role: ${role}. ${guidance[role]}\nOnly read-only tools are available. Researchers may read public HTTPS pages without a separate network prompt. Report findings to the main agent, not to the user.`,
+                    tools: role === 'researcher' ? [...tools, webTool] : tools,
+                    execute: async (call, signal) => {
+                        if (READ_TOOLS.has(call.name)) {
+                            const paths = [call.arguments.path, ...(Array.isArray(call.arguments.paths) ? call.arguments.paths : [])];
+                            const protectedPath = path.resolve(configPath());
+                            if (paths.some((value) => typeof value === 'string' && path.resolve(this.cwd, value) === protectedPath))
+                                return { toolCallId: call.id, content: 'subagents cannot read the router configuration file', isError: true };
+                            const result = await executeTool(call, this.cwd, { signal, redactValues: this.redactValues });
+                            result.content = sanitizeCommandOutput(result.content, this.redactValues);
+                            return result;
+                        }
+                        if (role === 'researcher' && call.name === 'research_fetch') {
+                            try {
+                                const url = call.arguments.url;
+                                if (typeof url !== 'string')
+                                    throw new Error('url must be a string');
+                                const content = await fetchPublicPage(url, signal);
+                                return { toolCallId: call.id, content: sanitizeCommandOutput(content, this.redactValues) };
+                            }
+                            catch (err) {
+                                return { toolCallId: call.id, content: sanitizeCommandOutput(err instanceof Error ? err.message : 'research failed', this.redactValues), isError: true };
+                            }
+                        }
+                        return { toolCallId: call.id, content: 'subagent tool not permitted', isError: true };
+                    },
+                    ask: async () => 'no',
+                    autoApprove: false, maxTokens: 4096, maxRounds: MAX_ROUNDS,
+                    contextTokens: 32_000, toolResultBudgetBytes: 8192, signal: controller.signal,
+                    onEvent: () => { }, onToolBatchComplete: () => this.onChange?.(job),
+                });
+                job.status = controller.signal.aborted ? 'cancelled' : result.stopReason === 'stop' ? 'done' : 'failed';
+                job.result = job.status === 'done' ? history.at(-1)?.content : `Subagent stopped: ${result.stopReason}`;
+            }
+            catch (err) {
+                job.status = controller.signal.aborted ? 'cancelled' : 'failed';
+                job.result = job.status === 'cancelled' ? 'Cancelled' : `Subagent failed: ${err instanceof Error ? err.message : 'unknown error'}`;
+            }
+            finally {
+                parent?.removeEventListener('abort', onAbort);
+                job.result = sanitizeCommandOutput(job.result ?? '', this.redactValues).slice(0, MAX_RESULT);
+                this.onChange?.(job);
+            }
+        })();
+        return { id: job.id, role, status: job.status, model: job.model, effort: job.effort };
+    }
+    async wait(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return undefined;
+        await job.task;
+        return this.get(id);
+    }
+    cancel(id) {
+        const job = this.jobs.get(id);
+        if (!job || job.status !== 'running')
+            return false;
+        job.controller.abort();
+        return true;
+    }
+    cancelAll() { for (const job of this.jobs.values())
+        job.controller.abort(); }
+    async settle(signal) {
+        const running = [...this.jobs.values()].filter((job) => job.status === 'running');
+        if (!running.length)
+            return;
+        signal?.throwIfAborted();
+        let onAbort;
+        try {
+            await Promise.race([
+                Promise.all(running.map((job) => job.task)),
+                new Promise((_, reject) => {
+                    onAbort = () => reject(signal?.reason);
+                    signal?.addEventListener('abort', onAbort, { once: true });
+                }),
+            ]);
+        }
+        finally {
+            if (onAbort)
+                signal?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+export const SUBAGENT_TOOLS = [
+    { name: 'subagent_start', description: 'Start a helper in the background while continuing main work. Model and effort inherit the main agent unless overridden in /agents. Roles: ui-ux, code, minor, oracle, reviewer, coder, researcher. Helpers can only read project files; researchers can fetch public HTTPS pages. No helper can edit files or run commands.',
+        parameters: { type: 'object', properties: { role: { type: 'string', enum: SUBAGENT_ROLES }, task: { type: 'string', description: 'specific independent question, max 4000 characters' } }, required: ['role', 'task'] }, requiresApproval: false },
+    { name: 'subagent_status', description: 'Check background helpers; omit id to list jobs, or pass a job id to retrieve its final findings. You may continue main work while a job runs.',
+        parameters: { type: 'object', properties: { id: { type: 'integer', minimum: 1 } } }, requiresApproval: false },
+];