@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-channels-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 AgentChannelsAction = 'status' | 'channel' | 'setup' | 'triage' | 'deliveries';
+
+interface AgentChannelsToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly channelId?: unknown;
+  readonly id?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentChannelsToolDeps {
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly toolRegistry: ToolRegistry;
+  readonly harnessTool?: Tool;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeChannelsAction(value: unknown): AgentChannelsAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'list' || action === 'readiness' || action === 'channels') return 'status';
+  if (action === 'channel' || action === 'show' || action === 'inspect') return 'channel';
+  if (action === 'setup' || action === 'guide' || action === 'setup_guide' || action === 'channel_setup_guide') return 'setup';
+  if (action === 'triage' || action === 'inbox' || action === 'blockers' || action === 'retries' || action === 'channel_triage') return 'triage';
+  if (action === 'deliveries' || action === 'delivery' || action === 'receipts' || action === 'history' || action === 'channel_deliveries') return 'deliveries';
+  return null;
+}
+
+function readAction(args: AgentChannelsToolArgs): AgentChannelsAction {
+  const explicit = normalizeChannelsAction(args.action) ?? normalizeChannelsAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.channelId) || readString(args.id)) return 'channel';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function channelIdArg(args: AgentChannelsToolArgs): unknown {
+  return readString(args.channelId) || readString(args.id) || undefined;
+}
+
+export function createAgentChannelsTool(deps: AgentChannelsToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'channels',
+      description: 'Inspect channel readiness, setup, triage, and receipts.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'channel', 'setup', 'triage', 'deliveries'],
+            description: 'Read channel status, setup, triage, or receipts.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          channelId: { type: 'string', description: 'Channel id to inspect.' },
+          id: { type: 'string', description: 'Alias for channelId.' },
+          target: { type: 'string', description: 'Channel lookup target.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include route detail and safe config-key names.' },
+          limit: { type: 'number', description: 'Maximum triage, delivery, or channel rows.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentChannelsToolArgs;
+      const action = readAction(args);
+
+      if (action === 'channel') {
+        return harnessTool.execute(compactArgs({
+          mode: 'channel',
+          channelId: channelIdArg(args),
+          target: args.target,
+          query: args.query,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'setup') {
+        return harnessTool.execute(compactArgs({
+          mode: 'channel_setup_guide',
+          channelId: channelIdArg(args),
+          target: args.target,
+          query: args.query,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'triage') {
+        return harnessTool.execute(compactArgs({
+          mode: 'channel_triage',
+          limit: args.limit,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      if (action === 'deliveries') {
+        return harnessTool.execute(compactArgs({
+          mode: 'channel_deliveries',
+          limit: args.limit,
+          includeParameters: args.includeParameters,
+        }));
+      }
+      return harnessTool.execute(compactArgs({
+        mode: 'channels',
+        query: args.query ?? args.target,
+        limit: args.limit,
+        includeParameters: args.includeParameters,
+      }));
+    },
+  };
+}
+
+export function registerAgentChannelsTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('channels')) registry.register(createAgentChannelsTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -0,0 +1,168 @@
+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 AgentComputerAction =
+  | 'status'
+  | 'plan'
+  | 'control'
+  | 'browser'
+  | 'open_browser'
+  | 'setup'
+  | 'mcp';
+
+interface AgentComputerToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+interface AgentComputerToolDeps {
+  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 normalizeComputerAction(value: unknown): AgentComputerAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'overview' || action === 'computer' || action === 'computer_use') return 'status';
+  if (action === 'plan' || action === 'route' || action === 'control_plan' || action === 'browser_plan' || action === 'desktop_plan' || action === 'screenshot' || action === 'screen' || action === 'screen_recording' || action === 'observe') return 'plan';
+  if (action === 'control' || action === 'browser_control' || action === 'desktop' || action === 'desktop_control') return 'control';
+  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 === 'setup' || action === 'configure' || action === 'browser_desktop_control') return 'setup';
+  if (action === 'mcp' || action === 'tools' || action === 'servers' || action === 'mcp_servers') return 'mcp';
+  return null;
+}
+
+function readAction(args: AgentComputerToolArgs): AgentComputerAction | null {
+  const explicit = readString(args.action) || readString(args.mode);
+  return explicit ? normalizeComputerAction(explicit) : 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function controlArgs(args: AgentComputerToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'execution_route',
+    executionRouteId: 'browser-or-desktop-control',
+    includeParameters: args.includeParameters ?? true,
+  });
+}
+
+function planArgs(args: AgentComputerToolArgs): Record<string, unknown> {
+  const rawAction = readString(args.action) || readString(args.mode);
+  const normalizedAction = rawAction.toLowerCase().replace(/-/g, '_');
+  const actionAsQuery = ['screenshot', 'screen', 'screen_recording', 'observe'].includes(normalizedAction) ? rawAction : undefined;
+  return compactArgs({
+    mode: 'browser_control_route',
+    query: args.query ?? args.target ?? actionAsQuery,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function browserArgs(args: AgentComputerToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'ui_surface',
+    surfaceId: 'connected-browser-cockpit',
+    includeParameters: args.includeParameters ?? true,
+  });
+}
+
+function openBrowserArgs(args: AgentComputerToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'open_ui_surface',
+    surfaceId: 'connected-browser-cockpit',
+    confirm: args.confirm,
+    explicitUserRequest: args.explicitUserRequest,
+  });
+}
+
+function setupArgs(args: AgentComputerToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'setup_item',
+    setupItemId: 'browser-desktop-control',
+    includeParameters: args.includeParameters ?? true,
+  });
+}
+
+function mcpArgs(args: AgentComputerToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'mcp_servers',
+    query: args.query ?? args.target ?? 'browser desktop',
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentComputerTool(deps: AgentComputerToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'computer',
+      description: 'Inspect/open browser, desktop, and computer-use routes.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'plan', 'control', 'browser', 'open_browser', 'setup', 'mcp'],
+            description: 'Computer, browser/PWA, setup, MCP, or confirmed open route.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          target: { type: 'string', description: 'Lookup or search target.' },
+          query: { type: 'string', description: 'Search text for MCP review.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed route contracts.' },
+          confirm: { type: 'boolean', description: 'Required true for visible open actions.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing a visible open action.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentComputerToolArgs;
+      const action = readAction(args);
+      if (!action) return error('Unknown computer action. Use action:"status" for browser/desktop control posture.');
+
+      if (action === 'status' || action === 'control') return harnessTool.execute(controlArgs(args));
+      if (action === 'plan') return harnessTool.execute(planArgs(args));
+      if (action === 'browser') return harnessTool.execute(browserArgs(args));
+      if (action === 'open_browser') return harnessTool.execute(openBrowserArgs(args));
+      if (action === 'setup') return harnessTool.execute(setupArgs(args));
+      if (action === 'mcp') return harnessTool.execute(mcpArgs(args));
+
+      return error('Unknown computer action. Use action:"status" for browser/desktop control posture.');
+    },
+  };
+}
+
+export function registerAgentComputerTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('computer')) registry.register(createAgentComputerTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -37,13 +37,13 @@ const CONTEXT_TOOL_FALLBACK = {
   preferredTool: 'agent_harness',
   routes: {
     summary: 'agent_harness mode:"summary"',
-    capabilities: 'agent_harness mode:"summary" includeParameters:true',
+    capabilities: 'goodvibes_context mode:"capabilities"',
     tools: 'agent_harness mode:"tools"',
     tool: 'agent_harness mode:"tool"',
-    settings: 'agent_harness mode:"settings"',
-    commands: 'agent_harness mode:"commands"',
-    workspace: 'agent_harness mode:"workspace"',
-    status: 'agent_harness mode:"connected_host_status"',
+    settings: 'settings action:"list"',
+    commands: 'workspace action:"commands"',
+    workspace: 'workspace action:"status"',
+    status: 'host action:"status"',
   },
 };
 
@@ -71,6 +71,8 @@ export function wrapAgentContextToolForAgentPolicy(tool: Tool, registry?: ToolRe
   tool.execute = async (rawArgs) => {
     const args = rawArgs as AgentContextArgs;
     const mode = readAgentContextMode(args.mode);
+    if (mode === 'capabilities') return ok(buildAgentCapabilitiesContract(registry));
+
     const harnessMode = agentContextModeToHarnessMode(mode);
     const harnessTool = registry?.list().find((entry) => entry.definition.name === 'agent_harness');
     if (!harnessTool) {
@@ -93,7 +95,7 @@ export function wrapAgentContextToolForAgentPolicy(tool: Tool, registry?: ToolRe
       category: args.category,
       prefix: args.prefix,
       includeHidden: args.includeHidden,
-      includeParameters: mode === 'capabilities' ? true : args.includeParameters,
+      includeParameters: args.includeParameters,
       limit: args.limit,
     };
     const result = await harnessTool.execute(dropUndefined(harnessArgs));
@@ -116,7 +118,6 @@ function readAgentContextMode(value: unknown): AgentContextMode {
 }
 
 function agentContextModeToHarnessMode(mode: AgentContextMode): string {
-  if (mode === 'capabilities') return 'summary';
   if (mode === 'modes') return 'modes';
   if (mode === 'tools') return 'tools';
   if (mode === 'tool') return 'tool';
@@ -129,6 +130,135 @@ function agentContextModeToHarnessMode(mode: AgentContextMode): string {
   return 'summary';
 }
 
+function buildAgentCapabilitiesContract(registry?: ToolRegistry): Record<string, unknown> {
+  const availableTools = new Set(safeToolNames(registry));
+  const has = (name: string) => availableTools.has(name);
+  const optionalTool = (name: string) => has(name) ? name : `${name} (not registered)`;
+
+  return {
+    runtime: 'GoodVibes Agent',
+    answerStyle: 'Answer user capability questions from this contract. Do not dump inventory counts.',
+    currentContract: {
+      autonomy: 'User-directed operator agent. It can inspect, plan, edit, run tools, and perform confirmed effects; it is not an unrestricted background account-creation or self-expansion agent.',
+      confirmations: 'External sends, reminders, media generation, settings writes, slash-command execution, workspace actions, packet preset saves, and operator actions require an explicit user request plus confirm:true where the tool requires it.',
+      secrets: 'Do not reveal raw secrets. Use configured secret refs, provider accounts, and channel readiness routes.',
+    },
+    canDoNow: [
+      {
+        area: 'Project and computer work',
+        can: 'Read, search, analyze, edit, and write workspace files; run bounded shell commands; inspect diffs and project structure; recover recent file edit/write snapshots.',
+        tools: ['read', 'find', 'analyze', 'inspect', 'edit', 'write', 'exec', optionalTool('execution'), optionalTool('delegation')].filter(has),
+        inspect: 'execution action:"status"; delegation action:"status"',
+      },
+      {
+        area: 'Web research',
+        can: has('web_search')
+          ? 'Brief multi-step research from one read-only queue, plan routes, search the web with bounded evidence, inspect URLs, capture candidate sources in a local review queue, and summarize sourced findings in the main conversation.'
+          : 'Web research is not available until the web_search tool is registered.',
+        tools: [optionalTool('research'), optionalTool('agent_harness'), optionalTool('web_search'), optionalTool('fetch'), optionalTool('agent_research_runs'), optionalTool('agent_research_sources'), optionalTool('agent_research_report')],
+        inspect: 'research action:"briefing" query:"<research request>", action:"plan" for route planning, action:"search" for public source candidates, or action:"runner" for browser-backed readiness',
+      },
+      {
+        area: 'Harness operation',
+        can: 'Discover and use harness modes, slash commands, workspace actions, settings, panels, UI surfaces, keybindings, and model tools.',
+        tools: [optionalTool('agent_harness'), optionalTool('host'), optionalTool('settings'), 'goodvibes_context'],
+        inspect: 'agent_harness mode:"modes" query:"capability"',
+      },
+      {
+        area: 'Memory and knowledge',
+        can: 'Use VIBE.md personality files, Agent-local memory, notes, personas, skills, routines, prompt-context inspection, memory/vector posture, learning curator review/proposal queues, confirmed duplicate-consolidation phase helpers, work plans, and isolated Agent Knowledge ask/search/ingest routes.',
+        tools: [optionalTool('vibe'), optionalTool('context'), optionalTool('memory'), optionalTool('agent_harness'), optionalTool('agent_local_registry'), optionalTool('agent_learning_consolidation'), optionalTool('agent_work_plan'), optionalTool('agent_knowledge'), optionalTool('agent_knowledge_ingest')],
+        inspect: 'vibe action:"status"; context action:"prompt|files"; memory action:"status|curator"',
+      },
+      {
+        area: 'Personal operations',
+        can: 'Turn inbox, agenda, task, reminder, note, routine, or delivery requests into the safest visible lane, route, required fields, and confirmation boundary, then inspect the broader operations map without inventing missing connectors.',
+        tools: [optionalTool('personal_ops'), optionalTool('autonomy'), optionalTool('agent_harness'), optionalTool('agent_local_registry'), optionalTool('agent_work_plan'), optionalTool('schedule'), optionalTool('agent_autonomy_schedule'), optionalTool('agent_reminder_schedule'), optionalTool('agent_schedule_edit'), optionalTool('agent_channel_send')],
+        inspect: 'personal_ops action:"queue" for saved inbox/calendar review queues, action:"intake" query:"<personal request>", or action:"status"',
+      },
+      {
+      area: 'Documents and artifacts',
+      can: 'Create, revise, version, review, comment on, suggest changes to, attach or insert saved artifacts into, export Agent document drafts with reviewer appendices, inspect reviewer-readiness preflight, save reusable review packet presets, and share confirmed reviewer packet archive references; browse saved artifacts; track visible research run checkpoints; capture and review research source queues; save sourced research report artifacts; promote reviewed artifacts into isolated Agent Knowledge; handle uploads, source checks, generated media artifacts, and run confirmed blind model comparisons from prompts or saved text artifacts with durable review, side-by-side views, section-jump reviewer handoff diffs, judgment, task/document/benchmark-filtered analytics/synthesis, reviewer handoff, handoff archive with matching route-decision receipt evidence, route-update actions, and leave-unchanged route-decision receipts.',
+      tools: [optionalTool('research'), optionalTool('agent_harness'), optionalTool('agent_documents'), optionalTool('agent_review_packet_presets'), optionalTool('agent_review_packet_share'), optionalTool('agent_artifacts'), optionalTool('agent_knowledge'), optionalTool('agent_knowledge_ingest'), optionalTool('agent_media_generate'), optionalTool('agent_model_compare'), optionalTool('agent_research_runs'), optionalTool('agent_research_sources'), optionalTool('agent_research_report')],
+        inspect: 'agent_harness mode:"document_ops"',
+      },
+      {
+        area: 'Configured services and messages',
+        can: 'Inspect configured channel readiness, visible autonomy queue, and send one confirmed message/notification/reminder/media request or create/edit one confirmed autonomous schedule through configured targets.',
+        tools: [optionalTool('autonomy'), optionalTool('device'), optionalTool('agent_channel_send'), optionalTool('agent_notify'), optionalTool('schedule'), optionalTool('agent_autonomy_schedule'), optionalTool('agent_reminder_schedule'), optionalTool('agent_schedule_edit'), optionalTool('agent_media_generate')],
+        inspect: 'channels action:"status|triage|deliveries", autonomy action:"queue", or agent_harness mode:"notifications"',
+      },
+      {
+        area: 'Device, voice, and browser surfaces',
+        can: 'Inspect companion pairing, mobile/PWA, voice/TTS, notification, browser/desktop-control, and unpublished sensor posture without claiming unavailable device APIs; open the connected browser cockpit or TTS pickers only after confirmation.',
+        tools: [optionalTool('computer'), optionalTool('device'), optionalTool('agent_harness'), optionalTool('setup')],
+        inspect: 'computer action:"browser|control|setup|mcp"; device action:"status"; voice posture with device action:"voice"',
+      },
+      {
+        area: 'Provider and setup work',
+        can: 'Inspect provider accounts, subscriptions, model routing, hardware-scored local model cookbook setup plans, confirmed local server checks, confirmed benchmark action routes, setup posture, service posture, connected-host status, and GoodVibes settings import; apply supported settings changes when explicitly requested.',
+        tools: [optionalTool('models'), optionalTool('setup'), optionalTool('host'), optionalTool('settings'), optionalTool('agent_harness'), optionalTool('import_goodvibes_settings')],
+        inspect: 'setup action:"status"; use host action:"status|services|methods" for host diagnostics, models action:"status|local|providers" for model/provider catalogs, and settings action:"list|get" for detailed settings',
+      },
+    ],
+    needsSetupOrIntegration: [
+      'Email inbox triage and replies are not a built-in advertised Agent tool in this package; they require a configured plugin, MCP server, or channel/service connector that exposes inbox and send/reply actions.',
+      'New third-party service signup/account creation is not a built-in autonomous flow. The Agent can help fill instructions and run explicit tools, but it should not use local personal information to create accounts without a user-owned integration and confirmation path.',
+      'Long-running autonomous operation requires an explicit schedule, routine, automation, research run, or connected-host route visible in the autonomy queue. The main conversation does not silently create hidden background jobs.',
+      'New capabilities can come from installed plugins, MCP servers, configured services, or code changes; the Agent should inspect what is installed before claiming a capability exists.',
+    ],
+    commonRoutes: {
+      findCapability: 'agent_harness mode:"modes" query:"<task>"',
+      executionPosture: 'execution action:"status"; inspect one route with action:"route"; use terminal command:"..." background:true confirm:true explicitUserRequest:"..." for visible tracked long-running commands and process action:"list|poll|log|wait|kill|write" to manage them; inspect tracked processes with action:"processes|process", recent work with action:"history|record", and recovery posture with action:"recovery"; prefer local read/edit/exec for the current workspace, delegation action:"status" for isolation/parallel/remote',
+      delegation: 'delegation action:"status"; inspect one route with action:"route" delegationRouteId:"..."; delegated submission uses workspace action:"run" actionId:"delegate-task" or workspace action:"run_command" command:"/delegate ..." only after explicit confirmation',
+      fileRecovery: 'execution action:"recovery"; apply one snapshot with agent_harness mode:"run_file_recovery" recoveryAction:"undo|redo" confirm:true explicitUserRequest:"..."',
+      personalOps: 'personal_ops action:"briefing"; use action:"queue" for saved inbox/calendar review queues and refresh routes; use action:"intake" query:"<personal request>" to choose the safest lane; inspect one lane with action:"lane" laneId:"..."; run one live inbox/calendar read with action:"read" confirm:true explicitUserRequest:"..."; use schedule action:"list|create|remind|edit|run|pause|resume|delete" for connected schedules/reminders after explicit confirmation',
+      promptContext: 'context action:"prompt"; add includeParameters:true only when bounded prompt previews are needed; inspect context files with action:"files|file" and receipts with action:"receipts|receipt"',
+      memoryPosture: 'memory action:"status"; inspect one embedding or external-memory provider with action:"provider"; write/rebuild/change routes stay confirmed',
+      autonomyIntake: 'autonomy action:"intake" query:"<ongoing work request>"; use returned route and missing fields before creating background work',
+      autonomyQueue: 'autonomy action:"queue"; inspect one card with action:"item"; use returned live records/log tails when present',
+      setup: 'setup action:"status"; inspect one row with action:"item" setupItemId:"..."; use action:"checkpoint"; confirmed effects use action:"save_checkpoint|clear_checkpoint|token|smoke|finish|import_settings" confirm:true explicitUserRequest:"..."',
+      vibe: 'vibe action:"status"; inspect one file with action:"show" scope:"project|global"; confirmed effects use action:"init|import_persona" confirm:true explicitUserRequest:"..."',
+      settings: 'settings action:"list"; inspect one setting with action:"get" key:"..."; confirmed changes use action:"set|reset" confirm:true explicitUserRequest:"..."; import existing GoodVibes settings with action:"import" and confirm:true only after approval',
+      host: 'host action:"status"; inspect capabilities/services/methods with action:"capabilities|capability|services|service|methods|method"; execute exact daemon operations separately with agent_operator_method after confirmation',
+      settingsImport: 'settings action:"import"; previews by default and applies with confirm:true explicitUserRequest:"..." after user approval; import_goodvibes_settings remains available for compatibility',
+      computer: 'computer action:"status|plan|control|browser|setup|mcp"; open the connected browser cockpit with action:"open_browser" confirm:true explicitUserRequest:"..."; use this route for browser/PWA, browser/screenshot/desktop-control planning, screen, and computer-use posture',
+      device: 'device action:"status"; inspect one capability/route with action:"capability" capabilityId:"..."; inspect voice/media with action:"voice"; inspect one provider with action:"provider"; browser/PWA and desktop-control compatibility routes remain available but computer is the primary route',
+      models: 'models action:"status"; inspect one model/local endpoint route with action:"route" modelRouteId:"..."; inspect local cookbook with action:"local"; inspect providers with action:"providers"; inspect one provider with action:"provider" providerId:"..."; run local model server checks with action:"smoke" confirm:true explicitUserRequest:"..."',
+      learningCurator: 'memory action:"curator"; inspect one card with action:"candidate"; apply duplicate phases with agent_learning_consolidation mode:"preview|merge|stale|delete|rollback"',
+      documentOps: 'agent_harness mode:"document_ops"; inspect one lane with mode:"document_ops_lane"',
+      documents: 'agent_documents mode:"list"; show with documentId; confirmed create/update/review/comment/resolveComment/suggest/acceptSuggestion/rejectSuggestion/attachArtifact/insertArtifact/export with confirm:true',
+      reviewPacketPresets: 'agent_review_packet_presets mode:"list"; show with artifactId to check missing/superseded ids and reuse routes; refresh stale presets with mode:"refresh" confirm:true explicitUserRequest:"..."; save reusable packet defaults with mode:"save" confirm:true explicitUserRequest:"..."',
+      reviewPacketShare: 'agent_review_packet_share archiveArtifactId:"..." channel:"..." confirm:true explicitUserRequest:"..."; sends a plain-text archive reference only',
+      artifacts: 'agent_artifacts mode:"list"; inspect with mode:"show"; export one with mode:"export"; package selected ids with mode:"package" or mode:"archive"; promote reviewed artifact ids with agent_knowledge_ingest sourceKind:"artifact"',
+      researchWorkflow: 'research action:"briefing" query:"<research request>"; returns one read-only next-action queue across visible runs, sources, saved reports, browser readiness, and exact follow-up routes. Use action:"plan" for route planning, action:"search" for bounded public source candidates, and action:"runner" for browser-backed readiness only',
+      researchRuns: 'research action:"runs"; create visible run state with action:"create_run" confirm:true explicitUserRequest:"..."; checkpoint/pause/resume/cancel/complete use confirmed research lifecycle actions; no hidden background work starts from the ledger',
+      researchSources: 'research action:"sources"; capture with action:"add_source" confirm:true explicitUserRequest:"..."; review with action:"review_source" confirm:true explicitUserRequest:"..."; bundle with action:"bundle"; no Knowledge ingest occurs unless agent_knowledge_ingest is called separately',
+      researchReports: 'research action:"reports" lists saved sourced report artifacts; action:"report_artifact" previews one; save with action:"report" reviewed sources, citation coverage repair metadata, optional requireCitationCoverage:true, confirm:true, and explicitUserRequest',
+      localModelCookbook: 'models action:"local"; inspect hardware fit with action:"route" modelRouteId:"local-model-cookbook"; confirmed local server checks use action:"smoke" confirm:true explicitUserRequest:"..."',
+      listTools: 'agent_harness mode:"tools" query:"<task>"',
+      inspectTool: 'agent_harness mode:"tool" toolName:"<tool>"',
+      listCommands: 'workspace action:"commands" query:"<task>"',
+      runCommand: 'workspace action:"run_command" command:"/<command> ..." confirm:true explicitUserRequest:"..."',
+      listWorkspaceActions: 'workspace action:"actions" query:"<task>"',
+      runWorkspaceAction: 'workspace action:"run" actionId:"<id>" confirm:true explicitUserRequest:"..."',
+      inspectSettings: 'settings action:"list" query:"<setting>"',
+      setSetting: 'settings action:"set" key:"<key>" value:<value> confirm:true explicitUserRequest:"..."',
+      webResearch: `multi-step: research action:"briefing" query:"<research request>"; route plan: research action:"plan" query:"<research request>"; public source candidates: research action:"search" query:"<research request>"; browser readiness: research action:"runner"; raw single-shot fallback: ${has('web_search') ? 'web_search query:"<research request>" verbosity:"evidence" maxResults:10 evidenceTopN:3' : 'web_search not registered'}`,
+      channels: 'channels action:"status|channel|setup|triage|deliveries"; send with agent_channel_send only after explicit user request',
+    },
+    registeredModelTools: safeToolNames(registry),
+  };
+}
+
+function safeToolNames(registry?: ToolRegistry): readonly string[] {
+  try {
+    return registry?.getToolDefinitions().map((tool) => tool.name).sort((a, b) => a.localeCompare(b)) ?? [];
+  } catch {
+    return [];
+  }
+}
+
 function dropUndefined<T extends Record<string, unknown>>(value: T): Record<string, unknown> {
   return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
 }

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 }));
+}