@pellux/goodvibes-agent 1.0.28 → 1.0.30

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Product-facing release notes for GoodVibes Agent.
 
+## 1.0.30 - 2026-06-04
+
+- Surface workspace and workspace_categories modes in the agent_harness summary and package docs so the model can discover the Agent workspace category catalog before action lookup.
+- Keep workspace action/editor execution guidance unchanged while documenting the category catalog/action-count route.
+- Add focused harness coverage for workspace category discovery and summary guidance.
+
+## 1.0.29 - 2026-06-03
+
+- Add preferred model-route metadata to every built-in slash command policy so command inspection always tells the model which Agent-owned route to use.
+- Add preferred route metadata to every supported top-level CLI mirror, including current-conversation handling for non-interactive run mirrors.
+- Refresh 1.0.x package docs and focused harness coverage for exhaustive command and CLI preferred-route metadata.
+
 ## 1.0.28 - 2026-06-03
 
 - Expose modelExecution metadata for every Agent workspace editor action, including local-registry, command-backed, direct local-create, profile, and prompt-returning editor flows.

package/README.md

@@ -7,7 +7,7 @@ GoodVibes Agent is the personal operator assistant TUI for GoodVibes. It is buil
 
 The Agent product connects to a GoodVibes host owned outside this package. It does not install, start, stop, restart, or own that host.
 
-Most work happens in the interactive TUI. The installed CLI exists to launch that TUI and provide scriptable mirrors for workflows that are already reachable from the workspace. The main Agent model can inspect the same harness surface through Agent-owned tools: workspace actions and single-action lookup, built-in panels and single-panel lookup, modal/overlay/picker UI surfaces and single-surface lookup, named operator surfaces, top-level CLI mirrors and single-mirror lookup, fixed shortcuts, configurable keybindings, single-keybinding lookup, shell-safe keybinding execution, slash commands, single-command lookup with policy metadata, settings and single-setting lookup, model tools and individual model tool schemas, local registries, connected-host capability boundaries, and live connected-host readiness are all discoverable from the conversation without exposing connected-host lifecycle control.
+Most work happens in the interactive TUI. The installed CLI exists to launch that TUI and provide scriptable mirrors for workflows that are already reachable from the workspace. The main Agent model can inspect the same harness surface through Agent-owned tools: workspace categories/actions and single-action lookup, built-in panels and single-panel lookup, modal/overlay/picker UI surfaces and single-surface lookup, named operator surfaces, top-level CLI mirrors and single-mirror lookup with preferred model routes, fixed shortcuts, configurable keybindings, single-keybinding lookup, shell-safe keybinding execution, slash commands, single-command lookup with effect, boundary, and preferred-route policy metadata, settings and single-setting lookup, model tools and individual model tool schemas, local registries, connected-host capability boundaries, and live connected-host readiness are all discoverable from the conversation without exposing connected-host lifecycle control.
 
 ## Install
 
@@ -66,7 +66,7 @@ Use the workspace as the primary product surface:
 
 Inside the Agent workspace, press `/` to search every workspace action by name, category, command, or detail. This is the primary discovery path for product actions; slash commands and CLI subcommands remain power-user/scriptable mirrors.
 
-The model has the same harness map through `agent_harness`: it can list Agent workspace actions, inspect or run one workspace action by `actionId`, `command`, `target`, or `query`, list built-in panels and inspect one panel by `panelId`, `target`, or `query`, inspect modal/overlay/picker UI surfaces by `surfaceId`, `target`, or `query`, list top-level CLI mirrors and inspect one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, inspect fixed shortcuts and configurable keybindings by `actionId`, `target`, `key`, or `query`, run shell-safe keybinding equivalents with confirmation, list slash commands, inspect or run one slash command by `command`, `commandName`, `target`, or `query` with parsed arguments and concrete built-in effect/boundary policy metadata, inspect model tool definitions or one model tool schema, inspect or change Agent settings by `key`, `target`, or `query` with confirmation, and report connected-host capability and live readiness posture. CLI mirror modes are read-only catalog and parser inspection; inside the main conversation, the model uses the returned preferred model tool, workspace action, setting mode, or confirmed slash-command mirror instead of launching hidden nested CLI processes. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose fixed runtime/editor controls plus the live resolved keybinding table; each keybinding descriptor reports its model operation route, `run_keybinding` executes only supported shell-safe equivalents with confirmation, and prompt-editor-only or terminal-selection shortcuts remain explicit direct user interaction. `set_keybinding` and `reset_keybinding` write the same `keybindings.json` file the user edits and require confirmation. Workspace action discovery can inline editor field schemas with `includeParameters:true`; every editor action descriptor reports `modelExecution` route metadata for local-registry, slash-command, direct local-create, prompt-returning, or first-class-tool execution; single-action lookup and execution use the same user-facing search fields, return or preserve lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates; CLI mirror, panel, UI surface, keybinding, slash-command, model tool, setting, and connected-host capability lookup use their catalog search fields and refuse ambiguous route, schema, capability, or mutation requests with candidates; confirmed slash-command execution uses the same slash-command lookup and refuses ambiguous requests before any handler runs; profile editors use the current starter-template inventory, and routine schedule editors can prefill a selected local routine from `recordId`. Selection-based local workspace actions accept a local `recordId` so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. Command-backed editor actions execute through the shared slash-command registry with confirmation, while web research/fetch editor actions return the main-conversation prompt for the model to use directly. The `connected_host` report includes route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and availability for the first-class Agent tools; `connected_host_capability` inspects one allowed or blocked capability by id, target, or query with its route families and boundary. The `connected_host_status` report performs a read-only live check of the connected-host status route and the isolated Agent Knowledge status route, reports SDK compatibility, token posture, endpoint bindings, route readiness, and actionable findings, and still refuses connected-host lifecycle control. The model uses those first-class tools for product workflows where they exist, such as Agent Knowledge, local memory/notes/personas/skills/routines, channel sends, notifications, reminders, media generation, work plans, and connected-host operator actions.
+The model has the same harness map through `agent_harness`: it can list Agent workspace categories, list Agent workspace actions, inspect or run one workspace action by `actionId`, `command`, `target`, or `query`, list built-in panels and inspect one panel by `panelId`, `target`, or `query`, inspect modal/overlay/picker UI surfaces by `surfaceId`, `target`, or `query`, list top-level CLI mirrors and inspect one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, inspect fixed shortcuts and configurable keybindings by `actionId`, `target`, `key`, or `query`, run shell-safe keybinding equivalents with confirmation, list slash commands, inspect or run one slash command by `command`, `commandName`, `target`, or `query` with parsed arguments and concrete built-in effect, boundary, and preferred-route policy metadata, inspect model tool definitions or one model tool schema, inspect or change Agent settings by `key`, `target`, or `query` with confirmation, and report connected-host capability and live readiness posture. CLI mirror modes are read-only catalog and parser inspection, and every supported top-level mirror reports the preferred in-process model route or current-conversation route; inside the main conversation, the model uses that returned route instead of launching hidden nested CLI processes. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose fixed runtime/editor controls plus the live resolved keybinding table; each keybinding descriptor reports its model operation route, `run_keybinding` executes only supported shell-safe equivalents with confirmation, and prompt-editor-only or terminal-selection shortcuts remain explicit direct user interaction. `set_keybinding` and `reset_keybinding` write the same `keybindings.json` file the user edits and require confirmation. Workspace action discovery can inline editor field schemas with `includeParameters:true`; every editor action descriptor reports `modelExecution` route metadata for local-registry, slash-command, direct local-create, prompt-returning, or first-class-tool execution; single-action lookup and execution use the same user-facing search fields, return or preserve lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates; CLI mirror, panel, UI surface, keybinding, slash-command, model tool, setting, and connected-host capability lookup use their catalog search fields and refuse ambiguous route, schema, capability, or mutation requests with candidates; confirmed slash-command execution uses the same slash-command lookup and refuses ambiguous requests before any handler runs; profile editors use the current starter-template inventory, and routine schedule editors can prefill a selected local routine from `recordId`. Selection-based local workspace actions accept a local `recordId` so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. Command-backed editor actions execute through the shared slash-command registry with confirmation, while web research/fetch editor actions return the main-conversation prompt for the model to use directly. The `connected_host` report includes route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and availability for the first-class Agent tools; `connected_host_capability` inspects one allowed or blocked capability by id, target, or query with its route families and boundary. The `connected_host_status` report performs a read-only live check of the connected-host status route and the isolated Agent Knowledge status route, reports SDK compatibility, token posture, endpoint bindings, route readiness, and actionable findings, and still refuses connected-host lifecycle control. The model uses those first-class tools for product workflows where they exist, such as Agent Knowledge, local memory/notes/personas/skills/routines, channel sends, notifications, reminders, media generation, work plans, and connected-host operator actions.
 
 The setup workspace surfaces discovered Agent-local persona, skill, and routine markdown files so day-one setup can import useful behavior instead of starting from blank records. It can also create one initial scratchpad note, local persona, skill, and routine directly during first-run setup; those records stay in Agent-local registries and never write to default knowledge or non-Agent segments.
 

package/dist/package/main.js

@@ -816508,7 +816508,7 @@ var createStyledCell = (char, overrides = {}) => ({
 // src/version.ts
 import { readFileSync } from "fs";
 import { join } from "path";
-var _version = "1.0.28";
+var _version = "1.0.30";
 var _sdkVersion = "0.33.35";
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf-8"));
@@ -847717,13 +847717,13 @@ init_state3();
 
 // src/input/commands/recall-shared.ts
 var VALID_CLASSES = ["decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership"];
-var VALID_SCOPES = ["session", "project", "team"];
+var VALID_SCOPES2 = ["session", "project", "team"];
 var VALID_REVIEW_STATES = ["fresh", "reviewed", "stale", "contradicted"];
 function isValidClass(s4) {
   return VALID_CLASSES.includes(s4);
 }
 function isValidScope(s4) {
-  return VALID_SCOPES.includes(s4);
+  return VALID_SCOPES2.includes(s4);
 }
 function isValidReviewState(s4) {
   return VALID_REVIEW_STATES.includes(s4);
@@ -847766,7 +847766,7 @@ function handleRecallSearch(args2, context) {
     if (isValidScope(scope))
       filter.scope = scope;
     else {
-      context.print(`[memory] Unknown scope "${scope}". Valid values ${VALID_SCOPES.join(", ")}.`);
+      context.print(`[memory] Unknown scope "${scope}". Valid values ${VALID_SCOPES2.join(", ")}.`);
       return;
     }
   }
@@ -847941,7 +847941,7 @@ function handleRecallList(args2, context) {
   if (scopeIdx !== -1 && args2[scopeIdx + 1]) {
     const scope = args2[scopeIdx + 1];
     if (!isValidScope(scope)) {
-      context.print(`[memory] Unknown scope "${scope}". Valid values ${VALID_SCOPES.join(", ")}.`);
+      context.print(`[memory] Unknown scope "${scope}". Valid values ${VALID_SCOPES2.join(", ")}.`);
       return;
     }
     filter.scope = scope;
@@ -847991,7 +847991,7 @@ async function handleRecallAdd(args2, context) {
   const tags = tagsRaw ? tagsRaw.split(",").map((token) => token.trim()).filter(Boolean) : [];
   const scope = scopeRaw && isValidScope(scopeRaw) ? scopeRaw : "project";
   if (scopeRaw && !isValidScope(scopeRaw)) {
-    context.print(`[memory] Invalid scope "${scopeRaw}". Valid values ${VALID_SCOPES.join(", ")}.`);
+    context.print(`[memory] Invalid scope "${scopeRaw}". Valid values ${VALID_SCOPES2.join(", ")}.`);
     return;
   }
   const provenance = [];
@@ -848125,7 +848125,7 @@ function handleRecallExport(args2, context) {
   if (scopeIdx !== -1 && commandArgs[scopeIdx + 1]) {
     const scope = commandArgs[scopeIdx + 1];
     if (!isValidScope(scope)) {
-      context.print(`[memory] Unknown scope "${scope}". Valid values ${VALID_SCOPES.join(", ")}.`);
+      context.print(`[memory] Unknown scope "${scope}". Valid values ${VALID_SCOPES2.join(", ")}.`);
       return;
     }
     filter.scope = scope;
@@ -848204,7 +848204,7 @@ function handleRecallHandoffExport(args2, context) {
   const scopeIdx = commandArgs.indexOf("--scope");
   const scopeRaw = scopeIdx !== -1 ? commandArgs[scopeIdx + 1] : "team";
   if (!scopeRaw || !isValidScope(scopeRaw)) {
-    context.print(`[memory] Unknown scope "${scopeRaw ?? ""}". Valid values ${VALID_SCOPES.join(", ")}.`);
+    context.print(`[memory] Unknown scope "${scopeRaw ?? ""}". Valid values ${VALID_SCOPES2.join(", ")}.`);
     return;
   }
   const bundle = memory.exportBundle({ scope: scopeRaw });
@@ -848320,7 +848320,7 @@ function handleRecallPromote(args2, context) {
   const id = parsed.rest[0];
   const scope = parsed.rest[1];
   if (!id || !scope || !isValidScope(scope)) {
-    context.print(`[memory] Usage: /memory promote <id> <${VALID_SCOPES.join("|")}> --yes`);
+    context.print(`[memory] Usage: /memory promote <id> <${VALID_SCOPES2.join("|")}> --yes`);
     return;
   }
   if (!parsed.yes) {
@@ -862253,7 +862253,7 @@ import { mkdirSync as mkdirSync64, readFileSync as readFileSync86, writeFileSync
 import { dirname as dirname63, resolve as resolve39 } from "path";
 init_state3();
 var VALID_CLASSES2 = ["decision", "constraint", "incident", "pattern", "fact", "risk", "runbook", "architecture", "ownership"];
-var VALID_SCOPES3 = ["session", "project", "team"];
+var VALID_SCOPES4 = ["session", "project", "team"];
 var VALID_REVIEW_STATES3 = ["fresh", "reviewed", "stale", "contradicted"];
 var VALID_PROVENANCE_KINDS = ["session", "turn", "task", "event", "file"];
 var VALUE_OPTIONS = new Set([
@@ -862353,7 +862353,7 @@ function isMemoryClass2(value) {
   return VALID_CLASSES2.includes(value);
 }
 function isMemoryScope2(value) {
-  return VALID_SCOPES3.includes(value);
+  return VALID_SCOPES4.includes(value);
 }
 function isReviewState(value) {
   return VALID_REVIEW_STATES3.includes(value);
@@ -862368,7 +862368,7 @@ function requireClass(value) {
 }
 function requireScope(value) {
   if (!value || !isMemoryScope2(value))
-    throw new Error(`Invalid memory scope "${value ?? ""}". Valid values ${VALID_SCOPES3.join(", ")}`);
+    throw new Error(`Invalid memory scope "${value ?? ""}". Valid values ${VALID_SCOPES4.join(", ")}`);
   return value;
 }
 function optionalScope(value) {
@@ -879518,6 +879518,7 @@ function describeCommandPolicy(commandName) {
     return {
       effect: "delegated-work",
       confirmation,
+      preferredModelTool: "agent_harness workspace_actions/workspace_action/run_workspace_action",
       boundary: "Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly."
     };
   }
@@ -879525,6 +879526,7 @@ function describeCommandPolicy(commandName) {
     return {
       effect: "session-lifecycle",
       confirmation,
+      preferredModelTool: "agent_harness commands/command/run_command",
       boundary: "Session and conversation commands operate on the visible harness session lifecycle."
     };
   }
@@ -879532,6 +879534,7 @@ function describeCommandPolicy(commandName) {
     return {
       effect: "local-state",
       confirmation,
+      preferredModelTool: "agent_harness workspace_actions/workspace_action/run_workspace_action or agent_harness run_command",
       boundary: "Conversation export writes a local workspace file and requires an explicit output intent."
     };
   }
@@ -879539,7 +879542,7 @@ function describeCommandPolicy(commandName) {
     return {
       effect: "ui-navigation",
       confirmation,
-      preferredModelTool: root === "bookmarks" ? "agent_harness open_ui_surface" : undefined,
+      preferredModelTool: root === "bookmarks" ? "agent_harness open_ui_surface" : "agent_harness run_command",
       boundary: "Conversation display navigation mutates only the visible transcript view or scroll position."
     };
   }
@@ -879615,6 +879618,7 @@ function describeCliCommandPolicy(commandName) {
     return {
       effect: "mixed",
       confirmation,
+      preferredModelTool: "current Agent conversation response; do not invoke hidden nested CLI run",
       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."
     };
   }
@@ -879646,6 +879650,7 @@ function describeCliCommandPolicy(commandName) {
     return {
       effect: "delegated-work",
       confirmation,
+      preferredModelTool: "agent_harness workspace_actions/workspace_action/run_workspace_action",
       boundary: "Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly."
     };
   }
@@ -879653,6 +879658,7 @@ function describeCliCommandPolicy(commandName) {
     return {
       effect: root === "pair" ? "external-network" : "mixed",
       confirmation,
+      preferredModelTool: root === "pair" ? "agent_harness workspace_actions/workspace_action/run_workspace_action" : "agent_harness settings/get_setting/set_setting/reset_setting or workspace_actions",
       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."
     };
   }
@@ -882986,7 +882992,7 @@ function createAgentHarnessTool(deps) {
       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, UI surfaces, keybindings, slash commands with policy metadata, model tools or one model tool schema, connected-host capabilities or one connected-host capability detail, and Agent settings, or to invoke a workspace action/command through the same in-process command registry the user uses in the TUI.",
+        "Use this tool to inspect Agent workspace categories/actions, built-in panels, top-level CLI mirrors, UI surfaces, keybindings, slash commands with policy metadata, model tools or one model tool schema, connected-host capabilities or one connected-host capability detail, 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, keybinding actions, 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(" "),
@@ -883023,7 +883029,7 @@ function createAgentHarnessTool(deps) {
               uiSurfaces: 'Use mode:"ui_surfaces" to list and mode:"ui_surface" with surfaceId, target, or query to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
               shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"keybinding" with actionId, target, key, or query; use mode:"run_keybinding" for confirmation-gated shell-safe shortcut equivalents; use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
               slashCommands: 'Use mode:"commands" to list slash commands and mode:"command" with command, commandName, target, or query to inspect one command; use mode:"run_command" with the same lookup fields plus confirm:true and explicitUserRequest to execute one uniquely resolved command.',
-              workspace: 'Use mode:"workspace_actions" to list, mode:"workspace_action" with actionId, command, target, or query for one action, editor schema, and modelExecution route metadata, and mode:"run_workspace_action" with the same lookup fields plus confirmation for executable actions; set includeParameters:true on workspace_actions to inline editor schemas.',
+              workspace: 'Use mode:"workspace" or mode:"workspace_categories" to list Agent workspace categories, mode:"workspace_actions" to list actions, mode:"workspace_action" with actionId, command, target, or query for one action, editor schema, and modelExecution route metadata, and mode:"run_workspace_action" with the same lookup fields plus confirmation for executable actions; set includeParameters:true on workspace_actions to inline editor schemas.',
               settings: 'Use mode:"settings" to list and mode:"get_setting" with key, target, or query for one setting. Use mode:"set_setting" or mode:"reset_setting" with key, target, or query plus confirm:true and explicitUserRequest.',
               tools: 'Use mode:"tools" to list first-class model tools, or mode:"tool" with toolName, target, or query to inspect one schema.',
               connectedHost: 'Use mode:"connected_host" for the connected-host capability map and blocked boundaries. Use mode:"connected_host_capability" with capabilityId, target, or query for one allowed or blocked capability.',

package/docs/README.md

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

package/docs/getting-started.md

@@ -44,7 +44,7 @@ After setup has been applied once, the TUI opens directly into the Agent operato
 
 Press `/` inside the Agent workspace to search every workspace action by name, category, command, or detail. Use that finder before reaching for shell commands; CLI subcommands are scriptable mirrors of these TUI workflows.
 
-The model can inspect and use the same harness surface through Agent-owned tools. `agent_harness` exposes workspace action discovery, single workspace-action inspection and execution by action id, command, or lookup text, built-in panel discovery/routing by panel id or lookup text, modal/overlay/picker UI surface discovery/routing by surface id or lookup text, top-level CLI mirror discovery and single-mirror lookup by command string, command token, or lookup text, fixed shortcut and configurable keybinding discovery, keybinding inspection/mutation by action id or lookup text, confirmation-gated shell-safe keybinding execution, slash-command discovery, single slash-command inspection by typed command or lookup text, concrete built-in command effect/boundary policy metadata, single slash-command execution by typed command or lookup text with confirmation, model tool discovery and single-tool schema inspection, settings inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness posture. CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, or slash-command mirror. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; keybinding descriptors include a model operation route, `run_keybinding` executes supported shell-safe equivalents only with confirmation, prompt-editor-only or terminal-selection shortcuts remain direct user interaction, and confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager. Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied; every editor descriptor reports `modelExecution` route metadata, and single-action lookup and execution use the same user-facing search fields, return lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates. Single-CLI-mirror, single-panel, single-surface, single-keybinding, single-slash-command, single-tool, single-setting, and single-connected-host-capability lookup use their catalog search fields, return lookup metadata where the result carries it, and refuse ambiguous route, schema, capability, or mutation requests with candidates; confirmed slash-command execution uses the same slash-command lookup and refuses ambiguous requests before any handler runs. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. Command-backed editor forms execute through the shared slash-command registry with confirmation, and web research/fetch forms return the main-conversation prompt for the model to use directly. 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 category discovery, workspace action discovery, single workspace-action inspection and execution by action id, command, or lookup text, built-in panel discovery/routing by panel id or lookup text, modal/overlay/picker UI surface discovery/routing by surface id or lookup text, top-level CLI mirror discovery and single-mirror lookup by command string, command token, or lookup text, fixed shortcut and configurable keybinding discovery, keybinding inspection/mutation by action id or lookup text, confirmation-gated shell-safe keybinding execution, slash-command discovery, single slash-command inspection by typed command or lookup text, concrete built-in command effect, boundary, and preferred-route policy metadata, single slash-command execution by typed command or lookup text with confirmation, model tool discovery and single-tool schema inspection, settings inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness posture. CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, slash-command mirror, or current-conversation response route. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; keybinding descriptors include a model operation route, `run_keybinding` executes supported shell-safe equivalents only with confirmation, prompt-editor-only or terminal-selection shortcuts remain direct user interaction, and confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager. Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied; every editor descriptor reports `modelExecution` route metadata, and single-action lookup and execution use the same user-facing search fields, return lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates. Single-CLI-mirror, single-panel, single-surface, single-keybinding, single-slash-command, single-tool, single-setting, and single-connected-host-capability lookup use their catalog search fields, return lookup metadata where the result carries it, and refuse ambiguous route, schema, capability, or mutation requests with candidates; confirmed slash-command execution uses the same slash-command lookup and refuses ambiguous requests before any handler runs. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. Command-backed editor forms execute through the shared slash-command registry with confirmation, and web research/fetch forms return the main-conversation prompt for the model to use directly. 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

@@ -50,11 +50,11 @@ The main Agent model has an Agent-owned harness bridge rather than generic SDK s
 - `agent_work_plan`: keep the visible Agent-local work plan current from the conversation.
 - `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, and `agent_media_generate`: perform confirmed external delivery, notification, reminder, or media actions when the user explicitly asks.
 
-`agent_harness` discovery modes are read-only. `summary` reports the model access map; `panels` lists the built-in panel catalog, and `panel` resolves one panel by `panelId`, `target`, or `query` with current open/focused state plus its matching Agent workspace route; `ui_surfaces` lists modal, overlay, picker, and workspace entrypoints, and `ui_surface` resolves one by `surfaceId`, `target`, or `query` with shell-opener availability and preferred model routes; `cli_commands` lists top-level package CLI mirror metadata, and `cli_command` resolves one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, returning parser output for concrete invocations, blocked command tokens, lookup metadata, and preferred in-process model routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` lists the live resolved keybinding table, and `keybinding`, `run_keybinding`, `set_keybinding`, and `reset_keybinding` resolve one action by `actionId`, `target`, `key`, or `query` with default bindings, custom state, config path, lookup metadata, and model-operation route metadata; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments plus concrete built-in effect/confirmation/preferred-tool/boundary policy metadata, and refuses ambiguous command lookup with candidate commands; `run_command` executes one confirmed slash command using the same `command`, `commandName`, `target`, or `query` resolver and refuses ambiguous command lookup before any handler runs; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` and `run_workspace_action` resolve one action by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields; inspection returns lookup metadata plus editor schema and `modelExecution` route metadata for every editor action, and execution refuses ambiguous requests with candidate actions before any effect; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query` and refuses ambiguous schema lookup with candidate tools; `settings` returns setting descriptors plus setting policy; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text and refuses ambiguous capability lookup with candidates; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
+`agent_harness` discovery modes are read-only. `summary` reports the model access map; `workspace` and `workspace_categories` list the Agent workspace category catalog with action counts; `panels` lists the built-in panel catalog, and `panel` resolves one panel by `panelId`, `target`, or `query` with current open/focused state plus its matching Agent workspace route; `ui_surfaces` lists modal, overlay, picker, and workspace entrypoints, and `ui_surface` resolves one by `surfaceId`, `target`, or `query` with shell-opener availability and preferred model routes; `cli_commands` lists top-level package CLI mirror metadata, and `cli_command` resolves one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, returning parser output for concrete invocations, blocked command tokens, lookup metadata, and preferred in-process model or current-conversation routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` lists the live resolved keybinding table, and `keybinding`, `run_keybinding`, `set_keybinding`, and `reset_keybinding` resolve one action by `actionId`, `target`, `key`, or `query` with default bindings, custom state, config path, lookup metadata, and model-operation route metadata; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments plus concrete built-in effect/confirmation/preferred-tool/boundary policy metadata for every registered command root, and refuses ambiguous command lookup with candidate commands; `run_command` executes one confirmed slash command using the same `command`, `commandName`, `target`, or `query` resolver and refuses ambiguous command lookup before any handler runs; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` and `run_workspace_action` resolve one action by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields; inspection returns lookup metadata plus editor schema and `modelExecution` route metadata for every editor action, and execution refuses ambiguous requests with candidate actions before any effect; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query` and refuses ambiguous schema lookup with candidate tools; `settings` returns setting descriptors plus setting policy; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text and refuses ambiguous capability lookup with candidates; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
 
 `open_ui_surface` is a confirmation-gated visible navigation mode for the same shell surfaces the user can open: Agent workspace, settings, MCP workspace, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, conversation search, prompt-history search, slash-command mode, command browser, file picker, block actions, bookmarks, context inspector, runtime activity monitor, live process output, help, shortcuts, and onboarding. It does not perform hidden operations; use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual state changes. Ambiguous UI surface lookup text is refused with candidate surfaces instead of routed.
 
-`cli_command` is a read-only inspection mode. Concrete CLI strings are parsed with redacted config overrides; descriptive lookup text searches the same `cli_commands` catalog and returns one match or candidate mirrors when broad.
+`cli_command` is a read-only inspection mode. Concrete CLI strings are parsed with redacted config overrides; descriptive lookup text searches the same `cli_commands` catalog and returns one match or candidate mirrors when broad. Supported top-level CLI mirrors report `preferredModelTool`, including current-conversation handling for non-interactive run mirrors that must not create hidden nested turns.
 
 `run_keybinding`, `set_keybinding`, and `reset_keybinding` are confirmation-gated control modes. `run_keybinding` executes only keybinding actions with a faithful current-shell route, such as cancel generation, clear screen, open/focus/dismiss visible panel workspace routes, open conversation or prompt-history search, paste through the existing clipboard handler, or open the visible block-action surface. Prompt-editor-only controls, terminal text selection, category cycling, and reserved shortcuts stay visible in descriptors but return unsupported/direct-interaction metadata instead of pretending a hidden model operation exists. `set_keybinding` and `reset_keybinding` write the same Agent `keybindings.json` file exposed by `/keybindings`, reload the runtime keybinding manager, and leave fixed runtime/editor shortcuts read-only. Ambiguous keybinding lookup text is refused with candidate actions instead of guessed.
 

package/package.json

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

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

@@ -222,6 +222,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'delegated-work',
       confirmation,
+      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action',
       boundary: 'Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly.',
     };
   }
@@ -244,6 +245,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'session-lifecycle',
       confirmation,
+      preferredModelTool: 'agent_harness commands/command/run_command',
       boundary: 'Session and conversation commands operate on the visible harness session lifecycle.',
     };
   }
@@ -251,6 +253,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'local-state',
       confirmation,
+      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action or agent_harness run_command',
       boundary: 'Conversation export writes a local workspace file and requires an explicit output intent.',
     };
   }
@@ -258,7 +261,7 @@ export function describeCommandPolicy(commandName: string): CommandExecutionPoli
     return {
       effect: 'ui-navigation',
       confirmation,
-      preferredModelTool: root === 'bookmarks' ? 'agent_harness open_ui_surface' : undefined,
+      preferredModelTool: root === 'bookmarks' ? 'agent_harness open_ui_surface' : 'agent_harness run_command',
       boundary: 'Conversation display navigation mutates only the visible transcript view or scroll position.',
     };
   }
@@ -335,6 +338,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: 'mixed',
       confirmation,
+      preferredModelTool: 'current Agent conversation response; do not invoke hidden nested CLI run',
       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.',
     };
   }
@@ -366,6 +370,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: 'delegated-work',
       confirmation,
+      preferredModelTool: 'agent_harness workspace_actions/workspace_action/run_workspace_action',
       boundary: 'Delegation is explicit user-directed work only; no hidden background review or separate Agent job should be created implicitly.',
     };
   }
@@ -373,6 +378,7 @@ export function describeCliCommandPolicy(commandName: string): CommandExecutionP
     return {
       effect: root === 'pair' ? 'external-network' : 'mixed',
       confirmation,
+      preferredModelTool: root === 'pair' ? 'agent_harness workspace_actions/workspace_action/run_workspace_action' : 'agent_harness settings/get_setting/set_setting/reset_setting or workspace_actions',
       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.',
     };
   }

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

@@ -530,7 +530,7 @@ 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, UI surfaces, keybindings, slash commands with policy metadata, model tools or one model tool schema, connected-host capabilities or one connected-host capability detail, and Agent settings, or to invoke a workspace action/command through the same in-process command registry the user uses in the TUI.',
+        'Use this tool to inspect Agent workspace categories/actions, built-in panels, top-level CLI mirrors, UI surfaces, keybindings, slash commands with policy metadata, model tools or one model tool schema, connected-host capabilities or one connected-host capability detail, 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, keybinding actions, 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(' '),
@@ -566,7 +566,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
               uiSurfaces: 'Use mode:"ui_surfaces" to list and mode:"ui_surface" with surfaceId, target, or query to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
               shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"keybinding" with actionId, target, key, or query; use mode:"run_keybinding" for confirmation-gated shell-safe shortcut equivalents; use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
               slashCommands: 'Use mode:"commands" to list slash commands and mode:"command" with command, commandName, target, or query to inspect one command; use mode:"run_command" with the same lookup fields plus confirm:true and explicitUserRequest to execute one uniquely resolved command.',
-              workspace: 'Use mode:"workspace_actions" to list, mode:"workspace_action" with actionId, command, target, or query for one action, editor schema, and modelExecution route metadata, and mode:"run_workspace_action" with the same lookup fields plus confirmation for executable actions; set includeParameters:true on workspace_actions to inline editor schemas.',
+              workspace: 'Use mode:"workspace" or mode:"workspace_categories" to list Agent workspace categories, mode:"workspace_actions" to list actions, mode:"workspace_action" with actionId, command, target, or query for one action, editor schema, and modelExecution route metadata, and mode:"run_workspace_action" with the same lookup fields plus confirmation for executable actions; set includeParameters:true on workspace_actions to inline editor schemas.',
               settings: 'Use mode:"settings" to list and mode:"get_setting" with key, target, or query for one setting. Use mode:"set_setting" or mode:"reset_setting" with key, target, or query plus confirm:true and explicitUserRequest.',
               tools: 'Use mode:"tools" to list first-class model tools, or mode:"tool" with toolName, target, or query to inspect one schema.',
               connectedHost: 'Use mode:"connected_host" for the connected-host capability map and blocked boundaries. Use mode:"connected_host_capability" with capabilityId, target, or query for one allowed or blocked capability.',

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.28';
+let _version = '1.0.30';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {