@pellux/goodvibes-agent 1.1.7 → 1.2.0

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

@@ -0,0 +1,155 @@
+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 AgentAuditAction = 'readiness' | 'item' | 'evidence' | 'artifact';
+
+interface AgentAuditToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly itemId?: unknown;
+  readonly artifactId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentAuditToolDeps {
+  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 normalizeAuditAction(value: unknown): AgentAuditAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (['readiness', 'status', 'summary', 'inventory', 'gate', 'gates', 'release_readiness'].includes(action)) return 'readiness';
+  if (['item', 'readiness_item', 'release_readiness_item'].includes(action)) return 'item';
+  if (['evidence', 'artifacts', 'release_evidence', 'ledger', 'verification'].includes(action)) return 'evidence';
+  if (['artifact', 'evidence_artifact', 'release_evidence_artifact'].includes(action)) return 'artifact';
+  return null;
+}
+
+function evidenceLikeText(args: AgentAuditToolArgs): boolean {
+  const text = `${readString(args.query)}\n${readString(args.target)}`.toLowerCase();
+  return /\b(evidence|artifact|ledger|verification|live[-\s]?verification|release notes|performance snapshot)\b/.test(text);
+}
+
+function readAction(args: AgentAuditToolArgs): AgentAuditAction | null {
+  const explicit = normalizeAuditAction(args.action) ?? normalizeAuditAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.artifactId)) return 'artifact';
+  if (readString(args.itemId)) return 'item';
+  if (evidenceLikeText(args)) return 'evidence';
+  return 'readiness';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function readinessArgs(args: AgentAuditToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'release_readiness',
+    query: args.query ?? args.target,
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function itemArgs(args: AgentAuditToolArgs): Record<string, unknown> {
+  const itemId = readString(args.itemId) || readString(args.id);
+  return compactArgs({
+    mode: 'release_readiness_item',
+    itemId,
+    target: itemId ? undefined : args.target,
+    query: itemId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function evidenceArgs(args: AgentAuditToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'release_evidence',
+    query: args.query ?? args.target,
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function artifactArgs(args: AgentAuditToolArgs): Record<string, unknown> {
+  const artifactId = readString(args.artifactId) || readString(args.id);
+  return compactArgs({
+    mode: 'release_evidence_artifact',
+    artifactId,
+    target: artifactId ? undefined : args.target,
+    query: artifactId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentAuditTool(deps: AgentAuditToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'audit',
+      description: 'Read release readiness and packaged release evidence.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['readiness', 'item', 'evidence', 'artifact'],
+            description: 'Read release inventory, one item, evidence list, or one artifact.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Alias for itemId or artifactId depending on action.' },
+          itemId: { type: 'string', description: 'Release readiness item id.' },
+          artifactId: { type: 'string', description: 'Release evidence artifact id.' },
+          target: { type: 'string', description: 'Lookup target or search text.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed release artifact or item content.' },
+          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 AgentAuditToolArgs;
+      const action = readAction(args);
+      if (!action) return error('Unknown audit action. Use action:"readiness", "item", "evidence", or "artifact".');
+      if (action === 'readiness') return harnessTool.execute(readinessArgs(args));
+      if (action === 'item') return harnessTool.execute(itemArgs(args));
+      if (action === 'evidence') return harnessTool.execute(evidenceArgs(args));
+      if (action === 'artifact') return harnessTool.execute(artifactArgs(args));
+      return error('Unknown audit action. Use action:"readiness", "item", "evidence", or "artifact".');
+    },
+  };
+}
+
+export function registerAgentAuditTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('audit')) registry.register(createAgentAuditTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -0,0 +1,238 @@
+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 {
+  buildAutonomySchedulePreview,
+  createAutonomySchedule,
+  parseAutonomyScheduleArgs,
+  resolveAutonomyConnectedHostConnection,
+  type AutonomyScheduleResult,
+} from '../agent/autonomy-schedule.ts';
+import {
+  formatAutonomyScheduleFailure,
+  formatAutonomySchedulePreview,
+  formatAutonomyScheduleSuccess,
+} from '../agent/autonomy-schedule-format.ts';
+import type { AgentConnectedHostConfigReader } from '../agent/routine-schedule-promotion.ts';
+
+type AutonomyScheduleKind = 'at' | 'every' | 'cron';
+
+export interface AgentAutonomyScheduleToolArgs {
+  readonly task?: unknown;
+  readonly successCriteria?: unknown;
+  readonly scheduleKind?: unknown;
+  readonly scheduleValue?: unknown;
+  readonly timezone?: unknown;
+  readonly name?: unknown;
+  readonly provider?: unknown;
+  readonly model?: unknown;
+  readonly deliveryChannel?: unknown;
+  readonly deliveryRoute?: unknown;
+  readonly deliveryWebhook?: unknown;
+  readonly deliveryLink?: unknown;
+  readonly disabled?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+const SCHEDULE_KINDS: readonly AutonomyScheduleKind[] = ['at', 'every', 'cron'];
+
+function isScheduleKind(value: unknown): value is AutonomyScheduleKind {
+  return typeof value === 'string' && SCHEDULE_KINDS.includes(value as AutonomyScheduleKind);
+}
+
+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 scheduleFlag(kind: AutonomyScheduleKind): string {
+  if (kind === 'cron') return '--cron';
+  if (kind === 'every') return '--every';
+  return '--at';
+}
+
+function buildAutonomyScheduleArgs(rawArgs: AgentAutonomyScheduleToolArgs): readonly string[] {
+  const task = readOptionalString(rawArgs.task);
+  const successCriteria = readOptionalString(rawArgs.successCriteria);
+  const explicitUserRequest = readOptionalString(rawArgs.explicitUserRequest);
+  const scheduleValue = readOptionalString(rawArgs.scheduleValue);
+  if (!task) throw new Error('task is required.');
+  if (!successCriteria) throw new Error('successCriteria is required.');
+  if (!explicitUserRequest) throw new Error('explicitUserRequest is required.');
+  if (!isScheduleKind(rawArgs.scheduleKind)) throw new Error('scheduleKind must be one of: at, every, cron.');
+  if (!scheduleValue) throw new Error('scheduleValue is required.');
+
+  const args = [
+    scheduleFlag(rawArgs.scheduleKind),
+    scheduleValue,
+    '--task',
+    task,
+    '--success-criteria',
+    successCriteria,
+    '--explicit-user-request',
+    explicitUserRequest,
+  ];
+  addOptionalArg(args, '--timezone', rawArgs.timezone);
+  addOptionalArg(args, '--name', rawArgs.name);
+  addOptionalArg(args, '--provider', rawArgs.provider);
+  addOptionalArg(args, '--model', rawArgs.model);
+  addOptionalArg(args, '--delivery-channel', rawArgs.deliveryChannel);
+  addOptionalArg(args, '--delivery-route', rawArgs.deliveryRoute);
+  addOptionalArg(args, '--delivery-webhook', rawArgs.deliveryWebhook);
+  addOptionalArg(args, '--delivery-link', rawArgs.deliveryLink);
+  if (readBoolean(rawArgs.disabled)) args.push('--disabled');
+  if (readBoolean(rawArgs.confirm)) args.push('--yes');
+  return args;
+}
+
+function outputForResult(result: AutonomyScheduleResult): { readonly success: boolean; readonly output?: string; readonly error?: string } {
+  if (result.ok) {
+    return {
+      success: true,
+      output: formatAutonomyScheduleSuccess(result),
+    };
+  }
+  return {
+    success: false,
+    error: formatAutonomyScheduleFailure(result),
+  };
+}
+
+function confirmationError(preview: ReturnType<typeof buildAutonomySchedulePreview>): string {
+  return [
+    formatAutonomySchedulePreview(preview),
+    '',
+    'Model tool confirmation required. Call this tool with confirm:true only when the user explicitly asked GoodVibes Agent to create this autonomous schedule.',
+    'Do not create autonomous schedules from vague suggestions, brainstorming, inferred follow-up work, or tasks without success criteria.',
+  ].join('\n');
+}
+
+export function createAgentAutonomyScheduleTool(
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): Tool {
+  return {
+    definition: {
+      name: 'agent_autonomy_schedule',
+      description: 'Schedule one confirmed visible autonomous Agent task.',
+      parameters: {
+        type: 'object',
+        properties: {
+          task: {
+            type: 'string',
+            description: 'Exact autonomous task the schedule should run.',
+          },
+          successCriteria: {
+            type: 'string',
+            description: 'What a successful scheduled run must report or produce.',
+          },
+          scheduleKind: {
+            type: 'string',
+            enum: [...SCHEDULE_KINDS],
+            description: 'Schedule kind: at, every, or cron.',
+          },
+          scheduleValue: {
+            type: 'string',
+            description: 'ISO timestamp, interval, or cron expression matching scheduleKind.',
+          },
+          timezone: {
+            type: 'string',
+            description: 'Optional IANA timezone for cron/at schedules.',
+          },
+          name: {
+            type: 'string',
+            description: 'Optional connected schedule display name.',
+          },
+          provider: {
+            type: 'string',
+            description: 'Optional provider row id for scheduled execution.',
+          },
+          model: {
+            type: 'string',
+            description: 'Optional model id for scheduled execution.',
+          },
+          deliveryChannel: {
+            type: 'string',
+            description: 'Optional delivery channel target.',
+          },
+          deliveryRoute: {
+            type: 'string',
+            description: 'Optional connected route target: routeId:label.',
+          },
+          deliveryWebhook: {
+            type: 'string',
+            description: 'Optional http(s) webhook target.',
+          },
+          deliveryLink: {
+            type: 'string',
+            description: 'Optional link delivery target.',
+          },
+          disabled: {
+            type: 'boolean',
+            description: 'Create the schedule disabled.',
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Required true only when user requested this schedule.',
+          },
+          explicitUserRequest: {
+            type: 'string',
+            description: 'User request authorizing this schedule.',
+          },
+        },
+        required: ['task', 'successCriteria', 'scheduleKind', 'scheduleValue', 'confirm', 'explicitUserRequest'],
+        additionalProperties: false,
+      },
+      sideEffects: ['network', 'state'],
+    },
+    execute: async (rawArgs: unknown) => {
+      try {
+        const args = rawArgs as AgentAutonomyScheduleToolArgs;
+        const parsed = parseAutonomyScheduleArgs(buildAutonomyScheduleArgs(args));
+        if (parsed.errors.length > 0) {
+          return {
+            success: false,
+            error: parsed.errors.join('\n'),
+          };
+        }
+        const preview = buildAutonomySchedulePreview(parsed);
+        if (!parsed.yes) {
+          return {
+            success: false,
+            error: confirmationError(preview),
+          };
+        }
+        const connection = resolveAutonomyConnectedHostConnection(configManager, shellPaths.homeDirectory);
+        return outputForResult(await createAutonomySchedule(connection, preview));
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}
+
+export function registerAgentAutonomyScheduleTool(
+  registry: ToolRegistry,
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): void {
+  registry.register(createAgentAutonomyScheduleTool(shellPaths, configManager));
+}

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

@@ -0,0 +1,140 @@
+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 AgentAutonomyAction = 'intake' | 'queue' | 'item' | 'status';
+
+interface AgentAutonomyToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly queueItemId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentAutonomyToolDeps {
+  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 normalizeAutonomyAction(value: unknown): AgentAutonomyAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'intake' || action === 'request' || action === 'route' || action === 'plan' || action === 'triage' || action === 'autonomy_intake') return 'intake';
+  if (action === 'queue' || action === 'list' || action === 'work' || action === 'ongoing' || action === 'autonomy_queue') return 'queue';
+  if (action === 'item' || action === 'card' || action === 'show' || action === 'inspect' || action === 'autonomy_queue_item') return 'item';
+  if (action === 'status' || action === 'summary' || action === 'overview') return 'status';
+  return null;
+}
+
+function readAction(args: AgentAutonomyToolArgs): AgentAutonomyAction {
+  const explicit = normalizeAutonomyAction(args.action) ?? normalizeAutonomyAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.queueItemId) || readString(args.id)) return 'item';
+  if (readString(args.query) || readString(args.target)) return 'intake';
+  return 'queue';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function queueItemId(args: AgentAutonomyToolArgs): string {
+  return readString(args.queueItemId) || readString(args.id);
+}
+
+function intakeArgs(args: AgentAutonomyToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'autonomy_intake',
+    query: args.query,
+    target: args.target,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function queueArgs(args: AgentAutonomyToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'autonomy_queue',
+    query: args.query ?? args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function itemArgs(args: AgentAutonomyToolArgs): Record<string, unknown> {
+  const itemId = queueItemId(args);
+  return compactArgs({
+    mode: 'autonomy_queue_item',
+    queueItemId: itemId,
+    target: itemId ? undefined : args.target,
+    query: itemId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentAutonomyTool(deps: AgentAutonomyToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'autonomy',
+      description: 'Route ongoing work and inspect visible autonomy.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['intake', 'queue', 'item', 'status'],
+            description: 'Read-only autonomy intake, queue, item, or status view.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Alias for queueItemId.' },
+          queueItemId: { type: 'string', description: 'Autonomy queue card id.' },
+          target: { type: 'string', description: 'Lookup target or ongoing-work request.' },
+          query: { type: 'string', description: 'Ongoing-work request or queue search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed routes, schemas, live records, and control evidence.' },
+          limit: { type: 'number', description: 'Maximum queue rows returned.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentAutonomyToolArgs;
+      const action = readAction(args);
+
+      if (action === 'intake') return harnessTool.execute(intakeArgs(args));
+      if (action === 'queue' || action === 'status') return harnessTool.execute(queueArgs(args));
+      if (action === 'item') return harnessTool.execute(itemArgs(args));
+
+      return error('Unknown autonomy action. Use action:"intake" for ongoing work or action:"queue" for visible autonomous work.');
+    },
+  };
+}
+
+export function registerAgentAutonomyTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('autonomy')) registry.register(createAgentAutonomyTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

package/src/tools/agent-channel-send-tool.ts

@@ -1,12 +1,14 @@
 import type { ChannelDeliveryRouter } from '@pellux/goodvibes-sdk/platform/channels';
 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 {
   buildAgentChannelDeliveryPreview,
   deliverAgentChannelMessage,
   formatAgentChannelDeliveryPreview,
   formatAgentChannelDeliveryResult,
 } from '../agent/channel-delivery.ts';
+import { recordAgentChannelDeliveryReceipt } from '../agent/channel-delivery-receipts.ts';
 
 export interface AgentChannelSendToolArgs {
   readonly message?: unknown;
@@ -19,6 +21,10 @@ export interface AgentChannelSendToolArgs {
   readonly explicitUserRequest?: unknown;
 }
 
+export interface AgentChannelSendToolOptions {
+  readonly shellPaths?: Pick<ShellPathService, 'resolveUserPath'>;
+}
+
 function readString(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
@@ -37,6 +43,7 @@ function output(text: string): { readonly success: true; readonly output: string
 
 export function createAgentChannelSendTool(
   channelDeliveryRouter: Pick<ChannelDeliveryRouter, 'deliver' | 'listStrategies'>,
+  options: AgentChannelSendToolOptions = {},
 ): Tool {
   return {
     definition: {
@@ -111,7 +118,21 @@ export function createAgentChannelSendTool(
         ].join('\n'));
       }
       try {
-        return output(formatAgentChannelDeliveryResult(await deliverAgentChannelMessage(channelDeliveryRouter, input)));
+        const result = await deliverAgentChannelMessage(channelDeliveryRouter, input);
+        const lines = [formatAgentChannelDeliveryResult(result)];
+        if (options.shellPaths) {
+          try {
+            const receipt = recordAgentChannelDeliveryReceipt(options.shellPaths, {
+              source: 'model-tool',
+              deliveryInput: input,
+              result,
+            });
+            lines.push(`  receipt ${receipt.id}`);
+          } catch (receiptError) {
+            lines.push(`  receipt unavailable ${receiptError instanceof Error ? receiptError.message : String(receiptError)}`);
+          }
+        }
+        return output(lines.join('\n'));
       } catch (error) {
         return failure(error instanceof Error ? error.message : String(error));
       }
@@ -122,6 +143,7 @@ export function createAgentChannelSendTool(
 export function registerAgentChannelSendTool(
   registry: ToolRegistry,
   channelDeliveryRouter: Pick<ChannelDeliveryRouter, 'deliver' | 'listStrategies'>,
+  options: AgentChannelSendToolOptions = {},
 ): void {
-  registry.register(createAgentChannelSendTool(channelDeliveryRouter));
+  registry.register(createAgentChannelSendTool(channelDeliveryRouter, options));
 }