@pellux/goodvibes-agent 1.1.7 → 1.3.0

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

@@ -0,0 +1,230 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
+import { createAgentHarnessTool } from './agent-harness-tool.ts';
+
+type AgentExecutionAction =
+  | 'status'
+  | 'route'
+  | 'history'
+  | 'record'
+  | 'processes'
+  | 'process_capabilities'
+  | 'process'
+  | 'recovery';
+
+interface AgentExecutionToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly routeId?: unknown;
+  readonly executionRouteId?: unknown;
+  readonly recordId?: unknown;
+  readonly executionRecordId?: unknown;
+  readonly processId?: unknown;
+  readonly processSessionId?: unknown;
+  readonly sessionId?: unknown;
+  readonly session_id?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentExecutionToolDeps {
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly toolRegistry: ToolRegistry;
+  readonly harnessTool?: Tool;
+}
+
+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 normalizeExecutionAction(value: unknown): AgentExecutionAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'overview' || action === 'routes' || action === 'posture' || action === 'execution_posture') return 'status';
+  if (action === 'route' || action === 'show_route' || action === 'inspect_route' || action === 'execution_route') return 'route';
+  if (action === 'history' || action === 'activity' || action === 'records' || action === 'execution_history') return 'history';
+  if (action === 'record' || action === 'item' || action === 'show' || action === 'inspect' || action === 'execution_history_item') return 'record';
+  if (action === 'processes' || action === 'background' || action === 'backgrounds' || action === 'background_processes') return 'processes';
+  if (action === 'capabilities' || action === 'doctor' || action === 'parity' || action === 'process_capabilities' || action === 'process_doctor' || action === 'process_parity') return 'process_capabilities';
+  if (action === 'process' || action === 'background_process') return 'process';
+  if (action === 'recovery' || action === 'file_recovery' || action === 'undo_redo') return 'recovery';
+  return null;
+}
+
+function readAction(args: AgentExecutionToolArgs): AgentExecutionAction | null {
+  const explicit = readString(args.action) || readString(args.mode);
+  if (explicit) return normalizeExecutionAction(explicit);
+  const id = readString(args.id);
+  if (readString(args.processId) || readString(args.processSessionId) || readString(args.sessionId) || readString(args.session_id)) return 'process';
+  if (readString(args.executionRecordId) || readString(args.recordId)) return 'record';
+  if (/^(bg|proc|process|session)[_-]/i.test(id)) return 'process';
+  if (readString(args.executionRouteId) || readString(args.routeId) || id) return 'route';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function routeId(args: AgentExecutionToolArgs): string {
+  return readString(args.executionRouteId) || readString(args.routeId) || readString(args.id);
+}
+
+function recordId(args: AgentExecutionToolArgs): string {
+  return readString(args.executionRecordId) || readString(args.recordId) || readString(args.id);
+}
+
+function processLookup(args: AgentExecutionToolArgs): Record<string, unknown> {
+  const id = readString(args.processId) || readString(args.processSessionId) || readString(args.sessionId) || readString(args.session_id) || readString(args.id);
+  return compactArgs({
+    processId: id,
+    target: id ? undefined : args.target,
+    query: id ? undefined : args.query,
+  });
+}
+
+function statusArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'execution_posture',
+    query: args.query ?? args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function routeArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  const executionRouteId = routeId(args);
+  return compactArgs({
+    mode: 'execution_route',
+    executionRouteId,
+    target: executionRouteId ? undefined : args.target,
+    query: executionRouteId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function historyArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'execution_history',
+    query: args.query ?? args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function recordArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  const executionRecordId = recordId(args);
+  return compactArgs({
+    mode: 'execution_history_item',
+    executionRecordId,
+    target: executionRecordId ? undefined : args.target,
+    query: executionRecordId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function processesArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'background_processes',
+    query: args.query ?? args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function processCapabilitiesArgs(): Record<string, unknown> {
+  return {
+    mode: 'run_background_process',
+    processAction: 'capabilities',
+  };
+}
+
+function processArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'background_process',
+    ...processLookup(args),
+    includeParameters: args.includeParameters,
+  });
+}
+
+function recoveryArgs(args: AgentExecutionToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'file_recovery',
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentExecutionTool(deps: AgentExecutionToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'execution',
+      description: 'Inspect local work routes, history, and recovery.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'route', 'history', 'record', 'processes', 'process_capabilities', 'process', 'recovery', 'capabilities', 'doctor', 'parity'],
+            description: 'Read-only execution posture, route, history, process, or recovery view.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Generic route, record, process, or session id.' },
+          routeId: { type: 'string', description: 'Alias for executionRouteId.' },
+          executionRouteId: { type: 'string', description: 'Execution route id.' },
+          recordId: { type: 'string', description: 'Alias for executionRecordId.' },
+          executionRecordId: { type: 'string', description: 'Execution history record id.' },
+          processId: { type: 'string', description: 'Tracked local background process id.' },
+          processSessionId: { type: 'string', description: 'Tracked process session id alias.' },
+          sessionId: { type: 'string', description: 'Tracked process session id alias.' },
+          session_id: { type: 'string', description: 'Tracked process session id alias.' },
+          target: { type: 'string', description: 'Lookup target or search text.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed route, evidence, and policy metadata.' },
+          limit: { type: 'number', description: 'Maximum rows returned.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentExecutionToolArgs;
+      const action = readAction(args);
+      if (!action) return error('Unknown execution action. Use action:"status" for local route posture or action:"history" for recent work.');
+
+      if (action === 'status') return harnessTool.execute(statusArgs(args));
+      if (action === 'route') return harnessTool.execute(routeArgs(args));
+      if (action === 'history') return harnessTool.execute(historyArgs(args));
+      if (action === 'record') return harnessTool.execute(recordArgs(args));
+      if (action === 'processes') return harnessTool.execute(processesArgs(args));
+      if (action === 'process_capabilities') return harnessTool.execute(processCapabilitiesArgs());
+      if (action === 'process') return harnessTool.execute(processArgs(args));
+      if (action === 'recovery') return harnessTool.execute(recoveryArgs(args));
+
+      return error('Unknown execution action. Use action:"status" for local route posture or action:"history" for recent work.');
+    },
+  };
+}
+
+export function registerAgentExecutionTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('execution')) registry.register(createAgentExecutionTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

package/src/tools/agent-harness-agent-orchestration-policy.ts

@@ -0,0 +1,75 @@
+export const AGENT_TOOL_MODES = [
+  'spawn',
+  'batch-spawn',
+  'list',
+  'templates',
+  'status',
+  'get',
+  'budget',
+  'plan',
+  'wait',
+  'message',
+  'cancel',
+  'wrfc-chains',
+  'wrfc-history',
+  'cohort-status',
+  'cohort-report',
+] as const;
+
+export const AGENT_TEMPLATES = ['orchestrator', 'engineer', 'reviewer', 'tester', 'researcher', 'integrator', 'general'] as const;
+
+export function agentOrchestrationDecisionCards(agentToolAvailable: boolean): readonly Record<string, unknown>[] {
+  return [
+    {
+      id: 'serial-by-default',
+      label: 'Stay serial by default',
+      status: 'ready',
+      chooseWhen: ['Ordinary chat, planning, research, setup, local context, and short current-workspace tool work.'],
+      route: 'main conversation',
+      reason: 'Lowest-friction route for the user when parallelism does not improve outcome.',
+    },
+    {
+      id: 'visible-single-agent',
+      label: 'Spawn one visible agent',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['A bounded autonomous task can run independently with visible status and cancellation.'],
+      requiredFields: ['task', 'successCriteria or requiredEvidence when outcome quality matters'],
+      modelRoute: 'agent { mode: "spawn" }',
+      inspectRoute: 'agent_harness mode:"agent_orchestration"',
+    },
+    {
+      id: 'visible-batch-spawn',
+      label: 'Batch-spawn independent agents',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['Tasks are genuinely independent and parallel work materially improves time-to-result.'],
+      doNotUseWhen: ['Review/test/verification role fanout for one deliverable; that collapses to one owner chain.'],
+      requiredFields: ['tasks[]', 'authoritativeTask for the original user ask when applicable'],
+      modelRoute: 'agent { mode: "batch-spawn" }',
+      inspectRoute: 'agent_harness mode:"agent_orchestration"',
+    },
+    {
+      id: 'managed-multi-runner-plan',
+      label: 'Use a managed multi-runner plan',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['A large task already has approval for parallel work and needs milestones, evidence, and cancellation routes.'],
+      requiredFields: ['original user ask', 'lane reason', 'success criteria', 'per-runner evidence', 'cancel/recovery route'],
+      modelRoute: 'agent_work_plan action:"dispatch_agents" ids:["..."] confirm:true explicitUserRequest:"..."',
+      inspectRoute: 'agent_harness mode:"agent_orchestration"',
+      policy: 'Read-only plan surface first; approved work-plan dispatch, spawn, message, wait, cancel, or remote mutation stays on confirmed first-class routes.',
+    },
+    {
+      id: 'inspect-or-control-visible-agent',
+      label: 'Inspect or control a visible agent',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['The user asks for progress, budget, plan, message, wait, cancel, WRFC chain, or cohort status.'],
+      modelRoutes: ['agent { mode: "list" }', 'agent { mode: "get" }', 'agent { mode: "message" }', 'agent { mode: "wait" }', 'agent { mode: "cancel" }'],
+    },
+    {
+      id: 'hidden-fanout-blocked',
+      label: 'Block hidden fanout',
+      status: 'blocked',
+      chooseWhen: ['A request implies invisible background agents, unmanaged parallel coding workers, or orphaned jobs.'],
+      saferRoutes: ['visible work plan', 'research run', 'confirmed schedule', 'agent { mode: "spawn" }', 'delegation action:"status"'],
+    },
+  ];
+}