@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/input/agent-workspace-setup-checkpoint-action.ts

@@ -0,0 +1,127 @@
+import { clearSetupWizardCheckpoint, readSetupWizardCheckpoint, saveSetupWizardCheckpoint } from '../agent/setup-wizard-checkpoint.ts';
+import type { CommandContext } from './command-registry.ts';
+import { buildAgentWorkspaceRuntimeSnapshot } from './agent-workspace-snapshot.ts';
+import type { AgentWorkspaceAction, AgentWorkspaceActionResult, AgentWorkspaceRuntimeSnapshot } from './agent-workspace-types.ts';
+
+interface AgentWorkspaceSetupCheckpointTarget {
+  readonly context: CommandContext | null;
+  readonly runtimeSnapshot: AgentWorkspaceRuntimeSnapshot | null;
+  readonly setRuntimeSnapshot: (snapshot: AgentWorkspaceRuntimeSnapshot | null) => void;
+  readonly setStatus: (status: string) => void;
+  readonly setLastActionResult: (result: AgentWorkspaceActionResult) => void;
+  readonly clampSelection: () => void;
+}
+
+export function applyAgentWorkspaceSetupCheckpointAction(
+  target: AgentWorkspaceSetupCheckpointTarget,
+  action: AgentWorkspaceAction,
+  requestRender?: () => void,
+): void {
+  const shellPaths = target.context?.workspace?.shellPaths;
+  if (!shellPaths || typeof shellPaths.resolveUserPath !== 'function') {
+    target.setStatus('Setup checkpoint storage is unavailable.');
+    target.setLastActionResult({
+      kind: 'error',
+      title: 'Setup checkpoint unavailable',
+      detail: 'The Agent workspace cannot locate Agent shell paths for setup checkpoint storage.',
+      safety: action.safety,
+    });
+    requestRender?.();
+    return;
+  }
+
+  const refreshSnapshot = (): void => {
+    target.setRuntimeSnapshot(target.context ? buildAgentWorkspaceRuntimeSnapshot(target.context) : target.runtimeSnapshot);
+    target.clampSelection();
+  };
+
+  try {
+    const operation = action.setupCheckpointOperation ?? 'show';
+    if (operation === 'show') {
+      const checkpoint = readSetupWizardCheckpoint(shellPaths);
+      const detail = checkpoint.checkpoint
+        ? `Saved setup checkpoint: ${checkpoint.checkpoint.currentStepLabel} (${checkpoint.checkpoint.currentStepId}) at ${checkpoint.checkpoint.savedAt}.`
+        : checkpoint.exists
+          ? `Saved setup checkpoint could not be read: ${checkpoint.parseError ?? 'invalid checkpoint file'}.`
+          : 'No setup wizard checkpoint is saved yet.';
+      target.setStatus(checkpoint.checkpoint ? 'Setup checkpoint loaded.' : 'No setup checkpoint saved.');
+      target.setLastActionResult({
+        kind: checkpoint.exists && !checkpoint.checkpoint ? 'error' : 'guidance',
+        title: 'Setup checkpoint',
+        detail,
+        safety: action.safety,
+      });
+      requestRender?.();
+      return;
+    }
+
+    if (operation === 'clear') {
+      const before = readSetupWizardCheckpoint(shellPaths);
+      const checkpoint = clearSetupWizardCheckpoint(shellPaths);
+      refreshSnapshot();
+      target.setStatus(before.exists ? 'Setup checkpoint cleared.' : 'No setup checkpoint was saved.');
+      target.setLastActionResult({
+        kind: 'refreshed',
+        title: 'Setup checkpoint cleared',
+        detail: before.exists
+          ? `Cleared the Agent-owned setup wizard checkpoint at ${checkpoint.path}.`
+          : `No Agent-owned setup wizard checkpoint existed at ${checkpoint.path}.`,
+        safety: action.safety,
+      });
+      requestRender?.();
+      return;
+    }
+
+    const wizard = target.runtimeSnapshot?.setupWizard;
+    const current = wizard?.currentStepId
+      ? wizard.steps.find((step) => step.id === wizard.currentStepId) ?? null
+      : null;
+    if (!current) {
+      target.setStatus('No current setup wizard step to save.');
+      target.setLastActionResult({
+        kind: 'guidance',
+        title: 'Setup checkpoint not saved',
+        detail: 'The setup wizard is complete or unavailable, so there is no current step to resume.',
+        safety: action.safety,
+      });
+      requestRender?.();
+      return;
+    }
+    if (current.sourceStatus === 'ready') {
+      target.setStatus('Setup checkpoint not saved.');
+      target.setLastActionResult({
+        kind: 'guidance',
+        title: 'Setup checkpoint not saved',
+        detail: `${current.label} is already ready; use the next live setup step instead.`,
+        safety: action.safety,
+      });
+      requestRender?.();
+      return;
+    }
+    const checkpoint = saveSetupWizardCheckpoint(shellPaths, {
+      currentStepId: current.id,
+      currentStepLabel: current.label,
+      source: 'workspace',
+      note: 'User-selected setup wizard checkpoint.',
+    });
+    refreshSnapshot();
+    target.setStatus(`Saved setup checkpoint for ${current.label}.`);
+    target.setLastActionResult({
+      kind: 'refreshed',
+      title: 'Setup checkpoint saved',
+      detail: `Saved ${current.label} (${current.id}) as the Agent-owned setup resume point at ${checkpoint.path}.`,
+      safety: action.safety,
+    });
+    requestRender?.();
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    target.setStatus('Setup checkpoint action failed.');
+    target.setLastActionResult({
+      kind: 'error',
+      title: 'Setup checkpoint action failed',
+      detail,
+      safety: action.safety,
+    });
+    requestRender?.();
+  }
+}

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

@@ -0,0 +1,217 @@
+import type { ArtifactDescriptor } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { CommandContext } from './command-registry.ts';
+import { readSetupWizardCheckpoint } from '../agent/setup-wizard-checkpoint.ts';
+import { readOnboardingCompletionMarker } from '../runtime/onboarding/index.ts';
+import { DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE, DEFAULT_AGENT_SETUP_WIZARD_SAVE_SMOKE_ROUTE, buildAgentSetupWizard, emptyAgentSetupSmokeHistory, emptyAgentSetupWizardCheckpoint, type AgentSetupWizard, type AgentSetupWizardBlockedCheckFrequency, type AgentSetupWizardCheckpoint, type AgentSetupWizardDurableReceipt, type AgentSetupWizardSmokeHistory, type AgentSetupWizardSourceItem } from '../agent/setup-wizard.ts';
+import type { AgentWorkspaceSetupChecklistItem } from './agent-workspace-setup.ts';
+import { readArtifactMetadataString, readArtifactMetadataStringList } from './agent-workspace-artifact-metadata.ts';
+
+function isSetupSmokeEvidenceArtifact(artifact: ArtifactDescriptor): boolean {
+  return readArtifactMetadataString(artifact.metadata, 'purpose') === 'agent-setup-smoke-evidence';
+}
+
+function setupSmokeEvidenceScore(artifact: ArtifactDescriptor): number {
+  const result = readArtifactMetadataString(artifact.metadata, 'result');
+  if (result === 'ready-for-user-run') return 2;
+  if (result === 'blocked') return 0;
+  return 1;
+}
+
+function setupSmokeEvidenceTrend(artifacts: readonly ArtifactDescriptor[]): string {
+  if (artifacts.length === 0) return 'none';
+  if (artifacts.length === 1) return 'first-run';
+  const latest = setupSmokeEvidenceScore(artifacts[0]!);
+  const previous = setupSmokeEvidenceScore(artifacts[1]!);
+  if (latest > previous) return 'improving';
+  if (latest < previous) return 'regressing';
+  const result = readArtifactMetadataString(artifacts[0]!.metadata, 'result');
+  if (result === 'ready-for-user-run') return 'unchanged-ready';
+  if (result === 'blocked') return 'unchanged-blocked';
+  return 'unchanged';
+}
+
+function artifactCreatedAtIso(artifact: ArtifactDescriptor): string | null {
+  const createdAt = artifact.createdAt;
+  if (typeof createdAt !== 'number' || !Number.isFinite(createdAt)) return null;
+  return new Date(createdAt).toISOString();
+}
+
+function setupSmokeBlockedCheckFrequency(artifacts: readonly ArtifactDescriptor[]): readonly AgentSetupWizardBlockedCheckFrequency[] {
+  const counts = new Map<string, number>();
+  for (const artifact of artifacts) {
+    for (const checkId of readArtifactMetadataStringList(artifact.metadata, 'blockedChecks')) {
+      counts.set(checkId, (counts.get(checkId) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+    .slice(0, 8)
+    .map(([checkId, count]) => ({ checkId, count }));
+}
+
+export function buildSetupSmokeHistory(artifacts: readonly ArtifactDescriptor[], artifactListAvailable: boolean): AgentSetupWizardSmokeHistory {
+  if (!artifactListAvailable) {
+    return {
+      ...emptyAgentSetupSmokeHistory('Artifact list support is unavailable in this runtime.'),
+      status: 'unavailable',
+    };
+  }
+  const setupSmokeArtifacts = artifacts
+    .filter(isSetupSmokeEvidenceArtifact)
+    .sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0));
+  if (setupSmokeArtifacts.length === 0) return emptyAgentSetupSmokeHistory();
+  const resultCounts = setupSmokeArtifacts.reduce<Record<string, number>>((counts, artifact) => {
+    const result = readArtifactMetadataString(artifact.metadata, 'result') || 'unknown';
+    counts[result] = (counts[result] ?? 0) + 1;
+    return counts;
+  }, {});
+  const latest = setupSmokeArtifacts[0]!;
+  const previous = setupSmokeArtifacts[1] ?? null;
+  return {
+    status: 'available',
+    total: setupSmokeArtifacts.length,
+    trend: setupSmokeEvidenceTrend(setupSmokeArtifacts),
+    latestResult: readArtifactMetadataString(latest.metadata, 'result') || 'unknown',
+    previousResult: previous ? readArtifactMetadataString(previous.metadata, 'result') || 'unknown' : null,
+    latestEvidenceId: latest.id,
+    latestEvidenceAt: artifactCreatedAtIso(latest),
+    resultCounts,
+    blockedCheckFrequency: setupSmokeBlockedCheckFrequency(setupSmokeArtifacts),
+    inspectLatestRoute: `agent_artifacts show artifactId:"${latest.id}" includeContent:false`,
+    rerunRoute: DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE,
+    saveRoute: DEFAULT_AGENT_SETUP_WIZARD_SAVE_SMOKE_ROUTE,
+  };
+}
+
+export function buildSetupWizardCheckpoint(context: CommandContext): AgentSetupWizardCheckpoint {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths || typeof shellPaths.resolveUserPath !== 'function') {
+    return {
+      ...emptyAgentSetupWizardCheckpoint('Agent shell paths are unavailable; setup wizard checkpoint storage cannot be inspected.'),
+      status: 'unavailable',
+    };
+  }
+  const snapshot = readSetupWizardCheckpoint(shellPaths);
+  const routes = {
+    markCurrentRoute: DEFAULT_AGENT_SETUP_WIZARD_MARK_CHECKPOINT_ROUTE,
+    clearRoute: DEFAULT_AGENT_SETUP_WIZARD_CLEAR_CHECKPOINT_ROUTE,
+    inspectRoute: DEFAULT_AGENT_SETUP_WIZARD_INSPECT_CHECKPOINT_ROUTE,
+  };
+  if (!snapshot.exists) {
+    return {
+      ...emptyAgentSetupWizardCheckpoint(),
+      ...routes,
+      path: snapshot.path,
+    };
+  }
+  if (!snapshot.checkpoint) {
+    return {
+      ...emptyAgentSetupWizardCheckpoint(snapshot.parseError ?? 'Saved setup wizard checkpoint could not be read.'),
+      ...routes,
+      status: 'unavailable',
+      path: snapshot.path,
+      ...(snapshot.parseError ? { parseError: snapshot.parseError } : {}),
+    };
+  }
+  return {
+    status: 'available',
+    currentStepId: snapshot.checkpoint.currentStepId,
+    currentStepLabel: snapshot.checkpoint.currentStepLabel,
+    savedAt: snapshot.checkpoint.savedAt,
+    source: snapshot.checkpoint.source,
+    resumed: false,
+    summary: `Saved setup checkpoint for ${snapshot.checkpoint.currentStepLabel}.`,
+    path: snapshot.path,
+    ...(snapshot.checkpoint.note ? { note: snapshot.checkpoint.note } : {}),
+    ...routes,
+  };
+}
+
+function setupChecklistUserRoute(item: AgentWorkspaceSetupChecklistItem): string {
+  return item.command ?? 'Start';
+}
+
+function setupChecklistModelRoute(item: AgentWorkspaceSetupChecklistItem): string {
+  if (item.id === 'runtime') return 'agent_harness mode:"setup_item" setupItemId:"connected-host-readiness"';
+  if (item.id === 'provider-model') return 'models action:"status"';
+  if (item.id === 'install-smoke') return DEFAULT_AGENT_SETUP_WIZARD_RERUN_SMOKE_ROUTE;
+  if (item.id === 'subscriptions') return 'models action:"providers"';
+  if (item.id === 'agent-knowledge') return 'agent_knowledge mode:"status"';
+  if (item.id === 'profile') return 'agent_harness mode:"workspace_action" actionId:"profile-template-show"';
+  if (item.id === 'persona') return 'agent_harness mode:"workspace" target:"personas"';
+  if (item.id === 'skills') return 'agent_harness mode:"workspace" target:"skills"';
+  if (item.id === 'routines') return 'agent_harness mode:"workspace" target:"routines"';
+  if (item.id === 'memory') return 'memory action:"status"';
+  if (item.id === 'notes') return 'personal_ops action:"lane" laneId:"notes"';
+  if (item.id === 'channels') return 'channels action:"status"';
+  if (item.id === 'browser-pwa') return 'computer action:"browser" includeParameters:true';
+  if (item.id === 'voice-media') return 'device action:"voice"';
+  return `agent_harness mode:"setup_item" setupItemId:"${item.id}"`;
+}
+
+function setupChecklistActionId(item: AgentWorkspaceSetupChecklistItem): string {
+  if (item.id === 'provider-model') return 'setup-provider-model';
+  if (item.id === 'subscriptions') return 'subscription-login-start';
+  if (item.id === 'agent-knowledge') return 'knowledge-status';
+  if (item.id === 'profile') return 'profile-template-show';
+  if (item.id === 'persona') return 'persona-search';
+  if (item.id === 'skills') return 'skill-search';
+  if (item.id === 'routines') return 'routine-search';
+  if (item.id === 'channels') return 'channel-show';
+  if (item.id === 'browser-pwa') return 'browser-cockpit-readiness';
+  if (item.id === 'voice-media') return 'voice-enable';
+  return item.id;
+}
+
+const SETUP_WIZARD_SNAPSHOT_BLOCKER_ALIASES: Readonly<Record<string, readonly string[]>> = {
+  'agent-binary': ['runtime', 'install-smoke'],
+  'connected-host-status': ['runtime'],
+  'connected-host-auth': ['connected-host-auth'],
+  'provider-model': ['provider-model'],
+  'setup-posture': ['install-smoke'],
+  'first-assistant-turn': ['install-smoke'],
+};
+
+export function buildWorkspaceSetupWizard(
+  checklist: readonly AgentWorkspaceSetupChecklistItem[],
+  smokeHistory: AgentSetupWizardSmokeHistory,
+  checkpoint: AgentSetupWizardCheckpoint,
+  setupMarkerExists: boolean,
+  durableReceipts: readonly AgentSetupWizardDurableReceipt[] = [],
+): AgentSetupWizard {
+  const browserPwaNeedsReceipt = checklist.some((item) => item.id === 'browser-pwa' && item.status !== 'ready');
+  const items: AgentSetupWizardSourceItem[] = checklist.map((item) => ({
+    id: item.id,
+    label: item.label,
+    status: item.status,
+    detail: item.detail,
+    userRoute: setupChecklistUserRoute(item),
+    modelRoute: setupChecklistModelRoute(item),
+    actionId: setupChecklistActionId(item),
+  }));
+  return buildAgentSetupWizard({
+    items,
+    smokeHistory,
+    checkpoint,
+    closeoutCriticalStepIds: ['runtime', 'connected-host-auth', 'provider-model'],
+    receiptRequiredStepIds: [
+      'runtime',
+      'connected-host-auth',
+      'install-smoke',
+      ...(browserPwaNeedsReceipt ? ['browser-pwa'] : []),
+    ],
+    durableReceipts,
+    setupMarkerExists,
+    repeatedBlockerAliases: SETUP_WIZARD_SNAPSHOT_BLOCKER_ALIASES,
+  });
+}
+
+export function setupCompletionMarkerExists(context: CommandContext): boolean {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths || typeof shellPaths.resolveUserPath !== 'function') return false;
+  try {
+    return readOnboardingCompletionMarker(shellPaths, 'user').exists;
+  } catch {
+    return false;
+  }
+}

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

@@ -14,6 +14,11 @@ export interface AgentWorkspaceSetupChecklistInput {
   readonly provider: string;
   readonly model: string;
   readonly runtimeBaseUrl: string;
+  readonly connectedHostTokenPresent: boolean;
+  readonly connectedHostTokenReadable: boolean;
+  readonly connectedHostTokenPath: string;
+  readonly connectedHostTokenError?: string | null;
+  readonly connectedHostAuthReceiptReady?: boolean;
   readonly activeSubscriptionCount: number;
   readonly pendingSubscriptionCount: number;
   readonly availableSubscriptionProviderCount: number;
@@ -37,6 +42,10 @@ export interface AgentWorkspaceSetupChecklistInput {
   readonly readyChannelCount: number;
   readonly voiceProviderCount: number;
   readonly mediaProviderCount: number;
+  readonly installSmokeReceiptReady?: boolean;
+  readonly browserPwaEnabled: boolean;
+  readonly browserPwaPublicBaseUrl: string;
+  readonly browserPwaFirstRunReceiptStatus: 'published' | 'not-published';
   readonly runtimeProfileCount: number;
   readonly runtimeStarterTemplateCount: number;
 }
@@ -53,16 +62,43 @@ function sampleNames(summary: AgentBehaviorDiscoverySummary): string {
 
 export function buildAgentWorkspaceSetupChecklist(input: AgentWorkspaceSetupChecklistInput): readonly AgentWorkspaceSetupChecklistItem[] {
   const providerReady = input.provider !== 'unknown' && input.model !== 'unknown';
+  const tokenPathKnown = input.connectedHostTokenPath !== '(Agent home unavailable)';
+  const connectedHostAuthReceiptReady = input.connectedHostAuthReceiptReady === true;
+  const connectedHostAuthStatus: AgentWorkspaceSetupStatus = input.connectedHostTokenReadable || connectedHostAuthReceiptReady
+    ? 'ready'
+    : tokenPathKnown
+      ? 'blocked'
+      : 'recommended';
+  const installSmokePrerequisitesReady = providerReady && (input.connectedHostTokenReadable || connectedHostAuthReceiptReady);
+  const installSmokeReceiptReady = input.installSmokeReceiptReady === true;
   const hasActivePersona = input.activePersonaName !== '(none)' && input.activePersonaName !== '(unavailable)';
   const discoveredBehaviorCount = input.discoveredPersonas.count + input.discoveredSkills.count + input.discoveredRoutines.count;
+  const browserPwaUrl = input.browserPwaPublicBaseUrl.trim();
+  const browserPwaHasPublicUrl = browserPwaUrl.length > 0 && browserPwaUrl !== '(not configured)';
+  const browserPwaReceiptPublished = input.browserPwaFirstRunReceiptStatus === 'published';
   return [
     {
       id: 'runtime',
       label: 'Connected host',
       status: 'ready',
-      detail: `Agent will connect to ${input.runtimeBaseUrl}; connected-host ownership stays outside this product.`,
+      detail: `Agent will connect to ${input.runtimeBaseUrl}; protected host routes also need the Agent companion token below.`,
       command: 'Home -> Review health',
     },
+    {
+      id: 'connected-host-auth',
+      label: 'Connected-host auth',
+      status: connectedHostAuthStatus,
+      detail: connectedHostAuthReceiptReady
+        ? `Durable connected-host auth receipt is ready${input.connectedHostTokenReadable ? ` and Agent has a readable operator token at ${input.connectedHostTokenPath}` : ''}.`
+        : input.connectedHostTokenReadable
+        ? `Agent has a readable connected-host operator token at ${input.connectedHostTokenPath}.`
+        : input.connectedHostTokenError
+          ? `The connected-host operator token exists but cannot be read at ${input.connectedHostTokenPath}. Use the confirmed setup token provisioning route, then rerun auth review.`
+          : tokenPathKnown
+            ? `Provision Agent's local connected-host operator token at ${input.connectedHostTokenPath} before pairing channels, Knowledge, schedules, or protected daemon routes.`
+            : 'Shell paths are unavailable in this runtime, so connected-host auth cannot be verified from the workspace snapshot.',
+      command: 'Host -> Connected-host auth owner',
+    },
     {
       id: 'provider-model',
       label: 'Provider and model',
@@ -72,6 +108,17 @@ export function buildAgentWorkspaceSetupChecklist(input: AgentWorkspaceSetupChec
         : 'Choose a provider and model before relying on assistant turns.',
       command: 'Setup -> Provider and model',
     },
+    {
+      id: 'install-smoke',
+      label: 'Install smoke',
+      status: installSmokeReceiptReady ? 'ready' : installSmokePrerequisitesReady ? 'recommended' : tokenPathKnown ? 'blocked' : 'recommended',
+      detail: installSmokeReceiptReady
+        ? 'Durable setup smoke receipt is ready for release closeout; rerun smoke only after install, host, auth, or model changes.'
+        : installSmokePrerequisitesReady
+        ? 'Run setup smoke after install or migration to prove package start, connected host, auth, model route, setup posture, and first assistant turn.'
+        : 'Resolve connected-host auth and provider/model setup before treating the first assistant turn as install-ready.',
+      command: 'Start -> Install smoke',
+    },
     {
       id: 'subscriptions',
       label: 'Provider subscriptions',
@@ -175,6 +222,19 @@ export function buildAgentWorkspaceSetupChecklist(input: AgentWorkspaceSetupChec
         : 'Pair or review channels only when you want the assistant reachable outside this terminal.',
       command: 'Channels',
     },
+    {
+      id: 'browser-pwa',
+      label: 'Browser/PWA',
+      status: browserPwaReceiptPublished ? 'ready' : 'recommended',
+      detail: browserPwaReceiptPublished
+        ? `Connected-host browser/PWA first-run receipt is published${browserPwaHasPublicUrl ? ` for ${browserPwaUrl}` : ''}.`
+        : input.browserPwaEnabled
+          ? browserPwaHasPublicUrl
+            ? `Browser cockpit is openable at ${browserPwaUrl}, but the connected-host browser/PWA first-run completion receipt is not published yet. Terminal Agent remains primary until that receipt exists.`
+            : 'Browser cockpit is enabled through the connected-host web endpoint, but the connected-host browser/PWA first-run completion receipt is not published yet.'
+          : 'Enable the connected-host web endpoint and publish the browser/PWA first-run completion receipt before treating browser access as setup-ready.',
+      command: 'Voice & Media -> Browser/PWA readiness',
+    },
     {
       id: 'voice-media',
       label: 'Voice and media',