@pellux/goodvibes-agent 0.1.0

package/src/shell/service-settings-sync.ts

@@ -0,0 +1,273 @@
+import { mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
+import type { ManagedServiceStatus } from '@pellux/goodvibes-sdk/platform/daemon';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import {
+  createPlatformServiceManager,
+  getServiceStateRoot,
+  type CliServiceRuntime,
+} from '../cli/service-posture.ts';
+
+type ManagedServiceAction = 'install' | 'uninstall' | 'start' | 'stop' | 'restart' | 'status';
+
+export interface ServiceManagerLike {
+  status(): ManagedServiceStatus;
+  install(): ManagedServiceStatus;
+  uninstall(): ManagedServiceStatus;
+  start(): ManagedServiceStatus;
+  stop(): ManagedServiceStatus;
+  restart(): ManagedServiceStatus;
+}
+
+export interface CommandResult {
+  readonly status: number | null;
+  readonly stdout?: string;
+  readonly stderr?: string;
+}
+
+export interface ServiceSettingsSyncChange {
+  readonly key: ConfigKey;
+  readonly previousValue: unknown;
+  readonly value: unknown;
+}
+
+export interface ServiceSettingsSyncResult {
+  readonly handled: boolean;
+  readonly action?: ManagedServiceAction | 'install-start' | 'disable';
+  readonly status?: ManagedServiceStatus;
+  readonly message?: string;
+  readonly error?: string;
+}
+
+export interface ServiceSettingsSyncOptions {
+  readonly createManager?: (runtime: CliServiceRuntime) => ServiceManagerLike;
+  readonly runCommand?: (command: string, args: readonly string[]) => CommandResult;
+  readonly mkdir?: typeof mkdirSync;
+}
+
+const SERVICE_DEFINITION_KEYS = new Set<ConfigKey>([
+  'service.restartOnFailure',
+  'service.platform',
+  'service.serviceName',
+  'service.logPath',
+] as ConfigKey[]);
+
+function runCommand(command: string, args: readonly string[], options: ServiceSettingsSyncOptions): CommandResult {
+  if (options.runCommand) return options.runCommand(command, args);
+  return spawnSync(command, [...args], { stdio: 'pipe', encoding: 'utf-8' });
+}
+
+function commandError(result: CommandResult): string | null {
+  if ((result.status ?? 1) === 0) return null;
+  return ((result.stderr ?? '') || (result.stdout ?? '') || `command exited with ${result.status}`).trim();
+}
+
+function serviceName(runtime: CliServiceRuntime, fallback = 'goodvibes'): string {
+  return String(runtime.configManager.get('service.serviceName') ?? fallback).trim() || fallback;
+}
+
+function runSystemd(runtime: CliServiceRuntime, args: readonly string[], options: ServiceSettingsSyncOptions): string | null {
+  const result = runCommand('systemctl', ['--user', ...args], options);
+  return commandError(result);
+}
+
+function reloadSystemdIfNeeded(
+  runtime: CliServiceRuntime,
+  status: ManagedServiceStatus,
+  options: ServiceSettingsSyncOptions,
+): string | null {
+  if (status.platform !== 'systemd') return null;
+  return runSystemd(runtime, ['daemon-reload'], options);
+}
+
+function disableSystemService(
+  runtime: CliServiceRuntime,
+  manager: ServiceManagerLike,
+  options: ServiceSettingsSyncOptions,
+): ServiceSettingsSyncResult {
+  const before = manager.status();
+  let disableError: string | null = null;
+  if (before.platform === 'systemd') {
+    disableError = before.installed || before.running
+      ? runSystemd(runtime, ['disable', '--now', `${serviceName(runtime)}.service`], options)
+      : null;
+    if (disableError) {
+      logger.warn('Settings service sync: systemd disable failed', { error: disableError });
+    }
+  } else if (before.running || before.installed) {
+    const stopped = manager.stop();
+    if (stopped.actionError) {
+      return {
+        handled: true,
+        action: 'stop',
+        status: stopped,
+        message: `Service disable failed: ${stopped.actionError}`,
+        error: stopped.actionError,
+      };
+    }
+  }
+
+  const uninstalled = manager.uninstall();
+  const reloadError = reloadSystemdIfNeeded(runtime, uninstalled, options);
+  const error = uninstalled.actionError ?? reloadError ?? disableError ?? undefined;
+  return {
+    handled: true,
+    action: 'disable',
+    status: uninstalled,
+    message: error ? `Service disable failed: ${error}` : 'OS service disabled',
+    ...(error ? { error } : {}),
+  };
+}
+
+function installAndStartSystemService(
+  runtime: CliServiceRuntime,
+  manager: ServiceManagerLike,
+  options: ServiceSettingsSyncOptions,
+): ServiceSettingsSyncResult {
+  (options.mkdir ?? mkdirSync)(getServiceStateRoot(runtime), { recursive: true });
+  const installed = manager.install();
+  if (installed.actionError) {
+    return {
+      handled: true,
+      action: 'install',
+      status: installed,
+      message: `Service install failed: ${installed.actionError}`,
+      error: installed.actionError,
+    };
+  }
+
+  const reloadError = reloadSystemdIfNeeded(runtime, installed, options);
+  if (reloadError) {
+    return {
+      handled: true,
+      action: 'install',
+      status: installed,
+      message: `Service install failed: ${reloadError}`,
+      error: reloadError,
+    };
+  }
+
+  const started = manager.start();
+  const error = started.actionError ?? undefined;
+  return {
+    handled: true,
+    action: 'install-start',
+    status: started,
+    message: error ? `Service start failed: ${error}` : 'OS service installed and started',
+    ...(error ? { error } : {}),
+  };
+}
+
+function refreshInstalledSystemService(
+  runtime: CliServiceRuntime,
+  manager: ServiceManagerLike,
+  options: ServiceSettingsSyncOptions,
+): ServiceSettingsSyncResult {
+  const before = manager.status();
+  if (!before.installed && runtime.configManager.get('service.autostart') !== true) {
+    return {
+      handled: true,
+      action: 'status',
+      status: before,
+      message: 'Service setting saved',
+    };
+  }
+
+  const installed = manager.install();
+  if (installed.actionError) {
+    return {
+      handled: true,
+      action: 'install',
+      status: installed,
+      message: `Service update failed: ${installed.actionError}`,
+      error: installed.actionError,
+    };
+  }
+
+  const reloadError = reloadSystemdIfNeeded(runtime, installed, options);
+  if (reloadError) {
+    return {
+      handled: true,
+      action: 'install',
+      status: installed,
+      message: `Service update failed: ${reloadError}`,
+      error: reloadError,
+    };
+  }
+
+  const next = before.running ? manager.restart() : manager.start();
+  const error = next.actionError ?? undefined;
+  return {
+    handled: true,
+    action: before.running ? 'restart' : 'start',
+    status: next,
+    message: error ? `Service update failed: ${error}` : 'OS service updated',
+    ...(error ? { error } : {}),
+  };
+}
+
+export function syncServiceSettingToPlatform(
+  runtime: CliServiceRuntime,
+  change: ServiceSettingsSyncChange,
+  options: ServiceSettingsSyncOptions = {},
+): ServiceSettingsSyncResult {
+  if (!String(change.key).startsWith('service.')) return { handled: false };
+  if (change.previousValue === change.value) return { handled: true, message: 'Service setting unchanged' };
+
+  const manager = options.createManager?.(runtime) ?? createPlatformServiceManager(runtime);
+
+  try {
+    if (change.key === 'service.autostart') {
+      if (change.value === true) {
+        if (runtime.configManager.get('service.enabled') !== true) {
+          runtime.configManager.setDynamic('service.enabled', true);
+        }
+        return installAndStartSystemService(runtime, manager, options);
+      }
+      return disableSystemService(runtime, manager, options);
+    }
+
+    if (change.key === 'service.enabled') {
+      if (change.value === false) {
+        if (runtime.configManager.get('service.autostart') === true) {
+          runtime.configManager.setDynamic('service.autostart', false);
+        }
+        return disableSystemService(runtime, manager, options);
+      }
+      if (runtime.configManager.get('service.autostart') === true) {
+        return installAndStartSystemService(runtime, manager, options);
+      }
+      return {
+        handled: true,
+        action: 'status',
+        status: manager.status(),
+        message: 'Service mode saved; enable autostart to install the OS service',
+      };
+    }
+
+    if (SERVICE_DEFINITION_KEYS.has(change.key)) {
+      if (runtime.configManager.get('service.enabled') === true && runtime.configManager.get('service.autostart') === true) {
+        return refreshInstalledSystemService(runtime, manager, options);
+      }
+      return {
+        handled: true,
+        action: 'status',
+        status: manager.status(),
+        message: 'Service setting saved; enable autostart to install the OS service',
+      };
+    }
+  } catch (error) {
+    const summarized = summarizeError(error);
+    logger.error('Settings service sync failed', { key: change.key, error: summarized });
+    return {
+      handled: true,
+      action: 'status',
+      status: manager.status(),
+      message: `Service sync failed: ${summarized}`,
+      error: summarized,
+    };
+  }
+
+  return { handled: false };
+}

package/src/shell/ui-openers.ts

@@ -0,0 +1,352 @@
+import type { ConfigManager } from '../config/index.ts';
+import { getProviderIdFromModel } from '../config/provider-model.ts';
+import type { ConversationManager } from '../core/conversation';
+import type { CommandContext } from '../input/command-registry.ts';
+import type { InputHandler } from '../input/handler.ts';
+import type { PanelManager } from '../panels/panel-manager.ts';
+import type { ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
+import type { MutableRuntimeState } from '@/runtime/index.ts';
+import type { FeatureFlagManager } from '@/runtime/index.ts';
+import type { McpRegistry } from '@pellux/goodvibes-sdk/platform/mcp';
+import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { SecretsManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { ServiceInspectionQuery } from '../runtime/ui-service-queries.ts';
+import type { ModelPickerTargetInfo } from '../input/model-picker.ts';
+import { syncServiceSettingToPlatform } from './service-settings-sync.ts';
+
+type WireShellUiOpenersOptions = {
+  commandContext: CommandContext;
+  input: InputHandler;
+  panelManager: PanelManager;
+  conversation: ConversationManager;
+  configManager: ConfigManager;
+  providerRegistry: ProviderRegistry;
+  runtime: MutableRuntimeState;
+  featureFlags: FeatureFlagManager;
+  mcpRegistry: McpRegistry;
+  subscriptionManager: SubscriptionManager;
+  secretsManager?: Pick<SecretsManager, 'delete' | 'get' | 'set'>;
+  serviceRegistry: Pick<ServiceInspectionQuery, 'getAll'>;
+  workingDirectory: string;
+  homeDirectory: string;
+  getConfiguredProviderIds: () => string[];
+  getPinned: () => Promise<string[]>;
+  render: () => void;
+};
+
+/**
+ * Derive the configuredVia tier for a provider.
+ * Tier order mirrors SDK provider-routes.ts: env → secrets → subscription → undefined.
+ * The preResolvedSecretKeys set is pre-fetched async before the sync picker render cycle.
+ */
+function deriveConfiguredVia(
+  providerId: string,
+  configuredIds: Set<string>,
+  subscriptionManager: SubscriptionManager,
+  preResolvedSecretKeys?: ReadonlySet<string>,
+): 'env' | 'secrets' | 'subscription' | 'anonymous' | undefined {
+  if (!configuredIds.has(providerId)) return undefined;
+
+  // Tier 1: subscription check (most specific — subscription overrides env for this provider)
+  const subs = subscriptionManager.list();
+  if (subs.some((s) => s.provider === providerId)) return 'subscription';
+
+  // Tier 2: env-var present (process.env check; anonymous providers don't appear in configuredIds)
+  // We don't have BUILTIN_PROVIDER_ENV_KEYS here; if env was used the configuredIds path covers it.
+  // The presence in configuredIds and no subscription → either env or secrets.
+  // Tier 3: secrets-manager backed (pre-resolved async batch)
+  if (preResolvedSecretKeys && preResolvedSecretKeys.has(providerId)) return 'secrets';
+
+  return 'env';
+}
+
+/**
+ * Build a configuredViaMap for the given provider list.
+ * Pass preResolvedSecretKeys (from an async SecretsManager batch) to surface the 'secrets' tier.
+ */
+function buildConfiguredViaMap(
+  providers: string[],
+  configuredIds: Set<string>,
+  subscriptionManager: SubscriptionManager,
+  preResolvedSecretKeys?: ReadonlySet<string>,
+): Map<string, 'env' | 'secrets' | 'subscription' | 'anonymous'> {
+  const map = new Map<string, 'env' | 'secrets' | 'subscription' | 'anonymous'>();
+  for (const p of providers) {
+    const via = deriveConfiguredVia(p, configuredIds, subscriptionManager, preResolvedSecretKeys);
+    if (via !== undefined) map.set(p, via);
+  }
+  return map;
+}
+
+export function wireShellUiOpeners(options: WireShellUiOpenersOptions): void {
+  const {
+    commandContext,
+    input,
+    panelManager,
+    conversation,
+    configManager,
+    providerRegistry,
+    runtime,
+    featureFlags,
+    mcpRegistry,
+    subscriptionManager,
+    secretsManager,
+    serviceRegistry,
+    workingDirectory,
+    homeDirectory,
+    getConfiguredProviderIds,
+    getPinned,
+    render,
+  } = options;
+
+  /**
+   * Pre-resolve which provider IDs have secrets-manager keys (async batch, SDK tier pattern).
+   * Returns a set of provider IDs (not env var names) that are secrets-backed.
+   * Falls back to empty set if secretsManager is not provided.
+   */
+  async function resolveSecretProviderIds(): Promise<ReadonlySet<string>> {
+    if (!secretsManager) return new Set<string>();
+    const configuredIds = new Set(getConfiguredProviderIds());
+    // For each configured provider, check if secretsManager has a key for it by provider ID.
+    // We use provider ID as the lookup key since we don't have BUILTIN_PROVIDER_ENV_KEYS here.
+    const results = await Promise.all(
+      [...configuredIds].map(async (providerId) => {
+        const val = await secretsManager.get(providerId).catch(() => null);
+        return val !== null ? providerId : null;
+      }),
+    );
+    return new Set(results.filter((v): v is string => v !== null));
+  }
+
+  const getCurrentModelForPickerTarget = (): string => {
+    const selectedTarget = input.modelPicker.getSelectedTargetInfo();
+    const target = selectedTarget?.target ?? input.modelPicker.target;
+    if (target === 'helper') return String(configManager.get('helper.globalModel') || runtime.model);
+    if (target === 'tool') return String(configManager.get('tools.llmModel') || runtime.model);
+    if (target === 'tts') return String(configManager.get('tts.llmModel') || runtime.model);
+    return runtime.model;
+  };
+
+  const getCurrentProviderForPickerTarget = (): string => {
+    const selectedTarget = input.modelPicker.getSelectedTargetInfo();
+    const target = selectedTarget?.target ?? input.modelPicker.target;
+    if (target === 'helper') return String(configManager.get('helper.globalProvider') || runtime.provider);
+    if (target === 'tool') return String(configManager.get('tools.llmProvider') || runtime.provider);
+    if (target === 'tts') return String(configManager.get('tts.llmProvider') || runtime.provider);
+    return runtime.provider;
+  };
+
+  const buildModelPickerTargets = (): ModelPickerTargetInfo[] => {
+    const mainProvider = getProviderIdFromModel(configManager.get('provider.model') || runtime.provider).trim();
+    const mainModel = String(configManager.get('provider.model') || runtime.model || '').trim();
+    const helperProvider = String(configManager.get('helper.globalProvider') ?? '').trim();
+    const helperModel = String(configManager.get('helper.globalModel') ?? '').trim();
+    const toolProvider = String(configManager.get('tools.llmProvider') ?? '').trim();
+    const toolModel = String(configManager.get('tools.llmModel') ?? '').trim();
+    const ttsProvider = String(configManager.get('tts.llmProvider') ?? '').trim();
+    const ttsModel = String(configManager.get('tts.llmModel') ?? '').trim();
+
+    return [
+      {
+        target: 'main',
+        label: 'Main Chat',
+        description: 'Default provider and model for normal chat turns in this TUI session.',
+        provider: mainProvider,
+        model: mainModel,
+        enabled: true,
+        inherited: false,
+      },
+      {
+        target: 'helper',
+        label: 'Helper Model',
+        description: 'Optional helper route used for supporting work. Empty provider/model values inherit Main Chat.',
+        provider: helperProvider || mainProvider,
+        model: helperModel || mainModel,
+        enabled: Boolean(configManager.get('helper.enabled')),
+        inherited: helperProvider.length === 0 && helperModel.length === 0,
+      },
+      {
+        target: 'tool',
+        label: 'Tool LLM',
+        description: 'Optional LLM route for tool-specific reasoning. Selecting a model enables the tool LLM route.',
+        provider: toolProvider || mainProvider,
+        model: toolModel || mainModel,
+        enabled: Boolean(configManager.get('tools.llmEnabled')),
+        inherited: toolProvider.length === 0 && toolModel.length === 0,
+      },
+      {
+        target: 'tts',
+        label: 'TTS LLM',
+        description: 'Optional LLM override for /tts response generation. Empty values use the current chat model.',
+        provider: ttsProvider || mainProvider,
+        model: ttsModel || mainModel,
+        enabled: true,
+        inherited: ttsProvider.length === 0 && ttsModel.length === 0,
+      },
+    ];
+  };
+
+  commandContext.openModelPicker = () => {
+    void (async () => {
+      const models = providerRegistry.getSelectableModels();
+      const configuredIds = new Set(getConfiguredProviderIds());
+      input.modelPicker.configuredProviders = configuredIds;
+      const providerIds = [...new Set(models.map((m) => m.provider))];
+      const secretProviderIds = await resolveSecretProviderIds();
+      input.modelPicker.configuredViaMap = buildConfiguredViaMap(providerIds, configuredIds, subscriptionManager, secretProviderIds);
+      void getPinned().then((pinned) => {
+        input.modelPicker.pinnedIds = new Set(pinned);
+      });
+      void input.modelPicker.loadRecentModels().catch(() => {}); // best-effort: prefetch for UI, failure is non-visible
+      input.modalOpened('modelPicker');
+      input.modelPicker.setTargetInfos(buildModelPickerTargets());
+      input.modelPicker.openAllModels(models, getCurrentModelForPickerTarget());
+      render();
+    })().catch((error: unknown) => {
+      commandContext.print?.(`Model picker failed to open: ${error instanceof Error ? error.message : String(error)}`);
+      render();
+    });
+  };
+
+  commandContext.openModelPickerWithTarget = (target) => input.openModelPickerWithTarget(target);
+  commandContext.openProviderModelPickerWithTarget = (target) => input.openProviderModelPickerWithTarget(target);
+
+  commandContext.openProviderPicker = () => {
+    void (async () => {
+      const providers = [...new Set(providerRegistry.listModels().map((model) => model.provider))];
+      const configuredIds = new Set(getConfiguredProviderIds());
+      input.modelPicker.configuredProviders = configuredIds;
+      const secretProviderIds = await resolveSecretProviderIds();
+      input.modelPicker.configuredViaMap = buildConfiguredViaMap(providers, configuredIds, subscriptionManager, secretProviderIds);
+      input.modalOpened('modelPicker');
+      input.modelPicker.setTargetInfos(buildModelPickerTargets());
+      input.modelPicker.openProviders(providers, getCurrentProviderForPickerTarget());
+      render();
+    })().catch((error: unknown) => {
+      commandContext.print?.(`Provider picker failed to open: ${error instanceof Error ? error.message : String(error)}`);
+      render();
+    });
+  };
+
+  commandContext.openSelection = (title, items, opts, callback) => {
+    input.openSelection(title, items, opts, callback);
+  };
+
+  commandContext.openOnboardingWizard = (modeOrOptions) => {
+    input.openOnboardingWizard(modeOrOptions);
+  };
+
+  commandContext.openContextInspector = () => {
+    input.modalOpened('contextInspector');
+    input.contextInspectorModal.open();
+    render();
+  };
+
+  commandContext.openBookmarkModal = () => {
+    input.modalOpened('bookmark');
+    input.bookmarkModal.open();
+    render();
+  };
+
+  commandContext.openHelpOverlay = () => {
+    if (!input.helpOverlayActive) input.modalOpened('help');
+    input.helpOverlayActive = !input.helpOverlayActive;
+    input.helpScrollOffset = 0;
+  };
+
+  commandContext.openShortcutsOverlay = () => {
+    if (!input.shortcutsOverlayActive) input.modalOpened('shortcuts');
+    input.shortcutsOverlayActive = !input.shortcutsOverlayActive;
+    input.shortcutsScrollOffset = 0;
+    render();
+  };
+
+  commandContext.openProfilePicker = () => {
+    input.modalOpened('profilePicker');
+    input.profilePickerModal.open();
+    render();
+  };
+
+  commandContext.openSettingsModal = (target?: string) => {
+    input.modalOpened('settings');
+    input.settingsModal.open(configManager, featureFlags, subscriptionManager, serviceRegistry, mcpRegistry, secretsManager, {
+      onSettingApplied: (change) => syncServiceSettingToPlatform(
+        { configManager, workingDirectory, homeDirectory },
+        change,
+      ),
+    });
+    input.settingsModal.selectTarget(target);
+    render();
+  };
+
+  commandContext.openMcpWorkspace = () => {
+    input.openMcpWorkspace(commandContext);
+    render();
+  };
+
+  commandContext.openAgentWorkspace = () => {
+    input.openAgentWorkspace(commandContext);
+    render();
+  };
+
+  commandContext.openSessionPicker = () => {
+    input.modalOpened('sessionPicker');
+    input.sessionPickerModal.open();
+    render();
+  };
+
+  commandContext.openPanelPicker = () => {
+    if (!panelManager.isVisible()) {
+      if (panelManager.getAllOpen().length === 0) {
+        try {
+          panelManager.open('panel-list');
+        } catch {
+          // non-fatal
+        }
+      }
+      panelManager.show();
+      input.panelFocused = true;
+      conversation.setSplashSuppressed(true);
+      conversation.rebuildHistory();
+    } else if (!input.panelFocused) {
+      if (panelManager.getAllOpen().length === 0) {
+        try {
+          panelManager.open('panel-list');
+        } catch {
+          // non-fatal
+        }
+      }
+      panelManager.show();
+      input.panelFocused = true;
+      conversation.setSplashSuppressed(true);
+      conversation.rebuildHistory();
+    } else {
+      panelManager.hide();
+      input.panelFocused = false;
+      conversation.setSplashSuppressed(false);
+      conversation.rebuildHistory();
+    }
+    render();
+  };
+
+  commandContext.focusPanels = () => {
+    if (!panelManager.isVisible() || panelManager.getAllOpen().length === 0) return;
+    input.panelFocused = true;
+    render();
+  };
+
+  commandContext.focusPrompt = () => {
+    input.panelFocused = false;
+    input.indicatorFocused = false;
+    render();
+  };
+
+  commandContext.showPanel = (panelId, pane) => {
+    panelManager.open(panelId, pane);
+    panelManager.show();
+    input.panelFocused = true;
+    conversation.setSplashSuppressed(true);
+    conversation.rebuildHistory();
+    render();
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1 @@
+export { registerAllTools } from '@pellux/goodvibes-sdk/platform/tools';

package/src/tools/wrfc-agent-guard.ts

@@ -0,0 +1,49 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+
+type AgentToolArgs = {
+  readonly mode?: unknown;
+  readonly [key: string]: unknown;
+};
+
+type AgentToolPolicyGuardOptions = {
+  readonly getLastUserMessage?: () => string | null;
+};
+
+const LOCAL_AGENT_DENIAL = [
+  'GoodVibes Agent does not spawn local Engineer/Reviewer/Tester/Verifier roots or run local WRFC chains.',
+  'Keep ordinary assistant work serial in the main conversation.',
+  'For explicit build/fix/review work, delegate one request to GoodVibes TUI through the public shared-session/build-delegation contract with the full original user ask.',
+].join(' ');
+
+export function installAgentToolPolicyGuard(registry: ToolRegistry, options: AgentToolPolicyGuardOptions = {}): void {
+  const agentTool = registry.list().find((tool) => tool.definition.name === 'agent');
+  if (!agentTool) throw new Error('Agent tool policy guard could not find the agent tool.');
+  wrapAgentToolForAgentPolicy(agentTool, options);
+}
+
+export function wrapAgentToolForAgentPolicy(tool: Tool, _options: AgentToolPolicyGuardOptions = {}): void {
+  const originalExecute = tool.execute.bind(tool);
+  tool.execute = async (args) => {
+    const denial = validateAgentToolInvocationForAgentPolicy(args as AgentToolArgs);
+    if (denial) return { success: false, error: denial };
+    return originalExecute(normalizeAgentToolInvocationForAgentPolicy(args as AgentToolArgs) as Parameters<Tool['execute']>[0]);
+  };
+}
+
+export function validateAgentToolInvocationForAgentPolicy(args: AgentToolArgs): string | null {
+  if (args.mode === 'spawn' || args.mode === 'batch-spawn') return LOCAL_AGENT_DENIAL;
+  return null;
+}
+
+export function normalizeAgentToolInvocationForAgentPolicy(args: AgentToolArgs): AgentToolArgs {
+  return args;
+}
+
+export const AGENT_LOCAL_SPAWN_DENIAL_MESSAGE = LOCAL_AGENT_DENIAL;
+
+// Compatibility exports for copied TUI tests/imports during the near-fork phase.
+export const installWrfcAgentToolGuard = installAgentToolPolicyGuard;
+export const wrapWrfcAgentTool = wrapAgentToolForAgentPolicy;
+export const validateWrfcAgentToolInvocation = validateAgentToolInvocationForAgentPolicy;
+export const normalizeWrfcAgentToolInvocation = normalizeAgentToolInvocationForAgentPolicy;