@pellux/goodvibes-agent 1.0.3 → 1.0.5

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

@@ -18,9 +18,12 @@ import type {
 } from '../input/agent-workspace-types.ts';
 import { parseSlashCommand } from '../input/slash-command-parser.ts';
 import { blockedHarnessCliCommandTokens, describeHarnessCliCommand, listHarnessCliCommands, totalHarnessCliCommands } from './agent-harness-cli-metadata.ts';
+import { describeHarnessKeybinding, listHarnessKeybindings, listHarnessShortcuts, resetHarnessKeybinding, setHarnessKeybinding, totalHarnessKeybindings, totalHarnessShortcuts } from './agent-harness-keybinding-metadata.ts';
 import { describeHarnessPanel, listHarnessPanels, openHarnessPanel, totalHarnessPanels } from './agent-harness-panel-metadata.ts';
 import { describeLocalWorkspaceModelExecution, runLocalWorkspaceAction } from './agent-harness-local-operations.ts';
 import { listHarnessModelTools } from './agent-harness-model-tool-catalog.ts';
+import { AGENT_HARNESS_MODES, AGENT_HARNESS_PARAMETER_PROPERTIES } from './agent-harness-tool-schema.ts';
+import { describeHarnessUiSurface, listHarnessUiSurfaces, openHarnessUiSurface, totalHarnessUiSurfaces } from './agent-harness-ui-surface-metadata.ts';
 import {
   connectedHostSummary,
   describeCommandPolicy,
@@ -34,27 +37,7 @@ import {
   setHarnessSetting,
 } from '../agent/harness-control.ts';
 
-type AgentHarnessMode =
-  | 'summary'
-  | 'cli_commands'
-  | 'cli_command'
-  | 'panels'
-  | 'panel'
-  | 'open_panel'
-  | 'commands'
-  | 'command'
-  | 'run_command'
-  | 'settings'
-  | 'get_setting'
-  | 'set_setting'
-  | 'reset_setting'
-  | 'workspace'
-  | 'workspace_categories'
-  | 'workspace_actions'
-  | 'workspace_action'
-  | 'run_workspace_action'
-  | 'tools'
-  | 'connected_host';
+type AgentHarnessMode = typeof AGENT_HARNESS_MODES[number];
 
 interface AgentHarnessToolArgs {
   readonly mode?: unknown;
@@ -68,8 +51,12 @@ interface AgentHarnessToolArgs {
   readonly actionId?: unknown;
   readonly recordId?: unknown;
   readonly fields?: unknown;
+  readonly combo?: unknown;
+  readonly combos?: unknown;
+  readonly surfaceId?: unknown;
   readonly key?: unknown;
   readonly value?: unknown;
+  readonly target?: unknown;
   readonly category?: unknown;
   readonly prefix?: unknown;
   readonly includeHidden?: unknown;
@@ -91,31 +78,8 @@ interface WorkspaceEditorContext {
   readonly selectedRoutine: AgentWorkspaceLocalLibraryItem | null;
 }
 
-const MODES: readonly AgentHarnessMode[] = [
-  'summary',
-  'cli_commands',
-  'cli_command',
-  'panels',
-  'panel',
-  'open_panel',
-  'commands',
-  'command',
-  'run_command',
-  'settings',
-  'get_setting',
-  'set_setting',
-  'reset_setting',
-  'workspace',
-  'workspace_categories',
-  'workspace_actions',
-  'workspace_action',
-  'run_workspace_action',
-  'tools',
-  'connected_host',
-];
-
 function isMode(value: unknown): value is AgentHarnessMode {
-  return typeof value === 'string' && MODES.includes(value as AgentHarnessMode);
+  return typeof value === 'string' && AGENT_HARNESS_MODES.includes(value as AgentHarnessMode);
 }
 
 function readString(value: unknown): string {
@@ -145,9 +109,7 @@ 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 error(message: string): { readonly success: false; readonly error: string } { return { success: false, error: message }; }
 
 function commandMatches(command: SlashCommand, query: string): boolean {
   if (!query) return true;
@@ -541,106 +503,13 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
       name: 'agent_harness',
       description: [
         'Discover and operate the GoodVibes Agent harness from the main conversation.',
-        'Use this tool to inspect Agent workspace actions, built-in panels, top-level CLI mirrors, slash commands with policy metadata, model tools, connected-host capabilities, and Agent settings, or to invoke a workspace action/command through the same in-process command registry the user uses in the TUI.',
-        'Discovery modes are read-only. Setting writes, resets, slash command invocation, and workspace action invocation require confirm:true plus explicitUserRequest.',
+        'Use this tool to inspect Agent workspace actions, built-in panels, top-level CLI mirrors, UI surfaces, keybindings, slash commands with policy metadata, model tools, connected-host capabilities, and Agent settings, or to invoke a workspace action/command through the same in-process command registry the user uses in the TUI.',
+        'Discovery modes are read-only. Setting/keybinding writes, resets, UI routing, slash command invocation, and workspace action invocation require confirm:true plus explicitUserRequest.',
         'This tool preserves Agent product boundaries: connected-host lifecycle and listener posture stay externally owned, connected-host mode reports allowed and blocked route families, and secret-backed settings store raw values through the secret manager while config receives only a secret reference.',
       ].join(' '),
       parameters: {
         type: 'object',
-        properties: {
-          mode: {
-            type: 'string',
-            enum: MODES,
-            description: 'Harness operation to perform.',
-          },
-          query: {
-            type: 'string',
-            description: 'Search text for command, setting, or tool catalogs.',
-          },
-          command: {
-            type: 'string',
-            description: 'Full slash command string for mode run_command, for example "/settings get provider.model". In cli_command mode this may also hold a top-level CLI string such as "goodvibes-agent status --json".',
-          },
-          cliCommand: {
-            type: 'string',
-            description: 'Top-level CLI command string for mode cli_command, for example "goodvibes-agent status --json" or "profiles list". This mode is read-only metadata/parse inspection.',
-          },
-          commandName: {
-            type: 'string',
-            description: 'Slash command root without the leading slash for mode command or run_command, or a top-level CLI command token for cli_command.',
-          },
-          args: {
-            type: 'array',
-            items: { type: 'string' },
-            description: 'Slash command argument tokens for mode run_command when commandName is used.',
-          },
-          categoryId: {
-            type: 'string',
-            description: 'Agent workspace category id for workspace action filtering.',
-          },
-          panelId: {
-            type: 'string',
-            description: 'Built-in panel id for panel or open_panel modes.',
-          },
-          actionId: {
-            type: 'string',
-            description: 'Agent workspace action id for workspace_action or run_workspace_action.',
-          },
-          fields: {
-            type: 'object',
-            additionalProperties: { type: 'string' },
-            description: 'Field values for run_workspace_action when the workspace action opens an editor form.',
-          },
-          recordId: {
-            type: 'string',
-            description: 'Selected Agent-local record id for selection-based local workspace operations.',
-          },
-          key: {
-            type: 'string',
-            description: 'Agent setting key for get_setting, set_setting, or reset_setting.',
-          },
-          value: {
-            anyOf: [
-              { type: 'string' },
-              { type: 'number' },
-              { type: 'boolean' },
-            ],
-            description: 'Setting value for set_setting. Strings, booleans, numbers, and enum strings are accepted.',
-          },
-          category: {
-            type: 'string',
-            description: 'Setting category filter such as provider, behavior, tools, ui, tts, permissions, automation, or surfaces.',
-          },
-          prefix: {
-            type: 'string',
-            description: 'Setting key prefix filter such as surfaces.slack.',
-          },
-          includeHidden: {
-            type: 'boolean',
-            description: 'Include settings hidden from the Agent workspace because they are host-owned or non-Agent lifecycle settings.',
-          },
-          includeParameters: {
-            type: 'boolean',
-            description: 'Include model tool JSON schemas in tools mode, or workspace editor field schemas in workspace_actions mode.',
-          },
-          limit: {
-            type: 'number',
-            description: 'Maximum catalog entries to return.',
-          },
-          pane: {
-            type: 'string',
-            enum: ['top', 'bottom'],
-            description: 'Preferred panel pane for open_panel when the current shell supports panel routing.',
-          },
-          confirm: {
-            type: 'boolean',
-            description: 'Required true for set_setting, reset_setting, run_command, open_panel, and mutating run_workspace_action calls after an explicit user request.',
-          },
-          explicitUserRequest: {
-            type: 'string',
-            description: 'Exact user request or faithful short summary authorizing a setting mutation or slash command invocation.',
-          },
-        },
+        properties: AGENT_HARNESS_PARAMETER_PROPERTIES,
         required: ['mode'],
         additionalProperties: false,
       },
@@ -656,6 +525,9 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             cliCommands: totalHarnessCliCommands(),
             blockedCliCommandTokens: blockedHarnessCliCommandTokens(),
             panels: totalHarnessPanels(deps.commandContext),
+            uiSurfaces: totalHarnessUiSurfaces(),
+            shortcuts: totalHarnessShortcuts(deps.commandContext),
+            keybindings: totalHarnessKeybindings(deps.commandContext),
             commands: deps.commandRegistry.list().length,
             settings: deps.commandContext.platform.configManager.getSchema().length,
             workspaceCategories: AGENT_WORKSPACE_CATEGORIES.length,
@@ -664,6 +536,8 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             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.',
               slashCommands: 'Use mode:"commands" and mode:"command" to inspect; use mode:"run_command" with confirm:true plus explicitUserRequest to execute.',
               workspace: 'Use mode:"workspace_actions" to list and mode:"workspace_action" for editor schemas; set includeParameters:true on workspace_actions to inline editor schemas.',
               settings: 'Use mode:"settings", mode:"get_setting", mode:"set_setting", and mode:"reset_setting".',
@@ -705,6 +579,35 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           if (confirmationError) return error(confirmationError);
           return output(openHarnessPanel(deps.commandContext, args));
         }
+        if (args.mode === 'ui_surfaces') {
+          const surfaces = listHarnessUiSurfaces(deps.commandContext, args);
+          return output({ surfaces, returned: surfaces.length, total: totalHarnessUiSurfaces() });
+        }
+        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>'}.`);
+        }
+        if (args.mode === 'open_ui_surface') {
+          const confirmationError = requireConfirmedAction(args, 'UI surface routing');
+          if (confirmationError) return error(confirmationError);
+          return output(openHarnessUiSurface(deps.commandContext, args));
+        }
+        if (args.mode === 'shortcuts') return output(listHarnessShortcuts(deps.commandContext, args));
+        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>'}.`);
+        }
+        if (args.mode === 'set_keybinding') {
+          const confirmationError = requireConfirmedAction(args, 'Keybinding mutation');
+          if (confirmationError) return error(confirmationError);
+          return output(setHarnessKeybinding(deps.commandContext, args));
+        }
+        if (args.mode === 'reset_keybinding') {
+          const confirmationError = requireConfirmedAction(args, 'Keybinding reset');
+          if (confirmationError) return error(confirmationError);
+          return output(resetHarnessKeybinding(deps.commandContext, args));
+        }
         if (args.mode === 'commands') {
           const commands = listCommands(deps.commandRegistry, args);
           return output({ commands, returned: commands.length, total: deps.commandRegistry.list().length });

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

@@ -0,0 +1,343 @@
+import type { CommandContext } from '../input/command-registry.ts';
+
+type UiSurfaceKind = 'overlay' | 'modal' | 'workspace' | 'picker';
+
+export interface AgentHarnessUiSurfaceArgs {
+  readonly query?: unknown;
+  readonly surfaceId?: unknown;
+  readonly categoryId?: unknown;
+  readonly category?: unknown;
+  readonly target?: unknown;
+  readonly key?: unknown;
+  readonly prefix?: unknown;
+  readonly limit?: unknown;
+}
+
+interface UiSurfaceDefinition {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: UiSurfaceKind;
+  readonly summary: string;
+  readonly command: string;
+  readonly preferredModelRoute: string;
+  readonly parameters?: readonly string[];
+  readonly available: (context: CommandContext) => boolean;
+  readonly open: (context: CommandContext, args: AgentHarnessUiSurfaceArgs) => Record<string, unknown>;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function routeUnavailable(surface: UiSurfaceDefinition): Record<string, unknown> {
+  return {
+    status: 'route_unavailable',
+    surface: surface.id,
+    note: 'The current runtime did not provide the shell opener for this UI surface.',
+  };
+}
+
+function opened(surface: UiSurfaceDefinition, extra: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    status: 'opened',
+    surface: surface.id,
+    kind: surface.kind,
+    ...extra,
+    note: 'UI routing was handed to the current Agent shell bridge.',
+  };
+}
+
+function optionalModelTarget(args: AgentHarnessUiSurfaceArgs): 'main' | 'helper' | 'tool' | 'tts' | undefined {
+  const target = readString(args.target);
+  return target === 'main' || target === 'helper' || target === 'tool' || target === 'tts' ? target : undefined;
+}
+
+function optionalOnboardingMode(args: AgentHarnessUiSurfaceArgs): 'new' | 'edit' | 'reopen' | undefined {
+  const target = readString(args.target);
+  return target === 'new' || target === 'edit' || target === 'reopen' ? target : undefined;
+}
+
+function workspaceCategory(args: AgentHarnessUiSurfaceArgs): string | undefined {
+  return readString(args.categoryId || args.category || args.target) || undefined;
+}
+
+function settingsTarget(args: AgentHarnessUiSurfaceArgs): string | undefined {
+  return readString(args.target || args.key || args.prefix) || undefined;
+}
+
+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.',
+    command: '/agent',
+    preferredModelRoute: 'Use workspace_actions/workspace_action/run_workspace_action for model operation; use open_ui_surface only to visibly navigate.',
+    parameters: ['categoryId'],
+    available: (context) => typeof context.openAgentWorkspace === 'function',
+    open: (context, args) => {
+      const surface = findSurfaceById('agent-workspace')!;
+      if (!context.openAgentWorkspace) return routeUnavailable(surface);
+      const categoryId = workspaceCategory(args);
+      context.openAgentWorkspace(categoryId);
+      return opened(surface, { categoryId: categoryId ?? 'default' });
+    },
+  },
+  {
+    id: 'settings',
+    label: 'Settings',
+    kind: 'modal',
+    summary: 'Fullscreen settings workspace for Agent-owned configuration, subscriptions, secrets, MCP, tools, and surface settings.',
+    command: '/settings',
+    preferredModelRoute: 'Use settings/get_setting/set_setting/reset_setting for model operation; use open_ui_surface only to visibly navigate.',
+    parameters: ['target', 'key', 'prefix'],
+    available: (context) => typeof context.openSettingsModal === 'function',
+    open: (context, args) => {
+      const surface = findSurfaceById('settings')!;
+      if (!context.openSettingsModal) return routeUnavailable(surface);
+      const target = settingsTarget(args);
+      context.openSettingsModal(target);
+      return opened(surface, { target: target ?? 'default' });
+    },
+  },
+  {
+    id: 'mcp-workspace',
+    label: 'MCP Workspace',
+    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.',
+    available: (context) => typeof context.openMcpWorkspace === 'function',
+    open: (context) => {
+      const surface = findSurfaceById('mcp-workspace')!;
+      if (!context.openMcpWorkspace) return routeUnavailable(surface);
+      context.openMcpWorkspace();
+      return opened(surface);
+    },
+  },
+  {
+    id: 'model-picker',
+    label: 'Model Picker',
+    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.',
+    parameters: ['target'],
+    available: (context) => typeof context.openModelPicker === 'function' || typeof context.openModelPickerWithTarget === 'function',
+    open: (context, args) => {
+      const surface = findSurfaceById('model-picker')!;
+      const target = optionalModelTarget(args);
+      if (target && context.openModelPickerWithTarget) {
+        const openedForTarget = context.openModelPickerWithTarget(target);
+        return opened(surface, { target, openedForTarget });
+      }
+      if (!context.openModelPicker) return routeUnavailable(surface);
+      context.openModelPicker();
+      return opened(surface, { target: 'main' });
+    },
+  },
+  {
+    id: 'provider-picker',
+    label: 'Provider Picker',
+    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.',
+    parameters: ['target'],
+    available: (context) => typeof context.openProviderPicker === 'function' || typeof context.openProviderModelPickerWithTarget === 'function',
+    open: (context, args) => {
+      const surface = findSurfaceById('provider-picker')!;
+      const target = optionalModelTarget(args);
+      if (target && context.openProviderModelPickerWithTarget) {
+        context.openProviderModelPickerWithTarget(target);
+        return opened(surface, { target });
+      }
+      if (!context.openProviderPicker) return routeUnavailable(surface);
+      context.openProviderPicker();
+      return opened(surface, { target: 'main' });
+    },
+  },
+  {
+    id: 'session-picker',
+    label: 'Session Picker',
+    kind: 'picker',
+    summary: 'Saved session browser and loader.',
+    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);
+    },
+  },
+  {
+    id: 'profile-picker',
+    label: 'Profile Picker',
+    kind: 'picker',
+    summary: 'Agent profile picker for local isolated profile selection.',
+    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);
+    },
+  },
+  {
+    id: 'bookmark-modal',
+    label: 'Bookmarks',
+    kind: 'modal',
+    summary: 'Transcript bookmark browser.',
+    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);
+    },
+  },
+  {
+    id: 'context-inspector',
+    label: 'Context Inspector',
+    kind: 'modal',
+    summary: 'Context-window usage and token breakdown inspector.',
+    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);
+    },
+  },
+  {
+    id: 'help-overlay',
+    label: 'Help Overlay',
+    kind: 'overlay',
+    summary: 'Registry-driven command and shortcut help overlay.',
+    command: '/help',
+    preferredModelRoute: 'Use commands/command and shortcuts modes 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);
+    },
+  },
+  {
+    id: 'shortcuts-overlay',
+    label: 'Shortcuts Overlay',
+    kind: 'overlay',
+    summary: 'Keyboard shortcut reference overlay.',
+    command: '/shortcuts',
+    preferredModelRoute: 'Use shortcuts/keybindings modes for model-readable discovery and confirmed keybinding edits.',
+    available: (context) => typeof context.openShortcutsOverlay === 'function',
+    open: (context) => {
+      const surface = findSurfaceById('shortcuts-overlay')!;
+      if (!context.openShortcutsOverlay) return routeUnavailable(surface);
+      context.openShortcutsOverlay();
+      return opened(surface);
+    },
+  },
+  {
+    id: 'onboarding',
+    label: 'Onboarding Wizard',
+    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.',
+    parameters: ['target=new|edit|reopen'],
+    available: (context) => typeof context.openOnboardingWizard === 'function',
+    open: (context, args) => {
+      const surface = findSurfaceById('onboarding')!;
+      if (!context.openOnboardingWizard) return routeUnavailable(surface);
+      const mode = optionalOnboardingMode(args);
+      context.openOnboardingWizard(mode);
+      return opened(surface, { mode: mode ?? 'default' });
+    },
+  },
+];
+
+function findSurfaceById(surfaceId: string): UiSurfaceDefinition | undefined {
+  return UI_SURFACES.find((surface) => surface.id === surfaceId);
+}
+
+function surfaceMatches(surface: Record<string, unknown>, query: string): boolean {
+  if (!query) return true;
+  return [
+    surface.id,
+    surface.label,
+    surface.kind,
+    surface.summary,
+    surface.command,
+    surface.preferredModelRoute,
+  ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
+}
+
+function describeSurface(context: CommandContext, surface: UiSurfaceDefinition): Record<string, unknown> {
+  return {
+    id: surface.id,
+    label: surface.label,
+    kind: surface.kind,
+    summary: surface.summary,
+    command: surface.command,
+    preferredModelRoute: surface.preferredModelRoute,
+    parameters: surface.parameters ?? [],
+    available: surface.available(context),
+    policy: {
+      effect: 'visible-ui-navigation',
+      confirmation: 'agent_harness mode:"open_ui_surface" requires confirm:true and explicitUserRequest.',
+      boundary: 'UI surface routing opens the same visible Agent shell surface the user can open. Use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual operations.',
+    },
+  };
+}
+
+export function totalHarnessUiSurfaces(): number {
+  return UI_SURFACES.length;
+}
+
+export function listHarnessUiSurfaces(context: CommandContext, args: AgentHarnessUiSurfaceArgs): readonly Record<string, unknown>[] {
+  const query = readString(args.query);
+  const limit = readLimit(args.limit, 200);
+  return UI_SURFACES
+    .map((surface) => describeSurface(context, surface))
+    .filter((surface) => surfaceMatches(surface, query))
+    .slice(0, limit);
+}
+
+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;
+}
+
+export function openHarnessUiSurface(context: CommandContext, args: AgentHarnessUiSurfaceArgs): 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) {
+    return {
+      status: 'unknown_ui_surface',
+      surfaceId: surfaceId || '<missing>',
+      availableSurfaces: UI_SURFACES.map((entry) => entry.id),
+    };
+  }
+  return {
+    ...surface.open(context, args),
+    descriptor: describeSurface(context, surface),
+  };
+}

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '1.0.3';
+let _version = '1.0.5';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {