@pellux/goodvibes-agent 1.0.17 → 1.0.18

package/docs/README.md

@@ -22,7 +22,7 @@ Important baseline constraints:
 - Agent depends on `@pellux/goodvibes-sdk@0.33.35`.
 - Agent connects to a GoodVibes host owned outside this product.
 - Agent does not start, stop, restart, install, uninstall, or own the connected GoodVibes host.
-- User-facing Agent workspace actions, single workspace-action lookup, built-in panels, modal/overlay/picker UI surfaces, named operator surfaces, top-level CLI mirrors, fixed shortcuts, configurable keybindings, slash commands, single-command lookup with policy metadata, model tools and individual model tool schemas, settings and single-setting lookup, local registries, connected-host capability boundaries, single connected-host capability inspection, and live connected-host readiness are model-visible through Agent-owned tools. Visible UI routing includes the command browser, reasoning-effort picker, live process output, runtime activity, settings, workspaces, and pickers the user can open. Local memory, note, persona, skill, and routine create editors can also run through confirmed workspace actions. Mutations and visible UI routing remain explicit and confirmation-gated, and ambiguous setting lookups are refused with candidates instead of guessed.
+- User-facing Agent workspace actions, single workspace-action lookup, built-in panels and single-panel lookup, modal/overlay/picker UI surfaces and single-surface lookup, named operator surfaces, top-level CLI mirrors, fixed shortcuts, configurable keybindings and single-keybinding lookup, slash commands, single-command lookup with policy metadata, model tools and individual model tool schemas, settings and single-setting lookup, local registries, connected-host capability boundaries, single connected-host capability inspection, and live connected-host readiness are model-visible through Agent-owned tools. Visible UI routing includes the command browser, reasoning-effort picker, live process output, runtime activity, settings, workspaces, and pickers the user can open. Local memory, note, persona, skill, and routine create editors can also run through confirmed workspace actions. Mutations and visible UI routing remain explicit and confirmation-gated, and ambiguous lookup matches are refused with candidates instead of guessed.
 - Agent Knowledge uses only `/api/goodvibes-agent/knowledge/*`; there is no default knowledge or non-Agent product fallback.
 - Agent supports isolated Agent homes with `GOODVIBES_AGENT_HOME=<path>` and named profile homes with `goodvibes-agent profiles create <name> --template <starter> --yes` plus `--agent-profile <name>`.
 - Agent supports connected-host URL overrides with `--runtime-url http://host:port` or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port`; these only change the Agent connection target.

package/docs/getting-started.md

@@ -44,7 +44,7 @@ After setup has been applied once, the TUI opens directly into the Agent operato
 
 Press `/` inside the Agent workspace to search every workspace action by name, category, command, or detail. Use that finder before reaching for shell commands; CLI subcommands are scriptable mirrors of these TUI workflows.
 
-The model can inspect and use the same harness surface through Agent-owned tools. `agent_harness` exposes workspace action discovery, single workspace-action inspection by action id, command, or lookup text, built-in panel discovery/routing, modal/overlay/picker UI surface discovery/routing, top-level CLI mirror discovery, fixed shortcut and configurable keybinding discovery, keybinding mutation with confirmation, slash-command discovery, single slash-command inspection by typed command or lookup text, command policy metadata, command execution with confirmation, model tool discovery and single-tool schema inspection, settings inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness posture. CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, or slash-command mirror. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager. Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied; single-action lookup uses the same user-facing search fields and returns lookup metadata plus the editor schema; single-setting lookup uses `key`, `target`, or `query`, returns lookup metadata, and refuses ambiguous mutations with candidate settings. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. First-class model tools cover the main product workflows directly: Agent Knowledge, Agent Knowledge ingest, Agent-local memory/notes/personas/skills/routines, operator actions, notifications, channel sends, reminders, generated media, and work plans.
+The model can inspect and use the same harness surface through Agent-owned tools. `agent_harness` exposes workspace action discovery, single workspace-action inspection by action id, command, or lookup text, built-in panel discovery/routing by panel id or lookup text, modal/overlay/picker UI surface discovery/routing by surface id or lookup text, top-level CLI mirror discovery, fixed shortcut and configurable keybinding discovery, keybinding inspection/mutation by action id or lookup text, slash-command discovery, single slash-command inspection by typed command or lookup text, command policy metadata, command execution with confirmation, model tool discovery and single-tool schema inspection, settings inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness posture. CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, or slash-command mirror. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager. Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied; single-action lookup uses the same user-facing search fields and returns lookup metadata plus the editor schema; single-panel, single-surface, single-keybinding, and single-setting lookup use their catalog search fields, return lookup metadata, and refuse ambiguous route or mutation requests with candidates. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. First-class model tools cover the main product workflows directly: Agent Knowledge, Agent Knowledge ingest, Agent-local memory/notes/personas/skills/routines, operator actions, notifications, channel sends, reminders, generated media, and work plans.
 
 Use the Artifacts area for concrete files and generated output: attach images to prompts, export conversations or saved sessions, ingest local source files and URL lists into Agent Knowledge, import bookmarks or browser history, inspect source records, and generate media artifacts from confirmed prompts.
 
@@ -122,7 +122,7 @@ Use `/channels` inside the TUI for channel readiness and exact confirmed sends.
 
 The main assistant conversation can perform narrow confirmed operator actions when the user explicitly asks for a specific target: approve/deny/cancel one approval, run/pause/resume one automation job, cancel/retry one automation run, or run one schedule. Those calls use only public connected-host routes, require confirmation, and do not create, edit, or delete automation definitions.
 
-When the main assistant conversation needs to change Agent settings, change Agent keybindings, open a visible UI surface, or run a user-facing harness action, it should use `agent_harness` rather than generic SDK context/settings tools. Setting descriptors report writability, workspace visibility, lock reasons, and lookup metadata when a single setting is resolved from `key`, `target`, or `query`; ambiguous setting mutation requests return candidates instead of guessing. Keybinding descriptors report fixed shortcuts, resolved bindings, defaults, custom state, and config path; UI surface descriptors report the visible shell opener, preferred model route, and confirmation policy; secret-backed settings store raw values through the secret manager; connected-host lifecycle settings stay read-only in Agent; and destructive local record deletion requires explicit confirmation.
+When the main assistant conversation needs to change Agent settings, change Agent keybindings, open a visible UI surface, or run a user-facing harness action, it should use `agent_harness` rather than generic SDK context/settings tools. Panel, UI surface, keybinding, and setting descriptors report lookup metadata when resolved from `target` or `query`; ambiguous route or mutation requests return candidates instead of guessing. Setting descriptors also report writability, workspace visibility, and lock reasons. Keybinding descriptors report fixed shortcuts, resolved bindings, defaults, custom state, and config path; UI surface descriptors report the visible shell opener, preferred model route, and confirmation policy; secret-backed settings store raw values through the secret manager; connected-host lifecycle settings stay read-only in Agent; and destructive local record deletion requires explicit confirmation.
 
 ## Connected GoodVibes Host
 

package/docs/tools-and-commands.md

@@ -43,20 +43,20 @@ Host-management and coding-first commands that would imply connected-host lifecy
 
 The main Agent model has an Agent-owned harness bridge rather than generic SDK settings/context control. Use these model tools as the supported parity layer:
 
-- `agent_harness`: inspect workspace categories/actions and one workspace action by action id, command, or lookup text, inspect built-in panels, inspect modal/overlay/picker UI surfaces and named operator surfaces, inspect top-level CLI mirrors, inspect fixed shortcuts and configurable keybindings, inspect slash commands and one slash command by typed command or lookup text with policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools or one model tool schema, inspect or change Agent settings/keybindings by exact id or lookup text, inspect connected-host capability boundaries or one connected-host capability, and inspect live connected-host readiness.
+- `agent_harness`: inspect workspace categories/actions and one workspace action by action id, command, or lookup text, inspect built-in panels and one panel by id or lookup text, inspect modal/overlay/picker UI surfaces and named operator surfaces by id or lookup text, inspect top-level CLI mirrors, inspect fixed shortcuts and configurable keybindings, inspect or change one keybinding by action id or lookup text, inspect slash commands and one slash command by typed command or lookup text with policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools or one model tool schema, inspect or change Agent settings by exact key or lookup text, inspect connected-host capability boundaries or one connected-host capability, and inspect live connected-host readiness.
 - `agent_local_registry`: inspect and maintain Agent-local memory, notes, personas, skills, skill bundles, and routines. Deleting local records requires `confirm:true` and `explicitUserRequest`.
 - `agent_knowledge` and `agent_knowledge_ingest`: ask/search and ingest into the isolated Agent Knowledge segment.
 - `agent_operator_briefing` and `agent_operator_action`: inspect connected work/approval/automation posture, or run exact confirmed approval/automation actions.
 - `agent_work_plan`: keep the visible Agent-local work plan current from the conversation.
 - `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, and `agent_media_generate`: perform confirmed external delivery, notification, reminder, or media actions when the user explicitly asks.
 
-`agent_harness` discovery modes are read-only. `summary` reports the model access map; `panels` and `panel` return the built-in panel catalog, current open/focused state, and each panel's matching Agent workspace route; `ui_surfaces` and `ui_surface` return modal, overlay, picker, and workspace entrypoints with shell-opener availability and preferred model routes; `cli_commands` and `cli_command` return top-level package CLI mirror metadata, parser output, blocked command tokens, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` and `keybinding` return the live resolved keybinding table, default bindings, custom state, and config path; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments plus effect/confirmation/preferred-tool/boundary policy metadata; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` returns one action by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields and returning lookup metadata plus its editor schema; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query`; `settings` returns setting descriptors plus setting policy; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
+`agent_harness` discovery modes are read-only. `summary` reports the model access map; `panels` lists the built-in panel catalog, and `panel` resolves one panel by `panelId`, `target`, or `query` with current open/focused state plus its matching Agent workspace route; `ui_surfaces` lists modal, overlay, picker, and workspace entrypoints, and `ui_surface` resolves one by `surfaceId`, `target`, or `query` with shell-opener availability and preferred model routes; `cli_commands` and `cli_command` return top-level package CLI mirror metadata, parser output, blocked command tokens, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` lists the live resolved keybinding table, and `keybinding`, `set_keybinding`, and `reset_keybinding` resolve one action by `actionId`, `target`, `key`, or `query` with default bindings, custom state, config path, and lookup metadata; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments plus effect/confirmation/preferred-tool/boundary policy metadata; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` returns one action by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields and returning lookup metadata plus its editor schema; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query`; `settings` returns setting descriptors plus setting policy; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
 
-`open_ui_surface` is a confirmation-gated visible navigation mode for the same shell surfaces the user can open: Agent workspace, settings, MCP workspace, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, conversation search, prompt-history search, slash-command mode, command browser, file picker, block actions, bookmarks, context inspector, runtime activity monitor, live process output, help, shortcuts, and onboarding. It does not perform hidden operations; use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual state changes.
+`open_ui_surface` is a confirmation-gated visible navigation mode for the same shell surfaces the user can open: Agent workspace, settings, MCP workspace, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, conversation search, prompt-history search, slash-command mode, command browser, file picker, block actions, bookmarks, context inspector, runtime activity monitor, live process output, help, shortcuts, and onboarding. It does not perform hidden operations; use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual state changes. Ambiguous UI surface lookup text is refused with candidate surfaces instead of routed.
 
-`set_keybinding` and `reset_keybinding` are confirmation-gated control modes. They write the same Agent `keybindings.json` file exposed by `/keybindings`, reload the runtime keybinding manager, and leave fixed runtime/editor shortcuts read-only.
+`set_keybinding` and `reset_keybinding` are confirmation-gated control modes. They write the same Agent `keybindings.json` file exposed by `/keybindings`, reload the runtime keybinding manager, and leave fixed runtime/editor shortcuts read-only. Ambiguous keybinding lookup text is refused with candidate actions instead of guessed.
 
-`open_panel` is a confirmation-gated UI routing mode. It hands a visible panel/workspace route to the current Agent shell bridge and does not mutate connected-host lifecycle, listener posture, or external accounts.
+`open_panel` is a confirmation-gated UI routing mode. It hands a visible panel/workspace route to the current Agent shell bridge and does not mutate connected-host lifecycle, listener posture, or external accounts. Ambiguous panel lookup text is refused with candidate panels instead of routed.
 
 CLI mirror modes are catalog and parser inspection only. When the user asks the model to operate from inside the main conversation, use the returned first-class model tool, workspace action, setting mode, or confirmed slash-command mirror instead of launching a hidden nested `goodvibes-agent` process.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",

package/src/tools/agent-harness-keybinding-metadata.ts

@@ -23,6 +23,7 @@ const FIXED_SHORTCUTS: readonly Record<string, string>[] = [
 interface HarnessKeybindingArgs {
   readonly query?: unknown;
   readonly actionId?: unknown;
+  readonly target?: unknown;
   readonly key?: unknown;
   readonly fields?: unknown;
   readonly combo?: unknown;
@@ -33,6 +34,24 @@ interface HarnessKeybindingArgs {
 
 type KeybindingsOverrideFile = Record<string, unknown>;
 
+interface KeybindingLookup {
+  readonly source: 'actionId' | 'target' | 'key' | 'query';
+  readonly input: string;
+  readonly resolvedBy: 'action' | 'case-insensitive-action' | 'search';
+}
+
+type KeybindingResolution =
+  | {
+    readonly status: 'found';
+    readonly action: KeyAction;
+    readonly lookup: KeybindingLookup;
+  }
+  | {
+    readonly status: 'ambiguous';
+    readonly input: string;
+    readonly candidates: readonly Record<string, unknown>[];
+  };
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -58,11 +77,6 @@ function isKeyAction(action: string): action is KeyAction {
   return Object.hasOwn(ACTION_DESCRIPTIONS, action);
 }
 
-function actionFromArgs(args: HarnessKeybindingArgs): KeyAction | null {
-  const action = readString(args.actionId || args.key || args.query);
-  return action && isKeyAction(action) ? action : null;
-}
-
 function readBoolean(value: unknown): boolean | undefined {
   if (typeof value === 'boolean') return value;
   if (typeof value !== 'string') return undefined;
@@ -138,22 +152,63 @@ function describeCombo(manager: KeybindingsManager, combo: KeyCombo): Record<str
   };
 }
 
-function bindingMatches(entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }, query: string): boolean {
-  if (!query) return true;
-  const haystack = [
+function keybindingLookupFromArgs(args: HarnessKeybindingArgs): { readonly source: KeybindingLookup['source']; readonly input: string } | null {
+  const actionId = readString(args.actionId);
+  if (actionId) return { source: 'actionId', input: actionId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const key = readString(args.key);
+  if (key) return { source: 'key', input: key };
+  const query = readString(args.query);
+  if (query) return { source: 'query', input: query };
+  return null;
+}
+
+function bindingSearchText(manager: KeybindingsManager, entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }): string {
+  return [
     entry.action,
     entry.description,
     ...entry.combos.map((combo) => comboFingerprint(combo)),
+    ...entry.combos.map((combo) => manager.formatCombo(combo)),
   ].join('\n').toLowerCase();
-  return haystack.includes(query.toLowerCase());
 }
 
-function describeBinding(manager: KeybindingsManager, action: KeyAction, combos: KeyCombo[]): Record<string, unknown> {
+function bindingCandidate(manager: KeybindingsManager, entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }): Record<string, unknown> {
+  return {
+    action: entry.action,
+    description: entry.description,
+    labels: entry.combos.map((combo) => manager.formatCombo(combo)),
+  };
+}
+
+function bindingMatches(manager: KeybindingsManager, entry: { readonly action: KeyAction; readonly description: string; readonly combos: KeyCombo[] }, query: string): boolean {
+  if (!query) return true;
+  return bindingSearchText(manager, entry).includes(query.toLowerCase());
+}
+
+function resolveHarnessKeybinding(context: CommandContext, args: HarnessKeybindingArgs): KeybindingResolution | null {
+  const manager = requireKeybindingsManager(context);
+  const lookup = keybindingLookupFromArgs(args);
+  if (!lookup) return null;
+  const entries = manager.getAll();
+  if (isKeyAction(lookup.input)) return { status: 'found', action: lookup.input, lookup: { ...lookup, resolvedBy: 'action' } };
+  const inputLower = lookup.input.toLowerCase();
+  const ciActions = entries.filter((entry) => entry.action.toLowerCase() === inputLower);
+  if (ciActions.length === 1) return { status: 'found', action: ciActions[0]!.action, lookup: { ...lookup, resolvedBy: 'case-insensitive-action' } };
+  if (ciActions.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: ciActions.map((entry) => bindingCandidate(manager, entry)).slice(0, 8) };
+  const matches = entries.filter((entry) => bindingMatches(manager, entry, lookup.input));
+  if (matches.length === 1) return { status: 'found', action: matches[0]!.action, lookup: { ...lookup, resolvedBy: 'search' } };
+  if (matches.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: matches.map((entry) => bindingCandidate(manager, entry)).slice(0, 8) };
+  return null;
+}
+
+function describeBinding(manager: KeybindingsManager, action: KeyAction, combos: KeyCombo[], lookup?: KeybindingLookup): Record<string, unknown> {
   const defaults = DEFAULT_KEYBINDINGS[action];
   const customized = !combosEqual(combos, defaults);
   return {
     action,
     description: ACTION_DESCRIPTIONS[action],
+    ...(lookup ? { lookup } : {}),
     bindings: combos.map((combo) => describeCombo(manager, combo)),
     labels: combos.map((combo) => manager.formatCombo(combo)),
     defaultBindings: defaults.map((combo) => describeCombo(manager, combo)),
@@ -205,7 +260,7 @@ export function listHarnessKeybindings(context: CommandContext, args: HarnessKey
   const manager = requireKeybindingsManager(context);
   const query = readString(args.query);
   const entries = manager.getAll()
-    .filter((entry) => bindingMatches(entry, query))
+    .filter((entry) => bindingMatches(manager, entry, query))
     .slice(0, readLimit(args.limit, 200))
     .map((entry) => describeBinding(manager, entry.action, entry.combos));
   return {
@@ -219,44 +274,49 @@ export function listHarnessKeybindings(context: CommandContext, args: HarnessKey
 
 export function describeHarnessKeybinding(context: CommandContext, args: HarnessKeybindingArgs): Record<string, unknown> | null {
   const manager = requireKeybindingsManager(context);
-  const action = actionFromArgs(args);
-  if (!action) return null;
-  const entry = manager.getAll().find((candidate) => candidate.action === action);
+  const resolved = resolveHarnessKeybinding(context, args);
+  if (resolved?.status === 'ambiguous') return { status: 'ambiguous', input: resolved.input, candidates: resolved.candidates };
+  if (!resolved) return null;
+  const entry = manager.getAll().find((candidate) => candidate.action === resolved.action);
   return entry ? {
     configPath: manager.getConfigPath(),
-    ...describeBinding(manager, entry.action, entry.combos),
+    ...describeBinding(manager, entry.action, entry.combos, resolved.lookup),
   } : null;
 }
 
 export function setHarnessKeybinding(context: CommandContext, args: HarnessKeybindingArgs): Record<string, unknown> {
   const manager = requireKeybindingsManager(context);
-  const action = actionFromArgs(args);
-  if (!action) throw new Error('set_keybinding requires a valid keybinding action id.');
+  const resolved = resolveHarnessKeybinding(context, args);
+  if (resolved?.status === 'ambiguous') throw new Error(`Ambiguous keybinding action ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  if (!resolved) throw new Error('set_keybinding requires a valid keybinding action id, target, or query.');
   const combos = combosFromArgs(args);
   const configPath = manager.getConfigPath();
   const overrides = readOverrideFile(configPath);
-  overrides[action] = combos.length === 1 ? combos[0] : combos;
+  overrides[resolved.action] = combos.length === 1 ? combos[0] : combos;
   writeOverrideFile(configPath, overrides);
   manager.loadFromDisk();
   return {
     status: 'updated',
     configPath,
-    keybinding: describeHarnessKeybinding(context, { actionId: action }),
+    keybinding: describeHarnessKeybinding(context, { actionId: resolved.action }),
+    lookup: resolved.lookup,
   };
 }
 
 export function resetHarnessKeybinding(context: CommandContext, args: HarnessKeybindingArgs): Record<string, unknown> {
   const manager = requireKeybindingsManager(context);
-  const action = actionFromArgs(args);
-  if (!action) throw new Error('reset_keybinding requires a valid keybinding action id.');
+  const resolved = resolveHarnessKeybinding(context, args);
+  if (resolved?.status === 'ambiguous') throw new Error(`Ambiguous keybinding action ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  if (!resolved) throw new Error('reset_keybinding requires a valid keybinding action id, target, or query.');
   const configPath = manager.getConfigPath();
   const overrides = readOverrideFile(configPath);
-  delete overrides[action];
+  delete overrides[resolved.action];
   writeOverrideFile(configPath, overrides);
   manager.loadFromDisk();
   return {
     status: 'reset',
     configPath,
-    keybinding: describeHarnessKeybinding(context, { actionId: action }),
+    keybinding: describeHarnessKeybinding(context, { actionId: resolved.action }),
+    lookup: resolved.lookup,
   };
 }

package/src/tools/agent-harness-panel-metadata.ts

@@ -5,11 +5,30 @@ import type { PanelRegistration } from '../panels/types.ts';
 export interface AgentHarnessPanelArgs {
   readonly query?: unknown;
   readonly panelId?: unknown;
+  readonly target?: unknown;
   readonly category?: unknown;
   readonly limit?: unknown;
   readonly pane?: unknown;
 }
 
+interface PanelLookup {
+  readonly source: 'panelId' | 'target' | 'query';
+  readonly input: string;
+  readonly resolvedBy: 'id' | 'case-insensitive-id' | 'name' | 'case-insensitive-name' | 'search';
+}
+
+type PanelResolution =
+  | {
+    readonly status: 'found';
+    readonly registration: PanelRegistration;
+    readonly lookup: PanelLookup;
+  }
+  | {
+    readonly status: 'ambiguous';
+    readonly input: string;
+    readonly candidates: readonly Record<string, unknown>[];
+  };
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -32,10 +51,59 @@ function panelMatches(panel: Record<string, unknown>, query: string): boolean {
     panel.category,
     panel.description,
     panel.workspaceRoute,
-  ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
+  ].map((value) => typeof value === 'object' ? JSON.stringify(value) : String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
+}
+
+function panelLookupFromArgs(args: AgentHarnessPanelArgs): { readonly source: PanelLookup['source']; readonly input: string } | null {
+  const panelId = readString(args.panelId);
+  if (panelId) return { source: 'panelId', input: panelId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  if (query) return { source: 'query', input: query };
+  return null;
 }
 
-function describePanelRegistration(context: CommandContext, registration: PanelRegistration): Record<string, unknown> {
+function panelCandidate(registration: PanelRegistration): Record<string, unknown> {
+  return {
+    id: registration.id,
+    name: registration.name,
+    category: registration.category,
+    description: registration.description,
+    workspaceRoute: {
+      categoryId: agentWorkspaceCategoryForPanel(registration.id),
+      command: agentWorkspaceCommandForPanel(registration.id),
+    },
+  };
+}
+
+function resolveHarnessPanel(context: CommandContext, args: AgentHarnessPanelArgs): PanelResolution | null {
+  const manager = panelManager(context);
+  const lookup = panelLookupFromArgs(args);
+  if (!manager || !lookup) return null;
+  const registrations = manager.getRegisteredTypes();
+  const exactId = registrations.find((panel) => panel.id === lookup.input);
+  if (exactId) return { status: 'found', registration: exactId, lookup: { ...lookup, resolvedBy: 'id' } };
+  const inputLower = lookup.input.toLowerCase();
+  const exactName = registrations.find((panel) => panel.name === lookup.input);
+  if (exactName) return { status: 'found', registration: exactName, lookup: { ...lookup, resolvedBy: 'name' } };
+  const ciId = registrations.filter((panel) => panel.id.toLowerCase() === inputLower);
+  if (ciId.length === 1) return { status: 'found', registration: ciId[0]!, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } };
+  if (ciId.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: ciId.map(panelCandidate).slice(0, 8) };
+  const ciName = registrations.filter((panel) => panel.name.toLowerCase() === inputLower);
+  if (ciName.length === 1) return { status: 'found', registration: ciName[0]!, lookup: { ...lookup, resolvedBy: 'case-insensitive-name' } };
+  if (ciName.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: ciName.map(panelCandidate).slice(0, 8) };
+  const category = readString(args.category);
+  const search = registrations.filter((registration) => {
+    if (category && registration.category !== category) return false;
+    return panelMatches(panelCandidate(registration), lookup.input);
+  });
+  if (search.length === 1) return { status: 'found', registration: search[0]!, lookup: { ...lookup, resolvedBy: 'search' } };
+  if (search.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: search.map(panelCandidate).slice(0, 8) };
+  return null;
+}
+
+function describePanelRegistration(context: CommandContext, registration: PanelRegistration, lookup?: PanelLookup): Record<string, unknown> {
   const manager = panelManager(context);
   const openPanel = manager?.getPanel(registration.id) ?? null;
   const pane = manager?.getPaneOf(registration.id) ?? null;
@@ -46,6 +114,7 @@ function describePanelRegistration(context: CommandContext, registration: PanelR
     icon: registration.icon,
     category: registration.category,
     description: registration.description,
+    ...(lookup ? { lookup } : {}),
     preload: registration.preload === true,
     open: openPanel !== null,
     pane,
@@ -82,26 +151,27 @@ export function listHarnessPanels(context: CommandContext, args: AgentHarnessPan
 }
 
 export function describeHarnessPanel(context: CommandContext, args: AgentHarnessPanelArgs): Record<string, unknown> | null {
-  const manager = panelManager(context);
-  if (!manager) return null;
-  const panelId = readString(args.panelId || args.query);
-  if (!panelId) return null;
-  const registration = manager.getRegisteredTypes().find((panel) => (
-    panel.id === panelId
-    || panel.name.toLowerCase() === panelId.toLowerCase()
-  ));
-  return registration ? describePanelRegistration(context, registration) : null;
+  const resolved = resolveHarnessPanel(context, args);
+  if (resolved?.status === 'found') return describePanelRegistration(context, resolved.registration, resolved.lookup);
+  if (resolved?.status === 'ambiguous') {
+    return { status: 'ambiguous', input: resolved.input, candidates: resolved.candidates };
+  }
+  return null;
 }
 
 export function openHarnessPanel(context: CommandContext, args: AgentHarnessPanelArgs): Record<string, unknown> {
-  const panel = describeHarnessPanel(context, args);
-  if (!panel) {
+  const resolved = resolveHarnessPanel(context, args);
+  if (resolved?.status === 'ambiguous') {
+    return { status: 'ambiguous_panel', input: resolved.input, candidates: resolved.candidates };
+  }
+  if (!resolved) {
     return {
       status: 'unknown_panel',
-      panelId: readString(args.panelId || args.query) || '<missing>',
+      panelId: readString(args.panelId || args.target || args.query) || '<missing>',
       availablePanels: listHarnessPanels(context, { limit: 50 }).map((entry) => entry.id),
     };
   }
+  const panel = describePanelRegistration(context, resolved.registration, resolved.lookup);
   const requestedPane = readString(args.pane);
   const pane = requestedPane === 'bottom' || requestedPane === 'top' ? requestedPane : undefined;
   if (!context.showPanel) {

package/src/tools/agent-harness-tool-schema.ts

@@ -23,7 +23,7 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   query: {
     type: 'string',
-    description: 'Search text for command, workspace action, setting, tool, or UI surface catalogs; also a slash-command lookup for mode command or setting lookup for get_setting/set_setting/reset_setting.',
+    description: 'Search text for command, panel, UI surface, keybinding, workspace action, setting, or tool catalogs; also slash-command, setting, panel, UI surface, or keybinding lookup for single-item modes.',
   },
   command: {
     type: 'string',
@@ -48,15 +48,15 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   surfaceId: {
     type: 'string',
-    description: 'UI surface id for ui_surface or open_ui_surface modes.',
+    description: 'UI surface id for ui_surface or open_ui_surface modes. target or query can also look up one UI surface when the exact id is not known.',
   },
   panelId: {
     type: 'string',
-    description: 'Built-in panel id for panel or open_panel modes.',
+    description: 'Built-in panel id for panel or open_panel modes. target or query can also look up one panel when the exact id is not known.',
   },
   actionId: {
     type: 'string',
-    description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/set_keybinding/reset_keybinding.',
+    description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/set_keybinding/reset_keybinding. target or query can also look up one keybinding action.',
   },
   fields: {
     type: 'object',
@@ -90,7 +90,7 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   target: {
     type: 'string',
-    description: 'Optional lookup target, such as a model-picker target, workspace action id/search text, slash command root or invocation, setting key/search text, model tool name, or connected-host capability id.',
+    description: 'Optional lookup target, such as a model-picker target, panel id/search text, UI surface id/search text, workspace action id/search text, slash command root or invocation, setting key/search text, keybinding action/search text, model tool name, or connected-host capability id.',
   },
   capabilityId: {
     type: 'string',

package/src/tools/agent-harness-tool.ts

@@ -595,9 +595,9 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             tools: deps.toolRegistry.getToolDefinitions().length,
             modelAccess: {
               cliCommands: 'Use mode:"cli_commands" and mode:"cli_command" to inspect package CLI mirrors and their preferred in-process model routes. CLI modes are discovery-only.',
-              panels: 'Use mode:"panels" and mode:"panel" to inspect built-in panel catalog/open state; use mode:"open_panel" with confirm:true plus explicitUserRequest to route a visible panel/workspace change.',
-              uiSurfaces: 'Use mode:"ui_surfaces" and mode:"ui_surface" to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
-              shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
+              panels: 'Use mode:"panels" to list and mode:"panel" with panelId, target, or query to inspect built-in panel catalog/open state; use mode:"open_panel" with confirm:true plus explicitUserRequest to route a visible panel/workspace change.',
+              uiSurfaces: 'Use mode:"ui_surfaces" to list and mode:"ui_surface" with surfaceId, target, or query to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
+              shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"keybinding" with actionId, target, key, or query; use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
               slashCommands: 'Use mode:"commands" to list slash commands and mode:"command" with command, commandName, target, or query to inspect one command; use mode:"run_command" with confirm:true plus explicitUserRequest to execute.',
               workspace: 'Use mode:"workspace_actions" to list and mode:"workspace_action" with actionId, command, target, or query for one action and editor schema; set includeParameters:true on workspace_actions to inline editor schemas.',
               settings: 'Use mode:"settings" to list and mode:"get_setting" with key, target, or query for one setting. Use mode:"set_setting" or mode:"reset_setting" with key, target, or query plus confirm:true and explicitUserRequest.',
@@ -633,7 +633,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         }
         if (args.mode === 'panel') {
           const panel = describeHarnessPanel(deps.commandContext, args);
-          return panel ? output(panel) : error(`Unknown panel ${readString(args.panelId || args.query) || '<missing>'}.`);
+          return panel ? output(panel) : error(`Unknown panel ${readString(args.panelId || args.target || args.query) || '<missing>'}.`);
         }
         if (args.mode === 'open_panel') {
           const confirmationError = requireConfirmedAction(args, 'Panel routing');
@@ -646,7 +646,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         }
         if (args.mode === 'ui_surface') {
           const surface = describeHarnessUiSurface(deps.commandContext, args);
-          return surface ? output(surface) : error(`Unknown UI surface ${readString(args.surfaceId || args.query) || '<missing>'}.`);
+          return surface ? output(surface) : error(`Unknown UI surface ${readString(args.surfaceId || args.query || args.target) || '<missing>'}.`);
         }
         if (args.mode === 'open_ui_surface') {
           const confirmationError = requireConfirmedAction(args, 'UI surface routing');
@@ -657,7 +657,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         if (args.mode === 'keybindings') return output(listHarnessKeybindings(deps.commandContext, args));
         if (args.mode === 'keybinding') {
           const binding = describeHarnessKeybinding(deps.commandContext, args);
-          return binding ? output(binding) : error(`Unknown keybinding action ${readString(args.actionId || args.key || args.query) || '<missing>'}.`);
+          return binding ? output(binding) : error(`Unknown keybinding action ${readString(args.actionId || args.target || args.key || args.query) || '<missing>'}.`);
         }
         if (args.mode === 'set_keybinding') {
           const confirmationError = requireConfirmedAction(args, 'Keybinding mutation');

package/src/tools/agent-harness-ui-surface-metadata.ts

@@ -27,6 +27,24 @@ interface UiSurfaceDefinition {
   readonly open: (context: CommandContext, args: AgentHarnessUiSurfaceArgs) => Record<string, unknown> | Promise<Record<string, unknown>>;
 }
 
+interface UiSurfaceLookup {
+  readonly source: 'surfaceId' | 'target' | 'query';
+  readonly input: string;
+  readonly resolvedBy: 'id' | 'case-insensitive-id' | 'label' | 'case-insensitive-label' | 'search';
+}
+
+type UiSurfaceResolution =
+  | {
+    readonly status: 'found';
+    readonly surface: UiSurfaceDefinition;
+    readonly lookup: UiSurfaceLookup;
+  }
+  | {
+    readonly status: 'ambiguous';
+    readonly input: string;
+    readonly candidates: readonly Record<string, unknown>[];
+  };
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -668,7 +686,17 @@ function surfaceMatches(surface: Record<string, unknown>, query: string): boolea
   ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
 }
 
-function describeSurface(context: CommandContext, surface: UiSurfaceDefinition): Record<string, unknown> {
+function surfaceLookupFromArgs(args: AgentHarnessUiSurfaceArgs): { readonly source: UiSurfaceLookup['source']; readonly input: string } | null {
+  const surfaceId = readString(args.surfaceId);
+  if (surfaceId) return { source: 'surfaceId', input: surfaceId };
+  const query = readString(args.query);
+  if (query) return { source: 'query', input: query };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  return null;
+}
+
+function surfaceCandidate(surface: UiSurfaceDefinition): Record<string, unknown> {
   return {
     id: surface.id,
     label: surface.label,
@@ -676,6 +704,38 @@ function describeSurface(context: CommandContext, surface: UiSurfaceDefinition):
     summary: surface.summary,
     command: surface.command,
     preferredModelRoute: surface.preferredModelRoute,
+  };
+}
+
+function resolveHarnessUiSurface(args: AgentHarnessUiSurfaceArgs): UiSurfaceResolution | null {
+  const lookup = surfaceLookupFromArgs(args);
+  if (!lookup) return null;
+  const exactId = UI_SURFACES.find((surface) => surface.id === lookup.input);
+  if (exactId) return { status: 'found', surface: exactId, lookup: { ...lookup, resolvedBy: 'id' } };
+  const exactLabel = UI_SURFACES.find((surface) => surface.label === lookup.input);
+  if (exactLabel) return { status: 'found', surface: exactLabel, lookup: { ...lookup, resolvedBy: 'label' } };
+  const inputLower = lookup.input.toLowerCase();
+  const ciId = UI_SURFACES.filter((surface) => surface.id.toLowerCase() === inputLower);
+  if (ciId.length === 1) return { status: 'found', surface: ciId[0]!, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } };
+  if (ciId.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: ciId.map(surfaceCandidate).slice(0, 8) };
+  const ciLabel = UI_SURFACES.filter((surface) => surface.label.toLowerCase() === inputLower);
+  if (ciLabel.length === 1) return { status: 'found', surface: ciLabel[0]!, lookup: { ...lookup, resolvedBy: 'case-insensitive-label' } };
+  if (ciLabel.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: ciLabel.map(surfaceCandidate).slice(0, 8) };
+  const search = UI_SURFACES.filter((surface) => surfaceMatches(surfaceCandidate(surface), lookup.input));
+  if (search.length === 1) return { status: 'found', surface: search[0]!, lookup: { ...lookup, resolvedBy: 'search' } };
+  if (search.length > 1) return { status: 'ambiguous', input: lookup.input, candidates: search.map(surfaceCandidate).slice(0, 8) };
+  return null;
+}
+
+function describeSurface(context: CommandContext, surface: UiSurfaceDefinition, lookup?: UiSurfaceLookup): Record<string, unknown> {
+  return {
+    id: surface.id,
+    label: surface.label,
+    kind: surface.kind,
+    summary: surface.summary,
+    command: surface.command,
+    ...(lookup ? { lookup } : {}),
+    preferredModelRoute: surface.preferredModelRoute,
     parameters: surface.parameters ?? [],
     available: surface.available(context),
     policy: {
@@ -700,25 +760,29 @@ export function listHarnessUiSurfaces(context: CommandContext, args: AgentHarnes
 }
 
 export function describeHarnessUiSurface(context: CommandContext, args: AgentHarnessUiSurfaceArgs): Record<string, unknown> | null {
-  const surfaceId = readString(args.surfaceId || args.query);
-  if (!surfaceId) return null;
-  const surface = UI_SURFACES.find((entry) => entry.id === surfaceId || entry.label.toLowerCase() === surfaceId.toLowerCase());
-  return surface ? describeSurface(context, surface) : null;
+  const resolved = resolveHarnessUiSurface(args);
+  if (resolved?.status === 'found') return describeSurface(context, resolved.surface, resolved.lookup);
+  if (resolved?.status === 'ambiguous') {
+    return { status: 'ambiguous', input: resolved.input, candidates: resolved.candidates };
+  }
+  return null;
 }
 
 export async function openHarnessUiSurface(context: CommandContext, args: AgentHarnessUiSurfaceArgs): Promise<Record<string, unknown>> {
-  const surfaceId = readString(args.surfaceId || args.query);
-  const surface = UI_SURFACES.find((entry) => entry.id === surfaceId || entry.label.toLowerCase() === surfaceId.toLowerCase());
-  if (!surface) {
+  const resolved = resolveHarnessUiSurface(args);
+  if (resolved?.status === 'ambiguous') {
+    return { status: 'ambiguous_ui_surface', input: resolved.input, candidates: resolved.candidates };
+  }
+  if (!resolved) {
     return {
       status: 'unknown_ui_surface',
-      surfaceId: surfaceId || '<missing>',
+      surfaceId: readString(args.surfaceId || args.query || args.target) || '<missing>',
       availableSurfaces: UI_SURFACES.map((entry) => entry.id),
     };
   }
-  const routed = await surface.open(context, args);
+  const routed = await resolved.surface.open(context, args);
   return {
     ...routed,
-    descriptor: describeSurface(context, surface),
+    descriptor: describeSurface(context, resolved.surface, resolved.lookup),
   };
 }