@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-terminal-process-tools.ts

@@ -0,0 +1,167 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext } from '../input/command-registry.ts';
+import { backgroundProcessSummary, describeBackgroundProcess, runBackgroundProcessAction } from './agent-harness-background-processes.ts';
+
+const READ_ONLY_PROCESS_ACTIONS = new Set(['list', 'status', 'poll', 'log', 'output', 'capabilities', 'doctor', 'parity']);
+
+interface AgentTerminalToolArgs {
+  readonly command?: unknown;
+  readonly background?: unknown;
+  readonly cwd?: unknown;
+  readonly timeoutMs?: unknown;
+  readonly pty?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+interface AgentProcessToolArgs {
+  readonly action?: unknown;
+  readonly processAction?: unknown;
+  readonly processId?: unknown;
+  readonly processSessionId?: unknown;
+  readonly sessionId?: unknown;
+  readonly session_id?: unknown;
+  readonly command?: unknown;
+  readonly cwd?: unknown;
+  readonly timeoutMs?: unknown;
+  readonly pty?: unknown;
+  readonly data?: unknown;
+  readonly query?: unknown;
+  readonly target?: unknown;
+  readonly limit?: unknown;
+  readonly includeParameters?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+function output(value: unknown): { readonly success: true; readonly output: string } {
+  return {
+    success: true,
+    output: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+  };
+}
+
+function error(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || (typeof value === 'string' && value.trim().toLowerCase() === 'true');
+}
+
+function readProcessAction(args: AgentProcessToolArgs): string {
+  const action = readString(args.action) || readString(args.processAction);
+  if (action) return action.toLowerCase();
+  return readString(args.command) ? 'start' : 'list';
+}
+
+function isReadOnlyProcessAction(action: string): boolean {
+  return READ_ONLY_PROCESS_ACTIONS.has(action);
+}
+
+export function createAgentTerminalTool(commandContext: CommandContext): Tool {
+  return {
+    definition: {
+      name: 'terminal',
+      description: 'Start visible tracked background shell commands.',
+      parameters: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: 'Shell command to start via the shared ProcessManager.' },
+          background: { type: 'boolean', description: 'Must be true. Foreground shell uses exec.' },
+          cwd: { type: 'string', description: 'Workspace-relative or absolute working directory.' },
+          timeoutMs: { type: 'number', description: 'Background process timeout in milliseconds.' },
+          pty: { type: 'boolean', description: 'Request PTY mode; returns unsupported until the SDK publishes a typed PTY contract.' },
+          confirm: { type: 'boolean', description: 'Required true for starting a process.' },
+          explicitUserRequest: { type: 'string', description: 'The user request authorizing the background command.' },
+        },
+        required: ['command', 'background'],
+        additionalProperties: false,
+      },
+      sideEffects: ['exec'],
+      concurrency: 'serial',
+      supportsProgress: true,
+      supportsStreamingOutput: true,
+    },
+    execute: async (args: Record<string, unknown>) => {
+      const input = args as AgentTerminalToolArgs;
+      if (!readBoolean(input.background)) {
+        return error('terminal is the tracked-background adapter. Use exec for bounded foreground shell commands, or call terminal with background:true, confirm:true, and explicitUserRequest.');
+      }
+      return output(await runBackgroundProcessAction(commandContext, {
+        ...input,
+        processAction: 'start',
+      }));
+    },
+  };
+}
+
+export function createAgentProcessTool(commandContext: CommandContext): Tool {
+  return {
+    definition: {
+      name: 'process',
+      description: 'List, poll, log, wait, stop tracked processes.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['list', 'poll', 'status', 'wait', 'log', 'output', 'kill', 'stop', 'cancel', 'write', 'start', 'capabilities', 'doctor', 'parity'],
+            description: 'Process lifecycle action. list/poll/log are read-only; wait/kill/write/start require confirmation.',
+          },
+          processAction: { type: 'string', description: 'Alias for action.' },
+          processId: { type: 'string', description: 'Tracked background process id.' },
+          processSessionId: { type: 'string', description: 'Process session id alias.' },
+          sessionId: { type: 'string', description: 'Process session id alias.' },
+          session_id: { type: 'string', description: 'Process session id alias.' },
+          command: { type: 'string', description: 'Shell command for action:start.' },
+          cwd: { type: 'string', description: 'Working directory for action:start.' },
+          timeoutMs: { type: 'number', description: 'Wait or background timeout in milliseconds.' },
+          pty: { type: 'boolean', description: 'Request PTY mode; reports unsupported until a typed contract exists.' },
+          data: { type: 'string', description: 'Input data for confirmed action:write when supported by the SDK.' },
+          query: { type: 'string', description: 'Search text for list or process lookup.' },
+          target: { type: 'string', description: 'Process lookup text.' },
+          limit: { type: 'number', description: 'Maximum list rows.' },
+          includeParameters: { type: 'boolean', description: 'Include full bounded command/output metadata.' },
+          confirm: { type: 'boolean', description: 'Required true for wait/kill/write/start.' },
+          explicitUserRequest: { type: 'string', description: 'The user request authorizing side-effecting process actions.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['exec'],
+      concurrency: 'serial',
+      supportsProgress: true,
+      supportsStreamingOutput: true,
+    },
+    execute: async (args: Record<string, unknown>) => {
+      const input = args as AgentProcessToolArgs;
+      const action = readProcessAction(input);
+
+      if (action === 'list') return output(backgroundProcessSummary(commandContext, input));
+      if (isReadOnlyProcessAction(action) && action !== 'capabilities' && action !== 'doctor' && action !== 'parity') {
+        const resolved = describeBackgroundProcess(commandContext, {
+          ...input,
+          processAction: action,
+        });
+        if (resolved.status === 'found') return output(resolved.process);
+        if (resolved.status === 'ambiguous') return error(`Ambiguous process ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+        return error(resolved.usage);
+      }
+
+      return output(await runBackgroundProcessAction(commandContext, {
+        ...input,
+        processAction: action,
+      }));
+    },
+  };
+}
+
+export function registerAgentTerminalProcessTools(registry: ToolRegistry, commandContext: CommandContext): void {
+  if (!registry.has('terminal')) registry.register(createAgentTerminalTool(commandContext));
+  if (!registry.has('process')) registry.register(createAgentProcessTool(commandContext));
+}

package/src/tools/agent-tool-policy-guard-types.ts

@@ -0,0 +1,77 @@
+export type AgentToolArgs = {
+  readonly mode?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type ExecCommandArgs = {
+  readonly cmd?: unknown;
+  readonly background?: unknown;
+  readonly until?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type ExecToolArgs = {
+  readonly commands?: unknown;
+  readonly parallel?: unknown;
+  readonly file_ops?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type ModeToolArgs = {
+  readonly mode?: unknown;
+  readonly createIfMissing?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type FetchToolArgs = {
+  readonly urls?: unknown;
+  readonly parallel?: unknown;
+  readonly sanitize_mode?: unknown;
+  readonly trusted_hosts?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type StateToolArgs = {
+  readonly mode?: unknown;
+  readonly memoryAction?: unknown;
+  readonly hookAction?: unknown;
+  readonly modeAction?: unknown;
+  readonly analyticsAction?: unknown;
+  readonly values?: unknown;
+  readonly clearKeys?: unknown;
+  readonly memoryValue?: unknown;
+  readonly hookDefinition?: unknown;
+  readonly modeName?: unknown;
+  readonly analyticsTool?: unknown;
+  readonly analyticsArgs?: unknown;
+  readonly analyticsResult?: unknown;
+  readonly analyticsDuration?: unknown;
+  readonly analyticsTokens?: unknown;
+  readonly analyticsFormat?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type InspectToolArgs = {
+  readonly mode?: unknown;
+  readonly dryRun?: unknown;
+  readonly [key: string]: unknown;
+};
+
+export type AgentToolPolicyGuardOptions = {
+  readonly getLastUserMessage?: () => string | null;
+};
+
+export type ModeRestrictedToolPolicy = {
+  readonly allowedModes: readonly string[];
+  readonly modeSet: ReadonlySet<string>;
+  readonly description: string;
+  readonly denial: string;
+  readonly removedProperties?: readonly string[];
+};
+
+export interface AgentToolPolicyInvocationExplanation {
+  readonly status: 'allowed' | 'denied';
+  readonly layer: 'agent_tool_policy';
+  readonly reason: string;
+  readonly allowedModes?: readonly string[];
+}

package/src/tools/agent-tool-policy-guard.ts

@@ -10,79 +10,37 @@ import {
 import { wrapFindToolForAgentPolicy } from './agent-find-policy.ts';
 import { wrapReadToolForAgentPolicy } from './agent-read-policy.ts';
 import { wrapWebSearchToolForAgentPolicy } from './agent-web-search-policy.ts';
-
-type AgentToolArgs = {
-  readonly mode?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type ExecCommandArgs = {
-  readonly cmd?: unknown;
-  readonly background?: unknown;
-  readonly until?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type ExecToolArgs = {
-  readonly commands?: unknown;
-  readonly parallel?: unknown;
-  readonly file_ops?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type ModeToolArgs = {
-  readonly mode?: unknown;
-  readonly createIfMissing?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type FetchToolArgs = {
-  readonly urls?: unknown;
-  readonly parallel?: unknown;
-  readonly sanitize_mode?: unknown;
-  readonly trusted_hosts?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type StateToolArgs = {
-  readonly mode?: unknown;
-  readonly memoryAction?: unknown;
-  readonly hookAction?: unknown;
-  readonly modeAction?: unknown;
-  readonly analyticsAction?: unknown;
-  readonly values?: unknown;
-  readonly clearKeys?: unknown;
-  readonly memoryValue?: unknown;
-  readonly hookDefinition?: unknown;
-  readonly modeName?: unknown;
-  readonly analyticsTool?: unknown;
-  readonly analyticsArgs?: unknown;
-  readonly analyticsResult?: unknown;
-  readonly analyticsDuration?: unknown;
-  readonly analyticsTokens?: unknown;
-  readonly analyticsFormat?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type InspectToolArgs = {
-  readonly mode?: unknown;
-  readonly dryRun?: unknown;
-  readonly [key: string]: unknown;
-};
-
-type AgentToolPolicyGuardOptions = {
-  readonly getLastUserMessage?: () => string | null;
-};
-
-const BLOCKED_MAIN_CONVERSATION_TOOL_NAMES = ['write', 'edit', 'workflow', 'repl'] as const;
-const AGENT_EXEC_BACKGROUND_COMMAND = /^\s*bg_(?:status|output|stop)\b/;
+import type {
+  AgentToolArgs,
+  AgentToolPolicyGuardOptions,
+  AgentToolPolicyInvocationExplanation,
+  ExecCommandArgs,
+  ExecToolArgs,
+  FetchToolArgs,
+  InspectToolArgs,
+  ModeRestrictedToolPolicy,
+  ModeToolArgs,
+  StateToolArgs,
+} from './agent-tool-policy-guard-types.ts';
+export type { AgentToolPolicyInvocationExplanation } from './agent-tool-policy-guard-types.ts';
+
+const BLOCKED_MAIN_CONVERSATION_TOOL_NAMES = [] as const;
+const AGENT_EXEC_BACKGROUND_COMMAND = /^\s*bg_(?:list|status|output|stop)\b/;
 
 const READ_ONLY_AGENT_TOOL_MODES = [
+  'spawn',
+  'batch-spawn',
   'status',
+  'cancel',
   'list',
   'templates',
   'get',
   'budget',
+  'plan',
+  'wait',
+  'message',
+  'wrfc-chains',
+  'wrfc-history',
   'cohort-status',
   'cohort-report',
 ] as const;
@@ -122,21 +80,19 @@ const READ_ONLY_QUERY_TOOL_MODE_SET = new Set<string>(READ_ONLY_QUERY_TOOL_MODES
 const READ_ONLY_CONTROL_TOOL_MODE_SET = new Set<string>(READ_ONLY_CONTROL_TOOL_MODES);
 
 const LOCAL_AGENT_DENIAL = [
-  'GoodVibes Agent does not create coding-role Agent jobs or run local delegated review chains.',
-  'Keep ordinary assistant work serial in the main conversation.',
-  'For explicit build/fix/review work, delegate one request to GoodVibes TUI through the public shared-session/build-delegation contract with the full original user ask.',
+  'GoodVibes Agent creates only visible, tracked Agent jobs.',
+  'Use a known agent mode and keep spawned work tied to the user request, visible status, and cancellable follow-up.',
 ].join(' ');
 
 const LOCAL_CODING_TOOL_DENIAL = [
-  'GoodVibes Agent does not perform direct local file mutation, local delegated review workflow execution, or local execution-isolation work from the main conversation.',
-  'For explicit build/fix/review/code execution work, delegate one request to GoodVibes TUI through the public shared-session/build-delegation contract with the full original user ask.',
-  'For durable Agent memory, skills, personas, routines, and knowledge, use the Agent-owned commands and isolated Agent Knowledge routes.',
+  'This tool is not exposed directly in GoodVibes Agent.',
+  'Use a first-class visible Agent tool or a confirmed GoodVibes daemon operator method for the requested workflow.',
 ].join(' ');
 
 const BACKGROUND_EXEC_DENIAL = [
   'GoodVibes Agent only runs foreground, serial command-line work from the main conversation.',
-  'Background processes, parallel command batches, background process controls, and exec pre-command file operations are disabled here.',
-  'For long-running build/fix/review work, delegate one request to GoodVibes TUI through the public shared-session/build-delegation contract.',
+  'Raw exec background flags, parallel command batches, bg_* controls, and exec pre-command file operations are disabled here.',
+  'For user-approved long-running local commands, use execution action:"processes", terminal background:true, and process lifecycle actions. Delegate only when isolation, remote execution, or parallel work is the user benefit.',
 ].join(' ');
 
 const REMOTE_MUTATION_DENIAL = [
@@ -460,14 +416,6 @@ export function normalizeInspectToolInvocationForAgentPolicy(args: InspectToolAr
   return { ...args, dryRun: true };
 }
 
-type ModeRestrictedToolPolicy = {
-  readonly allowedModes: readonly string[];
-  readonly modeSet: ReadonlySet<string>;
-  readonly description: string;
-  readonly denial: string;
-  readonly removedProperties?: readonly string[];
-};
-
 export function wrapModeRestrictedToolForAgentPolicy(tool: Tool, policy: ModeRestrictedToolPolicy): void {
   narrowModeToolDefinitionForAgentPolicy(tool, policy.allowedModes, policy.description);
   if (policy.removedProperties) removeToolDefinitionProperties(tool, policy.removedProperties);
@@ -507,6 +455,80 @@ export function validateChannelToolInvocationForAgentPolicy(args: ModeToolArgs):
   return null;
 }
 
+function allowedByAgentPolicy(reason: string, allowedModes?: readonly string[]): AgentToolPolicyInvocationExplanation {
+  return {
+    status: 'allowed',
+    layer: 'agent_tool_policy',
+    reason,
+    ...(allowedModes ? { allowedModes } : {}),
+  };
+}
+
+function deniedByAgentPolicy(reason: string, allowedModes?: readonly string[]): AgentToolPolicyInvocationExplanation {
+  return {
+    status: 'denied',
+    layer: 'agent_tool_policy',
+    reason,
+    ...(allowedModes ? { allowedModes } : {}),
+  };
+}
+
+function explainModeRestrictedAgentPolicy(
+  args: ModeToolArgs,
+  allowedModes: readonly string[],
+  modeSet: ReadonlySet<string>,
+  denial: string,
+): AgentToolPolicyInvocationExplanation {
+  const denied = validateModeRestrictedToolInvocationForAgentPolicy(args, modeSet, denial);
+  if (denied) return deniedByAgentPolicy(denied, allowedModes);
+  const mode = typeof args.mode === 'string' && args.mode.trim() ? args.mode.trim() : '(default)';
+  return allowedByAgentPolicy(`Agent policy allows ${mode} for read-only inspection on this tool.`, allowedModes);
+}
+
+export function explainAgentToolPolicyInvocation(
+  toolName: string,
+  args: Record<string, unknown> = {},
+): AgentToolPolicyInvocationExplanation {
+  if (BLOCKED_MAIN_CONVERSATION_TOOL_NAME_SET.has(toolName)) return deniedByAgentPolicy(LOCAL_CODING_TOOL_DENIAL);
+  if (toolName === 'agent') {
+    const denied = validateAgentToolInvocationForAgentPolicy(args as AgentToolArgs);
+    return denied ? deniedByAgentPolicy(denied, READ_ONLY_AGENT_TOOL_MODES) : allowedByAgentPolicy('Agent policy allows visible tracked Agent modes.', READ_ONLY_AGENT_TOOL_MODES);
+  }
+  if (toolName === 'exec') {
+    const denied = validateExecToolInvocationForAgentPolicy(args as ExecToolArgs);
+    return denied ? deniedByAgentPolicy(denied) : allowedByAgentPolicy('Agent policy allows foreground serial shell execution.');
+  }
+  if (toolName === 'remote') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_REMOTE_TOOL_MODES, READ_ONLY_REMOTE_TOOL_MODE_SET, REMOTE_MUTATION_DENIAL);
+  if (toolName === 'channel') {
+    const modeDenied = validateModeRestrictedToolInvocationForAgentPolicy(args as ModeToolArgs, READ_ONLY_CHANNEL_TOOL_MODE_SET, CHANNEL_ACTION_DENIAL);
+    const channelDenied = modeDenied ?? validateChannelToolInvocationForAgentPolicy(args as ModeToolArgs);
+    return channelDenied
+      ? deniedByAgentPolicy(channelDenied, READ_ONLY_CHANNEL_TOOL_MODES)
+      : allowedByAgentPolicy('Agent policy allows read-only channel inspection.', READ_ONLY_CHANNEL_TOOL_MODES);
+  }
+  if (toolName === 'mcp') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_MCP_TOOL_MODES, READ_ONLY_MCP_TOOL_MODE_SET, MCP_SECURITY_MUTATION_DENIAL);
+  if (toolName === 'fetch') {
+    const denied = validateFetchToolInvocationForAgentPolicy(args as FetchToolArgs);
+    return denied ? deniedByAgentPolicy(denied, READ_ONLY_FETCH_METHODS) : allowedByAgentPolicy('Agent policy allows serial sanitized read-only HTTP fetches.', READ_ONLY_FETCH_METHODS);
+  }
+  if (toolName === 'state') {
+    const denied = validateStateToolInvocationForAgentPolicy(args as StateToolArgs);
+    return denied ? deniedByAgentPolicy(denied, READ_ONLY_STATE_TOOL_MODES) : allowedByAgentPolicy('Agent policy allows read-only runtime state inspection.', READ_ONLY_STATE_TOOL_MODES);
+  }
+  if (toolName === 'goodvibes_settings') return deniedByAgentPolicy(SETTINGS_MUTATION_DENIAL);
+  if (toolName === 'inspect') {
+    const denied = validateInspectToolInvocationForAgentPolicy(args as InspectToolArgs);
+    return denied ? deniedByAgentPolicy(denied) : allowedByAgentPolicy('Agent policy allows inspection and dry-run scaffolding only.');
+  }
+  if (toolName === 'control') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_CONTROL_TOOL_MODES, READ_ONLY_CONTROL_TOOL_MODE_SET, CONTROL_MUTATION_DENIAL);
+  if (toolName === 'task') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_TASK_TOOL_MODES, READ_ONLY_TASK_TOOL_MODE_SET, DURABLE_WORKFLOW_MUTATION_DENIAL);
+  if (toolName === 'team') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_TEAM_TOOL_MODES, READ_ONLY_TEAM_TOOL_MODE_SET, DURABLE_WORKFLOW_MUTATION_DENIAL);
+  if (toolName === 'worklist') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_WORKLIST_TOOL_MODES, READ_ONLY_WORKLIST_TOOL_MODE_SET, DURABLE_WORKFLOW_MUTATION_DENIAL);
+  if (toolName === 'packet') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_PACKET_TOOL_MODES, READ_ONLY_PACKET_TOOL_MODE_SET, DURABLE_WORKFLOW_MUTATION_DENIAL);
+  if (toolName === 'query') return explainModeRestrictedAgentPolicy(args as ModeToolArgs, READ_ONLY_QUERY_TOOL_MODES, READ_ONLY_QUERY_TOOL_MODE_SET, DURABLE_WORKFLOW_MUTATION_DENIAL);
+  return allowedByAgentPolicy('No Agent-specific route guard blocks this invocation.');
+}
+
 export const AGENT_LOCAL_SPAWN_DENIAL_MESSAGE = LOCAL_AGENT_DENIAL;
 export const AGENT_READ_ONLY_TOOL_MODES = READ_ONLY_AGENT_TOOL_MODES;
 export const AGENT_BLOCKED_MAIN_CONVERSATION_TOOL_NAMES = BLOCKED_MAIN_CONVERSATION_TOOL_NAMES;
@@ -595,15 +617,14 @@ function isPresent(value: unknown): boolean {
 }
 
 function narrowAgentToolDefinitionForAgentPolicy(tool: Tool): void {
-  tool.definition.description = 'Read-only local Agent inspection for GoodVibes Agent.';
-  tool.definition.sideEffects = [];
+  tool.definition.description = 'Visible local Agent orchestration for GoodVibes Agent: spawn, inspect, message, wait, cancel, and report tracked autonomous work.';
 
   const properties = tool.definition.parameters.properties;
   if (!isRecord(properties)) return;
   const modeProperty = properties.mode;
   if (!isRecord(modeProperty)) return;
   modeProperty.enum = [...READ_ONLY_AGENT_TOOL_MODES];
-  modeProperty.description = 'Read-only Agent inspection mode. Separate Agent job creation, batch creation, cancel, message, wait, and plan modes are disabled in GoodVibes Agent.';
+  modeProperty.description = 'Agent orchestration mode. Spawned work is visible, tracked, and cancellable.';
 }
 
 function narrowExecToolDefinitionForAgentPolicy(tool: Tool): void {