@pellux/goodvibes-agent 1.1.6 → 1.2.0

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

@@ -0,0 +1,282 @@
+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 { createAgentAutonomyScheduleTool } from './agent-autonomy-schedule-tool.ts';
+import { createAgentOperatorActionTool } from './agent-operator-action-tool.ts';
+import { createAgentOperatorMethodTool } from './agent-operator-method-tool.ts';
+import { createAgentReminderScheduleTool } from './agent-reminder-schedule-tool.ts';
+import { createAgentScheduleEditTool } from './agent-schedule-edit-tool.ts';
+
+type ScheduleAction =
+  | 'list'
+  | 'create'
+  | 'reminder'
+  | 'edit'
+  | 'run'
+  | 'pause'
+  | 'resume'
+  | 'delete';
+
+interface AgentScheduleToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly scheduleId?: unknown;
+  readonly jobId?: unknown;
+  readonly targetId?: unknown;
+  readonly task?: unknown;
+  readonly message?: unknown;
+  readonly successCriteria?: unknown;
+  readonly scheduleKind?: unknown;
+  readonly kind?: unknown;
+  readonly scheduleValue?: unknown;
+  readonly value?: unknown;
+  readonly at?: unknown;
+  readonly every?: unknown;
+  readonly cron?: unknown;
+  readonly timezone?: unknown;
+  readonly staggerMs?: unknown;
+  readonly name?: unknown;
+  readonly prompt?: unknown;
+  readonly provider?: unknown;
+  readonly model?: unknown;
+  readonly deliveryChannel?: unknown;
+  readonly deliveryRoute?: unknown;
+  readonly deliveryWebhook?: unknown;
+  readonly deliveryLink?: unknown;
+  readonly disabled?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+  readonly query?: unknown;
+  readonly limit?: unknown;
+}
+
+const LIFECYCLE_ACTIONS: Readonly<Record<'run' | 'pause' | 'resume' | 'delete', string>> = {
+  run: 'schedules.run',
+  pause: 'schedules.disable',
+  resume: 'schedules.enable',
+  delete: 'schedules.delete',
+};
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+function readScheduleId(args: AgentScheduleToolArgs): string {
+  return readString(args.scheduleId) || readString(args.jobId) || readString(args.targetId);
+}
+
+function normalizeAction(value: unknown): ScheduleAction | null {
+  const action = readString(value).toLowerCase();
+  if (!action) return null;
+  if (action === 'autonomous' || action === 'schedule' || action === 'create_task' || action === 'create-task') return 'create';
+  if (action === 'remind' || action === 'reminder' || action === 'create_reminder' || action === 'create-reminder') return 'reminder';
+  if (action === 'update' || action === 'patch') return 'edit';
+  if (action === 'disable' || action === 'stop' || action === 'cancel') return 'pause';
+  if (action === 'enable' || action === 'start') return 'resume';
+  if (action === 'remove') return 'delete';
+  if (action === 'ls' || action === 'status' || action === 'show') return 'list';
+  if (action === 'list' || action === 'create' || action === 'edit' || action === 'run' || action === 'pause' || action === 'resume' || action === 'delete') return action;
+  return null;
+}
+
+function hasEditFields(args: AgentScheduleToolArgs): boolean {
+  return Boolean(
+    readString(args.scheduleKind)
+      || readString(args.kind)
+      || readString(args.scheduleValue)
+      || readString(args.value)
+      || readString(args.at)
+      || readString(args.every)
+      || readString(args.cron)
+      || readString(args.name)
+      || readString(args.prompt)
+      || readString(args.task)
+      || readString(args.successCriteria)
+      || args.staggerMs !== undefined,
+  );
+}
+
+function readAction(args: AgentScheduleToolArgs): ScheduleAction {
+  const explicit = normalizeAction(args.action) ?? normalizeAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.message)) return 'reminder';
+  if (readString(args.task)) return readScheduleId(args) && hasEditFields(args) ? 'edit' : 'create';
+  if (readScheduleId(args) && hasEditFields(args)) return 'edit';
+  return 'list';
+}
+
+function scheduleKind(args: AgentScheduleToolArgs): string {
+  const direct = readString(args.scheduleKind) || readString(args.kind);
+  if (direct) return direct.toLowerCase();
+  if (readString(args.at)) return 'at';
+  if (readString(args.every)) return 'every';
+  if (readString(args.cron)) return 'cron';
+  return '';
+}
+
+function scheduleValue(args: AgentScheduleToolArgs, kind: string): string {
+  const direct = readString(args.scheduleValue) || readString(args.value);
+  if (direct) return direct;
+  if (kind === 'at') return readString(args.at);
+  if (kind === 'every') return readString(args.every);
+  if (kind === 'cron') return readString(args.cron);
+  return readString(args.at) || readString(args.every) || readString(args.cron);
+}
+
+function sharedCreateArgs(args: AgentScheduleToolArgs): Record<string, unknown> {
+  const kind = scheduleKind(args);
+  return {
+    scheduleKind: kind,
+    scheduleValue: scheduleValue(args, kind),
+    timezone: args.timezone,
+    name: args.name,
+    provider: args.provider,
+    model: args.model,
+    deliveryChannel: args.deliveryChannel,
+    deliveryRoute: args.deliveryRoute,
+    deliveryWebhook: args.deliveryWebhook,
+    deliveryLink: args.deliveryLink,
+    disabled: args.disabled,
+    confirm: args.confirm,
+    explicitUserRequest: args.explicitUserRequest,
+  };
+}
+
+function autonomyArgs(args: AgentScheduleToolArgs): Record<string, unknown> {
+  return {
+    task: args.task,
+    successCriteria: args.successCriteria,
+    ...sharedCreateArgs(args),
+  };
+}
+
+function reminderArgs(args: AgentScheduleToolArgs): Record<string, unknown> {
+  return {
+    message: args.message,
+    ...sharedCreateArgs(args),
+  };
+}
+
+function editArgs(args: AgentScheduleToolArgs): Record<string, unknown> {
+  const kind = scheduleKind(args);
+  return {
+    scheduleId: readScheduleId(args),
+    scheduleKind: kind || undefined,
+    scheduleValue: kind ? scheduleValue(args, kind) : undefined,
+    timezone: args.timezone,
+    staggerMs: args.staggerMs,
+    name: args.name,
+    prompt: args.prompt,
+    task: args.task,
+    successCriteria: args.successCriteria,
+    confirm: args.confirm,
+    explicitUserRequest: args.explicitUserRequest,
+  };
+}
+
+function listInput(args: AgentScheduleToolArgs): Record<string, unknown> {
+  const input: Record<string, unknown> = {};
+  const query = readString(args.query) || readScheduleId(args);
+  if (query) input.query = query;
+  if (typeof args.limit === 'number' && Number.isFinite(args.limit)) input.limit = args.limit;
+  return input;
+}
+
+export function createAgentScheduleTool(
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): Tool {
+  const autonomyTool = createAgentAutonomyScheduleTool(shellPaths, configManager);
+  const reminderTool = createAgentReminderScheduleTool(shellPaths, configManager);
+  const editTool = createAgentScheduleEditTool(shellPaths, configManager);
+  const operatorActionTool = createAgentOperatorActionTool(shellPaths, configManager);
+  const operatorMethodTool = createAgentOperatorMethodTool(shellPaths, configManager);
+
+  return {
+    definition: {
+      name: 'schedule',
+      description: 'List, create, edit, run, pause, resume schedules.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['list', 'create', 'autonomous', 'remind', 'reminder', 'edit', 'run', 'pause', 'resume', 'enable', 'disable', 'delete'],
+            description: 'Schedule action; list is read-only, others confirm.',
+          },
+          scheduleId: { type: 'string', description: 'Connected schedule id for edit/run/pause/resume/delete.' },
+          jobId: { type: 'string', description: 'Alias for scheduleId.' },
+          targetId: { type: 'string', description: 'Alias for scheduleId.' },
+          task: { type: 'string', description: 'Autonomous task for action:create, or replacement task for action:edit.' },
+          message: { type: 'string', description: 'Reminder text for action:reminder.' },
+          successCriteria: { type: 'string', description: 'Required for autonomous scheduled tasks.' },
+          scheduleKind: { type: 'string', enum: ['at', 'every', 'cron'], description: 'Schedule kind.' },
+          kind: { type: 'string', enum: ['at', 'every', 'cron'], description: 'Alias for scheduleKind.' },
+          scheduleValue: { type: 'string', description: 'ISO timestamp, interval, or cron expression.' },
+          value: { type: 'string', description: 'Alias for scheduleValue.' },
+          at: { type: 'string', description: 'ISO timestamp shortcut.' },
+          every: { type: 'string', description: 'Interval shortcut such as 1d or 30m.' },
+          cron: { type: 'string', description: 'Cron expression shortcut.' },
+          timezone: { type: 'string', description: 'Optional IANA timezone.' },
+          staggerMs: { type: 'number', description: 'Optional cron stagger in milliseconds for edits.' },
+          name: { type: 'string', description: 'Connected schedule display name.' },
+          prompt: { type: 'string', description: 'Exact replacement prompt for action:edit.' },
+          provider: { type: 'string', description: 'Optional provider row id for scheduled execution.' },
+          model: { type: 'string', description: 'Optional model id for scheduled execution.' },
+          deliveryChannel: { type: 'string', description: 'Optional delivery channel target.' },
+          deliveryRoute: { type: 'string', description: 'Optional connected route target.' },
+          deliveryWebhook: { type: 'string', description: 'Optional webhook target.' },
+          deliveryLink: { type: 'string', description: 'Optional link delivery target.' },
+          disabled: { type: 'boolean', description: 'Create schedule disabled.' },
+          query: { type: 'string', description: 'Optional list query or schedule lookup text.' },
+          limit: { type: 'number', description: 'Optional list limit when supported by the connected host.' },
+          confirm: { type: 'boolean', description: 'Required true for create/edit/run/pause/resume/delete.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing side-effecting schedule actions.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['network', 'state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentScheduleToolArgs;
+      const action = readAction(args);
+      if (action === 'list') {
+        return operatorMethodTool.execute({
+          methodId: 'schedules.list',
+          input: listInput(args),
+        });
+      }
+      if (action === 'create') return autonomyTool.execute(autonomyArgs(args));
+      if (action === 'reminder') return reminderTool.execute(reminderArgs(args));
+      if (action === 'edit') return editTool.execute(editArgs(args));
+
+      const scheduleId = readScheduleId(args);
+      if (!scheduleId) {
+        return {
+          success: false,
+          error: `scheduleId is required for schedule action:${action}.`,
+        };
+      }
+      return operatorActionTool.execute({
+        action: LIFECYCLE_ACTIONS[action],
+        scheduleId,
+        confirm: readBoolean(args.confirm),
+        explicitUserRequest: args.explicitUserRequest,
+      });
+    },
+  };
+}
+
+export function registerAgentScheduleTool(
+  registry: ToolRegistry,
+  shellPaths: ShellPathService,
+  configManager: AgentConnectedHostConfigReader,
+): void {
+  if (!registry.has('schedule')) registry.register(createAgentScheduleTool(shellPaths, configManager));
+}

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

@@ -0,0 +1,145 @@
+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';
+import { explainAgentPolicyDecision } from './agent-policy-explanation.ts';
+
+type AgentSecurityAction = 'status' | 'finding' | 'explain';
+
+interface AgentSecurityToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly findingId?: unknown;
+  readonly toolName?: unknown;
+  readonly tool?: unknown;
+  readonly toolArgs?: unknown;
+  readonly args?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentSecurityToolDeps {
+  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 output(value: unknown): { readonly success: true; readonly output: string } {
+  return { success: true, output: JSON.stringify(value, null, 2) };
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeSecurityAction(value: unknown): AgentSecurityAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'summary' || action === 'review' || action === 'posture') return 'status';
+  if (action === 'finding' || action === 'show' || action === 'inspect' || action === 'security_finding') return 'finding';
+  if (action === 'explain' || action === 'policy' || action === 'policy_explain' || action === 'why') return 'explain';
+  return null;
+}
+
+function readAction(args: AgentSecurityToolArgs): AgentSecurityAction | null {
+  const explicit = readString(args.action) || readString(args.mode);
+  if (explicit) return normalizeSecurityAction(explicit);
+  if (readString(args.toolName) || readString(args.tool)) return 'explain';
+  if (readString(args.findingId) || readString(args.id)) return 'finding';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function statusArgs(args: AgentSecurityToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'security_posture',
+    query: args.query ?? args.target,
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function findingArgs(args: AgentSecurityToolArgs): Record<string, unknown> {
+  const findingId = readString(args.findingId) || readString(args.id);
+  return compactArgs({
+    mode: 'security_finding',
+    findingId,
+    target: findingId ? undefined : args.target,
+    query: findingId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentSecurityTool(deps: AgentSecurityToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'security',
+      description: 'Read security posture, findings, and policy explanations.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'finding', 'explain'],
+            description: 'Read posture, finding detail, or action policy.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Generic finding id.' },
+          findingId: { type: 'string', description: 'Security finding id.' },
+          toolName: { type: 'string', description: 'Model tool name for action:explain.' },
+          tool: { type: 'string', description: 'Alias for toolName.' },
+          toolArgs: { type: 'object', description: 'Arguments for policy explanation.' },
+          args: { type: 'object', description: 'Alias for toolArgs.' },
+          target: { type: 'string', description: 'Lookup target or search text.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed evidence and tool metadata.' },
+          limit: { type: 'number', description: 'Maximum findings returned.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentSecurityToolArgs;
+      const action = readAction(args);
+      if (!action) return error('Unknown security action. Use action:"status" or action:"explain".');
+
+      if (action === 'status') return harnessTool.execute(statusArgs(args));
+      if (action === 'finding') return harnessTool.execute(findingArgs(args));
+      if (action === 'explain') {
+        const resolved = explainAgentPolicyDecision(deps.commandContext, deps.toolRegistry, args);
+        if (resolved.status === 'found') return output(resolved.explanation);
+        if (resolved.status === 'ambiguous') return error(`Ambiguous security policy target ${resolved.input}. Candidates: ${JSON.stringify(resolved.candidates)}`);
+        return error(resolved.usage);
+      }
+
+      return error('Unknown security action. Use action:"status" or action:"explain".');
+    },
+  };
+}
+
+export function registerAgentSecurityTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('security')) registry.register(createAgentSecurityTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

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

@@ -0,0 +1,122 @@
+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 AgentSessionsAction = 'list' | 'get';
+
+interface AgentSessionsToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly sessionId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface AgentSessionsToolDeps {
+  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 normalizeSessionsAction(value: unknown): AgentSessionsAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (['list', 'search', 'status', 'summary', 'catalog', 'sessions', 'bookmarks'].includes(action)) return 'list';
+  if (['get', 'show', 'inspect', 'session'].includes(action)) return 'get';
+  return null;
+}
+
+function readAction(args: AgentSessionsToolArgs): AgentSessionsAction | null {
+  const explicit = normalizeSessionsAction(args.action) ?? normalizeSessionsAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.sessionId) || readString(args.id)) return 'get';
+  return 'list';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function listArgs(args: AgentSessionsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'sessions',
+    query: args.query ?? args.target,
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function getArgs(args: AgentSessionsToolArgs): Record<string, unknown> {
+  const sessionId = readString(args.sessionId) || readString(args.id);
+  return compactArgs({
+    mode: 'session',
+    sessionId,
+    target: sessionId ? undefined : args.target,
+    query: sessionId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+export function createAgentSessionsTool(deps: AgentSessionsToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'sessions',
+      description: 'Read saved sessions, bookmarks, and transcript continuity.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['list', 'search', 'status', 'get'],
+            description: 'List/search sessions or inspect one saved session.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Alias for sessionId.' },
+          sessionId: { type: 'string', description: 'Saved session id.' },
+          target: { type: 'string', description: 'Lookup target or search text.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detail, snippets, and route metadata.' },
+          limit: { type: 'number', description: 'Maximum sessions returned.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: [],
+      concurrency: 'parallel',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentSessionsToolArgs;
+      const action = readAction(args);
+      if (!action) return error('Unknown sessions action. Use action:"list" or action:"get".');
+      if (action === 'list') return harnessTool.execute(listArgs(args));
+      if (action === 'get') return harnessTool.execute(getArgs(args));
+      return error('Unknown sessions action. Use action:"list" or action:"get".');
+    },
+  };
+}
+
+export function registerAgentSessionsTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('sessions')) registry.register(createAgentSessionsTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

package/src/tools/agent-settings-import-tool.ts

@@ -0,0 +1,104 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext } from '../input/command-registry.ts';
+import {
+  importAgentWorkspaceTuiSettings,
+  previewAgentWorkspaceTuiSettingsImport,
+} from '../input/agent-workspace-settings.ts';
+
+type SettingsImportAction = 'preview' | 'apply';
+
+interface AgentSettingsImportArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+function output(value: unknown): { readonly success: true; readonly output: string } {
+  return {
+    success: true,
+    output: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+  };
+}
+
+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 readBoolean(value: unknown): boolean {
+  return value === true || (typeof value === 'string' && ['true', 'yes', 'apply', 'import'].includes(value.trim().toLowerCase()));
+}
+
+function readAction(args: AgentSettingsImportArgs): SettingsImportAction {
+  const raw = (readString(args.action) || readString(args.mode)).toLowerCase();
+  if (raw === 'apply' || raw === 'confirm') return 'apply';
+  if (raw === 'import') return readBoolean(args.confirm) ? 'apply' : 'preview';
+  return 'preview';
+}
+
+export function createAgentSettingsImportTool(commandContext: CommandContext): Tool {
+  return {
+    definition: {
+      name: 'import_goodvibes_settings',
+      description: 'Preview or apply shared GoodVibes settings import.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['preview', 'import', 'apply'],
+            description: 'preview is read-only; apply/import with confirm mutates Agent settings.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          confirm: { type: 'boolean', description: 'Required true for action:apply.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing confirmed import.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentSettingsImportArgs;
+      const preview = previewAgentWorkspaceTuiSettingsImport(commandContext);
+      if (!preview) return error('GoodVibes settings import is unavailable in this runtime.');
+      const action = readAction(args);
+
+      if (action === 'preview' || !readBoolean(args.confirm)) {
+        return output({
+          status: 'confirmation_required',
+          action: 'import_goodvibes_settings',
+          preview,
+          next: 'Run action:"apply" with confirm:true and explicitUserRequest after the user asks to import these settings.',
+        });
+      }
+
+      const explicitUserRequest = readString(args.explicitUserRequest);
+      if (!explicitUserRequest) return error('GoodVibes settings import requires explicitUserRequest when confirm is true.');
+
+      const outcome = await importAgentWorkspaceTuiSettings(commandContext);
+      return output({
+        status: outcome.status,
+        action: 'import_goodvibes_settings',
+        preview,
+        actionResult: outcome.result,
+        runtimeSnapshot: outcome.runtimeSnapshot,
+        policy: {
+          effect: 'state',
+          confirmation: 'confirmed',
+          explicitUserRequest,
+          boundary: 'Applied only Agent-owned settings and subscription state from published GoodVibes platform sources; source package stores were not mutated.',
+        },
+      });
+    },
+  };
+}
+
+export function registerAgentSettingsImportTool(registry: ToolRegistry, commandContext: CommandContext): void {
+  if (!registry.has('import_goodvibes_settings')) registry.register(createAgentSettingsImportTool(commandContext));
+}