@pellux/goodvibes-tui 1.24.2 → 1.25.0

package/src/input/commands/connection-status.ts

@@ -0,0 +1,258 @@
+/**
+ * connection-status.ts — honest connection state for the mail and calendar
+ * capabilities, derived from the daemon's own answer rather than re-decided
+ * here.
+ *
+ * The daemon owns mail (IMAP/SMTP) and calendar (CalDAV/ICS) end to end: the
+ * settings resolution, the credential read, the connectors, the confirmation
+ * posture (see src/daemon/handlers/email and src/daemon/handlers/calendar).
+ * The TUI holds no second copy of any of it. So "is mail connected?" is not a
+ * question this file answers from config — it is a question it ASKS, by
+ * invoking the cheapest read verb and reading the failure code that comes back:
+ *
+ *   EMAIL_NOT_CONFIGURED       host/user are missing
+ *   EMAIL_CREDENTIALS_MISSING  host/user are set, the password secret is not
+ *   CALENDAR_NOT_CONFIGURED    CalDAV url/user are missing
+ *
+ * Those codes are the daemon's, and the next step each one implies is the
+ * daemon's requirement, not a guess here. If the daemon changes what it needs,
+ * this surface follows, because it never encoded the rule.
+ *
+ * ## Why the in-process catalog and not the operator HTTP wire
+ *
+ * Every `email.*` / `calendar.*` descriptor the SDK catalogs carries
+ * `invokable: false`. On the generic HTTP/WS dispatch path that flag is checked
+ * by `validateGatewayInvocation` BEFORE any handler lookup and answered with a
+ * flat 400 `NOT_INVOKABLE` — so `sdk.operator.invoke('email.inbox.list', …)`
+ * cannot reach these verbs no matter what is configured, and a surface built on
+ * it would be a dead button.
+ *
+ * `GatewayMethodCatalog.invoke()` deliberately does NOT consult that flag: a
+ * runtime that has registered a real handler is authoritative over whether its
+ * own method works. This product registers those handlers into its own catalog
+ * at composition time (`createDaemonHandlerComposition`, called by the shared
+ * `createRuntimeServices` root that both the TUI and the daemon boot from), so
+ * the in-process catalog is a live, correct route to the same code — the same
+ * seam `/review` already uses for `checkpoints.*`. That is what these surfaces
+ * call.
+ *
+ * Nothing here reads, holds, or renders a credential. The probe asks for one
+ * item and discards it; only presence or absence of a failure reaches the UI.
+ */
+
+import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
+
+export type ConnectionSurface = 'mail' | 'calendar';
+
+/**
+ * What a surface can be.
+ *
+ * `checking` exists because the probe is real I/O and the settings workspace
+ * renders synchronously — a row has to say something true while the answer is
+ * in flight, and "checking" is true where "not configured" would be invented.
+ */
+export type ConnectionState = 'ready' | 'needs-setup' | 'unreachable' | 'checking';
+
+export interface ConnectionStatus {
+  readonly surface: ConnectionSurface;
+  readonly state: ConnectionState;
+  /** One line stating what is actually true right now. Never a credential. */
+  readonly detail: string;
+  /** Concrete next steps. Empty only when the state is `ready`. */
+  readonly nextActions: readonly string[];
+}
+
+/** Display label for a surface. */
+export function connectionSurfaceLabel(surface: ConnectionSurface): string {
+  return surface === 'mail' ? 'Mail' : 'Calendar';
+}
+
+/** The read verb each surface is probed with — the cheapest read it has. */
+export const CONNECTION_PROBE_METHOD = {
+  mail: 'email.inbox.list',
+  calendar: 'calendar.events.list',
+} as const;
+
+/**
+ * The setup steps each daemon failure code implies.
+ *
+ * The `surfaces.*` settings are daemon-owned by prefix (see the SDK's
+ * `config-ownership`), so `/config set` on them lands in the daemon's own
+ * store and keeps working with this client closed — which is the requirement.
+ *
+ * The PASSWORDS now have it too, and these steps changed the round the platform
+ * gave it to them. A credential is filed in the daemon's tier only when a
+ * daemon-owned config path declares it, and the two keys this product's daemon
+ * reads — `surfaces.email.password` and `surfaces.calendar.caldavPassword` —
+ * were declared in neither `CONFIG_SCHEMA` nor the platform's non-schema
+ * daemon-owned path list. `isDaemonOwnedSecretKey()` answered false for both,
+ * so a `/secrets set` filed them in THIS client's store where the daemon never
+ * looks, and telling anyone to run it would have been handing them a step that
+ * silently did nothing. The instruction was the daemon's own environment
+ * instead, because that genuinely reached it.
+ *
+ * The platform release that began serving `email.*` and `calendar.*` declares
+ * the whole mail and CalDAV connection as daemon-owned, so both keys answer
+ * true now and a write carrying an explicit scope is RELOCATED to the daemon
+ * tier rather than filed where it was asked for. `/secrets set` is therefore the
+ * step that works, and it is the better one: it needs no restart and no shell
+ * access to the machine the daemon runs on. The environment still resolves
+ * first, so an operator who already set it there is not broken by this.
+ */
+const DAEMON_TIER_NOTE =
+  'The password reaches the DAEMON: a daemon-owned credential is filed in its tier '
+  + 'no matter which surface stores it, so this keeps working with this client closed.';
+
+const SETUP_STEPS: Readonly<Record<string, readonly string[]>> = {
+  EMAIL_NOT_CONFIGURED: [
+    '/config set surfaces.email.host imap.example.com',
+    '/config set surfaces.email.user you@example.com',
+    `/secrets set GOODVIBES_SURFACES_EMAIL_PASSWORD <password>. ${DAEMON_TIER_NOTE}`,
+  ],
+  EMAIL_CREDENTIALS_MISSING: [
+    `/secrets set GOODVIBES_SURFACES_EMAIL_PASSWORD <password>. ${DAEMON_TIER_NOTE}`,
+  ],
+  CALENDAR_NOT_CONFIGURED: [
+    '/config set surfaces.calendar.caldavUrl https://example.com/dav/',
+    '/config set surfaces.calendar.caldavUser you@example.com',
+    `/secrets set GOODVIBES_SURFACES_CALENDAR_CALDAV_PASSWORD <password>. ${DAEMON_TIER_NOTE}`,
+  ],
+};
+
+/** Message text off an unknown thrown value, without assuming Error. */
+export function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Pull the daemon's machine code off a thrown handler error.
+ *
+ * In-process the throw is the daemon's own `HandlerError`, which carries
+ * `code` directly. The structured wire body is also checked so the same
+ * derivation keeps working if a surface ever reaches these verbs over HTTP.
+ */
+export function daemonErrorCode(error: unknown): string | null {
+  if (typeof error !== 'object' || error === null) return null;
+  const direct = (error as { readonly code?: unknown }).code;
+  if (typeof direct === 'string' && direct.length > 0) return direct;
+  const body = (error as { readonly body?: unknown }).body;
+  if (typeof body === 'object' && body !== null) {
+    const bodyCode = (body as { readonly code?: unknown }).code;
+    if (typeof bodyCode === 'string' && bodyCode.length > 0) return bodyCode;
+  }
+  return null;
+}
+
+/**
+ * Turn a probe outcome into a status. Pure — the caller does the I/O, so every
+ * daemon answer is exercised in tests without a daemon.
+ *
+ * `error === null` means the read verb returned. That is the only evidence
+ * that counts as ready: settings resolved, credential read, server reached.
+ */
+export function describeConnectionProbe(
+  surface: ConnectionSurface,
+  error: unknown,
+): ConnectionStatus {
+  const label = connectionSurfaceLabel(surface);
+
+  if (error === null) {
+    return {
+      surface,
+      state: 'ready',
+      detail: `${label} is connected — the daemon reached the server and returned a result.`,
+      nextActions: [],
+    };
+  }
+
+  const code = daemonErrorCode(error);
+  const steps = code === null ? undefined : SETUP_STEPS[code];
+  if (steps !== undefined) {
+    return {
+      surface,
+      state: 'needs-setup',
+      detail: `${label} is not set up yet: ${errorText(error)}`,
+      nextActions: steps,
+    };
+  }
+
+  // A missing descriptor is a real answer and a different problem from "not
+  // configured". Saying "not set up" here would send the owner off to set
+  // config keys that would change nothing.
+  if (code === 'METHOD_NOT_FOUND' || code === 'NOT_INVOKABLE') {
+    return {
+      surface,
+      state: 'unreachable',
+      detail: `This build does not serve ${CONNECTION_PROBE_METHOD[surface]} (${code}).`,
+      nextActions: [`Update to a build whose daemon serves the ${surface} methods.`],
+    };
+  }
+
+  return {
+    surface,
+    state: 'unreachable',
+    detail: `${label} could not be checked: ${errorText(error)}`,
+    nextActions: ['Check that the runtime composed its daemon handlers: /doctor'],
+  };
+}
+
+/** The status for a surface when the gateway catalog is not wired at all. */
+export function unwiredConnectionStatus(surface: ConnectionSurface): ConnectionStatus {
+  return {
+    surface,
+    state: 'unreachable',
+    detail: `${connectionSurfaceLabel(surface)} runs through the gateway method catalog, which is not wired into this session.`,
+    nextActions: ['Start the full runtime (this surface is unavailable in a reduced harness).'],
+  };
+}
+
+/** The invocation envelope every read on these surfaces uses. */
+export const READ_INVOCATION_CONTEXT = { context: { clientKind: 'tui' as const } };
+
+/**
+ * The invocation envelope a confirmation-gated write needs.
+ *
+ * The daemon's register wrapper demands BOTH `body.confirm === true` and
+ * `context.metadata.explicitUserRequest === true`. The second is set only on
+ * paths where a person typed the command that performs the write, which is the
+ * whole point of the flag — it is never set on a read or on a background
+ * refresh.
+ */
+export const EXPLICIT_WRITE_INVOCATION_CONTEXT = {
+  context: { clientKind: 'tui' as const, metadata: { explicitUserRequest: true } },
+};
+
+/**
+ * Probe one surface against the in-process gateway catalog.
+ *
+ * Asks for a single item — enough to prove the whole path (settings →
+ * credential → connector → server) without pulling a mailbox into memory.
+ */
+export async function probeConnection(
+  gateway: GatewayMethodCatalog | undefined,
+  surface: ConnectionSurface,
+): Promise<ConnectionStatus> {
+  if (!gateway) return unwiredConnectionStatus(surface);
+  try {
+    await gateway.invoke(CONNECTION_PROBE_METHOD[surface], {
+      ...READ_INVOCATION_CONTEXT,
+      body: { limit: 1 },
+    });
+    return describeConnectionProbe(surface, null);
+  } catch (error) {
+    return describeConnectionProbe(surface, error);
+  }
+}
+
+/** Render one status as transcript lines. Used by `/mail` and `/calendar`. */
+export function renderConnectionStatus(status: ConnectionStatus): string {
+  const lines = [
+    `${connectionSurfaceLabel(status.surface)}: ${status.state}`,
+    `  ${status.detail}`,
+  ];
+  if (status.nextActions.length > 0) {
+    lines.push('  Next:');
+    for (const action of status.nextActions) lines.push(`    ${action}`);
+  }
+  return lines.join('\n');
+}

package/src/input/commands/mail-runtime.ts

@@ -0,0 +1,267 @@
+/**
+ * mail-runtime.ts — `/mail`, the terminal surface over the daemon's mail
+ * capability.
+ *
+ * This command implements no mail. Every verb here is one call into the
+ * gateway method catalog, where `src/daemon/handlers/email/` owns IMAP, SMTP,
+ * settings resolution, the credential read, and the confirmation gate. What
+ * lives in this file is argument parsing, rendering, and an honest refusal when
+ * the capability is not set up — nothing else.
+ *
+ * ## What is exposed, and what is not
+ *
+ * Reading (`list`, `read`) and drafting are exposed because checking mail
+ * without leaving the terminal is squarely what this product is for, and
+ * because a draft changes nothing outside the account's own Drafts folder.
+ *
+ * Sending is exposed too — a shipped route with no way to reach it is a route
+ * that is not wired up — but never in one step. `/mail send` first renders
+ * exactly what would leave the machine and stops; only a re-run carrying
+ * `--confirm` sets both flags the daemon's gate demands. That mirrors the
+ * preview-then-confirm shape `/review` uses for hunk reverts, and it means the
+ * dangerous action cannot happen from a typo or a recalled line of history.
+ *
+ * Message bodies are attacker-controlled text. They are printed as transcript
+ * output, which is display-only and never enters the model's message history,
+ * so a body cannot smuggle instructions into a turn by being read here.
+ */
+
+import type { CommandContext, CommandRegistry } from '../command-registry.ts';
+import {
+  EXPLICIT_WRITE_INVOCATION_CONTEXT,
+  READ_INVOCATION_CONTEXT,
+  errorText,
+  probeConnection,
+  renderConnectionStatus,
+} from './connection-status.ts';
+
+/** Inbox summary, exactly the daemon's `email.inbox.list` item shape. */
+interface InboxMessage {
+  readonly uid: number;
+  readonly from: string;
+  readonly subject: string;
+  readonly date: string;
+  readonly unread: boolean;
+  readonly bodyPreview: string;
+}
+
+/** Full message, exactly the daemon's `email.inbox.read` output shape. */
+interface FullMessage {
+  readonly uid: number;
+  readonly from: string;
+  readonly subject: string;
+  readonly date: string;
+  readonly bodyText?: string;
+  readonly attachments?: ReadonlyArray<{ readonly filename: string; readonly sizeBytes: number }>;
+}
+
+const DEFAULT_LIST_LIMIT = 15;
+const MAX_LIST_LIMIT = 100;
+
+function truncate(value: string, width: number): string {
+  const flat = value.replace(/\s+/g, ' ').trim();
+  return flat.length <= width ? flat : `${flat.slice(0, width - 1)}…`;
+}
+
+export function renderInboxList(messages: readonly InboxMessage[]): string {
+  if (messages.length === 0) return 'Inbox is empty (nothing matched).';
+  const lines = [`Inbox — ${messages.length} message${messages.length === 1 ? '' : 's'}:`];
+  for (const message of messages) {
+    const mark = message.unread ? '●' : ' ';
+    lines.push(`  ${mark} ${String(message.uid).padStart(6)}  ${truncate(message.from, 28).padEnd(28)}  ${truncate(message.subject, 48)}`);
+  }
+  lines.push('', '  /mail read <uid> — open one message');
+  return lines.join('\n');
+}
+
+export function renderMessage(message: FullMessage): string {
+  const lines = [
+    `From:    ${message.from}`,
+    `Subject: ${message.subject}`,
+    `Date:    ${message.date}`,
+  ];
+  const attachments = message.attachments ?? [];
+  if (attachments.length > 0) {
+    lines.push(`Files:   ${attachments.map((a) => `${a.filename} (${a.sizeBytes} bytes)`).join(', ')}`);
+  }
+  lines.push('', message.bodyText && message.bodyText.trim().length > 0
+    ? message.bodyText.trimEnd()
+    : '(no plain-text body)');
+  return lines.join('\n');
+}
+
+/**
+ * Split `to | subject | body` on unescaped pipes.
+ *
+ * A pipe rather than positional words because a subject and a body both
+ * contain spaces, and quoting rules invented per-command are their own bug
+ * source. Exactly three fields are required, so a missing one is a clear
+ * usage error rather than a message sent with an empty subject.
+ */
+export function parseComposeArgs(raw: string): { to: string; subject: string; body: string } | null {
+  const parts = raw.split('|').map((part) => part.trim());
+  if (parts.length !== 3) return null;
+  const [to, subject, body] = parts;
+  if (!to || !subject || !body) return null;
+  return { to, subject, body };
+}
+
+function parseLimit(raw: string | undefined): number {
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_LIST_LIMIT;
+  return Math.min(MAX_LIST_LIMIT, Math.floor(parsed));
+}
+
+const USAGE = [
+  'Usage:',
+  '  /mail                       connection status and the latest messages',
+  '  /mail status                connection status only',
+  '  /mail list [n]              list the n most recent messages (default 15)',
+  '  /mail read <uid>            open one message',
+  '  /mail draft <to | subject | body>   save a draft to the account',
+  '  /mail send  <to | subject | body> [--confirm]   preview, then send',
+].join('\n');
+
+export function registerMailRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'mail',
+    aliases: ['email'],
+    description: 'Mail over the daemon: connection status, inbox, read, draft, send',
+    usage: '[status|list|read|draft|send] …',
+    argsHint: '[status|list <n>|read <uid>|draft|send]',
+    async handler(args, ctx) {
+      const gateway = ctx.workspace.gatewayMethods;
+      const sub = (args[0] ?? '').toLowerCase();
+
+      if (sub === 'status') {
+        ctx.print(renderConnectionStatus(await probeConnection(gateway, 'mail')));
+        return;
+      }
+
+      if (!gateway) {
+        ctx.print(renderConnectionStatus(await probeConnection(undefined, 'mail')));
+        return;
+      }
+
+      if (sub === '' || sub === 'list') {
+        await listInbox(ctx, gateway, parseLimit(args[1]), sub === '');
+        return;
+      }
+      if (sub === 'read') {
+        await readMessage(ctx, gateway, args[1]);
+        return;
+      }
+      if (sub === 'draft' || sub === 'send') {
+        await compose(ctx, gateway, sub, args.slice(1));
+        return;
+      }
+      ctx.print(USAGE);
+    },
+  });
+}
+
+type Gateway = NonNullable<CommandContext['workspace']['gatewayMethods']>;
+
+/**
+ * Every failure path renders the connection status rather than a bare error:
+ * "not configured" is far more often the real cause than a transient fault,
+ * and the status carries the exact next step.
+ */
+async function withStatusOnFailure(
+  ctx: CommandContext,
+  gateway: Gateway,
+  label: string,
+  run: () => Promise<void>,
+): Promise<void> {
+  try {
+    await run();
+  } catch (error) {
+    ctx.print(`[mail ${label}] ${errorText(error)}`);
+    ctx.print(renderConnectionStatus(await probeConnection(gateway, 'mail')));
+  }
+}
+
+async function listInbox(ctx: CommandContext, gateway: Gateway, limit: number, withStatus: boolean): Promise<void> {
+  await withStatusOnFailure(ctx, gateway, 'list', async () => {
+    const result = await gateway.invoke('email.inbox.list', {
+      ...READ_INVOCATION_CONTEXT,
+      body: { limit },
+    }) as { readonly messages?: readonly InboxMessage[] };
+    if (withStatus) {
+      ctx.print(renderConnectionStatus({
+        surface: 'mail',
+        state: 'ready',
+        detail: 'Mail is connected — the daemon reached the server and returned a result.',
+        nextActions: [],
+      }));
+    }
+    ctx.print(renderInboxList(result.messages ?? []));
+  });
+}
+
+async function readMessage(ctx: CommandContext, gateway: Gateway, rawUid: string | undefined): Promise<void> {
+  const uid = Number(rawUid);
+  if (!Number.isFinite(uid) || uid <= 0) {
+    ctx.print('Usage: /mail read <uid> — the uid column from /mail list.');
+    return;
+  }
+  await withStatusOnFailure(ctx, gateway, 'read', async () => {
+    const message = await gateway.invoke('email.inbox.read', {
+      ...READ_INVOCATION_CONTEXT,
+      body: { uid },
+    }) as FullMessage;
+    ctx.print(renderMessage(message));
+  });
+}
+
+async function compose(ctx: CommandContext, gateway: Gateway, verb: 'draft' | 'send', rest: readonly string[]): Promise<void> {
+  const raw = rest.filter((part) => part !== '--confirm').join(' ');
+  const confirmed = rest.includes('--confirm');
+  const parsed = parseComposeArgs(raw);
+  if (parsed === null) {
+    ctx.print([
+      `Usage: /mail ${verb} <to | subject | body>`,
+      '  Three fields separated by | — for example:',
+      `  /mail ${verb} me@example.com | Build is green | All gates passed.`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'draft') {
+    await withStatusOnFailure(ctx, gateway, 'draft', async () => {
+      // No `confirm` in the body: the SDK contract for draft.create does not
+      // declare one (its input schema is closed), and the handler is registered
+      // without the confirmation wrapper. Sending one would be a field the
+      // schema rejects.
+      const result = await gateway.invoke('email.draft.create', {
+        ...EXPLICIT_WRITE_INVOCATION_CONTEXT,
+        body: { to: parsed.to, subject: parsed.subject, body: parsed.body },
+      }) as { readonly uid: number; readonly draftId: string };
+      ctx.print(`Draft saved to the account (uid ${result.uid}). Nothing was sent.`);
+    });
+    return;
+  }
+
+  // Send: preview first, always. The daemon would refuse an unconfirmed call
+  // anyway; showing exactly what would leave the machine is the point.
+  if (!confirmed) {
+    ctx.print([
+      'This would send:',
+      `  To:      ${parsed.to}`,
+      `  Subject: ${parsed.subject}`,
+      '',
+      parsed.body,
+      '',
+      'Nothing has been sent. Re-run the same line with --confirm to send it.',
+    ].join('\n'));
+    return;
+  }
+
+  await withStatusOnFailure(ctx, gateway, 'send', async () => {
+    const result = await gateway.invoke('email.send', {
+      ...EXPLICIT_WRITE_INVOCATION_CONTEXT,
+      body: { to: parsed.to, subject: parsed.subject, body: parsed.body, confirm: true },
+    }) as { readonly messageId: string; readonly sentAt: string };
+    ctx.print(`Sent to ${parsed.to} at ${result.sentAt} (message id ${result.messageId}).`);
+  });
+}

package/src/input/commands/review-runtime.ts

@@ -26,7 +26,19 @@ interface RevertHunkResult {
   readonly refusal: { readonly reason: string } | null;
 }
 
-const INVOKE_CONTEXT = { context: { clientKind: 'tui' as const } };
+/**
+ * The review UI's invoke context.
+ *
+ * `explicitUserRequest: true` is honest here and only here-shaped: this path
+ * runs because a person is looking at a hunk and pressed a key. Scheduled
+ * work, triggers and channel-driven work must never set it — the distinction
+ * is exactly "did the owner ask for this right now", and it is what lets a
+ * confirmation-gated verb tell an authorized action apart from one initiated
+ * by content.
+ */
+const INVOKE_CONTEXT = {
+  context: { clientKind: 'tui' as const, metadata: { explicitUserRequest: true } },
+};
 
 /** True for the honest 409 the revert verb throws when the hunk drifted since it was captured. */
 function isConflict(err: unknown): boolean {

package/src/input/commands.ts

@@ -79,6 +79,8 @@ import { registerReviewRuntimeCommands } from './commands/review-runtime.ts';
 import { registerPaletteRuntimeCommands } from './commands/palette-runtime.ts';
 import { registerCiRuntimeCommands } from './commands/ci-runtime.ts';
 import { registerCheckinRuntimeCommands } from './commands/checkin-runtime.ts';
+import { registerMailRuntimeCommands } from './commands/mail-runtime.ts';
+import { registerCalendarRuntimeCommands } from './commands/calendar-runtime.ts';
 import { registerPrincipalsRuntimeCommands } from './commands/principals-runtime.ts';
 
 /**
@@ -173,6 +175,8 @@ export const BUILTIN_COMMAND_GROUPS: readonly BuiltinCommandGroup[] = [
   { category: 'Diff & Review', register: registerReviewRuntimeCommands },
   { category: 'CI', register: registerCiRuntimeCommands },
   { category: 'Check-in', register: registerCheckinRuntimeCommands },
+  { category: 'Mail & Calendar', register: registerMailRuntimeCommands },
+  { category: 'Mail & Calendar', register: registerCalendarRuntimeCommands },
   { category: 'Principals', register: registerPrincipalsRuntimeCommands },
   { category: 'Policy', register: (registry) => registry.register(policyCommand) },
   { category: 'Providers', register: (registry) => registry.register(providerCommand) },

package/src/input/settings-modal-connections.ts

@@ -0,0 +1,102 @@
+/**
+ * settings-modal-connections.ts — the Connections category of the settings
+ * workspace: whether mail and calendar are actually usable, and if not, the
+ * exact next step.
+ *
+ * This category exists because a capability reachable only by typing a slash
+ * command is not, as far as someone clicking through the workspace is
+ * concerned, wired up at all. `/mail status` and `/calendar status` answer the
+ * same question; a person opening `/settings` to see what is connected should
+ * not have to already know those commands exist.
+ *
+ * ## Why the rows arrive asynchronously
+ *
+ * Every other settings category reads a value out of config and renders it.
+ * This one cannot: "is mail connected?" is only answerable by asking the
+ * daemon's handler, which is real I/O. The workspace renders synchronously, so
+ * the rows start in `checking` — which is true — and the refresh replaces them
+ * and asks for a re-render, the same contract the Services surface uses for its
+ * inspections. Nothing is ever shown as "not configured" merely because an
+ * answer has not arrived yet; that would be a guess rendered as a fact.
+ *
+ * No credential is read, held, or rendered here. The probe asks each surface
+ * for one item and keeps only whether it failed and why.
+ */
+
+import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
+import {
+  connectionSurfaceLabel,
+  probeConnection,
+  type ConnectionStatus,
+  type ConnectionSurface,
+} from './commands/connection-status.ts';
+
+/** The surfaces this category covers, in display order. */
+export const CONNECTION_SURFACES: readonly ConnectionSurface[] = ['mail', 'calendar'];
+
+/**
+ * The pre-probe rows.
+ *
+ * Stated as `checking` rather than blank so the category is never empty and
+ * never asserts a state it has not established.
+ */
+export function initialConnectionEntries(): ConnectionStatus[] {
+  return CONNECTION_SURFACES.map((surface) => ({
+    surface,
+    state: 'checking' as const,
+    detail: `Asking the daemon whether ${connectionSurfaceLabel(surface).toLowerCase()} is reachable…`,
+    nextActions: [],
+  }));
+}
+
+/**
+ * Probe every surface. Returns rows in `CONNECTION_SURFACES` order so the
+ * category never reorders itself under the cursor between refreshes.
+ */
+export async function buildConnectionEntries(
+  gateway: GatewayMethodCatalog | undefined,
+): Promise<ConnectionStatus[]> {
+  return Promise.all(CONNECTION_SURFACES.map((surface) => probeConnection(gateway, surface)));
+}
+
+/**
+ * The mutable slice of the settings workspace this module drives. Declared
+ * structurally rather than importing the class, so the split stays a file-size
+ * split and does not become an import cycle.
+ */
+export interface ConnectionsHost {
+  active: boolean;
+  selectedIndex: number;
+  connectionEntries: ConnectionStatus[];
+  connectionsRefreshing: boolean;
+  gatewayMethods: GatewayMethodCatalog | null;
+  requestRender: (() => void) | null;
+}
+
+/**
+ * Refresh the rows from the daemon and repaint.
+ *
+ * A second call while one is in flight is dropped: entering the tab repeatedly
+ * should not queue a probe per keystroke. A probe that lands after the
+ * workspace closed is discarded rather than written, so reopening starts from
+ * `checking` instead of resurrecting an answer about a finished session.
+ */
+export async function refreshConnectionEntries(host: ConnectionsHost): Promise<void> {
+  if (host.connectionsRefreshing) return;
+  host.connectionsRefreshing = true;
+  try {
+    const entries = await buildConnectionEntries(host.gatewayMethods ?? undefined);
+    if (!host.active) return;
+    host.connectionEntries = entries;
+    host.requestRender?.();
+  } finally {
+    host.connectionsRefreshing = false;
+  }
+}
+
+/** The selected row, clamped, or null when the category is empty. */
+export function selectedConnectionEntry(host: ConnectionsHost): ConnectionStatus | null {
+  const entries = host.connectionEntries;
+  if (entries.length === 0) return null;
+  return entries[Math.max(0, Math.min(entries.length - 1, host.selectedIndex))] ?? null;
+}

package/src/input/settings-modal-types.ts

@@ -45,6 +45,7 @@ export type SettingsCategory =
   | 'agents'
   | 'security'
   | 'integrations'
+  | 'connections'
   | 'policy'
   | 'notifications'
   | 'release'
@@ -62,7 +63,7 @@ export const SETTINGS_CATEGORY_GROUPS: ReadonlyArray<{
   { label: 'Interface', categories: ['display', 'ui', 'behavior', 'notifications', 'permissions', 'policy', 'security'] },
   { label: 'AI Routing', categories: ['provider', 'pricing', 'subscriptions', 'helper', 'tools', 'tts', 'voice'] },
   { label: 'Service & Network', categories: ['service', 'daemon', 'network', 'controlPlane', 'httpListener', 'web', 'relay'] },
-  { label: 'Surfaces & Cloud', categories: ['surfaces', 'device', 'conversationGate', 'integrations', 'mcp', 'cloudflare'] },
+  { label: 'Surfaces & Cloud', categories: ['surfaces', 'device', 'conversationGate', 'integrations', 'connections', 'mcp', 'cloudflare'] },
   { label: 'Automation', categories: ['batch', 'automation', 'checkin', 'watchers', 'orchestration', 'planner', 'wrfc'] },
   { label: 'Runtime & Data', categories: ['storage', 'atRest', 'sandbox', 'fetch', 'agents', 'runtime', 'power', 'memory', 'cache', 'telemetry', 'diagnostics', 'learning'] },
   { label: 'Advanced', categories: ['release', 'update', 'danger'] },