@pellux/goodvibes-agent 1.2.0 → 1.3.0

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

@@ -24,6 +24,8 @@ import type { PromptContextReceipt } from '../agent/prompt-context-receipts.ts';
 import { discoverProjectContextFiles } from '../agent/project-context-files.ts';
 import { getAgentRuntimeProfilesRoot, listAgentRuntimeProfiles, listAgentRuntimeProfileTemplates, readAgentRuntimeProfileSelection } from '../agent/runtime-profile.ts';
 import { RoutineScheduleReceiptStore } from '../agent/routine-schedule-receipts.ts';
+import { buildSetupWizardDurableReceipts } from '../agent/setup-wizard-artifact-receipts.ts';
+import { mergeSetupWizardDurableReceipts, setupWizardLiveDurableReceipts } from './setup-wizard-live-receipts.ts';
 import { readSetupWizardCheckpoint } from '../agent/setup-wizard-checkpoint.ts';
 import { discoverVibeFiles } from '../agent/vibe-file.ts';
 import {
@@ -35,6 +37,7 @@ import {
   buildAgentSetupWizard,
   emptyAgentSetupSmokeHistory,
   emptyAgentSetupWizardCheckpoint,
+  setupStepHasSatisfyingReceipt,
   type AgentSetupWizard,
   type AgentSetupWizardBlockedCheckFrequency,
   type AgentSetupWizardCheckpoint,
@@ -266,6 +269,11 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
       return { available: false, items: [] };
     }
   })();
+  const setupSmokeHistory = buildSetupSmokeHistory(artifactListSnapshot.items, artifactListSnapshot.available);
+  const durableSetupReceipts = mergeSetupWizardDurableReceipts(
+    buildSetupWizardDurableReceipts(artifactListSnapshot.items),
+    setupWizardLiveDurableReceipts(context),
+  );
   const recentReviewerHandoffs = (() => {
     try {
       const handoffs = artifactListSnapshot.items
@@ -452,6 +460,12 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
     voiceProviders: voiceProviderDescriptors,
     mediaProviders: mediaProviderDescriptors,
   });
+  const browserPwaEnabled = readConfigBoolean(context, 'web.enabled', false);
+  const browserPwaPublicBaseUrl = readConfigString(context, 'web.publicBaseUrl', '(not configured)');
+  const connectedHostAuthReceiptReady = setupStepHasSatisfyingReceipt(durableSetupReceipts, 'connected-host-auth');
+  const installSmokeReceiptReady = setupSmokeHistory.latestResult === 'ready-for-user-run'
+    || setupStepHasSatisfyingReceipt(durableSetupReceipts, 'install-smoke');
+  const browserPwaReceiptReady = setupStepHasSatisfyingReceipt(durableSetupReceipts, 'browser-pwa');
   const setupChecklist = buildAgentWorkspaceSetupChecklist({
     provider,
     model,
@@ -460,6 +474,7 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
     connectedHostTokenReadable: companionAccess.tokenReadable,
     connectedHostTokenPath: companionAccess.tokenPath,
     connectedHostTokenError: companionAccess.tokenError,
+    connectedHostAuthReceiptReady,
     activeSubscriptionCount: subscriptionSnapshot.active,
     pendingSubscriptionCount: subscriptionSnapshot.pending,
     availableSubscriptionProviderCount: subscriptionSnapshot.available,
@@ -483,14 +498,19 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
     readyChannelCount: channels.filter((channel) => channel.ready).length,
     voiceProviderCount: voiceProviders.length,
     mediaProviderCount: mediaProviders.length,
+    installSmokeReceiptReady,
+    browserPwaEnabled,
+    browserPwaPublicBaseUrl,
+    browserPwaFirstRunReceiptStatus: browserPwaReceiptReady ? 'published' : 'not-published',
     runtimeProfileCount: runtimeProfiles.length,
     runtimeStarterTemplateCount: runtimeStarterTemplates.length,
   });
   const setupWizard = buildWorkspaceSetupWizard(
     setupChecklist,
-    buildSetupSmokeHistory(artifactListSnapshot.items, artifactListSnapshot.available),
+    setupSmokeHistory,
     buildSetupWizardCheckpoint(context),
     setupCompletionMarkerExists(context),
+    durableSetupReceipts,
   );
   const researchBrowserRunnerContract = buildResearchBrowserRunnerContract(context);
   const researchVisualReportContract = buildResearchVisualReportContract(researchSourceSnapshot);
@@ -619,8 +639,8 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
     mcpConnectedServerCount: mcpSnapshot.connectedCount,
     mcpQuarantinedServerCount: mcpSnapshot.quarantinedCount,
     mcpAllowAllServerCount: mcpSnapshot.allowAllCount,
-    browserToolExposureEnabled: readConfigBoolean(context, 'web.enabled', false),
-    browserToolPublicBaseUrl: readConfigString(context, 'web.publicBaseUrl', '(not configured)'),
+    browserToolExposureEnabled: browserPwaEnabled,
+    browserToolPublicBaseUrl: browserPwaPublicBaseUrl,
     activeRuntimeProfile: inferActiveRuntimeProfile(context.workspace?.shellPaths?.homeDirectory ?? ''),
     selectedRuntimeProfile: selectedRuntimeProfile?.id ?? null,
     selectedRuntimeProfileExists: selectedRuntimeProfile?.exists ?? false,

package/src/input/agent-workspace.ts

@@ -19,7 +19,7 @@ import { deleteAgentWorkspaceMemoryEditor, submitAgentWorkspaceMemoryEditor } fr
 import { jumpAgentWorkspaceSelection, moveAgentWorkspaceSelection, selectAgentWorkspaceCategory } from './agent-workspace-navigation.ts';
 import { appendAgentWorkspaceActionSearchText, backspaceAgentWorkspaceActionSearch, beginAgentWorkspaceActionSearch, clearAgentWorkspaceActionSearch, commitAgentWorkspaceActionSearchSelection, searchAgentWorkspaceActions } from './agent-workspace-search.ts';
 import { applyAgentWorkspaceSetupCheckpointAction } from './agent-workspace-setup-checkpoint-action.ts';
-import { agentWorkspaceSettingSchema, applyAgentWorkspaceSettingValue, buildAgentWorkspaceSettingActionEffect, importAgentWorkspaceTuiSettings, isAgentWorkspaceActionVisible } from './agent-workspace-settings.ts';
+import { agentWorkspaceSettingSchema, applyAgentWorkspaceSettingValue, buildAgentWorkspaceSettingActionEffect, buildAgentWorkspaceSettingActionPreview, importAgentWorkspaceTuiSettings, isAgentWorkspaceActionVisible } from './agent-workspace-settings.ts';
 import { buildAgentWorkspaceRuntimeSnapshot } from './agent-workspace-snapshot.ts';
 import { submitAgentWorkspaceSubscriptionLoginFinishEditor, submitAgentWorkspaceSubscriptionLoginStartEditor, submitAgentWorkspaceSubscriptionLogoutEditor } from './agent-workspace-subscription-editor.ts';
 import type { AgentWorkspaceAction, AgentWorkspaceActionResult, AgentWorkspaceActionSearchResult, AgentWorkspaceCategory, AgentWorkspaceCommandDispatcher, AgentWorkspaceEditorField, AgentWorkspaceFocusPane, AgentWorkspaceLocalEditor, AgentWorkspaceLocalEditorKind, AgentWorkspaceLocalLibraryItem, AgentWorkspaceLocalOperation, AgentWorkspacePromptDispatcher, AgentWorkspaceRuntimeSnapshot } from './agent-workspace-types.ts';
@@ -142,6 +142,10 @@ export class AgentWorkspace {
     return selectedAgentWorkspaceLocalLibraryItem(this.runtimeSnapshot, this.selectedLibraryItemIndexes, kind);
   }
 
+  settingActionPreview(action: AgentWorkspaceAction): string | null {
+    return buildAgentWorkspaceSettingActionPreview(this.context, action);
+  }
+
   focusCategories(): void {
     this.focusPane = 'categories';
   }

package/src/input/setup-wizard-live-receipts.ts

@@ -0,0 +1,76 @@
+import type { CommandContext } from './command-registry.ts';
+import { buildSetupWizardDurableReceiptsFromReadModel, mergeSetupWizardDurableReceipts } from '../agent/setup-wizard-artifact-receipts.ts';
+import type { AgentSetupWizardDurableReceipt } from '../agent/setup-wizard.ts';
+
+interface SetupReceiptReadModelSource {
+  readonly path: string;
+  readonly source: unknown;
+}
+
+function readRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function setupReceiptReadModelSources(context: CommandContext): readonly SetupReceiptReadModelSource[] {
+  const contextRecord = context as unknown as Record<string, unknown>;
+  const platform = readRecord(contextRecord.platform);
+  const clients = readRecord(contextRecord.clients);
+  const readModels = readRecord(platform.readModels);
+  const setup = readRecord(readModels.setup);
+  const setupWizard = readRecord(readModels.setupWizard);
+  const firstRun = readRecord(readModels.firstRun);
+  const browserPwa = readRecord(readModels.browserPwa);
+  const operator = readRecord(clients.operator);
+  return [
+    { path: 'context.platform.readModels.setup.receipts', source: setup.receipts },
+    { path: 'context.platform.readModels.setup.setupReceipts', source: setup.setupReceipts },
+    { path: 'context.platform.readModels.setup.receiptEvents', source: setup.receiptEvents },
+    { path: 'context.platform.readModels.setup.eventStream', source: setup.eventStream },
+    { path: 'context.platform.readModels.setup', source: readModels.setup },
+    { path: 'context.platform.readModels.setupWizard.receipts', source: setupWizard.receipts },
+    { path: 'context.platform.readModels.setupWizard.durableReceipts', source: setupWizard.durableReceipts },
+    { path: 'context.platform.readModels.setupWizard.receiptEvents', source: setupWizard.receiptEvents },
+    { path: 'context.platform.readModels.setupWizard.eventStream', source: setupWizard.eventStream },
+    { path: 'context.platform.readModels.setupReceipts', source: readModels.setupReceipts },
+    { path: 'context.platform.readModels.setupReceiptEvents', source: readModels.setupReceiptEvents },
+    { path: 'context.platform.readModels.setupReceiptEventStream', source: readModels.setupReceiptEventStream },
+    { path: 'context.platform.readModels.durableSetupReceipts', source: readModels.durableSetupReceipts },
+    { path: 'context.platform.readModels.firstRun.receipts', source: firstRun.receipts },
+    { path: 'context.platform.readModels.browserPwa.firstRunReceipts', source: browserPwa.firstRunReceipts },
+    { path: 'context.platform.setupReceipts', source: platform.setupReceipts },
+    { path: 'context.platform.setupReceiptEvents', source: platform.setupReceiptEvents },
+    { path: 'context.clients.operator.setupReceipts', source: operator.setupReceipts },
+    { path: 'context.clients.operator.setupReceiptEvents', source: operator.setupReceiptEvents },
+  ];
+}
+
+function readSnapshot(source: unknown): unknown {
+  if (typeof source === 'function') {
+    const result = (source as () => unknown)();
+    return result instanceof Promise ? undefined : result;
+  }
+  const record = readRecord(source);
+  for (const methodName of ['getSnapshot', 'snapshot', 'list', 'listReceipts', 'listEvents', 'listReceiptEvents', 'readEvents']) {
+    const method = record[methodName];
+    if (typeof method === 'function') {
+      const result = (method as () => unknown)();
+      return result instanceof Promise ? undefined : result;
+    }
+  }
+  return source;
+}
+
+export function setupWizardLiveDurableReceipts(context: CommandContext): readonly AgentSetupWizardDurableReceipt[] {
+  const receipts: AgentSetupWizardDurableReceipt[][] = [];
+  for (const entry of setupReceiptReadModelSources(context)) {
+    if (entry.source === undefined || entry.source === null) continue;
+    try {
+      receipts.push([...buildSetupWizardDurableReceiptsFromReadModel(readSnapshot(entry.source), entry.path)]);
+    } catch {
+      // Broken host read models should not hide local setup posture.
+    }
+  }
+  return mergeSetupWizardDurableReceipts(...receipts);
+}
+
+export { mergeSetupWizardDurableReceipts };

package/src/renderer/agent-workspace-context-lines.ts

@@ -83,6 +83,21 @@ function setupOverviewLines(snapshot: AgentWorkspaceRuntimeSnapshot): ContextLin
       fg: wizard.smokeHistory.latestResult === 'blocked' ? PALETTE.warn : PALETTE.info,
     });
   }
+  if (wizard.stepHistory.length > 0) {
+    const latest = wizard.stepHistory[0]!;
+    lines.push({
+      text: `Step history: ${wizard.stepHistory.length} recorded; latest ${latest.stepLabel} ${latest.kind} at ${latest.recordedAt}.`,
+      fg: PALETTE.good,
+    });
+  }
+  if (wizard.receiptGaps.length > 0) {
+    const labels = wizard.receiptGaps.slice(0, 3).map((gap) => gap.stepLabel).join(', ');
+    const suffix = wizard.receiptGaps.length > 3 ? `, +${wizard.receiptGaps.length - 3} more` : '';
+    lines.push({
+      text: `Receipt gaps: ${labels}${suffix} still need durable setup receipt ids.`,
+      fg: PALETTE.warn,
+    });
+  }
   return lines;
 }
 
@@ -257,13 +272,13 @@ function promptReceiptTimelineLines(snapshot: AgentWorkspaceRuntimeSnapshot): Co
     fg: promptReceiptOutcomeColor(latest.outcomeStatus),
     bold: latest.outcomeStatus === 'error' || latest.outcomeStatus === 'cancelled',
   });
-  lines.push({ text: `Inspect latest prompt receipt: ${latest.inspectRoute}`, fg: PALETTE.good });
+  lines.push({ text: `Latest prompt receipt: ${latest.receiptId}; inspect it from Prompt context.`, fg: PALETTE.good });
   if (timeline.errorCount > 0) {
-    lines.push({ text: `Filter prompt receipt errors: ${timeline.filterRoutes.error}`, fg: PALETTE.warn });
+    lines.push({ text: 'Prompt receipt filter: show errors.', fg: PALETTE.warn });
   } else if (timeline.cancelledCount > 0) {
-    lines.push({ text: `Filter cancelled prompt receipts: ${timeline.filterRoutes.cancelled}`, fg: PALETTE.warn });
+    lines.push({ text: 'Prompt receipt filter: show cancelled turns.', fg: PALETTE.warn });
   } else if (timeline.pendingCount > 0) {
-    lines.push({ text: `Filter pending prompt receipts: ${timeline.filterRoutes.pending}`, fg: PALETTE.info });
+    lines.push({ text: 'Prompt receipt filter: show pending turns.', fg: PALETTE.info });
   }
   for (const receipt of timeline.items.slice(0, 3)) {
     lines.push({
@@ -274,7 +289,7 @@ function promptReceiptTimelineLines(snapshot: AgentWorkspaceRuntimeSnapshot): Co
   if (latest.detail) {
     lines.push({ text: `Latest outcome detail: ${compactText(latest.detail, 104)}`, fg: PALETTE.warn });
   }
-  lines.push({ text: `Inspect: ${timeline.inspectRoute}`, fg: PALETTE.good });
+  lines.push({ text: 'Prompt context controls stay read-only from this setup page.', fg: PALETTE.good });
   return lines;
 }
 
@@ -478,7 +493,7 @@ export function snapshotLines(workspace: AgentWorkspace, category: AgentWorkspac
       { text: `VIBE.md: ${vibe.applied} applied; ${vibe.blocked} blocked; ${vibe.truncated} truncated.`, fg: vibe.blocked > 0 ? PALETTE.warn : vibe.applied > 0 ? PALETTE.good : PALETTE.muted },
       { text: `Project context: ${projectContext.loaded} loaded; ${projectContext.blocked} blocked; ${projectContext.truncated} truncated.`, fg: projectContext.blocked > 0 ? PALETTE.warn : projectContext.loaded > 0 ? PALETTE.good : PALETTE.muted },
       ...promptReceiptTimelineLines(snapshot),
-      { text: 'Context routes: context prompt/files/file/receipt, /vibe status.', fg: PALETTE.good },
+      { text: 'Context controls: prompt receipts, project files, one-file inspection, and VIBE.md review.', fg: PALETTE.good },
     );
   } else if (category.id === 'onboarding-automation') {
     base.push(

package/src/renderer/agent-workspace.ts

@@ -68,10 +68,42 @@ function actionCommand(action: AgentWorkspaceAction): string {
   return action.command ?? '(guidance)';
 }
 
-function actionMetaLine(action: AgentWorkspaceAction): ContextLine {
+function isOnboardingCategory(category: AgentWorkspaceCategory): boolean {
+  return category.group === 'ONBOARDING';
+}
+
+function onboardingActionChange(workspace: AgentWorkspace, action: AgentWorkspaceAction): string {
+  if (action.kind === 'setting') {
+    return workspace.settingActionPreview(action) ?? 'Update setting';
+  }
+  if (action.kind === 'settings-import') return 'Import compatible GoodVibes preferences';
+  if (action.kind === 'setup-checkpoint') {
+    if (action.setupCheckpointOperation === 'show') return 'Show saved setup progress';
+    if (action.setupCheckpointOperation === 'mark-current') return 'Save current setup progress';
+    if (action.setupCheckpointOperation === 'clear') return 'Clear saved setup progress';
+    return 'Review setup progress';
+  }
+  if (action.kind === 'model-picker') return action.modelPickerFlow === 'model' ? 'Choose a model' : 'Choose provider and model';
+  if (action.kind === 'settings-modal') return 'Open settings';
+  if (action.kind === 'workspace') return 'Open setup area';
+  if (action.kind === 'editor') return 'Open guided form';
+  if (action.kind === 'local-selection') return 'Move selection';
+  if (action.kind === 'local-operation') return 'Apply selected library action';
+  if (action.kind === 'onboarding-complete') return 'Save setup completion';
+  if (action.safety === 'read-only') return 'Review readiness';
+  if (action.safety === 'blocked') return 'Unavailable in this setup step';
+  return 'Open option';
+}
+
+function actionChange(workspace: AgentWorkspace, category: AgentWorkspaceCategory, action: AgentWorkspaceAction): string {
+  return isOnboardingCategory(category) ? onboardingActionChange(workspace, action) : actionCommand(action);
+}
+
+function actionMetaLine(workspace: AgentWorkspace, category: AgentWorkspaceCategory, action: AgentWorkspaceAction): ContextLine {
+  const onboarding = isOnboardingCategory(category);
   return {
-    text: `Does: ${actionCommand(action)}`,
-    fg: action.safety === 'blocked' ? PALETTE.warn : action.kind === 'command' ? PALETTE.info : PALETTE.muted,
+    text: `${onboarding ? 'Change' : 'Does'}: ${actionChange(workspace, category, action)}`,
+    fg: action.safety === 'blocked' ? PALETTE.warn : !onboarding && action.kind === 'command' ? PALETTE.info : PALETTE.muted,
   };
 }
 
@@ -135,19 +167,20 @@ function buildContextRows(workspace: AgentWorkspace, category: AgentWorkspaceCat
   const selectedActionLines: ContextLine[] = action
     ? [
       { text: `Selected: ${action.label}`, fg: PALETTE.title, bold: true },
-      actionMetaLine(action),
+      actionMetaLine(workspace, category, action),
     ]
     : [];
   const snapshotContextLines = snapshotLines(workspace, category, workspace.runtimeSnapshot);
   lines.push(...selectedActionLines, ...snapshotContextLines);
 
+  const onboarding = isOnboardingCategory(category);
   if (workspace.lastActionResult) {
     lines.push(
-      { text: 'Action Result', fg: PALETTE.title, bold: true },
+      { text: onboarding ? 'Result' : 'Action Result', fg: PALETTE.title, bold: true },
       { text: workspace.lastActionResult.title, fg: actionResultColor(workspace.lastActionResult), bold: true },
       { text: compactText(workspace.lastActionResult.detail), fg: PALETTE.text },
     );
-    if (workspace.lastActionResult.command) {
+    if (!onboarding && workspace.lastActionResult.command) {
       lines.push({ text: `Command: ${workspace.lastActionResult.command}`, fg: PALETTE.muted });
     }
   }
@@ -213,6 +246,8 @@ function buildEditorFieldRows(editor: AgentWorkspaceLocalEditor, index: number,
 
 function buildActionRows(workspace: AgentWorkspace, width: number, height: number): WorkspaceRow[] {
   if (workspace.localEditor) return buildEditorRows(workspace.localEditor, width, height);
+  const category = workspace.selectedActionCategory;
+  const onboarding = isOnboardingCategory(category);
   const rows: WorkspaceRow[] = [];
   const labelWidth = Math.min(34, Math.max(18, Math.floor(width * 0.38)));
   const commandWidth = Math.max(10, width - labelWidth - 6);
@@ -224,7 +259,7 @@ function buildActionRows(workspace: AgentWorkspace, width: number, height: numbe
     });
   }
   rows.push({
-    text: `  ${padDisplay(workspace.actionSearchActive ? 'Result' : 'Action', labelWidth)}  ${padDisplay('Does', commandWidth)}`,
+    text: `  ${padDisplay(workspace.actionSearchActive ? 'Result' : onboarding ? 'Option' : 'Action', labelWidth)}  ${padDisplay(onboarding ? 'Change' : 'Does', commandWidth)}`,
     fg: PALETTE.muted,
     bold: true,
   });
@@ -238,10 +273,11 @@ function buildActionRows(workspace: AgentWorkspace, width: number, height: numbe
     const action = actions[index]!;
     const selected = index === workspace.selectedActionIndex;
     const searchResult = workspace.actionSearchActive ? workspace.actionSearchResults[index] : null;
+    const actionCategory = searchResult?.category ?? category;
     const label = searchResult ? `${searchResult.category.label} / ${action.label}` : action.label;
     const marker = selected ? GLYPHS.navigation.selected : ' ';
     rows.push({
-      text: `${marker} ${padDisplay(label, labelWidth)}  ${padDisplay(actionCommand(action), commandWidth)}`,
+      text: `${marker} ${padDisplay(label, labelWidth)}  ${padDisplay(actionChange(workspace, actionCategory, action), commandWidth)}`,
       selected: selected && workspace.focusPane === 'actions',
       fg: action.safety === 'blocked' ? PALETTE.warn : selected ? PALETTE.text : PALETTE.info,
       bold: selected,
@@ -253,11 +289,11 @@ function buildActionRows(workspace: AgentWorkspace, width: number, height: numbe
   rows.push({ text: `Status: ${workspace.status}`, fg: PALETTE.muted });
   if (workspace.lastActionResult) {
     rows.push({ text: '' });
-    rows.push({ text: `Action Result: ${workspace.lastActionResult.title}`, fg: actionResultColor(workspace.lastActionResult), bold: true });
+    rows.push({ text: `${onboarding ? 'Result' : 'Action Result'}: ${workspace.lastActionResult.title}`, fg: actionResultColor(workspace.lastActionResult), bold: true });
     for (const line of wrapText(workspace.lastActionResult.detail, Math.max(1, width - 2))) {
       rows.push({ text: `  ${line}`, fg: PALETTE.text });
     }
-    if (workspace.lastActionResult.command) {
+    if (!onboarding && workspace.lastActionResult.command) {
       rows.push({ text: `  Command: ${workspace.lastActionResult.command}`, fg: PALETTE.muted });
     }
   }

package/src/runtime/tool-permission-safety.ts

@@ -67,7 +67,7 @@ const READ_ONLY_VIBE_ACTIONS = new Set(['', 'status', 'summary', 'list', 'show',
 const READ_ONLY_PERSONAL_OPS_ACTIONS = new Set(['', 'briefing', 'brief', 'daily', 'daily_brief', 'morning', 'status', 'summary', 'overview', 'map', 'list', 'queue', 'queues', 'review_queue', 'review_queues', 'personal_queue', 'ops_queue', 'intake', 'request', 'route', 'plan', 'triage', 'draft', 'lane', 'inspect', 'show']);
 const READ_ONLY_RESEARCH_ACTIONS = new Set(['', 'briefing', 'brief', 'status', 'dashboard', 'cockpit', 'next', 'plan', 'workflow', 'research', 'runner', 'browser', 'browser_runner', 'browser_backed', 'deep_research', 'runs', 'list_runs', 'run_list', 'run', 'show_run', 'inspect_run', 'sources', 'queue', 'source_queue', 'source', 'show_source', 'inspect_source', 'bundle', 'bundle_sources', 'source_bundle', 'search', 'public_search', 'collect', 'collect_sources', 'source_candidates', 'reports', 'list_reports', 'report_list', 'visual_reports', 'report_artifact', 'show_report', 'inspect_report', 'show_visual_report', 'visual_report_artifact']);
 const READ_ONLY_CHANNELS_ACTIONS = new Set(['', 'status', 'summary', 'list', 'readiness', 'channels', 'channel', 'show', 'inspect', 'setup', 'guide', 'setup_guide', 'channel_setup_guide', 'triage', 'inbox', 'blockers', 'retries', 'channel_triage', 'deliveries', 'delivery', 'receipts', 'history', 'channel_deliveries']);
-const READ_ONLY_MEMORY_ACTIONS = new Set(['', 'status', 'summary', 'posture', 'memory_posture', 'recall', 'providers', 'provider', 'memory_provider', 'embedding', 'external', 'external_provider', 'curator', 'learning', 'learning_curator', 'queue', 'review_queue', 'plan', 'candidate', 'learning_candidate', 'card', 'inspect_candidate', 'list', 'records', 'memories', 'search', 'find', 'lookup', 'get', 'show', 'inspect', 'read']);
+const READ_ONLY_MEMORY_ACTIONS = new Set(['', 'status', 'summary', 'posture', 'memory_posture', 'recall', 'providers', 'provider', 'memory_provider', 'embedding', 'external', 'external_provider', 'refinement', 'refinement_tasks', 'semantic_refinement', 'self_improvement', 'semantic_self_improvement', 'learning_loop', 'curator', 'learning', 'learning_curator', 'queue', 'review_queue', 'plan', 'candidate', 'learning_candidate', 'card', 'inspect_candidate', 'list', 'records', 'memories', 'search', 'find', 'lookup', 'get', 'show', 'inspect', 'read']);
 const READ_ONLY_COMPUTER_ACTIONS = new Set(['', 'status', 'summary', 'overview', 'computer', 'computer_use', 'plan', 'route', 'control_plan', 'browser_plan', 'desktop_plan', 'control', 'browser_control', 'desktop', 'desktop_control', 'screenshot', 'screen', 'screen_recording', 'observe', 'browser', 'pwa', 'cockpit', 'browser_cockpit', 'web', 'setup', 'configure', 'browser_desktop_control', 'mcp', 'tools', 'servers', 'mcp_servers']);
 const READ_ONLY_DEVICE_ACTIONS = new Set(['', 'status', 'map', 'capabilities', 'device', 'devices', 'mobile', 'phone', 'pairing', 'capability', 'route', 'pairing_route', 'show', 'inspect', 'browser', 'pwa', 'cockpit', 'browser_cockpit', 'web', 'control', 'browser_control', 'desktop', 'desktop_control', 'computer_use', 'voice', 'media', 'voice_media', 'workflows', 'provider', 'media_provider', 'voice_provider']);
 const READ_ONLY_MODELS_ACTIONS = new Set(['', 'status', 'routing', 'routes', 'models', 'model', 'readiness', 'route_readiness', 'route', 'model_route', 'inspect', 'show', 'candidate', 'endpoint', 'local', 'cookbook', 'local_cookbook', 'recipes', 'recipe', 'ollama', 'llama_cpp', 'llamacpp', 'vllm', 'local_servers', 'providers', 'provider_accounts', 'accounts', 'subscriptions', 'auth', 'logins', 'provider', 'provider_account', 'account', 'subscription', 'auth_status']);

package/src/tools/agent-harness-agent-orchestration-policy.ts

@@ -0,0 +1,75 @@
+export const AGENT_TOOL_MODES = [
+  'spawn',
+  'batch-spawn',
+  'list',
+  'templates',
+  'status',
+  'get',
+  'budget',
+  'plan',
+  'wait',
+  'message',
+  'cancel',
+  'wrfc-chains',
+  'wrfc-history',
+  'cohort-status',
+  'cohort-report',
+] as const;
+
+export const AGENT_TEMPLATES = ['orchestrator', 'engineer', 'reviewer', 'tester', 'researcher', 'integrator', 'general'] as const;
+
+export function agentOrchestrationDecisionCards(agentToolAvailable: boolean): readonly Record<string, unknown>[] {
+  return [
+    {
+      id: 'serial-by-default',
+      label: 'Stay serial by default',
+      status: 'ready',
+      chooseWhen: ['Ordinary chat, planning, research, setup, local context, and short current-workspace tool work.'],
+      route: 'main conversation',
+      reason: 'Lowest-friction route for the user when parallelism does not improve outcome.',
+    },
+    {
+      id: 'visible-single-agent',
+      label: 'Spawn one visible agent',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['A bounded autonomous task can run independently with visible status and cancellation.'],
+      requiredFields: ['task', 'successCriteria or requiredEvidence when outcome quality matters'],
+      modelRoute: 'agent { mode: "spawn" }',
+      inspectRoute: 'agent_harness mode:"agent_orchestration"',
+    },
+    {
+      id: 'visible-batch-spawn',
+      label: 'Batch-spawn independent agents',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['Tasks are genuinely independent and parallel work materially improves time-to-result.'],
+      doNotUseWhen: ['Review/test/verification role fanout for one deliverable; that collapses to one owner chain.'],
+      requiredFields: ['tasks[]', 'authoritativeTask for the original user ask when applicable'],
+      modelRoute: 'agent { mode: "batch-spawn" }',
+      inspectRoute: 'agent_harness mode:"agent_orchestration"',
+    },
+    {
+      id: 'managed-multi-runner-plan',
+      label: 'Use a managed multi-runner plan',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['A large task already has approval for parallel work and needs milestones, evidence, and cancellation routes.'],
+      requiredFields: ['original user ask', 'lane reason', 'success criteria', 'per-runner evidence', 'cancel/recovery route'],
+      modelRoute: 'agent_work_plan action:"dispatch_agents" ids:["..."] confirm:true explicitUserRequest:"..."',
+      inspectRoute: 'agent_harness mode:"agent_orchestration"',
+      policy: 'Read-only plan surface first; approved work-plan dispatch, spawn, message, wait, cancel, or remote mutation stays on confirmed first-class routes.',
+    },
+    {
+      id: 'inspect-or-control-visible-agent',
+      label: 'Inspect or control a visible agent',
+      status: agentToolAvailable ? 'ready' : 'unavailable',
+      chooseWhen: ['The user asks for progress, budget, plan, message, wait, cancel, WRFC chain, or cohort status.'],
+      modelRoutes: ['agent { mode: "list" }', 'agent { mode: "get" }', 'agent { mode: "message" }', 'agent { mode: "wait" }', 'agent { mode: "cancel" }'],
+    },
+    {
+      id: 'hidden-fanout-blocked',
+      label: 'Block hidden fanout',
+      status: 'blocked',
+      chooseWhen: ['A request implies invisible background agents, unmanaged parallel coding workers, or orphaned jobs.'],
+      saferRoutes: ['visible work plan', 'research run', 'confirmed schedule', 'agent { mode: "spawn" }', 'delegation action:"status"'],
+    },
+  ];
+}