@pellux/goodvibes-agent 1.0.16 → 1.0.18

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

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

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

@@ -33,9 +33,9 @@ import {
 } from './agent-harness-metadata.ts';
 import {
   formatHarnessError,
-  getHarnessSetting,
   listHarnessSettings,
   resetHarnessSetting,
+  resolveHarnessSetting,
   setHarnessSetting,
 } from '../agent/harness-control.ts';
 
@@ -109,6 +109,17 @@ function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
 
+function settingLookupArgs(args: AgentHarnessToolArgs) {
+  return {
+    key: readString(args.key) || undefined,
+    target: readString(args.target) || undefined,
+    query: readString(args.query) || undefined,
+    category: readString(args.category) || undefined,
+    prefix: readString(args.prefix) || undefined,
+    includeHidden: args.includeHidden === true,
+  };
+}
+
 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;
@@ -584,12 +595,12 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
             tools: deps.toolRegistry.getToolDefinitions().length,
             modelAccess: {
               cliCommands: 'Use mode:"cli_commands" and mode:"cli_command" to inspect package CLI mirrors and their preferred in-process model routes. CLI modes are discovery-only.',
-              panels: 'Use mode:"panels" and mode:"panel" to inspect built-in panel catalog/open state; use mode:"open_panel" with confirm:true plus explicitUserRequest to route a visible panel/workspace change.',
-              uiSurfaces: 'Use mode:"ui_surfaces" and mode:"ui_surface" to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
-              shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
+              panels: 'Use mode:"panels" to list and mode:"panel" with panelId, target, or query to inspect built-in panel catalog/open state; use mode:"open_panel" with confirm:true plus explicitUserRequest to route a visible panel/workspace change.',
+              uiSurfaces: 'Use mode:"ui_surfaces" to list and mode:"ui_surface" with surfaceId, target, or query to inspect modal/overlay/picker/workspace surfaces; use mode:"open_ui_surface" with confirm:true plus explicitUserRequest to route visible UI navigation.',
+              shortcuts: 'Use mode:"shortcuts" to inspect fixed shortcuts plus configurable keybindings. Use mode:"keybinding" with actionId, target, key, or query; use mode:"set_keybinding" and mode:"reset_keybinding" with confirm:true plus explicitUserRequest to edit the same config file the user edits.',
               slashCommands: 'Use mode:"commands" to list slash commands and mode:"command" with command, commandName, target, or query to inspect one command; use mode:"run_command" with confirm:true plus explicitUserRequest to execute.',
               workspace: 'Use mode:"workspace_actions" to list and mode:"workspace_action" with actionId, command, target, or query for one action and editor schema; set includeParameters:true on workspace_actions to inline editor schemas.',
-              settings: 'Use mode:"settings", mode:"get_setting", mode:"set_setting", and mode:"reset_setting".',
+              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.',
               connectedHostStatus: 'Use mode:"connected_host_status" for live read-only host reachability, SDK compatibility, token posture, and Agent Knowledge route readiness.',
@@ -622,7 +633,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         }
         if (args.mode === 'panel') {
           const panel = describeHarnessPanel(deps.commandContext, args);
-          return panel ? output(panel) : error(`Unknown panel ${readString(args.panelId || args.query) || '<missing>'}.`);
+          return panel ? output(panel) : error(`Unknown panel ${readString(args.panelId || args.target || args.query) || '<missing>'}.`);
         }
         if (args.mode === 'open_panel') {
           const confirmationError = requireConfirmedAction(args, 'Panel routing');
@@ -635,7 +646,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         }
         if (args.mode === 'ui_surface') {
           const surface = describeHarnessUiSurface(deps.commandContext, args);
-          return surface ? output(surface) : error(`Unknown UI surface ${readString(args.surfaceId || args.query) || '<missing>'}.`);
+          return surface ? output(surface) : error(`Unknown UI surface ${readString(args.surfaceId || args.query || args.target) || '<missing>'}.`);
         }
         if (args.mode === 'open_ui_surface') {
           const confirmationError = requireConfirmedAction(args, 'UI surface routing');
@@ -646,7 +657,7 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
         if (args.mode === 'keybindings') return output(listHarnessKeybindings(deps.commandContext, args));
         if (args.mode === 'keybinding') {
           const binding = describeHarnessKeybinding(deps.commandContext, args);
-          return binding ? output(binding) : error(`Unknown keybinding action ${readString(args.actionId || args.key || args.query) || '<missing>'}.`);
+          return binding ? output(binding) : error(`Unknown keybinding action ${readString(args.actionId || args.target || args.key || args.query) || '<missing>'}.`);
         }
         if (args.mode === 'set_keybinding') {
           const confirmationError = requireConfirmedAction(args, 'Keybinding mutation');
@@ -681,33 +692,48 @@ export function createAgentHarnessTool(deps: AgentHarnessToolDeps): Tool {
           return output({ settings, returned: settings.length, policy: settingsPolicySummary() });
         }
         if (args.mode === 'get_setting') {
-          const key = readString(args.key);
-          const setting = getHarnessSetting(deps.commandContext.platform.configManager, key);
-          return setting ? output(setting) : error(`Unknown setting ${key || '<missing>'}.`);
+          const setting = resolveHarnessSetting(deps.commandContext.platform.configManager, settingLookupArgs(args));
+          if (setting?.status === 'found') return output(setting.setting);
+          if (setting?.status === 'ambiguous') {
+            return error(`Ambiguous setting ${setting.input}. Candidates: ${JSON.stringify(setting.candidates)}`);
+          }
+          return error(`Unknown setting ${readString(args.key || args.target || args.query) || '<missing>'}. Use mode:"settings" to inspect available settings.`);
         }
         if (args.mode === 'set_setting') {
           const confirmationError = requireConfirmedAction(args, 'Setting mutation');
           if (confirmationError) return error(confirmationError);
           if (args.value === undefined) return error('set_setting requires value.');
-          const key = readString(args.key);
+          const setting = resolveHarnessSetting(deps.commandContext.platform.configManager, settingLookupArgs(args));
+          if (setting?.status === 'ambiguous') {
+            return error(`Ambiguous setting ${setting.input}. Candidates: ${JSON.stringify(setting.candidates)}`);
+          }
+          if (setting?.status !== 'found') {
+            return error(`Unknown setting ${readString(args.key || args.target || args.query) || '<missing>'}. Use mode:"settings" to inspect available settings.`);
+          }
           const result = await setHarnessSetting(
             deps.commandContext.platform.configManager,
             deps.commandContext.platform.secretsManager,
-            key,
+            setting.setting.key,
             args.value,
           );
-          return output(result);
+          return output({ ...result, lookup: setting.lookup });
         }
         if (args.mode === 'reset_setting') {
           const confirmationError = requireConfirmedAction(args, 'Setting reset');
           if (confirmationError) return error(confirmationError);
-          const key = readString(args.key);
+          const setting = resolveHarnessSetting(deps.commandContext.platform.configManager, settingLookupArgs(args));
+          if (setting?.status === 'ambiguous') {
+            return error(`Ambiguous setting ${setting.input}. Candidates: ${JSON.stringify(setting.candidates)}`);
+          }
+          if (setting?.status !== 'found') {
+            return error(`Unknown setting ${readString(args.key || args.target || args.query) || '<missing>'}. Use mode:"settings" to inspect available settings.`);
+          }
           const result = await resetHarnessSetting(
             deps.commandContext.platform.configManager,
             deps.commandContext.platform.secretsManager,
-            key,
+            setting.setting.key,
           );
-          return output(result);
+          return output({ ...result, lookup: setting.lookup });
         }
         if (args.mode === 'workspace' || args.mode === 'workspace_categories') {
           return output({

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

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

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