@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/input/agent-workspace-channel-command-editors.ts

@@ -1,4 +1,6 @@
 import type { AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
+import type { AgentWorkspaceEditorSpecEntry } from './agent-workspace-command-editor-engine.ts';
+import { createAgentWorkspaceEditorFromTable } from './agent-workspace-command-editor-engine.ts';
 
 export type AgentWorkspaceChannelCommandEditorKind = Extract<
   AgentWorkspaceEditorKind,
@@ -9,51 +11,41 @@ export function isAgentWorkspaceChannelCommandEditorKind(kind: AgentWorkspaceEdi
   return kind === 'channel-show' || kind === 'channel-doctor' || kind === 'channel-setup' || kind === 'channel-send';
 }
 
-export function createAgentWorkspaceChannelCommandEditor(kind: AgentWorkspaceChannelCommandEditorKind): AgentWorkspaceLocalEditor {
-  if (kind === 'channel-send') {
-    return {
-      kind,
-      mode: 'create',
-      title: 'Send Channel Message',
-      selectedFieldIndex: 0,
-      message: 'Send one message through a configured delivery target. Fill exactly one target field and type yes to confirm.',
-      fields: [
-        { id: 'message', label: 'Message', value: '', required: true, multiline: true, hint: 'Plain-text message. Ctrl-J inserts a new line.' },
-        { id: 'title', label: 'Title', value: '', required: false, multiline: false, hint: 'Optional delivery title. Blank uses the Agent default.' },
-        { id: 'channel', label: 'Channel target', value: '', required: false, multiline: false, hint: 'Optional surface[:route[:label]], such as slack:ops:Ops or telephony:+15551234567.' },
-        { id: 'route', label: 'Route target', value: '', required: false, multiline: false, hint: 'Optional route id or route:label.' },
-        { id: 'webhook', label: 'Webhook URL', value: '', required: false, multiline: false, hint: 'Optional http(s) webhook target.' },
-        { id: 'link', label: 'Link target', value: '', required: false, multiline: false, hint: 'Optional link delivery target.' },
-        { id: 'confirm', label: 'Confirm', value: '', required: true, multiline: false, hint: 'Type yes to run /channels send with --yes.' },
-      ],
-    };
-  }
-  if (kind === 'channel-doctor') {
-    return {
-      kind,
-      mode: 'create',
-      title: 'Run Channel Doctor',
-      selectedFieldIndex: 0,
-      message: 'Inspect one connected channel route without sending messages or changing delivery state.',
-      fields: [
-        { id: 'channel', label: 'Channel id', value: '', required: true, multiline: false, hint: 'Channel id, such as slack, telegram, discord, ntfy, signal, whatsapp, or telephony.' },
-      ],
-    };
-  }
-  if (kind === 'channel-setup') {
-    return {
-      kind,
-      mode: 'create',
-      title: 'Show Channel Setup',
-      selectedFieldIndex: 0,
-      message: 'Show read-only setup guidance for one channel. This does not pair, enable, or send through the channel.',
-      fields: [
-        { id: 'channel', label: 'Channel id', value: '', required: true, multiline: false, hint: 'Channel id, such as slack, telegram, discord, ntfy, signal, whatsapp, or telephony.' },
-      ],
-    };
-  }
-  return {
-    kind,
+const CHANNEL_COMMAND_EDITOR_SPECS: Readonly<Record<AgentWorkspaceChannelCommandEditorKind, AgentWorkspaceEditorSpecEntry<AgentWorkspaceChannelCommandEditorKind>>> = {
+  'channel-send': {
+    mode: 'create',
+    title: 'Send Channel Message',
+    selectedFieldIndex: 0,
+    message: 'Send one message through a configured delivery target. Fill exactly one target field and type yes to confirm.',
+    fields: [
+      { id: 'message', label: 'Message', value: '', required: true, multiline: true, hint: 'Plain-text message. Ctrl-J inserts a new line.' },
+      { id: 'title', label: 'Title', value: '', required: false, multiline: false, hint: 'Optional delivery title. Blank uses the Agent default.' },
+      { id: 'channel', label: 'Channel target', value: '', required: false, multiline: false, hint: 'Optional surface[:route[:label]], such as slack:ops:Ops or telephony:+15551234567.' },
+      { id: 'route', label: 'Route target', value: '', required: false, multiline: false, hint: 'Optional route id or route:label.' },
+      { id: 'webhook', label: 'Webhook URL', value: '', required: false, multiline: false, hint: 'Optional http(s) webhook target.' },
+      { id: 'link', label: 'Link target', value: '', required: false, multiline: false, hint: 'Optional link delivery target.' },
+      { id: 'confirm', label: 'Confirm', value: '', required: true, multiline: false, hint: 'Type yes to run /channels send with --yes.' },
+    ],
+  },
+  'channel-doctor': {
+    mode: 'create',
+    title: 'Run Channel Doctor',
+    selectedFieldIndex: 0,
+    message: 'Inspect one connected channel route without sending messages or changing delivery state.',
+    fields: [
+      { id: 'channel', label: 'Channel id', value: '', required: true, multiline: false, hint: 'Channel id, such as slack, telegram, discord, ntfy, signal, whatsapp, or telephony.' },
+    ],
+  },
+  'channel-setup': {
+    mode: 'create',
+    title: 'Show Channel Setup',
+    selectedFieldIndex: 0,
+    message: 'Show read-only setup guidance for one channel. This does not pair, enable, or send through the channel.',
+    fields: [
+      { id: 'channel', label: 'Channel id', value: '', required: true, multiline: false, hint: 'Channel id, such as slack, telegram, discord, ntfy, signal, whatsapp, or telephony.' },
+    ],
+  },
+  'channel-show': {
     mode: 'create',
     title: 'Show Channel Detail',
     selectedFieldIndex: 0,
@@ -61,5 +53,9 @@ export function createAgentWorkspaceChannelCommandEditor(kind: AgentWorkspaceCha
     fields: [
       { id: 'channel', label: 'Channel id', value: '', required: true, multiline: false, hint: 'Channel id, such as slack, telegram, discord, ntfy, signal, whatsapp, or telephony.' },
     ],
-  };
+  },
+};
+
+export function createAgentWorkspaceChannelCommandEditor(kind: AgentWorkspaceChannelCommandEditorKind): AgentWorkspaceLocalEditor {
+  return createAgentWorkspaceEditorFromTable(kind, CHANNEL_COMMAND_EDITOR_SPECS);
 }

package/src/input/agent-workspace-command-editor-engine.ts

@@ -0,0 +1,133 @@
+// Shared engine for the agent-workspace "command editor" domains (access, channel,
+// knowledge, library, mcp, media, memory, operations, provider, session, skill-bundle,
+// task). Every one of those domains follows the same two-stage shape: a declarative
+// field-spec factory (kind -> { title, mode, message, fields }) and a submission step
+// that reads the filled fields and builds a slash-command string handed to the
+// shell-owned command router. This module factors that repeated structural pattern
+// (the editor-construction factory, the submission dispatch/blocked-editor result
+// shapes, and the handful of small helpers every domain re-implemented locally) into
+// one place. Each domain keeps its own field content and command-building logic
+// (real product value, not boilerplate) as entries in a `Record<Kind, ...>` table.
+//
+// W4-H2 (Wave 4): consolidates the ~26 near-identical editor+submission file pairs
+// identified by the W4-H1 design ruling into this engine + per-domain data tables.
+import type { AgentWorkspaceActionResult, AgentWorkspaceEditorField, AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
+import { quoteSlashCommandArg } from './slash-command-parser.ts';
+
+export type AgentWorkspaceFieldReader = (fieldId: string) => string;
+
+/** The data shape every domain's per-kind editor literal already followed. */
+export interface AgentWorkspaceEditorSpec {
+  readonly mode: 'create' | 'update' | 'delete';
+  readonly title: string;
+  readonly message: string;
+  readonly selectedFieldIndex: number;
+  readonly fields: readonly AgentWorkspaceEditorField[];
+}
+
+/**
+ * A table entry is either a static spec, or (for the handful of kinds whose wording
+ * depends on which kind was requested, such as voice-enable/voice-disable sharing one
+ * shape) a function of the kind that returns one.
+ */
+export type AgentWorkspaceEditorSpecEntry<K extends string> =
+  | AgentWorkspaceEditorSpec
+  | ((kind: K) => AgentWorkspaceEditorSpec);
+
+export function createAgentWorkspaceEditorFromTable<K extends string>(
+  kind: K,
+  table: Readonly<Record<K, AgentWorkspaceEditorSpecEntry<K>>>,
+): AgentWorkspaceLocalEditor {
+  const entry = table[kind];
+  const spec: AgentWorkspaceEditorSpec = typeof entry === 'function' ? (entry as (kind: K) => AgentWorkspaceEditorSpec)(kind) : (entry as AgentWorkspaceEditorSpec);
+  return {
+    kind: kind as AgentWorkspaceEditorKind,
+    mode: spec.mode,
+    title: spec.title,
+    selectedFieldIndex: spec.selectedFieldIndex,
+    message: spec.message,
+    fields: spec.fields,
+  };
+}
+
+export type AgentWorkspaceCommandEditorSubmission =
+  | {
+    readonly kind: 'editor';
+    readonly editor: AgentWorkspaceLocalEditor;
+    readonly status: string;
+    readonly actionResult?: AgentWorkspaceActionResult;
+  }
+  | {
+    readonly kind: 'dispatch';
+    readonly command: string;
+    readonly status: string;
+    readonly actionResult: AgentWorkspaceActionResult;
+  };
+
+export type AgentWorkspaceCommandDispatchSafety = NonNullable<AgentWorkspaceActionResult['safety']>;
+
+export function isAffirmative(value: string): boolean {
+  return /^(y|yes|true)$/i.test(value.trim());
+}
+
+export function splitCommaList(value: string): readonly string[] {
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+/** Pushes `flag, quoteSlashCommandArg(value)` onto `parts` when `value` is non-blank. */
+export function appendOptionalArg(parts: string[], flag: string, value: string): void {
+  if (value.trim().length > 0) parts.push(flag, quoteSlashCommandArg(value));
+}
+
+/**
+ * The confirmed/dispatched result shape every domain built by hand: status is always
+ * `${title}.`, and the actionResult always carries kind: 'dispatched' with the same
+ * command, title, detail, and safety. Kinds whose actionResult.command legitimately
+ * differs from the dispatched command (for example a redacted secret) skip this
+ * helper and build the literal directly, same as before consolidation.
+ */
+export function dispatchCommandEditorSubmission(
+  command: string,
+  title: string,
+  detail: string,
+  safety: AgentWorkspaceCommandDispatchSafety,
+): AgentWorkspaceCommandEditorSubmission {
+  return {
+    kind: 'dispatch',
+    command,
+    status: `${title}.`,
+    actionResult: { kind: 'dispatched', title, detail, command, safety },
+  };
+}
+
+/**
+ * The "stay in the editor" result shape used for unconfirmed actions and other
+ * validation failures: the editor's message is replaced with `message`, and status
+ * defaults to the same text (the convention most domains used). Pass an explicit
+ * `status` for the domains that show a shorter status line than the in-editor message.
+ */
+export function editorMessageSubmission(
+  editor: AgentWorkspaceLocalEditor,
+  message: string,
+  status: string = message,
+): AgentWorkspaceCommandEditorSubmission {
+  return {
+    kind: 'editor',
+    editor: { ...editor, message },
+    status,
+  };
+}
+
+export type AgentWorkspaceCommandSubmissionHandler = (
+  editor: AgentWorkspaceLocalEditor,
+  readField: AgentWorkspaceFieldReader,
+) => AgentWorkspaceCommandEditorSubmission;
+
+export function buildCommandEditorSubmissionFromTable<K extends string>(
+  kind: K,
+  editor: AgentWorkspaceLocalEditor,
+  readField: AgentWorkspaceFieldReader,
+  table: Readonly<Record<K, AgentWorkspaceCommandSubmissionHandler>>,
+): AgentWorkspaceCommandEditorSubmission {
+  return table[kind](editor, readField);
+}

package/src/input/agent-workspace-command-editor.ts

@@ -10,6 +10,7 @@ import { buildAgentResearchReportPromptSubmission } from './agent-workspace-rese
 import { buildAgentResearchRunPromptSubmission } from './agent-workspace-research-run-editor.ts';
 import { buildAgentResearchSourcePromptSubmission } from './agent-workspace-research-source-editor.ts';
 import { buildAgentReminderScheduleEditorSubmission } from './agent-workspace-reminder-schedule-editor.ts';
+import { buildAgentWorkspaceCalendarConnectEditorSubmission } from './agent-workspace-calendar-connect-editor.ts';
 import { buildAgentRoutineScheduleEditorSubmission } from './agent-workspace-routine-schedule-editor.ts';
 import { buildAgentWorkspaceWebResearchSubmission } from './agent-workspace-web-research-editor.ts';
 import type { AgentWorkspaceActionResult, AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
@@ -69,6 +70,7 @@ type AgentWorkspaceCommandEditorKind = AgentWorkspaceBasicCommandEditorKind | Ex
   | 'secret-delete'
   | 'routine-schedule'
   | 'reminder-schedule'
+  | 'calendar-connect'
   | 'knowledge-bookmarks'
   | 'tts-prompt'
   | 'image-input'
@@ -166,6 +168,7 @@ export function isAgentWorkspaceCommandEditorKind(kind: AgentWorkspaceEditorKind
     || kind === 'model-compare-analytics'
     || kind === 'routine-schedule'
     || kind === 'reminder-schedule'
+    || kind === 'calendar-connect'
     || isAgentWorkspaceBasicCommandEditorKind(kind);
 }
 
@@ -263,5 +266,6 @@ export function buildAgentWorkspaceCommandEditorSubmission(
     return buildAgentWorkspaceBasicCommandEditorSubmission(editor, readField, commandDispatchAvailable);
   }
   if (editor.kind === 'reminder-schedule') return buildAgentReminderScheduleEditorSubmission(editor, readField, commandDispatchAvailable);
+  if (editor.kind === 'calendar-connect') return buildAgentWorkspaceCalendarConnectEditorSubmission(editor, readField, commandDispatchAvailable);
   return buildAgentRoutineScheduleEditorSubmission(editor, readField, commandDispatchAvailable);
 }

package/src/input/agent-workspace-direct-editor-submission.ts

@@ -0,0 +1,59 @@
+/**
+ * Editor kinds that perform a direct host action on submit (OAuth calls,
+ * config/secrets writes) rather than building a slash command for the
+ * generic command-editor dispatch pipeline (agent-workspace-command-editor.ts).
+ * Centralizing the dispatch here keeps AgentWorkspace.submitLocalEditor()
+ * under the architecture line cap as new direct-action editor kinds are
+ * added (W4-A5 added email-connect-wizard alongside the existing
+ * subscription-login-start/finish/logout kinds).
+ */
+import type { CommandContext } from './command-registry.ts';
+import type { AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
+import {
+  submitAgentWorkspaceSubscriptionLoginFinishEditor,
+  submitAgentWorkspaceSubscriptionLoginStartEditor,
+  submitAgentWorkspaceSubscriptionLogoutEditor,
+  type AgentWorkspaceSubscriptionEditorHost,
+} from './agent-workspace-subscription-editor.ts';
+import { submitAgentWorkspaceEmailConnectWizardEditor, type AgentWorkspaceEmailConnectEditorHost } from './agent-workspace-email-connect-editor.ts';
+import { submitAgentWorkspaceCalendarSubscribeWizardEditor, type AgentWorkspaceCalendarSubscribeEditorHost } from './agent-workspace-calendar-subscribe-editor.ts';
+import { submitAgentWorkspaceCalendarOAuthEditor, type AgentWorkspaceCalendarOAuthEditorHost } from './agent-workspace-calendar-oauth-editor.ts';
+
+type FieldReader = (id: string) => string;
+type DirectEditorHost = AgentWorkspaceSubscriptionEditorHost & AgentWorkspaceEmailConnectEditorHost & AgentWorkspaceCalendarSubscribeEditorHost & AgentWorkspaceCalendarOAuthEditorHost;
+
+/** Returns true when this editor kind was handled directly (caller should return without further dispatch). */
+export function trySubmitDirectHostActionEditor(
+  host: DirectEditorHost,
+  editor: AgentWorkspaceLocalEditor,
+  context: CommandContext | null,
+  readField: FieldReader,
+  requestRender?: () => void,
+): boolean {
+  if (editor.kind === 'subscription-login-start') {
+    void submitAgentWorkspaceSubscriptionLoginStartEditor(host, editor, context, readField).finally(() => requestRender?.());
+    return true;
+  }
+  if (editor.kind === 'subscription-login-finish') {
+    void submitAgentWorkspaceSubscriptionLoginFinishEditor(host, editor, context, readField).finally(() => requestRender?.());
+    return true;
+  }
+  if (editor.kind === 'subscription-logout') {
+    submitAgentWorkspaceSubscriptionLogoutEditor(host, editor, context, readField);
+    requestRender?.();
+    return true;
+  }
+  if (editor.kind === 'email-connect-wizard') {
+    void submitAgentWorkspaceEmailConnectWizardEditor(host, editor, context, readField).finally(() => requestRender?.());
+    return true;
+  }
+  if (editor.kind === 'calendar-subscribe-wizard') {
+    void submitAgentWorkspaceCalendarSubscribeWizardEditor(host, editor, context, readField).finally(() => requestRender?.());
+    return true;
+  }
+  if (editor.kind === 'calendar-oauth-google' || editor.kind === 'calendar-oauth-outlook') {
+    void submitAgentWorkspaceCalendarOAuthEditor(host, editor, context, readField).finally(() => requestRender?.());
+    return true;
+  }
+  return false;
+}

package/src/input/agent-workspace-email-connect-editor.ts

@@ -0,0 +1,162 @@
+/**
+ * Email connect wizard (W4-A5) — promotes the "Inbox workflows" workspace
+ * card from a dead guidance card into a real, stepped connect flow.
+ *
+ * Security: the raw password NEVER travels through the generic slash-command
+ * dispatch pipeline (AgentWorkspace.dispatchWorkspaceCommand), because that
+ * pipeline echoes its `command` argument back into
+ * AgentWorkspace.lastActionResult.command for the 'inline' execution path
+ * (see handler.ts dispatchAgentWorkspaceCommand) — a raw command string
+ * containing the password would render it in the workspace UI. Instead this
+ * editor is a DIRECT host action (the same pattern as the subscription
+ * login editors in agent-workspace-subscription-editor.ts): it calls
+ * persistEmailConfigField() and EmailService.testConnection() directly
+ * against ctx.platform.configManager / ctx.platform.secretsManager and never
+ * builds a command string. Credential persistence reuses the exact same
+ * persistEmailConfigField() helper the /email set CLI command uses — one
+ * storage path, not a fork.
+ */
+import type { CommandContext } from './command-registry.ts';
+import { isAffirmative } from './agent-workspace-editors.ts';
+import { EmailService, ensureEmailConfigDefaults, type EmailConnectionTestResult } from '../agent/email/email-service.ts';
+import { requireSecretsManager } from './commands/runtime-services.ts';
+import { persistEmailConfigField } from './commands/email-runtime.ts';
+import { buildAgentWorkspaceRuntimeSnapshot } from './agent-workspace-snapshot.ts';
+import type { AgentWorkspaceActionResult, AgentWorkspaceEmailConnectStatus, AgentWorkspaceLocalEditor, AgentWorkspaceRuntimeSnapshot } from './agent-workspace-types.ts';
+
+type FieldReader = (id: string) => string;
+
+export interface AgentWorkspaceEmailConnectEditorHost {
+  localEditor: AgentWorkspaceLocalEditor | null;
+  runtimeSnapshot: AgentWorkspaceRuntimeSnapshot | null;
+  status: string;
+  lastActionResult: AgentWorkspaceActionResult | null;
+}
+
+/** Fields, in wizard-step order. imapPort/smtpPort/smtpSecurity carry sane defaults. */
+export function createEmailConnectWizardEditor(status: AgentWorkspaceEmailConnectStatus | null): AgentWorkspaceLocalEditor {
+  const message = !status
+    ? 'Connect your inbox. Enter your IMAP/SMTP settings; the password is stored through the Agent secret manager, never in plain config.'
+    : status.connected
+      ? `Currently connected as ${status.username} (${status.imapHost}). Re-enter settings below to reconnect or update credentials.`
+      : status.errors.length > 0
+        ? 'Not connected — connect your inbox. Enter your IMAP/SMTP settings below.'
+        : 'Not connected — connect your inbox. Enter your IMAP/SMTP settings below.';
+  return {
+    kind: 'email-connect-wizard',
+    mode: 'create',
+    title: 'Connect Inbox',
+    selectedFieldIndex: 0,
+    message,
+    fields: [
+      { id: 'imapHost', label: 'IMAP host', value: status?.imapHost ?? '', required: true, multiline: false, hint: 'For example imap.gmail.com.' },
+      { id: 'imapPort', label: 'IMAP port', value: '993', required: true, multiline: false, hint: 'Default 993 (implicit TLS).' },
+      { id: 'smtpHost', label: 'SMTP host', value: '', required: true, multiline: false, hint: 'For example smtp.gmail.com.' },
+      { id: 'smtpPort', label: 'SMTP port', value: '587', required: true, multiline: false, hint: 'Default 587 (STARTTLS) or 465 (TLS).' },
+      { id: 'smtpSecurity', label: 'SMTP security', value: 'auto', required: true, multiline: false, hint: 'tls, starttls, or auto (port-based).' },
+      { id: 'username', label: 'Username', value: status?.username ?? '', required: true, multiline: false, hint: 'Mailbox login, usually your email address.' },
+      { id: 'password', label: 'Password', value: '', required: true, multiline: false, hint: 'Stored through the Agent secret manager. Masked here and never rendered in results.', redact: true },
+      { id: 'fromAddress', label: 'From address', value: status?.username ?? '', required: true, multiline: false, hint: 'Address used in the From: header when sending.' },
+      { id: 'confirm', label: 'Confirm', value: '', required: true, multiline: false, hint: 'Type yes to store these settings and test the connection.' },
+    ],
+  };
+}
+
+/** Field ids that persistEmailConfigField expects, in order — 'password' input maps to the 'passwordRef' config field. */
+const FIELD_TO_EMAIL_KEY: Record<string, string> = {
+  imapHost: 'imapHost',
+  imapPort: 'imapPort',
+  smtpHost: 'smtpHost',
+  smtpPort: 'smtpPort',
+  smtpSecurity: 'smtpSecurity',
+  username: 'username',
+  fromAddress: 'fromAddress',
+};
+
+export type EmailConnectionTester = (
+  getConfig: (key: string) => unknown,
+  secretsManager: { readonly get: (key: string) => Promise<string | null> },
+) => { testConnection(): Promise<EmailConnectionTestResult> };
+
+const defaultTester: EmailConnectionTester = (getConfig, secretsManager) => new EmailService({ getConfig, secretsManager });
+
+export async function submitAgentWorkspaceEmailConnectWizardEditor(
+  host: AgentWorkspaceEmailConnectEditorHost,
+  editor: AgentWorkspaceLocalEditor,
+  context: CommandContext | null,
+  readField: FieldReader,
+  /** Injectable for tests — avoids real network I/O. Production callers omit this and get the real EmailService. */
+  buildTester: EmailConnectionTester = defaultTester,
+): Promise<void> {
+  if (!isAffirmative(readField('confirm'))) {
+    host.localEditor = { ...editor, message: 'Inbox connection not confirmed. Type yes, then press Enter.' };
+    host.status = 'Inbox connection not confirmed.';
+    return;
+  }
+  if (!context) {
+    host.localEditor = { ...editor, message: 'This runtime has no command context; cannot connect the inbox.' };
+    host.status = 'Inbox connect unavailable.';
+    host.lastActionResult = { kind: 'error', title: 'Inbox connect unavailable', detail: 'No command context is available in this runtime.', safety: 'safe' };
+    return;
+  }
+
+  try {
+    const secretsManager = requireSecretsManager(context);
+    ensureEmailConfigDefaults(context.platform.configManager);
+    const cm = context.platform.configManager as unknown as {
+      get: (key: string) => unknown;
+      setDynamic: (key: string, value: unknown) => void;
+      save: () => void;
+    };
+
+    for (const [fieldId, emailKey] of Object.entries(FIELD_TO_EMAIL_KEY)) {
+      const result = await persistEmailConfigField(cm, secretsManager, emailKey, readField(fieldId));
+      if (!result.ok) {
+        host.localEditor = { ...editor, message: result.error ?? `Could not save ${fieldId}.` };
+        host.status = result.error ?? 'Inbox connection settings were invalid.';
+        host.lastActionResult = { kind: 'error', title: 'Inbox settings invalid', detail: result.error ?? `Could not save ${fieldId}.`, safety: 'safe' };
+        return;
+      }
+    }
+    const passwordResult = await persistEmailConfigField(cm, secretsManager, 'passwordRef', readField('password'));
+    if (!passwordResult.ok) {
+      host.localEditor = { ...editor, message: passwordResult.error ?? 'Could not store the password.' };
+      host.status = passwordResult.error ?? 'Inbox password could not be stored.';
+      host.lastActionResult = { kind: 'error', title: 'Inbox password invalid', detail: passwordResult.error ?? 'Could not store the password.', safety: 'safe' };
+      return;
+    }
+    cm.save();
+
+    const service = buildTester((key: string) => cm.get(key), secretsManager);
+    const test = await service.testConnection();
+    if (!test.ok) {
+      host.localEditor = null;
+      host.status = `Inbox connection failed (${test.stage ?? 'unknown'}).`;
+      host.lastActionResult = {
+        kind: 'error',
+        title: 'Inbox connection failed',
+        detail: `Could not verify the mailbox (${test.stage ?? 'unknown'} stage): ${test.error ?? 'unknown error'}. Settings were saved — fix the value above and reconnect.`,
+        safety: 'safe',
+      };
+      host.runtimeSnapshot = buildAgentWorkspaceRuntimeSnapshot(context);
+      return;
+    }
+
+    cm.setDynamic('email.enabled', true);
+    cm.save();
+    host.localEditor = null;
+    host.status = 'Inbox connected.';
+    host.lastActionResult = {
+      kind: 'refreshed',
+      title: 'Inbox connected',
+      detail: `IMAP and SMTP were verified for ${readField('username')}. Inbox workflows are ready.`,
+      safety: 'safe',
+    };
+    host.runtimeSnapshot = buildAgentWorkspaceRuntimeSnapshot(context);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    host.localEditor = { ...editor, message: detail };
+    host.status = detail;
+    host.lastActionResult = { kind: 'error', title: 'Inbox connect failed', detail, safety: 'safe' };
+  }
+}