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

package/packages/status/src/title-activity.ts

@@ -0,0 +1,224 @@
+import {
+  shortenTitleTarget,
+  type TitleActivityClass,
+  type TitleActivityState,
+} from './title-state.ts';
+
+/**
+ * Activity feed for the title state (`deck-title-state`).
+ *
+ * Classifies tool-execution starts/updates into the observed activity classes
+ * with a short target label, attributes `span`/`parent` from the same span
+ * ids the runtime span store uses (turn root, bash/subagent containers,
+ * per-agent children), keeps only the newest event, and resets to null at
+ * turn end. Direct tools are owned by the turn span; bash and subagent
+ * containers own their own span ids.
+ */
+
+const EDITING_TOOLS = new Set(['edit', 'write']);
+const READING_TOOLS = new Set(['read', 'ls']);
+const GREPPING_TOOLS = new Set(['grep', 'find']);
+const BASH_TOOLS = new Set(['bash', 'powershell']);
+const SUBAGENT_TOOL = 'subagent';
+
+const FALLBACK_SUBAGENT_TARGET = 'subagent';
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function shortTarget(value: unknown): string | undefined {
+  const raw = text(value);
+  if (!raw) return undefined;
+  const shortened = shortenTitleTarget(raw);
+  return shortened || undefined;
+}
+
+function firstAgentArg(args: unknown): string | undefined {
+  const input = record(args);
+  if (!input) return undefined;
+  const single = text(input.agent);
+  if (single) return single;
+  for (const key of ['calls', 'tasks', 'chain'] as const) {
+    const list = Array.isArray(input[key]) ? input[key] : undefined;
+    const agent = list ? text(record(list[0])?.agent) : undefined;
+    if (agent) return agent;
+  }
+  return undefined;
+}
+
+export type TitleActivityClassification = {
+  class: TitleActivityClass;
+  target: string;
+};
+
+/**
+ * Classify one tool execution into a title activity class with a bounded
+ * target label. Returns undefined for tools outside the observed classes or
+ * when no bounded target label can be derived (except subagent, which falls
+ * back to a generic label until agent names stream in).
+ */
+export function classifyTitleActivity(
+  toolName: string,
+  args: unknown,
+): TitleActivityClassification | undefined {
+  const tool = toolName.trim().toLowerCase();
+  const input = record(args);
+
+  if (EDITING_TOOLS.has(tool)) {
+    const target = shortTarget(input?.path);
+    return target ? { class: 'editing', target } : undefined;
+  }
+  if (READING_TOOLS.has(tool)) {
+    const target =
+      tool === 'ls' ? (shortTarget(input?.path) ?? '.') : shortTarget(input?.path);
+    return target ? { class: 'reading', target } : undefined;
+  }
+  if (GREPPING_TOOLS.has(tool)) {
+    const target = shortTarget(input?.pattern);
+    return target ? { class: 'grepping', target } : undefined;
+  }
+  if (BASH_TOOLS.has(tool)) {
+    const target = shortTarget(input?.command);
+    return target ? { class: 'bash', target } : undefined;
+  }
+  if (tool === SUBAGENT_TOOL) {
+    return {
+      class: 'subagent',
+      target: shortTarget(firstAgentArg(args)) ?? FALLBACK_SUBAGENT_TARGET,
+    };
+  }
+  return 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: text(result?.agent),
+      active:
+        result?.exitCode === -1 &&
+        result.sawAgentStart === true &&
+        result.sawAgentSettled !== true,
+    };
+  });
+}
+
+function callsAgentName(args: unknown, index: number): string | undefined {
+  const rawCalls = Array.isArray(args)
+    ? args
+    : Array.isArray(record(args)?.calls)
+      ? (record(args) as { calls: unknown[] }).calls
+      : undefined;
+  if (!rawCalls) return undefined;
+  return text(record(rawCalls[index])?.agent);
+}
+
+function sameActivity(
+  left: TitleActivityState | null,
+  right: TitleActivityState | null,
+): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export class TitleActivityFeed {
+  private newest: TitleActivityState | null = null;
+
+  /** The newest observed event, or null when idle. */
+  current(): TitleActivityState | null {
+    return this.newest;
+  }
+
+  /** Clear the feed at turn end. Returns true when an event was dropped. */
+  reset(): boolean {
+    if (this.newest === null) return false;
+    this.newest = null;
+    return true;
+  }
+
+  /**
+   * Observe a tool-execution start. Bash and subagent containers own their
+   * span id (the tool call id); direct tools are owned by the turn span, so
+   * they publish `parent: null` unless no turn is active, in which case the
+   * tool call id stands in.
+   */
+  begin(
+    toolCallId: string,
+    toolName: string,
+    args: unknown,
+    turnSpanId: string | null,
+  ): boolean {
+    const classification = classifyTitleActivity(toolName, args);
+    if (!classification) return false;
+    const owned =
+      classification.class === 'bash' || classification.class === 'subagent';
+    const event: TitleActivityState = owned
+      ? {
+          class: classification.class,
+          target: classification.target,
+          span: toolCallId,
+          parent: turnSpanId,
+        }
+      : {
+          class: classification.class,
+          target: classification.target,
+          span: turnSpanId ?? toolCallId,
+          parent: null,
+        };
+    return this.set(event);
+  }
+
+  /**
+   * Observe a tool-execution update. Subagent partial results publish the
+   * newest active per-agent child span (nested under its container id);
+   * other tools refresh their start event with the same attribution.
+   */
+  update(
+    toolCallId: string,
+    toolName: string,
+    args: unknown,
+    partialResult: unknown,
+    turnSpanId: string | null,
+  ): boolean {
+    const results = partialAgentResults(partialResult);
+    if (results) {
+      for (let index = results.length - 1; index >= 0; index -= 1) {
+        const result = results[index];
+        if (!result?.active) continue;
+        const target =
+          shortTarget(result.agent) ??
+          shortTarget(callsAgentName(args, index)) ??
+          FALLBACK_SUBAGENT_TARGET;
+        return this.set({
+          class: 'subagent',
+          target,
+          span: `${toolCallId}:${index}`,
+          parent: toolCallId,
+        });
+      }
+      return false;
+    }
+    return this.begin(toolCallId, toolName, args, turnSpanId);
+  }
+
+  private set(event: TitleActivityState): boolean {
+    if (sameActivity(this.newest, event)) return false;
+    this.newest = event;
+    return true;
+  }
+}

package/packages/status/src/title-state.ts

@@ -0,0 +1,218 @@
+import type { OpenSpecFocus, SessionSubject } from './active-work.ts';
+import type { OpenSpecState } from './types.ts';
+
+/**
+ * Title-state contract v1 (`deck-title-state`).
+ *
+ * One authoritative object for the deck's upper half: `subject` is authored
+ * once, `work` is derived from OpenSpec focus, `activity` is observed from
+ * tool executions, and `waiver` suppresses one exact notice text. Rendering
+ * code may never write any slot; it only parses defensively.
+ */
+
+export const TITLE_STATE_VERSION = 1 as const;
+
+export const TITLE_ACTIVITY_CLASSES = [
+  'editing',
+  'reading',
+  'grepping',
+  'bash',
+  'subagent',
+] as const;
+
+export type TitleActivityClass = (typeof TITLE_ACTIVITY_CLASSES)[number];
+
+/** Short target label bound from the accepted schema. */
+export const TITLE_TARGET_MAX = 48;
+
+/** Task/step totals bound from the accepted schema. */
+export const TITLE_TOTAL_MAX = 999;
+
+const SUBJECT_MAX = 180;
+const IDENTIFIER_MAX = 120;
+const TASK_ID_MAX = 32;
+const SPAN_ID_MAX = 64;
+const WAIVER_ID_MAX = 64;
+const NOTICE_MAX = 180;
+
+export type TitleWorkState = {
+  change: string;
+  task?: string;
+  done: number;
+  total: number;
+};
+
+export type TitleActivityState = {
+  class: TitleActivityClass;
+  target: string;
+  span: string;
+  parent: string | null;
+};
+
+export type TitleWaiverState = { id: string; notice: string };
+
+export type TitleState = {
+  v: typeof TITLE_STATE_VERSION;
+  subject: string | null;
+  work: TitleWorkState | null;
+  activity: TitleActivityState | null;
+  waiver: TitleWaiverState | null;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function boundedText(
+  value: unknown,
+  maximum: number,
+  { required = true }: { required?: boolean } = {},
+): string | null | undefined {
+  if (value === null || value === undefined) return required ? null : undefined;
+  if (typeof value !== 'string') return null;
+  const points = Array.from(value.replace(/\s+/gu, ' ').trim());
+  if (points.length === 0) return null;
+  if (points.length > maximum) return null;
+  return points.join('');
+}
+
+function boundedTotal(value: unknown): number | null {
+  return typeof value === 'number' &&
+    Number.isInteger(value) &&
+    value >= 0 &&
+    value <= TITLE_TOTAL_MAX
+    ? value
+    : null;
+}
+
+function parseTitleActivity(value: unknown): TitleActivityState | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+  const activityClass = TITLE_ACTIVITY_CLASSES.includes(
+    value.class as TitleActivityClass,
+  )
+    ? (value.class as TitleActivityClass)
+    : undefined;
+  const target = boundedText(value.target, TITLE_TARGET_MAX);
+  const span = boundedText(value.span, SPAN_ID_MAX);
+  let parent: string | null | undefined;
+  if (value.parent === null) parent = null;
+  else if (typeof value.parent === 'string') {
+    const normalized = boundedText(value.parent, SPAN_ID_MAX);
+    parent = normalized === null ? undefined : normalized;
+  } else parent = undefined;
+  if (!activityClass || !target || !span || parent === undefined) return undefined;
+  return { class: activityClass, target, span, parent };
+}
+
+function parseTitleWork(value: unknown): TitleWorkState | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+  const change = boundedText(value.change, IDENTIFIER_MAX);
+  const done = boundedTotal(value.done);
+  const total = boundedTotal(value.total);
+  if (!change || done === null || total === null) return undefined;
+  const task = boundedText(value.task, TASK_ID_MAX, { required: false });
+  if (task === null) return undefined;
+  return task === undefined ? { change, done, total } : { change, task, done, total };
+}
+
+function parseTitleWaiver(value: unknown): TitleWaiverState | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+  const id = boundedText(value.id, WAIVER_ID_MAX);
+  const notice = boundedText(value.notice, NOTICE_MAX);
+  if (!id || !notice) return undefined;
+  return { id, notice };
+}
+
+/**
+ * Defensive parser for incoming title-state payloads. Unknown versions,
+ * malformed shapes, and out-of-bounds values (target > 48 characters,
+ * totals > 999) reject the whole object with `null`; it never throws.
+ */
+export function parseTitleState(value: unknown): TitleState | null {
+  try {
+    if (!isRecord(value)) return null;
+    if (value.v !== TITLE_STATE_VERSION) return null;
+    const subject = boundedText(value.subject, SUBJECT_MAX, { required: false });
+    if (subject === null) return null;
+    const work = parseTitleWork(value.work);
+    if (work === undefined) return null;
+    const activity = parseTitleActivity(value.activity);
+    if (activity === undefined) return null;
+    const waiver = parseTitleWaiver(value.waiver);
+    if (waiver === undefined) return null;
+    return {
+      v: TITLE_STATE_VERSION,
+      subject: subject ?? null,
+      work,
+      activity,
+      waiver,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Collapse whitespace and shorten a live target label to the schema bound. */
+export function shortenTitleTarget(value: string): string {
+  const points = Array.from(value.replace(/\s+/gu, ' ').trim());
+  if (points.length <= TITLE_TARGET_MAX) return points.join('');
+  return `${points.slice(0, Math.max(1, TITLE_TARGET_MAX - 1)).join('')}…`;
+}
+
+function boundedCount(value: number | undefined, fallback = 0): number {
+  const candidate = value === undefined || !Number.isFinite(value) ? fallback : value;
+  return Math.max(0, Math.min(TITLE_TOTAL_MAX, Math.round(candidate)));
+}
+
+/**
+ * Derive the `work` slot from the OpenSpec focus and the focused snapshot.
+ * A task focus owns its change; without a focus a passively collected change
+ * still reports progress, just without a task id.
+ */
+export function deriveTitleWork(
+  focus: OpenSpecFocus,
+  openspec: OpenSpecState | null | undefined,
+): TitleWorkState | null {
+  const counts = (state: OpenSpecState): { done: number; total: number } => ({
+    done: boundedCount(state.hierarchy?.tasks?.completed, state.completedTasks),
+    total: boundedCount(state.hierarchy?.tasks?.total, state.totalTasks),
+  });
+  if (focus.mode === 'task') {
+    const state = openspec && openspec.changeId === focus.change ? openspec : undefined;
+    return {
+      change: focus.change,
+      task: focus.taskId,
+      ...(state ? counts(state) : { done: 0, total: 0 }),
+    };
+  }
+  if (!openspec) return null;
+  return { change: openspec.changeId, ...counts(openspec) };
+}
+
+/**
+ * Build the v1 title state from publisher-owned facts: the authored session
+ * subject entry, the OpenSpec focus (plus its snapshot), and the newest
+ * observed activity event. The waiver slot stays null until the notice slice.
+ */
+export function buildTitleState(options: {
+  subject: SessionSubject;
+  focus: OpenSpecFocus;
+  openspec?: OpenSpecState | null;
+  activity?: TitleActivityState | null;
+}): TitleState {
+  return {
+    v: TITLE_STATE_VERSION,
+    subject: options.subject.state === 'set' ? options.subject.title : null,
+    work: deriveTitleWork(options.focus, options.openspec),
+    activity: options.activity ?? null,
+    waiver: null,
+  };
+}
+
+/** Checkpoint line for `/galactica-status-debug`: the live title-state JSON. */
+export function titleStateDebugLine(title: TitleState): string {
+  return `title-state: ${JSON.stringify(title)}`;
+}

package/packages/status/src/turn-cost.ts

@@ -0,0 +1,63 @@
+/**
+ * Per-turn cost meter for the title-state publisher (`deck-title-state`).
+ *
+ * Sums provider usage deltas across the assistant messages of the current
+ * turn and measures turn elapsed time. `before_agent_start` resets it; a
+ * settled (idle) session reads zero so the deck's line 3 shows `— · 0 tok`.
+ */
+
+export type TurnCostSnapshot = { tokens: number; elapsedMs: number };
+
+/** Matches the span-idle convention: 99m59s999ms. */
+const MAX_ELAPSED_MS = (99 * 60 + 59) * 1_000 + 999;
+
+function usageTokens(value: unknown): number {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return 0;
+  const usage = value as Record<string, unknown>;
+  let tokens = 0;
+  for (const key of ['input', 'output', 'cacheRead', 'cacheWrite'] as const) {
+    const count = usage[key];
+    if (typeof count === 'number' && Number.isFinite(count) && count > 0) {
+      tokens += count;
+    }
+  }
+  return Math.round(tokens);
+}
+
+export class TurnCostMeter {
+  private tokens = 0;
+  private startedAt: number | null = null;
+  private readonly now: () => number;
+
+  constructor(now: () => number = Date.now) {
+    this.now = now;
+  }
+
+  /** Reset at `before_agent_start`: zero tokens, elapsed from now. */
+  begin(): void {
+    this.tokens = 0;
+    this.startedAt = this.now();
+  }
+
+  /** Add one provider response's usage; returns true when tokens accrued. */
+  addUsage(usage: unknown): boolean {
+    const tokens = usageTokens(usage);
+    if (tokens <= 0) return false;
+    this.tokens += tokens;
+    return true;
+  }
+
+  /** Zero the meter when the turn settles so idle reads `{tokens:0,elapsedMs:0}`. */
+  settle(): void {
+    this.tokens = 0;
+    this.startedAt = null;
+  }
+
+  snapshot(): TurnCostSnapshot {
+    const elapsedMs =
+      this.startedAt === null
+        ? 0
+        : Math.max(0, Math.min(MAX_ELAPSED_MS, this.now() - this.startedAt));
+    return { tokens: this.tokens, elapsedMs };
+  }
+}