@pellux/goodvibes-agent 1.5.5 → 1.5.6

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

@@ -1,61 +1,51 @@
-import type { AgentWorkspaceActionResult, AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
+import type { AgentWorkspaceEditorKind, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
 import type { AgentWorkspaceTaskCommandEditorKind } from './agent-workspace-task-command-editors.ts';
 import { isAgentWorkspaceTaskCommandEditorKind } from './agent-workspace-task-command-editors.ts';
 import { quoteSlashCommandArg } from './slash-command-parser.ts';
+import type { AgentWorkspaceCommandEditorSubmission, AgentWorkspaceCommandSubmissionHandler, AgentWorkspaceFieldReader } from './agent-workspace-command-editor-engine.ts';
+import { buildCommandEditorSubmissionFromTable, dispatchCommandEditorSubmission } from './agent-workspace-command-editor-engine.ts';
 
-type AgentWorkspaceFieldReader = (fieldId: string) => string;
-
-export type AgentWorkspaceTaskCommandEditorSubmission =
-  | {
-    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 AgentWorkspaceTaskCommandEditorSubmission = AgentWorkspaceCommandEditorSubmission;
 
 export function isAgentWorkspaceTaskCommandSubmissionKind(kind: AgentWorkspaceEditorKind): kind is AgentWorkspaceTaskCommandEditorKind {
   return isAgentWorkspaceTaskCommandEditorKind(kind);
 }
 
-export function buildAgentWorkspaceTaskCommandEditorSubmission(
-  editor: AgentWorkspaceLocalEditor,
-  readField: AgentWorkspaceFieldReader,
-): AgentWorkspaceTaskCommandEditorSubmission {
-  if (editor.kind === 'task-list-filter') {
+const TASK_COMMAND_SUBMISSION_HANDLERS: Readonly<Record<AgentWorkspaceTaskCommandEditorKind, AgentWorkspaceCommandSubmissionHandler>> = {
+  'task-list-filter': (_editor, readField) => {
     const filter = readField('filter');
     const command = filter.length > 0 ? `/tasks list ${quoteSlashCommandArg(filter)}` : '/tasks list';
-    return {
-      kind: 'dispatch',
+    return dispatchCommandEditorSubmission(
       command,
-      status: 'Opening filtered task list.',
-      actionResult: {
-        kind: 'dispatched',
-        title: 'Opening filtered task list',
-        detail: 'The workspace handed read-only connected-host task listing to the shell-owned command router.',
-        command,
-        safety: 'read-only',
-      },
-    };
-  }
+      'Opening filtered task list',
+      'The workspace handed read-only connected-host task listing to the shell-owned command router.',
+      'read-only',
+    );
+  },
+  'task-output': (editor, readField) => taskInspection(editor, readField),
+  'task-show': (editor, readField) => taskInspection(editor, readField),
+};
+
+function taskInspection(editor: AgentWorkspaceLocalEditor, readField: AgentWorkspaceFieldReader): AgentWorkspaceCommandEditorSubmission {
   const subcommand = editor.kind === 'task-output' ? 'output' : 'show';
   const command = `/tasks ${subcommand} ${quoteSlashCommandArg(readField('taskId'))}`;
   const title = editor.kind === 'task-output' ? 'Opening task output' : 'Opening task inspection';
-  return {
-    kind: 'dispatch',
+  return dispatchCommandEditorSubmission(
     command,
-    status: `${title}.`,
-    actionResult: {
-      kind: 'dispatched',
-      title,
-      detail: 'The workspace handed read-only connected-host task inspection to the shell-owned command router.',
-      command,
-      safety: 'read-only',
-    },
-  };
+    title,
+    'The workspace handed read-only connected-host task inspection to the shell-owned command router.',
+    'read-only',
+  );
+}
+
+export function buildAgentWorkspaceTaskCommandEditorSubmission(
+  editor: AgentWorkspaceLocalEditor,
+  readField: AgentWorkspaceFieldReader,
+): AgentWorkspaceCommandEditorSubmission {
+  return buildCommandEditorSubmissionFromTable(
+    editor.kind as AgentWorkspaceTaskCommandEditorKind,
+    editor,
+    readField,
+    TASK_COMMAND_SUBMISSION_HANDLERS,
+  );
 }

package/src/input/agent-workspace-task-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 AgentWorkspaceTaskCommandEditorKind = Extract<
   AgentWorkspaceEditorKind,
@@ -9,33 +11,26 @@ export function isAgentWorkspaceTaskCommandEditorKind(kind: AgentWorkspaceEditor
   return kind === 'task-list-filter' || kind === 'task-show' || kind === 'task-output';
 }
 
-export function createAgentWorkspaceTaskCommandEditor(kind: AgentWorkspaceTaskCommandEditorKind): AgentWorkspaceLocalEditor {
-  if (kind === 'task-list-filter') {
-    return {
-      kind,
-      mode: 'create',
-      title: 'Filter Host Tasks',
-      selectedFieldIndex: 0,
-      message: 'List connected-host tasks filtered by status or kind. This is read-only and never creates, retries, or cancels tasks.',
-      fields: [
-        { id: 'filter', label: 'Status or kind', value: '', required: false, multiline: false, hint: 'Optional task status or kind. Blank lists recent tasks.' },
-      ],
-    };
-  }
-  if (kind === 'task-output') {
-    return {
-      kind,
-      mode: 'create',
-      title: 'Show Task Output',
-      selectedFieldIndex: 0,
-      message: 'Print one connected-host task output from the Agent workspace. This is read-only and does not retry, cancel, or mutate the task.',
-      fields: [
-        { id: 'taskId', label: 'Task id', value: '', required: true, multiline: false, hint: 'Connected-host task id from Host tasks.' },
-      ],
-    };
-  }
-  return {
-    kind,
+const TASK_COMMAND_EDITOR_SPECS: Readonly<Record<AgentWorkspaceTaskCommandEditorKind, AgentWorkspaceEditorSpecEntry<AgentWorkspaceTaskCommandEditorKind>>> = {
+  'task-list-filter': {
+    mode: 'create',
+    title: 'Filter Host Tasks',
+    selectedFieldIndex: 0,
+    message: 'List connected-host tasks filtered by status or kind. This is read-only and never creates, retries, or cancels tasks.',
+    fields: [
+      { id: 'filter', label: 'Status or kind', value: '', required: false, multiline: false, hint: 'Optional task status or kind. Blank lists recent tasks.' },
+    ],
+  },
+  'task-output': {
+    mode: 'create',
+    title: 'Show Task Output',
+    selectedFieldIndex: 0,
+    message: 'Print one connected-host task output from the Agent workspace. This is read-only and does not retry, cancel, or mutate the task.',
+    fields: [
+      { id: 'taskId', label: 'Task id', value: '', required: true, multiline: false, hint: 'Connected-host task id from Host tasks.' },
+    ],
+  },
+  'task-show': {
     mode: 'create',
     title: 'Inspect Host Task',
     selectedFieldIndex: 0,
@@ -43,5 +38,9 @@ export function createAgentWorkspaceTaskCommandEditor(kind: AgentWorkspaceTaskCo
     fields: [
       { id: 'taskId', label: 'Task id', value: '', required: true, multiline: false, hint: 'Connected-host task id from Host tasks.' },
     ],
-  };
+  },
+};
+
+export function createAgentWorkspaceTaskCommandEditor(kind: AgentWorkspaceTaskCommandEditorKind): AgentWorkspaceLocalEditor {
+  return createAgentWorkspaceEditorFromTable(kind, TASK_COMMAND_EDITOR_SPECS);
 }

package/src/input/agent-workspace-types.ts

@@ -241,7 +241,12 @@ export type AgentWorkspaceEditorKind =
   | 'workplan-delete'
   | 'workplan-clear-completed'
   | 'routine-schedule'
-  | 'reminder-schedule';
+  | 'reminder-schedule'
+  | 'email-connect-wizard'
+  | 'calendar-connect'
+  | 'calendar-subscribe-wizard'
+  | 'calendar-oauth-google'
+  | 'calendar-oauth-outlook';
 
 export type AgentWorkspaceLocalOperation =
   | 'memory-edit'
@@ -365,6 +370,13 @@ export interface AgentWorkspaceLocalLibraryItem {
   readonly missingRequirementCount?: number;
   readonly missingRequirements?: readonly string[];
   readonly startCount?: number;
+  /** Memory-only (Wave-4 W4-A1B): whether this record currently clears the prompt-injection
+   *  recall floor, per describeMemoryPromptEligibility. */
+  readonly promptEligible?: boolean;
+  /** Memory-only: the honest, per-record reason from describeMemoryPromptEligibility —
+   *  the same wording source prompt-context-receipts.ts and agent-harness-prompt-context.ts
+   *  use, so this workspace snapshot never has to invent its own paraphrase. */
+  readonly promptEligibilityReason?: string;
 }
 
 export interface AgentWorkspaceRecentReviewerHandoffArtifact {
@@ -628,6 +640,14 @@ export interface AgentWorkspaceCompanionAccessSummary {
   readonly nextStep: string;
 }
 
+/** Honest, no-I/O email-connect status (config validation only) for the inbox connect card/wizard (W4-A5). */
+export interface AgentWorkspaceEmailConnectStatus {
+  readonly connected: boolean;
+  readonly username: string;
+  readonly imapHost: string;
+  readonly errors: readonly string[];
+}
+
 export interface AgentWorkspaceRuntimeSnapshot {
   readonly provider: string;
   readonly model: string;
@@ -763,4 +783,18 @@ export interface AgentWorkspaceRuntimeSnapshot {
   readonly setupChecklist: readonly AgentWorkspaceSetupChecklistItem[];
   readonly setupWizard: AgentSetupWizard;
   readonly warnings: readonly string[];
+  /**
+   * True when the most recent render-path attempt to re-derive the live
+   * counters (memory count, routine counts + start counts — W4-A6) failed
+   * and the previous values below had to be kept. A fresh
+   * buildAgentWorkspaceRuntimeSnapshot() call is never stale (it just read
+   * everything); this only flips true from
+   * AgentWorkspace.syncLiveCountersForRender() when a live re-read errors.
+   * The render path uses this to label the counters honestly ("refreshing")
+   * instead of asserting a number the disk might already contradict.
+   */
+  readonly liveCountersStale: boolean;
+  /** Honest email-connect status for the connect wizard's entry state (W4-A5). Null when unavailable in this runtime. */
+  readonly emailConnectStatus: AgentWorkspaceEmailConnectStatus | null;
+  readonly calendarOAuthConfigStatus: { readonly google: boolean; readonly microsoft: boolean } | null; // F1c: per-provider client-id-configured state for the advanced cards
 }

package/src/input/agent-workspace.ts

@@ -21,7 +21,8 @@ import { appendAgentWorkspaceActionSearchText, backspaceAgentWorkspaceActionSear
 import { applyAgentWorkspaceSetupCheckpointAction } from './agent-workspace-setup-checkpoint-action.ts';
 import { agentWorkspaceSettingSchema, applyAgentWorkspaceSettingValue, buildAgentWorkspaceSettingActionDisplay, buildAgentWorkspaceSettingActionEffect, importAgentWorkspaceTuiSettings, isAgentWorkspaceActionVisible, type AgentWorkspaceSettingActionDisplay } from './agent-workspace-settings.ts';
 import { buildAgentWorkspaceRuntimeSnapshot } from './agent-workspace-snapshot.ts';
-import { submitAgentWorkspaceSubscriptionLoginFinishEditor, submitAgentWorkspaceSubscriptionLoginStartEditor, submitAgentWorkspaceSubscriptionLogoutEditor } from './agent-workspace-subscription-editor.ts';
+import { syncAgentWorkspaceLiveCounters } from './agent-workspace-live-counters.ts';
+import { trySubmitDirectHostActionEditor } from './agent-workspace-direct-editor-submission.ts';
 import type { AgentWorkspaceAction, AgentWorkspaceActionResult, AgentWorkspaceActionSearchResult, AgentWorkspaceCategory, AgentWorkspaceCategoryGroup, AgentWorkspaceCommandDispatcher, AgentWorkspaceEditorField, AgentWorkspaceFocusPane, AgentWorkspaceLocalEditor, AgentWorkspaceLocalEditorKind, AgentWorkspaceLocalLibraryItem, AgentWorkspaceLocalOperation, AgentWorkspacePromptDispatcher, AgentWorkspaceRuntimeSnapshot } from './agent-workspace-types.ts';
 import { ONBOARDING_COMPLETE_SYNTHETIC_ACTION, shouldShowOnboardingFinishFooter } from './agent-workspace-onboarding-finish.ts';
 import { completeOnboardingAction, onSubscriptionLoginSuccessAction } from './agent-workspace-onboarding-actions.ts';
@@ -218,6 +219,8 @@ export class AgentWorkspace {
     this.lastActionResult = { kind: 'refreshed', title: 'Runtime context refreshed', detail: 'Provider, model, session, local memory, runtime endpoint, and Agent knowledge route posture were re-read from the live command context.' };
   }
 
+  /** W4-A6 render-path live counter mirror (see syncAgentWorkspaceLiveCounters). */ syncLiveCountersForRender(): void { syncAgentWorkspaceLiveCounters({ context: this.context, runtimeSnapshot: this.runtimeSnapshot, setRuntimeSnapshot: (snapshot) => { this.runtimeSnapshot = snapshot; }, clampSelection: () => this.clampSelection() }); }
+
   cancelLocalEditor(): void {
     if (!this.localEditor) return;
     const title = this.localEditor.title;
@@ -554,19 +557,7 @@ export class AgentWorkspace {
       this.status = `${missing.label} is required.`;
       return;
     }
-    if (editor.kind === 'subscription-login-start') {
-      void submitAgentWorkspaceSubscriptionLoginStartEditor(this, editor, this.context, (id) => this.editorField(id)).finally(() => requestRender?.());
-      return;
-    }
-    if (editor.kind === 'subscription-login-finish') {
-      void submitAgentWorkspaceSubscriptionLoginFinishEditor(this, editor, this.context, (id) => this.editorField(id)).finally(() => requestRender?.());
-      return;
-    }
-    if (editor.kind === 'subscription-logout') {
-      submitAgentWorkspaceSubscriptionLogoutEditor(this, editor, this.context, (id) => this.editorField(id));
-      requestRender?.();
-      return;
-    }
+    if (trySubmitDirectHostActionEditor(this, editor, this.context, (id) => this.editorField(id), requestRender)) return;
     if (isAgentWorkspaceCommandEditorKind(editor.kind)) {
       this.submitCommandEditor(editor);
       requestRender?.();

package/src/input/command-registry.ts

@@ -259,8 +259,30 @@ export class CommandRegistry {
   private commands = new Map<string, SlashCommand>();
   private aliasIndex = new Map<string, SlashCommand>();
 
-  /** Register a command. Also indexes all aliases for O(1) lookup. */
+  /**
+   * Register a command. Also indexes all aliases for O(1) lookup.
+   *
+   * Collisions are LOUD: a second registration of the same primary name, or an
+   * alias that shadows an existing command's name or alias, throws instead of
+   * silently overwriting. Silent last-write-wins hid a real /session
+   * double-registration (session-workflow.ts vs commands/session.ts); the fork
+   * bypassed this check, so make it fail fast at startup instead.
+   */
   register(command: SlashCommand): void {
+    const existingByName = this.commands.get(command.name) ?? this.aliasIndex.get(command.name);
+    if (existingByName) {
+      throw new Error(
+        `Command registration collision: "${command.name}" is already registered by /${existingByName.name}.`,
+      );
+    }
+    for (const alias of command.aliases ?? []) {
+      const holder = this.commands.get(alias) ?? this.aliasIndex.get(alias);
+      if (holder) {
+        throw new Error(
+          `Command alias collision: "${alias}" on /${command.name} is already registered by /${holder.name}.`,
+        );
+      }
+    }
     this.commands.set(command.name, command);
     for (const alias of command.aliases ?? []) {
       this.aliasIndex.set(alias, command);

package/src/input/commands/calendar-connect-runtime.ts

@@ -0,0 +1,226 @@
+/**
+ * calendar-connect-runtime.ts — the /calendar connect|disconnect|accounts subcommands
+ * and the provider-event merge for /calendar upcoming (W4-A10).
+ *
+ * The OAuth network dance lives here (not in the workspace card) because a command
+ * handler can print the authorization URL / device user-code IMMEDIATELY, then await
+ * the browser callback or poll the device code. The default path uses the bundled
+ * project client id + PKCE; a power user's own client id/secret come from config +
+ * the secret manager (captured by the advanced workspace card). No secret is ever put
+ * into a command string.
+ *
+ * The service is injectable so tests drive every path against fakes with no real
+ * network, port, or browser.
+ */
+import type { CalendarProviderId, DeviceCodeFlowStart, EventWindow, MergedCalendarEvent } from '@pellux/goodvibes-sdk/platform/calendar';
+import type { CommandContext } from '../command-registry.ts';
+import { requireSecretsManager } from './runtime-services.ts';
+import { CalendarOAuthService, type CalendarConfigReader, type CalendarSecretSlice } from '../../agent/calendar/calendar-oauth-service.ts';
+
+/** Factory seam: production builds the real service from context; tests inject a fake. */
+export type CalendarServiceFactory = (ctx: CommandContext) => CalendarOAuthService;
+
+const PROVIDER_LABEL: Record<CalendarProviderId, string> = { google: 'Google Calendar', microsoft: 'Microsoft Outlook' };
+
+const CONNECTION_STATE_NOTE: Record<string, string> = {
+  connected: 'connected',
+  'refresh-due': 'connected (token refresh due)',
+  'reconnect-needed': 'reconnect needed — run the connect command again',
+  disconnected: 'disconnected',
+};
+
+/** Map the user's provider word to a provider id ('outlook' and 'microsoft' both ok). */
+export function normalizeProvider(word: string | undefined): CalendarProviderId | null {
+  const w = (word ?? '').trim().toLowerCase();
+  if (w === 'google' || w === 'gcal') return 'google';
+  if (w === 'outlook' || w === 'microsoft' || w === 'ms' || w === 'msft') return 'microsoft';
+  return null;
+}
+
+function defaultServiceFactory(ctx: CommandContext): CalendarOAuthService {
+  const config = ctx.platform.configManager as unknown as CalendarConfigReader;
+  const secrets = requireSecretsManager(ctx) as unknown as CalendarSecretSlice;
+  return new CalendarOAuthService({ config, secrets });
+}
+
+function deviceCodeMessage(label: string, start: DeviceCodeFlowStart): string {
+  return [
+    `Authorize ${label} on another device or browser:`,
+    `  1. Open ${start.verificationUri}`,
+    `  2. Enter the code: ${start.userCode}`,
+    start.verificationUriComplete ? `  (or open directly: ${start.verificationUriComplete})` : '',
+    '  Waiting for approval...',
+  ].filter(Boolean).join('\n');
+}
+
+function authUrlMessage(label: string, url: string): string {
+  return [
+    `Authorize ${label} in your browser:`,
+    `  ${url}`,
+    '  (Attempting to open it automatically. Waiting for the redirect...)',
+  ].join('\n');
+}
+
+/**
+ * The real guide for a bare `/calendar connect` (F1a): what connecting does, the
+ * two providers, and — since this build ships only the SDK's placeholder client
+ * ids until someone registers a project app — the honest situation and the exact
+ * next step, instead of a bare usage line that dead-ends with no explanation.
+ */
+function connectGuideMessage(): string {
+  return [
+    'Connect a calendar account over OAuth so its events show up alongside your local ones in /calendar upcoming.',
+    '  Providers: google (Google Calendar), outlook (Microsoft Outlook)',
+    '    /calendar connect google',
+    '    /calendar connect outlook',
+    '    (add --device to sign in with a device code instead of a browser)',
+    '',
+    'This build has no built-in Google/Microsoft sign-in configured yet — there is no project ' +
+      'client id shipped, so a bare connect will stop at the config step and tell you so. To ' +
+      'connect, you need a client id:',
+    '  1. Register a free OAuth app with the provider (Google Cloud Console, or the Azure portal for Microsoft).',
+    '  2. Copy the client id it gives you — a desktop/public-client app needs no secret.',
+    '  3. Open /agent personal-ops -> "Connect Google Calendar (advanced)" or "Connect Microsoft Outlook (advanced)" and paste it in.',
+    '  4. Run /calendar connect google (or outlook) again to authorize.',
+  ].join('\n');
+}
+
+/** An unrecognized provider word (not a missing one) keeps the short usage form. */
+function unknownProviderMessage(word: string): string {
+  return `Unknown calendar provider '${word}'. Usage: /calendar connect <google|outlook> [--device]`;
+}
+
+/** Best-effort browser open; never throws, never blocks the flow. */
+function bestEffortOpenBrowser(url: string): void {
+  void (async () => {
+    try {
+      const { spawn } = await import('node:child_process');
+      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+      const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+      const child = spawn(opener, args, { stdio: 'ignore', detached: true });
+      child.on('error', () => {});
+      child.unref();
+    } catch {
+      // ignore — the URL was already printed for the user to open manually
+    }
+  })();
+}
+
+export async function runCalendarConnect(
+  args: readonly string[],
+  ctx: CommandContext,
+  factory: CalendarServiceFactory = defaultServiceFactory,
+): Promise<void> {
+  const provider = normalizeProvider(args[1]);
+  if (!provider) {
+    ctx.print(args[1] ? unknownProviderMessage(args[1]) : connectGuideMessage());
+    return;
+  }
+  const label = PROVIDER_LABEL[provider];
+  const device = args.includes('--device');
+  const service = factory(ctx);
+
+  ctx.print(`Connecting ${label}...`);
+  const result = device
+    ? await service.connectDeviceCode(provider, { onDeviceCode: (s) => ctx.print(deviceCodeMessage(label, s)) })
+    : await service.connectAuto(provider, {
+        openUrl: (url) => {
+          ctx.print(authUrlMessage(label, url));
+          bestEffortOpenBrowser(url);
+        },
+        onDeviceCode: (s) => ctx.print(deviceCodeMessage(label, s)),
+      });
+
+  if (!result.ok) {
+    ctx.print([
+      `Could not connect ${label} (${result.stage ?? 'unknown'} stage).`,
+      `  ${result.error ?? 'unknown error'}`,
+    ].join('\n'));
+    return;
+  }
+  ctx.print([
+    `Connected ${label}.`,
+    `  account ${result.account?.label ?? provider}`,
+    `  via     ${result.transport === 'device-code' ? 'device code' : 'browser sign-in'}`,
+    `  scopes  ${(result.account?.scopes ?? []).join(', ') || '(none reported)'}`,
+  ].join('\n'));
+}
+
+export async function runCalendarDisconnect(
+  args: readonly string[],
+  ctx: CommandContext,
+  factory: CalendarServiceFactory = defaultServiceFactory,
+): Promise<void> {
+  const provider = normalizeProvider(args[1]);
+  if (!provider) {
+    ctx.print('Usage: /calendar disconnect <google|outlook>');
+    return;
+  }
+  const label = PROVIDER_LABEL[provider];
+  const service = factory(ctx);
+  const { revokedRemotely } = await service.disconnect(provider);
+  ctx.print([
+    `Disconnected ${label}.`,
+    revokedRemotely
+      ? '  The access was revoked at the provider and local tokens were cleared.'
+      : '  Local tokens were cleared. This provider offers no token-revocation endpoint, so revoke access in your account settings if desired.',
+  ].join('\n'));
+}
+
+export async function runCalendarAccounts(
+  ctx: CommandContext,
+  factory: CalendarServiceFactory = defaultServiceFactory,
+): Promise<void> {
+  const service = factory(ctx);
+  const accounts = await service.listAccounts();
+  if (accounts.length === 0) {
+    ctx.print([
+      'Connected calendar accounts',
+      '  None. Connect one with /calendar connect google  or  /calendar connect outlook',
+    ].join('\n'));
+    return;
+  }
+  ctx.print([
+    `Connected calendar accounts (${accounts.length})`,
+    ...accounts.map(({ account, state }) =>
+      `  ${PROVIDER_LABEL[account.provider]}  ${account.label}  [${CONNECTION_STATE_NOTE[state] ?? state}]`,
+    ),
+  ].join('\n'));
+}
+
+/**
+ * Best-effort fetch of provider events for the upcoming window, source-labeled. A
+ * provider failure (reconnect needed, rate limit, etc.) is reported as an honest note
+ * rather than aborting the whole /calendar upcoming view.
+ */
+export async function fetchProviderUpcoming(
+  ctx: CommandContext,
+  window: EventWindow,
+  factory: CalendarServiceFactory = defaultServiceFactory,
+): Promise<{ readonly events: MergedCalendarEvent[]; readonly notes: string[] }> {
+  const service = factory(ctx);
+  const accounts = await service.listAccounts();
+  if (accounts.length === 0) return { events: [], notes: [] };
+  const events: MergedCalendarEvent[] = [];
+  const notes: string[] = [];
+  for (const { account } of accounts) {
+    try {
+      const config = await service.resolveConfig(account.provider);
+      const providerEvents = await service.listEventsForProvider(config, window);
+      events.push(...providerEvents);
+    } catch (error) {
+      notes.push(`  ${PROVIDER_LABEL[account.provider]}: could not load events — ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return { events, notes };
+}
+
+/** Render a source label for a merged event. */
+export function sourceLabel(source: MergedCalendarEvent['source']): string {
+  switch (source) {
+    case 'google-api': return 'google';
+    case 'microsoft-graph': return 'outlook';
+    case 'ics-feed': return 'feed';
+    default: return 'local';
+  }
+}