@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/src/tools/agent-media-generate-tool.ts

@@ -0,0 +1,133 @@
+import type { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { MediaProviderRegistry } from '@pellux/goodvibes-sdk/platform/media';
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import {
+  formatAgentMediaGenerationResult,
+  generateAgentMedia,
+} from '../agent/media-generation.ts';
+
+export interface AgentMediaGenerateToolArgs {
+  readonly prompt?: unknown;
+  readonly providerId?: unknown;
+  readonly modelId?: unknown;
+  readonly outputMimeType?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+function failure(error: string): { readonly success: false; readonly error: string } {
+  return { success: false, error };
+}
+
+function output(text: string): { readonly success: true; readonly output: string } {
+  return { success: true, output: text };
+}
+
+function preview(args: AgentMediaGenerateToolArgs, providerCount: number): string {
+  const prompt = readString(args.prompt);
+  return [
+    'Agent media generation preview',
+    `  prompt ${prompt || '(missing)'}`,
+    `  provider ${readString(args.providerId) || '(auto)'}`,
+    `  model ${readString(args.modelId) || '(provider default)'}`,
+    `  output mime ${readString(args.outputMimeType) || '(provider default)'}`,
+    `  generation providers ${providerCount}`,
+    '  policy media generation requires an explicit user request and confirm:true',
+  ].join('\n');
+}
+
+export function createAgentMediaGenerateTool(
+  mediaProviderRegistry: MediaProviderRegistry,
+  artifactStore: Pick<ArtifactStore, 'create'>,
+): Tool {
+  return {
+    definition: {
+      name: 'agent_media_generate',
+      description: [
+        'Generate image or video artifacts through configured GoodVibes Agent media providers from the main conversation.',
+        'Use only when the user explicitly asks Agent to generate media.',
+        'Generated bytes are stored as GoodVibes artifacts and the response returns artifact ids; do not print inline base64.',
+        'This tool does not use default knowledge, non-Agent knowledge segments, connected-host lifecycle routes, separate Agent jobs, delegated review, channel sends, or arbitrary route invocation.',
+        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+      ].join(' '),
+      parameters: {
+        type: 'object',
+        properties: {
+          prompt: {
+            type: 'string',
+            description: 'Media generation prompt.',
+          },
+          providerId: {
+            type: 'string',
+            description: 'Optional configured media provider id. If omitted, the first generation-capable provider is used.',
+          },
+          modelId: {
+            type: 'string',
+            description: 'Optional provider-specific media model id.',
+          },
+          outputMimeType: {
+            type: 'string',
+            description: 'Optional requested output MIME type, such as image/png or video/mp4.',
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Required true only when the user explicitly asked for this media generation.',
+          },
+          explicitUserRequest: {
+            type: 'string',
+            description: 'Short quote or summary of the user request that authorized this generation.',
+          },
+        },
+        required: ['prompt', 'confirm', 'explicitUserRequest'],
+        additionalProperties: false,
+      },
+      sideEffects: ['network', 'state'],
+    },
+    execute: async (rawArgs: Record<string, unknown>) => {
+      const args = rawArgs as AgentMediaGenerateToolArgs;
+      const prompt = readString(args.prompt);
+      const explicitUserRequest = readString(args.explicitUserRequest);
+      const generationProviderCount = mediaProviderRegistry.list()
+        .filter((provider) => provider.capabilities.includes('generate')).length;
+      if (!prompt) return failure('prompt is required.');
+      if (!explicitUserRequest) {
+        return failure('explicitUserRequest is required so media generation stays tied to a direct user request.');
+      }
+      if (!readBoolean(args.confirm)) {
+        return failure([
+          preview(args, generationProviderCount),
+          '',
+          'Model tool confirmation required. Call this tool with confirm:true only when the user explicitly asked GoodVibes Agent to generate this media.',
+        ].join('\n'));
+      }
+      try {
+        const result = await generateAgentMedia(mediaProviderRegistry, artifactStore, {
+          prompt,
+          ...(readString(args.providerId) ? { providerId: readString(args.providerId) } : {}),
+          ...(readString(args.modelId) ? { modelId: readString(args.modelId) } : {}),
+          ...(readString(args.outputMimeType) ? { outputMimeType: readString(args.outputMimeType) } : {}),
+        });
+        return output(formatAgentMediaGenerationResult(result));
+      } catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+      }
+    },
+  };
+}
+
+export function registerAgentMediaGenerateTool(
+  registry: ToolRegistry,
+  mediaProviderRegistry: MediaProviderRegistry,
+  artifactStore: Pick<ArtifactStore, 'create'>,
+): void {
+  registry.register(createAgentMediaGenerateTool(mediaProviderRegistry, artifactStore));
+}

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

@@ -0,0 +1,143 @@
+import type { WebhookNotifierSendResult } from '@pellux/goodvibes-sdk/platform/integrations';
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+
+interface AgentNotificationConfigReader {
+  getCategory(category: string): unknown;
+}
+
+interface AgentNotificationSender {
+  setUrls(urls: string[]): void;
+  send(text: string): Promise<WebhookNotifierSendResult>;
+}
+
+export interface AgentNotifyToolArgs {
+  readonly message?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+function configuredWebhookUrls(configManager: AgentNotificationConfigReader): readonly string[] {
+  const category = configManager.getCategory('notifications');
+  if (!isRecord(category) || !Array.isArray(category.webhookUrls)) return [];
+  return category.webhookUrls
+    .filter((url): url is string => typeof url === 'string')
+    .map((url) => url.trim())
+    .filter((url) => url.length > 0);
+}
+
+function preview(message: string, targetCount: number): string {
+  return [
+    'Agent notification preview',
+    `  message ${message}`,
+    `  configured targets: ${targetCount}`,
+    '  policy external notification delivery requires an explicit user request and confirm:true',
+  ].join('\n');
+}
+
+function formatSendResult(result: WebhookNotifierSendResult): string {
+  const lines = [
+    'Agent notification sent',
+    `  attempted: ${result.attempted}`,
+    `  delivered: ${result.delivered}`,
+    `  failed: ${result.failed}`,
+  ];
+  result.results.slice(0, 20).forEach((delivery, index) => {
+    lines.push(`  target ${index + 1} ${delivery.ok ? 'ok' : `failed${delivery.error ? ` (${delivery.error})` : ''}`}`);
+  });
+  if (result.results.length > 20) lines.push(`  ${result.results.length - 20} more target(s) omitted.`);
+  return lines.join('\n');
+}
+
+function failure(error: string): { readonly success: false; readonly error: string } {
+  return { success: false, error };
+}
+
+function output(text: string): { readonly success: true; readonly output: string } {
+  return { success: true, output: text };
+}
+
+export function createAgentNotifyTool(
+  configManager: AgentNotificationConfigReader,
+  notifier: AgentNotificationSender,
+): Tool {
+  return {
+    definition: {
+      name: 'agent_notify',
+      description: [
+        'Send one plain-text notification to configured GoodVibes Agent webhook notification targets from the main conversation.',
+        'Use only when the user explicitly asks Agent to notify, message, alert, or send a configured notification.',
+        'This uses Agent-local notification webhook targets; it does not create channel routes, authorize accounts, manage connected-host hosting, create separate Agent jobs, run delegated review, or write to default knowledge or non-Agent knowledge segments.',
+        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+      ].join(' '),
+      parameters: {
+        type: 'object',
+        properties: {
+          message: {
+            type: 'string',
+            description: 'Plain-text notification body to send to configured Agent notification webhook targets.',
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Required true only when the user explicitly asked to send this notification.',
+          },
+          explicitUserRequest: {
+            type: 'string',
+            description: 'Short quote or summary of the user request that authorized this external notification.',
+          },
+        },
+        required: ['message', 'confirm', 'explicitUserRequest'],
+        additionalProperties: false,
+      },
+      sideEffects: ['network'],
+    },
+    execute: async (rawArgs: unknown) => {
+      try {
+        const args = rawArgs as AgentNotifyToolArgs;
+        const message = readString(args.message);
+        const explicitUserRequest = readString(args.explicitUserRequest);
+        if (!message) return failure('message is required.');
+        if (!explicitUserRequest) {
+          return failure('explicitUserRequest is required so notification delivery stays tied to a direct user request.');
+        }
+        const urls = configuredWebhookUrls(configManager);
+        if (!readBoolean(args.confirm)) {
+          return failure([
+            preview(message, urls.length),
+            '',
+            'Model tool confirmation required. Call this tool with confirm:true only when the user explicitly asked GoodVibes Agent to send this notification.',
+          ].join('\n'));
+        }
+        if (urls.length === 0) {
+          return failure('No Agent notification webhook targets are configured. Add one from the Channels workspace before sending notifications.');
+        }
+        notifier.setUrls([...urls]);
+        return output(formatSendResult(await notifier.send(message)));
+      } catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+      }
+    },
+  };
+}
+
+export function registerAgentNotifyTool(
+  registry: ToolRegistry,
+  configManager: AgentNotificationConfigReader,
+  notifier: AgentNotificationSender,
+): void {
+  registry.register(createAgentNotifyTool(configManager, notifier));
+}

package/src/tools/agent-operator-action-tool.ts

@@ -0,0 +1,137 @@
+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 type { AgentConnectedHostConfigReader } from '../agent/routine-schedule-promotion.ts';
+import { resolveAgentConnectedHostConnection } from '../agent/routine-schedule-promotion.ts';
+import {
+  buildOperatorActionRequest,
+  formatOperatorActionFailure,
+  formatOperatorActionSuccess,
+  formatOperatorActionToolPreview,
+  isRecord,
+  OPERATOR_ACTIONS,
+  postOperatorAction,
+  readOperatorActionBoolean,
+  readOperatorActionString,
+} from '../agent/operator-actions.ts';
+
+interface OperatorActionToolArgs {
+  readonly action?: unknown;
+  readonly targetId?: unknown;
+  readonly approvalId?: unknown;
+  readonly jobId?: unknown;
+  readonly runId?: unknown;
+  readonly scheduleId?: unknown;
+  readonly note?: unknown;
+  readonly remember?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+export function createAgentOperatorActionTool(
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): Tool {
+  return {
+    definition: {
+      name: 'agent_operator_action',
+      description: [
+        'Perform one explicit, confirmed connected-host operator action from the main conversation.',
+        'Allowed actions are approvals.approve, approvals.deny, approvals.cancel, automation.jobs.run, automation.jobs.pause, automation.jobs.resume, automation.runs.cancel, automation.runs.retry, and schedules.run.',
+        'Use only when the user explicitly asks for that exact approval, automation job, automation run, or schedule action.',
+        'This tool never creates, edits, deletes, or discovers automation definitions; never manages connected-host hosting; never uses default knowledge, non-Agent knowledge segments, separate Agent jobs, delegated review, or arbitrary route invocation.',
+        'Set confirm:true only for an explicit user request. Otherwise return the preview/confirmation error.',
+      ].join(' '),
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: Object.keys(OPERATOR_ACTIONS),
+            description: 'Exact allowlisted public operator method id to execute.',
+          },
+          targetId: {
+            type: 'string',
+            description: 'Generic target id. Prefer the specific approvalId, jobId, runId, or scheduleId field when known.',
+          },
+          approvalId: {
+            type: 'string',
+            description: 'Approval id for approvals.approve, approvals.deny, or approvals.cancel.',
+          },
+          jobId: {
+            type: 'string',
+            description: 'Automation job id for automation.jobs.run, automation.jobs.pause, or automation.jobs.resume.',
+          },
+          runId: {
+            type: 'string',
+            description: 'Automation run id for automation.runs.cancel or automation.runs.retry.',
+          },
+          scheduleId: {
+            type: 'string',
+            description: 'Schedule id for schedules.run.',
+          },
+          note: {
+            type: 'string',
+            description: 'Optional approval note for approval actions.',
+          },
+          remember: {
+            type: 'boolean',
+            description: 'Optional approval remember flag for approval actions only.',
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Required true only when the user explicitly asked for this exact operator action.',
+          },
+          explicitUserRequest: {
+            type: 'string',
+            description: 'Short quote or summary of the user request that authorized this action.',
+          },
+        },
+        required: ['action', 'confirm', 'explicitUserRequest'],
+        additionalProperties: false,
+      },
+      sideEffects: ['network', 'state'],
+    },
+    execute: async (rawArgs: unknown) => {
+      const request = buildOperatorActionRequest(rawArgs);
+      if (!request.ok) {
+        return { success: false, error: request.error };
+      }
+      const args = isRecord(rawArgs) ? rawArgs as OperatorActionToolArgs : {};
+      const explicitUserRequest = readOperatorActionString(args.explicitUserRequest);
+      if (!explicitUserRequest) {
+        return {
+          success: false,
+          error: formatOperatorActionToolPreview(request, ''),
+        };
+      }
+      if (!readOperatorActionBoolean(args.confirm)) {
+        return {
+          success: false,
+          error: formatOperatorActionToolPreview(request, explicitUserRequest),
+        };
+      }
+      const connection = resolveAgentConnectedHostConnection(configManager, shellPaths.homeDirectory);
+      if (!connection.token) {
+        return {
+          success: false,
+          error: `auth_required: no connected-host operator token found at ${connection.tokenPath}`,
+        };
+      }
+      const result = await postOperatorAction(connection, request);
+      if (!result.ok) return { success: false, error: formatOperatorActionFailure(result) };
+      return {
+        success: true,
+        output: formatOperatorActionSuccess(connection.baseUrl, result),
+      };
+    },
+  };
+}
+
+export function registerAgentOperatorActionTool(
+  registry: ToolRegistry,
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): void {
+  registry.register(createAgentOperatorActionTool(shellPaths, configManager));
+}

package/src/tools/agent-operator-briefing-tool.ts

@@ -0,0 +1,217 @@
+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 type { AgentConnectedHostConfigReader } from '../agent/routine-schedule-promotion.ts';
+import { resolveAgentConnectedHostConnection } from '../agent/routine-schedule-promotion.ts';
+
+type JsonRecord = Record<string, unknown>;
+
+interface OperatorRouteDescriptor {
+  readonly id: string;
+  readonly path: string;
+}
+
+interface OperatorRouteSuccess {
+  readonly ok: true;
+  readonly route: OperatorRouteDescriptor;
+  readonly body: unknown;
+}
+
+interface OperatorRouteFailure {
+  readonly ok: false;
+  readonly route: OperatorRouteDescriptor;
+  readonly kind: 'auth_required' | 'connected_host_unavailable' | 'connected_host_route_unavailable' | 'connected_host_error';
+  readonly error: string;
+}
+
+type OperatorRouteResult = OperatorRouteSuccess | OperatorRouteFailure;
+
+const OPERATOR_BRIEFING_ROUTES: readonly OperatorRouteDescriptor[] = [
+  { id: 'projectPlanning.workPlan.snapshot', path: '/api/projects/planning/work-plan' },
+  { id: 'approvals.list', path: '/api/approvals' },
+  { id: 'automation.integration.snapshot', path: '/api/automation' },
+  { id: 'schedules.list', path: '/api/automation/schedules' },
+  { id: 'scheduler.capacity', path: '/api/runtime/scheduler' },
+] as const;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readRecord(value: unknown, key: string): JsonRecord {
+  return isRecord(value) && isRecord(value[key]) ? value[key] as JsonRecord : {};
+}
+
+function readArray(value: unknown, key: string): readonly unknown[] {
+  return isRecord(value) && Array.isArray(value[key]) ? value[key] : [];
+}
+
+function readNumber(value: unknown, key: string): number | null {
+  if (!isRecord(value)) return null;
+  const candidate = value[key];
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : null;
+}
+
+function readString(value: unknown, key: string): string | null {
+  if (!isRecord(value)) return null;
+  const candidate = value[key];
+  return typeof candidate === 'string' ? candidate : null;
+}
+
+function summarizeFetchError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function readResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function classifyHttpFailure(route: OperatorRouteDescriptor, status: number, body: unknown): OperatorRouteFailure {
+  const detail = isRecord(body) && typeof body.error === 'string' ? body.error : '';
+  return {
+    ok: false,
+    route,
+    kind: status === 401 || status === 403
+      ? 'auth_required'
+      : status === 404
+        ? 'connected_host_route_unavailable'
+        : 'connected_host_error',
+    error: `HTTP ${status}${detail ? `: ${detail}` : ''}`,
+  };
+}
+
+async function fetchOperatorRoute(
+  baseUrl: string,
+  token: string,
+  route: OperatorRouteDescriptor,
+): Promise<OperatorRouteResult> {
+  try {
+    const response = await fetch(`${baseUrl}${route.path}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    const body = await readResponseBody(response);
+    if (!response.ok) return classifyHttpFailure(route, response.status, body);
+    return { ok: true, route, body };
+  } catch (error) {
+    return {
+      ok: false,
+      route,
+      kind: 'connected_host_unavailable',
+      error: summarizeFetchError(error),
+    };
+  }
+}
+
+function formatWorkPlan(body: unknown): string {
+  const counts = readRecord(body, 'counts');
+  const total = readNumber(counts, 'total') ?? readArray(body, 'tasks').length;
+  return `  work plan: total ${total}; pending ${readNumber(counts, 'pending') ?? 0}; active ${readNumber(counts, 'in_progress') ?? 0}; blocked ${readNumber(counts, 'blocked') ?? 0}; done ${readNumber(counts, 'done') ?? 0}`;
+}
+
+function formatApprovals(body: unknown): string {
+  const approvals = readArray(body, 'approvals');
+  const pending = approvals.filter((entry) => readString(entry, 'status') === 'pending').length;
+  return `  approvals: pending ${pending}; total ${approvals.length}; mode ${readString(body, 'mode') ?? 'unknown'}; awaiting decision ${readString(body, 'awaitingDecision') ?? String(Boolean(isRecord(body) && body.awaitingDecision))}`;
+}
+
+function formatAutomation(body: unknown): string {
+  const totals = readRecord(body, 'totals');
+  const jobs = readNumber(totals, 'jobs') ?? readArray(body, 'jobs').length;
+  return `  automation: jobs ${jobs}; enabled ${readNumber(totals, 'enabled') ?? 0}; paused ${readNumber(totals, 'paused') ?? 0}; recent runs ${readNumber(totals, 'runs') ?? readArray(body, 'recentRuns').length}`;
+}
+
+function formatSchedules(body: unknown): string {
+  const jobs = readArray(body, 'jobs');
+  const runs = readArray(body, 'runs');
+  const enabled = jobs.filter((entry) => isRecord(entry) && entry.enabled === true).length;
+  return `  schedules: jobs ${jobs.length}; enabled ${enabled}; runs ${runs.length}`;
+}
+
+function formatCapacity(body: unknown): string {
+  return `  scheduler: slots ${readNumber(body, 'slotsInUse') ?? 0}/${readNumber(body, 'slotsTotal') ?? 0}; queue ${readNumber(body, 'queueDepth') ?? 0}; oldest queued ms ${readNumber(body, 'oldestQueuedAgeMs') ?? 0}`;
+}
+
+function formatRouteFailureKind(kind: OperatorRouteFailure['kind']): string {
+  if (kind === 'auth_required') return 'authorization required';
+  if (kind === 'connected_host_unavailable') return 'connected host unavailable';
+  if (kind === 'connected_host_route_unavailable') return 'connected host route unavailable';
+  return 'connected host error';
+}
+
+function formatRoute(result: OperatorRouteResult): string {
+  if (!result.ok) return `  ${result.route.id}: unavailable (${result.kind}; ${result.error})`;
+  if (result.route.id === 'projectPlanning.workPlan.snapshot') return formatWorkPlan(result.body);
+  if (result.route.id === 'approvals.list') return formatApprovals(result.body);
+  if (result.route.id === 'automation.integration.snapshot') return formatAutomation(result.body);
+  if (result.route.id === 'schedules.list') return formatSchedules(result.body);
+  return formatCapacity(result.body);
+}
+
+function formatBriefing(baseUrl: string, results: readonly OperatorRouteResult[]): string {
+  const failures = results.filter((result): result is OperatorRouteFailure => !result.ok);
+  return [
+    'Agent operator briefing',
+    `  connected host ${baseUrl}`,
+    '  policy read-only public operator routes; no connected-host lifecycle, mutation routes, separate Agent jobs, delegated review, default knowledge, or non-Agent knowledge segments',
+    '',
+    ...results.map(formatRoute),
+    '',
+    failures.length === 0
+      ? '  warnings: none'
+      : `  warnings: ${failures.length} route(s) unavailable; retry after host/auth/version repair`,
+  ].join('\n');
+}
+
+export function createAgentOperatorBriefingTool(
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): Tool {
+  return {
+    definition: {
+      name: 'agent_operator_briefing',
+      description: [
+        'Read connected GoodVibes operator state for a concise main-conversation briefing.',
+        'Use when the user asks what needs attention, what is pending, what is scheduled, or what the operator status is.',
+        'This is read-only and calls only public work-plan, approvals, automation, schedules, and scheduler routes.',
+        'It never uses default knowledge, non-Agent knowledge segments, channel send routes, mutation routes, connected-host lifecycle, separate Agent jobs, or delegated review.',
+      ].join(' '),
+      parameters: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+      sideEffects: ['network'],
+    },
+    execute: async () => {
+      const connection = resolveAgentConnectedHostConnection(configManager, shellPaths.homeDirectory);
+      if (!connection.token) {
+        return {
+          success: false,
+          error: `auth_required: no connected-host operator token found at ${connection.tokenPath}`,
+        };
+      }
+      const results: OperatorRouteResult[] = [];
+      for (const route of OPERATOR_BRIEFING_ROUTES) {
+        results.push(await fetchOperatorRoute(connection.baseUrl, connection.token, route));
+      }
+      return {
+        success: true,
+        output: formatBriefing(connection.baseUrl, results),
+      };
+    },
+  };
+}
+
+export function registerAgentOperatorBriefingTool(
+  registry: ToolRegistry,
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): void {
+  registry.register(createAgentOperatorBriefingTool(shellPaths, configManager));
+}