mixdog 1.2.0 → 1.2.2

package/src/runtime/shared/shell-display.mjs

@@ -11,9 +11,15 @@
 export const POWERSHELL_UTF8_PREFIX =
   '[Console]::OutputEncoding=[System.Text.Encoding]::UTF8; $OutputEncoding=New-Object System.Text.UTF8Encoding $false;';
 
+// The `mixdog-skill-node` definition PowerShell commands carry next
+// (renderPowerShellSkillFunction) is the same kind of execution detail.
+const SKILL_FUNCTION_LINE = /^[ \t]*function mixdog-skill-node \{[^\r\n]*\r?\n/;
+
 export function displayShellCommand(value) {
   const text = String(value ?? '');
-  const trimmed = text.trimStart();
-  if (!trimmed.startsWith(POWERSHELL_UTF8_PREFIX)) return text;
-  return trimmed.slice(POWERSHELL_UTF8_PREFIX.length).replace(/^[ \t]*\r?\n/, '');
+  let rest = text.trimStart();
+  const prefixed = rest.startsWith(POWERSHELL_UTF8_PREFIX);
+  if (prefixed) rest = rest.slice(POWERSHELL_UTF8_PREFIX.length).replace(/^[ \t]*\r?\n/, '');
+  const withoutFunction = rest.replace(SKILL_FUNCTION_LINE, '');
+  return prefixed || withoutFunction !== rest ? withoutFunction : text;
 }

package/src/runtime/shared/skill-mentions.d.mts

@@ -0,0 +1,10 @@
+export interface SkillMention {
+  name: string;
+  start: number;
+  end: number;
+}
+export function isReservedMentionName(name: unknown): boolean;
+export function isInMarkdownCode(text: unknown, offset: number): boolean;
+export function skillMentionCandidates(text: unknown): SkillMention[];
+export function skillMentions(text: unknown, isSkill: (name: string) => boolean): SkillMention[];
+export function mentionedSkillNames(text: unknown, isSkill: (name: string) => boolean): string[];

package/src/runtime/shared/skill-mentions.mjs

@@ -0,0 +1,133 @@
+// Inline `$name` skill mentions: a skill can be named anywhere in a prompt.
+// A candidate is `$` at the start of the text or after whitespace or an
+// opening bracket/quote, followed by a skill-name token (the same
+// lowercase-letters, digits and hyphens rule, 64 characters at most, that
+// skill-document.mjs enforces). It selects a skill only when the token is
+// exactly a known skill name, so `$HOME`, `$300` and unknown names stay prose.
+// The token ends where no ASCII identifier character follows (`$pptx_env`,
+// `$pptxUPPER` are not `pptx`); any other character, Korean particles
+// included (`$pptx로`), ends it.
+const MENTION = /(^|[\s([{"'`])\$([a-z0-9][a-z0-9-]{0,63})(?![A-Za-z0-9_-])/g;
+
+// Common environment-variable names (compared case-insensitively) and
+// numeric-only tokens are never inline mentions, even when a skill has that
+// name: `$path` or `$300` in prose means the variable or the amount. Choosing
+// such a skill explicitly (the `Skill:` header chip) still works.
+const RESERVED_NAMES = new Set([
+  'path',
+  'home',
+  'user',
+  'shell',
+  'pwd',
+  'tmpdir',
+  'temp',
+  'tmp',
+  'lang',
+  'term',
+  'xdg_config_home',
+  'userprofile',
+  'appdata',
+  'localappdata',
+  'programfiles',
+  'systemroot',
+  'windir',
+  'comspec',
+]);
+
+/** True when `name` can never be an inline mention (env var or number). */
+export function isReservedMentionName(name) {
+  const value = String(name ?? '');
+  return /^[0-9]+$/.test(value) || RESERVED_NAMES.has(value.toLowerCase());
+}
+
+// Markdown code is never a mention: fenced blocks (``` or ~~~, 3+ chars,
+// optional info string, closed by a fence of the same char at least as long,
+// else running to the end) and inline code spans (a backtick run closed by
+// the next run of exactly the same length; an unmatched run is literal).
+// Deliberate Mixdog difference: Codex (codex-rs/skills/src/mentions.rs) scans
+// raw bytes with no code handling. Offsets stay those of the original text,
+// so desktop highlighting lines up (and never lands inside code).
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+
+function inlineCodeRanges(source, from, to, ranges) {
+  const runs = [];
+  const re = /`+/g;
+  re.lastIndex = from;
+  for (let match = re.exec(source); match && match.index < to; match = re.exec(source)) {
+    runs.push({ start: match.index, end: Math.min(to, match.index + match[0].length) });
+  }
+  for (let index = 0; index < runs.length; index += 1) {
+    const length = runs[index].end - runs[index].start;
+    const close = runs.findIndex((run, at) => at > index && run.end - run.start === length);
+    if (close < 0) continue;
+    ranges.push([runs[index].start, runs[close].end]);
+    index = close;
+  }
+}
+
+/** [start, end) offsets of Markdown code (fenced blocks and inline spans). */
+function codeRanges(source) {
+  const ranges = [];
+  let open = null;
+  let proseStart = 0;
+  for (let at = 0; at <= source.length; ) {
+    const newline = source.indexOf('\n', at);
+    const end = newline < 0 ? source.length : newline;
+    const next = newline < 0 ? source.length + 1 : newline + 1;
+    const line = source.slice(at, end).replace(/\r$/, '');
+    if (!open) {
+      const fence = FENCE_OPEN.exec(line);
+      if (fence && !(fence[1][0] === '`' && fence[2].includes('`'))) {
+        inlineCodeRanges(source, proseStart, at, ranges);
+        open = { char: fence[1][0], length: fence[1].length, start: at };
+      }
+    } else {
+      const fence = FENCE_CLOSE.exec(line);
+      if (fence && fence[1][0] === open.char && fence[1].length >= open.length) {
+        ranges.push([open.start, Math.min(next, source.length)]);
+        proseStart = Math.min(next, source.length);
+        open = null;
+      }
+    }
+    at = next;
+  }
+  if (open) ranges.push([open.start, source.length]);
+  else inlineCodeRanges(source, proseStart, source.length, ranges);
+  return ranges;
+}
+
+/** True when `offset` in `text` lies inside Markdown code (a fenced block or
+ *  an inline code span) by the same rules mention recognition uses, so a
+ *  composer can tell whether a `$` being typed can become a mention. */
+export function isInMarkdownCode(text, offset) {
+  const source = typeof text === 'string' ? text : '';
+  if (!Number.isInteger(offset) || (!source.includes('`') && !source.includes('~~~'))) return false;
+  return codeRanges(source).some(([from, to]) => offset >= from && offset < to);
+}
+
+/** Every syntactically valid `$name` in `text` outside Markdown code, in
+ *  order: `start` is the `$`. */
+export function skillMentionCandidates(text) {
+  const source = typeof text === 'string' ? text : '';
+  const found = [];
+  let code = null;
+  for (const match of source.matchAll(MENTION)) {
+    if (isReservedMentionName(match[2])) continue;
+    const start = match.index + match[1].length;
+    code ??= source.includes('`') || source.includes('~~~') ? codeRanges(source) : [];
+    if (code.some(([from, to]) => start >= from && start < to)) continue;
+    found.push({ name: match[2], start, end: start + 1 + match[2].length });
+  }
+  return found;
+}
+
+/** Candidates whose name `isSkill(name)` accepts (all occurrences, in order). */
+export function skillMentions(text, isSkill) {
+  return skillMentionCandidates(text).filter((mention) => isSkill(mention.name));
+}
+
+/** Distinct mentioned skill names in first-mention order. */
+export function mentionedSkillNames(text, isSkill) {
+  return [...new Set(skillMentions(text, isSkill).map((mention) => mention.name))];
+}

package/src/runtime/shared/skill-script-runtime.mjs

@@ -0,0 +1,264 @@
+// The interpreter a built-in skill's bundled scripts run on.
+//
+// `${MIXDOG_SKILL_DIR}` is a real directory every process can read, but the
+// pptx scripts import the runtime by relative path (../../../../runtime/...)
+// and its native dependencies (sharp, @napi-rs/canvas, pdf.js). A packaged
+// desktop keeps those only inside runtime.asar, which plain Node cannot open,
+// so `node "<dir>/scripts/x.mjs"` works from an npm install and fails there.
+//
+// So the daemon that runs the model's shells hands them its OWN runtime: a
+// per-installation directory, first on every model shell's PATH, holds
+// `mixdog-skill-node` launchers that run this process's executable (Electron
+// in node mode, or node) on src/skill-script-entry.mjs, which maps the script
+// back into the archive before importing it. Each daemon builds its own shell
+// env, so an SSH-remote or mobile session gets its execution host's runtime.
+// Launchers carry two paths and nothing else: no credentials, no daemon
+// identity.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeFileAtomicSync } from './atomic-file.mjs';
+import { resolvePluginData } from './plugin-paths.mjs';
+
+/** This module's package root (src/runtime/shared → the package). */
+export const SKILL_SCRIPT_PACKAGE_ROOT = path.resolve(fileURLToPath(new URL('.', import.meta.url)), '..', '..', '..');
+
+function pathApi(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+/** The `…/runtime.asar` prefix of a location inside the runtime archive, or null. */
+export function archiveRootOf(location, platform = process.platform) {
+  const sep = platform === 'win32' ? '[\\\\/]' : '/';
+  const match = new RegExp(`^(.*?${sep}runtime\\.asar)(?=${sep}|$)`).exec(String(location || ''));
+  return match ? pathApi(platform).normalize(match[1]) : null;
+}
+
+/**
+ * The path a script must be imported from. A built-in skill's directory is
+ * handed out under `runtime.asar.unpacked` (skillExecutionDir), but its
+ * relative imports only resolve from the archive, so a script under the
+ * sidecar of the archive that holds this package maps back into it. Source
+ * trees and npm installs keep the real path (symlinks resolved, as the ESM
+ * loader resolves them for import.meta.url).
+ */
+export function canonicalSkillScriptPath(
+  target,
+  {
+    packageRoot = SKILL_SCRIPT_PACKAGE_ROOT,
+    platform = process.platform,
+    cwd = process.cwd(),
+    realpath = realpathSync,
+  } = {}
+) {
+  const api = pathApi(platform);
+  let location = api.resolve(cwd, String(target));
+  try {
+    location = realpath(location);
+  } catch {
+    // A missing script fails at import with its own path in the message.
+  }
+  const archive = archiveRootOf(packageRoot, platform);
+  if (!archive) return location;
+  const sidecar = `${archive}.unpacked${api.sep}`;
+  const fold = (value) => (platform === 'win32' ? value.replaceAll('/', '\\').toLowerCase() : value);
+  if (!fold(location).startsWith(fold(sidecar))) return location;
+  return `${archive}${api.sep}${location.slice(sidecar.length)}`;
+}
+
+/** The runtime this process would hand a skill script to. */
+export function skillScriptRuntime({
+  execPath = process.execPath,
+  versions = process.versions,
+  packageRoot = SKILL_SCRIPT_PACKAGE_ROOT,
+  platform = process.platform,
+} = {}) {
+  return {
+    platform,
+    interpreter: execPath,
+    // Electron's own version marker, not ELECTRON_RUN_AS_NODE: model shells
+    // scrub that variable, and a daemon may have inherited it without being
+    // Electron at all.
+    electron: Boolean(versions?.electron),
+    packageRoot,
+    entry: pathApi(platform).join(packageRoot, 'src', 'skill-script-entry.mjs'),
+  };
+}
+
+function batchQuote(value) {
+  return `"${String(value).replaceAll('%', '%%')}"`;
+}
+
+function posixQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * The command `${MIXDOG_SKILL_NODE}` renders to. It is the same word in every
+ * shell: model shells find it on PATH (withSkillLauncherPath), as the
+ * extensionless sh launcher (bash, sh, zsh, Git Bash) or as the .cmd beside
+ * it (cmd through PATHEXT on Windows). PowerShell model commands define a
+ * function of the same name first (renderPowerShellSkillFunction), which
+ * takes precedence over both.
+ */
+export const SKILL_LAUNCHER_COMMAND = 'mixdog-skill-node';
+
+/**
+ * sh launcher text. Electron node mode is set only inside the launcher, for
+ * the one child it execs; every argument and the exit code pass through.
+ */
+export function renderPosixSkillLauncher({ interpreter, entry, electron }) {
+  return `${[
+    '#!/bin/sh',
+    '# Mixdog skill-script launcher, generated for one installation. Do not edit.',
+    ...(electron ? ['ELECTRON_RUN_AS_NODE=1', 'export ELECTRON_RUN_AS_NODE'] : []),
+    `exec ${posixQuote(interpreter)} ${posixQuote(entry)} "$@"`,
+  ].join('\n')}\n`;
+}
+
+/** .cmd launcher text, same contract as the sh launcher. */
+export function renderWindowsSkillLauncher({ interpreter, entry, electron }) {
+  // cmd decodes a batch file in the console code page line by line, so a
+  // non-ASCII path needs UTF-8 for the lines after chcp; the caller's code
+  // page is restored before exit.
+  const unicode = /\P{ASCII}/u.test(`${interpreter}${entry}`);
+  return `${[
+    '@echo off',
+    'rem Mixdog skill-script launcher, generated for one installation. Do not edit.',
+    'setlocal EnableExtensions DisableDelayedExpansion',
+    ...(unicode
+      ? ['for /f "tokens=2 delims=:." %%C in (\'chcp\') do set "MIXDOG_SKILL_CP=%%C"', 'chcp 65001 >nul']
+      : []),
+    ...(electron ? ['set "ELECTRON_RUN_AS_NODE=1"'] : []),
+    `${batchQuote(interpreter)} ${batchQuote(entry)} %*`,
+    'set "MIXDOG_SKILL_EXIT=%ERRORLEVEL%"',
+    ...(unicode ? ['if defined MIXDOG_SKILL_CP chcp %MIXDOG_SKILL_CP% >nul'] : []),
+    'exit /b %MIXDOG_SKILL_EXIT%',
+  ].join('\r\n')}\r\n`;
+}
+
+/** Environment variable carrying a PowerShell caller's arguments to the entry. */
+export const SKILL_ARGV_ENV = 'MIXDOG_SKILL_ARGV';
+const SKILL_ARGV_TAG = 'mixdog1';
+
+function psQuote(value) {
+  // PowerShell also treats the typographic single quotes as quote characters.
+  return `'${String(value).replace(/['\u2018\u2019\u201a\u201b]/g, '$&$&')}'`;
+}
+
+/**
+ * One-line PowerShell definition of `mixdog-skill-node`, prepended to every
+ * PowerShell model command. Through PATH, PowerShell would reach the .cmd via
+ * `cmd.exe /c` with arguments it does not quote, so `'a&b'` ran `b`. The
+ * function runs this daemon's executable on the entry as a plain native
+ * command, so PowerShell's own native-command handling provides streaming,
+ * ordering, backpressure, line endings, `2>&1`/`2>$null`/`2>file`,
+ * `$LASTEXITCODE`, Ctrl-C and early stop. The caller's arguments never reach
+ * that command line: they travel in SKILL_ARGV_ENV (UTF-8 base64), because
+ * Windows PowerShell 5.1 drops empty native arguments and does not escape
+ * embedded double quotes. A failing script ends the command with its exit
+ * code (`exit`), because a PowerShell function cannot fail `$?` or the
+ * -Command exit code.
+ *
+ * SKILL_ARGV_ENV and (Electron daemons only) ELECTRON_RUN_AS_NODE are set on
+ * $env just for the call and restored in `finally`; the bootstrap deletes
+ * both before importing the script. Accepted tradeoff: while the call runs,
+ * a process a concurrent downstream pipeline stage starts can see them.
+ */
+export function renderPowerShellSkillFunction({ interpreter, entry, electron }) {
+  const names = [SKILL_ARGV_ENV, ...(electron ? ['ELECTRON_RUN_AS_NODE'] : [])];
+  const values = ['$__mxa', ...(electron ? ["'1'"] : [])];
+  const body = [
+    `$__mxa = '${SKILL_ARGV_TAG}'`,
+    "foreach ($__mxv in $args) { foreach ($__mxe in @($__mxv)) { if ($null -ne $__mxe) { $__mxa += ',' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([string]$__mxe)) } } }",
+    names.map((name, i) => `$__mxo${i} = $env:${name}`).join('; '),
+    [
+      'try {',
+      ...names.map((name, i) => `$env:${name} = ${values[i]};`),
+      `& ${psQuote(interpreter)} ${psQuote(entry)}`,
+      '} finally {',
+      names.map((name, i) => `$env:${name} = $__mxo${i}`).join('; '),
+      '}',
+    ].join(' '),
+    'if ($LASTEXITCODE) { exit $LASTEXITCODE }',
+  ];
+  return `function ${SKILL_LAUNCHER_COMMAND} { ${body.join('; ')} }`;
+}
+
+/** The arguments a PowerShell caller sent through SKILL_ARGV_ENV, or null. */
+export function decodeSkillArgv(value) {
+  const text = typeof value === 'string' ? value : '';
+  if (!text.startsWith(SKILL_ARGV_TAG)) return null;
+  const rest = text.slice(SKILL_ARGV_TAG.length);
+  if (!rest) return [];
+  return rest
+    .slice(1)
+    .split(',')
+    .map((item) => Buffer.from(item, 'base64').toString('utf8'));
+}
+
+/** Launcher files of `runtime`: the sh script everywhere, plus the .cmd on Windows. */
+export function skillLauncherFiles(runtime) {
+  return [
+    { name: SKILL_LAUNCHER_COMMAND, content: renderPosixSkillLauncher(runtime) },
+    ...(runtime.platform === 'win32'
+      ? [{ name: `${SKILL_LAUNCHER_COMMAND}.cmd`, content: renderWindowsSkillLauncher(runtime) }]
+      : []),
+  ];
+}
+
+/** Private per-installation launcher directory under the data dir. */
+export function skillLauncherDir(runtime, dataDir = resolvePluginData()) {
+  const digest = createHash('sha256')
+    .update(JSON.stringify([runtime.platform, runtime.interpreter, runtime.entry, runtime.electron]))
+    .digest('hex')
+    .slice(0, 16);
+  return pathApi(runtime.platform).join(dataDir, 'skill-launchers', digest);
+}
+
+const ensuredDirs = new Set();
+
+/**
+ * Write (atomically) or refresh the launchers for `runtime`; returns their
+ * directory. A directory already verified by this process is only checked for
+ * presence, so the per-command shell env build stays a couple of stats.
+ */
+export function ensureSkillLauncherDir(runtime = skillScriptRuntime(), dataDir = resolvePluginData()) {
+  const dir = skillLauncherDir(runtime, dataDir);
+  const api = pathApi(runtime.platform);
+  const files = skillLauncherFiles(runtime);
+  if (ensuredDirs.has(dir) && files.every(({ name }) => existsSync(api.join(dir, name)))) return dir;
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  for (const { name, content } of files) {
+    const file = api.join(dir, name);
+    let current = null;
+    try {
+      current = readFileSync(file, 'utf8');
+    } catch {
+      // Not written yet.
+    }
+    if (current !== content) writeFileAtomicSync(file, content, { mode: 0o700 });
+  }
+  ensuredDirs.add(dir);
+  return dir;
+}
+
+/**
+ * `env` with this installation's launcher directory first on PATH. Only model
+ * shell environments call this; the daemon's own env, hooks and internal
+ * workers keep their PATH. The directory holds nothing but the launchers, so
+ * no existing command is shadowed.
+ */
+export function withSkillLauncherPath(env, { runtime = skillScriptRuntime(), dataDir = resolvePluginData() } = {}) {
+  const dir = ensureSkillLauncherDir(runtime, dataDir);
+  const delimiter = runtime.platform === 'win32' ? ';' : ':';
+  // Windows env keys are case-insensitive and usually spelled `Path`.
+  const key =
+    (runtime.platform === 'win32' ? Object.keys(env).find((name) => name.toUpperCase() === 'PATH') : null) || 'PATH';
+  const entries = String(env[key] || '')
+    .split(delimiter)
+    .filter((entry) => entry && entry !== dir);
+  env[key] = [dir, ...entries].join(delimiter);
+  return env;
+}

package/src/runtime/shared/statusline/statusline-format.mjs

@@ -6,7 +6,7 @@
  * the shared runtime formatter so L2 matches TUI/desktop cards.
  */
 import { colorEnabled, rgb, rgbSgr } from './ansi.mjs';
-import { displayModelName, shortenModelName } from '../model-display.mjs';
+import { displayModelName, effortDisplayLabel, shortenModelName } from '../model-display.mjs';
 import { getModelMetadataSync } from '../llm/model-catalog.mjs';
 import { contextMeasurementLabel } from '../context-measurement.mjs';
 import { formatElapsed } from '../time-format.mjs';
@@ -44,14 +44,14 @@ export function modelContextWindow(provider, model, explicitContextWindow = 0) {
   return FALLBACK_CONTEXT_WINDOW;
 }
 
-export function formatModelSegment({ provider, model, effort, fast, cols }) {
+export function formatModelSegment({ provider, model, effort, fast, ultra, cols }) {
   const raw = String(model || '').trim();
   const meta = getModelMetadataSync(raw, provider) || {};
   const displayHint = String(meta.displayName || meta.display || meta.name || '').trim();
   const modelName = shortenModelName(displayModelName(raw, provider, displayHint), cols);
   const bits = [`${B}${modelName}${R}`];
-  if (effort) bits.push(`${B}${String(effort).toUpperCase()}${R}`);
-  if (fast === true) bits.push(`${B}FAST${R}`);
+  if (effort) bits.push(`${B}${effortDisplayLabel(effort)}${R}`);
+  if (fast === true) bits.push(`${B}${ultra === true ? 'Ultrafast' : 'Fast'}${R}`);
   return bits.join(` ${D}·${R} `);
 }
 

package/src/runtime/shared/task-notification-envelope.mjs

@@ -30,13 +30,13 @@ export function taskCompletionSummary({ surface = 'tool', id, tag, status, error
   return `${subject} ${outcome}${status === 'failed' && error ? `: ${error}` : ''}${detail ? ` (${detail})` : ''}`;
 }
 
-export function renderTaskCompletionEnvelope({ surface = 'tool', id, tag, status, result = '', error } = {}) {
+export function renderTaskCompletionEnvelope({ surface = 'tool', id, tag, status, result = '', error, detail } = {}) {
   return [
     '<task-notification>',
     field('task-id', id),
     tag ? field('tag', tag) : null,
     field('status', status),
-    field('summary', taskCompletionSummary({ surface, id, tag, status })),
+    field('summary', taskCompletionSummary({ surface, id, tag, status, detail })),
     result ? `<result>\n${result}\n</result>` : null,
     status === 'failed' && error ? field('error', error) : null,
     '</task-notification>',

package/src/runtime/shared/tool-primitives.mjs

@@ -22,8 +22,39 @@ function rawToolName(name) {
   return String(name || 'tool').replace(/^functions\./, '');
 }
 
-export function parseMcpToolName(name) {
-  const text = rawToolName(name);
+// Tool names shortened to fit provider limits -> their real server and tool,
+// recorded when the name is built so name-only callers in this process
+// resolve them. Bounded; the oldest entries go first.
+const MCP_TOOL_IDENTITY_MAX = 4096;
+const mcpToolIdentities = new Map();
+
+export function rememberMcpToolIdentity(name, server, tool) {
+  const key = String(name || '');
+  if (!key) return;
+  mcpToolIdentities.delete(key);
+  mcpToolIdentities.set(key, { server: String(server || ''), tool: String(tool || '') });
+  if (mcpToolIdentities.size > MCP_TOOL_IDENTITY_MAX) mcpToolIdentities.delete(mcpToolIdentities.keys().next().value);
+}
+
+/** Server and tool of a shortened MCP tool name, when this process built it. */
+export function knownMcpToolIdentity(name) {
+  const known = mcpToolIdentities.get(rawToolName(name));
+  return known ? { ...known } : null;
+}
+
+/** `{ server, tool }` of an MCP tool, or null. Takes a tool definition (its
+ *  `mcpServerName`/`mcpToolName` metadata wins) or a name (a recorded
+ *  shortened name first, else the `mcp__<server>__<tool>` form). */
+export function parseMcpToolName(nameOrTool) {
+  if (nameOrTool && typeof nameOrTool === 'object') {
+    const server = String(nameOrTool.mcpServerName || '').trim();
+    const parsed = parseMcpToolName(nameOrTool.name);
+    if (!server) return parsed;
+    return { server, tool: String(nameOrTool.mcpToolName || '') || parsed?.tool || '' };
+  }
+  const text = rawToolName(nameOrTool);
+  const known = mcpToolIdentities.get(text);
+  if (known) return { ...known };
   const match = /^mcp__(.+?)__(.+)$/.exec(text);
   if (!match) return null;
   return { server: match[1], tool: match[2] };
@@ -169,6 +200,8 @@ export function toolSearchDisplayLabel(args = {}) {
 export function displayToolSearchTarget(value) {
   const text = String(value || '').trim();
   if (/^skill:/i.test(text)) return text.slice('skill:'.length);
+  const known = knownMcpToolIdentity(text);
+  if (known) return `${known.server}.${known.tool}`;
   const mcp = /^mcp__(.*?)__(.+)$/.exec(text);
   if (mcp) return `${mcp[1]}.${mcp[2]}`;
   return stripToolPrefix(text);