@pellux/goodvibes-agent 1.1.6 → 1.2.0

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

@@ -0,0 +1,143 @@
+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 AgentContextAction =
+  | 'status'
+  | 'files'
+  | 'file'
+  | 'prompt'
+  | 'receipts'
+  | 'receipt';
+
+interface AgentContextToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly contextFileId?: unknown;
+  readonly receiptId?: unknown;
+  readonly turnId?: unknown;
+  readonly outcomeStatus?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentContextToolDeps {
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly toolRegistry: ToolRegistry;
+  readonly harnessTool?: Tool;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeContextAction(value: unknown): AgentContextAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'context' || action === 'current') return 'status';
+  if (action === 'files' || action === 'project' || action === 'project_context' || action === 'instructions') return 'files';
+  if (action === 'file' || action === 'show' || action === 'project_context_file' || action === 'instruction') return 'file';
+  if (action === 'prompt' || action === 'prompt_context' || action === 'composition' || action === 'budget') return 'prompt';
+  if (action === 'receipts' || action === 'turns' || action === 'outcomes') return 'receipts';
+  if (action === 'receipt' || action === 'turn' || action === 'outcome') return 'receipt';
+  return null;
+}
+
+function readAction(args: AgentContextToolArgs): AgentContextAction {
+  const explicit = normalizeContextAction(args.action) ?? normalizeContextAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.receiptId) || readString(args.turnId) || readString(args.outcomeStatus)) return 'receipt';
+  if (readString(args.contextFileId)) return 'file';
+  if (readString(args.target) || readString(args.query)) return 'files';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+export function createAgentContextTool(deps: AgentContextToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'context',
+      description: 'Inspect project instructions and prompt context.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'files', 'file', 'prompt', 'receipts', 'receipt'],
+            description: 'Read project files, prompt context, or receipt history.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          contextFileId: { type: 'string', description: 'Project context file id.' },
+          receiptId: { type: 'string', description: 'Prompt context receipt id.' },
+          turnId: { type: 'string', description: 'Prompt context turn id.' },
+          outcomeStatus: { type: 'string', enum: ['completed', 'error', 'cancelled', 'pending'], description: 'Prompt receipt outcome filter.' },
+          target: { type: 'string', description: 'Target file path or context lookup text.' },
+          query: { type: 'string', description: 'Search text for context files.' },
+          includeParameters: { type: 'boolean', description: 'Include bounded bodies and receipt detail.' },
+          limit: { type: 'number', description: 'Maximum prompt receipts to return.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentContextToolArgs;
+      const action = readAction(args);
+
+      if (action === 'files') {
+        return harnessTool.execute(compactArgs({
+          mode: 'project_context',
+          target: args.target,
+          query: args.query,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'file') {
+        return harnessTool.execute(compactArgs({
+          mode: 'project_context_file',
+          contextFileId: args.contextFileId,
+          target: args.target,
+          query: args.query,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'receipt' || action === 'receipts') {
+        return harnessTool.execute(compactArgs({
+          mode: 'prompt_context',
+          receiptId: args.receiptId,
+          turnId: args.turnId,
+          outcomeStatus: args.outcomeStatus,
+          limit: args.limit,
+          includeParameters: action === 'receipt' ? args.includeParameters ?? true : args.includeParameters,
+        }));
+      }
+      return harnessTool.execute(compactArgs({
+        mode: 'prompt_context',
+        limit: args.limit,
+        includeParameters: args.includeParameters,
+      }));
+    },
+  };
+}
+
+export function registerAgentContextTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('context')) registry.register(createAgentContextTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -0,0 +1,128 @@
+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 AgentDelegationAction = 'status' | 'routes' | 'route';
+
+interface AgentDelegationToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly delegationRouteId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentDelegationToolDeps {
+  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 normalizeDelegationAction(value: unknown): AgentDelegationAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'overview' || action === 'policy' || action === 'decision' || action === 'decisions' || action === 'delegation_posture') return 'status';
+  if (action === 'routes' || action === 'list' || action === 'catalog' || action === 'posture') return 'routes';
+  if (action === 'route' || action === 'item' || action === 'card' || action === 'show' || action === 'inspect' || action === 'delegation_route') return 'route';
+  return null;
+}
+
+function readAction(args: AgentDelegationToolArgs): AgentDelegationAction {
+  const explicit = normalizeDelegationAction(args.action) ?? normalizeDelegationAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.delegationRouteId) || readString(args.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: AgentDelegationToolArgs): string {
+  return readString(args.delegationRouteId) || readString(args.id);
+}
+
+function postureArgs(args: AgentDelegationToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'delegation_posture',
+    query: args.query ?? args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function routeArgs(args: AgentDelegationToolArgs): Record<string, unknown> {
+  const delegationRouteId = routeId(args);
+  return compactArgs({
+    mode: 'delegation_route',
+    delegationRouteId,
+    target: delegationRouteId ? undefined : args.target,
+    query: delegationRouteId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentDelegationTool(deps: AgentDelegationToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'delegation',
+      description: 'Inspect build delegation routes and policy.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'routes', 'route'],
+            description: 'Read-only delegation status, route catalog, or single route inspection.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Alias for delegationRouteId.' },
+          delegationRouteId: { type: 'string', description: 'Delegation route id.' },
+          target: { type: 'string', description: 'Lookup target or route search text.' },
+          query: { type: 'string', description: 'Route search text.' },
+          includeParameters: { type: 'boolean', description: 'Include required fields, evidence, and confirmed handoff routes.' },
+          limit: { type: 'number', description: 'Maximum route rows returned.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentDelegationToolArgs;
+      const action = readAction(args);
+
+      if (action === 'status' || action === 'routes') return harnessTool.execute(postureArgs(args));
+      if (action === 'route') return harnessTool.execute(routeArgs(args));
+
+      return error('Unknown delegation action. Use action:"status" for policy or action:"route" for one delegation route.');
+    },
+  };
+}
+
+export function registerAgentDelegationTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('delegation')) registry.register(createAgentDelegationTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -0,0 +1,240 @@
+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 AgentDeviceAction =
+  | 'status'
+  | 'capability'
+  | 'browser'
+  | 'open_browser'
+  | 'control'
+  | 'voice'
+  | 'provider'
+  | 'open_tts_provider'
+  | 'open_tts_voice';
+
+interface AgentDeviceToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly capabilityId?: unknown;
+  readonly routeId?: unknown;
+  readonly pairingRouteId?: unknown;
+  readonly mediaProviderId?: unknown;
+  readonly providerId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+interface AgentDeviceToolDeps {
+  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 normalizeDeviceAction(value: unknown): AgentDeviceAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'map' || action === 'capabilities' || action === 'device' || action === 'devices' || action === 'mobile' || action === 'phone' || action === 'pairing') return 'status';
+  if (action === 'capability' || action === 'route' || action === 'pairing_route' || action === 'show' || action === 'inspect') return 'capability';
+  if (action === 'browser' || action === 'pwa' || action === 'cockpit' || action === 'browser_cockpit' || action === 'web') return 'browser';
+  if (action === 'open' || action === 'open_browser' || action === 'open_pwa' || action === 'open_cockpit' || action === 'open_browser_cockpit') return 'open_browser';
+  if (action === 'control' || action === 'browser_control' || action === 'desktop' || action === 'desktop_control' || action === 'computer_use') return 'control';
+  if (action === 'voice' || action === 'media' || action === 'voice_media' || action === 'workflows') return 'voice';
+  if (action === 'provider' || action === 'media_provider' || action === 'voice_provider') return 'provider';
+  if (action === 'open_tts_provider' || action === 'tts_provider_picker') return 'open_tts_provider';
+  if (action === 'open_tts_voice' || action === 'tts_voice_picker') return 'open_tts_voice';
+  return null;
+}
+
+function readAction(args: AgentDeviceToolArgs): AgentDeviceAction {
+  const explicit = normalizeDeviceAction(args.action) ?? normalizeDeviceAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.mediaProviderId) || readString(args.providerId)) return 'provider';
+  if (readString(args.capabilityId) || readString(args.routeId) || readString(args.pairingRouteId)) return 'capability';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function capabilityLookup(args: AgentDeviceToolArgs): string {
+  return readString(args.pairingRouteId)
+    || readString(args.capabilityId)
+    || readString(args.routeId)
+    || readString(args.id);
+}
+
+function providerLookup(args: AgentDeviceToolArgs): string {
+  return readString(args.mediaProviderId)
+    || readString(args.providerId)
+    || readString(args.id);
+}
+
+function confirmedArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    confirm: args.confirm,
+    explicitUserRequest: args.explicitUserRequest,
+  });
+}
+
+function statusArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'pairing_posture',
+    query: args.query ?? args.target ?? 'device',
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function capabilityArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  const pairingRouteId = capabilityLookup(args);
+  return compactArgs({
+    mode: 'pairing_route',
+    pairingRouteId,
+    target: pairingRouteId ? undefined : args.target,
+    query: pairingRouteId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function browserArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'ui_surface',
+    surfaceId: 'connected-browser-cockpit',
+    includeParameters: args.includeParameters ?? true,
+  });
+}
+
+function openBrowserArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'open_ui_surface',
+    surfaceId: 'connected-browser-cockpit',
+    ...confirmedArgs(args),
+  });
+}
+
+function controlArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'execution_route',
+    executionRouteId: 'browser-or-desktop-control',
+    includeParameters: args.includeParameters ?? true,
+  });
+}
+
+function voiceArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'media_posture',
+    query: args.query ?? args.target ?? 'voice',
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function providerArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  const mediaProviderId = providerLookup(args);
+  return compactArgs({
+    mode: 'media_provider',
+    mediaProviderId,
+    target: mediaProviderId ? undefined : args.target,
+    query: mediaProviderId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function openTtsProviderArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'open_ui_surface',
+    surfaceId: 'tts-provider-picker',
+    ...confirmedArgs(args),
+  });
+}
+
+function openTtsVoiceArgs(args: AgentDeviceToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'open_ui_surface',
+    surfaceId: 'tts-voice-picker',
+    target: readString(args.providerId) || readString(args.mediaProviderId) || args.target,
+    ...confirmedArgs(args),
+  });
+}
+
+export function createAgentDeviceTool(deps: AgentDeviceToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'device',
+      description: 'Inspect/open device, voice, and browser routes.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'capability', 'browser', 'open_browser', 'control', 'voice', 'provider', 'open_tts_provider', 'open_tts_voice'],
+            description: 'Read device/browser/voice posture; confirm visible open actions.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Capability, route, or provider id alias.' },
+          capabilityId: { type: 'string', description: 'Device capability id.' },
+          routeId: { type: 'string', description: 'Pairing route id alias.' },
+          pairingRouteId: { type: 'string', description: 'Pairing route id.' },
+          mediaProviderId: { type: 'string', description: 'Voice/media provider id.' },
+          providerId: { type: 'string', description: 'Voice/media provider id alias.' },
+          target: { type: 'string', description: 'Lookup or provider target.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed route contracts.' },
+          limit: { type: 'number', description: 'Maximum rows.' },
+          confirm: { type: 'boolean', description: 'Required true for visible open actions.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing visible open actions.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentDeviceToolArgs;
+      const action = readAction(args);
+
+      if (action === 'status') return harnessTool.execute(statusArgs(args));
+      if (action === 'capability') return harnessTool.execute(capabilityArgs(args));
+      if (action === 'browser') return harnessTool.execute(browserArgs(args));
+      if (action === 'open_browser') return harnessTool.execute(openBrowserArgs(args));
+      if (action === 'control') return harnessTool.execute(controlArgs(args));
+      if (action === 'voice') return harnessTool.execute(voiceArgs(args));
+      if (action === 'provider') return harnessTool.execute(providerArgs(args));
+      if (action === 'open_tts_provider') return harnessTool.execute(openTtsProviderArgs(args));
+      if (action === 'open_tts_voice') return harnessTool.execute(openTtsVoiceArgs(args));
+
+      return error('Unknown device action. Use action:"status" for the device capability map.');
+    },
+  };
+}
+
+export function registerAgentDeviceTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('device')) registry.register(createAgentDeviceTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}