@aemonge-dev/pi-stardeck 0.0.0-stage → 0.5.0

package/packages/status/src/reducer.ts

@@ -0,0 +1,190 @@
+import type { LedgerEvent } from './ledger.ts';
+import type { GoalHeaderState } from './goal.ts';
+import type { OpenSpecFocus, SessionSubject, SessionWorkFocus } from './active-work.ts';
+import type {
+  CockpitSnapshot,
+  ProgressFact,
+  RunSpan,
+  SelectionState,
+  StageValue,
+} from './types.ts';
+
+/**
+ * Pure reducer for the cockpit status core (frozen contract).
+ *
+ * The reducer is the only writer of snapshot state. Selection priority lives in
+ * exactly one resolver. Title and stage are derived projections, never stored
+ * facts. Placeholder rendering is structurally impossible here: absent facts
+ * produce absent slots, never sentinel dashes or narration.
+ */
+
+export type ReducerFacts = {
+  openSpec: OpenSpecFocus;
+  goal: GoalHeaderState | null;
+  work: SessionWorkFocus;
+  subject: SessionSubject;
+  runs: ReadonlyMap<string, RunSpan>;
+  progress: ProgressFact | null;
+};
+
+export const NO_SELECTION: SelectionState = { kind: 'none' };
+
+export function emptyFacts(): ReducerFacts {
+  return {
+    openSpec: { mode: 'none' },
+    goal: null,
+    work: { state: 'clear' },
+    subject: { state: 'clear' },
+    runs: new Map(),
+    progress: null,
+  };
+}
+
+/** The single selection resolver. Priority order is contract-frozen. */
+export function resolveSelection(facts: {
+  openSpec: OpenSpecFocus;
+  goal: GoalHeaderState | null;
+  work: SessionWorkFocus;
+  subject: SessionSubject;
+}): SelectionState {
+  if (facts.openSpec.mode === 'task') {
+    return {
+      kind: 'openspec-task',
+      change: facts.openSpec.change,
+      task: facts.openSpec.taskId,
+    };
+  }
+  if (facts.goal) {
+    return {
+      kind: 'goal',
+      status: facts.goal.status,
+      waiting: facts.goal.waiting,
+    };
+  }
+  if (facts.work.state !== 'clear') {
+    return {
+      kind: 'session-work',
+      intent: facts.work.intent,
+      phase: facts.work.state === 'validation' ? 'validation' : 'active',
+    };
+  }
+  if (facts.subject.state === 'set') {
+    return { kind: 'subject', title: facts.subject.title };
+  }
+  return NO_SELECTION;
+}
+
+function applyStageRule(span: RunSpan, stage: StageValue, declared: boolean): RunSpan {
+  // Declaration beats inference: an inferred stage never overrides a declared one.
+  if (!declared && span.stageDeclared) return span;
+  return { ...span, stage, stageDeclared: declared };
+}
+
+export function applyEvent(facts: ReducerFacts, event: LedgerEvent): ReducerFacts {
+  switch (event.type) {
+    case 'focus/openspec':
+      return { ...facts, openSpec: event.focus };
+    case 'focus/goal':
+      return { ...facts, goal: event.goal };
+    case 'focus/work':
+      return { ...facts, work: event.work };
+    case 'focus/subject':
+      return { ...facts, subject: event.subject };
+    case 'run/start': {
+      const runs = new Map(facts.runs);
+      runs.set(event.span.id, event.span);
+      return { ...facts, runs };
+    }
+    case 'run/stage': {
+      const span = facts.runs.get(event.id);
+      if (!span || span.endedAt !== undefined) return facts;
+      const runs = new Map(facts.runs);
+      runs.set(event.id, applyStageRule(span, event.stage, event.declared));
+      return { ...facts, runs };
+    }
+    case 'run/end': {
+      const span = facts.runs.get(event.id);
+      if (!span || span.endedAt !== undefined) return facts;
+      const runs = new Map(facts.runs);
+      runs.set(event.id, { ...span, endedAt: event.at });
+      return { ...facts, runs };
+    }
+    case 'progress/refresh':
+      return { ...facts, progress: event.progress };
+    case 'diagnostics/refresh':
+    case 'orchestration/refresh':
+    case 'taskflow/phase':
+      // Bounded collector domains feed the same ledger path but never the
+      // selection; snapshot consumers read them through their own projections.
+      return facts;
+  }
+}
+
+/** Fold a full ledger into one snapshot. Pure; version counts applied events. */
+export function reduceLedger(events: readonly LedgerEvent[]): CockpitSnapshot {
+  let facts = emptyFacts();
+  for (const event of events) {
+    facts = applyEvent(facts, event);
+  }
+  return snapshotFromFacts(facts, events.length);
+}
+
+export function snapshotFromFacts(
+  facts: ReducerFacts,
+  version: number,
+): CockpitSnapshot {
+  const runs = [...facts.runs.values()].sort((left, right) => {
+    if (left.since !== right.since) return left.since - right.since;
+    return left.id < right.id ? -1 : 1;
+  });
+  return {
+    version,
+    selection: resolveSelection(facts),
+    runs,
+    progress: facts.progress,
+  };
+}
+
+/** Root run of the current turn, if any (the direct agent). */
+export function rootRun(snapshot: CockpitSnapshot): RunSpan | undefined {
+  return snapshot.runs.find((span) => span.kind === 'agent' && span.parent === null);
+}
+
+/** Derived stage: the root run's stage, or listening when nothing runs. */
+export function derivedStage(snapshot: CockpitSnapshot): StageValue {
+  return rootRun(snapshot)?.stage ?? 'listening';
+}
+
+/**
+ * Derived terminal title. `title = f(selection, stage, progress)` — never stored,
+ * never updated independently, never a placeholder.
+ */
+export function deriveTitle(snapshot: CockpitSnapshot): string {
+  const selection = snapshot.selection;
+  let detail: string;
+  switch (selection.kind) {
+    case 'openspec-task':
+      detail = `${selection.change} › ${selection.task}`;
+      break;
+    case 'goal':
+      detail =
+        selection.status === 'complete'
+          ? 'Validate › Goal'
+          : selection.waiting
+            ? 'Goal › waiting'
+            : 'Goal';
+      break;
+    case 'session-work':
+      detail =
+        selection.phase === 'validation'
+          ? `Validate › ${selection.intent}`
+          : selection.intent;
+      break;
+    case 'subject':
+      detail = selection.title;
+      break;
+    default:
+      detail = '';
+  }
+  return detail ? `π ${detail}` : 'π';
+}

package/packages/status/src/runtime-runs.ts

@@ -0,0 +1,267 @@
+import type { StageValue } from './types.ts';
+import { classifyHeaderActivity, headerLifecycleForActivity } from './publisher.ts';
+
+/**
+ * Runtime span store (frozen contract, `runs` fact).
+ *
+ * Replaces count-only tracking: every live participant is a span with identity,
+ * parent, stage, and age. Subagent partial results map to per-agent child spans;
+ * bash children are leaf spans. The derived `snapshot()` keeps count parity with
+ * the retired `RuntimeRunTracker` while adding the span views renderers need.
+ */
+
+export interface ActiveRunSpanView {
+  id: string;
+  kind: 'agent' | 'subagent' | 'bash';
+  parent: string | null;
+  agent?: string;
+  label?: string;
+  stage: StageValue;
+  elapsedMs: number;
+}
+
+export interface ActiveRuntimeRuns {
+  children: number;
+  subagents: number;
+  spans?: ActiveRunSpanView[];
+}
+
+interface TrackedSpan {
+  id: string;
+  kind: 'agent' | 'subagent' | 'bash';
+  parent: string | null;
+  agent?: string;
+  label?: string;
+  stage: StageValue;
+  stageDeclared: boolean;
+  since: number;
+  endedAt?: number;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+interface PartialAgentResult {
+  agent?: string;
+  active: boolean;
+}
+
+function partialAgentResults(partialResult: unknown): PartialAgentResult[] | undefined {
+  const details = record(record(partialResult)?.details);
+  if (details?.kind !== 'pi-subagent' || !Array.isArray(details.results)) {
+    return undefined;
+  }
+  return details.results.map((rawResult) => {
+    const result = record(rawResult);
+    return {
+      agent: typeof result?.agent === 'string' ? result.agent : undefined,
+      active:
+        result?.exitCode === -1 &&
+        result.sawAgentStart === true &&
+        result.sawAgentSettled !== true,
+    };
+  });
+}
+
+function inferredStage(agent: string | undefined): StageValue {
+  const activity = classifyHeaderActivity(agent ?? '');
+  return headerLifecycleForActivity(activity) ?? 'working';
+}
+
+export interface SpanStoreChange {
+  started: ActiveRunSpanView[];
+  ended: string[];
+}
+
+export class RuntimeSpanStore {
+  private readonly spans = new Map<string, TrackedSpan>();
+  private changeQueue: SpanStoreChange = { started: [], ended: [] };
+
+  beginRoot(turnId: string, stage: StageValue, now = Date.now()): boolean {
+    return this.beginSpan({
+      id: turnId,
+      kind: 'agent',
+      parent: null,
+      stage,
+      stageDeclared: false,
+      since: now,
+    });
+  }
+
+  endRoot(turnId: string, now = Date.now()): boolean {
+    return this.finishSpan(turnId, now);
+  }
+
+  begin(
+    toolCallId: string,
+    kind: 'bash' | 'subagent',
+    parent: string | null,
+    now = Date.now(),
+  ): boolean {
+    if (this.spans.has(toolCallId)) return false;
+    return this.beginSpan({
+      id: toolCallId,
+      kind,
+      parent,
+      stage: 'working',
+      stageDeclared: false,
+      since: now,
+    });
+  }
+
+  finish(toolCallId: string, now = Date.now()): boolean {
+    return this.finishSpan(toolCallId, now);
+  }
+
+  /**
+   * Map subagent partial results to per-agent child spans. Returns true when any
+   * span started or ended; queued changes are drained by `drainChanges()`.
+   */
+  update(
+    toolCallId: string,
+    partialResult: unknown,
+    args?: unknown,
+    now = Date.now(),
+  ): boolean {
+    const parent = this.spans.get(toolCallId);
+    if (!parent || parent.kind !== 'subagent') return false;
+    const results = partialAgentResults(partialResult);
+    if (!results) return false;
+    // Agent names live in the tool input, not the results: calls[i].agent maps
+    // to results[i] by order. Bounded identifiers only, never prompt content.
+    const rawCalls = Array.isArray(args)
+      ? args
+      : (args as { calls?: unknown } | undefined)?.calls;
+    const calls = Array.isArray(rawCalls)
+      ? (rawCalls as Array<{ agent?: unknown }>)
+      : [];
+    const callAgent = (index: number): string | undefined => {
+      const agent = calls[index]?.agent;
+      return typeof agent === 'string' && agent.trim() ? agent.trim() : undefined;
+    };
+
+    let changed = false;
+    const expected = new Set<string>();
+    results.forEach((result, index) => {
+      const agent = result.agent?.trim() || callAgent(index);
+      if (!result.active) return;
+      const childId = `${toolCallId}:${index}`;
+      expected.add(childId);
+      const existing = this.spans.get(childId);
+      if (existing && existing.endedAt === undefined) {
+        if (agent && existing.agent !== agent) {
+          existing.agent = agent;
+          existing.stage = inferredStage(agent);
+          changed = true;
+        }
+        return;
+      }
+      changed =
+        this.beginSpan({
+          id: childId,
+          kind: 'subagent',
+          parent: toolCallId,
+          agent,
+          stage: inferredStage(agent),
+          stageDeclared: false,
+          since: now,
+        }) || changed;
+    });
+
+    for (const span of this.spans.values()) {
+      if (span.parent === toolCallId && span.endedAt === undefined) {
+        if (!expected.has(span.id)) {
+          changed = this.finishSpan(span.id, now) || changed;
+        }
+      }
+    }
+    return changed;
+  }
+
+  setStage(id: string, stage: StageValue, declared: boolean): boolean {
+    const span = this.spans.get(id);
+    if (!span || span.endedAt !== undefined) return false;
+    // Declaration beats inference: an inferred stage never overrides a declared one.
+    if (!declared && span.stageDeclared) return false;
+    if (span.stage === stage && span.stageDeclared === declared) return false;
+    span.stage = stage;
+    span.stageDeclared = declared;
+    return true;
+  }
+
+  /** Time since the last root span ended; 0 while any span is active. */
+  idleMs(now = Date.now()): number {
+    let lastEnded = 0;
+    for (const span of this.spans.values()) {
+      if (span.endedAt === undefined) return 0;
+      if (span.kind === 'agent' && span.endedAt > lastEnded) lastEnded = span.endedAt;
+    }
+    if (lastEnded === 0) return 0;
+    return Math.max(0, Math.min(now - lastEnded, (99 * 60 + 59) * 1_000 + 999));
+  }
+
+  drainChanges(): SpanStoreChange {
+    const drained = this.changeQueue;
+    this.changeQueue = { started: [], ended: [] };
+    return drained;
+  }
+
+  snapshot(now = Date.now()): ActiveRuntimeRuns {
+    const views: ActiveRunSpanView[] = [];
+    let children = 0;
+    let subagents = 0;
+    for (const span of this.spans.values()) {
+      if (span.endedAt !== undefined) continue;
+      const parent = span.parent ? this.spans.get(span.parent) : undefined;
+      const isAgentChild = span.kind === 'subagent' && parent?.kind === 'subagent';
+      views.push({
+        id: span.id,
+        kind: span.kind,
+        parent: span.parent,
+        ...(span.agent ? { agent: span.agent } : {}),
+        ...(span.label ? { label: span.label } : {}),
+        stage: span.stage,
+        elapsedMs: Math.max(0, now - span.since),
+      });
+      if (span.kind === 'bash') children += 1;
+      if (isAgentChild) {
+        children += 1;
+        subagents += 1;
+      }
+    }
+    return { children, subagents, spans: views };
+  }
+
+  private beginSpan(span: TrackedSpan): boolean {
+    if (this.spans.has(span.id)) return false;
+    this.spans.set(span.id, span);
+    this.changeQueue.started.push({
+      id: span.id,
+      kind: span.kind,
+      parent: span.parent,
+      ...(span.agent ? { agent: span.agent } : {}),
+      ...(span.label ? { label: span.label } : {}),
+      stage: span.stage,
+      elapsedMs: 0,
+    });
+    return true;
+  }
+
+  private finishSpan(id: string, now: number): boolean {
+    const span = this.spans.get(id);
+    if (!span || span.endedAt !== undefined) return false;
+    span.endedAt = now;
+    this.changeQueue.ended.push(id);
+    // Ending a container takes its per-agent children with it.
+    for (const child of this.spans.values()) {
+      if (child.parent === id && child.endedAt === undefined) {
+        child.endedAt = now;
+        this.changeQueue.ended.push(child.id);
+      }
+    }
+    return true;
+  }
+}

package/packages/status/src/state.ts

@@ -0,0 +1,178 @@
+import type {
+  DiagnosticsState,
+  OpenSpecState,
+  OrchestrationState,
+  RuntimeErrorRecord,
+  StatusSnapshot,
+} from './types.ts';
+
+export type DomainName = 'openspec' | 'diagnostics' | 'orchestration';
+
+export type RefreshOutcome<T> =
+  { kind: 'success'; value: T } | { kind: 'absent' } | { kind: 'error'; error: string };
+
+export interface RefreshBatch {
+  projectRoot: string;
+  at: number;
+  openspec: RefreshOutcome<OpenSpecState>;
+  diagnostics: RefreshOutcome<DiagnosticsState>;
+  orchestration: RefreshOutcome<OrchestrationState>;
+}
+
+function staleValue<
+  T extends { meta: { stale: boolean; attemptedAt: number; error?: string } },
+>(previous: T | null, error: string, at: number): T | null {
+  if (!previous) return null;
+  return {
+    ...previous,
+    meta: {
+      ...previous.meta,
+      stale: true,
+      attemptedAt: at,
+      error,
+    },
+  };
+}
+
+function applyOutcome<
+  T extends { meta: { stale: boolean; attemptedAt: number; error?: string } },
+>(previous: T | null, outcome: RefreshOutcome<T>, at: number): T | null {
+  if (outcome.kind === 'success') return outcome.value;
+  if (outcome.kind === 'absent') return null;
+  return staleValue(previous, outcome.error, at);
+}
+
+export class AtomicStatusStore {
+  private snapshot: StatusSnapshot;
+
+  constructor(initial: {
+    cwd: string;
+    projectRoot: string;
+    configPath: string;
+    configWarnings?: string[];
+  }) {
+    this.snapshot = {
+      cwd: initial.cwd,
+      projectRoot: initial.projectRoot,
+      configPath: initial.configPath,
+      configWarnings: [...(initial.configWarnings ?? [])],
+      openspec: null,
+      diagnostics: null,
+      orchestration: null,
+      errors: [],
+    };
+  }
+
+  get(): StatusSnapshot {
+    return this.snapshot;
+  }
+
+  setConfig(configPath: string, warnings: string[]): void {
+    this.snapshot = {
+      ...this.snapshot,
+      configPath,
+      configWarnings: [...warnings],
+    };
+  }
+
+  clearOpenSpec(): void {
+    if (!this.snapshot.openspec) return;
+    this.snapshot = { ...this.snapshot, openspec: null };
+  }
+
+  applyRefresh(batch: RefreshBatch): void {
+    this.snapshot = {
+      ...this.snapshot,
+      projectRoot: batch.projectRoot,
+      lastRefreshAt: batch.at,
+      openspec: applyOutcome(this.snapshot.openspec, batch.openspec, batch.at),
+      diagnostics: applyOutcome(this.snapshot.diagnostics, batch.diagnostics, batch.at),
+      orchestration: applyOutcome(
+        this.snapshot.orchestration,
+        batch.orchestration,
+        batch.at,
+      ),
+    };
+  }
+
+  recordError(error: RuntimeErrorRecord): void {
+    const duplicate = this.snapshot.errors.at(-1);
+    if (duplicate?.domain === error.domain && duplicate.message === error.message) {
+      this.snapshot = {
+        ...this.snapshot,
+        errors: [...this.snapshot.errors.slice(0, -1), error],
+      };
+      return;
+    }
+    this.snapshot = {
+      ...this.snapshot,
+      errors: [...this.snapshot.errors, error].slice(-12),
+    };
+  }
+}
+
+export class ResourceBag {
+  private cleanups: Array<() => void> = [];
+  private closed = false;
+
+  add(cleanup: () => void): () => void {
+    if (this.closed) {
+      cleanup();
+      return () => {};
+    }
+    let active = true;
+    const wrapped = () => {
+      if (!active) return;
+      active = false;
+      cleanup();
+    };
+    this.cleanups.push(wrapped);
+    return wrapped;
+  }
+
+  addInterval(
+    callback: () => void,
+    intervalMs: number,
+  ): ReturnType<typeof setInterval> {
+    const timer = setInterval(callback, intervalMs);
+    timer.unref?.();
+    this.add(() => clearInterval(timer));
+    return timer;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    for (const cleanup of this.cleanups.splice(0).reverse()) {
+      try {
+        cleanup();
+      } catch {
+        // Cleanup remains best-effort during Pi shutdown/reload.
+      }
+    }
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+}
+
+export function createDebouncer(
+  callback: () => void,
+  delayMs: number,
+  resources: ResourceBag,
+): () => void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  resources.add(() => {
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  });
+  return () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      callback();
+    }, delayMs);
+    timer.unref?.();
+  };
+}