@pellux/goodvibes-agent 1.0.34 → 1.0.36

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

@@ -28,13 +28,12 @@ import { describeHarnessSession, sessionCatalogStatus, sessionSummary } from './
 import { describeHarnessServiceEndpoint, servicePostureCatalogStatus, servicePostureSummary } from './agent-harness-service-posture.ts';
 import { describeHarnessSetupItem, setupPostureCatalogStatus, setupPostureSummary } from './agent-harness-setup-posture.ts';
 import { AGENT_HARNESS_MODES, AGENT_HARNESS_PARAMETER_PROPERTIES } from './agent-harness-tool-schema.ts';
+import { describeHarnessMode, HARNESS_MODE_DESCRIPTORS, listHarnessModes, type AgentHarnessMode } from './agent-harness-mode-catalog.ts';
 import { describeHarnessUiSurface, listHarnessUiSurfaces, openHarnessUiSurface, totalHarnessUiSurfaces } from './agent-harness-ui-surface-metadata.ts';
 import { AGENT_WORKSPACE_CATEGORIES, allWorkspaceActions, buildWorkspaceEditorContext, createWorkspaceEditor, describeWorkspaceAction, describeWorkspaceCategory, describeWorkspaceEditor, listWorkspaceActions, resolveWorkspaceActionDetail } from './agent-harness-workspace-actions.ts';
 import { describeWorkspaceEditorModelExecution } from './agent-harness-workspace-editor-execution.ts';
 import { connectedHostSummary, describeConnectedHostCapability, settingsPolicySummary } from './agent-harness-metadata.ts';
-import { formatHarnessError, listHarnessSettings, resetHarnessSetting, resolveHarnessSetting, setHarnessSetting } from '../agent/harness-control.ts';
-
-type AgentHarnessMode = typeof AGENT_HARNESS_MODES[number];
+import { countHarnessSettings, formatHarnessError, listHarnessSettings, resetHarnessSetting, resolveHarnessSetting, setHarnessSetting } from '../agent/harness-control.ts';
 
 interface AgentHarnessToolArgs {
   readonly mode?: unknown;
@@ -127,31 +126,21 @@ function output(value: unknown): { readonly success: true; readonly output: stri
 
 function error(message: string): { readonly success: false; readonly error: string } { return { success: false, error: message }; }
 
+function harnessModeIdsByKind(kind: AgentHarnessModeGuideKind): readonly AgentHarnessMode[] {
+  return HARNESS_MODE_DESCRIPTORS
+    .filter((descriptor) => descriptor.kind === kind)
+    .map((descriptor) => descriptor.id);
+}
+
+type AgentHarnessModeGuideKind = typeof HARNESS_MODE_DESCRIPTORS[number]['kind'];
+
 function compactHarnessModeGuide(): Record<string, unknown> {
   return {
-    discover: [
-      'cli_commands', 'panels', 'ui_surfaces', 'shortcuts', 'keybindings',
-      'commands', 'channels', 'notifications', 'provider_accounts', 'mcp_servers',
-      'setup_posture', 'model_routing', 'pairing_posture', 'delegation_posture',
-      'security_posture', 'support_bundles', 'media_posture', 'sessions',
-      'settings', 'workspace', 'workspace_categories', 'workspace_actions',
-      'tools', 'release_evidence', 'release_readiness', 'operator_methods',
-      'service_posture', 'connected_host', 'daemon',
-    ],
-    inspect: [
-      'cli_command', 'panel', 'ui_surface', 'keybinding', 'command', 'channel',
-      'notification_target', 'provider_account', 'mcp_server', 'setup_item',
-      'model_route', 'pairing_route', 'delegation_route', 'security_finding',
-      'support_bundle', 'media_provider', 'session', 'get_setting',
-      'workspace_action', 'tool', 'release_evidence_artifact',
-      'release_readiness_item', 'operator_method', 'service_endpoint',
-      'connected_host_capability', 'connected_host_status', 'daemon_status',
-    ],
-    effects: [
-      'open_panel', 'open_ui_surface', 'run_keybinding', 'set_keybinding',
-      'reset_keybinding', 'run_command', 'set_setting', 'reset_setting',
-      'run_workspace_action',
-    ],
+    start: ['summary', 'modes', 'mode'],
+    discover: harnessModeIdsByKind('discover'),
+    inspect: harnessModeIdsByKind('inspect'),
+    effects: harnessModeIdsByKind('effect'),
+    aliases: harnessModeIdsByKind('alias'),
     pattern: 'Use query|target for search, exact ids for inspect modes, and confirm:true plus explicitUserRequest for effects.',
   };
 }
@@ -175,15 +164,16 @@ function detailedHarnessModelAccessGuide(): Record<string, string> {
     supportBundles: 'List mode:"support_bundles"; inspect mode:"support_bundle"; export/import stays confirmation-gated.',
     mediaPosture: 'List mode:"media_posture"; inspect mode:"media_provider"; generate with agent_media_generate and confirmation.',
     sessions: 'List mode:"sessions"; inspect mode:"session"; save/resume/export/delete stays visible confirmed flow.',
-    workspace: 'List mode:"workspace" or mode:"workspace_categories"; actions via workspace_actions/workspace_action/run_workspace_action; includeParameters:true inlines editor schemas.',
-    settings: 'List mode:"settings" with category|prefix|query|includeHidden:true; get_setting/set_setting/reset_setting use key|target|query and confirmation for writes.',
+    workspace: 'List mode:"workspace" or mode:"workspace_categories"; actions via mode:"workspace_actions", mode:"workspace_action", and mode:"run_workspace_action"; includeParameters:true inlines editor schemas.',
+    settings: 'List mode:"settings" with category|prefix|query|includeHidden:true; mode:"get_setting", mode:"set_setting", and mode:"reset_setting" use key|target|query; writes require confirmation.',
     tools: 'List mode:"tools" with query|limit|includeParameters:true; inspect mode:"tool" with toolName|target|query.',
-    releaseEvidence: 'List mode:"release_evidence"; inspect mode:"release_evidence_artifact"; includeParameters:true inlines artifact detail.',
-    releaseReadiness: 'List mode:"release_readiness"; inspect mode:"release_readiness_item"; includeParameters:true inlines item detail.',
+    modeCatalog: 'Search mode:"modes" with query|target; inspect one contract with mode:"mode" target:"...".',
+    releaseEvidence: 'Operator/audit: list mode:"release_evidence"; inspect mode:"release_evidence_artifact"; includeParameters:true inlines artifact detail.',
+    releaseReadiness: 'Operator/audit: list mode:"release_readiness"; inspect mode:"release_readiness_item"; includeParameters:true inlines item detail.',
     operatorMethods: 'List mode:"operator_methods"; inspect mode:"operator_method"; execute only through the returned first-class tool.',
     servicePosture: 'List mode:"service_posture"; inspect mode:"service_endpoint"; includeParameters:true adds probes and redacted log tail.',
     connectedHost: 'Map mode:"connected_host"; inspect mode:"connected_host_capability"; no lifecycle control.',
-    connectedHostStatus: 'Live read-only mode:"connected_host_status" for host reachability, SDK compatibility, token posture, and Knowledge readiness.',
+    connectedHostStatus: 'Live read-only mode:"connected_host_status" for host reachability, token posture, and Knowledge readiness.',
     daemon: 'Daemon aliases route to mode:"connected_host" and mode:"connected_host_status"; lifecycle control is not exposed.',
   };
 }
@@ -392,7 +382,7 @@ async function runWorkspaceAction(
   }
   if (action.kind === 'editor' && action.editorKind) {
     const editor = createWorkspaceEditor(action.editorKind, buildWorkspaceEditorContext(deps.commandContext, args));
-    if (!editor) return error(`No workspace editor bridge exists for ${action.editorKind}.`);
+    if (!editor) return error(`No workspace editor route exists for ${action.editorKind}.`);
     return runWorkspaceEditorAction(deps, action, editor, args);
   }
   if (action.kind === 'local-selection' || action.kind === 'local-operation') {
@@ -425,6 +415,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
       try {
         if (args.mode === 'summary') {
           return output({
+            harnessModes: HARNESS_MODE_DESCRIPTORS.length,
             cliCommands: totalHarnessCliCommands(),
             blockedCliCommandTokens: blockedHarnessCliCommandTokens(),
             panels: totalHarnessPanels(deps.commandContext),
@@ -472,6 +463,13 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             }),
           });
         }
+        if (args.mode === 'modes') return output(listHarnessModes(args));
+        if (args.mode === 'mode') {
+          const mode = describeHarnessMode(args);
+          if (mode.status === 'ambiguous') return error(`Ambiguous harness mode ${String(mode.input)}. Candidates: ${JSON.stringify(mode.candidates)}`);
+          if (mode.status === 'missing_lookup') return error(String(mode.usage));
+          return output(mode.mode);
+        }
         if (args.mode === 'cli_commands') {
           const commands = listHarnessCliCommands(args);
           return output({
@@ -491,7 +489,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             panels,
             returned: panels.length,
             total: totalHarnessPanels(deps.commandContext),
-            policy: 'Panel modes expose Agent/TUI operator view catalog and open state. open_panel is confirmation-gated and routes through the current Agent shell bridge.',
+            policy: 'Panel modes expose Agent/TUI operator view catalog and open state. open_panel is confirmation-gated and routes through the current Agent operator surface.',
           });
         }
         if (args.mode === 'panel') {
@@ -630,16 +628,20 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           return error(resolved.usage);
         }
         if (args.mode === 'settings') {
-          const settings = listHarnessSettings(deps.commandContext.platform.configManager, {
+          const filters = {
             category: readString(args.category) || undefined,
             prefix: readString(args.prefix) || undefined,
             query: readString(args.query) || undefined,
             includeHidden: args.includeHidden === true,
-            limit: readLimit(args.limit, 100),
+            limit: readLimit(args.limit, 500),
+          };
+          const settings = listHarnessSettings(deps.commandContext.platform.configManager, {
+            ...filters,
           }, {
             includeParameters: args.includeParameters === true,
           });
-          return output({ settings, returned: settings.length, policy: settingsPolicySummary() });
+          const total = countHarnessSettings(deps.commandContext.platform.configManager, filters);
+          return output({ settings, returned: settings.length, total, policy: settingsPolicySummary() });
         }
         if (args.mode === 'get_setting') {
           const setting = resolveHarnessSetting(deps.commandContext.platform.configManager, settingLookupArgs(args));

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

@@ -3,6 +3,10 @@ import { openTtsProviderPicker, openTtsVoicePicker } from '../input/tts-settings
 
 type UiSurfaceKind = 'overlay' | 'modal' | 'workspace' | 'picker';
 
+function agentHarnessModes(...modes: readonly string[]): string {
+  return `agent_harness ${modes.map((mode) => `mode:"${mode}"`).join(', ')}`;
+}
+
 export interface AgentHarnessUiSurfaceArgs {
   readonly query?: unknown;
   readonly surfaceId?: unknown;
@@ -70,7 +74,7 @@ function opened(surface: UiSurfaceDefinition, extra: Record<string, unknown> = {
     surface: surface.id,
     kind: surface.kind,
     ...extra,
-    note: 'UI routing was handed to the current Agent shell bridge.',
+    note: 'UI routing was handed to the current Agent operator surface.',
   };
 }
 
@@ -150,20 +154,28 @@ function openPanelWorkspaceSurface(
       categoryId: options.categoryId,
       panelId: options.panelId,
       pane: pane ?? 'default',
-      route: 'panel-bridge',
+      route: 'panel-route',
     });
   }
   return routeUnavailable(surface);
 }
 
+function openSimpleContextSurface(context: CommandContext, surfaceId: string, openerKey: keyof CommandContext): Record<string, unknown> {
+  const surface = findSurfaceById(surfaceId)!;
+  const opener = context[openerKey] as unknown;
+  if (typeof opener !== 'function') return routeUnavailable(surface);
+  (opener as () => void)();
+  return opened(surface);
+}
+
 const UI_SURFACES: readonly UiSurfaceDefinition[] = [
   {
     id: 'agent-workspace',
     label: 'Agent Workspace',
     kind: 'workspace',
-    summary: 'Fullscreen operator workspace with setup, knowledge, local state, channels, automation, and delegation routes.',
+    summary: 'Operator workspace for setup, knowledge, channels, and automation.',
     command: '/agent',
-    preferredModelRoute: 'Use workspace_actions/workspace_action/run_workspace_action for model operation; use open_ui_surface only to visibly navigate.',
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['categoryId'],
     available: (context) => typeof context.openAgentWorkspace === 'function',
     open: (context, args) => {
@@ -178,9 +190,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'panel-picker',
     label: 'Panel Picker',
     kind: 'picker',
-    summary: 'Keyboard-accessible operator panel route that now opens the Agent Workspace home surface.',
+    summary: 'Operator panel route into Agent Workspace home.',
     command: 'Ctrl+P',
-    preferredModelRoute: 'Use panels/panel/open_panel for panel catalog and routing, or workspace_actions for concrete model operation.',
+    preferredModelRoute: `Use ${agentHarnessModes('panels', 'panel', 'open_panel')} for panel catalog and routing, or mode:"workspace_actions" for concrete model operation.`,
     available: (context) => typeof context.openPanelPicker === 'function' || typeof context.openAgentWorkspace === 'function',
     open: (context) => {
       const surface = findSurfaceById('panel-picker')!;
@@ -195,15 +207,11 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'security-panel',
     label: 'Security Panel',
     kind: 'workspace',
-    summary: 'Security review operator surface for token posture, MCP attack paths, policy posture, and plugin risk.',
+    summary: 'Operator security review for tokens, MCP, policy, and plugin risk.',
     command: '/security',
-    preferredModelRoute: 'Use workspace_actions for security review actions or run_command /security review for compact read-only output.',
+    preferredModelRoute: `Use mode:"workspace_actions" for security review actions or ${agentHarnessModes('run_command')} for confirmed /security review output.`,
     parameters: ['pane'],
-    available: (context) => (
-      typeof context.openAgentWorkspace === 'function'
-      || typeof context.openSecurityPanel === 'function'
-      || typeof context.showPanel === 'function'
-    ),
+    available: (context) => typeof context.openAgentWorkspace === 'function' || typeof context.openSecurityPanel === 'function' || typeof context.showPanel === 'function',
     open: (context, args) => {
       const surface = findSurfaceById('security-panel')!;
       return openPanelWorkspaceSurface(context, args, surface, {
@@ -217,15 +225,11 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'knowledge-panel',
     label: 'Knowledge Panel',
     kind: 'workspace',
-    summary: 'Agent Knowledge operator surface for isolated status, source/node/issue libraries, item lookup, map review, connectors, ask/search, and ingest forms.',
+    summary: 'Operator Knowledge surface for isolated status, search, and ingest.',
     command: '/knowledge',
-    preferredModelRoute: 'Use agent_knowledge, agent_knowledge_ingest, workspace_actions, or run_command /knowledge for concrete model operation.',
+    preferredModelRoute: `Use agent_knowledge, agent_knowledge_ingest, mode:"workspace_actions", or ${agentHarnessModes('run_command')} for confirmed /knowledge operation.`,
     parameters: ['pane'],
-    available: (context) => (
-      typeof context.openAgentWorkspace === 'function'
-      || typeof context.openKnowledgePanel === 'function'
-      || typeof context.showPanel === 'function'
-    ),
+    available: (context) => typeof context.openAgentWorkspace === 'function' || typeof context.openKnowledgePanel === 'function' || typeof context.showPanel === 'function',
     open: (context, args) => {
       const surface = findSurfaceById('knowledge-panel')!;
       return openPanelWorkspaceSurface(context, args, surface, {
@@ -239,15 +243,11 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'subscription-panel',
     label: 'Subscription Panel',
     kind: 'workspace',
-    summary: 'Provider subscription operator surface for subscription review, provider inspection, login, logout, and bundle flows.',
+    summary: 'Operator subscription surface for provider review, auth, and bundles.',
     command: '/subscription',
-    preferredModelRoute: 'Use workspace_actions or confirmed run_command /subscription mirrors for concrete subscription operation.',
+    preferredModelRoute: `Use mode:"workspace_actions" or ${agentHarnessModes('run_command')} for confirmed /subscription mirrors.`,
     parameters: ['pane'],
-    available: (context) => (
-      typeof context.openAgentWorkspace === 'function'
-      || typeof context.openSubscriptionPanel === 'function'
-      || typeof context.showPanel === 'function'
-    ),
+    available: (context) => typeof context.openAgentWorkspace === 'function' || typeof context.openSubscriptionPanel === 'function' || typeof context.showPanel === 'function',
     open: (context, args) => {
       const surface = findSurfaceById('subscription-panel')!;
       return openPanelWorkspaceSurface(context, args, surface, {
@@ -261,9 +261,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'settings',
     label: 'Settings',
     kind: 'modal',
-    summary: 'Fullscreen settings workspace for Agent-owned configuration, subscriptions, secrets, MCP, tools, and surface settings.',
+    summary: 'Fullscreen settings workspace for Agent config, secrets, MCP, and tools.',
     command: '/settings',
-    preferredModelRoute: 'Use settings/get_setting/set_setting/reset_setting for model operation; use open_ui_surface only to visibly navigate.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} for model operation; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['target', 'key', 'prefix'],
     available: (context) => typeof context.openSettingsModal === 'function',
     open: (context, args) => {
@@ -280,14 +280,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'workspace',
     summary: 'MCP server setup, trust posture, and tool inventory workspace.',
     command: '/mcp',
-    preferredModelRoute: 'Use workspace_actions, tools, and settings modes for model operation.',
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'tools', 'settings')} for model operation.`,
     available: (context) => typeof context.openMcpWorkspace === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('mcp-workspace')!;
-      if (!context.openMcpWorkspace) return routeUnavailable(surface);
-      context.openMcpWorkspace();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'mcp-workspace', 'openMcpWorkspace'),
   },
   {
     id: 'model-picker',
@@ -295,7 +290,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive model picker for main, helper, tool, and TTS model routes.',
     command: '/model',
-    preferredModelRoute: 'Use settings mode for direct provider.model changes, or run_command /model with confirmation when a concrete model id is known.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for direct provider.model changes, or mode:"run_command" with confirmation when a concrete model id is known.`,
     parameters: ['target'],
     available: (context) => typeof context.openModelPicker === 'function' || typeof context.openModelPickerWithTarget === 'function',
     open: (context, args) => {
@@ -316,7 +311,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'picker',
     summary: 'Interactive provider picker for model route setup.',
     command: '/provider',
-    preferredModelRoute: 'Use settings mode for direct provider routing changes, or run confirmed slash-command mirrors for concrete provider changes.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for direct provider routing changes, or confirmed mode:"run_command" mirrors for concrete provider changes.`,
     parameters: ['target'],
     available: (context) => typeof context.openProviderPicker === 'function' || typeof context.openProviderModelPickerWithTarget === 'function',
     open: (context, args) => {
@@ -335,9 +330,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'reasoning-effort-picker',
     label: 'Reasoning Effort Picker',
     kind: 'picker',
-    summary: 'Interactive reasoning-effort selector for the current main chat model when that model exposes effort levels.',
+    summary: 'Reasoning-effort selector for models that expose effort levels.',
     command: '/effort',
-    preferredModelRoute: 'Use settings/get_setting/set_setting for provider.reasoningEffort when a concrete level is known, or run_workspace_action setup-effort with confirmation.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for provider.reasoningEffort when a concrete level is known, or mode:"run_workspace_action" setup-effort with confirmation.`,
     available: (context) => typeof context.openReasoningEffortPicker === 'function',
     open: (context) => {
       const surface = findSurfaceById('reasoning-effort-picker')!;
@@ -363,9 +358,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'tts-provider-picker',
     label: 'TTS Provider Picker',
     kind: 'picker',
-    summary: 'Interactive streaming TTS provider picker opened from the Agent settings flow.',
+    summary: 'Streaming TTS provider picker from Agent settings.',
     command: '/config tts.provider',
-    preferredModelRoute: 'Use settings/get_setting/set_setting for tts.provider when a concrete provider id is known; use open_ui_surface only to visibly navigate.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting')} for tts.provider when a concrete provider id is known; use mode:"open_ui_surface" only to visibly navigate.`,
     available: (context) => typeof context.openSelection === 'function' && Boolean(context.platform.voiceProviderRegistry),
     open: (context) => {
       const surface = findSurfaceById('tts-provider-picker')!;
@@ -378,9 +373,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'tts-voice-picker',
     label: 'TTS Voice Picker',
     kind: 'picker',
-    summary: 'Interactive TTS voice picker opened from the Agent settings flow for the selected or supplied provider.',
+    summary: 'TTS voice picker for the selected or supplied provider.',
     command: '/config tts.voice',
-    preferredModelRoute: 'Use settings/get_setting/set_setting/reset_setting for tts.voice when a concrete voice id is known; use open_ui_surface only to visibly navigate.',
+    preferredModelRoute: `Use ${agentHarnessModes('settings', 'get_setting', 'set_setting', 'reset_setting')} for tts.voice when a concrete voice id is known; use mode:"open_ui_surface" only to visibly navigate.`,
     parameters: ['target'],
     available: (context) => typeof context.openSelection === 'function' && Boolean(context.platform.voiceService),
     open: async (context, args) => {
@@ -401,12 +396,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/sessions',
     preferredModelRoute: 'Use session slash-command mirrors with confirmation for concrete save/load/export actions.',
     available: (context) => typeof context.openSessionPicker === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('session-picker')!;
-      if (!context.openSessionPicker) return routeUnavailable(surface);
-      context.openSessionPicker();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'session-picker', 'openSessionPicker'),
   },
   {
     id: 'profile-picker',
@@ -416,12 +406,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/agent-profile',
     preferredModelRoute: 'Use workspace profile actions or profile slash-command mirrors for concrete model operation.',
     available: (context) => typeof context.openProfilePicker === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('profile-picker')!;
-      if (!context.openProfilePicker) return routeUnavailable(surface);
-      context.openProfilePicker();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'profile-picker', 'openProfilePicker'),
   },
   {
     id: 'bookmark-modal',
@@ -431,12 +416,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/bookmarks',
     preferredModelRoute: 'Use slash-command mirrors for concrete bookmark inspection; opening is visible navigation only.',
     available: (context) => typeof context.openBookmarkModal === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('bookmark-modal')!;
-      if (!context.openBookmarkModal) return routeUnavailable(surface);
-      context.openBookmarkModal();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'bookmark-modal', 'openBookmarkModal'),
   },
   {
     id: 'context-inspector',
@@ -446,33 +426,23 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     command: '/context',
     preferredModelRoute: 'Use slash-command mirrors for text output; opening is visible navigation only.',
     available: (context) => typeof context.openContextInspector === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('context-inspector')!;
-      if (!context.openContextInspector) return routeUnavailable(surface);
-      context.openContextInspector();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'context-inspector', 'openContextInspector'),
   },
   {
     id: 'process-monitor',
     label: 'Runtime Activity Monitor',
     kind: 'modal',
-    summary: 'Visible running-process and live-output monitor opened by the same shell route as F2.',
+    summary: 'Visible running-process and live-output monitor.',
     command: 'F2',
     preferredModelRoute: 'Use this only for visible supervision of runtime activity; use first-class model tools or confirmed commands for actual operations.',
     available: (context) => typeof context.openProcessModal === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('process-monitor')!;
-      if (!context.openProcessModal) return routeUnavailable(surface);
-      context.openProcessModal();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'process-monitor', 'openProcessModal'),
   },
   {
     id: 'live-tail',
     label: 'Live Process Output',
     kind: 'modal',
-    summary: 'Visible live-output tail for a running process, opened by the same shell route as Enter from the runtime activity monitor.',
+    summary: 'Visible live-output tail for a running process.',
     command: 'F2, Enter',
     preferredModelRoute: 'Use this only for visible supervision of a running process output stream; use first-class model tools or confirmed commands for actual operations.',
     parameters: ['target', 'query', 'prefix', 'key'],
@@ -504,7 +474,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'conversation-search',
     label: 'Conversation Search',
     kind: 'overlay',
-    summary: 'Visible transcript search overlay opened by the same shell route as Ctrl+F.',
+    summary: 'Visible transcript search overlay.',
     command: 'Ctrl+F',
     preferredModelRoute: 'Use conversation/session/content modes for model-readable inspection; use this surface for visible transcript search navigation.',
     parameters: ['query', 'prefix', 'key'],
@@ -521,7 +491,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'prompt-history-search',
     label: 'Prompt History Search',
     kind: 'overlay',
-    summary: 'Visible reverse prompt-history search opened by the same shell route as Ctrl+R.',
+    summary: 'Visible reverse prompt-history search.',
     command: 'Ctrl+R',
     preferredModelRoute: 'Use this only for visible prompt recall; accepting a result remains an explicit interactive shell action.',
     parameters: ['query', 'prefix', 'key'],
@@ -538,9 +508,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'slash-command-mode',
     label: 'Slash Command Mode',
     kind: 'overlay',
-    summary: 'Slash-command autocomplete route opened by the same shell path as typing / in an empty prompt.',
+    summary: 'Slash-command autocomplete route for empty prompts.',
     command: '/',
-    preferredModelRoute: 'Use commands/command for model-readable command discovery and run_command for confirmed command execution.',
+    preferredModelRoute: `Use ${agentHarnessModes('commands', 'command')} for model-readable command discovery and mode:"run_command" for confirmed command execution.`,
     parameters: ['query', 'prefix', 'key'],
     available: (context) => typeof context.openSlashCommandMode === 'function',
     open: (context, args) => {
@@ -563,9 +533,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'command-browser',
     label: 'Command Browser',
     kind: 'picker',
-    summary: 'Registry-driven searchable slash-command browser opened by /commands and /help.',
+    summary: 'Searchable slash-command browser opened by commands or help.',
     command: '/commands',
-    preferredModelRoute: 'Use commands/command for model-readable slash-command discovery and run_command for confirmed command execution.',
+    preferredModelRoute: `Use ${agentHarnessModes('commands', 'command')} for model-readable slash-command discovery and mode:"run_command" for confirmed command execution.`,
     available: (context) => typeof context.executeCommand === 'function',
     open: async (context) => {
       const surface = findSurfaceById('command-browser')!;
@@ -585,7 +555,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'file-picker',
     label: 'File Picker',
     kind: 'picker',
-    summary: 'Visible project file picker opened by the same prompt route as @ and !@ references.',
+    summary: 'Visible project file picker for file references and injection.',
     command: '@',
     preferredModelRoute: 'Use first-class file, workspace, or artifact tools for model operation; use this for visible file reference navigation.',
     parameters: ['target=reference|inject', 'query', 'prefix', 'key'],
@@ -604,7 +574,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     id: 'block-actions',
     label: 'Block Actions',
     kind: 'overlay',
-    summary: 'Visible nearest-block action menu opened by the same shell route as pressing Enter on an empty prompt near transcript content.',
+    summary: 'Visible nearest-block action menu for transcript content.',
     command: 'Enter on empty prompt',
     preferredModelRoute: 'Use conversation/session/content modes or confirmed slash-command mirrors for concrete block operations; use this surface for visible block-action navigation.',
     available: (context) => typeof context.openBlockActions === 'function',
@@ -628,14 +598,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'overlay',
     summary: 'Registry-driven command and shortcut help overlay.',
     command: '/help',
-    preferredModelRoute: 'Use commands/command and shortcuts modes for model-readable discovery.',
+    preferredModelRoute: `Use ${agentHarnessModes('commands', 'command', 'shortcuts')} for model-readable discovery.`,
     available: (context) => typeof context.openHelpOverlay === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('help-overlay')!;
-      if (!context.openHelpOverlay) return routeUnavailable(surface);
-      context.openHelpOverlay();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'help-overlay', 'openHelpOverlay'),
   },
   {
     id: 'shortcuts-overlay',
@@ -643,14 +608,9 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'overlay',
     summary: 'Keyboard shortcut reference overlay.',
     command: '/shortcuts',
-    preferredModelRoute: 'Use shortcuts/keybindings modes for model-readable discovery, run_keybinding for supported shell-safe actions, and confirmed keybinding edits for binding changes.',
+    preferredModelRoute: `Use ${agentHarnessModes('shortcuts', 'keybindings')} for model-readable discovery, mode:"run_keybinding" for supported shell-safe actions, and confirmed keybinding edits for binding changes.`,
     available: (context) => typeof context.openShortcutsOverlay === 'function',
-    open: (context) => {
-      const surface = findSurfaceById('shortcuts-overlay')!;
-      if (!context.openShortcutsOverlay) return routeUnavailable(surface);
-      context.openShortcutsOverlay();
-      return opened(surface);
-    },
+    open: (context) => openSimpleContextSurface(context, 'shortcuts-overlay', 'openShortcutsOverlay'),
   },
   {
     id: 'onboarding',
@@ -658,7 +618,7 @@ const UI_SURFACES: readonly UiSurfaceDefinition[] = [
     kind: 'modal',
     summary: 'First-run and setup review wizard for Agent readiness.',
     command: '/setup',
-    preferredModelRoute: 'Use workspace setup actions and settings modes for concrete model operation.',
+    preferredModelRoute: `Use ${agentHarnessModes('workspace_actions', 'settings')} for concrete setup operation.`,
     parameters: ['target=new|edit|reopen'],
     available: (context) => typeof context.openOnboardingWizard === 'function',
     open: (context, args) => {
@@ -683,6 +643,7 @@ function surfaceMatches(surface: Record<string, unknown>, query: string): boolea
     surface.kind,
     surface.summary,
     surface.command,
+    surface.modelRoute,
     surface.preferredModelRoute,
   ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
 }
@@ -704,10 +665,52 @@ function surfaceCandidate(surface: UiSurfaceDefinition): Record<string, unknown>
     kind: surface.kind,
     summary: surface.summary,
     command: surface.command,
-    preferredModelRoute: surface.preferredModelRoute,
+    modelRoute: uiSurfaceModelRoute(surface),
   };
 }
 
+function uiSurfaceModelRoute(surface: UiSurfaceDefinition): string {
+  switch (surface.id) {
+    case 'agent-workspace':
+    case 'panel-picker':
+    case 'security-panel':
+    case 'subscription-panel':
+    case 'mcp-workspace':
+    case 'onboarding':
+      return 'agent_harness mode:"workspace_actions" or mode:"open_ui_surface"';
+    case 'knowledge-panel':
+      return 'agent_knowledge, agent_knowledge_ingest, or workspace_actions';
+    case 'settings':
+    case 'tts-provider-picker':
+    case 'tts-voice-picker':
+    case 'reasoning-effort-picker':
+      return 'agent_harness mode:"settings" or mode:"open_ui_surface"';
+    case 'model-picker':
+    case 'provider-picker':
+      return 'agent_harness mode:"settings" or mode:"run_command"';
+    case 'session-picker':
+    case 'bookmark-modal':
+    case 'context-inspector':
+    case 'slash-command-mode':
+    case 'command-browser':
+    case 'block-actions':
+      return 'agent_harness mode:"commands" or mode:"run_command"';
+    case 'process-monitor':
+    case 'live-tail':
+    case 'file-picker':
+      return 'first-class tools or agent_harness mode:"open_ui_surface"';
+    case 'conversation-search':
+    case 'prompt-history-search':
+      return 'agent_harness mode:"open_ui_surface"';
+    case 'help-overlay':
+      return 'agent_harness mode:"commands" or mode:"shortcuts"';
+    case 'shortcuts-overlay':
+      return 'agent_harness mode:"shortcuts" or mode:"keybindings"';
+    default:
+      return 'agent_harness mode:"open_ui_surface"';
+  }
+}
+
 function resolveHarnessUiSurface(args: AgentHarnessUiSurfaceArgs): UiSurfaceResolution | null {
   const lookup = surfaceLookupFromArgs(args);
   if (!lookup) return null;
@@ -740,9 +743,10 @@ function describeSurface(
     summary: surface.summary,
     command: surface.command,
     ...(options.lookup ? { lookup: options.lookup } : {}),
-    preferredModelRoute: surface.preferredModelRoute,
+    modelRoute: uiSurfaceModelRoute(surface),
     available: surface.available(context),
     ...(options.includeParameters ? {
+      preferredModelRoute: surface.preferredModelRoute,
       parameters: surface.parameters ?? [],
       policy: {
         effect: 'visible-ui-navigation',