@pellux/goodvibes-tui 0.19.24 → 0.19.26

package/src/runtime/onboarding/types.ts

@@ -0,0 +1,402 @@
+import type { ConfigManager, ConfigKey, GoodVibesConfig } from '../../config/index.ts';
+import type { SecretsManager, SecretRecord, SecretStorageReview } from '../../config/secrets.ts';
+import type { LocalAuthSnapshot, UserAuthManager } from '@pellux/goodvibes-sdk/platform/security/user-auth';
+import type { ShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
+import type {
+  LocalAuthInspectionQuery,
+  ServiceInspectionQuery,
+  SubscriptionAccessQuery,
+} from '../ui-service-queries.ts';
+
+export type OnboardingMode = 'new' | 'edit' | 'reopen';
+
+export type OnboardingNetworkMode = 'local-network-default' | 'custom';
+
+export type OnboardingAcknowledgementTarget = 'providers' | 'subscriptions' | 'auth';
+
+export type OnboardingAcknowledgementReason =
+  | 'not-needed'
+  | 'configured-routing'
+  | 'customized-config'
+  | 'subscription-state'
+  | 'pending-login'
+  | 'auth-state'
+  | 'bootstrap-credential'
+  | 'active-sessions';
+
+export type OnboardingVerificationStatus = 'pass' | 'warn' | 'fail';
+
+export type OnboardingCompletionMarkerScope = 'user' | 'project';
+
+export type OnboardingCompletionMarkerSource = 'wizard' | 'command' | 'import' | 'unknown';
+
+export interface OnboardingConfigSnapshot {
+  readonly display: GoodVibesConfig['display'];
+  readonly provider: GoodVibesConfig['provider'];
+  readonly behavior: GoodVibesConfig['behavior'];
+  readonly storage: GoodVibesConfig['storage'];
+  readonly permissions: GoodVibesConfig['permissions'];
+  readonly helper: GoodVibesConfig['helper'];
+  readonly tools: Pick<GoodVibesConfig['tools'], 'llmEnabled' | 'llmProvider' | 'llmModel'>;
+  readonly danger: GoodVibesConfig['danger'];
+  readonly controlPlane: GoodVibesConfig['controlPlane'];
+  readonly httpListener: GoodVibesConfig['httpListener'];
+  readonly web: GoodVibesConfig['web'];
+  readonly network: GoodVibesConfig['network'];
+  readonly surfaces: GoodVibesConfig['surfaces'];
+  readonly service: GoodVibesConfig['service'];
+}
+
+export interface OnboardingProviderRoutingSnapshot {
+  readonly primaryProviderId: string;
+  readonly primaryModelId: string;
+  readonly primaryReasoningEffort: GoodVibesConfig['provider']['reasoningEffort'];
+  readonly embeddingProviderId: string;
+  readonly systemPromptFile: string;
+  readonly helperEnabled: boolean;
+  readonly helperProviderId: string;
+  readonly helperModelId: string;
+  readonly toolLlmEnabled: boolean;
+  readonly toolProviderId: string;
+  readonly toolModelId: string;
+}
+
+export interface OnboardingServiceState {
+  readonly name: string;
+  readonly providerId: string;
+  readonly baseUrl: string | null;
+  readonly authType: 'bearer' | 'basic' | 'api-key' | 'oauth';
+  readonly tokenKey: string;
+  readonly oauthConfigured: boolean;
+  readonly hasPrimaryCredential: boolean;
+  readonly hasPasswordCredential: boolean;
+  readonly hasWebhookUrl: boolean;
+  readonly hasSigningSecret: boolean;
+  readonly hasPublicKey: boolean;
+}
+
+export interface OnboardingServicesSnapshot {
+  readonly total: number;
+  readonly oauthProviderIds: readonly string[];
+  readonly services: readonly OnboardingServiceState[];
+}
+
+export interface OnboardingSubscriptionsSnapshot {
+  readonly active: ReturnType<SubscriptionAccessQuery['list']>;
+  readonly pending: ReturnType<SubscriptionAccessQuery['listPending']>;
+  readonly activeProviderIds: readonly string[];
+  readonly pendingProviderIds: readonly string[];
+}
+
+export interface OnboardingSecretsSnapshot {
+  readonly review: SecretStorageReview;
+  readonly records: readonly SecretRecord[];
+}
+
+export interface OnboardingAuthSnapshot {
+  readonly snapshot: LocalAuthSnapshot;
+}
+
+export interface OnboardingBindSettingsSnapshot {
+  readonly daemonEnabled: boolean;
+  readonly httpListenerEnabled: boolean;
+  readonly controlPlane: GoodVibesConfig['controlPlane'];
+  readonly httpListener: GoodVibesConfig['httpListener'];
+  readonly web: GoodVibesConfig['web'];
+}
+
+export interface OnboardingSurfaceRecord {
+  readonly id: string;
+  readonly kind: string;
+  readonly label: string;
+  readonly enabled: boolean;
+  readonly state: string;
+  readonly capabilities: readonly string[];
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+export interface OnboardingSurfacesSnapshot {
+  readonly configuredEnabledKinds: readonly string[];
+  readonly records: readonly OnboardingSurfaceRecord[];
+}
+
+export interface OnboardingProviderAccountRecord {
+  readonly providerId: string;
+  readonly configured: boolean;
+  readonly active: boolean;
+  readonly oauthReady: boolean;
+  readonly pendingLogin: boolean;
+  readonly availableRoutes: readonly string[];
+  readonly activeRoute: string;
+  readonly authFreshness: string;
+}
+
+export interface OnboardingProviderAccountsSnapshot {
+  readonly capturedAt: number;
+  readonly configuredCount: number;
+  readonly issueCount: number;
+  readonly providers: readonly OnboardingProviderAccountRecord[];
+}
+
+export interface OnboardingRuntimeDefaultsSnapshot {
+  readonly providerReasoningEffort: GoodVibesConfig['provider']['reasoningEffort'];
+  readonly permissionsMode: GoodVibesConfig['permissions']['mode'];
+  readonly behavior: GoodVibesConfig['behavior'];
+  readonly display: GoodVibesConfig['display'];
+  readonly secretStoragePolicy: GoodVibesConfig['storage']['secretPolicy'];
+}
+
+export interface OnboardingAcknowledgementSnapshot {
+  readonly scope: OnboardingCompletionMarkerScope;
+  readonly exists: boolean;
+  readonly updatedAt: number | null;
+  readonly source: string | null;
+  readonly mode?: OnboardingMode;
+  readonly workspaceRoot?: string;
+  readonly accepted: Partial<Record<OnboardingAcknowledgementTarget, boolean>>;
+}
+
+export type OnboardingSnapshotCollectionIssueArea =
+  | 'services'
+  | 'subscriptions-active'
+  | 'subscriptions-pending'
+  | 'auth'
+  | 'secrets-review'
+  | 'secrets-records'
+  | 'surfaces'
+  | 'provider-accounts'
+  | 'acknowledgements';
+
+export interface OnboardingSnapshotCollectionIssue {
+  readonly area: OnboardingSnapshotCollectionIssueArea;
+  readonly message: string;
+}
+
+export interface OnboardingSnapshotState {
+  readonly capturedAt: number;
+  readonly config: OnboardingConfigSnapshot;
+  readonly providerRouting: OnboardingProviderRoutingSnapshot;
+  readonly runtimeDefaults: OnboardingRuntimeDefaultsSnapshot;
+  readonly acknowledgements: OnboardingAcknowledgementSnapshot;
+  readonly services: OnboardingServicesSnapshot;
+  readonly subscriptions: OnboardingSubscriptionsSnapshot;
+  readonly secrets: OnboardingSecretsSnapshot;
+  readonly auth: OnboardingAuthSnapshot;
+  readonly bindSettings: OnboardingBindSettingsSnapshot;
+  readonly surfaces: OnboardingSurfacesSnapshot;
+  readonly providerAccounts: OnboardingProviderAccountsSnapshot | null;
+  readonly collectionIssues: readonly OnboardingSnapshotCollectionIssue[];
+}
+
+export type OnboardingStep1CapabilityId =
+  | 'local-tui-only'
+  | 'browser-access'
+  | 'network-access'
+  | 'webhook-events'
+  | 'external-integrations';
+
+export interface OnboardingStep1CapabilityItem {
+  readonly id: OnboardingStep1CapabilityId;
+  readonly label: string;
+  readonly selected: boolean;
+  readonly detail: string;
+}
+
+export interface OnboardingStep1CapabilityFlags {
+  readonly providers: boolean;
+  readonly services: boolean;
+  readonly subscriptions: boolean;
+  readonly auth: boolean;
+  readonly controlPlane: boolean;
+  readonly httpListener: boolean;
+  readonly web: boolean;
+  readonly surfaces: boolean;
+}
+
+export interface OnboardingAcknowledgementState {
+  readonly required: boolean;
+  readonly accepted: boolean;
+  readonly reason: OnboardingAcknowledgementReason;
+  readonly detail: string;
+}
+
+export interface OnboardingReopenEditAcknowledgementState {
+  readonly providers: OnboardingAcknowledgementState;
+  readonly subscriptions: OnboardingAcknowledgementState;
+  readonly auth: OnboardingAcknowledgementState;
+}
+
+export interface OnboardingStepDerivationState {
+  readonly step1Capabilities: readonly OnboardingStep1CapabilityItem[];
+  readonly step1_5NetworkMode: OnboardingNetworkMode;
+  readonly reopenEditAcknowledgements: OnboardingReopenEditAcknowledgementState;
+}
+
+export type OnboardingApplyOperation =
+  | {
+      readonly kind: 'set-config';
+      readonly key: ConfigKey;
+      readonly value: unknown;
+      readonly scope?: 'global' | 'project';
+    }
+  | {
+      readonly kind: 'set-secret';
+      readonly key: string;
+      readonly value: string;
+      readonly scope?: 'project' | 'user';
+      readonly medium: 'secure' | 'plaintext';
+    }
+  | {
+      readonly kind: 'ensure-auth-user';
+      readonly username: string;
+      readonly password: string;
+      readonly roles?: readonly string[];
+      readonly createSession?: boolean;
+      readonly retireBootstrapCredential?: boolean;
+    }
+  | {
+      readonly kind: 'acknowledge';
+      readonly target: OnboardingAcknowledgementTarget;
+      readonly acknowledged: boolean;
+    }
+  | {
+      readonly kind: 'set-completion-marker';
+      readonly scope: OnboardingCompletionMarkerScope;
+      readonly completed: boolean;
+      readonly payload?: Partial<OnboardingCompletionMarkerPayload>;
+    };
+
+export interface OnboardingApplyRequest {
+  readonly mode: OnboardingMode;
+  readonly source: string;
+  readonly operations: readonly OnboardingApplyOperation[];
+}
+
+export interface OnboardingAppliedOperation {
+  readonly kind: OnboardingApplyOperation['kind'];
+  readonly summary: string;
+}
+
+export interface OnboardingSkippedOperation {
+  readonly kind: OnboardingApplyOperation['kind'];
+  readonly reason: string;
+}
+
+export interface OnboardingApplyError {
+  readonly kind: OnboardingApplyOperation['kind'];
+  readonly message: string;
+}
+
+export interface OnboardingApplyResult {
+  readonly ok: boolean;
+  readonly applied: readonly OnboardingAppliedOperation[];
+  readonly skipped: readonly OnboardingSkippedOperation[];
+  readonly errors: readonly OnboardingApplyError[];
+}
+
+export interface OnboardingVerificationItem {
+  readonly id: string;
+  readonly status: OnboardingVerificationStatus;
+  readonly message: string;
+  readonly target?: string;
+}
+
+export interface OnboardingVerificationResult {
+  readonly verifiedAt: number;
+  readonly ok: boolean;
+  readonly items: readonly OnboardingVerificationItem[];
+}
+
+export interface OnboardingAcknowledgementRuntimeState {
+  readonly version: 1;
+  readonly updatedAt: number;
+  readonly source: string;
+  readonly mode?: OnboardingMode;
+  readonly workspaceRoot?: string;
+  readonly acknowledgements: Partial<Record<OnboardingAcknowledgementTarget, boolean>>;
+}
+
+export interface OnboardingCompletionMarkerPayload {
+  readonly version: 1;
+  readonly completedAt: number;
+  readonly updatedAt: number;
+  readonly source: OnboardingCompletionMarkerSource;
+  readonly mode?: OnboardingMode;
+  readonly workspaceRoot?: string;
+}
+
+export interface OnboardingCompletionMarkerState {
+  readonly scope: OnboardingCompletionMarkerScope;
+  readonly path: string;
+  readonly exists: boolean;
+  readonly payload: OnboardingCompletionMarkerPayload | null;
+  readonly parseError?: string;
+}
+
+export interface OnboardingCompletionMarkersState {
+  readonly user: OnboardingCompletionMarkerState;
+  readonly project: OnboardingCompletionMarkerState;
+  readonly effective: OnboardingCompletionMarkerState | null;
+}
+
+export interface WriteOnboardingCompletionMarkerOptions {
+  readonly scope?: OnboardingCompletionMarkerScope;
+  readonly completedAt?: number;
+  readonly updatedAt?: number;
+  readonly source?: OnboardingCompletionMarkerSource;
+  readonly mode?: OnboardingMode;
+  readonly workspaceRoot?: string;
+}
+
+export interface OnboardingSurfaceReadHelper {
+  list(): readonly OnboardingSurfaceRecord[] | Promise<readonly OnboardingSurfaceRecord[]>;
+}
+
+export interface OnboardingProviderAccountReadHelper {
+  loadSnapshot(): Promise<OnboardingProviderAccountsSnapshot>;
+}
+
+export type OnboardingShellPaths = Pick<
+  ShellPathService,
+  'workingDirectory' | 'resolveProjectPath' | 'resolveUserPath'
+>;
+
+export interface OnboardingSnapshotDependencies {
+  readonly clock?: () => number;
+  readonly config: Pick<ConfigManager, 'get' | 'getCategory'>;
+  readonly subscriptions: Pick<SubscriptionAccessQuery, 'list' | 'listPending' | 'get' | 'getPending'>;
+  readonly secrets: Pick<SecretsManager, 'inspect' | 'listDetailed'>;
+  readonly auth: Pick<LocalAuthInspectionQuery, 'inspect'>;
+  readonly services: Pick<ServiceInspectionQuery, 'getAll' | 'inspect'>;
+  readonly surfaces?: OnboardingSurfaceReadHelper;
+  readonly providerAccounts?: OnboardingProviderAccountReadHelper;
+  readonly shellPaths?: OnboardingShellPaths;
+  readonly acknowledgementScope?: OnboardingCompletionMarkerScope;
+}
+
+export interface OnboardingApplyDependencies {
+  readonly clock?: () => number;
+  readonly config: Pick<ConfigManager, 'get' | 'getRaw' | 'load' | 'setDynamic'>;
+  readonly secrets?: Pick<SecretsManager, 'delete' | 'get' | 'inspect' | 'set'>;
+  readonly auth?: Pick<
+    UserAuthManager,
+    'addUser'
+    | 'clearBootstrapCredentialFile'
+    | 'createSession'
+    | 'deleteUser'
+    | 'getUser'
+    | 'inspect'
+    | 'revokeSession'
+  >;
+  readonly shellPaths: OnboardingShellPaths;
+  readonly acknowledgementScope?: OnboardingCompletionMarkerScope;
+}
+
+export interface OnboardingVerificationDependencies {
+  readonly clock?: () => number;
+  readonly config: Pick<ConfigManager, 'get'>;
+  readonly secrets?: Pick<SecretsManager, 'get'>;
+  readonly auth?: Pick<UserAuthManager, 'inspect'>;
+  readonly shellPaths: OnboardingShellPaths;
+  readonly acknowledgementScope?: OnboardingCompletionMarkerScope;
+}

package/src/runtime/onboarding/verify.ts

@@ -0,0 +1,233 @@
+import { isSecretRefInput } from '@pellux/goodvibes-sdk/platform/config/secret-refs';
+import { readOnboardingCompletionMarker } from './markers.ts';
+import { readOnboardingRuntimeState } from './state.ts';
+import type {
+  OnboardingApplyOperation,
+  OnboardingApplyRequest,
+  OnboardingVerificationDependencies,
+  OnboardingVerificationItem,
+  OnboardingVerificationResult,
+} from './types.ts';
+
+function getNow(deps: Pick<OnboardingVerificationDependencies, 'clock'>): number {
+  return deps.clock?.() ?? Date.now();
+}
+
+function normalizeCompletionSource(source: string): 'wizard' | 'command' | 'import' | 'unknown' {
+  if (source === 'wizard' || source === 'command' || source === 'import') return source;
+  return 'unknown';
+}
+
+function isDeepEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => isDeepEqual(value, right[index]));
+  }
+
+  if (
+    typeof left === 'object' && left !== null
+    && typeof right === 'object' && right !== null
+    && !Array.isArray(left)
+    && !Array.isArray(right)
+  ) {
+    const leftEntries = Object.entries(left);
+    const rightEntries = Object.entries(right);
+    if (leftEntries.length !== rightEntries.length) return false;
+
+    return leftEntries.every(([key, value]) => isDeepEqual(value, (right as Record<string, unknown>)[key]));
+  }
+
+  return false;
+}
+
+function isGoodVibesSecretRefInput(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://secrets/') && isSecretRefInput(normalized);
+}
+
+function verifyConfigOperation(
+  deps: OnboardingVerificationDependencies,
+  operation: Extract<OnboardingApplyOperation, { kind: 'set-config' }>,
+): OnboardingVerificationItem {
+  const actual = deps.config.get(operation.key);
+  const ok = isDeepEqual(actual, operation.value);
+
+  return {
+    id: `config:${operation.key}`,
+    status: ok ? 'pass' : 'fail',
+    message: ok
+      ? `${operation.key} matches the requested onboarding value.`
+      : `${operation.key} does not match the requested onboarding value.`,
+    target: operation.key,
+  };
+}
+
+function verifyAcknowledgementOperation(
+  deps: OnboardingVerificationDependencies,
+  operation: Extract<OnboardingApplyOperation, { kind: 'acknowledge' }>,
+): OnboardingVerificationItem {
+  const state = readOnboardingRuntimeState(deps.shellPaths, deps.acknowledgementScope ?? 'project');
+  if (state.parseError) {
+    return {
+      id: `acknowledge:${operation.target}`,
+      status: 'fail',
+      message: `Onboarding acknowledgement state could not be parsed: ${state.parseError}`,
+      target: operation.target,
+    };
+  }
+
+  const actual = state.payload?.acknowledgements[operation.target] ?? false;
+  const ok = actual === operation.acknowledged;
+
+  return {
+    id: `acknowledge:${operation.target}`,
+    status: ok ? 'pass' : 'fail',
+    message: ok
+      ? `${operation.target} acknowledgement matches the requested onboarding state.`
+      : `${operation.target} acknowledgement does not match the requested onboarding state.`,
+    target: operation.target,
+  };
+}
+
+function verifyCompletionMarkerOperation(
+  deps: OnboardingVerificationDependencies,
+  request: OnboardingApplyRequest,
+  operation: Extract<OnboardingApplyOperation, { kind: 'set-completion-marker' }>,
+): OnboardingVerificationItem {
+  const marker = readOnboardingCompletionMarker(deps.shellPaths, operation.scope);
+  if (marker.parseError) {
+    return {
+      id: `marker:${operation.scope}`,
+      status: 'fail',
+      message: `Onboarding completion marker could not be parsed: ${marker.parseError}`,
+      target: operation.scope,
+    };
+  }
+
+  if (!operation.completed) {
+    return {
+      id: `marker:${operation.scope}`,
+      status: marker.exists ? 'fail' : 'pass',
+      message: marker.exists
+        ? `${operation.scope} onboarding completion marker still exists.`
+        : `${operation.scope} onboarding completion marker is cleared.`,
+      target: operation.scope,
+    };
+  }
+
+  if (!marker.payload) {
+    return {
+      id: `marker:${operation.scope}`,
+      status: 'fail',
+      message: `${operation.scope} onboarding completion marker is missing.`,
+      target: operation.scope,
+    };
+  }
+
+  const expectedSource = operation.payload?.source ?? normalizeCompletionSource(request.source);
+  const expectedMode = operation.payload?.mode ?? request.mode;
+  const expectedWorkspaceRoot = operation.payload?.workspaceRoot ?? deps.shellPaths.workingDirectory;
+  const payloadMatches = marker.payload.source === expectedSource
+    && (expectedMode === undefined || marker.payload.mode === expectedMode)
+    && (expectedWorkspaceRoot === undefined || marker.payload.workspaceRoot === expectedWorkspaceRoot)
+    && (operation.payload?.completedAt === undefined || marker.payload.completedAt === operation.payload.completedAt)
+    && (operation.payload?.updatedAt === undefined || marker.payload.updatedAt === operation.payload.updatedAt);
+
+  return {
+    id: `marker:${operation.scope}`,
+    status: payloadMatches ? 'pass' : 'fail',
+    message: payloadMatches
+      ? `${operation.scope} onboarding completion marker matches the requested state.`
+      : `${operation.scope} onboarding completion marker does not match the requested state.`,
+    target: operation.scope,
+  };
+}
+
+async function verifySecretOperation(
+  deps: OnboardingVerificationDependencies,
+  operation: Extract<OnboardingApplyOperation, { kind: 'set-secret' }>,
+): Promise<OnboardingVerificationItem> {
+  if (!deps.secrets) {
+    return {
+      id: `secret:${operation.key}`,
+      status: 'fail',
+      message: 'Secret manager is unavailable.',
+      target: operation.key,
+    };
+  }
+
+  const actual = await deps.secrets.get(operation.key);
+  const ok = isGoodVibesSecretRefInput(operation.value)
+    ? actual !== null
+    : actual === operation.value;
+  return {
+    id: `secret:${operation.key}`,
+    status: ok ? 'pass' : 'fail',
+    message: ok
+      ? isGoodVibesSecretRefInput(operation.value)
+        ? `${operation.key} resolves through the stored GoodVibes secret reference.`
+        : `${operation.key} was stored through the secret manager.`
+      : `${operation.key} did not match the requested secret value.`,
+    target: operation.key,
+  };
+}
+
+function verifyAuthOperation(
+  deps: OnboardingVerificationDependencies,
+  operation: Extract<OnboardingApplyOperation, { kind: 'ensure-auth-user' }>,
+): OnboardingVerificationItem {
+  if (!deps.auth) {
+    return {
+      id: `auth:${operation.username}`,
+      status: 'fail',
+      message: 'Local auth manager is unavailable.',
+      target: operation.username,
+    };
+  }
+
+  const snapshot = deps.auth.inspect();
+  const username = operation.username.trim();
+  const user = snapshot.users.find((entry) => entry.username === username);
+  const requiredRoles = operation.roles ?? ['admin'];
+  const userExists = Boolean(user) && requiredRoles.every((role) => user!.roles.includes(role));
+  const sessionExists = operation.createSession === false
+    ? true
+    : snapshot.sessions.some((session) => session.username === username);
+  const bootstrapRetired = operation.retireBootstrapCredential
+    ? snapshot.bootstrapCredentialPresent === false
+    : true;
+  const ok = userExists && sessionExists && bootstrapRetired;
+  return {
+    id: `auth:${username}`,
+    status: ok ? 'pass' : 'fail',
+    message: ok
+      ? `${username} local auth user has required role(s) and session state.`
+      : `${username} local auth user/session/role/bootstrap state was not created.`,
+    target: username,
+  };
+}
+
+async function verifyOperation(
+  deps: OnboardingVerificationDependencies,
+  request: OnboardingApplyRequest,
+  operation: OnboardingApplyOperation,
+): Promise<OnboardingVerificationItem> {
+  if (operation.kind === 'set-config') return verifyConfigOperation(deps, operation);
+  if (operation.kind === 'set-secret') return verifySecretOperation(deps, operation);
+  if (operation.kind === 'ensure-auth-user') return verifyAuthOperation(deps, operation);
+  if (operation.kind === 'acknowledge') return verifyAcknowledgementOperation(deps, operation);
+  return verifyCompletionMarkerOperation(deps, request, operation);
+}
+
+export async function verifyOnboardingRequest(
+  deps: OnboardingVerificationDependencies,
+  request: OnboardingApplyRequest,
+): Promise<OnboardingVerificationResult> {
+  const items = await Promise.all(request.operations.map((operation) => verifyOperation(deps, request, operation)));
+
+  return {
+    verifiedAt: getNow(deps),
+    ok: items.every((item) => item.status === 'pass'),
+    items,
+  };
+}

package/src/runtime/ui-services.ts

@@ -48,12 +48,27 @@ export interface UiPlatformServices {
   readonly localUserAuthManager: RuntimeServices['localUserAuthManager'];
   readonly mcpRegistry: RuntimeServices['mcpRegistry'];
   readonly serviceRegistry: RuntimeServices['serviceRegistry'];
+  readonly surfaceRegistry: RuntimeServices['surfaceRegistry'];
   readonly subscriptionManager: RuntimeServices['subscriptionManager'];
   readonly secretsManager: SecretsManager;
   readonly tokenAuditor: RuntimeServices['tokenAuditor'];
   readonly replayEngine: RuntimeServices['replayEngine'];
   readonly webhookNotifier: RuntimeServices['webhookNotifier'];
   readonly policyRuntimeState: RuntimeServices['policyRuntimeState'];
+  readonly externalServices?: {
+    inspect(): {
+      readonly daemonRunning: boolean;
+      readonly daemonPortInUse?: boolean;
+      readonly httpListenerRunning: boolean;
+      readonly httpListenerPortInUse?: boolean;
+    };
+    restart(): Promise<{
+      readonly daemonRunning: boolean;
+      readonly daemonPortInUse?: boolean;
+      readonly httpListenerRunning: boolean;
+      readonly httpListenerPortInUse?: boolean;
+    }>;
+  };
 }
 
 export interface UiPlanningServices {
@@ -138,6 +153,7 @@ export function createUiRuntimeServices(
       localUserAuthManager: runtimeServices.localUserAuthManager,
       mcpRegistry: runtimeServices.mcpRegistry,
       serviceRegistry: runtimeServices.serviceRegistry,
+      surfaceRegistry: runtimeServices.surfaceRegistry,
       subscriptionManager: runtimeServices.subscriptionManager,
       secretsManager: runtimeServices.secretsManager,
       tokenAuditor: runtimeServices.tokenAuditor,

package/src/shell/ui-openers.ts

@@ -126,7 +126,10 @@ export function wireShellUiOpeners(options: WireShellUiOpenersOptions): void {
       input.modalOpened('modelPicker');
       input.modelPicker.openAllModels(models, runtime.model);
       render();
-    })();
+    })().catch((error: unknown) => {
+      commandContext.print?.(`Model picker failed to open: ${error instanceof Error ? error.message : String(error)}`);
+      render();
+    });
   };
 
   commandContext.openProviderPicker = () => {
@@ -139,13 +142,20 @@ export function wireShellUiOpeners(options: WireShellUiOpenersOptions): void {
       input.modalOpened('modelPicker');
       input.modelPicker.openProviders(providers, runtime.provider);
       render();
-    })();
+    })().catch((error: unknown) => {
+      commandContext.print?.(`Provider picker failed to open: ${error instanceof Error ? error.message : String(error)}`);
+      render();
+    });
   };
 
   commandContext.openSelection = (title, items, opts, callback) => {
     input.openSelection(title, items, opts, callback);
   };
 
+  commandContext.openOnboardingWizard = (modeOrOptions) => {
+    input.openOnboardingWizard(modeOrOptions);
+  };
+
   commandContext.openContextInspector = () => {
     input.modalOpened('contextInspector');
     input.contextInspectorModal.open();