conductor-remote 1.116.0 → 1.118.0

package/dist-node/src/mcp/tools/chats.js

@@ -0,0 +1,194 @@
+import { routes } from "../../routes.js";
+import { isToolResult, timestampMs, workspaceTitle } from "../../shared.js";
+import { chatCursor, parseChatCursor } from "../../transcript/cursor.js";
+import { need, num, str } from "../arguments.js";
+import { boundedTranscript, clip, unmark } from "../formatters.js";
+export function createSearchChatsTool(call) {
+    return {
+        name: 'search_chats',
+        description: 'Full-text search every Conductor chat on this Mac, archived workspaces included, and get back the workspaces that discussed it with the matching excerpts. Use this to answer "which workspace did I do X in" or "what did we decide about X". Searches the prompts the user typed, the agent replies and the agent\'s reasoning, not tool output. Each excerpt is tagged [user], [assistant] or [thinking] — a [thinking] hit is reasoning the agent never said out loud, so do not quote it back as its answer. Every excerpt carries its own session_id and cursor for a bounded nearby read_chat.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Plain words, ranked by relevance; wrap a "phrase in quotes" to require it word for word. Other punctuation and operators are ignored, not parsed.'
+                },
+                limit: { type: 'number', description: 'Max workspaces to return (default 12, max 50).' },
+                repo: {
+                    type: 'string',
+                    description: 'Only workspaces in this repo, by the exact name list_repos prints. Ranking happens inside the repo, so a rare mention there is not buried by busier repos.'
+                }
+            },
+            required: ['query']
+        },
+        run: async (args) => {
+            const query = need(args, 'query');
+            const limit = num(args.limit);
+            const repo = typeof args.repo === 'string' && args.repo.trim() ? args.repo.trim() : null;
+            const params = new URLSearchParams({ q: query });
+            if (limit)
+                params.set('limit', String(limit));
+            if (repo)
+                params.set('repo', repo);
+            const data = await call(`${routes.search.path()}?${params}`);
+            const lines = [];
+            if (data.index.error)
+                lines.push(`! chat index unavailable (${data.index.error}) — names matched only`);
+            else if (!data.index.ready)
+                lines.push(`! still indexing (${Math.round(data.index.progress * 100)}%) — older chats not searchable yet`);
+            const scope = repo ? ` in ${repo}` : '';
+            if (!data.results.length)
+                return [...lines, `no workspace or chat matches ${JSON.stringify(query)}${scope}`].join('\n');
+            for (const r of data.results) {
+                const w = r.workspace;
+                const tags = [w.repo_name, w.branch, w.archived ? 'ARCHIVED' : w.state].filter(Boolean).join(' · ');
+                lines.push('');
+                lines.push(`## ${workspaceTitle(w)}`);
+                lines.push(`${tags}${r.byName ? ' · name match' : ''}`);
+                lines.push(`workspace_id: ${w.id}${r.sessionId ? `  session_id: ${r.sessionId}` : ''}`);
+                if (r.hits)
+                    lines.push(`${r.hits} matching message${r.hits === 1 ? '' : 's'}:`);
+                for (const s of r.snippets) {
+                    lines.push(`  [${s.role}] ${clip(unmark(s.text), 400)}`);
+                    lines.push(`    session_id: ${s.sessionId}  cursor: ${s.cursor}`);
+                }
+            }
+            return lines.join('\n').trim();
+        }
+    };
+}
+export function createReadChatTool(call) {
+    return {
+        name: 'read_chat',
+        description: 'Read a bounded Conductor chat transcript by session_id, newest messages last. Pass a cursor from search_chats or a prior read_chat as near; before and after expand either direction or both together. For a [thinking] search hit, set include_thinking true to include the matching block. Without near, returns the trailing entries. Works for archived workspaces. Tool calls and failed tool output are summarised to one line each; prose is verbatim unless the output budget truncates it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: { type: 'string', description: 'From search_chats or list_chats.' },
+                near: { type: 'string', description: 'A cursor from search_chats or a prior read_chat.' },
+                before: { type: 'number', description: 'Entries before near to return (default 6, max 100).' },
+                after: { type: 'number', description: 'Entries after near to return (default 6, max 100).' },
+                limit: {
+                    type: 'number',
+                    description: 'Trailing entries when near is omitted (default 12, max 400).'
+                },
+                max_chars: {
+                    type: 'number',
+                    description: 'Hard result-size budget (default 12000, min 1000, max 40000).'
+                },
+                include_thinking: { type: 'boolean', description: 'Include the agent’s reasoning (default false).' },
+                include_tools: {
+                    type: 'boolean',
+                    description: 'Include tool calls and failed tool output (default false).'
+                }
+            },
+            required: ['session_id']
+        },
+        run: async (args) => {
+            const sessionId = need(args, 'session_id');
+            const near = str(args.near);
+            const anchor = near ? parseChatCursor(near) : null;
+            if (near && anchor === null)
+                throw new Error('near must be a cursor returned by search_chats');
+            const count = (value, fallback) => Math.min(100, Math.max(0, Math.floor(num(value) ?? fallback)));
+            const before = count(args.before, 6);
+            const after = count(args.after, 6);
+            const limit = Math.min(400, Math.max(1, Math.floor(num(args.limit) ?? 12)));
+            const maxChars = Math.min(40_000, Math.max(1_000, Math.floor(num(args.max_chars) ?? 12_000)));
+            // One flag each, because they answer different questions: tools are what the agent
+            // *did*, thinking is why it did it. Reading both off `include_tools` meant the only
+            // way to see the reasoning was to take the tool churn along with it.
+            const includeTools = args.include_tools === true;
+            const includeThinking = args.include_thinking === true;
+            const data = await call(`${routes.messages.path(sessionId)}?after=0`, {
+                timeoutMs: 30_000
+            });
+            if (anchor !== null && !data.entries.some(entry => entry.rowid === anchor)) {
+                throw new Error('near cursor is not in that session');
+            }
+            const wanted = data.entries.filter(e => {
+                if (e.role === 'thinking')
+                    return includeThinking;
+                // A successful result carries the call's output, which is the churn `include_tools`
+                // exists to keep out of a context window — the call above it already says what ran.
+                // A failed one stays: one line, and it is why the turn changed course.
+                if (isToolResult(e) && !e.error)
+                    return false;
+                if (e.role === 'tool')
+                    return includeTools;
+                return true;
+            });
+            if (!wanted.length)
+                return `no messages in session ${sessionId}`;
+            let selected;
+            const head = [];
+            if (anchor === null) {
+                selected = wanted.slice(-limit);
+                if (selected.length < wanted.length) {
+                    head.push(`(last ${selected.length} of ${wanted.length} entries · older_cursor: ${chatCursor(selected[0].rowid)})`);
+                }
+            }
+            else {
+                const older = wanted.filter(entry => entry.rowid < anchor);
+                const at = wanted.filter(entry => entry.rowid === anchor);
+                const newer = wanted.filter(entry => entry.rowid > anchor);
+                selected = [...(before ? older.slice(-before) : []), ...at, ...newer.slice(0, after)];
+                const parts = [
+                    `near ${near}`,
+                    `${Math.min(before, older.length)} before`,
+                    `${at.length} at`,
+                    `${Math.min(after, newer.length)} after`
+                ];
+                if (older.length > before && selected[0])
+                    parts.push(`older_cursor: ${chatCursor(selected[0].rowid)}`);
+                if (newer.length > after && selected.at(-1)) {
+                    parts.push(`newer_cursor: ${chatCursor(selected.at(-1).rowid)}`);
+                }
+                head.push(`(${parts.join(' · ')})`);
+            }
+            if (!selected.length) {
+                return boundedTranscript(head, ['(the matching entry is excluded by the current role filters)'], maxChars);
+            }
+            const rendered = selected.map(entry => {
+                if (entry.role === 'tool')
+                    return `[tool ${entry.tool ?? ''}] ${clip(entry.text, 200)}${entry.detail ? ` — ${entry.detail}` : ''}`;
+                return `[${entry.role}] ${entry.text}`;
+            });
+            return boundedTranscript(head, rendered, maxChars);
+        }
+    };
+}
+export function createListChatsTool(call) {
+    return {
+        name: 'list_chats',
+        description: 'List the chat tabs in a workspace with each one’s status, model and how full its context window is. A workspace can hold several conversations, each with its own context; send_prompt and read_chat address one of them.',
+        inputSchema: {
+            type: 'object',
+            properties: { workspace_id: { type: 'string' } },
+            required: ['workspace_id']
+        },
+        run: async (args) => {
+            const id = need(args, 'workspace_id');
+            const data = await call(routes.sessions.path(id));
+            if (!data.sessions.length)
+                return `no chats in workspace ${id}`;
+            // Context is per chat and only per chat — the same workspace can hold a tab at 85%
+            // beside one at 28% — so it is printed on every row rather than summarised above.
+            return data.sessions
+                .map(s => {
+                const ctx = typeof s.context_used_percent === 'number' && s.context_used_percent > 0
+                    ? ` · ${Math.round(s.context_used_percent)}% context`
+                    : '';
+                // A chat waiting on a background task reads `idle` in `status` and will resume
+                // itself; an agent that reads only the status would call it done and send a
+                // second prompt into the wait.
+                const waiting = (s.background_tasks ?? []).map(t => `\n    waiting for task: ${t.description} (${Math.max(0, Math.round((Date.now() - timestampMs(t.since)) / 60_000))}m so far)`);
+                const glyph = s.status === 'working' ? '▶' : waiting.length ? '⧗' : '·';
+                const role = data.session_roles?.[s.id];
+                return `${glyph} ${s.title ?? '(untitled)'} — ${s.status ?? '?'} · ${s.model ?? '?'}${role ? ` · role ${role.role}` : ''}${ctx}\n    session_id: ${s.id}${waiting.join('')}`;
+            })
+                .join('\n');
+        }
+    };
+}

package/dist-node/src/mcp/tools/delegation.js

@@ -0,0 +1,135 @@
+import { routes } from "../../routes.js";
+import { parseChatCursor } from "../../transcript/cursor.js";
+import { need, rejectUnknown, str } from "../arguments.js";
+export function createListRolesTool(call) {
+    return {
+        name: 'list_roles',
+        description: 'List configured models, effort, Fast mode, instructions, and validation issues before lightweight delegation. Choose a role whose current configuration fits the task. Invalid roles cannot start a child or new Workflow. Active Workflows use the frozen roles from their root envelope.',
+        inputSchema: { type: 'object', properties: {} },
+        run: async () => {
+            const data = await call(routes.roles.path());
+            const issueByRole = new Map(data.issues.map(issue => [issue.role, issue.error]));
+            const lines = Object.entries(data.roles).map(([name, role]) => {
+                const settings = [role.model, role.effort, role.fast === undefined ? null : role.fast ? 'fast on' : 'fast off']
+                    .filter(Boolean)
+                    .join(' · ');
+                const issue = issueByRole.get(name);
+                const instructions = role.preamble?.trim();
+                return `${issue ? '!' : '·'} ${name}: ${settings}${issue ? ` — ${issue.code}: ${issue.message}` : ''}${instructions ? `\n    Instructions: ${instructions.replaceAll('\n', '\n    ')}` : ''}`;
+            });
+            if (data.warning)
+                lines.unshift(`! ${data.warning}`);
+            return lines.join('\n') || 'no delegated roles are configured';
+        }
+    };
+}
+export function createDelegateTaskTool(call) {
+    return {
+        name: 'delegate_task',
+        description: 'Spawn one lightweight tracked sibling chat in a subtab. From an ordinary chat, pass session_id, a valid role from list_roles, and a focused prompt. Choose a configured role whose instructions fit the task; repeat for independent questions so children can run concurrently. This does not start a Workflow or turn the parent into a planner. The role must use a different provider than the parent. The child follows the configured preamble and assignment, receives a transcript attachment, and returns its result. Queue mode delivers behind the current turn by default; use steer if the result is needed during this turn. Keep working and integrate the result. For an active Workflow, only its root may call with workflow_id and current phase_capability from the private envelope; its frozen settings, role restrictions, transcript boundary, and Baton routing apply. Returns immediately with a delegation id; list_delegations observes progress. The relay later opens/configures/sends the child through the Mac UI. This tool cannot start or recover a Workflow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflow_id: { type: 'string', description: 'Active Workflow only: id from the private root envelope.' },
+                phase_capability: {
+                    type: 'string',
+                    description: 'Opaque current-phase capability from that same envelope; never copy it elsewhere.'
+                },
+                session_id: { type: 'string', description: 'Parent chat id; an active Workflow requires its root session.' },
+                role: { type: 'string', description: 'Configured role name. Workflows allow exploration or implementation.' },
+                prompt: {
+                    type: 'string',
+                    description: 'The independent question or implementation brief, including file ownership for edits.'
+                },
+                return_mode: {
+                    type: 'string',
+                    enum: ['queue', 'steer'],
+                    description: 'Ordinary chats only. Queue the Baton behind this turn (default), or steer it into a running turn.'
+                },
+                through: {
+                    type: 'string',
+                    description: 'Ordinary chats only. Optional read_chat cursor bounding the transcript handoff.'
+                },
+                include_thinking: {
+                    type: 'boolean',
+                    description: 'Ordinary chats only. Include parent reasoning in the handoff (default false).'
+                }
+            },
+            required: ['session_id', 'role', 'prompt'],
+            additionalProperties: false
+        },
+        run: async (args) => {
+            if (!Object.hasOwn(args, 'workflow_id') && !Object.hasOwn(args, 'phase_capability')) {
+                rejectUnknown(args, ['session_id', 'role', 'prompt', 'return_mode', 'through', 'include_thinking']);
+                const sessionId = need(args, 'session_id');
+                if (args.return_mode !== undefined && args.return_mode !== 'queue' && args.return_mode !== 'steer') {
+                    throw new Error('return_mode must be queue or steer');
+                }
+                if (args.include_thinking !== undefined && typeof args.include_thinking !== 'boolean') {
+                    throw new Error('include_thinking must be a boolean');
+                }
+                const through = args.through === undefined ? undefined : parseChatCursor(need(args, 'through'));
+                if (through === null)
+                    throw new Error('through must be a read_chat cursor');
+                const body = {
+                    role: need(args, 'role'),
+                    prompt: need(args, 'prompt'),
+                    ...(args.return_mode === undefined ? {} : { returnMode: args.return_mode }),
+                    ...(through === undefined ? {} : { throughRowid: through }),
+                    ...(args.include_thinking === undefined ? {} : { includeThinking: args.include_thinking })
+                };
+                const result = await call(routes.delegateTask.path(sessionId), {
+                    method: routes.delegateTask.method,
+                    body
+                });
+                if (!result.ok)
+                    throw new Error(`${result.error.code}: ${result.error.message}`);
+                return `delegation ${result.delegationId} queued · ${result.role} · ${result.model}`;
+            }
+            rejectUnknown(args, ['workflow_id', 'phase_capability', 'session_id', 'role', 'prompt']);
+            const workflowId = need(args, 'workflow_id');
+            const sessionId = need(args, 'session_id');
+            const role = need(args, 'role');
+            if (role !== 'exploration' && role !== 'implementation')
+                throw new Error('role is invalid');
+            const body = {
+                workflow_id: workflowId,
+                phase_capability: need(args, 'phase_capability'),
+                session_id: sessionId,
+                role,
+                prompt: need(args, 'prompt')
+            };
+            const result = await call(routes.workflowDelegation.path(workflowId), {
+                method: routes.workflowDelegation.method,
+                body
+            });
+            if (!result.ok)
+                throw new Error(`${result.error.code}: ${result.error.message}`);
+            return `delegation ${result.delegationId} queued · ${result.role} · ${result.model}`;
+        }
+    };
+}
+export function createListDelegationsTool(call) {
+    return {
+        name: 'list_delegations',
+        description: 'List active and failed delegated jobs. Successful jobs leave their chats and role chips, not a second history log.',
+        inputSchema: {
+            type: 'object',
+            properties: { workspace_id: { type: 'string', description: 'Optional workspace filter.' } }
+        },
+        run: async (args) => {
+            const workspaceId = str(args.workspace_id);
+            const suffix = workspaceId ? `?workspaceId=${encodeURIComponent(workspaceId)}` : '';
+            const data = await call(`${routes.delegations.path()}${suffix}`);
+            if (!data.delegations.length)
+                return 'no active or failed delegations';
+            return data.delegations
+                .map(job => {
+                const child = job.childSessionId ? ` · child ${job.childSessionId}` : '';
+                const failure = job.failure ? ` · ${job.failure.code}: ${job.failure.message}` : '';
+                return `${job.status} · ${job.role} · ${job.resolvedRole.model} · ${job.id}${child}${failure}`;
+            })
+                .join('\n');
+        }
+    };
+}

package/dist-node/src/mcp/tools/system.js

@@ -0,0 +1,135 @@
+import { routes } from "../../routes.js";
+import { num, str } from "../arguments.js";
+import { clip, relative, stamp } from "../formatters.js";
+export function createPlanUsageTool(call) {
+    return {
+        name: 'plan_usage',
+        description: 'Read rolling Claude Code and Codex subscription allowances from their local CLIs: percentage used and reset time. Sends no model prompt and touches no Conductor UI. Cursor Agent and OpenCode explain why no comparable plan quota is available.',
+        inputSchema: { type: 'object', properties: {} },
+        run: async () => {
+            const data = await call(routes.planUsage.path(), { timeoutMs: 15_000 });
+            const sections = data.providers.map(provider => {
+                const head = `## ${provider.label}${provider.plan ? ` · ${provider.plan}` : ''}`;
+                if (provider.status !== 'available')
+                    return `${head}\n${provider.message ?? 'unavailable'}`;
+                const lines = provider.buckets.flatMap(bucket => bucket.windows.map(window => {
+                    const bucketName = provider.buckets.length > 1 ? `${bucket.label} — ` : '';
+                    const reset = window.resetsAt === null ? 'reset unavailable' : `resets ${new Date(window.resetsAt).toISOString()}`;
+                    return `- ${bucketName}${window.label}: ${Math.round(window.usedPercent)}% used · ${reset}`;
+                }));
+                return `${head}\n${lines.join('\n')}`;
+            });
+            return `${sections.join('\n\n')}\n\nupdated ${new Date(data.fetchedAt).toISOString()}`;
+        }
+    };
+}
+export function createDismissPromptTool(call) {
+    return {
+        name: 'dismiss_prompt',
+        description: 'Throw away a prompt the relay is still holding — a new workspace’s first prompt waiting on setup, or one parked behind a locked Mac. Touches no UI. list_workspaces shows these; a failed one stays visible until it is dismissed, on purpose. Pass session_id for a parked prompt, workspace_id for a first prompt.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: { type: 'string', description: 'Dismiss the prompt parked for this chat.' },
+                workspace_id: { type: 'string', description: 'Dismiss this workspace’s undelivered first prompt.' }
+            }
+        },
+        run: async (args) => {
+            const sessionId = str(args.session_id);
+            const workspaceId = str(args.workspace_id);
+            // Both would be two deletes wearing one name, and the caller could not tell which
+            // half failed — so it is one or the other, never both.
+            if (!sessionId && !workspaceId)
+                throw new Error('pass session_id or workspace_id');
+            if (sessionId && workspaceId)
+                throw new Error('pass session_id or workspace_id, not both');
+            const route = sessionId ? routes.dismissParkedPrompt : routes.dismissFirstPrompt;
+            await call(route.path((sessionId ?? workspaceId)), { method: route.method });
+            return 'dismissed';
+        }
+    };
+}
+export function createKeepAwakeTool(call) {
+    return {
+        name: 'keep_awake',
+        description: 'Read or set the window that holds this Mac awake with the lid shut. Touches no UI. This is what keeps the relay reachable at all, so a long unattended run wants it: without it a closed lid sleeps the Mac and every agent on it stops. Needs `conductor-remote nosleep setup` to have been run once; without that the status says so and holding fails. Releasing a window while the lid is shut sleeps the Mac straight away.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['status', 'hold', 'release'],
+                    description: 'Default status.'
+                },
+                seconds: { type: 'number', description: 'How long to hold it awake. Required for hold.' }
+            }
+        },
+        run: async (args) => {
+            const action = str(args.action) ?? 'status';
+            if (action === 'status') {
+                const s = await call(routes.nosleep.path());
+                if (!s.available)
+                    return 'unavailable — run `conductor-remote nosleep setup` on the Mac first';
+                if (!s.armed)
+                    return `sleeping normally; a window can be up to ${s.maxSeconds}s`;
+                return `awake${s.until ? `, expires ${relative(s.until)}` : ' until stopped'} (pid ${s.pid})`;
+            }
+            if (action === 'release') {
+                const r = await call(routes.disarmNoSleep.path(), { method: routes.disarmNoSleep.method });
+                if (!r.ok)
+                    throw new Error(r.error ?? 'could not release the window');
+                return r.willSleep ? 'released — the lid is shut, so the Mac is going to sleep now' : 'released';
+            }
+            if (action !== 'hold')
+                throw new Error(`unknown action ${action}`);
+            const seconds = num(args.seconds);
+            if (seconds === undefined)
+                throw new Error('seconds is required for hold');
+            const r = await call(routes.armNoSleep.path(), {
+                method: routes.armNoSleep.method,
+                body: { seconds }
+            });
+            if (!r.ok)
+                throw new Error(r.error ?? 'could not hold the Mac awake');
+            return `awake${r.state.until ? `, expires ${relative(r.state.until)}` : ''}`;
+        }
+    };
+}
+export function createRelayLogsTool(call) {
+    return {
+        name: 'relay_logs',
+        description: 'The relay’s own log — why a send failed, whether Conductor refused Accessibility, what the network did. Touches no UI. Default is the running relay’s captured console; `file` tails the daemon’s log on disk, which is the only place a *previous* process’s crash survives. Secrets are redacted before it leaves the relay.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file: {
+                    type: 'string',
+                    enum: ['relay.log', 'relay.err.log'],
+                    description: 'Omit for this process’s live log.'
+                },
+                limit: { type: 'number', description: 'Most recent N lines. Default 200, max 2000.' },
+                contains: {
+                    type: 'string',
+                    description: 'Keep only lines containing this (case-insensitive). Filtered here, not by the relay.'
+                }
+            }
+        },
+        run: async (args) => {
+            const file = str(args.file);
+            const limit = Math.min(2000, Math.max(1, Math.trunc(num(args.limit) ?? 200)));
+            const q = new URLSearchParams({ limit: String(limit) });
+            if (file)
+                q.set('file', file);
+            const data = await call(`${routes.logs.path()}?${q}`);
+            const needle = str(args.contains)?.toLowerCase();
+            const kept = needle ? data.entries.filter(e => e.text.toLowerCase().includes(needle)) : data.entries;
+            if (!kept.length)
+                return needle ? `no line in ${data.source} matches ${needle}` : `${data.source} is empty`;
+            const lines = kept.map(e => `${stamp(e.t)} ${e.level === 'info' ? '' : `${e.level.toUpperCase()} `}${clip(e.text, 2000)}`);
+            // Whose log this is decides what it proves: an unmanaged relay's files belong to a
+            // *different* process, so a clean tail there says nothing about the one just called.
+            const head = data.managed ? data.source : `${data.source} (written by the LaunchAgent, not the relay just called)`;
+            return [`— ${head}, ${kept.length} lines —`, ...lines].join('\n');
+        }
+    };
+}

package/dist-node/src/mcp/tools/voice.js

@@ -0,0 +1,136 @@
+import { routes } from "../../routes.js";
+import { need, num, rejectUnknown, str } from "../arguments.js";
+import { boundedTranscript, clip, unmark, voiceCallHeader, voiceEntryFlags } from "../formatters.js";
+export function createListVoiceCallsTool(call) {
+    return {
+        name: 'list_voice_calls',
+        description: 'List saved fleet voice calls on this Mac, newest first, with dates, previews and call_id values for read_voice_call. These transcripts are separate from Conductor chat history. Read-only; no live call or UI interaction.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'integer', description: 'Calls per page (default 20, max 50).' },
+                offset: {
+                    type: 'integer',
+                    description: 'Skip this many calls; use next_offset from the previous page (default 0).'
+                }
+            },
+            additionalProperties: false
+        },
+        run: async (args) => {
+            rejectUnknown(args, ['limit', 'offset']);
+            const limit = Math.min(50, Math.max(1, Math.floor(num(args.limit) ?? 20)));
+            const offset = Math.min(1_000_000, Math.max(0, Math.floor(num(args.offset) ?? 0)));
+            const params = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+            const data = await call(`${routes.voiceHistory.path()}?${params}`);
+            if (!data.calls.length)
+                return 'No saved voice calls on this page. Only calls captured after transcript saving was enabled are available.';
+            return [
+                ...data.calls.map(item => [...voiceCallHeader(item), clip(item.preview.replace(/\s+/g, ' '), 200)].join('\n')),
+                ...(data.hasMore ? [`next_offset: ${offset + data.calls.length}`] : [])
+            ].join('\n\n');
+        }
+    };
+}
+export function createSearchVoiceCallsTool(call) {
+    return {
+        name: 'search_voice_calls',
+        description: 'Search caller and assistant text across saved fleet calls. Results include matching excerpts, call_id and item_id; pass those to read_voice_call as call_id and near to read surrounding decisions. Partial and interrupted text is labeled. Read-only; no UI interaction.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    maxLength: 500,
+                    description: 'Words ranked by relevance; quote an exact phrase. Uses the same query grammar as search_chats.'
+                },
+                call_id: { type: 'string', description: 'Optional: search only this saved call.' },
+                limit: { type: 'integer', description: 'Matching utterances per page (default 12, max 50).' },
+                offset: {
+                    type: 'integer',
+                    description: 'Skip this many hits; use next_offset from the previous page (default 0).'
+                }
+            },
+            required: ['query'],
+            additionalProperties: false
+        },
+        run: async (args) => {
+            rejectUnknown(args, ['query', 'call_id', 'limit', 'offset']);
+            const query = need(args, 'query');
+            if (query.length > 500)
+                throw new Error('query must be at most 500 characters');
+            const limit = Math.min(50, Math.max(1, Math.floor(num(args.limit) ?? 12)));
+            const offset = Math.min(1_000_000, Math.max(0, Math.floor(num(args.offset) ?? 0)));
+            const params = new URLSearchParams({ q: query, limit: String(limit), offset: String(offset) });
+            if (str(args.call_id))
+                params.set('callId', str(args.call_id));
+            const data = await call(`${routes.voiceSearch.path()}?${params}`);
+            if (!data.hits.length)
+                return `No saved voice transcript matches ${JSON.stringify(query)} on this page.`;
+            return [
+                ...data.hits.map(hit => [
+                    ...voiceCallHeader(hit.call),
+                    `item_id: ${hit.itemId} · ${new Date(hit.at).toISOString()}`,
+                    `[${hit.role}]${voiceEntryFlags(hit)} ${clip(unmark(hit.snippet), 500)}`
+                ].join('\n')),
+                ...(data.hasMore ? [`next_offset: ${offset + data.hits.length}`] : [])
+            ].join('\n\n');
+        }
+    };
+}
+export function createReadVoiceCallTool(call) {
+    return {
+        name: 'read_voice_call',
+        description: 'Read a saved fleet-call transcript by call_id, with caller, orchestrator and tool activity in conversation order. Pass an item_id from search_voice_calls as near for surrounding context, or use older_item/newer_item from a previous read. Without near, reads the latest entries. Text can be clipped to max_chars; narrow the window or raise that budget to read more. Interrupted replies can include generated words the caller never heard. Read-only; no UI interaction.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                call_id: { type: 'string', description: 'From list_voice_calls or search_voice_calls.' },
+                near: { type: 'string', description: 'A transcript item_id from a search hit or previous read.' },
+                before: { type: 'integer', description: 'Entries before near (default 6, max 100).' },
+                after: { type: 'integer', description: 'Entries after near (default 6, max 100).' },
+                limit: { type: 'integer', description: 'Latest entries when near is omitted (default 20, max 200).' },
+                max_chars: { type: 'integer', description: 'Hard output budget (default 12000, min 1000, max 40000).' }
+            },
+            required: ['call_id'],
+            additionalProperties: false
+        },
+        run: async (args) => {
+            rejectUnknown(args, ['call_id', 'near', 'before', 'after', 'limit', 'max_chars']);
+            const callId = need(args, 'call_id');
+            const data = await call(routes.voiceTranscript.path(callId));
+            const entries = data.entries.filter(entry => entry.role !== 'relay');
+            const near = str(args.near);
+            const anchor = near ? entries.findIndex(entry => entry.id === near) : -1;
+            if (near && anchor === -1)
+                throw new Error('near item is not in that saved call');
+            const count = (value, fallback, max) => Math.min(max, Math.max(0, Math.floor(num(value) ?? fallback)));
+            const limit = Math.max(1, count(args.limit, 20, 200));
+            let start = near ? Math.max(0, anchor - count(args.before, 6, 100)) : Math.max(0, entries.length - limit);
+            let end = near ? Math.min(entries.length, anchor + count(args.after, 6, 100) + 1) : entries.length;
+            const maxChars = Math.max(1_000, count(args.max_chars, 12_000, 40_000));
+            const heading = (entry) => `[${entry.role}] item_id: ${entry.id} · ${new Date(entry.at).toISOString()}${voiceEntryFlags(entry)}\n`;
+            // Keep identities and caveats readable even for a tiny budget. Shrink the
+            // window around its anchor, then advertise the omitted sides for paging.
+            while (end - start > 1) {
+                const minRow = Math.max(...entries.slice(start, end).map(entry => heading(entry).length)) + 80;
+                if (voiceCallHeader(data).join('\n').length + 240 + (end - start) * (minRow + 2) <= maxChars)
+                    break;
+                if (!near || anchor - start > end - anchor - 1)
+                    start += 1;
+                else
+                    end -= 1;
+            }
+            const selected = entries.slice(start, end);
+            const head = [
+                ...voiceCallHeader(data),
+                `Showing ${selected.length} of ${entries.length} entries.`,
+                ...(start > 0 && selected[0] ? [`older_item: ${selected[0].id} (use as near with before > 0)`] : []),
+                ...(end < entries.length && selected.at(-1)
+                    ? [`newer_item: ${selected.at(-1).id} (use as near with after > 0)`]
+                    : [])
+            ];
+            const rendered = selected.map(entry => `${heading(entry)}${entry.text}`);
+            return boundedTranscript(head, rendered, maxChars);
+        }
+    };
+}