agentic-orchestrator 0.1.28 → 0.2.1

package/packages/web-dashboard/src/lib/focus-view.ts

@@ -0,0 +1,300 @@
+import type { FeatureDetail } from '@/lib/types.js';
+
+export type FocusTabId =
+  | 'overview'
+  | 'intake'
+  | 'planning'
+  | 'changes'
+  | 'gates_qa'
+  | 'review'
+  | 'conflicts'
+  | 'runtime'
+  | 'history'
+  | 'transcript';
+
+export type FocusLazyGroup = 'review_qa' | 'runtime' | 'history_log' | null;
+export type ActivatedFocusLazyGroup = Exclude<FocusLazyGroup, null>;
+
+export interface FocusTabDefinition {
+  id: FocusTabId;
+  label: string;
+  lazyGroup: FocusLazyGroup;
+  visible: boolean;
+}
+
+export interface FocusPinnedAction {
+  id: 'review' | 'human_input';
+  label: string;
+  targetTab: FocusTabId;
+}
+
+const TAB_ORDER: FocusTabId[] = [
+  'overview',
+  'intake',
+  'planning',
+  'changes',
+  'gates_qa',
+  'review',
+  'conflicts',
+  'runtime',
+  'history',
+  'transcript',
+];
+
+function hasDetail(detail: FeatureDetail | null): detail is FeatureDetail {
+  return detail !== null;
+}
+
+function isReviewPhase(detail: FeatureDetail): boolean {
+  return detail.feature.phase === 'qa' || detail.feature.phase === 'ready_to_merge';
+}
+
+function hasDiff(detail: FeatureDetail): boolean {
+  return detail.diff.trim().length > 0;
+}
+
+function hasGateOrQa(detail: FeatureDetail): boolean {
+  return Boolean(detail.gate_evidence) || Boolean(detail.qa_test_index);
+}
+
+function waitingForInput(detail: FeatureDetail): boolean {
+  return (
+    detail.feature.activity_state === 'waiting_input' ||
+    (detail.feature.waiting_input_count ?? 0) > 0
+  );
+}
+
+function showIntakeTab(detail: FeatureDetail): boolean {
+  return (
+    detail.feature.phase === 'intake' ||
+    (detail.feature.phase === 'awaiting_input' && detail.feature.resume_status === 'intake') ||
+    detail.intake != null ||
+    (detail.questions ?? []).some(
+      (question) =>
+        question.status === 'open' &&
+        (question.resume_status === 'intake' ||
+          question.resume_phase === 'intake' ||
+          question.phase === 'intake'),
+    )
+  );
+}
+
+function showPlanningTab(detail: FeatureDetail): boolean {
+  const verifiedManifestVersion =
+    detail.feature.verified_manifest_version ??
+    detail.intake?.summary.verified_manifest_version ??
+    null;
+
+  return (
+    detail.feature.phase === 'intake' ||
+    (detail.feature.phase === 'awaiting_input' && detail.feature.resume_status === 'intake') ||
+    detail.feature.phase === 'planning' ||
+    detail.feature.phase === 'building' ||
+    detail.feature.phase === 'qa' ||
+    detail.feature.phase === 'ready_to_merge' ||
+    detail.feature.phase === 'merged' ||
+    detail.intake != null ||
+    detail.plan != null ||
+    verifiedManifestVersion != null
+  );
+}
+
+export function getFocusLazyGroup(tabId: FocusTabId): FocusLazyGroup {
+  if (tabId === 'gates_qa' || tabId === 'review' || tabId === 'conflicts') {
+    return 'review_qa';
+  }
+  if (tabId === 'runtime') {
+    return 'runtime';
+  }
+  if (tabId === 'history' || tabId === 'transcript') {
+    return 'history_log';
+  }
+  return null;
+}
+
+export function isFocusTabLazy(tabId: FocusTabId): boolean {
+  return getFocusLazyGroup(tabId) !== null;
+}
+
+export function getVisibleFocusTabs(detail: FeatureDetail | null): FocusTabDefinition[] {
+  if (!hasDetail(detail)) {
+    return [
+      {
+        id: 'overview',
+        label: 'Overview',
+        lazyGroup: null,
+        visible: true,
+      },
+    ];
+  }
+
+  const reviewVisible = isReviewPhase(detail) || hasDiff(detail) || Boolean(detail.review_brief);
+  const gatesVisible = isReviewPhase(detail) || hasGateOrQa(detail);
+  const changesVisible = hasDiff(detail) || (detail.checkpoints?.length ?? 0) > 0;
+
+  const conflictsVisible =
+    detail.conflict_summary != null && detail.conflict_summary.resolution_status !== 'resolved';
+
+  const labels: Record<FocusTabId, string> = {
+    overview: 'Overview',
+    intake: 'Intake',
+    planning: 'Plan',
+    changes: 'Changes',
+    gates_qa: 'Gates & QA',
+    review: 'Review',
+    conflicts: 'Conflicts',
+    runtime: 'Runtime',
+    history: 'History',
+    transcript: 'Transcript',
+  };
+
+  return TAB_ORDER.map((id) => ({
+    id,
+    label: labels[id],
+    lazyGroup: getFocusLazyGroup(id),
+    visible:
+      id === 'overview' ||
+      (id === 'intake' && showIntakeTab(detail)) ||
+      (id === 'planning' && showPlanningTab(detail)) ||
+      id === 'runtime' ||
+      id === 'history' ||
+      id === 'transcript' ||
+      (id === 'changes' && changesVisible) ||
+      (id === 'gates_qa' && gatesVisible) ||
+      (id === 'review' && reviewVisible) ||
+      (id === 'conflicts' && conflictsVisible),
+  })).filter((tab) => tab.visible);
+}
+
+export function getDefaultFocusTab(detail: FeatureDetail | null): FocusTabId {
+  if (!detail) {
+    return 'overview';
+  }
+
+  if (waitingForInput(detail) && detail.feature.resume_status === 'intake') {
+    return 'intake';
+  }
+
+  if (waitingForInput(detail) && detail.feature.resume_status === 'planning') {
+    return 'planning';
+  }
+
+  if (waitingForInput(detail)) {
+    return 'overview';
+  }
+
+  const phase = detail.feature.phase ?? 'unknown';
+  if (phase === 'intake') {
+    return 'intake';
+  }
+  if (phase === 'planning') {
+    return 'planning';
+  }
+  if (phase === 'building') {
+    return hasDiff(detail) ? 'changes' : 'overview';
+  }
+  if (phase === 'qa') {
+    return 'gates_qa';
+  }
+  if (phase === 'ready_to_merge') {
+    return 'review';
+  }
+  if (
+    phase === 'blocked' &&
+    detail.conflict_summary != null &&
+    detail.conflict_summary.resolution_status !== 'resolved'
+  ) {
+    return 'conflicts';
+  }
+  if (phase === 'blocked') {
+    return 'overview';
+  }
+  if (phase === 'merged') {
+    return 'history';
+  }
+  return 'overview';
+}
+
+export function getPinnedFocusActions(detail: FeatureDetail | null): FocusPinnedAction[] {
+  if (!detail) {
+    return [];
+  }
+
+  if (waitingForInput(detail)) {
+    const targetTab: FocusTabId =
+      detail.feature.resume_status === 'intake'
+        ? 'intake'
+        : detail.feature.resume_status === 'planning'
+          ? 'planning'
+          : isReviewPhase(detail)
+            ? 'review'
+            : 'overview';
+    return [
+      {
+        id: 'human_input',
+        label: 'Answer required',
+        targetTab,
+      },
+    ];
+  }
+
+  if (isReviewPhase(detail)) {
+    return [
+      {
+        id: 'review',
+        label: detail.feature.phase === 'ready_to_merge' ? 'Review decision' : 'Review workspace',
+        targetTab: 'review',
+      },
+    ];
+  }
+
+  return [];
+}
+
+export function isFocusTabVisible(detail: FeatureDetail | null, tabId: FocusTabId): boolean {
+  return getVisibleFocusTabs(detail).some((tab) => tab.id === tabId);
+}
+
+export function coerceFocusTab(
+  detail: FeatureDetail | null,
+  requestedTab: FocusTabId | null | undefined,
+): FocusTabId {
+  if (requestedTab && isFocusTabVisible(detail, requestedTab)) {
+    return requestedTab;
+  }
+  return getDefaultFocusTab(detail);
+}
+
+export function resolveFocusActiveTab(
+  detail: FeatureDetail | null,
+  activeTab: FocusTabId,
+  initialTab: FocusTabId | undefined,
+  hasUserSelectedTab: boolean,
+): FocusTabId {
+  const requestedTab = hasUserSelectedTab ? activeTab : (initialTab ?? getDefaultFocusTab(detail));
+  return coerceFocusTab(detail, requestedTab);
+}
+
+export function getNextActivatedLazyGroups(
+  current: readonly ActivatedFocusLazyGroup[],
+  tabId: FocusTabId,
+): ActivatedFocusLazyGroup[] {
+  const group = getFocusLazyGroup(tabId);
+  if (group === null || current.includes(group)) {
+    return [...current];
+  }
+  return [...current, group];
+}
+
+export function shouldMountFocusTab(
+  tabId: FocusTabId,
+  activeTab: FocusTabId,
+  activatedGroups: readonly ActivatedFocusLazyGroup[],
+): boolean {
+  if (tabId === activeTab) {
+    return true;
+  }
+
+  const group = getFocusLazyGroup(tabId);
+  return group !== null && activatedGroups.includes(group);
+}

package/packages/web-dashboard/src/lib/health-diagnosis.ts

@@ -0,0 +1,356 @@
+import type {
+  FeatureDetail,
+  FeatureSummary,
+  GateRunEvidence,
+  GateStepResult,
+} from '@/lib/types.js';
+
+export const STALL_THRESHOLD_MS = 20 * 60_000;
+
+export type HealthSeverity = 'healthy' | 'waiting' | 'stalled' | 'degraded' | 'blocked';
+
+export type HealthCauseCode =
+  | 'DEPENDENCY_BLOCKED'
+  | 'FEATURE_RECOVERING'
+  | 'FEATURE_BLOCKED'
+  | 'GATE_FAILED'
+  | 'AGENT_EXITED'
+  | 'OPEN_REVIEW_THREADS'
+  | 'WAITING_INPUT'
+  | 'ACTIVITY_STALLED';
+
+export interface HealthCauseMetadata {
+  command?: string;
+  dependencies?: string[];
+  exitCode?: number | null;
+  lastMeaningfulChangeAt?: string;
+  outputTail?: string[];
+  recoveryAttempt?: number | null;
+  recoveryCause?: string | null;
+  recoveryRole?: string | null;
+  reviewThreads?: number;
+  stepName?: string;
+}
+
+export interface HealthDiagnosisCause {
+  code: HealthCauseCode;
+  severity: Exclude<HealthSeverity, 'healthy'>;
+  title: string;
+  detail: string;
+  metadata?: HealthCauseMetadata;
+}
+
+export interface HealthDiagnosis {
+  severity: HealthSeverity;
+  summary: string;
+  primary: HealthDiagnosisCause | null;
+  secondary: HealthDiagnosisCause[];
+}
+
+interface DeriveHealthDiagnosisInput {
+  detail: FeatureDetail | null;
+  nowMs?: number;
+  unresolvedDependencies?: string[];
+}
+
+const ACTIVE_PHASES = new Set(['planning', 'building', 'qa', 'ready_to_merge']);
+const SEVERITY_RANK: Record<Exclude<HealthSeverity, 'healthy'>, number> = {
+  blocked: 4,
+  degraded: 3,
+  stalled: 2,
+  waiting: 1,
+};
+const CAUSE_PRIORITY: Record<HealthCauseCode, number> = {
+  DEPENDENCY_BLOCKED: 8,
+  FEATURE_BLOCKED: 7,
+  FEATURE_RECOVERING: 6,
+  GATE_FAILED: 5,
+  AGENT_EXITED: 4,
+  OPEN_REVIEW_THREADS: 3,
+  ACTIVITY_STALLED: 2,
+  WAITING_INPUT: 1,
+};
+
+function isFeatureRecovering(feature: FeatureSummary): boolean {
+  if (!feature.recovery || feature.recovery.state !== 'retrying') {
+    return false;
+  }
+  if (feature.phase === 'merged' || feature.phase === 'ready_to_merge') {
+    return false;
+  }
+  const cause = feature.recovery.cause?.trim().toLowerCase();
+  if (!cause) {
+    return true;
+  }
+  if (feature.phase !== 'blocked') {
+    return true;
+  }
+  return feature.status_reason?.trim().toLowerCase().startsWith(`${cause}:`) ?? false;
+}
+
+function isWaitingForInput(feature: FeatureSummary): boolean {
+  return feature.activity_state === 'waiting_input' || (feature.waiting_input_count ?? 0) > 0;
+}
+
+function lastActivityTimestamp(feature: FeatureSummary): string | undefined {
+  return (
+    feature.last_meaningful_change_at ?? feature.activity_last_event_at ?? feature.last_updated
+  );
+}
+
+function isActivityStalled(feature: FeatureSummary, nowMs: number): boolean {
+  if (!ACTIVE_PHASES.has(feature.phase ?? 'unknown')) {
+    return false;
+  }
+  if (
+    feature.activity_state === 'waiting_input' ||
+    feature.activity_state === 'blocked' ||
+    feature.activity_state === 'exited'
+  ) {
+    return false;
+  }
+
+  const timestamp = lastActivityTimestamp(feature);
+  if (!timestamp) {
+    return false;
+  }
+
+  const parsed = Date.parse(timestamp);
+  if (Number.isNaN(parsed) || parsed > nowMs) {
+    return false;
+  }
+
+  return nowMs - parsed >= STALL_THRESHOLD_MS;
+}
+
+function summarizeGateFailure(step: GateStepResult): HealthDiagnosisCause {
+  const outputTail = step.output_tail?.filter((line) => line.trim().length > 0) ?? [];
+  const lastLine = outputTail.at(-1);
+  const fallback =
+    typeof step.exit_code === 'number'
+      ? `Exit code ${step.exit_code} from ${step.command || step.name}.`
+      : `Command ${step.command || step.name || 'unknown'} failed.`;
+
+  return {
+    code: 'GATE_FAILED',
+    severity: 'degraded',
+    title: `Gate failed: ${step.name || 'unknown step'}`,
+    detail: lastLine ?? fallback,
+    metadata: {
+      command: step.command,
+      exitCode: step.exit_code,
+      outputTail,
+      stepName: step.name,
+    },
+  };
+}
+
+function gateFailureCause(
+  evidence: GateRunEvidence | null | undefined,
+): HealthDiagnosisCause | null {
+  if (!evidence) {
+    return null;
+  }
+
+  const failedStep = evidence.steps.find((step) => step.status === 'fail');
+  if (failedStep) {
+    return summarizeGateFailure(failedStep);
+  }
+
+  if (evidence.overall === 'fail') {
+    return {
+      code: 'GATE_FAILED',
+      severity: 'degraded',
+      title: 'Gate failed',
+      detail: `Gate profile ${evidence.profile ?? 'unknown'} failed in ${evidence.mode} mode.`,
+      metadata: {
+        outputTail: [],
+      },
+    };
+  }
+
+  return null;
+}
+
+function dependencyCause(unresolvedDependencies: string[]): HealthDiagnosisCause | null {
+  if (unresolvedDependencies.length === 0) {
+    return null;
+  }
+
+  return {
+    code: 'DEPENDENCY_BLOCKED',
+    severity: 'blocked',
+    title: 'Waiting on dependencies',
+    detail: `Blocked by ${unresolvedDependencies.join(', ')}.`,
+    metadata: {
+      dependencies: unresolvedDependencies,
+    },
+  };
+}
+
+function blockedCause(feature: FeatureSummary): HealthDiagnosisCause | null {
+  if (isFeatureRecovering(feature)) {
+    return null;
+  }
+  if (feature.phase !== 'blocked' && feature.activity_state !== 'blocked') {
+    return null;
+  }
+
+  return {
+    code: 'FEATURE_BLOCKED',
+    severity: 'blocked',
+    title: 'Feature is blocked',
+    detail:
+      feature.status_reason?.trim() || 'This feature is blocked and needs operator attention.',
+  };
+}
+
+function recoveryCause(feature: FeatureSummary): HealthDiagnosisCause | null {
+  if (!isFeatureRecovering(feature)) {
+    return null;
+  }
+
+  const role = feature.recovery?.role?.trim() || 'agent';
+  const titleRole = `${role.charAt(0).toUpperCase()}${role.slice(1)}`;
+  const attempt = typeof feature.recovery?.attempt === 'number' ? feature.recovery.attempt : null;
+  const detailByCause: Record<string, string> = {
+    provider_output_invalid: `${titleRole} is retrying after malformed provider output.`,
+    provider_no_progress: `${titleRole} is retrying after a no-progress detection.`,
+    provider_context_stall: `${titleRole} is retrying after repeated context refreshes stalled progress.`,
+  };
+  const causeKey = feature.recovery?.cause?.trim().toLowerCase() ?? '';
+  const baseDetail =
+    detailByCause[causeKey] ??
+    feature.status_reason?.trim() ??
+    `${titleRole} is retrying automatically inside the current run.`;
+  const detail = attempt && attempt > 0 ? `${baseDetail} Attempt ${attempt}.` : baseDetail;
+
+  return {
+    code: 'FEATURE_RECOVERING',
+    severity: 'degraded',
+    title: `${titleRole} retrying`,
+    detail,
+    metadata: {
+      recoveryAttempt: attempt,
+      recoveryCause: feature.recovery?.cause ?? null,
+      recoveryRole: feature.recovery?.role ?? null,
+    },
+  };
+}
+
+function waitingCause(feature: FeatureSummary): HealthDiagnosisCause | null {
+  if (!isWaitingForInput(feature)) {
+    return null;
+  }
+
+  return {
+    code: 'WAITING_INPUT',
+    severity: 'waiting',
+    title: 'Awaiting human input',
+    detail:
+      feature.status_reason?.trim() || 'A human response is required before work can continue.',
+  };
+}
+
+function stalledCause(feature: FeatureSummary, nowMs: number): HealthDiagnosisCause | null {
+  if (!isActivityStalled(feature, nowMs)) {
+    return null;
+  }
+
+  return {
+    code: 'ACTIVITY_STALLED',
+    severity: 'stalled',
+    title: 'Activity appears stalled',
+    detail: `No meaningful change has been recorded for at least ${Math.round(STALL_THRESHOLD_MS / 60_000)} minutes.`,
+    metadata: {
+      lastMeaningfulChangeAt: lastActivityTimestamp(feature),
+    },
+  };
+}
+
+function exitedCause(feature: FeatureSummary): HealthDiagnosisCause | null {
+  if (feature.activity_state !== 'exited') {
+    return null;
+  }
+
+  return {
+    code: 'AGENT_EXITED',
+    severity: 'degraded',
+    title: 'Agent session exited',
+    detail:
+      feature.status_reason?.trim() ||
+      'The active agent session exited before the feature completed.',
+  };
+}
+
+function reviewThreadsCause(feature: FeatureSummary): HealthDiagnosisCause | null {
+  const reviewThreads = feature.pr?.pending_review_threads ?? 0;
+  if (reviewThreads <= 0) {
+    return null;
+  }
+
+  return {
+    code: 'OPEN_REVIEW_THREADS',
+    severity: 'degraded',
+    title: 'Open review threads',
+    detail: `${reviewThreads} review thread${reviewThreads === 1 ? '' : 's'} still need resolution.`,
+    metadata: {
+      reviewThreads,
+    },
+  };
+}
+
+function compareCauses(left: HealthDiagnosisCause, right: HealthDiagnosisCause): number {
+  const rankDelta = SEVERITY_RANK[right.severity] - SEVERITY_RANK[left.severity];
+  if (rankDelta !== 0) {
+    return rankDelta;
+  }
+  const priorityDelta = CAUSE_PRIORITY[right.code] - CAUSE_PRIORITY[left.code];
+  if (priorityDelta !== 0) {
+    return priorityDelta;
+  }
+  return left.title.localeCompare(right.title);
+}
+
+export function deriveHealthDiagnosis(input: DeriveHealthDiagnosisInput): HealthDiagnosis {
+  if (!input.detail) {
+    return {
+      severity: 'healthy',
+      summary: 'No feature selected.',
+      primary: null,
+      secondary: [],
+    };
+  }
+
+  const nowMs = input.nowMs ?? Date.now();
+  const feature = input.detail.feature;
+  const causes = [
+    dependencyCause(input.unresolvedDependencies ?? []),
+    recoveryCause(feature),
+    blockedCause(feature),
+    gateFailureCause(input.detail.gate_evidence),
+    exitedCause(feature),
+    reviewThreadsCause(feature),
+    stalledCause(feature, nowMs),
+    waitingCause(feature),
+  ].filter((cause): cause is HealthDiagnosisCause => cause !== null);
+
+  if (causes.length === 0) {
+    return {
+      severity: 'healthy',
+      summary: 'No blocking or degraded health signals detected.',
+      primary: null,
+      secondary: [],
+    };
+  }
+
+  const sorted = [...causes].sort(compareCauses);
+  const [primary, ...secondary] = sorted;
+
+  return {
+    severity: primary.severity,
+    summary: primary.detail,
+    primary,
+    secondary,
+  };
+}