@pellux/goodvibes-agent 1.0.31 → 1.0.34

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

@@ -0,0 +1,177 @@
+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';
+
+export interface AgentHarnessChannelArgs {
+  readonly channelId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type ChannelLookupSource = 'channelId' | 'target' | 'query';
+
+type ChannelResolution =
+  | { readonly status: 'found'; readonly channel: 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() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function channelLookupFromArgs(args: AgentHarnessChannelArgs): { readonly source: ChannelLookupSource; readonly input: string } | null {
+  const channelId = readString(args.channelId);
+  if (channelId) return { source: 'channelId', input: channelId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function channelSearchText(channel: AgentWorkspaceChannelStatus): string {
+  return [
+    channel.id,
+    channel.label,
+    channel.delivery,
+    channel.risk,
+    channel.riskLabel,
+    channel.setupState,
+    channel.nextStep,
+    ...channel.requiredKeys,
+    ...channel.missingRequiredKeys,
+    ...channel.defaultTargetKeys,
+    ...channel.configuredDefaultTargetKeys,
+  ].join('\n').toLowerCase();
+}
+
+function describeChannelCandidate(channel: AgentWorkspaceChannelStatus): Record<string, unknown> {
+  return {
+    channelId: channel.id,
+    label: channel.label,
+    setupState: channel.setupState,
+    ready: channel.ready,
+    delivery: channel.delivery,
+  };
+}
+
+function describeChannel(
+  channel: AgentWorkspaceChannelStatus,
+  options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {},
+): Record<string, unknown> {
+  return {
+    id: channel.id,
+    label: channel.label,
+    enabled: channel.enabled,
+    ready: channel.ready,
+    setupState: channel.setupState,
+    delivery: channel.delivery,
+    risk: channel.risk,
+    riskLabel: channel.riskLabel,
+    missingConfigCount: channel.missingConfigCount,
+    defaultTarget: channel.defaultTarget,
+    nextStep: channel.nextStep,
+    requiredConfigKeys: channel.requiredKeys,
+    missingConfigKeys: channel.missingRequiredKeys,
+    defaultTargetKeys: channel.defaultTargetKeys,
+    configuredDefaultTargetKeys: channel.configuredDefaultTargetKeys,
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? {
+      policy: {
+        effect: 'read-only',
+        values: 'Config key names and target key names are shown; secret values and stored target values are never returned.',
+        delivery: 'Use agent_channel_send only for one explicit, confirmed delivery target requested by the user.',
+        setup: 'Use connected-host setup/account/policy routes only as read-only diagnostics unless another confirmed first-class tool owns the mutation.',
+      },
+      modelAccess: {
+        sendTool: 'agent_channel_send',
+        notificationTool: 'agent_notify',
+        reminderTool: 'agent_reminder_schedule',
+        slashCommandDetail: `/channels show ${channel.id}`,
+        readOnlyConnectedRoutes: [
+          '/channels accounts',
+          '/channels policies',
+          '/channels status',
+          `/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"',
+        deliveryTargetShape: 'surface[:route[:label]]',
+        exampleTarget: `${channel.id}:route:Label`,
+      },
+    } : {}),
+  };
+}
+
+export function channelReadinessCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const channels = buildAgentWorkspaceChannels(context);
+  return {
+    modes: ['channels', 'channel'],
+    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,
+    readOnly: true,
+    deliveryTool: 'agent_channel_send',
+  };
+}
+
+export function listHarnessChannels(context: CommandContext, args: AgentHarnessChannelArgs): Record<string, unknown> {
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const limit = readLimit(args.limit, 200);
+  const channels = buildAgentWorkspaceChannels(context);
+  const filtered = channels
+    .filter((channel) => !query || channelSearchText(channel).includes(query))
+    .slice(0, limit);
+  return {
+    channels: filtered.map((channel) => describeChannel(channel, { includeParameters })),
+    returned: filtered.length,
+    total: 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,
+    policy: 'Read-only channel readiness catalog. It returns key names, setup state, delivery posture, and model routes without printing secrets or sending messages.',
+  };
+}
+
+export function describeHarnessChannel(context: CommandContext, args: AgentHarnessChannelArgs): ChannelResolution {
+  const lookup = channelLookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'channel requires channelId, target, or query. Use mode:"channels" to inspect available channel ids.',
+    };
+  }
+  const channels = buildAgentWorkspaceChannels(context);
+  const normalized = lookup.input.toLowerCase();
+  const exact = channels.find((channel) => channel.id === lookup.input);
+  if (exact) return { status: 'found', channel: describeChannel(exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitiveId = channels.find((channel) => channel.id.toLowerCase() === normalized);
+  if (insensitiveId) return { status: 'found', channel: describeChannel(insensitiveId, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const insensitiveLabel = channels.find((channel) => channel.label.toLowerCase() === normalized);
+  if (insensitiveLabel) return { status: 'found', channel: describeChannel(insensitiveLabel, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-label' } }) };
+  const searched = channels.filter((channel) => channelSearchText(channel).includes(normalized));
+  if (searched.length === 1) {
+    return { status: 'found', channel: describeChannel(searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  }
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeChannelCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown channel ${lookup.input}. Use mode:"channels" to inspect available channel ids.`,
+  };
+}

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

@@ -14,6 +14,7 @@ export interface AgentHarnessCliArgs {
   readonly cliCommand?: unknown;
   readonly commandName?: unknown;
   readonly target?: unknown;
+  readonly includeParameters?: unknown;
   readonly limit?: unknown;
 }
 
@@ -106,12 +107,14 @@ export function blockedHarnessCliCommandTokens(): readonly string[] {
 export function listHarnessCliCommands(args: AgentHarnessCliArgs): readonly Record<string, unknown>[] {
   const query = readString(args.query);
   const limit = readLimit(args.limit, 200);
+  const includeParameters = args.includeParameters === true;
   return listGoodVibesCliCommands()
     .filter((command) => command !== 'unknown')
     .map((command) => describeCliCommand(command))
     .filter((command) => cliCommandMatches(command, query))
     .sort((a, b) => String(a.name).localeCompare(String(b.name)))
-    .slice(0, limit);
+    .slice(0, limit)
+    .map((command) => includeParameters ? command : cliCommandCandidate(command));
 }
 
 function cliInputFromArgs(args: AgentHarnessCliArgs): { readonly source: CliCommandLookup['source']; readonly input: string } | null {

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

@@ -8,6 +8,7 @@ export interface AgentHarnessCommandCatalogArgs {
   readonly commandName?: unknown;
   readonly args?: unknown;
   readonly target?: unknown;
+  readonly includeParameters?: unknown;
   readonly limit?: unknown;
 }
 
@@ -38,6 +39,11 @@ function readStringArray(value: unknown): readonly string[] {
   return value.map((entry) => typeof entry === 'string' ? entry : String(entry));
 }
 
+function previewText(value: string, maxLength = 120): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 1).trimEnd()}...`;
+}
+
 function commandMatches(command: SlashCommand, query: string): boolean {
   if (!query) return true;
   const haystack = [
@@ -76,8 +82,8 @@ function describeCommandCandidate(command: SlashCommand): Record<string, unknown
     name: command.name,
     slash: `/${command.name}`,
     aliases: command.aliases ?? [],
-    description: command.description,
-    usage: command.usage ?? '',
+    summary: previewText(command.description),
+    ...(command.argsHint ? { argsHint: command.argsHint } : {}),
   };
 }
 
@@ -165,11 +171,12 @@ export function resolveHarnessCommandDetail(commandRegistry: CommandRegistry, ar
 export function listHarnessCommands(commandRegistry: CommandRegistry, args: AgentHarnessCommandCatalogArgs): readonly Record<string, unknown>[] {
   const query = readString(args.query);
   const limit = readLimit(args.limit, 200);
+  const includeParameters = args.includeParameters === true;
   return commandRegistry.list()
     .filter((command) => commandMatches(command, query))
     .sort((a, b) => a.name.localeCompare(b.name))
     .slice(0, limit)
-    .map((command) => describeCommand(command));
+    .map((command) => includeParameters ? describeCommand(command) : describeCommandCandidate(command));
 }
 
 export function describeHarnessCommand(commandRegistry: CommandRegistry, args: AgentHarnessCommandCatalogArgs): Record<string, unknown> | null {

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

@@ -73,6 +73,7 @@ function connectedHostFindings(
 export async function connectedHostStatusSummary(
   context: CommandContext,
   toolRegistry: ToolRegistry,
+  options: { readonly includeParameters?: boolean } = {},
 ): Promise<Record<string, unknown>> {
   const homeDirectory = resolveHomeDirectory(context);
   const workingDirectory = resolveWorkingDirectory(context);
@@ -134,13 +135,18 @@ export async function connectedHostStatusSummary(
       },
     ],
     findings: connectedHostFindings(runtime, tokenUsable),
-    modelAccess: {
-      diagnostics: 'Use mode:"connected_host_status" for live read-only host readiness. Use mode:"connected_host" for capability and boundary inventory.',
+    capabilitySummary: {
+      routeFamilies: connectedHostRouteFamilies().length,
+      availableCapabilities: connectedHostCapabilityMap(toolRegistry).filter((capability) => capability.available === true).length,
+      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.',
       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'],
     },
     routeFamilies: connectedHostRouteFamilies(),
     capabilities: connectedHostCapabilityMap(toolRegistry),
-    blockedCapabilities: blockedConnectedHostCapabilities(),
+    blockedCapabilities: blockedConnectedHostCapabilities() } : {}),
   };
 }

package/src/tools/agent-harness-delegation-posture.ts

@@ -0,0 +1,216 @@
+import type { CommandContext } from '../input/command-registry.ts';
+
+export interface AgentHarnessDelegationArgs {
+  readonly delegationRouteId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type DelegationResolution =
+  | { readonly status: 'found'; readonly route: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+type DelegationLookupSource = 'delegationRouteId' | 'target' | 'query';
+
+interface DelegationRoute {
+  readonly id: string;
+  readonly label: string;
+  readonly detail: string;
+  readonly effect: 'read-only' | 'main-conversation' | 'delegated-work' | 'blocked';
+  readonly command?: string;
+  readonly commandTemplate?: string;
+  readonly workspaceActionId?: string;
+  readonly confirmationRequired?: boolean;
+  readonly reviewPolicy?: 'explicit-only' | 'not-applicable';
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function lookupFromArgs(args: AgentHarnessDelegationArgs): { readonly source: DelegationLookupSource; readonly input: string } | null {
+  const delegationRouteId = readString(args.delegationRouteId);
+  if (delegationRouteId) return { source: 'delegationRouteId', input: delegationRouteId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function routes(): readonly DelegationRoute[] {
+  return [
+    {
+      id: 'delegate-build-task',
+      label: 'Delegate build/fix/review task',
+      detail: 'Send one explicit build, fix, implementation, patch, or review task to GoodVibes TUI/shared-session routes with the full original ask.',
+      effect: 'delegated-work',
+      commandTemplate: '/delegate <full original user ask>',
+      workspaceActionId: 'delegate-task',
+      confirmationRequired: true,
+      reviewPolicy: 'explicit-only',
+    },
+    {
+      id: 'delegate-build-task-with-review',
+      label: 'Delegate with requested review',
+      detail: 'Request delegated review only when the user explicitly asks for review or explicitly requests review as part of a build/fix/review handoff.',
+      effect: 'delegated-work',
+      commandTemplate: '/delegate --review <full original user ask>',
+      workspaceActionId: 'delegate-task',
+      confirmationRequired: true,
+      reviewPolicy: 'explicit-only',
+    },
+    {
+      id: 'delegation-status',
+      label: 'Delegation status',
+      detail: 'Inspect build-delegation receipts and shared-session status without starting coding work.',
+      effect: 'read-only',
+      command: '/delegate status',
+      workspaceActionId: 'delegation-status',
+      reviewPolicy: 'not-applicable',
+    },
+    {
+      id: 'ordinary-agent-work',
+      label: 'Ordinary Agent work',
+      detail: 'Planning, research, operations, memory, configuration, approvals, automation observability, media generation, and ordinary assistant work stay in the main Agent conversation or first-class Agent tools.',
+      effect: 'main-conversation',
+      reviewPolicy: 'not-applicable',
+    },
+    {
+      id: 'local-coding-blocked',
+      label: 'Local coding execution blocked in Agent',
+      detail: 'Agent does not own file edits, git/worktree workflows, execution isolation UX, coding panels, or local delegated review chains.',
+      effect: 'blocked',
+      reviewPolicy: 'not-applicable',
+    },
+  ];
+}
+
+function routeSearchText(route: DelegationRoute): string {
+  return [
+    route.id,
+    route.label,
+    route.detail,
+    route.effect,
+    route.command ?? '',
+    route.commandTemplate ?? '',
+    route.workspaceActionId ?? '',
+    route.reviewPolicy ?? '',
+  ].join('\n').toLowerCase();
+}
+
+function describeCandidate(route: DelegationRoute): Record<string, unknown> {
+  return {
+    delegationRouteId: route.id,
+    label: route.label,
+    effect: route.effect,
+    confirmationRequired: route.confirmationRequired === true,
+  };
+}
+
+function describeRoute(
+  context: CommandContext,
+  route: DelegationRoute,
+  options: { readonly includeParameters?: boolean; readonly lookup?: Record<string, unknown> } = {},
+): Record<string, unknown> {
+  return {
+    delegationRouteId: route.id,
+    label: route.label,
+    detail: route.detail,
+    effect: route.effect,
+    ...(route.command ? { command: route.command } : {}),
+    ...(route.commandTemplate ? { commandTemplate: route.commandTemplate } : {}),
+    ...(route.workspaceActionId ? { workspaceActionId: route.workspaceActionId } : {}),
+    confirmationRequired: route.confirmationRequired === true,
+    reviewPolicy: route.reviewPolicy ?? 'not-applicable',
+    runtime: {
+      sessionId: context.session.runtime.sessionId,
+      operatorClientAttached: Boolean(context.clients?.operator),
+    },
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    ...(options.includeParameters ? {
+      policy: {
+        effect: route.effect,
+        values: 'Delegation posture returns policy, route, confirmation, and runtime availability metadata only; it does not submit delegated work.',
+        mutation: 'Delegated work submission stays a visible confirmed workspace or slash-command flow and must preserve the full original user ask.',
+      },
+      modelAccess: {
+        inspectDelegation: 'agent_harness mode:"delegation_posture"',
+        inspectRoute: 'agent_harness mode:"delegation_route"',
+        workspaceAction: route.workspaceActionId ? `agent_harness mode:"workspace_action" actionId:"${route.workspaceActionId}"` : null,
+        runWorkspaceAction: route.workspaceActionId ? `agent_harness mode:"run_workspace_action" actionId:"${route.workspaceActionId}" confirm:true explicitUserRequest:"..."` : null,
+        runCommand: route.command ? `agent_harness mode:"run_command" command:"${route.command}" confirm:true explicitUserRequest:"..."` : null,
+        runCommandTemplate: route.commandTemplate ? `agent_harness mode:"run_command" command:"${route.commandTemplate}" confirm:true explicitUserRequest:"..."` : null,
+      },
+    } : {}),
+  };
+}
+
+export function delegationPostureCatalogStatus(context: CommandContext): Record<string, unknown> {
+  return {
+    modes: ['delegation_posture', 'delegation_route'],
+    routes: routes().length,
+    operatorClientAttached: Boolean(context.clients?.operator),
+    readOnly: true,
+  };
+}
+
+export function delegationPostureSummary(context: CommandContext, args: AgentHarnessDelegationArgs): Record<string, unknown> {
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const filtered = routes()
+    .filter((route) => !query || routeSearchText(route).includes(query))
+    .slice(0, readLimit(args.limit, 100));
+  return {
+    status: 'available',
+    summary: {
+      routes: routes().length,
+      operatorClientAttached: Boolean(context.clients?.operator),
+      sessionId: context.session.runtime.sessionId,
+      delegatedReviewPolicy: 'explicit-build-delegation-only',
+      normalChatPolicy: 'ordinary assistant work stays in the main Agent conversation',
+      codingOwnership: 'GoodVibes TUI owns file edits, git/worktree workflows, execution isolation UX, coding panels, and delegated review coordination',
+    },
+    routes: filtered.map((route) => describeRoute(context, route, { includeParameters })),
+    returned: filtered.length,
+    total: routes().length,
+    policy: 'Read-only delegation posture. Delegation submission requires an explicit build/fix/review/implementation user request, visible confirmation, and preservation of the full original ask.',
+  };
+}
+
+export function describeHarnessDelegationRoute(context: CommandContext, args: AgentHarnessDelegationArgs): DelegationResolution {
+  const lookup = lookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'delegation_route requires delegationRouteId, target, or query. Use mode:"delegation_posture" to inspect delegation route ids.',
+    };
+  }
+  const all = routes();
+  const normalized = lookup.input.toLowerCase();
+  const exact = all.find((route) => route.id === lookup.input);
+  if (exact) return { status: 'found', route: describeRoute(context, exact, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = all.find((route) => route.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', route: describeRoute(context, insensitive, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = all.filter((route) => routeSearchText(route).includes(normalized));
+  if (searched.length === 1) return { status: 'found', route: describeRoute(context, searched[0]!, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown delegation route ${lookup.input}. Use mode:"delegation_posture" to inspect delegation route ids.`,
+  };
+}