@blockrun/franklin 3.0.0

package/dist/agent/permissions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Permission system for runcode.
+ * Controls which tools can execute automatically vs. require user approval.
+ */
+export type PermissionBehavior = 'allow' | 'deny' | 'ask';
+export interface PermissionRules {
+    allow: string[];
+    deny: string[];
+    ask: string[];
+}
+export type PermissionMode = 'default' | 'trust' | 'deny-all' | 'plan';
+export interface PermissionDecision {
+    behavior: PermissionBehavior;
+    reason?: string;
+}
+export declare class PermissionManager {
+    private rules;
+    private mode;
+    private sessionAllowed;
+    private promptFn?;
+    constructor(mode?: PermissionMode, promptFn?: (toolName: string, description: string) => Promise<'yes' | 'no' | 'always'>);
+    /**
+     * Check if a tool can be used. Returns the decision.
+     */
+    check(toolName: string, input: Record<string, unknown>): Promise<PermissionDecision>;
+    /**
+     * Prompt the user interactively for permission.
+     * Uses injected promptFn (Ink UI) when available, falls back to readline.
+     * pendingCount: how many more operations of this type are waiting (including this one).
+     * Returns true if allowed, false if denied.
+     */
+    promptUser(toolName: string, input: Record<string, unknown>, pendingCount?: number): Promise<boolean>;
+    private loadRules;
+    private matchesRule;
+    private getPrimaryInputValue;
+    private globMatch;
+    private sessionKey;
+    private describeAction;
+}

package/dist/agent/permissions.js

@@ -0,0 +1,226 @@
+/**
+ * Permission system for runcode.
+ * Controls which tools can execute automatically vs. require user approval.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import chalk from 'chalk';
+import { BLOCKRUN_DIR } from '../config.js';
+// ─── Default Rules ─────────────────────────────────────────────────────────
+const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebSearch', 'Task', 'AskUser', 'ImageGen']);
+const DESTRUCTIVE_TOOLS = new Set(['Write', 'Edit', 'Bash']);
+const DEFAULT_RULES = {
+    allow: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'AskUser', 'ImageGen'],
+    deny: [],
+    ask: ['Write', 'Edit', 'Bash', 'Agent'],
+};
+// ─── Permission Manager ────────────────────────────────────────────────────
+export class PermissionManager {
+    rules;
+    mode;
+    sessionAllowed = new Set(); // "always allow" for this session
+    promptFn;
+    constructor(mode = 'default', promptFn) {
+        this.mode = mode;
+        this.rules = this.loadRules();
+        this.promptFn = promptFn;
+    }
+    /**
+     * Check if a tool can be used. Returns the decision.
+     */
+    async check(toolName, input) {
+        // Trust mode: allow everything
+        if (this.mode === 'trust') {
+            return { behavior: 'allow', reason: 'trust mode' };
+        }
+        // Plan mode: only allow read-only tools
+        if (this.mode === 'plan') {
+            if (READ_ONLY_TOOLS.has(toolName)) {
+                return { behavior: 'allow', reason: 'plan mode — read-only' };
+            }
+            return { behavior: 'deny', reason: 'plan mode — use /execute to enable writes' };
+        }
+        // Deny-all mode: deny everything that isn't read-only
+        if (this.mode === 'deny-all') {
+            if (READ_ONLY_TOOLS.has(toolName)) {
+                return { behavior: 'allow', reason: 'read-only tool' };
+            }
+            return { behavior: 'deny', reason: 'deny-all mode' };
+        }
+        // Check session-level always-allow
+        const sessionKey = this.sessionKey(toolName, input);
+        if (this.sessionAllowed.has(toolName) || this.sessionAllowed.has(sessionKey)) {
+            return { behavior: 'allow', reason: 'session allow' };
+        }
+        // Check explicit deny rules
+        if (this.matchesRule(toolName, input, this.rules.deny)) {
+            return { behavior: 'deny', reason: 'denied by rule' };
+        }
+        // Check explicit allow rules
+        if (this.matchesRule(toolName, input, this.rules.allow)) {
+            return { behavior: 'allow', reason: 'allowed by rule' };
+        }
+        // Check explicit ask rules
+        if (this.matchesRule(toolName, input, this.rules.ask)) {
+            return { behavior: 'ask' };
+        }
+        // Default: read-only tools are auto-allowed, others ask
+        if (READ_ONLY_TOOLS.has(toolName)) {
+            return { behavior: 'allow', reason: 'read-only default' };
+        }
+        return { behavior: 'ask' };
+    }
+    /**
+     * Prompt the user interactively for permission.
+     * Uses injected promptFn (Ink UI) when available, falls back to readline.
+     * pendingCount: how many more operations of this type are waiting (including this one).
+     * Returns true if allowed, false if denied.
+     */
+    async promptUser(toolName, input, pendingCount = 1) {
+        const description = this.describeAction(toolName, input);
+        // Append pending-count hint so user knows to press [a] to skip all
+        const hint = pendingCount > 1
+            ? `${description}\n  │ \x1b[33m${pendingCount} pending — press [a] to allow all\x1b[0m`
+            : description;
+        // Ink UI path: use injected prompt function to avoid stdin conflict.
+        // Ink owns stdin in raw mode; a second readline would get EOF immediately.
+        if (this.promptFn) {
+            const result = await this.promptFn(toolName, hint);
+            if (result === 'always') {
+                this.sessionAllowed.add(toolName);
+                return true;
+            }
+            return result === 'yes';
+        }
+        // Readline fallback (basic terminal / piped mode)
+        console.error('');
+        console.error(chalk.yellow('  ╭─ Permission required ─────────────────'));
+        console.error(chalk.yellow(`  │ ${toolName}`));
+        console.error(chalk.dim(`  │ ${description}`));
+        if (pendingCount > 1) {
+            console.error(chalk.yellow(`  │ ${pendingCount} pending — press [a] to allow all`));
+        }
+        console.error(chalk.yellow('  ╰─────────────────────────────────────'));
+        const answer = await askQuestion(chalk.bold('  Allow? ') + chalk.dim('[Y/a/n] '));
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === 'a' || normalized === 'always') {
+            this.sessionAllowed.add(toolName);
+            console.error(chalk.green(`  ✓ ${toolName} allowed for this session`));
+            return true;
+        }
+        if (normalized === 'y' || normalized === 'yes' || normalized === '') {
+            return true;
+        }
+        console.error(chalk.red(`  ✗ ${toolName} denied`));
+        return false;
+    }
+    // ─── Internal ──────────────────────────────────────────────────────────
+    loadRules() {
+        const configPath = path.join(BLOCKRUN_DIR, 'runcode-permissions.json');
+        try {
+            if (fs.existsSync(configPath)) {
+                const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                return {
+                    allow: [...DEFAULT_RULES.allow, ...(raw.allow || [])],
+                    deny: [...(raw.deny || [])],
+                    ask: [...DEFAULT_RULES.ask, ...(raw.ask || [])],
+                };
+            }
+        }
+        catch { /* use defaults */ }
+        return { ...DEFAULT_RULES };
+    }
+    matchesRule(toolName, input, rules) {
+        for (const rule of rules) {
+            // Exact tool name match
+            if (rule === toolName)
+                return true;
+            // Pattern match: "Bash(git *)" matches Bash with command starting with "git "
+            const patternMatch = rule.match(/^(\w+)\((.+)\)$/);
+            if (patternMatch) {
+                const [, ruleTool, pattern] = patternMatch;
+                if (ruleTool !== toolName)
+                    continue;
+                // Match against the primary input field
+                const primaryValue = this.getPrimaryInputValue(toolName, input);
+                if (primaryValue && this.globMatch(pattern, primaryValue)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    getPrimaryInputValue(toolName, input) {
+        switch (toolName) {
+            case 'Bash': return input.command || null;
+            case 'Read': return input.file_path || null;
+            case 'Write': return input.file_path || null;
+            case 'Edit': return input.file_path || null;
+            default: return null;
+        }
+    }
+    globMatch(pattern, text) {
+        // Glob matching: * matches non-space chars, ** matches anything
+        const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        const regex = new RegExp('^' +
+            escaped
+                .replace(/\*\*/g, '{{GLOB_STAR}}')
+                .replace(/\*/g, '[^ ]*')
+                .replace(/\{\{GLOB_STAR\}\}/g, '.*')
+            + '$');
+        return regex.test(text);
+    }
+    sessionKey(toolName, input) {
+        const primary = this.getPrimaryInputValue(toolName, input);
+        return primary ? `${toolName}:${primary}` : toolName;
+    }
+    describeAction(toolName, input) {
+        switch (toolName) {
+            case 'Bash': {
+                const cmd = input.command || '';
+                return `Execute: ${cmd.length > 100 ? cmd.slice(0, 100) + '...' : cmd}`;
+            }
+            case 'Write': {
+                const fp = input.file_path || '';
+                return `Write file: ${fp}`;
+            }
+            case 'Edit': {
+                const fp = input.file_path || '';
+                const old = input.old_string || '';
+                return `Edit ${fp}: replace "${old.slice(0, 60)}${old.length > 60 ? '...' : ''}"`;
+            }
+            case 'Agent':
+                return `Launch sub-agent: ${input.description || input.prompt?.slice(0, 80) || 'task'}`;
+            default:
+                return JSON.stringify(input).slice(0, 120);
+        }
+    }
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function askQuestion(prompt) {
+    // Non-TTY (piped/scripted) input: cannot ask interactively — auto-allow.
+    // The caller (permissionMode logic in start.ts) already routes piped sessions
+    // to trust mode, so this path is rarely hit. Guard here for safety.
+    if (!process.stdin.isTTY) {
+        process.stderr.write(prompt + 'y (auto-approved: non-interactive mode)\n');
+        return Promise.resolve('y');
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+    });
+    return new Promise((resolve) => {
+        let answered = false;
+        rl.question(prompt, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(answer);
+        });
+        rl.on('close', () => {
+            if (!answered)
+                resolve('n'); // Default deny on EOF for safety
+        });
+    });
+}

package/dist/agent/reduce.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Token Reduction for runcode.
+ * Original implementation — reduces context size through intelligent pruning.
+ *
+ * Strategy: instead of compression/encoding, we PRUNE redundant content.
+ * The model doesn't need verbose tool outputs from 20 turns ago.
+ *
+ * Three reduction passes:
+ * 1. Tool result aging — progressively shorten old tool results
+ * 2. Whitespace normalization — remove excessive blank lines and indentation
+ * 3. Stale context removal — drop system info that's been superseded
+ */
+import type { Dialogue } from './types.js';
+/**
+ * Progressively shorten tool results based on age.
+ * Recent results: keep full. Older results: keep summary. Very old: keep one line.
+ *
+ * This is the biggest token saver — a 10KB bash output from 20 turns ago
+ * can be reduced to "✓ Bash: ran npm test (exit 0)" saving ~2500 tokens.
+ */
+export declare function ageToolResults(history: Dialogue[]): Dialogue[];
+/**
+ * Normalize whitespace in text messages.
+ * - Collapse 3+ blank lines to 2
+ * - Remove trailing spaces
+ * - Reduce indentation beyond 8 spaces to 8
+ */
+export declare function normalizeWhitespace(history: Dialogue[]): Dialogue[];
+/**
+ * Trim very long assistant text messages from old turns.
+ * Recent messages: keep full. Old long messages: keep first 1000 chars.
+ */
+export declare function trimOldAssistantMessages(history: Dialogue[]): Dialogue[];
+/**
+ * Remove consecutive duplicate messages (same role + same content).
+ */
+export declare function deduplicateMessages(history: Dialogue[]): Dialogue[];
+/**
+ * Collapse repeated consecutive lines within tool results.
+ * "Fetching...\nFetching...\nFetching...\n" → "Fetching... ×3"
+ * Also strips any residual ANSI escape codes from older tool results.
+ * RTK-inspired: dedup_lines + strip_ansi pipeline stages.
+ */
+export declare function deduplicateToolResultLines(history: Dialogue[]): Dialogue[];
+/**
+ * Run all token reduction passes on conversation history.
+ * Returns same reference if nothing changed (cheap identity check).
+ */
+export declare function reduceTokens(history: Dialogue[], debug?: boolean): Dialogue[];

package/dist/agent/reduce.js

@@ -0,0 +1,317 @@
+/**
+ * Token Reduction for runcode.
+ * Original implementation — reduces context size through intelligent pruning.
+ *
+ * Strategy: instead of compression/encoding, we PRUNE redundant content.
+ * The model doesn't need verbose tool outputs from 20 turns ago.
+ *
+ * Three reduction passes:
+ * 1. Tool result aging — progressively shorten old tool results
+ * 2. Whitespace normalization — remove excessive blank lines and indentation
+ * 3. Stale context removal — drop system info that's been superseded
+ */
+// ─── 1. Tool Result Aging ─────────────────────────────────────────────────
+/**
+ * Progressively shorten tool results based on age.
+ * Recent results: keep full. Older results: keep summary. Very old: keep one line.
+ *
+ * This is the biggest token saver — a 10KB bash output from 20 turns ago
+ * can be reduced to "✓ Bash: ran npm test (exit 0)" saving ~2500 tokens.
+ */
+export function ageToolResults(history) {
+    // Find all tool_result positions
+    const toolPositions = [];
+    for (let i = 0; i < history.length; i++) {
+        const msg = history[i];
+        if (msg.role === 'user' &&
+            Array.isArray(msg.content) &&
+            msg.content.some(p => p.type === 'tool_result')) {
+            toolPositions.push(i);
+        }
+    }
+    if (toolPositions.length <= 3)
+        return history; // Nothing to age
+    const result = [...history];
+    const totalResults = toolPositions.length;
+    for (let idx = 0; idx < toolPositions.length; idx++) {
+        const pos = toolPositions[idx];
+        const age = totalResults - idx; // Higher = older
+        const msg = result[pos];
+        if (!Array.isArray(msg.content))
+            continue;
+        const parts = msg.content;
+        let modified = false;
+        const aged = parts.map(part => {
+            if (part.type !== 'tool_result')
+                return part;
+            const content = typeof part.content === 'string'
+                ? part.content
+                : JSON.stringify(part.content);
+            const charLen = content.length;
+            // Recent 3 results: keep full
+            if (age <= 3)
+                return part;
+            // Age 4-8: keep first 500 chars
+            if (age <= 8 && charLen > 500) {
+                modified = true;
+                const truncated = content.slice(0, 500);
+                const lastNl = truncated.lastIndexOf('\n');
+                const clean = lastNl > 250 ? truncated.slice(0, lastNl) : truncated;
+                return {
+                    ...part,
+                    content: `${clean}\n... (${charLen - clean.length} chars omitted, ${age} turns ago)`,
+                };
+            }
+            // Age 9-15: keep first 200 chars
+            if (age <= 15 && charLen > 200) {
+                modified = true;
+                const firstLine = content.split('\n')[0].slice(0, 150);
+                return {
+                    ...part,
+                    content: `${firstLine}\n... (${charLen} chars, ${age} turns ago)`,
+                };
+            }
+            // Age 16+: one line summary
+            if (age > 15 && charLen > 80) {
+                modified = true;
+                const summary = content.split('\n')[0].slice(0, 60);
+                return {
+                    ...part,
+                    content: part.is_error
+                        ? `[Error: ${summary}...]`
+                        : `[Result: ${summary}...]`,
+                };
+            }
+            return part;
+        });
+        if (modified) {
+            result[pos] = { role: 'user', content: aged };
+        }
+    }
+    return result;
+}
+// ─── 2. Whitespace Normalization ──────────────────────────────────────────
+/**
+ * Normalize whitespace in text messages.
+ * - Collapse 3+ blank lines to 2
+ * - Remove trailing spaces
+ * - Reduce indentation beyond 8 spaces to 8
+ */
+export function normalizeWhitespace(history) {
+    let modified = false;
+    const result = history.map(msg => {
+        if (typeof msg.content !== 'string')
+            return msg;
+        const original = msg.content;
+        const cleaned = original
+            .replace(/[ \t]+$/gm, '') // Trailing spaces
+            .replace(/\n{4,}/g, '\n\n\n') // Max 3 consecutive newlines
+            .replace(/^( {9,})/gm, '        '); // Cap indentation at 8 spaces
+        if (cleaned !== original) {
+            modified = true;
+            return { ...msg, content: cleaned };
+        }
+        return msg;
+    });
+    return modified ? result : history;
+}
+// ─── 3. Verbose Assistant Message Trimming ────────────────────────────────
+/**
+ * Trim very long assistant text messages from old turns.
+ * Recent messages: keep full. Old long messages: keep first 1000 chars.
+ */
+export function trimOldAssistantMessages(history) {
+    const MAX_OLD_ASSISTANT_CHARS = 1500;
+    const KEEP_RECENT = 4; // Keep last 4 assistant messages full
+    let assistantCount = 0;
+    for (const msg of history) {
+        if (msg.role === 'assistant')
+            assistantCount++;
+    }
+    if (assistantCount <= KEEP_RECENT)
+        return history;
+    let seenAssistant = 0;
+    let modified = false;
+    const result = history.map(msg => {
+        if (msg.role !== 'assistant')
+            return msg;
+        seenAssistant++;
+        // Keep recent messages full
+        if (assistantCount - seenAssistant < KEEP_RECENT)
+            return msg;
+        if (typeof msg.content === 'string' && msg.content.length > MAX_OLD_ASSISTANT_CHARS) {
+            modified = true;
+            const truncated = msg.content.slice(0, MAX_OLD_ASSISTANT_CHARS);
+            const lastNl = truncated.lastIndexOf('\n');
+            const clean = lastNl > MAX_OLD_ASSISTANT_CHARS / 2 ? truncated.slice(0, lastNl) : truncated;
+            return { ...msg, content: clean + '\n... (response truncated)' };
+        }
+        // Also handle content array with text parts
+        if (Array.isArray(msg.content)) {
+            const parts = msg.content;
+            let totalChars = 0;
+            for (const p of parts) {
+                if (p.type === 'text')
+                    totalChars += p.text.length;
+            }
+            if (totalChars > MAX_OLD_ASSISTANT_CHARS) {
+                modified = true;
+                const trimmedParts = parts.map(p => {
+                    if (p.type !== 'text' || p.text.length <= 500)
+                        return p;
+                    return { ...p, text: p.text.slice(0, 500) + '\n... (trimmed)' };
+                });
+                return { ...msg, content: trimmedParts };
+            }
+        }
+        return msg;
+    });
+    return modified ? result : history;
+}
+// ─── 4. Deduplication ─────────────────────────────────────────────────────
+/**
+ * Remove consecutive duplicate messages (same role + same content).
+ */
+export function deduplicateMessages(history) {
+    if (history.length < 3)
+        return history;
+    const result = [history[0]];
+    let modified = false;
+    for (let i = 1; i < history.length; i++) {
+        const prev = history[i - 1];
+        const curr = history[i];
+        if (curr.role === prev.role && typeof curr.content === 'string' && curr.content === prev.content) {
+            modified = true;
+            continue;
+        }
+        result.push(curr);
+    }
+    return modified ? result : history;
+}
+// ─── 5. Line-level deduplication in tool results ──────────────────────────
+const ANSI_RE_REDUCE = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+/**
+ * Collapse repeated consecutive lines within tool results.
+ * "Fetching...\nFetching...\nFetching...\n" → "Fetching... ×3"
+ * Also strips any residual ANSI escape codes from older tool results.
+ * RTK-inspired: dedup_lines + strip_ansi pipeline stages.
+ */
+export function deduplicateToolResultLines(history) {
+    let modified = false;
+    const result = history.map(msg => {
+        if (msg.role !== 'user' || !Array.isArray(msg.content))
+            return msg;
+        const parts = msg.content;
+        let partModified = false;
+        const newParts = parts.map(part => {
+            if (part.type !== 'tool_result')
+                return part;
+            const raw = typeof part.content === 'string' ? part.content : JSON.stringify(part.content);
+            // Strip ANSI codes
+            const stripped = raw.replace(ANSI_RE_REDUCE, '');
+            // Collapse repeated consecutive lines
+            const lines = stripped.split('\n');
+            const deduped = [];
+            let i = 0;
+            while (i < lines.length) {
+                const line = lines[i];
+                let count = 1;
+                while (i + count < lines.length && lines[i + count] === line)
+                    count++;
+                if (count > 2 && line.trim() !== '') {
+                    deduped.push(`${line} ×${count}`);
+                }
+                else {
+                    for (let k = 0; k < count; k++)
+                        deduped.push(line);
+                }
+                i += count;
+            }
+            const result = deduped.join('\n');
+            if (result === raw)
+                return part;
+            partModified = true;
+            return { ...part, content: result };
+        });
+        if (!partModified)
+            return msg;
+        modified = true;
+        return { ...msg, content: newParts };
+    });
+    return modified ? result : history;
+}
+// ─── Pipeline ───────���───────────────────���─────────────────────────────────
+/**
+ * Run all token reduction passes on conversation history.
+ * Returns same reference if nothing changed (cheap identity check).
+ */
+export function reduceTokens(history, debug) {
+    if (history.length < 8)
+        return history; // Skip for short conversations
+    let current = history;
+    let totalSaved = 0;
+    // Pass 1: Age old tool results
+    const aged = ageToolResults(current);
+    if (aged !== current) {
+        const before = estimateChars(current);
+        current = aged;
+        const saved = before - estimateChars(current);
+        totalSaved += saved;
+    }
+    // Pass 2: Normalize whitespace
+    const normalized = normalizeWhitespace(current);
+    if (normalized !== current) {
+        const before = estimateChars(current);
+        current = normalized;
+        totalSaved += before - estimateChars(current);
+    }
+    // Pass 3: Trim old verbose assistant messages
+    const trimmed = trimOldAssistantMessages(current);
+    if (trimmed !== current) {
+        const before = estimateChars(current);
+        current = trimmed;
+        totalSaved += before - estimateChars(current);
+    }
+    // Pass 4: Remove consecutive duplicate messages
+    const deduped = deduplicateMessages(current);
+    if (deduped !== current) {
+        const before = estimateChars(current);
+        current = deduped;
+        totalSaved += before - estimateChars(current);
+    }
+    // Pass 5: Strip ANSI + collapse repeated lines in tool results
+    const lineDeduped = deduplicateToolResultLines(current);
+    if (lineDeduped !== current) {
+        const before = estimateChars(current);
+        current = lineDeduped;
+        totalSaved += before - estimateChars(current);
+    }
+    if (debug && totalSaved > 500) {
+        const tokensSaved = Math.round(totalSaved / 4);
+        console.error(`[runcode] Token reduction: ~${tokensSaved} tokens saved`);
+    }
+    return current;
+}
+function estimateChars(history) {
+    let total = 0;
+    for (const msg of history) {
+        if (typeof msg.content === 'string') {
+            total += msg.content.length;
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const p of msg.content) {
+                if ('type' in p) {
+                    if (p.type === 'text')
+                        total += p.text.length;
+                    else if (p.type === 'tool_result') {
+                        total += typeof p.content === 'string' ? p.content.length : JSON.stringify(p.content).length;
+                    }
+                    else if (p.type === 'tool_use') {
+                        total += JSON.stringify(p.input).length;
+                    }
+                }
+            }
+        }
+    }
+    return total;
+}

package/dist/agent/streaming-executor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Streaming Tool Executor for runcode.
+ * Starts executing concurrent-safe tools while the model is still streaming.
+ * Non-concurrent tools wait until the full response is received.
+ */
+import type { CapabilityHandler, CapabilityInvocation, CapabilityResult, ExecutionScope } from './types.js';
+import type { PermissionManager } from './permissions.js';
+export declare class StreamingExecutor {
+    private handlers;
+    private scope;
+    private permissions?;
+    private onStart;
+    private onProgress?;
+    private pending;
+    constructor(opts: {
+        handlers: Map<string, CapabilityHandler>;
+        scope: ExecutionScope;
+        permissions?: PermissionManager;
+        onStart: (id: string, name: string, preview?: string) => void;
+        onProgress?: (id: string, text: string) => void;
+    });
+    /**
+     * Called when a tool_use block is fully received from the stream.
+     * If the tool is concurrent-safe, start executing immediately.
+     * Otherwise, queue it for later.
+     */
+    onToolReceived(invocation: CapabilityInvocation): void;
+    /**
+     * After the model finishes streaming, execute any non-concurrent tools
+     * and collect all results (including concurrent ones that may already be done).
+     */
+    collectResults(allInvocations: CapabilityInvocation[]): Promise<[CapabilityInvocation, CapabilityResult][]>;
+    private executeWithPermissions;
+    /** Extract a short preview string from a tool invocation's input. */
+    private inputPreview;
+}