@pellux/goodvibes-agent 1.1.6 → 1.2.0

package/src/tools/agent-route-planner.ts

@@ -0,0 +1,185 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import { listHarnessModes } from './agent-harness-mode-catalog.ts';
+import { listWorkspaceActions } from './agent-harness-workspace-actions.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+import { addSetupModelContextRouteCandidates } from './agent-route-planner-candidates-setup.ts';
+import { addResearchScheduleExecutionRouteCandidates } from './agent-route-planner-candidates-work.ts';
+import { addSurfaceSecurityRouteCandidates } from './agent-route-planner-candidates-surfaces.ts';
+import { autonomousLike, browserCockpitLike, browserControlLike, channelDeliveriesLike, channelSendLike, channelSetupLike, channelTargetFromText, channelTriageLike, directScheduleLike, externalChannelLike, externalMemoryProviderId, externalMemoryProviderLike, fileRecoveryLike, hasAll, hasAny, hostDiagnosticsLike, interactiveProcessCapabilityLike, localModelLike, localModelSmokeLike, mediaGenerationLike, modelProviderId, modelRouteReadinessLike, personalOpsBriefingLike, personalOpsConnectorSetupLike, personalOpsFreshReadLike, personalOpsLaneFromText, personalOpsLike, personalOpsMutationLike, personalOpsQueueLike, processLifecycleLike, providerAccountLike, quote, releaseAuditLike, releaseEvidenceLike, researchRunnerLike, scheduleLike, securityFindingLike, securityPermissionLike, securityPolicyExplainLike, securityPolicyToolTarget, securityStatusLike, sessionMutationLike, sessionWorkspaceLike, simplifiedModeQuery, supportBundleEffectLike, supportBundleLike, ttsProviderLike, visualResearchReportLike, voiceWorkflowLike } from './agent-route-planner-helpers.ts';
+
+export interface AgentRoutePlannerArgs {
+  readonly query?: unknown;
+  readonly target?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+export interface RouteCandidateDraft {
+  readonly id: string;
+  readonly label: string;
+  readonly score: number;
+  readonly userSurface: string;
+  readonly userOutcome: string;
+  readonly why: string;
+  readonly modelRoute: string;
+  readonly inspectRoute: string;
+  readonly userRoute?: string;
+  readonly requiresConfirmation: boolean;
+  readonly missingFields?: readonly string[];
+  readonly nextQuestion?: string;
+  readonly supportingRoutes?: readonly string[];
+  readonly policy?: string;
+}
+
+export interface AgentRouteCandidate {
+  readonly id: string;
+  readonly label: string;
+  readonly confidence: 'high' | 'medium' | 'low';
+  readonly userSurface: string;
+  readonly userOutcome: string;
+  readonly why: string;
+  readonly modelRoute: string;
+  readonly inspectRoute: string;
+  readonly userRoute?: string;
+  readonly requiresConfirmation: boolean;
+  readonly missingFields?: readonly string[];
+  readonly nextQuestion?: string;
+  readonly supportingRoutes?: readonly string[];
+  readonly policy?: string;
+  readonly score?: number;
+}
+
+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(20, Math.trunc(parsed)));
+}
+
+function buildCandidates(request: string): readonly RouteCandidateDraft[] {
+  const lower = request.toLowerCase();
+  const candidates: RouteCandidateDraft[] = [];
+
+  const add = (candidate: RouteCandidateDraft): void => {
+    candidates.push(candidate);
+  };
+
+  addSetupModelContextRouteCandidates(lower, request, add);
+
+  addResearchScheduleExecutionRouteCandidates(lower, request, add);
+
+  addSurfaceSecurityRouteCandidates(lower, request, add);
+
+  if (candidates.length === 0) {
+    add({
+      id: 'main-conversation-first',
+      label: 'Main conversation first',
+      score: 35,
+      userSurface: 'Main conversation',
+      userOutcome: 'Answer or plan directly before escalating into a specialized tool or workspace.',
+      why: 'The request does not clearly need a specialized route yet.',
+      modelRoute: 'main conversation',
+      inspectRoute: `workspace action:"actions" query:${quote(request, 72)}`,
+      userRoute: 'Main conversation',
+      requiresConfirmation: false,
+      supportingRoutes: [
+        `route action:"plan" query:${quote(request, 72)}`,
+        `workspace action:"actions" query:${quote(request, 72)}`,
+      ],
+      policy: 'Stay in the main conversation unless a visible specialized route improves clarity, durability, safety, or autonomy.',
+    });
+  }
+
+  return candidates;
+}
+
+function confidence(score: number): AgentRouteCandidate['confidence'] {
+  if (score >= 80) return 'high';
+  if (score >= 50) return 'medium';
+  return 'low';
+}
+
+function describeCandidate(candidate: RouteCandidateDraft, includeParameters: boolean): AgentRouteCandidate {
+  return {
+    id: candidate.id,
+    label: candidate.label,
+    confidence: confidence(candidate.score),
+    userSurface: candidate.userSurface,
+    userOutcome: candidate.userOutcome,
+    why: candidate.why,
+    modelRoute: candidate.modelRoute,
+    inspectRoute: candidate.inspectRoute,
+    ...(candidate.userRoute ? { userRoute: candidate.userRoute } : {}),
+    requiresConfirmation: candidate.requiresConfirmation,
+    ...(candidate.missingFields?.length ? { missingFields: candidate.missingFields } : {}),
+    ...(candidate.nextQuestion ? { nextQuestion: candidate.nextQuestion } : {}),
+    ...(candidate.supportingRoutes?.length ? { supportingRoutes: candidate.supportingRoutes } : {}),
+    ...(candidate.policy ? { policy: candidate.policy } : {}),
+    ...(includeParameters ? { score: candidate.score } : {}),
+  };
+}
+
+function workspaceMatches(context: CommandContext, request: string, limit: number): readonly Record<string, unknown>[] {
+  try {
+    return listWorkspaceActions(context, { query: request, limit }).slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
+function modeMatches(request: string, limit: number): readonly Record<string, unknown>[] {
+  try {
+    const result = listHarnessModes({ query: request, limit }) as { readonly modes?: readonly Record<string, unknown>[] };
+    const matches = result.modes?.slice(0, limit) ?? [];
+    if (matches.length > 0) return matches;
+    const simplified = simplifiedModeQuery(request);
+    if (!simplified || simplified === request.toLowerCase()) return [];
+    const fallback = listHarnessModes({ query: simplified, limit }) as { readonly modes?: readonly Record<string, unknown>[] };
+    return fallback.modes?.slice(0, limit) ?? [];
+  } catch {
+    return [];
+  }
+}
+
+export function planAgentTaskRoute(context: CommandContext, args: AgentRoutePlannerArgs): Record<string, unknown> {
+  const request = readString(args.query) || readString(args.target);
+  if (!request) {
+    return {
+      status: 'missing_request',
+      usage: 'Use route action:"plan" query:"<user task>" to get the preferred GoodVibes Agent route, alternatives, missing fields, and confirmation boundary.',
+      examples: [
+        'Fix the failing tests in this repo.',
+        'Triage my inbox and draft replies.',
+        'Run a weekly source-backed research report.',
+        'Why would settings action:set need confirmation?',
+      ],
+      policy: 'Route planning is read-only. It never runs tools, creates jobs, sends messages, changes settings, or opens UI surfaces.',
+    };
+  }
+
+  const includeParameters = args.includeParameters === true;
+  const limit = readLimit(args.limit, includeParameters ? 8 : 5);
+  const candidates = [...buildCandidates(request)]
+    .sort((left, right) => right.score - left.score)
+    .slice(0, limit)
+    .map((candidate) => describeCandidate(candidate, includeParameters));
+  const preferred = candidates[0]!;
+  const workspaceActionMatches = workspaceMatches(context, request, includeParameters ? 6 : 3);
+  const modes = modeMatches(request, includeParameters ? 6 : 3);
+
+  return {
+    status: 'ready',
+    request: previewHarnessText(request, includeParameters ? 220 : 120),
+    preferred,
+    alternatives: candidates.slice(1),
+    nextAction: preferred.requiresConfirmation
+      ? 'Inspect the preferred route, collect missing fields, then run the returned confirmed route only after the user explicitly asks for that effect.'
+      : 'Use the preferred read-only route first; only move to a confirmed route if the returned plan asks for one and the user requested the effect.',
+    workspaceMatches: workspaceActionMatches,
+    harnessModeMatches: modes,
+    policy: 'GoodVibes Agent routes by user outcome. Package, daemon, TUI, SDK, and host ownership are diagnostic details; the model should choose the visible route that is easiest and safest for the user.',
+  };
+}

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

@@ -0,0 +1,105 @@
+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 { planAgentTaskRoute } from './agent-route-planner.ts';
+
+type AgentRouteAction = 'plan' | 'status';
+
+interface AgentRouteToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly query?: unknown;
+  readonly target?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeRouteAction(value: unknown): AgentRouteAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'plan' || action === 'route' || action === 'decide' || action === 'decision' || action === 'task' || action === 'intake') return 'plan';
+  if (action === 'status' || action === 'summary' || action === 'help' || action === 'usage') return 'status';
+  return null;
+}
+
+function readAction(args: AgentRouteToolArgs): AgentRouteAction {
+  const explicit = normalizeRouteAction(args.action) ?? normalizeRouteAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.query) || readString(args.target)) return 'plan';
+  return 'status';
+}
+
+function output(value: unknown): { readonly success: true; readonly output: string } {
+  return {
+    success: true,
+    output: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+  };
+}
+
+function status(): Record<string, unknown> {
+  return {
+    status: 'ready',
+    usage: 'Use route action:"plan" query:"<user task>" before choosing a specialized GoodVibes Agent surface.',
+    actions: ['plan', 'status'],
+    examples: [
+      'route action:"plan" query:"fix the failing tests"',
+      'route action:"plan" query:"check daemon health"',
+      'route action:"plan" query:"change the theme setting"',
+      'route action:"plan" query:"remind me tomorrow to stretch"',
+      'route action:"plan" query:"run pytest in background"',
+      'route action:"plan" query:"run claude code with pty and sudo"',
+      'route action:"plan" query:"undo the last file edit"',
+      'route action:"plan" query:"show current permissions"',
+      'route action:"plan" query:"why was that tool call blocked"',
+      'route action:"plan" query:"export a support bundle"',
+      'route action:"plan" query:"search saved sessions"',
+      'route action:"plan" query:"show release readiness evidence"',
+      'route action:"plan" query:"generate an image of a product dashboard"',
+      'route action:"plan" query:"take a screenshot of the browser dashboard"',
+      'route action:"plan" query:"triage my inbox and draft replies"',
+      'route action:"plan" query:"run a weekly source-backed research report"',
+    ],
+    policy: 'Route is read-only. It selects visible user-first routes and missing fields but never runs tools, creates jobs, sends messages, changes settings, or opens UI surfaces.',
+  };
+}
+
+export function createAgentRouteTool(commandContext: CommandContext): Tool {
+  return {
+    definition: {
+      name: 'route',
+      description: 'Choose the best visible route for a user task.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['plan', 'status'],
+            description: 'Plan a user-task route or show route-tool usage.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          query: { type: 'string', description: 'Plain user request to route.' },
+          target: { type: 'string', description: 'Alias for query.' },
+          includeParameters: { type: 'boolean', description: 'Include scoring and more catalog matches.' },
+          limit: { type: 'number', description: 'Maximum candidate routes returned.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentRouteToolArgs;
+      const action = readAction(args);
+      if (action === 'status') return output(status());
+      return output(planAgentTaskRoute(commandContext, args));
+    },
+  };
+}
+
+export function registerAgentRouteTool(registry: ToolRegistry, commandContext: CommandContext): void {
+  if (!registry.has('route')) registry.register(createAgentRouteTool(commandContext));
+}

package/src/tools/agent-schedule-edit-tool.ts

@@ -0,0 +1,210 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { ShellPathService } from '@/runtime/index.ts';
+import {
+  buildScheduleEditPreview,
+  editConnectedSchedule,
+  enrichScheduleEditPreviewFromConnectedHost,
+  parseScheduleEditArgs,
+  resolveScheduleEditConnectedHostConnection,
+  scheduleEditKindFromValue,
+  type ScheduleEditResult,
+} from '../agent/schedule-edit.ts';
+import {
+  formatScheduleEditFailure,
+  formatScheduleEditPreview,
+  formatScheduleEditSuccess,
+} from '../agent/schedule-edit-format.ts';
+import type { AgentConnectedHostConfigReader } from '../agent/routine-schedule-promotion.ts';
+
+export interface AgentScheduleEditToolArgs {
+  readonly scheduleId?: unknown;
+  readonly jobId?: unknown;
+  readonly scheduleKind?: unknown;
+  readonly scheduleValue?: unknown;
+  readonly timezone?: unknown;
+  readonly staggerMs?: unknown;
+  readonly name?: unknown;
+  readonly prompt?: unknown;
+  readonly task?: unknown;
+  readonly successCriteria?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readOptionalString(value: unknown): string | null {
+  const text = readString(value);
+  return text ? text : null;
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+function addOptionalArg(args: string[], flag: string, value: unknown): void {
+  const text = readOptionalString(value);
+  if (!text) return;
+  args.push(flag, text);
+}
+
+function addOptionalNumber(args: string[], flag: string, value: unknown): void {
+  if (value === undefined || value === null || value === '') return;
+  if (typeof value === 'number') {
+    args.push(flag, String(value));
+    return;
+  }
+  addOptionalArg(args, flag, value);
+}
+
+function buildScheduleEditArgs(rawArgs: AgentScheduleEditToolArgs): readonly string[] {
+  const scheduleId = readOptionalString(rawArgs.scheduleId) ?? readOptionalString(rawArgs.jobId);
+  const explicitUserRequest = readOptionalString(rawArgs.explicitUserRequest);
+  if (!scheduleId) throw new Error('scheduleId is required.');
+  if (!explicitUserRequest) throw new Error('explicitUserRequest is required.');
+
+  const args = [scheduleId, '--explicit-user-request', explicitUserRequest];
+  const scheduleKind = scheduleEditKindFromValue(rawArgs.scheduleKind);
+  const scheduleValue = readOptionalString(rawArgs.scheduleValue);
+  if (scheduleKind && !scheduleValue) throw new Error('scheduleValue is required when scheduleKind is set.');
+  if (!scheduleKind && scheduleValue) throw new Error('scheduleKind is required when scheduleValue is set.');
+  if (scheduleKind && scheduleValue) args.push(`--${scheduleKind}`, scheduleValue);
+
+  addOptionalArg(args, '--timezone', rawArgs.timezone);
+  addOptionalNumber(args, '--stagger-ms', rawArgs.staggerMs);
+  addOptionalArg(args, '--name', rawArgs.name);
+  addOptionalArg(args, '--prompt', rawArgs.prompt);
+  addOptionalArg(args, '--task', rawArgs.task);
+  addOptionalArg(args, '--success-criteria', rawArgs.successCriteria);
+  if (readBoolean(rawArgs.confirm)) args.push('--yes');
+  return args;
+}
+
+function outputForResult(result: ScheduleEditResult): { readonly success: boolean; readonly output?: string; readonly error?: string } {
+  if (result.ok) {
+    return {
+      success: true,
+      output: formatScheduleEditSuccess(result),
+    };
+  }
+  return {
+    success: false,
+    error: formatScheduleEditFailure(result),
+  };
+}
+
+function confirmationError(preview: ReturnType<typeof buildScheduleEditPreview>): string {
+  return [
+    formatScheduleEditPreview(preview),
+    '',
+    'Model tool confirmation required. Call this tool with confirm:true only when the user explicitly asked GoodVibes Agent to edit this exact schedule.',
+    'Do not infer schedule edits from vague optimization, cleanup, or follow-up suggestions.',
+  ].join('\n');
+}
+
+export function createAgentScheduleEditTool(
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): Tool {
+  return {
+    definition: {
+      name: 'agent_schedule_edit',
+      description: 'Edit one confirmed connected GoodVibes schedule.',
+      parameters: {
+        type: 'object',
+        properties: {
+          scheduleId: {
+            type: 'string',
+            description: 'Connected schedule id to edit.',
+          },
+          jobId: {
+            type: 'string',
+            description: 'Automation job id when known instead of scheduleId.',
+          },
+          scheduleKind: {
+            type: 'string',
+            enum: ['at', 'every', 'cron'],
+            description: 'Optional replacement schedule kind.',
+          },
+          scheduleValue: {
+            type: 'string',
+            description: 'Replacement ISO time, interval, or cron expression.',
+          },
+          timezone: {
+            type: 'string',
+            description: 'Optional IANA timezone for cron replacements.',
+          },
+          staggerMs: {
+            type: 'number',
+            description: 'Optional cron stagger in milliseconds.',
+          },
+          name: {
+            type: 'string',
+            description: 'Optional replacement schedule display name.',
+          },
+          prompt: {
+            type: 'string',
+            description: 'Optional exact replacement prompt.',
+          },
+          task: {
+            type: 'string',
+            description: 'Optional replacement autonomous task.',
+          },
+          successCriteria: {
+            type: 'string',
+            description: 'Required with task; expected run outcome.',
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Required true only when user requested this edit.',
+          },
+          explicitUserRequest: {
+            type: 'string',
+            description: 'User request authorizing this schedule edit.',
+          },
+        },
+        required: ['scheduleId', 'confirm', 'explicitUserRequest'],
+        additionalProperties: false,
+      },
+      sideEffects: ['network', 'state'],
+    },
+    execute: async (rawArgs: unknown) => {
+      try {
+        const args = rawArgs as AgentScheduleEditToolArgs;
+        const parsed = parseScheduleEditArgs(buildScheduleEditArgs(args));
+        if (parsed.errors.length > 0) {
+          return {
+            success: false,
+            error: parsed.errors.join('\n'),
+          };
+        }
+        let preview = buildScheduleEditPreview(parsed);
+        const connection = resolveScheduleEditConnectedHostConnection(configManager, shellPaths.homeDirectory);
+        if (!parsed.yes) {
+          preview = await enrichScheduleEditPreviewFromConnectedHost(connection, preview);
+          return {
+            success: false,
+            error: confirmationError(preview),
+          };
+        }
+        return outputForResult(await editConnectedSchedule(connection, preview));
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}
+
+export function registerAgentScheduleEditTool(
+  registry: ToolRegistry,
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): void {
+  registry.register(createAgentScheduleEditTool(shellPaths, configManager));
+}