@pellux/goodvibes-agent 1.1.6 → 1.2.0

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

@@ -1,6 +1,8 @@
 import type { CommandContext } from '../input/command-registry.ts';
 import type { AgentWorkspaceChannelStatus } from '../input/agent-workspace-channels.ts';
-import { buildAgentWorkspaceChannels } from '../input/agent-workspace-channels.ts';
+import { readAgentChannelDeliveryReceipts } from '../agent/channel-delivery-receipts.ts';
+import { buildAgentWorkspaceChannelTriage, type AgentWorkspaceChannelTriage } from '../input/agent-workspace-channel-triage.ts';
+import { buildAgentWorkspaceChannelSetupGuide, buildAgentWorkspaceChannels } from '../input/agent-workspace-channels.ts';
 import { previewHarnessText } from './agent-harness-text.ts';
 
 export interface AgentHarnessChannelArgs {
@@ -18,6 +20,11 @@ type ChannelResolution =
   | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
   | { readonly status: 'missing_lookup'; readonly usage: string };
 
+type ChannelSetupGuideResolution =
+  | { readonly status: 'found'; readonly guide: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -60,12 +67,28 @@ function describeChannelCandidate(channel: AgentWorkspaceChannelStatus): Record<
     setupState: channel.setupState,
     ready: channel.ready,
     delivery: channel.delivery,
-    modelRoute: channelModelRoute(),
+    modelRoute: channelModelRoute(channel.id),
   };
 }
 
-function channelModelRoute(): string {
-  return 'agent_channel_send or agent_harness mode:"channel"';
+function channelModelRoute(channelId?: string): string {
+  return channelId
+    ? `channels action:"channel" channelId:"${channelId}"`
+    : 'channels action:"status"';
+}
+
+function channelSetupGuideModelRoute(channelId?: string): string {
+  return channelId
+    ? `channels action:"setup" channelId:"${channelId}"`
+    : 'channels action:"setup"';
+}
+
+function channelDeliveriesModelRoute(): string {
+  return 'channels action:"deliveries"';
+}
+
+function channelTriageModelRoute(): string {
+  return 'channels action:"triage"';
 }
 
 function describeChannel(
@@ -88,7 +111,8 @@ function describeChannel(
     missingConfigKeys: channel.missingRequiredKeys,
     defaultTargetKeys: channel.defaultTargetKeys,
     configuredDefaultTargetKeys: channel.configuredDefaultTargetKeys,
-    modelRoute: channelModelRoute(),
+    modelRoute: channelModelRoute(channel.id),
+    setupGuideRoute: channelSetupGuideModelRoute(channel.id),
     ...(options.lookup ? { lookup: options.lookup } : {}),
     ...(options.includeParameters
       ? {
@@ -110,8 +134,8 @@ function describeChannel(
             `/channels doctor ${channel.id}`,
             `/channels setup ${channel.id}`,
           ],
-          settingsFilter: `agent_harness mode:"settings" prefix:"surfaces.${channel.id}" includeHidden:true`,
-          connectedHostBoundary: 'agent_harness mode:"connected_host_capability" query:"delivery"',
+          settingsFilter: `settings action:"list" prefix:"surfaces.${channel.id}" includeHidden:true`,
+          connectedHostBoundary: 'host action:"capability" query:"delivery"',
           deliveryTargetShape: 'surface[:route[:label]]',
           exampleTarget: `${channel.id}:route:Label`,
         },
@@ -124,14 +148,25 @@ function describeChannel(
 
 export function channelReadinessCatalogStatus(context: CommandContext): Record<string, unknown> {
   const channels = buildAgentWorkspaceChannels(context);
+  const guide = buildAgentWorkspaceChannelSetupGuide(channels);
   return {
-    modes: ['channels', 'channel'],
+    modes: ['channels', 'channel', 'channel_setup_guide', 'channel_triage', 'channel_deliveries'],
+    modelRoute: 'channels action:"status"',
     channels: channels.length,
     enabled: channels.filter((channel) => channel.enabled).length,
     ready: channels.filter((channel) => channel.ready).length,
     attention: channels.filter((channel) => channel.enabled && channel.setupState !== 'ready').length,
+    setupGuide: {
+      status: guide.status,
+      currentChannelId: guide.currentChannelId,
+      currentStepId: guide.currentStepId,
+      progressLabel: guide.progressLabel,
+      modelRoute: channelSetupGuideModelRoute(guide.currentChannelId ?? undefined),
+    },
     readOnly: true,
     deliveryTool: 'agent_channel_send',
+    triage: channelTriageModelRoute(),
+    deliveryReceipts: channelDeliveriesModelRoute(),
   };
 }
 
@@ -150,6 +185,12 @@ export function listHarnessChannels(context: CommandContext, args: AgentHarnessC
     enabled: channels.filter((channel) => channel.enabled).length,
     ready: channels.filter((channel) => channel.ready).length,
     attention: channels.filter((channel) => channel.enabled && channel.setupState !== 'ready').length,
+    setupGuide: {
+      status: buildAgentWorkspaceChannelSetupGuide(channels).status,
+      modelRoute: channelSetupGuideModelRoute(),
+    },
+    triage: channelTriageModelRoute(),
+    deliveryReceipts: channelDeliveriesModelRoute(),
     policy: 'Read-only channel readiness catalog. It returns key names, setup state, delivery posture, and model routes without printing secrets or sending messages.',
   };
 }
@@ -159,7 +200,7 @@ export function describeHarnessChannel(context: CommandContext, args: AgentHarne
   if (!lookup) {
     return {
       status: 'missing_lookup',
-      usage: 'channel requires channelId, target, or query. Use mode:"channels" to inspect available channel ids.',
+      usage: 'channels action:"channel" requires channelId, target, or query. Use channels action:"status" to inspect available channel ids.',
     };
   }
   const channels = buildAgentWorkspaceChannels(context);
@@ -183,6 +224,123 @@ export function describeHarnessChannel(context: CommandContext, args: AgentHarne
   }
   return {
     status: 'missing_lookup',
-    usage: `Unknown channel ${lookup.input}. Use mode:"channels" to inspect available channel ids.`,
+    usage: `Unknown channel ${lookup.input}. Use channels action:"status" to inspect available channel ids.`,
+  };
+}
+
+export function describeHarnessChannelSetupGuide(context: CommandContext, args: AgentHarnessChannelArgs): ChannelSetupGuideResolution {
+  const channels = buildAgentWorkspaceChannels(context);
+  const lookup = channelLookupFromArgs(args);
+  if (!lookup) {
+    const guide = buildAgentWorkspaceChannelSetupGuide(channels);
+    return {
+      status: 'found',
+      guide: {
+        mode: 'channel_setup_guide',
+        guide,
+        routes: {
+          channels: 'channels action:"status"',
+          currentChannel: guide.currentChannelId ? channelSetupGuideModelRoute(guide.currentChannelId) : null,
+        },
+        policy: guide.policy,
+      },
+    };
+  }
+  const normalized = lookup.input.toLowerCase();
+  const exact = channels.find((channel) => channel.id === lookup.input || channel.id.toLowerCase() === normalized || channel.label.toLowerCase() === normalized);
+  if (exact) {
+    const guide = buildAgentWorkspaceChannelSetupGuide(channels, { channelId: exact.id });
+    return {
+      status: 'found',
+      guide: {
+        mode: 'channel_setup_guide',
+        guide,
+        lookup: { ...lookup, resolvedBy: exact.id === lookup.input ? 'id' : 'case-insensitive' },
+        routes: {
+          channel: channelModelRoute(exact.id),
+          channels: 'channels action:"status"',
+        },
+        policy: guide.policy,
+      },
+    };
+  }
+  const searched = channels.filter((channel) => channelSearchText(channel).includes(normalized));
+  if (searched.length === 1) {
+    const channel = searched[0]!;
+    const guide = buildAgentWorkspaceChannelSetupGuide(channels, { channelId: channel.id });
+    return {
+      status: 'found',
+      guide: {
+        mode: 'channel_setup_guide',
+        guide,
+        lookup: { ...lookup, resolvedBy: 'search' },
+        routes: {
+          channel: channelModelRoute(channel.id),
+          channels: 'channels action:"status"',
+        },
+        policy: guide.policy,
+      },
+    };
+  }
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeChannelCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown channel setup guide target ${lookup.input}. Use channels action:"status" to inspect available channel ids.`,
+  };
+}
+
+export function describeHarnessChannelDeliveries(context: CommandContext, args: AgentHarnessChannelArgs): Record<string, unknown> {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths) {
+    return {
+      mode: 'channel_deliveries',
+      status: 'unavailable',
+      receipts: [],
+      policy: 'Read-only delivery receipts require Agent shell path context. Sends still require explicit confirmation.',
+      nextActions: ['Open a normal Agent workspace before relying on channel delivery receipts.'],
+    };
+  }
+  const limit = readLimit(args.limit, 20);
+  const snapshot = readAgentChannelDeliveryReceipts(shellPaths);
+  const receipts = snapshot.receipts.slice(0, limit).map((receipt) => ({
+    receiptId: receipt.id,
+    createdAt: receipt.createdAt,
+    source: receipt.source,
+    status: receipt.status,
+    target: receipt.target,
+    title: receipt.title,
+    messageLength: receipt.messageLength,
+    messageDigest: receipt.messageDigest,
+    messagePreview: receipt.messagePreview,
+    strategyCount: receipt.strategyCount,
+    responseId: receipt.responseId ?? null,
+    userRoute: receipt.userRoute,
+    modelRoute: receipt.modelRoute,
+    authorization: receipt.authorization,
+  }));
+  return {
+    mode: 'channel_deliveries',
+    status: snapshot.parseError ? 'attention' : snapshot.exists ? 'ready' : 'empty',
+    path: snapshot.path,
+    total: snapshot.receipts.length,
+    returned: receipts.length,
+    receipts,
+    routes: {
+      command: '/channels deliveries',
+      sendTool: 'agent_channel_send',
+      channels: 'channels action:"status"',
+    },
+    ...(snapshot.parseError ? { parseError: snapshot.parseError } : {}),
+    policy: 'Read-only confirmed delivery history. Receipt targets redact webhook/link addresses, message bodies are bounded/redacted, and new sends still require explicit user confirmation.',
   };
 }
+
+export async function describeHarnessChannelTriage(context: CommandContext, args: AgentHarnessChannelArgs): Promise<AgentWorkspaceChannelTriage> {
+  return buildAgentWorkspaceChannelTriage(context, args);
+}

package/src/tools/agent-harness-cli-command-policy.ts

@@ -0,0 +1,110 @@
+import type { CommandExecutionPolicy } from './agent-harness-metadata.ts';
+
+function agentHarnessModes(...modes: readonly string[]): string {
+  return `agent_harness ${modes.map((mode) => `mode:"${mode}"`).join(', ')}`;
+}
+
+function settingsActions(...actions: readonly string[]): string {
+  return `settings ${actions.map((action) => `action:"${action}"`).join('|')}`;
+}
+
+function hostActions(...actions: readonly string[]): string {
+  return `host ${actions.map((action) => `action:"${action}"`).join('|')}`;
+}
+
+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, route relays, 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'
+        ? agentHarnessModes('workspace', 'workspace_actions', 'workspace_action', 'run_workspace_action')
+        : agentHarnessModes('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 routes from the model when operating inside the TUI.',
+    };
+  }
+  if (root === 'run') {
+    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.',
+    };
+  }
+  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' : `${hostActions('status', 'services', 'service', 'capabilities')} or ${settingsActions('list', 'get')} or ${agentHarnessModes('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' ? agentHarnessModes('workspace_actions', 'workspace_action', '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,
+      preferredModelTool: agentHarnessModes('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.',
+    };
+  }
+  if (root === 'subscription' || root === 'secrets' || root === 'pair') {
+    return {
+      effect: root === 'pair' ? 'external-network' : 'mixed',
+      confirmation,
+      preferredModelTool: root === 'pair'
+        ? agentHarnessModes('workspace_actions', 'workspace_action', 'run_workspace_action')
+        : `${settingsActions('list', 'get', 'set', 'reset')} or ${agentHarnessModes('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.',
+    };
+  }
+  return {
+    effect: 'unknown',
+    confirmation,
+    boundary: 'Inspect the CLI help, parser result, and preferred model routes before using an equivalent command path.',
+  };
+}

package/src/tools/agent-harness-command-catalog.ts

@@ -58,7 +58,7 @@ function commandMatches(command: SlashCommand, query: string): boolean {
 
 function describeCommand(command: SlashCommand, lookup?: CommandDetailLookup): Record<string, unknown> {
   const policy = describeCommandPolicy(command.name);
-  const modelRoute = previewText(policy.preferredModelTool ?? 'agent_harness mode:"command", mode:"run_command"');
+  const modelRoute = previewText(policy.preferredModelTool ?? `workspace action:"command" commandName:"${command.name}"`);
   return {
     name: command.name,
     slash: `/${command.name}`,
@@ -71,6 +71,8 @@ function describeCommand(command: SlashCommand, lookup?: CommandDetailLookup): R
       inspect: `agent_harness mode:"command" commandName:"${command.name}"`,
       run: `agent_harness mode:"run_command" commandName:"${command.name}" confirm:true explicitUserRequest:"..."`,
       preferred: modelRoute,
+      directInspect: `workspace action:"command" commandName:"${command.name}"`,
+      directRun: `workspace action:"run_command" commandName:"${command.name}" confirm:true explicitUserRequest:"..."`,
     },
     ...(lookup ? {
       lookup: {
@@ -93,7 +95,7 @@ function describeCommandCandidate(command: SlashCommand): Record<string, unknown
     aliases: command.aliases ?? [],
     summary: previewText(command.description),
     effect: policy.effect,
-    modelRoute: previewText(policy.preferredModelTool ?? 'agent_harness mode:"command", mode:"run_command"'),
+    modelRoute: previewText(policy.preferredModelTool ?? `workspace action:"command" commandName:"${command.name}"`),
     ...(command.argsHint ? { argsHint: command.argsHint } : {}),
   };
 }

package/src/tools/agent-harness-command-runner.ts

@@ -0,0 +1,42 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import { resolveHarnessCommandDetail, type CommandDetailLookup } from './agent-harness-command-catalog.ts';
+import type { AgentHarnessToolArgs, AgentHarnessToolDeps } from './agent-harness-tool-types.ts';
+import { error, output, requireConfirmedAction } from './agent-harness-tool-utils.ts';
+
+function invocationArgsFromLookup(lookup: CommandDetailLookup): readonly string[] {
+  return lookup.resolvedBy === 'description' ? [] : lookup.parsedArgs;
+}
+
+function safeCommandDisplay(name: string): string {
+  return `/${name}`;
+}
+
+export async function runCommand(deps: AgentHarnessToolDeps, args: AgentHarnessToolArgs): Promise<{ readonly success: boolean; readonly output?: string; readonly error?: string }> {
+  const confirmationError = requireConfirmedAction(args, 'Slash command invocation');
+  if (confirmationError) return error(confirmationError);
+  const resolved = resolveHarnessCommandDetail(deps.commandRegistry, args);
+  if (resolved?.status === 'ambiguous') {
+    return error(`Ambiguous slash command ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+  }
+  if (!resolved) return error('run_command requires a valid command, commandName, target, or query. Use mode:"commands" to inspect available commands.');
+
+  const printed: string[] = [];
+  const toolContext: CommandContext = {
+    ...deps.commandContext,
+    print: (text: string) => {
+      printed.push(text);
+    },
+    renderRequest: () => {},
+    executeCommand: async (name: string, commandArgs: string[]) => {
+      return deps.commandRegistry.execute(name, commandArgs, toolContext);
+    },
+  };
+  const commandArgs = invocationArgsFromLookup(resolved.lookup);
+  const handled = await deps.commandRegistry.execute(resolved.command.name, [...commandArgs], toolContext);
+  if (!handled) return error(`Unknown slash command /${resolved.command.name}.`);
+  return output([
+    `Command ${safeCommandDisplay(resolved.command.name)} completed.`,
+    `Resolved by ${resolved.lookup.source} ${resolved.lookup.resolvedBy}.`,
+    printed.length > 0 ? printed.join('\n') : '(no text output)',
+  ].join('\n'));
+}

package/src/tools/agent-harness-connected-host-status.ts

@@ -88,9 +88,12 @@ export async function connectedHostStatusSummary(
   return {
     ownership: 'external-connected-host',
     readOnly: true,
-    modelRoute: 'agent_harness mode:"connected_host_status" or mode:"service_posture"',
+    modelRoute: 'host action:"status" or action:"services"',
+    compatibilityRoutes: {
+      modelRoute: 'agent_harness mode:"connected_host_status" or mode:"service_posture"',
+    },
     timeoutMs: CONNECTED_HOST_STATUS_TIMEOUT_MS,
-    lifecycle: 'GoodVibes Agent can inspect connected-host readiness and use public operator routes, but does not start, stop, restart, install, expose, or mutate the host listener.',
+    lifecycle: 'GoodVibes Agent can inspect daemon readiness and use confirmed operator methods for supported lifecycle/listener changes.',
     paths: {
       workingDirectory,
       homeDirectory,
@@ -140,9 +143,9 @@ export async function connectedHostStatusSummary(
       blockedCapabilities: blockedConnectedHostCapabilities().length,
     },
     ...(options.includeParameters ? { modelAccess: {
-      diagnostics: 'Use mode:"connected_host_status" for live read-only host readiness, mode:"service_posture" for endpoint posture, mode:"service_endpoint" for one endpoint, and mode:"connected_host" for capability and boundary inventory.',
+      diagnostics: 'Use host action:"status" for live readiness, action:"services|service" for endpoint posture, and action:"capabilities|capability" for capability inventory.',
       daemonAliases: 'mode:"daemon_status" is an alias for mode:"connected_host_status"; mode:"daemon" is an alias for mode:"connected_host".',
-      lifecycleBlocked: 'Start, stop, restart, install, expose, and listener mutation are not exposed through Agent.',
+      lifecycle: 'Use setup or agent_operator_method with confirm:true and explicitUserRequest for supported daemon service methods.',
       cliMirrors: ['goodvibes-agent status --json', 'goodvibes-agent doctor', 'goodvibes-agent compat'],
       tuiMirrors: ['Agent Workspace -> Home -> Host compatibility', 'Agent Workspace -> Home -> Doctor diagnostics', 'Agent Workspace -> Home -> Review health'],
     },