mixdog 1.4.0 → 1.4.2

package/src/runtime/connectors/connector-accounts-mcp.mjs

@@ -1,20 +1,32 @@
-// The one MCP server of a multi-account connector (connector-catalog.mjs
-// connectorAccountsOf): Gmail, Google Calendar or Google Drive with every
-// connected account behind one tool set. Answered in-process like the
-// one-account servers it fronts (google-mcp.mjs, gmail-app-password.mjs):
-// each tool takes `account` (the account's address), and the call goes to
-// that account's own endpoint with that account's own credentials (its OAuth
-// tokens, or its app password from the keychain). With one account
-// `account` may be left out; with several, a call naming none is refused
-// with the list, so the model asks the user. An account that fails stays
-// listed with why (connectorAccountHealth); the server only fails to start
-// when no account can be used.
+// The one MCP server of a catalog connector (connector-catalog.mjs
+// connectorAccountsOf): every connected account of Gmail, Notion, Postgres…
+// behind one tool set, answered in-process. Underneath, each account is its
+// own ordinary MCP connection with its own credentials (client-transport.mjs
+// connectorAccountClient), and its tools are the ones its backend lists. This
+// server lists their union (a tool whose schema differs between accounts is
+// left out), each with one more optional argument, `account` (an account's
+// address or name), which never reaches the account.
+//
+// The account a call uses: the one it names; else the one last used in its
+// conversation, else the connector's last-used account (connectorAccountInUse),
+// else the topmost connected account. A named or remembered account that is
+// switched off, removed or needs a sign-in fails the call with the usable
+// accounts listed; no other account ever stands in for it. A conversation's
+// call (`_meta[CONVERSATION_META]`) makes its account the last used, for the
+// conversation and the connector. Every result of a call made on an account,
+// errors included, says which account answered. A name binds a call to one
+// account; an address or label two accounts share binds none.
+// An account that fails stays listed with why (connectorAccountHealth); the
+// server only fails to start when no account can be used.
+import { join } from 'node:path';
+import { readJsonStateSync, updateJsonAtomicSync } from '../shared/atomic-file.mjs';
 import { accountsOfInstructions, connectorAccountsInstructions } from '../shared/connector-accounts.mjs';
 import { connectorById } from '../shared/connector-catalog.mjs';
-import { gmailAppPasswordTools } from './gmail-app-password.mjs';
-import { googleMcpTools } from './google-mcp.mjs';
+import { resolvePluginData } from '../shared/plugin-paths.mjs';
 
 const PROTOCOL_VERSION = '2025-06-18';
+/** The `_meta` key of a tools/call that names the conversation it is made in. */
+export const CONVERSATION_META = 'mixdog/conversation';
 
 const json = (status, body) =>
   new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
@@ -36,66 +48,158 @@ export function forgetConnectorAccountHealth(name) {
   health.delete(name);
 }
 
-const ACCOUNT_PROPERTY = Object.freeze({
-  type: 'string',
-  description:
-    'The account to act as (its email address). May be left out when one account is connected; required when several are.',
-});
+// ── The last-used account ───────────────────────────────────────────────────
+// Per connector, in the data dir (every runtime reads the same one); per
+// conversation, in memory (the newest conversations kept).
+const ACCOUNTS_IN_USE_FILE = 'connector-accounts-in-use.json';
+const inUseFile = () => join(resolvePluginData(), ACCOUNTS_IN_USE_FILE);
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const validInUse = (value) => {
+  if (!isRecord(value)) throw new Error('the accounts in use must be an object');
+  return value;
+};
 
-const SERVICE_OF = { gmail: 'gmail', 'google-calendar': 'calendar', 'google-drive': 'drive' };
-
-/** The tools of `connector` over `accounts`, each taking `account`. Gmail on
- *  an app password has the larger set (IMAP); a Google sign-in Gmail account
- *  answers the tools it has and refuses the others. */
-function connectorTools(connector, accounts, { hidden = false } = {}) {
-  const tools =
-    connector === 'gmail' && accounts.some((account) => account.appPassword)
-      ? gmailAppPasswordTools({ hidden })
-      : googleMcpTools(SERVICE_OF[connector]);
-  return tools.map((tool) => ({
-    ...tool,
-    inputSchema: {
-      ...tool.inputSchema,
-      properties: { ...(tool.inputSchema?.properties || {}), account: ACCOUNT_PROPERTY },
-    },
-  }));
+/** The name of the account catalog connector `connector` used last, '' when
+ *  none was recorded. */
+export function connectorAccountInUse(connector) {
+  const stored = readJsonStateSync(inUseFile(), { validate: validInUse, fallback: {} });
+  return typeof stored[connector] === 'string' ? stored[connector] : '';
 }
 
-class AccountChoiceError extends Error {}
+function rememberAccountInUse(connector, name) {
+  if (connectorAccountInUse(connector) === name) return;
+  updateJsonAtomicSync(inUseFile(), (current) => ({ ...(isRecord(current) ? current : {}), [connector]: name }));
+}
 
-const labelOf = (account) => account.email || account.name;
+const CONVERSATIONS_KEPT = 500;
+// conversation → (connector → account name), oldest first.
+const conversations = new Map();
 
-/** The account a call names (by address, or by its account name), or its
- *  only account; throws the account list otherwise. */
-function pickAccount(accounts, value, service) {
-  const list = accounts.map(labelOf).join(', ');
-  const wanted = text(value).toLowerCase();
-  if (wanted) {
-    const found = accounts.find(
-      (account) => account.email.toLowerCase() === wanted || account.name.toLowerCase() === wanted
-    );
-    if (!found) throw new AccountChoiceError(`Unknown ${service} account "${text(value)}". Accounts: ${list}.`);
-    return found;
+/** Account `name` of `connector` was removed: wherever it is the last used it
+ *  stays a removed account, so a call that would default to it keeps failing
+ *  closed, even once a new account is given the same name. */
+export function retireConnectorAccount(connector, name) {
+  const removed = `${name} (removed)`;
+  for (const own of conversations.values()) if (own.get(connector) === name) own.set(connector, removed);
+  if (connectorAccountInUse(connector) === name) rememberAccountInUse(connector, removed);
+}
+
+function rememberConversationAccount(conversation, connector, name) {
+  const own = conversations.get(conversation) || new Map();
+  conversations.delete(conversation);
+  own.set(connector, name);
+  conversations.set(conversation, own);
+  if (conversations.size > CONVERSATIONS_KEPT) conversations.delete(conversations.keys().next().value);
+}
+
+const ACCOUNT_PROPERTY = Object.freeze({
+  type: 'string',
+  description: 'The account to use (its email address or account name). Left out: the account used last.',
+});
+
+/** `value` as JSON with every object's keys sorted, so equal schemas compare
+ *  equal whatever order their keys were written in. */
+const canonical = (value) => {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (isRecord(value)) {
+    const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+};
+
+/** The tools every account lists, once each, with `account` added; a tool
+ *  two accounts list with different schemas is left out. */
+function unionTools(states) {
+  const first = new Map();
+  const differs = new Set();
+  for (const { tools = [] } of states) {
+    for (const tool of tools) {
+      const seen = first.get(tool.name);
+      if (!seen) first.set(tool.name, tool);
+      else if (canonical(seen.inputSchema) !== canonical(tool.inputSchema)) differs.add(tool.name);
+    }
   }
-  if (accounts.length === 1) return accounts[0];
-  throw new AccountChoiceError(
-    `Several ${service} accounts are connected: ${list}. Ask the user which one, then pass it as \`account\`.`
-  );
+  return [...first.values()]
+    .filter((tool) => !differs.has(tool.name))
+    .map((tool) => ({
+      ...tool,
+      inputSchema: {
+        type: 'object',
+        ...tool.inputSchema,
+        properties: { ...(tool.inputSchema?.properties || {}), account: ACCOUNT_PROPERTY },
+      },
+    }));
 }
 
 const noteOf = (state) => (state.authRequired ? 'needs sign-in' : 'unavailable');
+const usable = (account) => health.get(account.name)?.authRequired !== true;
+
+/** `result` saying which account answered it (`label`). */
+const withAccountNote = (result, service, label) => ({
+  ...result,
+  content: [
+    ...(Array.isArray(result?.content) ? result.content : []),
+    { type: 'text', text: `(${service} account: ${label})` },
+  ],
+});
 
 /**
  * A `fetch` answering the accounts server of `connector` in-process. Each of
- * `accounts` is `{ name, email, appPassword, request(message, { signal }) }`:
- * `request` sends one JSON-RPC message to that account's own endpoint with its own
- * credentials and resolves the JSON-RPC reply; it throws when the account
- * cannot be reached (an `authRequired` error when it needs a sign-in).
+ * `accounts` is `{ name, email, connect(signal), callTool(params, { signal, onprogress }) }`:
+ * `connect` resolves `{ instructions, tools }` of that account's own MCP
+ * connection, `callTool` sends it one tools/call (reporting its progress to
+ * `onprogress`, when given) and resolves the result; both
+ * throw when the account cannot be reached (an `authRequired` error when it
+ * needs a sign-in). The fetch carries `connectorAccounts`: `{ connector,
+ * choose({ tool, wanted, conversation }) }`, `{ name, label }` of the account
+ * such a call would use (it throws the refusal otherwise), for binding a call
+ * to its account (by its unique name) before it is approved.
  */
 export function withConnectorAccountsMcp({ connector, accounts }) {
   const service = connectorById(connector)?.name || connector;
-  const listed = connectorTools(connector, accounts);
-  const callable = connectorTools(connector, accounts, { hidden: true });
+  // account name → the names of the tools it lists (set once it answered).
+  const toolsOf = new Map();
+  let listed = [];
+  const same = (a, b) => Boolean(a) && a.toLowerCase() === b.toLowerCase();
+  /** What an account is called to the model: its address, with its name when
+   *  another account shares that address. */
+  const labelOf = (account) => {
+    if (!account.email) return account.name;
+    const shared = accounts.some((other) => other !== account && same(other.email, account.email));
+    return shared ? `${account.email} (${account.name})` : account.email;
+  };
+  /** The account a call uses (see the header); throws the refusal. */
+  const choose = ({ tool, wanted, conversation }) => {
+    const refuse = (why) => {
+      const list = accounts.filter(usable).map(labelOf).join(', ') || 'none';
+      return new Error(`${why} Usable ${service} accounts: ${list}. Pass one as \`account\`.`);
+    };
+    const named = text(wanted);
+    let account;
+    if (named) {
+      // Its unique name, else the one account its address or label is.
+      let matches = accounts.filter((one) => same(one.name, named));
+      if (!matches.length) matches = accounts.filter((one) => same(one.email, named) || same(labelOf(one), named));
+      if (!matches.length) throw refuse(`No connected ${service} account is "${named}".`);
+      if (matches.length > 1) {
+        const names = matches.map((one) => one.name).join(', ');
+        throw refuse(`"${named}" is more than one ${service} account (${names}); name one.`);
+      }
+      [account] = matches;
+    } else {
+      const remembered =
+        (conversation && conversations.get(conversation)?.get(connector)) || connectorAccountInUse(connector);
+      account = remembered ? accounts.find((one) => one.name === remembered) : accounts[0];
+      if (!account) throw refuse(`The ${service} account used last (${remembered}) is not connected now.`);
+    }
+    if (!usable(account)) throw refuse(`${labelOf(account)} needs a sign-in in Connectors.`);
+    const has = toolsOf.get(account.name);
+    if (has && !has.has(tool) && listed.some((one) => one.name === tool)) {
+      throw refuse(`${labelOf(account)} has no ${tool} tool.`);
+    }
+    return account;
+  };
   const record = (account, state) => {
     if (state.email) account.email = state.email;
     health.set(account.name, {
@@ -109,13 +213,13 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
     record(account, state);
     return state;
   };
-  // Each account's own initialize: whether it can be used, and its address.
+  // Each account's own connection: whether it can be used, its address and tools.
   const probe = async (account, signal) => {
     try {
-      const reply = await account.request({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, { signal });
-      if (reply?.error) return failure(account, new Error(reply.error.message || 'The account did not start'));
-      const [email = ''] = accountsOfInstructions(reply?.result?.instructions);
-      const state = { email: account.email || email };
+      const { instructions, tools } = await account.connect(signal);
+      toolsOf.set(account.name, new Set(tools.map((tool) => tool.name)));
+      const [email = ''] = accountsOfInstructions(instructions);
+      const state = { email: account.email || email, instructions, tools };
       record(account, state);
       return state;
     } catch (error) {
@@ -125,7 +229,9 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
   // The calls in flight by JSON-RPC id, so a `notifications/cancelled` for one
   // aborts its downstream request.
   const inflight = new Map();
-  async function rpc(message, transportSignal) {
+  /** One JSON-RPC request's reply; `notify` sends a notification ahead of it
+   *  (a tools/call's progress). */
+  async function rpc(message, transportSignal, notify = null) {
     const { id, method, params } = message || {};
     const reply = (result) => ({ jsonrpc: '2.0', id, result });
     if (method === 'initialize') {
@@ -138,55 +244,69 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
           error: { code: -32001, message: first?.error || `No ${service} account is connected` },
         };
       }
+      listed = unionTools(states);
+      // What the accounts' own servers tell the model (an in-process Google
+      // account's only names its address, which the account list says).
+      const own = [
+        ...new Set(
+          states.map((state) => text(state.instructions)).filter((one) => one && !accountsOfInstructions(one).length)
+        ),
+      ];
+      const accountsLine = connectorAccountsInstructions(
+        accounts.map((account, index) => ({
+          email: labelOf(account),
+          ...(states[index].error ? { note: noteOf(states[index]) } : {}),
+        }))
+      );
       return reply({
         protocolVersion: text(params?.protocolVersion) || PROTOCOL_VERSION,
         capabilities: { tools: { listChanged: false } },
         serverInfo: { name: `mixdog-${connector}`, version: '1.0.0' },
-        instructions: connectorAccountsInstructions(
-          accounts.map((account, index) => ({
-            email: labelOf(account),
-            ...(states[index].error ? { note: noteOf(states[index]) } : {}),
-          }))
-        ),
+        instructions: [accountsLine, ...own].filter(Boolean).join('\n\n') || undefined,
       });
     }
     if (method === 'ping') return reply({});
     if (method === 'tools/list') return reply({ tools: listed });
     if (method === 'tools/call') {
       const name = params?.name;
-      if (!callable.some((tool) => tool.name === name)) {
-        return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${name}` } };
-      }
-      const { account: chosen, ...args } = params?.arguments || {};
+      const { account: wanted, ...args } = params?.arguments || {};
+      const conversation = text(params?._meta?.[CONVERSATION_META]);
       let account;
       try {
-        account = pickAccount(accounts, chosen, service);
+        account = choose({ tool: name, wanted, conversation });
+        if (conversation) {
+          rememberConversationAccount(conversation, connector, account.name);
+          rememberAccountInUse(connector, account.name);
+        }
       } catch (error) {
-        return reply(errorResult(error.message));
+        return reply(errorResult(error?.message || String(error)));
       }
       const cancel = new AbortController();
       const signal = transportSignal ? AbortSignal.any([transportSignal, cancel.signal]) : cancel.signal;
       inflight.set(id, cancel);
+      // The account's progress reaches the caller under the caller's own token,
+      // so it resets the call's deadline as a direct server's progress does.
+      const progressToken = params?._meta?.progressToken;
+      const onprogress =
+        notify && progressToken !== undefined
+          ? (progress) => notify({ jsonrpc: '2.0', method: 'notifications/progress', params: { ...progress, progressToken } })
+          : undefined;
       try {
-        const answer = await account.request(
-          { jsonrpc: '2.0', id, method, params: { name, arguments: args } },
-          { signal }
-        );
-        if (answer?.error) return reply(errorResult(`${labelOf(account)}: ${answer.error.message}`));
+        // An unlisted tool (one only the approval gate calls) is the account's to answer.
+        const result = await account.callTool({ name, arguments: args }, { signal, onprogress });
         if (health.get(account.name)?.error) record(account, {});
-        return reply(answer?.result ?? errorResult(`${labelOf(account)}: no answer`));
+        return reply(withAccountNote(result, service, labelOf(account)));
       } catch (error) {
         // A cancelled call says nothing about the account's health.
-        if (signal.aborted) return reply(errorResult(`${labelOf(account)}: cancelled`));
-        const state = failure(account, error);
-        return reply(errorResult(`${labelOf(account)}: ${state.error}`));
+        const why = signal.aborted ? 'cancelled' : failure(account, error).error;
+        return reply(withAccountNote(errorResult(why), service, labelOf(account)));
       } finally {
         inflight.delete(id);
       }
     }
     return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
   }
-  return async (input, init) => {
+  const fetchImpl = async (input, init) => {
     const request = input instanceof Request ? input : null;
     if (String(request?.method || init?.method || 'GET').toUpperCase() !== 'POST') {
       return new Response(null, { status: 405, headers: { allow: 'POST' } });
@@ -203,28 +323,41 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
     for (const one of batch) {
       if (one?.method === 'notifications/cancelled') inflight.get(one.params?.requestId)?.abort();
     }
+    // A call asking for progress is answered as an event stream: its progress
+    // notifications, then its reply.
+    if (!Array.isArray(message) && message?.id !== undefined && message.params?._meta?.progressToken !== undefined) {
+      const encoder = new TextEncoder();
+      let open = true;
+      const stream = new ReadableStream({
+        start(controller) {
+          const send = (payload) => {
+            if (open) controller.enqueue(encoder.encode(`event: message\ndata: ${JSON.stringify(payload)}\n\n`));
+          };
+          void rpc(message, signal, send).then((answer) => {
+            send(answer);
+            if (open) controller.close();
+            open = false;
+          });
+        },
+        // The caller stopped reading (its call was aborted).
+        cancel() {
+          open = false;
+        },
+      });
+      return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+    }
     const replies = (await Promise.all(batch.map((one) => (one?.id === undefined ? null : rpc(one, signal))))).filter(
       Boolean
     );
     if (!replies.length) return new Response(null, { status: 202 });
     return json(200, Array.isArray(message) ? replies : replies[0]);
   };
-}
-
-/** `request` for an account answered at `url` through `fetchImpl` (its
- *  credentials applied there) with `headers`: one JSON-RPC POST, its reply. */
-export function connectorAccountRequest(url, fetchImpl, headers = {}) {
-  return async (message, { signal } = {}) => {
-    const response = await fetchImpl(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...headers },
-      body: JSON.stringify(message),
-      signal,
-    });
-    if (!response.ok) {
-      await response.body?.cancel();
-      throw new Error(`The account's server answered ${response.status}`);
-    }
-    return response.json();
+  fetchImpl.connectorAccounts = {
+    connector,
+    choose: (call) => {
+      const account = choose(call);
+      return { name: account.name, label: labelOf(account) };
+    },
   };
+  return fetchImpl;
 }

package/src/runtime/connectors/gmail-app-password.mjs

@@ -723,9 +723,9 @@ const TOOLS = [
 ];
 
 /** The tool definitions (name, description, schema, annotations) the server
- *  lists; with `hidden`, also the ones only the approval gate calls. */
-export function gmailAppPasswordTools({ hidden = false } = {}) {
-  return TOOLS.filter((tool) => hidden || !tool.hidden).map(({ run, hidden: _hidden, ...tool }) => tool);
+ *  lists: never the ones only the approval gate calls. */
+export function gmailAppPasswordTools() {
+  return TOOLS.filter((tool) => !tool.hidden).map(({ run, hidden: _hidden, ...tool }) => tool);
 }
 
 // ── The MCP server at the reserved address ──────────────────────────────────

package/src/runtime/explore/explorer.mjs

@@ -0,0 +1,93 @@
+// One explorer: the agent loop driven directly with one fixed system prompt
+// and the read-only filesystem tools — no session record, rules, skills,
+// profile context or persistence.
+import { agentLoop } from '../agent/orchestrator/session/agent-loop.mjs';
+import { readOnlyFilesystemTools } from '../agent/orchestrator/session/manager/tool-resolution.mjs';
+import { sharedPrefixProviderCacheOpts } from '../agent/orchestrator/agent-runtime/cache-strategy.mjs';
+import { partialHandoffTextFromSession } from '../agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs';
+
+// Tool-calling responses before the explorer must answer from what it has.
+export const EXPLORER_MAX_TOOL_ROUNDS = 10;
+
+export const EXPLORER_SYSTEM_PROMPT = [
+  'You explore the working directory read-only to answer one question. You cannot edit, run commands or delegate.',
+  '',
+  'Search:',
+  `- You have ${EXPLORER_MAX_TOOL_ROUNDS} tool rounds: batch independent searches in one turn (parallel calls or array arguments).`,
+  "- Search the question's own nouns, and match the subsystem it names, not a similarly named one.",
+  '- Locate first, then read only that window.',
+  '- A location a tool returned is final; never reconfirm it.',
+  '- Before answering, list the parts the question asks about; each needs its own tool-returned `path:line`.',
+  '- Cite implementation, not tests, docs or changelogs, unless asked.',
+  '- A part without a `path:line`: search again with different terms, or use `code_graph` on a found symbol (definition, callers, writers). Call it missing only after that search, and name what you searched.',
+  '- Stop once every part has its location.',
+  '',
+  'Answer shape, hard limit 1,500 characters, nothing else:',
+  '- One short answer line.',
+  '- One evidence line per hop of each part (entry, callee, writer, reader), at most 10 lines: `path:line` from tool output, the exact function or symbol name there, a few words.',
+  '- No intro, summary, extra locations, notes about unread code or "Open:" lines.',
+].join('\n');
+
+// One list for the process: identical schema bytes for every explorer.
+const EXPLORER_TOOLS = readOnlyFilesystemTools();
+export const EXPLORER_TOOL_NAMES = Object.freeze(EXPLORER_TOOLS.map((tool) => tool.name));
+
+/** Exact provider prefix inputs, for cache-stability checks. */
+export function explorerPrefix() {
+  return { system: EXPLORER_SYSTEM_PROMPT, tools: EXPLORER_TOOLS };
+}
+
+/**
+ * Answer `query` on `route` with `provider`. Resolves the answer text (on a
+ * salvage-flagged abort, the text written so far); rejects on failure.
+ */
+export async function runExplorer({ query, route, provider, cwd = null, signal, ownerSessionId = null }) {
+  const tools = EXPLORER_TOOLS.slice();
+  const messages = [
+    { role: 'system', content: EXPLORER_SYSTEM_PROMPT },
+    { role: 'user', content: query },
+  ];
+  // In-memory policy only: the schema allowlist is also the execution
+  // allowlist (pre-dispatch-deny.mjs), and the owner ids attribute spend in
+  // the usage ledger. No session id, so nothing session-keyed is created.
+  const policy = {
+    provider: route.provider,
+    model: route.model,
+    cwd,
+    tools,
+    schemaAllowedTools: EXPLORER_TOOL_NAMES,
+    compaction: { auto: false },
+    ownerSessionId,
+    parentSessionId: ownerSessionId,
+  };
+  // Text of the request in flight, for salvage when the deadline cuts it.
+  let streamed = '';
+  try {
+    const response = await agentLoop(provider, messages, route.model, tools, null, cwd, {
+      signal,
+      session: policy,
+      ...(route.effort ? { effort: route.effort } : {}),
+      fast: route.fast === true,
+      modelParameters: route.modelParameters || {},
+      turnLimits: { maxToolRounds: EXPLORER_MAX_TOOL_ROUNDS },
+      ...sharedPrefixProviderCacheOpts(route.provider),
+      onProviderSendStarted: () => {
+        streamed = '';
+      },
+      onTextDelta: (chunk) => {
+        streamed += typeof chunk === 'string' ? chunk : '';
+      },
+      onTextReset: ({ chars } = {}) => {
+        streamed = streamed.slice(0, Math.max(0, streamed.length - (Number(chars) || 0)));
+        return true;
+      },
+    });
+    return String(response?.content || '').trim();
+  } catch (error) {
+    if (signal?.reason?.salvagePartial === true) {
+      const partial = [partialHandoffTextFromSession({ messages }, 2), streamed.trim()].filter(Boolean).join('\n\n');
+      if (partial) return partial;
+    }
+    throw error;
+  }
+}

package/src/runtime/explore/tool-defs.mjs

@@ -0,0 +1,35 @@
+import { TOOL_SYNC_EXECUTION_CONTRACT } from '../shared/tool-execution-contract.mjs';
+
+export const EXPLORE_MAX_QUERIES = 8;
+
+export const TOOL_DEFS = [
+  {
+    name: 'explore',
+    title: 'Explore',
+    annotations: {
+      title: 'Explore',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    description:
+      'Read-only code search in parallel explorers outside your context; returns one merged answer with path:line evidence. ' +
+      'Use when locating needs 3+ searches, spans 2+ files or areas, or covers independent questions; a known file or one lookup: read/grep. ' +
+      TOOL_SYNC_EXECUTION_CONTRACT,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          anyOf: [
+            { type: 'string', minLength: 1 },
+            { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, maxItems: EXPLORE_MAX_QUERIES },
+          ],
+          description: 'One self-contained question, or an array of independent ones (one explorer each).',
+        },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+  },
+];