@pellux/goodvibes-agent 1.4.3 → 1.5.0

package/src/input/agent-workspace-onboarding-actions.ts

@@ -0,0 +1,132 @@
+import type { AgentWorkspaceActionResult } from './agent-workspace-types.ts';
+import type { OnboardingShellPaths } from '../runtime/onboarding/types.ts';
+import type { AgentWorkspaceRuntimeSnapshot } from './agent-workspace-types.ts';
+import { writeOnboardingCheckMarker, writeOnboardingCompletionMarker } from '../runtime/onboarding/index.ts';
+import { computeOnboardingStateFromSnapshot, deriveOnboardingEntry } from './agent-workspace-onboarding-state.ts';
+import type { OnboardingState } from '../runtime/onboarding/onboarding-state.ts';
+
+export interface CompleteOnboardingParams {
+  readonly awaitingRecapDismiss: boolean;
+  readonly runtimeSnapshot: AgentWorkspaceRuntimeSnapshot | null;
+  readonly shellPaths: OnboardingShellPaths | undefined;
+  readonly dismissAgentWorkspace: (() => boolean) | undefined;
+  readonly close: () => void;
+}
+
+export interface CompleteOnboardingResult {
+  /** True when the dismiss path was taken — caller should close immediately. */
+  readonly dismissed: boolean;
+  /** New value for _awaitingRecapDismiss (only meaningful when dismissed=false). */
+  readonly awaitingRecapDismiss: boolean;
+  readonly status: string;
+  readonly lastActionResult: AgentWorkspaceActionResult;
+}
+
+/**
+ * Pure logic for the completeOnboarding() class method.
+ * Handles both the initial "write markers + show recap" path and the
+ * deferred "dismiss recap" path.
+ */
+export function completeOnboardingAction(params: CompleteOnboardingParams): CompleteOnboardingResult {
+  const { awaitingRecapDismiss, runtimeSnapshot, shellPaths, dismissAgentWorkspace, close } = params;
+
+  // Second activation: dismiss the recap and close the workspace.
+  if (awaitingRecapDismiss) {
+    if (!dismissAgentWorkspace?.()) close();
+    return {
+      dismissed: true,
+      awaitingRecapDismiss: false,
+      status: '',
+      lastActionResult: { kind: 'guidance', title: '', detail: '', safety: 'safe' },
+    };
+  }
+
+  // Shell paths are required to write the completion markers.
+  if (!shellPaths) {
+    return {
+      dismissed: false,
+      awaitingRecapDismiss: false,
+      status: 'Cannot complete onboarding without Agent shell paths.',
+      lastActionResult: {
+        kind: 'error',
+        title: 'Onboarding completion unavailable',
+        detail: 'The Agent workspace cannot locate the user onboarding completion marker path for this runtime.',
+        safety: 'safe',
+      },
+    };
+  }
+
+  try {
+    const marker = { scope: 'user', source: 'wizard', mode: 'new', workspaceRoot: shellPaths.workingDirectory } as const;
+    writeOnboardingCheckMarker(shellPaths, marker);
+    writeOnboardingCompletionMarker(shellPaths, marker);
+    const obs = computeOnboardingStateFromSnapshot(runtimeSnapshot, shellPaths);
+    const headline = obs?.recap.headline ?? 'Onboarding complete';
+    const lines: readonly string[] = obs?.recap.lines ?? [];
+    return {
+      dismissed: false,
+      awaitingRecapDismiss: true,
+      status: headline,
+      lastActionResult: {
+        kind: 'recap',
+        title: headline,
+        detail: lines.join('\n') || 'Saved the user onboarding completion marker.',
+        lines,
+        safety: 'safe',
+      },
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      dismissed: false,
+      awaitingRecapDismiss: false,
+      status: 'Onboarding completion failed.',
+      lastActionResult: { kind: 'error', title: 'Onboarding completion failed', detail, safety: 'safe' },
+    };
+  }
+}
+
+export interface OnSubscriptionLoginSuccessParams {
+  readonly onlyGroup: string | null;
+  readonly runtimeSnapshot: AgentWorkspaceRuntimeSnapshot | null;
+  readonly shellPaths: OnboardingShellPaths | undefined;
+}
+
+export interface OnSubscriptionLoginSuccessResult {
+  /** Updated onboarding state, or null when not in ONBOARDING mode. */
+  readonly onboardingState: OnboardingState | null;
+  /**
+   * Category ID to navigate to (undefined = no change).
+   * The caller must resolve this against its own this.categories AFTER
+   * updating _onboardingState and the reveal set, so the index is never stale.
+   */
+  readonly targetCategoryId: string | undefined;
+  readonly status: string;
+}
+
+/**
+ * Pure logic for the onSubscriptionLoginSuccess() class method.
+ * Re-derives onboarding state and returns the target category ID.
+ * The caller is responsible for resolving the ID to an index against
+ * its FRESHLY-UPDATED categories list (after assigning _onboardingState
+ * and updating the reveal set) to avoid a stale-index window.
+ */
+export function onSubscriptionLoginSuccessAction(params: OnSubscriptionLoginSuccessParams): OnSubscriptionLoginSuccessResult {
+  const { onlyGroup, runtimeSnapshot, shellPaths } = params;
+
+  if (onlyGroup !== 'ONBOARDING') {
+    return { onboardingState: null, targetCategoryId: undefined, status: '' };
+  }
+
+  const obs = computeOnboardingStateFromSnapshot(runtimeSnapshot, shellPaths);
+  if (!obs) {
+    return { onboardingState: null, targetCategoryId: undefined, status: '' };
+  }
+
+  const entry = deriveOnboardingEntry(obs);
+  const status = obs.readyToChat
+    ? 'Signed in. You are ready to chat — Apply & close when ready.'
+    : `Signed in. ${entry.status}`;
+
+  return { onboardingState: obs, targetCategoryId: entry.categoryId, status };
+}

package/src/input/agent-workspace-onboarding-categories.ts

@@ -6,15 +6,15 @@ export const AGENT_WORKSPACE_ONBOARDING_DETAIL_CATEGORIES: readonly AgentWorkspa
     id: 'onboarding-channels',
     group: 'ONBOARDING',
     label: 'Messaging',
-    summary: 'Choose remote channels, then fill only the fields for enabled channels.',
-    detail: 'Enable the channels you actually want. Channel credentials and default targets are saved as Agent settings or secret refs.',
+    summary: 'Connect messaging channels, then check, test, and send from one page.',
+    detail: 'Connect a chat app so the assistant can message you and you can reply from your phone. Enable the channels you want, then fill in the credentials for each one.',
     actions: [
-      settingAction({ id: 'channel-ntfy-enabled', label: 'Use ntfy', detail: 'Toggle ntfy notifications and chat routing.', key: 'surfaces.ntfy.enabled' }),
+      settingAction({ id: 'channel-ntfy-enabled', label: 'Use ntfy', detail: 'Turn on ntfy to get push notifications and send replies from your phone or browser. Fill in the server URL and topics below once enabled.', key: 'surfaces.ntfy.enabled' }),
       settingAction({ id: 'channel-ntfy-base-url', label: 'ntfy base URL', detail: 'Set the ntfy server URL.', key: 'surfaces.ntfy.baseUrl', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-ntfy-chat-topic', label: 'ntfy chat topic', detail: 'Set the topic routed into active terminal chat.', key: 'surfaces.ntfy.chatTopic', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-ntfy-agent-topic', label: 'ntfy agent topic', detail: 'Set the topic routed to Agent work.', key: 'surfaces.ntfy.agentTopic', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-ntfy-default-topic', label: 'ntfy default topic', detail: 'Set the default outbound notification topic.', key: 'surfaces.ntfy.topic', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'channel-ntfy-remote-topic', label: 'ntfy remote topic', detail: 'Set the daemon-owned remote chat topic.', key: 'surfaces.ntfy.remoteTopic', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
+      settingAction({ id: 'channel-ntfy-remote-topic', label: 'ntfy remote topic', detail: 'Set the assistant service remote chat topic.', key: 'surfaces.ntfy.remoteTopic', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-ntfy-token', label: 'ntfy token', detail: 'Store the ntfy access token or secret reference.', key: 'surfaces.ntfy.token', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-ntfy-priority', label: 'ntfy priority', detail: 'Set default ntfy priority from 1 to 5.', key: 'surfaces.ntfy.defaultPriority', visibleWhenKey: 'surfaces.ntfy.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-slack-enabled', label: 'Use Slack', detail: 'Toggle Slack adapter configuration.', key: 'surfaces.slack.enabled' }),
@@ -51,7 +51,7 @@ export const AGENT_WORKSPACE_ONBOARDING_DETAIL_CATEGORIES: readonly AgentWorkspa
       settingAction({ id: 'channel-homeassistant-conversation', label: 'Home automation conversation', detail: 'Set the default conversation id.', key: 'surfaces.homeassistant.defaultConversationId', visibleWhenKey: 'surfaces.homeassistant.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-homeassistant-device-id', label: 'Home automation device ID', detail: 'Set the stable device id exposed to the home automation surface.', key: 'surfaces.homeassistant.deviceId', visibleWhenKey: 'surfaces.homeassistant.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-homeassistant-device-name', label: 'Home automation device name', detail: 'Set the device display name exposed to the home automation surface.', key: 'surfaces.homeassistant.deviceName', visibleWhenKey: 'surfaces.homeassistant.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'channel-homeassistant-event-type', label: 'Home automation event type', detail: 'Set the event type used for daemon-to-home automation delivery.', key: 'surfaces.homeassistant.eventType', visibleWhenKey: 'surfaces.homeassistant.enabled', visibleWhenValue: true }),
+      settingAction({ id: 'channel-homeassistant-event-type', label: 'Home automation event type', detail: 'Set the event type used for home automation delivery.', key: 'surfaces.homeassistant.eventType', visibleWhenKey: 'surfaces.homeassistant.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-homeassistant-session-ttl', label: 'Home automation session TTL', detail: 'Set the idle TTL for remote home automation conversation sessions.', key: 'surfaces.homeassistant.remoteSessionTtlMs', visibleWhenKey: 'surfaces.homeassistant.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-signal-enabled', label: 'Use Signal', detail: 'Toggle Signal bridge delivery.', key: 'surfaces.signal.enabled' }),
       settingAction({ id: 'channel-signal-bridge', label: 'Signal bridge URL', detail: 'Set the Signal bridge base URL.', key: 'surfaces.signal.bridgeUrl', visibleWhenKey: 'surfaces.signal.enabled', visibleWhenValue: true }),
@@ -71,16 +71,26 @@ export const AGENT_WORKSPACE_ONBOARDING_DETAIL_CATEGORIES: readonly AgentWorkspa
       settingAction({ id: 'channel-imessage-account', label: 'iMessage account', detail: 'Set the iMessage account id.', key: 'surfaces.imessage.account', visibleWhenKey: 'surfaces.imessage.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-imessage-token', label: 'iMessage token', detail: 'Store the iMessage bridge token or secret reference.', key: 'surfaces.imessage.token', visibleWhenKey: 'surfaces.imessage.enabled', visibleWhenValue: true }),
       settingAction({ id: 'channel-imessage-chat', label: 'iMessage chat ID', detail: 'Set the default iMessage chat id.', key: 'surfaces.imessage.defaultChatId', visibleWhenKey: 'surfaces.imessage.enabled', visibleWhenValue: true }),
+      { id: 'channel-show', label: 'Check a channel', detail: 'Open a read-only readiness check for one channel.', editorKind: 'channel-show', kind: 'editor', safety: 'read-only' },
+      { id: 'channel-doctor', label: 'Diagnose a channel', detail: 'Run read-only delivery diagnostics for one channel.', editorKind: 'channel-doctor', kind: 'editor', safety: 'read-only' },
+      { id: 'channel-setup', label: 'Channel setup guide', detail: 'Open step-by-step setup guidance for one channel.', editorKind: 'channel-setup', kind: 'editor', safety: 'read-only' },
+      { id: 'channel-send', label: 'Send a message', detail: 'Send one message through a configured channel after confirmation.', editorKind: 'channel-send', kind: 'editor', safety: 'safe' },
+      { id: 'notification-send', label: 'Send a notification', detail: 'Send one plain-text notification to your configured targets after confirmation.', editorKind: 'notify-send', kind: 'editor', safety: 'safe' },
+      { id: 'notification-add-webhook', label: 'Add notification target', detail: 'Add one webhook target for reminder and routine delivery.', editorKind: 'notify-webhook', kind: 'editor', safety: 'safe' },
+      { id: 'notification-remove-webhook', label: 'Remove notification target', detail: 'Remove one webhook notification target after confirmation.', editorKind: 'notify-webhook-remove', kind: 'editor', safety: 'safe' },
+      { id: 'notification-clear-webhooks', label: 'Clear notification targets', detail: 'Remove every configured webhook notification target after confirmation.', editorKind: 'notify-webhook-clear', kind: 'editor', safety: 'safe' },
+      { id: 'notification-test-webhooks', label: 'Test notification targets', detail: 'Send one test notification to configured targets after typed confirmation.', editorKind: 'notify-webhook-test', kind: 'editor', safety: 'safe' },
+      { id: 'channel-safety', label: 'Delivery safety', detail: 'Messages only go out when you explicitly send them. Nothing is delivered silently from this page.', kind: 'guidance', safety: 'blocked' },
     ],
   },
   {
     id: 'onboarding-voice-media',
     group: 'ONBOARDING',
-    label: 'Voice & Phone',
-    summary: 'Configure voice controls, spoken output, and SMS or phone-call delivery.',
-    detail: 'Use this page for saved voice/TTS settings and telephony credentials. Generating media is available later from Voice & Media.',
+    label: 'Voice & Media',
+    summary: 'Voice controls, spoken output, media generation, and phone delivery.',
+    detail: 'Let the assistant speak to you, listen for your voice, describe images, or send SMS. Voice, TTS, image input, media generation, and telephony live on this one page. Side effects stay explicit.',
     actions: [
-      settingAction({ id: 'voice-enabled', label: 'Use voice controls', detail: 'Toggle the optional local voice control surface.', key: 'ui.voiceEnabled' }),
+      settingAction({ id: 'voice-enabled', label: 'Use voice controls', detail: 'Turn on the local voice control surface so the assistant can listen and respond out loud. Requires a microphone and configured TTS provider.', key: 'ui.voiceEnabled' }),
       settingAction({ id: 'voice-tts-provider', label: 'TTS provider', detail: 'Set the default text-to-speech provider id.', key: 'tts.provider' }),
       settingAction({ id: 'voice-tts-voice', label: 'TTS voice', detail: 'Set the default text-to-speech voice id.', key: 'tts.voice' }),
       settingAction({ id: 'telephony-enabled', label: 'Use telephony', detail: 'Toggle SMS, voice call, or telephony bridge delivery.', key: 'surfaces.telephony.enabled' }),
@@ -94,6 +104,15 @@ export const AGENT_WORKSPACE_ONBOARDING_DETAIL_CATEGORIES: readonly AgentWorkspa
       settingAction({ id: 'telephony-recipient', label: 'Recipient phone number', detail: 'Set the default telephony recipient number.', key: 'surfaces.telephony.defaultRecipient', visibleWhenKey: 'surfaces.telephony.enabled', visibleWhenValue: true }),
       settingAction({ id: 'telephony-webhook-secret', label: 'Telephony webhook secret', detail: 'Store the shared telephony webhook secret or secret reference.', key: 'surfaces.telephony.webhookSecret', visibleWhenKey: 'surfaces.telephony.enabled', visibleWhenValue: true }),
       settingAction({ id: 'telephony-voice-language', label: 'Voice language', detail: 'Set the BCP-47 language code for voice-call text-to-speech.', key: 'surfaces.telephony.voiceLanguage', visibleWhenKey: 'surfaces.telephony.enabled', visibleWhenValue: true }),
+      { id: 'voice-enable', label: 'Enable voice', detail: 'Open a confirmed form that enables local voice interaction.', editorKind: 'voice-enable', kind: 'editor', safety: 'safe' },
+      { id: 'voice-disable', label: 'Disable voice', detail: 'Open a confirmed form that disables local voice interaction.', editorKind: 'voice-disable', kind: 'editor', safety: 'safe' },
+      { id: 'tts-speak', label: 'Speak a prompt', detail: 'Open a prompt form for spoken assistant replies through configured live TTS.', editorKind: 'tts-prompt', kind: 'editor', safety: 'safe' },
+      { id: 'image-attach', label: 'Attach image input', detail: 'Open an image form for attaching a real image path and optional prompt.', editorKind: 'image-input', kind: 'editor', safety: 'safe' },
+      { id: 'media-generate', label: 'Generate media', detail: 'Open a confirmed prompt form that generates image or video artifacts through configured media providers.', editorKind: 'media-generate', kind: 'editor', safety: 'safe' },
+      { id: 'voice-workflow-posture', label: 'Voice readiness', detail: 'Check push-to-talk, voice memo transcription, spoken responses, and wake-word readiness.', kind: 'guidance', safety: 'read-only' },
+      { id: 'device-capability-map', label: 'Device capability map', detail: 'Check pairing, mobile command routing, browser, notification, and camera/location readiness for this device.', kind: 'guidance', safety: 'read-only' },
+      { id: 'voice-bundle-export', label: 'Export voice bundle', detail: 'Open a confirmed form that exports voice setup state for review.', editorKind: 'voice-bundle-export', kind: 'editor', safety: 'safe' },
+      { id: 'voice-bundle-inspect', label: 'Inspect voice bundle', detail: 'Open a form that inspects voice setup state before review.', editorKind: 'voice-bundle-inspect', kind: 'editor', safety: 'read-only' },
     ],
   },
   {
@@ -101,7 +120,7 @@ export const AGENT_WORKSPACE_ONBOARDING_DETAIL_CATEGORIES: readonly AgentWorkspa
     group: 'ONBOARDING',
     label: 'Local Context',
     summary: 'Create/import memory, personas, skills, routines, notes, and Knowledge.',
-    detail: 'Use this page to seed the assistant with durable local context. These forms create Agent-owned records or ingest reviewed sources.',
+    detail: 'Give the assistant a memory of who you are and what you care about. Create personas, starter memories, skills, and routines, or import context files you already have. These records are stored locally and used on every turn.',
     actions: [
       { id: 'context-vibe-status', label: 'Inspect VIBE.md', detail: 'Show project/global VIBE.md personality files, blocked files, and init paths before relying on a custom assistant feel.', kind: 'guidance', safety: 'read-only' },
       { id: 'context-project-files', label: 'Inspect project context', detail: 'List secret-scanned .hermes.md, HERMES.md, AGENTS.md, CLAUDE.md, SOUL.md, and Cursor context files with blocked/truncated status.', kind: 'guidance', safety: 'read-only' },
@@ -122,20 +141,4 @@ export const AGENT_WORKSPACE_ONBOARDING_DETAIL_CATEGORIES: readonly AgentWorkspa
       { id: 'context-knowledge-browser-history', label: 'Import browser history', detail: 'Import local browser history or bookmarks into isolated Agent Knowledge.', editorKind: 'knowledge-browser-history', kind: 'editor', safety: 'safe' },
     ],
   },
-  {
-    id: 'onboarding-automation',
-    group: 'ONBOARDING',
-    label: 'Automation Setup',
-    summary: 'Set scheduled work limits for reminders and routines.',
-    detail: 'Use this page to enable automation and set bounded run limits. Creating actual reminders and routines remains a separate confirmed action.',
-    actions: [
-      settingAction({ id: 'automation-enabled', label: 'Use automation', detail: 'Toggle the automation subsystem for reminders and scheduled routines.', key: 'automation.enabled' }),
-      settingAction({ id: 'automation-max-concurrent', label: 'Concurrent runs', detail: 'Set the maximum automation runs that can execute concurrently.', key: 'automation.maxConcurrentRuns', visibleWhenKey: 'automation.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'automation-history-limit', label: 'Run history limit', detail: 'Set the number of run history entries retained per automation job.', key: 'automation.runHistoryLimit', visibleWhenKey: 'automation.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'automation-default-timeout', label: 'Default timeout', detail: 'Set the default automation run timeout in milliseconds.', key: 'automation.defaultTimeoutMs', visibleWhenKey: 'automation.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'automation-catch-up', label: 'Catch-up window', detail: 'Set how long startup should catch up missed automation runs.', key: 'automation.catchUpWindowMinutes', visibleWhenKey: 'automation.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'automation-failure-cooldown', label: 'Failure cooldown', detail: 'Set the cooldown after a failed automation run.', key: 'automation.failureCooldownMs', visibleWhenKey: 'automation.enabled', visibleWhenValue: true }),
-      settingAction({ id: 'automation-delete-after-run', label: 'Delete one-shot jobs', detail: 'Toggle deleting one-shot automation jobs after their first successful run.', key: 'automation.deleteAfterRun', visibleWhenKey: 'automation.enabled', visibleWhenValue: true }),
-    ],
-  },
 ];

package/src/input/agent-workspace-onboarding-finish.ts

@@ -1,5 +1,8 @@
 import type { AgentWorkspaceAction, AgentWorkspaceCategory } from './agent-workspace-types.ts';
 
+// These are WIZARD-STEP ids (AgentSetupWizardStep.id), NOT normalized plan ids.
+// Do NOT cross-check these against SetupPlanItem ids or PLAN_ITEM_CATEGORY_MAP keys.
+// (Compare: agent-workspace-onboarding-state.ts normalises 'provider-model' → 'provider-access' for plan-layer lookups.)
 export const ONBOARDING_CRITICAL_STEP_IDS = ['runtime', 'connected-host-auth', 'provider-model'] as const;
 
 export const ONBOARDING_COMPLETE_SYNTHETIC_ACTION: AgentWorkspaceAction = {
@@ -13,9 +16,13 @@ export const ONBOARDING_COMPLETE_SYNTHETIC_ACTION: AgentWorkspaceAction = {
 export function shouldShowOnboardingFinishFooter(
   category: AgentWorkspaceCategory,
   baseActions: readonly AgentWorkspaceAction[],
+  readyToChat?: boolean,
 ): boolean {
-  return (
-    category.group === 'ONBOARDING'
-    && baseActions.every((a) => a.kind !== 'onboarding-complete')
-  );
+  if (category.group !== 'ONBOARDING') return false;
+  if (baseActions.some((a) => a.kind === 'onboarding-complete')) return false;
+  // When readyToChat is explicitly false (we have a valid OnboardingState and the user
+  // cannot chat yet), withhold the footer so completion is not premature.
+  // When readyToChat is undefined (no OnboardingState available), default to showing.
+  if (readyToChat === false) return false;
+  return true;
 }

package/src/input/agent-workspace-onboarding-state.ts

@@ -0,0 +1,111 @@
+import type { AgentSetupWizardStep } from '../agent/setup-wizard.ts';
+import type { SetupPlanItem } from '../tools/agent-harness-setup-posture-types.ts';
+import type { AgentWorkspaceRuntimeSnapshot } from './agent-workspace-types.ts';
+import type { OnboardingShellPaths } from '../runtime/onboarding/types.ts';
+import {
+  deriveOnboardingState,
+  readOnboardingCheckMarker,
+  readOnboardingCompletionMarker,
+  type OnboardingState,
+} from '../runtime/onboarding/index.ts';
+
+/**
+ * Adapts an AgentSetupWizardStep to a SetupPlanItem for use with
+ * deriveOnboardingState. The wizard uses different IDs for some steps;
+ * this adapter normalises the two known divergences:
+ *   - 'provider-model' (wizard) → 'provider-access' (plan) so readyToChat
+ *     and PLAN_ITEM_CATEGORY_MAP both resolve correctly.
+ * The output ids are PLAN ids (SetupPlanItem.id), not wizard-step ids.
+ * Do NOT compare the output ids against ONBOARDING_CRITICAL_STEP_IDS which
+ * operates on wizard-step ids (see agent-workspace-onboarding-finish.ts).
+ * blocksAutonomy is inferred from sourceStatus: blocked or check items block autonomy.
+ * Intentional approximation: AgentSetupWizardStep does not carry the authoritative
+ * SetupPlanItem.blocksAutonomy field; the wizard snapshot only exposes sourceStatus,
+ * so we derive it from status here rather than threading the real value through.
+ */
+function wizardItemToSetupPlanItem(step: AgentSetupWizardStep): SetupPlanItem {
+  const id = step.id === 'provider-model' ? 'provider-access' : step.id;
+  return {
+    id,
+    label: step.label,
+    status: step.sourceStatus,
+    priority: 0,
+    // Intentional approximation: AgentSetupWizardStep doesn't carry blocksAutonomy;
+    // derive it from sourceStatus since the real value isn't available at this layer.
+    blocksAutonomy: step.sourceStatus === 'blocked' || step.sourceStatus === 'check',
+    reason: step.detail,
+    nextAction: step.userRoute,
+    userRoute: step.userRoute,
+    modelRoute: step.modelRoute,
+  };
+}
+
+export interface OnboardingEntryResult {
+  /** Category ID to navigate to on entry (undefined = leave as-is). */
+  readonly categoryId: string | undefined;
+  /** Status message to display. */
+  readonly status: string;
+}
+
+/**
+ * Derives the entry navigation and status message from an OnboardingState.
+ * Called by open() in ONBOARDING mode.
+ */
+export function deriveOnboardingEntry(obs: OnboardingState): OnboardingEntryResult {
+  if (obs.phase === 'in-progress' && obs.currentStepId) {
+    const step = obs.steps.find((s) => s.id === obs.currentStepId);
+    if (step) return { categoryId: step.categoryId, status: `Picking up where you left off: ${step.label}.` };
+  }
+  const currentStep = obs.steps.find((s) => s.id === obs.currentStepId);
+  const nextHint = currentStep ? ` — ${currentStep.nextLabel}` : '';
+  return { categoryId: undefined, status: `${obs.progressLabel}${nextHint}.` };
+}
+
+/**
+ * Given an OnboardingState, computes the set of ONBOARDING category IDs that are
+ * currently unlocked and adds them to the provided mutable revealed set.
+ * 'setup' is always present; other categories unlock once their step is ready.
+ */
+export function updateRevealedOnboardingCategories(
+  obs: OnboardingState,
+  revealed: Set<string>,
+): void {
+  revealed.add('setup');
+  for (const step of obs.steps) {
+    if (step.status === 'ready') revealed.add(step.categoryId);
+  }
+  if (obs.readyToChat) revealed.add('account-model');
+  // Also reveal the active resume target so that navigating to it on re-entry
+  // actually works. The resume target is by definition non-ready (it is the
+  // first blocker), so it would otherwise be filtered out above. Only adds —
+  // preserves monotonicity of the revealed set.
+  if (obs.phase === 'in-progress' && obs.currentStepId) {
+    const cur = obs.steps.find((s) => s.id === obs.currentStepId);
+    if (cur) revealed.add(cur.categoryId);
+  }
+}
+
+/**
+ * Derives the current OnboardingState from a runtime snapshot and shell paths.
+ * Returns null when no snapshot is available (e.g. context is not fully initialised).
+ * Reads check and completion markers from shellPaths when provided.
+ */
+export function computeOnboardingStateFromSnapshot(
+  snapshot: AgentWorkspaceRuntimeSnapshot | null,
+  shellPaths: OnboardingShellPaths | undefined,
+): OnboardingState | null {
+  const wizard = snapshot?.setupWizard;
+  if (!wizard?.steps?.length) return null;
+
+  const plan: SetupPlanItem[] = wizard.steps.map(wizardItemToSetupPlanItem);
+
+  // Build minimal marker states — default to non-existent when shellPaths is unavailable.
+  const checkMarker = shellPaths
+    ? readOnboardingCheckMarker(shellPaths, 'user')
+    : { scope: 'user' as const, path: '', exists: false, payload: null };
+  const completionMarker = shellPaths
+    ? readOnboardingCompletionMarker(shellPaths, 'user')
+    : { scope: 'user' as const, path: '', exists: false, payload: null };
+
+  return deriveOnboardingState({ plan, checkMarker, completionMarker });
+}

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

@@ -0,0 +1,260 @@
+import type { AgentWorkspaceActionResult, AgentWorkspaceLocalEditor } from './agent-workspace-types.ts';
+import { quoteSlashCommandArg } from './slash-command-parser.ts';
+import type { AgentWorkspaceProfileEditorKind } from './agent-workspace-profile-editors.ts';
+
+type AgentWorkspaceFieldReader = (fieldId: string) => string;
+
+type AgentWorkspaceProfileEditorSubmissionResult =
+  | {
+    readonly kind: 'editor';
+    readonly editor: AgentWorkspaceLocalEditor;
+    readonly status: string;
+    readonly actionResult?: AgentWorkspaceActionResult;
+  }
+  | {
+    readonly kind: 'dispatch';
+    readonly command: string;
+    readonly status: string;
+    readonly actionResult: AgentWorkspaceActionResult;
+  };
+
+function isAffirmative(value: string): boolean {
+  return /^(y|yes|true)$/i.test(value.trim());
+}
+
+export function isAgentWorkspaceProfileEditorSubmissionKind(kind: string): kind is AgentWorkspaceProfileEditorKind {
+  return kind === 'profile-template-export'
+    || kind === 'profile-template-import'
+    || kind === 'profile-template-show'
+    || kind === 'profile-show'
+    || kind === 'profile-template-from-discovered'
+    || kind === 'profile-from-discovered'
+    || kind === 'profile-default'
+    || kind === 'profile-default-clear'
+    || kind === 'profile-delete';
+}
+
+export function buildAgentWorkspaceProfileEditorSubmission(
+  editor: AgentWorkspaceLocalEditor,
+  readField: AgentWorkspaceFieldReader,
+): AgentWorkspaceProfileEditorSubmissionResult {
+  if (editor.kind === 'profile-template-export') {
+    if (!isAffirmative(readField('confirm'))) {
+      return {
+        kind: 'editor',
+        editor: { ...editor, message: 'Starter template export not confirmed. Type yes, then press Enter.' },
+        status: 'Agent starter template export not confirmed.',
+      };
+    }
+    const command = `/agent-profile template export ${quoteSlashCommandArg(readField('templateId'))} ${quoteSlashCommandArg(readField('path'))} --yes`;
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening Agent starter template export.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening Agent starter template export',
+        detail: 'The workspace handed a confirmed starter template export command to the shell-owned command router.',
+        command,
+        safety: 'safe',
+      },
+    };
+  }
+  if (editor.kind === 'profile-template-import') {
+    if (!isAffirmative(readField('confirm'))) {
+      return {
+        kind: 'editor',
+        editor: { ...editor, message: 'Starter template import not confirmed. Type yes, then press Enter.' },
+        status: 'Agent starter template import not confirmed.',
+      };
+    }
+    const command = `/agent-profile template import ${quoteSlashCommandArg(readField('path'))} --yes`;
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening Agent starter template import.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening Agent starter template import',
+        detail: 'The workspace handed a confirmed starter template import command to the shell-owned command router.',
+        command,
+        safety: 'safe',
+      },
+    };
+  }
+  if (editor.kind === 'profile-template-show') {
+    const command = `/agent-profile template show ${quoteSlashCommandArg(readField('id'))}`;
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening Agent starter template preview.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening Agent starter template preview',
+        detail: 'The workspace handed a read-only starter template preview command to the shell-owned command router.',
+        command,
+        safety: 'read-only',
+      },
+    };
+  }
+  if (editor.kind === 'profile-show') {
+    const command = `/agent-profile show ${quoteSlashCommandArg(readField('profile'))}`;
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening Agent profile detail.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening Agent profile detail',
+        detail: 'The workspace handed a read-only Agent profile inspection command to the shell-owned command router.',
+        command,
+        safety: 'read-only',
+      },
+    };
+  }
+  if (editor.kind === 'profile-template-from-discovered') {
+    if (!isAffirmative(readField('confirm'))) {
+      return {
+        kind: 'editor',
+        editor: { ...editor, message: 'Starter-from-discovered creation not confirmed. Type yes, then press Enter.' },
+        status: 'Agent starter-from-discovered creation not confirmed.',
+      };
+    }
+    const parts = [
+      '/agent-profile',
+      'template',
+      'from-discovered',
+      quoteSlashCommandArg(readField('id')),
+    ];
+    const name = readField('name');
+    const description = readField('description');
+    const persona = readField('persona');
+    const skills = readField('skills');
+    const routines = readField('routines');
+    if (name.length > 0) parts.push('--name', quoteSlashCommandArg(name));
+    if (description.length > 0) parts.push('--description', quoteSlashCommandArg(description));
+    if (persona.length > 0) parts.push('--persona', quoteSlashCommandArg(persona));
+    if (skills.length > 0) parts.push('--skills', quoteSlashCommandArg(skills));
+    if (routines.length > 0) parts.push('--routines', quoteSlashCommandArg(routines));
+    if (isAffirmative(readField('replace'))) parts.push('--replace');
+    parts.push('--yes');
+    const command = parts.join(' ');
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening Agent starter-from-discovered creation.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening Agent starter-from-discovered creation',
+        detail: 'The workspace handed a confirmed starter creation command to the shell-owned command router.',
+        command,
+        safety: 'safe',
+      },
+    };
+  }
+  if (editor.kind === 'profile-from-discovered') {
+    if (!isAffirmative(readField('confirm'))) {
+      return {
+        kind: 'editor',
+        editor: { ...editor, message: 'Profile-from-discovered creation not confirmed. Type yes, then press Enter.' },
+        status: 'Agent profile-from-discovered creation not confirmed.',
+      };
+    }
+    const parts = [
+      '/agent-profile',
+      'create-from-discovered',
+      quoteSlashCommandArg(readField('profile')),
+    ];
+    const templateId = readField('templateId');
+    const name = readField('name');
+    const description = readField('description');
+    const persona = readField('persona');
+    const skills = readField('skills');
+    const routines = readField('routines');
+    if (templateId.length > 0) parts.push('--template-id', quoteSlashCommandArg(templateId));
+    if (name.length > 0) parts.push('--name', quoteSlashCommandArg(name));
+    if (description.length > 0) parts.push('--description', quoteSlashCommandArg(description));
+    if (persona.length > 0) parts.push('--persona', quoteSlashCommandArg(persona));
+    if (skills.length > 0) parts.push('--skills', quoteSlashCommandArg(skills));
+    if (routines.length > 0) parts.push('--routines', quoteSlashCommandArg(routines));
+    if (isAffirmative(readField('replace'))) parts.push('--replace');
+    parts.push('--yes');
+    const command = parts.join(' ');
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening Agent profile-from-discovered creation.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening Agent profile-from-discovered creation',
+        detail: 'The workspace handed a confirmed discovered-behavior profile creation command to the shell-owned command router.',
+        command,
+        safety: 'safe',
+      },
+    };
+  }
+  if (editor.kind === 'profile-default') {
+    if (!isAffirmative(readField('confirm'))) {
+      return {
+        kind: 'editor',
+        editor: { ...editor, message: 'Default Agent profile selection not confirmed. Type yes, then press Enter.' },
+        status: 'Default Agent profile selection not confirmed.',
+      };
+    }
+    const command = `/agent-profile use ${quoteSlashCommandArg(readField('profile'))} --yes`;
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening default Agent profile selection.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening default Agent profile selection',
+        detail: 'The workspace handed a confirmed default profile selection command to the shell-owned command router.',
+        command,
+        safety: 'safe',
+      },
+    };
+  }
+  if (editor.kind === 'profile-default-clear') {
+    if (!isAffirmative(readField('confirm'))) {
+      return {
+        kind: 'editor',
+        editor: { ...editor, message: 'Default Agent profile clear not confirmed. Type yes, then press Enter.' },
+        status: 'Default Agent profile clear not confirmed.',
+      };
+    }
+    const command = '/agent-profile default clear --yes';
+    return {
+      kind: 'dispatch',
+      command,
+      status: 'Opening default Agent profile clear.',
+      actionResult: {
+        kind: 'dispatched',
+        title: 'Opening default Agent profile clear',
+        detail: 'The workspace handed a confirmed default profile clear command to the shell-owned command router.',
+        command,
+        safety: 'safe',
+      },
+    };
+  }
+  if (!isAffirmative(readField('confirm'))) {
+    return {
+      kind: 'editor',
+      editor: { ...editor, message: 'Agent profile delete not confirmed. Type yes, then press Enter.' },
+      status: 'Agent profile delete not confirmed.',
+    };
+  }
+  const command = `/agent-profile delete ${quoteSlashCommandArg(readField('profile'))} --yes`;
+  return {
+    kind: 'dispatch',
+    command,
+    status: 'Opening Agent profile deletion.',
+    actionResult: {
+      kind: 'dispatched',
+      title: 'Opening Agent profile deletion',
+      detail: 'The workspace handed a confirmed profile deletion command to the shell-owned command router.',
+      command,
+      safety: 'safe',
+    },
+  };
+}