@pellux/goodvibes-agent 1.0.2 → 1.0.3

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, slash commands, command policy metadata, model tools, settings, local registries, and connected-host capability boundaries are model-visible through Agent-owned tools. Mutations remain explicit and confirmation-gated.
+- User-facing Agent workspace actions, built-in panels, top-level CLI mirrors, slash commands, command policy metadata, model tools, settings, local registries, and connected-host capability boundaries are model-visible through Agent-owned tools. Mutations remain explicit and confirmation-gated.
 - 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, slash-command discovery, command policy metadata, command execution with confirmation, model tool discovery, settings inspection/mutation, and connected-host posture. 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. 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. 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, built-in panel discovery/routing, top-level CLI mirror discovery, slash-command discovery, command policy metadata, command execution with confirmation, model tool discovery, settings inspection/mutation, and connected-host 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. 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. 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. 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.
 

package/docs/tools-and-commands.md

@@ -43,14 +43,18 @@ 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, inspect slash commands and command policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools, inspect or change Agent settings, and inspect connected-host posture.
+- `agent_harness`: inspect workspace categories/actions, inspect built-in panels, inspect top-level CLI mirrors, inspect slash commands and command policy metadata, run concrete workspace or slash-command mirrors with confirmation, inspect model tools, inspect or change Agent settings, and inspect connected-host posture.
 - `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; `commands` and `command` return command descriptions 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 with its editor schema; `tools` can inline model tool JSON schemas with `includeParameters:true`; `settings` returns setting descriptors plus setting policy; and `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability.
+`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; `cli_commands` and `cli_command` return top-level package CLI mirror metadata, parser output, blocked command tokens, and preferred in-process model routes; `commands` and `command` return slash-command descriptions 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 with its editor schema; `tools` can inline model tool JSON schemas with `includeParameters:true`; `settings` returns setting descriptors plus setting policy; and `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability.
+
+`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.
+
+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.
 
 Setting writes, setting resets, slash-command invocation, workspace-action invocation, local record deletion, channel sends, notifications, reminders, media generation, and connected-host operator mutations require explicit user request and confirmation. Secret-backed settings are stored through the secret manager, and connected-host lifecycle/listener settings remain read-only in Agent.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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/cli/help.ts

@@ -131,6 +131,15 @@ type CommandHelp = {
   readonly examples?: readonly string[];
 };
 
+export interface GoodVibesCommandHelpDescriptor {
+  readonly command: string;
+  readonly aliases: readonly string[];
+  readonly summary: string;
+  readonly usage: readonly string[];
+  readonly subcommands: readonly string[];
+  readonly examples: readonly string[];
+}
+
 const COMMAND_HELP: Record<string, CommandHelp> = {
   run: {
     usage: ['run [prompt] [--output text|json|stream-json]', 'exec [prompt]'],
@@ -416,6 +425,23 @@ export function hasGoodVibesCommandHelp(topic: string): boolean {
   return COMMAND_HELP[normalizeHelpTopic(topic)] !== undefined;
 }
 
+export function describeGoodVibesCommandHelp(topic: string): GoodVibesCommandHelpDescriptor | null {
+  const normalized = normalizeHelpTopic(topic);
+  const help = COMMAND_HELP[normalized];
+  if (!help) return null;
+  return {
+    command: normalized,
+    aliases: Object.entries(HELP_ALIASES)
+      .filter(([, target]) => target === normalized)
+      .map(([alias]) => alias)
+      .sort(),
+    summary: help.summary,
+    usage: help.usage,
+    subcommands: help.subcommands ?? [],
+    examples: help.examples ?? [],
+  };
+}
+
 export function renderGoodVibesCommandHelp(topic: string, binary = 'goodvibes-agent'): string {
   const normalized = normalizeHelpTopic(topic);
   const help = COMMAND_HELP[normalized];

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

@@ -0,0 +1,152 @@
+import type { GoodVibesCliCommand } from '../cli/types.ts';
+import { describeGoodVibesCommandHelp } from '../cli/help.ts';
+import {
+  listBlockedGoodVibesCliCommandTokens,
+  listGoodVibesCliCommandTokens,
+  listGoodVibesCliCommands,
+  parseGoodVibesCli,
+} from '../cli/parser.ts';
+import { describeCliCommandPolicy } from './agent-harness-metadata.ts';
+
+export interface AgentHarnessCliArgs {
+  readonly query?: unknown;
+  readonly command?: unknown;
+  readonly cliCommand?: unknown;
+  readonly commandName?: unknown;
+  readonly limit?: 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 cliCommandTokens(command: GoodVibesCliCommand): readonly string[] {
+  if (command === 'unknown') return [];
+  if (command === 'tui') return ['(no command)'];
+  return listGoodVibesCliCommandTokens()
+    .filter((token) => parseGoodVibesCli([token]).command === command)
+    .sort();
+}
+
+function fallbackCliSummary(command: GoodVibesCliCommand): string {
+  if (command === 'tui') return 'Launch the interactive Agent TUI.';
+  if (command === 'help') return 'Print top-level or command-specific help.';
+  if (command === 'version') return 'Print the installed Agent package version.';
+  return 'Inspect the CLI help for this Agent package command.';
+}
+
+function describeCliCommand(command: GoodVibesCliCommand): Record<string, unknown> {
+  const help = describeGoodVibesCommandHelp(command);
+  const tokens = cliCommandTokens(command);
+  return {
+    name: command,
+    tokens,
+    invocation: command === 'tui' ? 'goodvibes-agent' : `goodvibes-agent ${tokens[0] ?? command}`,
+    helpTopic: help?.command ?? command,
+    summary: help?.summary ?? fallbackCliSummary(command),
+    usage: help?.usage ?? (command === 'tui' ? ['goodvibes-agent [OPTIONS]'] : [`goodvibes-agent ${command} [ARGS]`]),
+    aliases: help?.aliases ?? tokens.filter((token) => token !== command),
+    subcommands: help?.subcommands ?? [],
+    examples: help?.examples ?? [],
+    policy: describeCliCommandPolicy(command),
+  };
+}
+
+function cliCommandMatches(command: Record<string, unknown>, query: string): boolean {
+  if (!query) return true;
+  return [
+    command.name,
+    command.tokens,
+    command.summary,
+    command.usage,
+    command.aliases,
+    command.subcommands,
+    command.examples,
+    command.policy,
+  ].map((value) => JSON.stringify(value)).join('\n').toLowerCase().includes(query.toLowerCase());
+}
+
+export function totalHarnessCliCommands(): number {
+  return listGoodVibesCliCommands().filter((command) => command !== 'unknown').length;
+}
+
+export function blockedHarnessCliCommandTokens(): readonly string[] {
+  return listBlockedGoodVibesCliCommandTokens();
+}
+
+export function listHarnessCliCommands(args: AgentHarnessCliArgs): readonly Record<string, unknown>[] {
+  const query = readString(args.query);
+  const limit = readLimit(args.limit, 200);
+  return listGoodVibesCliCommands()
+    .filter((command) => command !== 'unknown')
+    .map(describeCliCommand)
+    .filter((command) => cliCommandMatches(command, query))
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)))
+    .slice(0, limit);
+}
+
+function cliTokensFromArgs(args: AgentHarnessCliArgs): readonly string[] {
+  const raw = readString(args.cliCommand) || readString(args.command) || readString(args.commandName) || readString(args.query);
+  if (!raw) return [];
+  const tokens = raw.split(/\s+/).filter((token) => token.length > 0);
+  if (tokens[0] === 'goodvibes-agent' || tokens[0]?.endsWith('/goodvibes-agent')) return tokens.slice(1);
+  return tokens;
+}
+
+export function describeHarnessCliCommand(args: AgentHarnessCliArgs): Record<string, unknown> {
+  const tokens = cliTokensFromArgs(args);
+  if (tokens.length === 0) return describeCliCommand('tui');
+  const parsed = parseGoodVibesCli(tokens);
+  if (parsed.command === 'unknown') {
+    return {
+      supported: false,
+      token: parsed.rawCommand ?? tokens[0],
+      errors: parsed.errors,
+      blockedTokens: blockedHarnessCliCommandTokens(),
+      policy: describeCliCommandPolicy(parsed.rawCommand ?? tokens[0] ?? 'unknown'),
+    };
+  }
+  return {
+    ...describeCliCommand(parsed.command),
+    parsed: {
+      command: parsed.command,
+      rawCommand: parsed.rawCommand,
+      commandArgs: parsed.commandArgs,
+      positionals: parsed.positionals,
+      flags: {
+        provider: parsed.flags.provider,
+        model: parsed.flags.model,
+        agentProfile: parsed.flags.agentProfile,
+        runtimeUrl: parsed.flags.runtimeUrl,
+        workingDir: parsed.flags.workingDir,
+        help: parsed.flags.help,
+        version: parsed.flags.version,
+        print: parsed.flags.print,
+        outputFormat: parsed.flags.outputFormat,
+        configOverrides: parsed.flags.configOverrides.map((override) => {
+          const index = override.indexOf('=');
+          return index < 0 ? override : `${override.slice(0, index)}=<redacted>`;
+        }),
+        enableFeatures: parsed.flags.enableFeatures,
+        disableFeatures: parsed.flags.disableFeatures,
+        noAltScreen: parsed.flags.noAltScreen,
+        port: parsed.flags.port,
+        hostname: parsed.flags.hostname,
+        open: parsed.flags.open,
+        continueLast: parsed.flags.continueLast,
+        resume: parsed.flags.resume,
+        session: parsed.flags.session,
+        fork: parsed.flags.fork,
+        rawOutput: parsed.flags.rawOutput,
+        acceptRawOutputRisk: parsed.flags.acceptRawOutputRisk,
+      },
+      errors: parsed.errors,
+    },
+  };
+}

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

@@ -1,4 +1,6 @@
 import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext } from '../input/command-registry.ts';
+import { resolveAgentConnectedHostConnection } from '../agent/routine-schedule-promotion.ts';
 
 export interface CommandExecutionPolicy {
   readonly effect: 'read-only' | 'local-state' | 'connected-host-state' | 'external-network' | 'ui-navigation' | 'session-lifecycle' | 'delegated-work' | 'mixed' | 'unknown';
@@ -132,6 +134,96 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
   };
 }
 
+export function describeCliCommandPolicy(commandName: string): CommandExecutionPolicy {
+  const root = commandName.trim().toLowerCase();
+  const confirmation = 'agent_harness CLI command modes are discovery-only. Use first-class model tools, workspace actions, slash-command mirrors, or an explicit external shell request to execute equivalent CLI workflows.';
+  if ([
+    'app',
+    'bridge',
+    'control-plane',
+    'controlplane',
+    'cp',
+    'daemon',
+    'http-listener',
+    'launch',
+    'listener',
+    'remote',
+    'serve',
+    'server',
+    'service',
+    'services',
+    'start',
+    'surface',
+    'surfaces',
+    'web',
+    'webhook',
+  ].includes(root)) {
+    return {
+      effect: 'unknown',
+      confirmation,
+      boundary: 'Blocked package CLI token. Agent can launch its own TUI and use public connected-host routes, but it does not manage connected-host lifecycle, listeners, servers, bridges, remotes, web surfaces, or webhook listeners.',
+    };
+  }
+  if (root === 'tui' || root === 'onboarding' || root === 'help' || root === 'version' || root === 'completion') {
+    return {
+      effect: root === 'tui' || root === 'onboarding' ? 'ui-navigation' : 'read-only',
+      confirmation,
+      preferredModelTool: root === 'onboarding' || root === 'tui' ? 'agent_harness workspace/workspace_actions' : 'agent_harness cli_commands/cli_command',
+      boundary: 'Top-level CLI launch, setup, help, version, and completion commands are package entrypoint surfaces; use in-process workspace and slash-command bridges from the model when operating inside the TUI.',
+    };
+  }
+  if (root === 'run') {
+    return {
+      effect: 'mixed',
+      confirmation,
+      boundary: 'The CLI run command starts a non-interactive Agent turn from a process entrypoint. Do not create hidden nested turns from agent_harness; answer the user directly in the current conversation.',
+    };
+  }
+  if (root === 'status' || root === 'doctor' || root === 'auth' || root === 'compat' || root === 'models' || root === 'providers' || root === 'tasks') {
+    return {
+      effect: 'read-only',
+      confirmation,
+      preferredModelTool: root === 'tasks' ? 'agent_operator_briefing' : 'agent_harness connected_host/settings/tools',
+      boundary: 'Diagnostics and posture commands are readable from Agent-owned settings, provider, model, and connected-host capability surfaces without taking connected-host lifecycle ownership.',
+    };
+  }
+  if (root === 'profiles' || root === 'personas' || root === 'skills' || root === 'memory' || root === 'routines' || root === 'sessions' || root === 'bundle') {
+    return {
+      effect: 'local-state',
+      confirmation,
+      preferredModelTool: root === 'profiles' ? 'agent_harness workspace_actions/run_workspace_action' : 'agent_local_registry',
+      boundary: 'Local library/profile/session/bundle CLI commands operate on Agent-local data. Mutations require explicit user intent and should use first-class Agent-local tools where available.',
+    };
+  }
+  if (root === 'knowledge' || root === 'ask' || root === 'search') {
+    return {
+      effect: 'mixed',
+      confirmation,
+      preferredModelTool: root === 'knowledge' ? 'agent_knowledge or agent_knowledge_ingest' : 'agent_knowledge',
+      boundary: 'Agent Knowledge CLI commands must stay on isolated Agent Knowledge routes and never fall back to default or non-Agent knowledge spaces.',
+    };
+  }
+  if (root === 'delegate') {
+    return {
+      effect: 'delegated-work',
+      confirmation,
+      boundary: 'Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly.',
+    };
+  }
+  if (root === 'subscription' || root === 'secrets' || root === 'pair') {
+    return {
+      effect: root === 'pair' ? 'external-network' : 'mixed',
+      confirmation,
+      boundary: 'Provider subscription, secret, and pairing flows can expose credentials or external account state. Use only explicit user-directed flows and prefer secret refs over raw values.',
+    };
+  }
+  return {
+    effect: 'unknown',
+    confirmation,
+    boundary: 'Inspect the CLI help, parser result, and preferred model routes before using an equivalent command path.',
+  };
+}
+
 function toolIsAvailable(toolRegistry: ToolRegistry, toolName: string): boolean {
   return toolRegistry.getToolDefinitions().some((tool) => tool.name === toolName);
 }
@@ -264,6 +356,22 @@ export function connectedHostRouteFamilies(): readonly Record<string, unknown>[]
   ];
 }
 
+export function connectedHostSummary(context: CommandContext, toolRegistry: ToolRegistry): Record<string, unknown> {
+  const shellPaths = context.workspace.shellPaths;
+  const homeDirectory = shellPaths?.homeDirectory ?? context.platform.configManager.getHomeDirectory() ?? '';
+  const connection = resolveAgentConnectedHostConnection(context.platform.configManager, homeDirectory);
+  return {
+    baseUrl: connection.baseUrl,
+    operatorToken: connection.token ? 'configured' : 'missing',
+    tokenPath: connection.tokenPath,
+    ownership: 'external-connected-host',
+    lifecycle: 'GoodVibes Agent can use public connected-host operator routes, but does not start, stop, restart, install, expose, or mutate the host listener.',
+    routeFamilies: connectedHostRouteFamilies(),
+    capabilities: connectedHostCapabilityMap(toolRegistry),
+    blockedCapabilities: blockedConnectedHostCapabilities(),
+  };
+}
+
 export function blockedConnectedHostCapabilities(): readonly Record<string, unknown>[] {
   return [
     {

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

@@ -0,0 +1,36 @@
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+
+export interface AgentHarnessModelToolCatalogArgs {
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: 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)));
+}
+
+export function listHarnessModelTools(toolRegistry: ToolRegistry, args: AgentHarnessModelToolCatalogArgs): readonly Record<string, unknown>[] {
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const limit = readLimit(args.limit, 200);
+  return toolRegistry.getToolDefinitions()
+    .filter((tool) => !query || [tool.name, tool.description, ...(tool.sideEffects ?? [])].join('\n').toLowerCase().includes(query))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .slice(0, limit)
+    .map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      sideEffects: tool.sideEffects ?? [],
+      concurrency: tool.concurrency ?? 'parallel',
+      supportsProgress: tool.supportsProgress ?? false,
+      supportsStreamingOutput: tool.supportsStreamingOutput ?? false,
+      ...(includeParameters ? { parameters: tool.parameters } : {}),
+    }));
+}

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

@@ -0,0 +1,121 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import { agentWorkspaceCategoryForPanel, agentWorkspaceCommandForPanel } from '../input/agent-workspace-panel-route.ts';
+import type { PanelRegistration } from '../panels/types.ts';
+
+export interface AgentHarnessPanelArgs {
+  readonly query?: unknown;
+  readonly panelId?: unknown;
+  readonly category?: unknown;
+  readonly limit?: unknown;
+  readonly pane?: 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 panelManager(context: CommandContext) {
+  return context.workspace.panelManager ?? null;
+}
+
+function panelMatches(panel: Record<string, unknown>, query: string): boolean {
+  if (!query) return true;
+  return [
+    panel.id,
+    panel.name,
+    panel.category,
+    panel.description,
+    panel.workspaceRoute,
+  ].map((value) => String(value ?? '')).join('\n').toLowerCase().includes(query.toLowerCase());
+}
+
+function describePanelRegistration(context: CommandContext, registration: PanelRegistration): Record<string, unknown> {
+  const manager = panelManager(context);
+  const openPanel = manager?.getPanel(registration.id) ?? null;
+  const pane = manager?.getPaneOf(registration.id) ?? null;
+  const activePanel = manager?.getActivePanel() ?? null;
+  return {
+    id: registration.id,
+    name: registration.name,
+    icon: registration.icon,
+    category: registration.category,
+    description: registration.description,
+    preload: registration.preload === true,
+    open: openPanel !== null,
+    pane,
+    active: activePanel?.id === registration.id,
+    focused: activePanel?.id === registration.id,
+    workspaceRoute: {
+      categoryId: agentWorkspaceCategoryForPanel(registration.id),
+      command: agentWorkspaceCommandForPanel(registration.id),
+    },
+    policy: {
+      effect: 'ui-navigation',
+      confirmation: 'agent_harness mode:"open_panel" requires confirm:true and explicitUserRequest.',
+      boundary: 'Panels are Agent/TUI operator views. The model can inspect panel catalog/open state; panel routing uses the existing Agent workspace bridge and does not mutate connected-host lifecycle.',
+    },
+  };
+}
+
+export function totalHarnessPanels(context: CommandContext): number {
+  return panelManager(context)?.getRegisteredTypes().length ?? 0;
+}
+
+export function listHarnessPanels(context: CommandContext, args: AgentHarnessPanelArgs): readonly Record<string, unknown>[] {
+  const manager = panelManager(context);
+  if (!manager) return [];
+  const query = readString(args.query);
+  const category = readString(args.category);
+  const limit = readLimit(args.limit, 200);
+  return manager.getRegisteredTypes()
+    .map((registration) => describePanelRegistration(context, registration))
+    .filter((panel) => !category || panel.category === category)
+    .filter((panel) => panelMatches(panel, query))
+    .sort((a, b) => String(a.id).localeCompare(String(b.id)))
+    .slice(0, limit);
+}
+
+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;
+}
+
+export function openHarnessPanel(context: CommandContext, args: AgentHarnessPanelArgs): Record<string, unknown> {
+  const panel = describeHarnessPanel(context, args);
+  if (!panel) {
+    return {
+      status: 'unknown_panel',
+      panelId: readString(args.panelId || args.query) || '<missing>',
+      availablePanels: listHarnessPanels(context, { limit: 50 }).map((entry) => entry.id),
+    };
+  }
+  const requestedPane = readString(args.pane);
+  const pane = requestedPane === 'bottom' || requestedPane === 'top' ? requestedPane : undefined;
+  if (!context.showPanel) {
+    return {
+      status: 'route_unavailable',
+      panel,
+      note: 'The current runtime did not provide showPanel. Use the returned workspaceRoute from the TUI.',
+    };
+  }
+  context.showPanel(String(panel.id), pane);
+  return {
+    status: 'routed',
+    panel,
+    pane: pane ?? 'default',
+    note: 'Panel routing was handed to the current Agent shell bridge.',
+  };
+}