@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-harness-setup-plan.ts

@@ -0,0 +1,253 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import type { CliServicePosture } from '../cli/service-posture.ts';
+import type { OnboardingStep1CapabilityItem } from '../runtime/onboarding/index.ts';
+import { previewAgentWorkspaceTuiSettingsImport } from '../input/agent-workspace-settings.ts';
+import { browserControlPosture } from './agent-harness-browser-control.ts';
+import { localModelCookbook } from './agent-harness-model-routing.ts';
+import { sudoExecutionPosture } from './agent-harness-sudo-posture.ts';
+import { agentHarnessVibeHealth } from './agent-harness-vibe-health.ts';
+import { capabilityById, collectSnapshot, setupPlanStatusForCapability, setupProviderSignalIds } from './agent-harness-setup-posture-utils.ts';
+import { browserControlSignals, localModelSetupNextAction, localModelSetupReadiness, localModelSetupSignals, localModelSetupStatus, settingsImportChangeCount, settingsImportSignals } from './agent-harness-setup-model-helpers.ts';
+import { connectedHostAuthNextAction, connectedHostAuthPosture, connectedHostAuthSignals, connectedHostAuthStatus, connectedHostBootstrapPlan, connectedHostRepairCards, connectedHostServiceProbe, hostSetupStatus, serviceProbeSignal, setupServiceLifecycleDecision } from './agent-harness-setup-connected-host.ts';
+import { installSmokePlan, installSmokeSignals, setupCompletionMarkerExists } from './agent-harness-setup-smoke.ts';
+import type { SetupPlanItem } from './agent-harness-setup-posture-types.ts';
+
+export function buildSetupPlan(
+  context: CommandContext,
+  snapshot: Awaited<ReturnType<typeof collectSnapshot>>,
+  capabilities: readonly OnboardingStep1CapabilityItem[],
+  servicePosture: CliServicePosture | null,
+): readonly SetupPlanItem[] {
+  const providerAccess = capabilityById(capabilities, 'provider-access');
+  const agentKnowledge = capabilityById(capabilities, 'agent-knowledge');
+  const localBehavior = capabilityById(capabilities, 'local-behavior');
+  const communicationChannels = capabilityById(capabilities, 'communication-channels');
+  const automationReview = capabilityById(capabilities, 'automation-review');
+  const tuiDelegation = capabilityById(capabilities, 'tui-delegation');
+  const setupMarkerDone = setupCompletionMarkerExists(context);
+  const browserControl = browserControlPosture(context);
+  const settingsImport = previewAgentWorkspaceTuiSettingsImport(context);
+  const settingsImportChanges = settingsImportChangeCount(settingsImport);
+  const localModels = localModelCookbook(context, true);
+  const localModelReadiness = localModelSetupReadiness(localModels);
+  const serviceProbe = connectedHostServiceProbe(servicePosture);
+  const authPosture = connectedHostAuthPosture(context, snapshot);
+  const smokePlan = installSmokePlan(providerAccess, serviceProbe, authPosture);
+  const vibeHealth = agentHarnessVibeHealth(context);
+  const sudoPosture = sudoExecutionPosture(context);
+
+  const plan: SetupPlanItem[] = [
+    {
+      id: 'connected-host-readiness',
+      label: 'Connected host readiness',
+      status: hostSetupStatus(snapshot, serviceProbe),
+      priority: 10,
+      blocksAutonomy: true,
+      reason: 'Daemon-backed automation, Agent Knowledge, channels, and companion routes need a reachable compatible GoodVibes host.',
+      nextAction: 'Run connected-host status, then start, update, or repair the owning GoodVibes host if the live check reports a gap.',
+      userRoute: 'Agent Workspace -> Home -> Host compatibility',
+      modelRoute: 'host action:"status"',
+      relatedSetupItemId: 'operator-terminal',
+      signals: [
+        serviceProbeSignal(serviceProbe),
+        ...serviceProbe.issues.slice(0, 3),
+        ...snapshot.collectionIssues.filter((issue) => issue.area === 'host').map((issue) => issue.message),
+      ],
+      repairCards: connectedHostRepairCards(snapshot, serviceProbe),
+      serviceLifecycleDecision: setupServiceLifecycleDecision(snapshot, serviceProbe),
+      bootstrapPlan: connectedHostBootstrapPlan(snapshot, serviceProbe),
+      serviceProbe,
+    },
+    {
+      id: 'connected-host-auth',
+      label: 'Connected-host auth',
+      status: connectedHostAuthStatus(authPosture),
+      priority: 12,
+      blocksAutonomy: true,
+      reason: 'Protected daemon routes, approvals, schedules, channels, and Agent Knowledge writes need a usable connected-host operator token from the canonical GoodVibes host token store.',
+      nextAction: connectedHostAuthNextAction(authPosture),
+      userRoute: 'Agent Workspace -> Host -> Connected-host auth owner; /auth review',
+      modelRoute: authPosture.operatorToken.usable
+        ? 'host action:"status" includeParameters:true'
+        : authPosture.routes.provisionTokenRoute,
+      relatedSetupItemId: 'operator-terminal',
+      signals: connectedHostAuthSignals(authPosture),
+      authPosture,
+    },
+    {
+      id: 'goodvibes-settings-import',
+      label: 'GoodVibes settings import',
+      status: settingsImport?.summary.parseErrors ? 'check' : settingsImportChanges > 0 ? 'recommended' : 'optional',
+      priority: 15,
+      blocksAutonomy: false,
+      reason: 'Existing shared GoodVibes settings can seed Agent provider, subscription, behavior, permission, UI, TTS, channel, helper, tool, release, and automation state.',
+      nextAction: settingsImportChanges > 0
+        ? 'Preview the import, explain the changed setting and subscription counts, then apply only after the user confirms the import.'
+        : 'Use this when reusing settings from GoodVibes TUI or another published GoodVibes platform store; the preview shows whether anything importable is present.',
+      userRoute: 'Agent Workspace -> Start -> Import GoodVibes settings',
+      modelRoute: 'import_goodvibes_settings action:"preview"',
+      signals: settingsImportSignals(settingsImport),
+    },
+    {
+      id: 'provider-access',
+      label: 'Provider and model access',
+      status: setupPlanStatusForCapability(providerAccess, 'blocked'),
+      priority: 20,
+      blocksAutonomy: true,
+      reason: providerAccess.detail,
+      nextAction: providerAccess.selected ? 'Review the current model route and provider accounts.' : 'Choose a provider/model route or store a provider credential before relying on assistant turns.',
+      userRoute: 'Agent Workspace -> Start -> Choose main model',
+      modelRoute: 'models action:"status|providers"',
+      relatedSetupItemId: providerAccess.id,
+      signals: setupProviderSignalIds(snapshot),
+    },
+    {
+      id: 'install-smoke',
+      label: 'Install smoke',
+      status: smokePlan.status === 'ready-to-run' ? 'recommended' : 'blocked',
+      priority: 22,
+      blocksAutonomy: false,
+      reason: 'A fresh install should be provable from package binary to reachable host, usable auth, selected model route, reviewed setup posture, and one successful assistant turn.',
+      nextAction: smokePlan.status === 'ready-to-run'
+        ? 'Run the confirmed setup smoke route, then complete the user-visible package/status and first-turn checks.'
+        : 'Resolve connected-host, connected-host auth, and provider/model blockers, then rerun the confirmed setup smoke route.',
+      userRoute: 'Agent Workspace -> Start -> Install smoke',
+      modelRoute: 'setup action:"smoke" setupItemId:"install-smoke"',
+      signals: installSmokeSignals(smokePlan),
+      installSmokePlan: smokePlan,
+    },
+    {
+      id: 'local-model-readiness',
+      label: 'Local model readiness',
+      status: localModelSetupStatus(localModels),
+      priority: 25,
+      blocksAutonomy: false,
+      reason: 'A local route gives the assistant a private/offline fallback and can reduce cost, but it should be set up through visible server, refresh, and benchmark steps.',
+      nextAction: localModelSetupNextAction(localModels),
+      userRoute: 'Agent Workspace -> Start -> Local model cookbook',
+      modelRoute: 'models action:"local"',
+      signals: localModelSetupSignals(localModels),
+      localModelReadiness,
+    },
+    {
+      id: 'agent-knowledge',
+      label: 'Agent Knowledge readiness',
+      status: 'recommended',
+      priority: 30,
+      blocksAutonomy: false,
+      reason: agentKnowledge.detail,
+      nextAction: 'Inspect isolated Agent Knowledge status before source-backed memory or research ingest.',
+      userRoute: 'Agent Workspace -> Knowledge',
+      modelRoute: 'host action:"status" or agent_knowledge',
+      relatedSetupItemId: agentKnowledge.id,
+    },
+    {
+      id: 'vibe-personality',
+      label: 'VIBE.md personality',
+      status: vibeHealth.status,
+      priority: 35,
+      blocksAutonomy: false,
+      reason: 'VIBE.md is the user-friendly personality file for how GoodVibes Agent should feel, but blocked or truncated files should be visible before they shape a session.',
+      nextAction: vibeHealth.nextAction,
+      userRoute: vibeHealth.userRoute,
+      modelRoute: vibeHealth.modelRoute,
+      signals: vibeHealth.signals,
+      vibeHealth,
+    },
+    {
+      id: 'local-behavior',
+      label: 'Local memory, skills, and routines',
+      status: setupPlanStatusForCapability(localBehavior, 'recommended'),
+      priority: 40,
+      blocksAutonomy: false,
+      reason: localBehavior.detail,
+      nextAction: localBehavior.selected ? 'Review imported or customized local behavior.' : 'Import discovered behavior files or create the first persona, skill, or routine.',
+      userRoute: 'Agent Workspace -> Local Context',
+      modelRoute: 'memory action:"curator" or agent_harness mode:"workspace_actions" categoryId:"onboarding-context"',
+      relatedSetupItemId: localBehavior.id,
+    },
+    {
+      id: 'communication-channels',
+      label: 'Communication channels',
+      status: setupPlanStatusForCapability(communicationChannels, 'optional'),
+      priority: 50,
+      blocksAutonomy: false,
+      reason: communicationChannels.detail,
+      nextAction: communicationChannels.selected ? 'Review channel readiness and delivery safety.' : 'Enable only the channels where the assistant should be reachable.',
+      userRoute: 'Agent Workspace -> Channels',
+      modelRoute: 'channels action:"status"',
+      relatedSetupItemId: communicationChannels.id,
+      signals: snapshot.surfaces.configuredEnabledKinds,
+    },
+    {
+      id: 'automation-review',
+      label: 'Automation review',
+      status: setupPlanStatusForCapability(automationReview, 'recommended'),
+      priority: 60,
+      blocksAutonomy: false,
+      reason: automationReview.detail,
+      nextAction: 'Review schedules, approvals, routine promotion, and visible autonomy queue controls before ongoing background work.',
+      userRoute: 'Agent Workspace -> Personal Ops -> Autonomy queue',
+      modelRoute: 'autonomy action:"queue"',
+      relatedSetupItemId: automationReview.id,
+    },
+    {
+      id: 'browser-desktop-control',
+      label: 'Browser and desktop control',
+      status: browserControl.status === 'ready' ? 'ready' : browserControl.status === 'attention' ? 'check' : 'recommended',
+      priority: 65,
+      blocksAutonomy: false,
+      reason: browserControl.configured
+        ? 'A trusted browser, desktop, computer-use, screenshot, or screen-recording route is configured.'
+        : browserControl.status === 'attention'
+          ? 'A browser or desktop connector is present but needs trust, connection, or schema review before use.'
+        : 'Live browser navigation, UI testing, screenshots, screen recording, and desktop or device actions need a trusted MCP server or first-class tool before the Agent can perform them.',
+      nextAction: browserControl.configured
+        ? 'Inspect the browser/desktop execution route before using live UI automation.'
+        : browserControl.status === 'attention'
+          ? 'Review the matching MCP server trust, connection, and schema freshness before using live UI automation.'
+        : 'Configure and review a trusted browser or desktop MCP server, then inspect the execution route before offering live UI automation.',
+      userRoute: 'Agent Workspace -> Tools & MCP',
+      modelRoute: browserControl.recommendedRoute,
+      signals: browserControlSignals(browserControl),
+    },
+    {
+      id: 'sudo-execution-posture',
+      label: 'Sudo execution posture',
+      status: sudoPosture.setupStatus,
+      priority: 66,
+      blocksAutonomy: false,
+      reason: 'Privilege escalation must stay explicit, visible, and user-supervised; background sudo prompts, stdin password writes, and raw password display are blocked until the SDK/daemon publishes safe mediation.',
+      nextAction: sudoPosture.nextAction,
+      userRoute: 'Agent Workspace -> Computer Use -> Sudo posture',
+      modelRoute: sudoPosture.setupRoute,
+      signals: sudoPosture.signals,
+      sudoPosture,
+    },
+    {
+      id: 'build-delegation',
+      label: 'Build delegation boundary',
+      status: setupPlanStatusForCapability(tuiDelegation, 'optional'),
+      priority: 70,
+      blocksAutonomy: false,
+      reason: tuiDelegation.detail,
+      nextAction: 'Use delegation for explicit build, fix, review, isolation, or parallelism work rather than as a setup prerequisite.',
+      userRoute: 'Agent Workspace -> Home -> Connected host',
+      modelRoute: 'delegation action:"status"',
+      relatedSetupItemId: tuiDelegation.id,
+    },
+    {
+      id: 'finish-onboarding',
+      label: 'Finish onboarding state',
+      status: setupMarkerDone ? 'ready' : 'recommended',
+      priority: 80,
+      blocksAutonomy: false,
+      reason: setupMarkerDone ? 'A setup marker already exists for this Agent scope.' : 'No setup marker exists yet, so the user may see first-run guidance again.',
+      nextAction: setupMarkerDone ? 'Reopen setup only when changing provider, channel, automation, or local behavior decisions.' : 'Open onboarding, review the selected choices, then apply and close when the assistant is usable.',
+      userRoute: 'Agent Workspace -> Start -> Onboarding',
+      modelRoute: 'agent_harness mode:"open_ui_surface" surfaceId:"onboarding"',
+    },
+  ];
+
+  return plan.sort((left, right) => left.priority - right.priority);
+}

package/src/tools/agent-harness-setup-posture-types.ts

@@ -0,0 +1,218 @@
+import type { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { OnboardingStep1CapabilityItem, OnboardingSurfaceRecord } from '../runtime/onboarding/index.ts';
+import type { AgentHarnessVibeHealth } from './agent-harness-vibe-health.ts';
+import type { AgentHarnessSudoPosture } from './agent-harness-sudo-posture.ts';
+
+export interface AgentHarnessSetupArgs {
+  readonly setupItemId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+  readonly fields?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+export type SetupResolution =
+  | { readonly status: 'found'; readonly item: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+export type SetupLookupSource = 'setupItemId' | 'target' | 'query';
+
+export interface SurfaceRegistryLike {
+  syncConfiguredSurfaces(): readonly OnboardingSurfaceRecord[];
+}
+
+export type SetupPlanStatus = 'ready' | 'blocked' | 'recommended' | 'optional' | 'check';
+export type SetupRepairCardState = 'available' | 'requires-live-host' | 'missing';
+export type SetupRepairCardEffect = 'read-only' | 'confirmed-effect';
+export type SetupRepairRecommendation = 'recommended' | 'inspect-first' | 'not-needed' | 'unavailable';
+export type SetupServiceProbeStatus = 'reachable' | 'unreachable' | 'not-enabled' | 'not-probed';
+export type SetupSmokeArtifactStore = Partial<Pick<ArtifactStore, 'create' | 'list'>>;
+export type SetupHandoffKind = 'diagnostic' | 'workspace-action' | 'ui-surface' | 'confirmed-route' | 'operator-method' | 'conversation' | 'user-command' | 'tool-discovery';
+export type SetupHandoffEffect = 'read-only' | 'visible-navigation' | 'confirmed-effect' | 'user-run';
+
+export interface OperatorContractMethod {
+  readonly id: string;
+}
+
+export interface SetupPlanItem {
+  readonly id: string;
+  readonly label: string;
+  readonly status: SetupPlanStatus;
+  readonly priority: number;
+  readonly blocksAutonomy: boolean;
+  readonly reason: string;
+  readonly nextAction: string;
+  readonly userRoute: string;
+  readonly modelRoute: string;
+  readonly relatedSetupItemId?: string;
+  readonly signals?: readonly string[];
+  readonly repairCards?: readonly SetupRepairCard[];
+  readonly serviceLifecycleDecision?: SetupServiceLifecycleDecision;
+  readonly bootstrapPlan?: SetupBootstrapPlan;
+  readonly serviceProbe?: SetupServiceProbe;
+  readonly authPosture?: SetupConnectedHostAuthPosture;
+  readonly installSmokePlan?: SetupInstallSmokePlan;
+  readonly localModelReadiness?: Record<string, unknown>;
+  readonly vibeHealth?: AgentHarnessVibeHealth;
+  readonly sudoPosture?: AgentHarnessSudoPosture;
+}
+
+export interface SetupRepairCard {
+  readonly id: string;
+  readonly label: string;
+  readonly state: SetupRepairCardState;
+  readonly effect: SetupRepairCardEffect;
+  readonly methodId?: string;
+  readonly modelRoute?: string;
+  readonly userRoute: string;
+  readonly prerequisite?: string;
+  readonly recommendation: SetupRepairRecommendation;
+  readonly liveEvidence?: SetupRepairLiveEvidence;
+  readonly outcome?: SetupRepairOutcome;
+  readonly recommendedWhen: string;
+  readonly safety: string;
+}
+
+export interface SetupRepairLiveEvidence {
+  readonly probeStatus: SetupServiceProbeStatus;
+  readonly summary: string;
+}
+
+export interface SetupRepairOutcome {
+  readonly target: string;
+  readonly successCriteria: readonly string[];
+  readonly evidenceFields: readonly string[];
+  readonly verificationRoute: string;
+  readonly recoveryRoute: string;
+}
+
+export interface SetupServiceLifecycleDecision {
+  readonly status: 'needs-status-receipt' | 'no-lifecycle-action' | 'bootstrap-first' | 'status-route-unavailable';
+  readonly recommendedAction: 'read-services-status' | 'inspect-service-posture' | 'none';
+  readonly modelRoute: string;
+  readonly reason: string;
+  readonly evidence: {
+    readonly probeStatus: SetupServiceProbeStatus;
+    readonly binding: string;
+    readonly hostIssue: boolean;
+    readonly serviceStatusMethodPublished: boolean;
+  };
+  readonly receiptRules: readonly string[];
+  readonly blockedMutations: readonly string[];
+}
+
+export interface SetupServiceProbe {
+  readonly status: SetupServiceProbeStatus;
+  readonly endpointId: string;
+  readonly label: string;
+  readonly enabled: boolean;
+  readonly binding: string;
+  readonly diagnosticRoute: string;
+  readonly issues: readonly string[];
+}
+
+export interface SetupConnectedHostAuthPosture {
+  readonly owner: 'connected-host';
+  readonly operatorToken: {
+    readonly present: boolean;
+    readonly usable: boolean;
+    readonly path: string;
+    readonly fingerprint?: string;
+    readonly error?: string;
+  };
+  readonly compatibilityAuth: {
+    readonly userStorePath: string;
+    readonly userStorePresent: boolean;
+    readonly bootstrapCredentialPath: string;
+    readonly bootstrapCredentialPresent: boolean;
+    readonly users: number;
+    readonly sessions: number;
+  };
+  readonly routes: {
+    readonly reviewCommand: string;
+    readonly connectedHostStatus: string;
+    readonly pairingPosture: string;
+    readonly qrPairingRoute: string;
+    readonly manualTokenRoute: string;
+    readonly provisionTokenRoute: string;
+    readonly tokenProvisioningOwner: string;
+    readonly tokenProvisioningSource: string;
+  };
+}
+
+export interface SetupInstallSmokeCheck {
+  readonly id: string;
+  readonly label: string;
+  readonly status: 'ready' | 'blocked' | 'user-run';
+  readonly evidence: string;
+  readonly route: string;
+}
+
+export interface SetupInstallSmokePlan {
+  readonly status: 'ready-to-run' | 'blocked';
+  readonly source: string;
+  readonly checks: readonly SetupInstallSmokeCheck[];
+  readonly successCriteria: readonly string[];
+  readonly policy: string;
+}
+
+export interface SetupInstallSmokeRunSummary {
+  readonly ready: number;
+  readonly blocked: number;
+  readonly userRun: number;
+  readonly total: number;
+}
+
+export interface SetupSmokeEvidenceField {
+  readonly id: string;
+  readonly label: string;
+  readonly value: string;
+}
+
+export interface SetupBootstrapStep {
+  readonly id: string;
+  readonly label: string;
+  readonly purpose: string;
+  readonly commands: readonly string[];
+  readonly expected: string;
+  readonly fallback?: string;
+}
+
+export interface SetupBootstrapPlan {
+  readonly status: 'recommended' | 'optional';
+  readonly source: string;
+  readonly recommendedWhen: string;
+  readonly steps: readonly SetupBootstrapStep[];
+  readonly reconnectRoutes: Record<string, string>;
+  readonly policy: string;
+}
+
+export interface SetupHandoffCard {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: SetupHandoffKind;
+  readonly effect: SetupHandoffEffect;
+  readonly userRoute: string;
+  readonly modelRoute: string;
+  readonly nextStep: string;
+  readonly safety: string;
+  readonly requiresConfirmation?: boolean;
+  readonly prerequisite?: string;
+}
+
+export interface SetupRepairDecision {
+  readonly id: string;
+  readonly label: string;
+  readonly status: 'inspect-first' | 'ready' | 'confirmed-repair-available' | 'user-run-bootstrap';
+  readonly effect: SetupHandoffEffect;
+  readonly modelRoute: string;
+  readonly userRoute: string;
+  readonly nextStep: string;
+  readonly reason: string;
+  readonly safety: string;
+  readonly requiresConfirmation?: boolean;
+  readonly prerequisite?: string;
+}

package/src/tools/agent-harness-setup-posture-utils.ts

@@ -0,0 +1,173 @@
+import { statSync } from 'node:fs';
+import { buildProviderAccountSnapshot } from '../panels/provider-account-snapshot.ts';
+import { requireLocalUserAuthManager, requirePlatform, requireProvider, requireSecretsManager, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from '../input/commands/runtime-services.ts';
+import { collectOnboardingSnapshot } from '../runtime/onboarding/index.ts';
+import type { CommandContext } from '../input/command-registry.ts';
+import { buildCliServicePosture, type CliServicePosture } from '../cli/service-posture.ts';
+import type { AgentHarnessSetupArgs, SetupLookupSource, SetupPlanStatus, SurfaceRegistryLike, SetupSmokeArtifactStore } from './agent-harness-setup-posture-types.ts';
+import type { OnboardingStep1CapabilityItem } from '../runtime/onboarding/index.ts';
+
+export function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function readRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : {};
+}
+
+export function readStringArray(value: unknown): readonly string[] {
+  return Array.isArray(value) ? value.map((entry) => readString(entry)).filter(Boolean) : [];
+}
+
+export function readFieldMap(value: unknown): Readonly<Record<string, string>> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, typeof entry === 'string' ? entry : String(entry)]));
+}
+
+export function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+export function quoteRouteValue(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export function operatorMethodRoute(methodId: string, confirmed: boolean): string {
+  return `agent_operator_method methodId:"${quoteRouteValue(methodId)}" input:{}${confirmed ? ' confirm:true explicitUserRequest:"..."' : ''}`;
+}
+
+export function safeIso(value: number | null | undefined): string | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  return new Date(value).toISOString();
+}
+
+export function provisionConnectedHostTokenRoute(): string {
+  return 'setup action:"token" setupItemId:"connected-host-auth" confirm:true explicitUserRequest:"..."';
+}
+
+export function safeFileMode(path: string): string | null {
+  try {
+    return `0${(statSync(path).mode & 0o777).toString(8)}`;
+  } catch {
+    return null;
+  }
+}
+
+export function setupSmokeArtifactStore(context: CommandContext): SetupSmokeArtifactStore | null {
+  const candidate = (context.platform as { readonly artifactStore?: unknown }).artifactStore;
+  if (candidate && typeof candidate === 'object') {
+    return candidate as SetupSmokeArtifactStore;
+  }
+  return null;
+}
+
+export function surfaceRegistry(context: CommandContext): SurfaceRegistryLike | undefined {
+  const candidate = (context.platform as { readonly surfaceRegistry?: unknown }).surfaceRegistry;
+  if (candidate && typeof candidate === 'object' && 'syncConfiguredSurfaces' in candidate) {
+    return candidate as SurfaceRegistryLike;
+  }
+  return undefined;
+}
+
+export function setupServiceRuntime(context: CommandContext) {
+  const shellPaths = requireShellPaths(context);
+  return {
+    configManager: requirePlatform(context).configManager,
+    workingDirectory: shellPaths.workingDirectory,
+    homeDirectory: shellPaths.homeDirectory,
+  };
+}
+
+export async function collectServicePosture(context: CommandContext): Promise<CliServicePosture | null> {
+  try {
+    return await buildCliServicePosture(setupServiceRuntime(context), {
+      probe: true,
+      logTailBytes: 0,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export async function collectSnapshot(context: CommandContext) {
+  const registry = surfaceRegistry(context);
+  return await collectOnboardingSnapshot({
+    config: requirePlatform(context).configManager,
+    shellPaths: requireShellPaths(context),
+    acknowledgementScope: 'project',
+    subscriptions: requireSubscriptionManager(context),
+    secrets: requireSecretsManager(context),
+    auth: requireLocalUserAuthManager(context),
+    services: requireServiceRegistry(context),
+    ...(registry ? {
+      surfaces: {
+        list: () => registry.syncConfiguredSurfaces(),
+      },
+    } : {}),
+    providerAccounts: {
+      loadSnapshot: () => buildProviderAccountSnapshot({
+        providerModels: requireProvider(context).providerRegistry,
+        services: requireServiceRegistry(context),
+        subscriptions: requireSubscriptionManager(context),
+        environment: {
+          hasEnvironmentVariable: (name: string) => Boolean(process.env[name]),
+        },
+      }),
+    },
+  });
+}
+
+export function lookupFromArgs(args: AgentHarnessSetupArgs): { readonly source: SetupLookupSource; readonly input: string } | null {
+  const setupItemId = readString(args.setupItemId);
+  if (setupItemId) return { source: 'setupItemId', input: setupItemId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+export function itemSearchText(item: OnboardingStep1CapabilityItem): string {
+  return [
+    item.id,
+    item.label,
+    item.detail,
+    item.selected ? 'selected ready configured enabled' : 'optional attention unselected',
+  ].join('\n').toLowerCase();
+}
+export function summarizeLocalBehavior(snapshot: Awaited<ReturnType<typeof collectSnapshot>>): Record<string, unknown> {
+  const discovery = snapshot.localBehaviorDiscovery;
+  return {
+    personas: discovery.personas,
+    skills: discovery.skills,
+    routines: discovery.routines,
+  };
+}
+
+export function setupProviderSignalIds(snapshot: Awaited<ReturnType<typeof collectSnapshot>>): readonly string[] {
+  return [...new Set<string>([
+    ...(snapshot.providerAccounts?.providers ?? [])
+      .filter((provider) => provider.activeRoute !== 'unconfigured' || provider.oauthReady || provider.pendingLogin)
+      .map((provider) => provider.providerId),
+    ...snapshot.services.oauthProviderIds,
+    ...snapshot.services.services
+      .filter((service) => service.hasPrimaryCredential || service.hasPasswordCredential)
+      .map((service) => service.providerId),
+    ...snapshot.subscriptions.activeProviderIds,
+    ...snapshot.subscriptions.pendingProviderIds,
+  ])].sort((left, right) => left.localeCompare(right));
+}
+
+export function capabilityById(items: readonly OnboardingStep1CapabilityItem[], id: OnboardingStep1CapabilityItem['id']): OnboardingStep1CapabilityItem {
+  const item = items.find((candidate) => candidate.id === id);
+  if (!item) throw new Error(`Missing onboarding capability ${id}`);
+  return item;
+}
+
+export function setupPlanStatusForCapability(
+  item: OnboardingStep1CapabilityItem,
+  fallback: Exclude<SetupPlanStatus, 'check' | 'ready'>,
+): SetupPlanStatus {
+  return item.selected ? 'ready' : fallback;
+}