@wichayutdew/pi-workflows 1.0.1 → 2.0.0

package/src/workflow-status/render-step-detail.ts

@@ -0,0 +1,379 @@
+import { wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import type {
+  StepExecutionAttempt,
+  StepHistoryEntry,
+} from '../engine/state.ts';
+import { redactStepDetailText } from '../step-log.ts';
+import { boxed, keyValueLines } from './layout.ts';
+import { buildPathEntries } from './render-path.ts';
+import type { StepTranscriptLog } from './transcript-reader.ts';
+import type { WorkflowStatusSnapshot, WorkflowStatusTheme } from './types.ts';
+
+const MAX_DETAIL_ARTIFACT_CHARS = 20_000;
+
+export type StepTranscriptViewState =
+  { readonly status: 'loading' } | StepTranscriptLog;
+
+export type StepTranscriptViewCache = ReadonlyMap<
+  string,
+  StepTranscriptViewState
+>;
+
+export type SelectedStepDetail = {
+  readonly entryIndex: number;
+  readonly historyEntry?: StepHistoryEntry;
+  readonly attempts: ReadonlyArray<StepExecutionAttempt>;
+  readonly omittedAttempts: number;
+};
+
+export function stepTranscriptCacheKey(
+  runId: string,
+  attempt: StepExecutionAttempt,
+): string {
+  return `${runId}\0${attempt.requestId}`;
+}
+
+/** Resolves one displayed path row back to its durable checkpoint evidence. */
+export function selectedStepDetail(
+  snapshot: WorkflowStatusSnapshot,
+  selectedIndex: number,
+): SelectedStepDetail | undefined {
+  const entries = buildPathEntries(snapshot);
+  const entry = entries[selectedIndex];
+  if (!entry) return undefined;
+  if (entry.historyIndex !== undefined) {
+    const historyEntry = snapshot.run.history[entry.historyIndex];
+    if (!historyEntry) return undefined;
+    return {
+      entryIndex: entry.index,
+      historyEntry,
+      attempts: historyEntry.attempts ?? [],
+      omittedAttempts: historyEntry.omittedAttempts ?? 0,
+    };
+  }
+  return {
+    entryIndex: entry.index,
+    attempts: snapshot.run.currentStepAttempts ?? [],
+    omittedAttempts: snapshot.run.currentStepOmittedAttempts ?? 0,
+  };
+}
+
+function wrapPlain(
+  value: string,
+  width: number,
+  theme: WorkflowStatusTheme,
+  color: 'text' | 'muted' | 'dim' | 'warning' = 'text',
+): Array<string> {
+  const sanitized = redactStepDetailText(value);
+  const logicalLines = sanitized.split('\n');
+  const wrapped = logicalLines.flatMap((line) => {
+    const themed = theme.fg(color, line || ' ');
+    return wrapTextWithAnsi(themed, Math.max(1, width));
+  });
+  return wrapped.length > 0 ? wrapped : [theme.fg(color, ' ')];
+}
+
+function boundedArtifact(value: string): {
+  readonly value: string;
+  readonly truncated: boolean;
+} {
+  return value.length <= MAX_DETAIL_ARTIFACT_CHARS
+    ? { value, truncated: false }
+    : {
+        value: value.slice(0, MAX_DETAIL_ARTIFACT_CHARS),
+        truncated: true,
+      };
+}
+
+function renderResult(
+  theme: WorkflowStatusTheme,
+  attempt: StepExecutionAttempt,
+  width: number,
+): Array<string> {
+  const result = attempt.result;
+  if (!result) return [];
+  const artifact =
+    result.artifact === undefined
+      ? undefined
+      : boundedArtifact(result.artifact);
+  return [
+    '',
+    theme.bold(theme.fg('accent', 'Submitted result')),
+    ...keyValueLines(theme, 'outcome', result.outcome, width, 'success'),
+    ...keyValueLines(
+      theme,
+      'summary',
+      `${result.summary}${result.summaryTruncated ? ' … [trace truncated]' : ''}`,
+      width,
+    ),
+    ...(result.workspaceCwd
+      ? keyValueLines(theme, 'workspace', result.workspaceCwd, width)
+      : []),
+    ...(artifact
+      ? [
+          theme.fg('muted', 'artifact'),
+          ...wrapPlain(
+            `${artifact.value}${
+              artifact.truncated || result.artifactTruncated
+                ? '\n… [artifact truncated in status trace]'
+                : ''
+            }`,
+            width,
+            theme,
+          ),
+        ]
+      : []),
+  ];
+}
+
+function renderGateDecision(
+  theme: WorkflowStatusTheme,
+  attempt: StepExecutionAttempt,
+  width: number,
+): Array<string> {
+  const decision = attempt.gateDecision;
+  if (!decision) return [];
+  return [
+    '',
+    theme.bold(theme.fg('accent', 'Human gate decision')),
+    ...keyValueLines(theme, 'provider', decision.provider, width),
+    ...keyValueLines(
+      theme,
+      'decision',
+      decision.approved ? 'approved' : 'rejected',
+      width,
+      decision.approved ? 'success' : 'warning',
+    ),
+    ...(decision.reviewId
+      ? keyValueLines(theme, 'review', decision.reviewId, width, 'muted')
+      : []),
+    ...(decision.feedback
+      ? keyValueLines(
+          theme,
+          'feedback',
+          `${decision.feedback}${
+            decision.feedbackTruncated ? ' … [trace truncated]' : ''
+          }`,
+          width,
+        )
+      : []),
+  ];
+}
+
+function renderTranscript(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  attempt: StepExecutionAttempt,
+  cache: StepTranscriptViewCache,
+  width: number,
+): Array<string> {
+  if (attempt.kind === 'main') {
+    const events = (attempt.log ?? []).flatMap((event, index) => [
+      theme.fg('muted', `#${index + 1}`),
+      ...wrapPlain(event, width, theme),
+    ]);
+    return [
+      ...(events.length > 0
+        ? events
+        : [
+            theme.fg(
+              'muted',
+              'No main-agent reaction log was recorded for this attempt. Legacy checkpoints still show the exact task and result.',
+            ),
+          ]),
+      ...(attempt.logTruncated
+        ? [
+            theme.fg(
+              'warning',
+              `… Main-agent log was bounded; ${attempt.omittedLogEvents ?? 0} later event${attempt.omittedLogEvents === 1 ? '' : 's'} omitted.`,
+            ),
+          ]
+        : []),
+    ];
+  }
+  if (!attempt.transcript) {
+    return wrapPlain(
+      'No trusted child transcript reference was recorded for this attempt.',
+      width,
+      theme,
+      'muted',
+    );
+  }
+  const state = cache.get(stepTranscriptCacheKey(snapshot.run.runId, attempt));
+  if (!state || state.status === 'loading') {
+    return [theme.fg('muted', 'Loading trusted child transcript…')];
+  }
+  if (state.status === 'unavailable') {
+    return wrapPlain(state.reason, width, theme, 'warning');
+  }
+  const events = state.lines.flatMap((event, index) => [
+    theme.fg('muted', `#${index + 1}`),
+    ...wrapPlain(event, width, theme),
+  ]);
+  return [
+    ...(events.length > 0
+      ? events
+      : [theme.fg('muted', 'No displayable assistant or tool events found.')]),
+    ...(state.truncated
+      ? [
+          theme.fg(
+            'warning',
+            '… Transcript display was bounded; additional events were omitted.',
+          ),
+        ]
+      : []),
+  ];
+}
+
+function renderAttempt(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  attempt: StepExecutionAttempt,
+  attemptNumber: number,
+  cache: StepTranscriptViewCache,
+  width: number,
+): Array<string> {
+  const actor =
+    attempt.kind === 'subagent' ? `subagent · ${attempt.agent}` : 'main agent';
+  const truncation = attempt.taskTruncated
+    ? `\n… [${attempt.omittedTaskChars ?? 0} task characters omitted from the bounded checkpoint trace]`
+    : '';
+  return [
+    theme.bold(theme.fg('accent', `Attempt ${attemptNumber} · ${actor}`)),
+    ...keyValueLines(theme, 'request', attempt.requestId, width, 'muted'),
+    '',
+    theme.bold('Requirement fed to the agent'),
+    ...wrapPlain(`${attempt.task}${truncation}`, width, theme),
+    '',
+    theme.bold('Chronological reaction and tool log'),
+    ...renderTranscript(theme, snapshot, attempt, cache, width),
+    ...renderResult(theme, attempt, width),
+    ...renderGateDecision(theme, attempt, width),
+  ];
+}
+
+function attemptDisplayOrdinal(
+  attempt: StepExecutionAttempt,
+  index: number,
+  omittedAttempts: number,
+): number {
+  if (attempt.ordinal !== undefined) return attempt.ordinal;
+  if (omittedAttempts === 0 || index === 0) return index + 1;
+  return omittedAttempts + index + 1;
+}
+
+/** Renders one selected execution-path row and its persisted evidence. */
+export function renderStepDetail(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  selectedIndex: number,
+  cache: StepTranscriptViewCache,
+  width: number,
+): Array<string> {
+  const entries = buildPathEntries(snapshot);
+  const entry = entries[selectedIndex];
+  const detail = selectedStepDetail(snapshot, selectedIndex);
+  if (!entry || !detail) {
+    return boxed(
+      theme,
+      'Step Explorer',
+      width,
+      [theme.fg('muted', 'The selected step is no longer available.')],
+      'borderAccent',
+    );
+  }
+
+  const history = detail.historyEntry;
+  const finalArtifact =
+    history?.artifact ??
+    (entry.isCurrent ? snapshot.run.pendingGate?.artifact : undefined);
+  const artifact =
+    finalArtifact === undefined ? undefined : boundedArtifact(finalArtifact);
+  const attempts = detail.attempts.flatMap((attempt, index) => [
+    ...(index > 0 ? ['', theme.fg('dim', '─'.repeat(Math.max(1, width)))] : []),
+    ...renderAttempt(
+      theme,
+      snapshot,
+      attempt,
+      attemptDisplayOrdinal(attempt, index, detail.omittedAttempts),
+      cache,
+      width,
+    ),
+  ]);
+  const currentReason =
+    entry.isCurrent && snapshot.run.pauseReason
+      ? snapshot.run.pauseReason
+      : undefined;
+  const body = [
+    ...keyValueLines(theme, 'workflow', snapshot.run.workflowId, width),
+    ...keyValueLines(theme, 'run', snapshot.run.runId, width, 'muted'),
+    ...keyValueLines(theme, 'step', entry.stepId, width),
+    ...keyValueLines(theme, 'visit', String(entry.visit), width),
+    ...keyValueLines(theme, 'status', entry.status, width),
+    ...(history
+      ? [
+          ...keyValueLines(theme, 'outcome', history.outcome, width, 'success'),
+          ...keyValueLines(theme, 'summary', history.summary, width),
+        ]
+      : []),
+    ...(currentReason
+      ? keyValueLines(theme, 'reason', currentReason, width, 'warning')
+      : []),
+    ...(entry.isCurrent && snapshot.run.gateFeedback
+      ? keyValueLines(
+          theme,
+          'feedback',
+          snapshot.run.gateFeedback,
+          width,
+          'warning',
+        )
+      : []),
+    ...(history?.workspaceCwd
+      ? keyValueLines(theme, 'workspace', history.workspaceCwd, width)
+      : entry.isCurrent && snapshot.run.cwd
+        ? keyValueLines(theme, 'workspace', snapshot.run.cwd, width)
+        : []),
+    ...(artifact
+      ? [
+          '',
+          theme.bold('Final/review artifact'),
+          ...wrapPlain(
+            `${artifact.value}${
+              artifact.truncated
+                ? '\n… [artifact truncated in status display]'
+                : ''
+            }`,
+            width,
+            theme,
+          ),
+        ]
+      : []),
+    '',
+    ...(detail.omittedAttempts > 0
+      ? [
+          theme.fg(
+            'warning',
+            `${detail.omittedAttempts} attempt${
+              detail.omittedAttempts === 1 ? ' was' : 's were'
+            } compacted from the bounded checkpoint trace; retained attempt numbers preserve the chronological gap.`,
+          ),
+          '',
+        ]
+      : []),
+    ...(attempts.length > 0
+      ? attempts
+      : [
+          theme.fg(
+            'muted',
+            'No execution trace was recorded. This step may predate the step-explorer feature.',
+          ),
+        ]),
+  ];
+  return boxed(
+    theme,
+    `Step Explorer · ${entry.title} · visit ${entry.visit}`,
+    width,
+    body,
+    'borderAccent',
+  );
+}

package/src/workflow-status/render-summary.ts

@@ -25,9 +25,11 @@ export function renderHeaderLines(
   width: number,
 ): Array<string> {
   const { run } = snapshot;
+  const command = snapshot.workflow?.definition.command;
   const firstLine = [
     statusGlyph(theme, runDisplayStatus(run), snapshot.now),
     theme.bold(inline(run.workflowId)),
+    ...(command ? [theme.fg('accent', `/${inline(command)}`)] : []),
     statusBadge(theme, run.status),
     theme.fg('muted', '·'),
     theme.fg(
@@ -62,6 +64,23 @@ export function renderSummaryLines(
   const { run, workflow } = snapshot;
   const lines = [
     ...keyValueLines(theme, 'workflow', run.workflowId, width),
+    ...(workflow
+      ? [
+          ...keyValueLines(
+            theme,
+            'command',
+            `/${workflow.definition.command}`,
+            width,
+            'accent',
+          ),
+          ...keyValueLines(
+            theme,
+            'about',
+            workflow.definition.description,
+            width,
+          ),
+        ]
+      : []),
     ...keyValueLines(theme, 'run', run.runId, width),
     ...keyValueLines(
       theme,
@@ -91,6 +110,9 @@ export function renderSummaryLines(
     ),
   ];
 
+  if (run.cwd && run.startCwd && run.cwd !== run.startCwd) {
+    lines.push(...keyValueLines(theme, 'workspace', run.cwd, width, 'accent'));
+  }
   const execution = formatExecution(snapshot.execution);
   if (execution) {
     lines.push(

package/src/workflow-status/transcript-reader.ts

@@ -0,0 +1,231 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import {
+  MAX_STEP_TRACE_LOG_CHARS,
+  MAX_STEP_TRACE_LOG_EVENTS,
+  type SubagentTranscriptReference,
+} from '../engine/state.ts';
+import {
+  redactStepLogText,
+  redactStepLogValue,
+  sanitizeStepLogText,
+  stepLogLinesFromMessage,
+} from '../step-log.ts';
+
+const MAX_TRANSCRIPT_BYTES = 2 * 1024 * 1024;
+
+export type StepTranscriptLog =
+  | {
+      readonly status: 'available';
+      readonly lines: ReadonlyArray<string>;
+      readonly truncated: boolean;
+    }
+  | {
+      readonly status: 'unavailable';
+      readonly reason: string;
+    };
+
+type UnknownRecord = Readonly<Record<string, unknown>>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const pathFromRoot = relative(resolve(root), resolve(candidate));
+  return (
+    pathFromRoot !== '' &&
+    pathFromRoot !== '..' &&
+    !pathFromRoot.startsWith(`..${sep}`) &&
+    !isAbsolute(pathFromRoot)
+  );
+}
+
+function hasSafeIdentity(reference: SubagentTranscriptReference): boolean {
+  return (
+    isAbsolute(reference.trustedRoot) &&
+    isAbsolute(reference.sessionFile) &&
+    !reference.trustedRoot.includes('\0') &&
+    !reference.sessionFile.includes('\0') &&
+    reference.runId.length > 0 &&
+    !reference.runId.includes('\0') &&
+    !reference.runId.includes('/') &&
+    !reference.runId.includes('\\') &&
+    reference.runId !== '.' &&
+    reference.runId !== '..' &&
+    Number.isSafeInteger(reference.childIndex) &&
+    reference.childIndex >= 0 &&
+    resolve(reference.sessionFile) ===
+      resolve(
+        reference.trustedRoot,
+        reference.runId,
+        `run-${reference.childIndex}`,
+        'session.jsonl',
+      )
+  );
+}
+
+export {
+  redactStepDetailText as redactStatusDetailText,
+  redactStepLogText as redactStatusLogText,
+  sanitizeStepLogText as sanitizeStatusLogText,
+} from '../step-log.ts';
+
+function transcriptEntryLines(entry: unknown): Array<string> {
+  if (!isRecord(entry)) return [];
+  if (entry.type === 'custom_message') {
+    const customType =
+      typeof entry.customType === 'string' ? entry.customType : 'custom';
+    const content =
+      typeof entry.content === 'string'
+        ? redactStepLogText(entry.content)
+        : redactStepLogValue(entry.details);
+    return content
+      ? [`event ${sanitizeStepLogText(customType)}\n${content}`]
+      : [];
+  }
+  if (entry.type !== 'message' || !isRecord(entry.message)) return [];
+  return stepLogLinesFromMessage(entry.message);
+}
+
+function parseTranscript(
+  content: string,
+  sourceTruncated: boolean,
+): StepTranscriptLog {
+  const lines: Array<string> = [];
+  let chars = 0;
+  let truncated = sourceTruncated;
+  for (const rawLine of content.split('\n')) {
+    if (!rawLine.trim()) continue;
+    let entry: unknown;
+    try {
+      entry = JSON.parse(rawLine);
+    } catch {
+      continue;
+    }
+    for (const line of transcriptEntryLines(entry)) {
+      if (
+        lines.length >= MAX_STEP_TRACE_LOG_EVENTS ||
+        chars + line.length > MAX_STEP_TRACE_LOG_CHARS
+      ) {
+        truncated = true;
+        break;
+      }
+      lines.push(line);
+      chars += line.length;
+    }
+    if (
+      lines.length >= MAX_STEP_TRACE_LOG_EVENTS ||
+      chars >= MAX_STEP_TRACE_LOG_CHARS
+    ) {
+      break;
+    }
+  }
+  return { status: 'available', lines, truncated };
+}
+
+/**
+ * Reads one child transcript through a confined, no-follow, stable prefix.
+ *
+ * The private child-policy user message is never rendered. Callers display
+ * the separately persisted policy-envelope-free task body instead.
+ */
+export async function readStepTranscript(
+  reference: SubagentTranscriptReference,
+): Promise<StepTranscriptLog> {
+  if (!hasSafeIdentity(reference)) {
+    return {
+      status: 'unavailable',
+      reason: 'The recorded child transcript identity is invalid.',
+    };
+  }
+  try {
+    const runDirectory = resolve(reference.trustedRoot, reference.runId);
+    const childDirectory = resolve(runDirectory, `run-${reference.childIndex}`);
+    const [runDirectoryInfo, childDirectoryInfo] = await Promise.all([
+      lstat(runDirectory),
+      lstat(childDirectory),
+    ]);
+    if (
+      runDirectoryInfo.isSymbolicLink() ||
+      !runDirectoryInfo.isDirectory() ||
+      childDirectoryInfo.isSymbolicLink() ||
+      !childDirectoryInfo.isDirectory()
+    ) {
+      return {
+        status: 'unavailable',
+        reason:
+          'The recorded child transcript directory identity is not trusted.',
+      };
+    }
+    const inspected = await lstat(reference.sessionFile);
+    if (inspected.isSymbolicLink() || !inspected.isFile()) {
+      return {
+        status: 'unavailable',
+        reason: 'The recorded child transcript is not a regular file.',
+      };
+    }
+    const [canonicalRoot, canonicalSession] = await Promise.all([
+      realpath(reference.trustedRoot),
+      realpath(reference.sessionFile),
+    ]);
+    const canonicalExpected = resolve(
+      canonicalRoot,
+      reference.runId,
+      `run-${reference.childIndex}`,
+      'session.jsonl',
+    );
+    if (
+      !isWithin(canonicalRoot, canonicalSession) ||
+      canonicalSession !== canonicalExpected
+    ) {
+      return {
+        status: 'unavailable',
+        reason:
+          'The recorded child transcript does not match its trusted canonical identity.',
+      };
+    }
+
+    const handle = await open(
+      canonicalSession,
+      constants.O_RDONLY | constants.O_NOFOLLOW,
+    );
+    try {
+      const before = await handle.stat();
+      if (!before.isFile()) {
+        return {
+          status: 'unavailable',
+          reason: 'The recorded child transcript is not readable.',
+        };
+      }
+      const bytesToRead = Math.min(before.size, MAX_TRANSCRIPT_BYTES);
+      const buffer = Buffer.alloc(bytesToRead);
+      const { bytesRead } = await handle.read(buffer, 0, bytesToRead, 0);
+      const after = await handle.stat();
+      if (
+        after.dev !== before.dev ||
+        after.ino !== before.ino ||
+        after.size !== before.size ||
+        after.mtimeMs !== before.mtimeMs
+      ) {
+        return {
+          status: 'unavailable',
+          reason: 'The child transcript changed while it was being read.',
+        };
+      }
+      return parseTranscript(
+        buffer.subarray(0, bytesRead).toString('utf8'),
+        before.size > bytesToRead,
+      );
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return {
+      status: 'unavailable',
+      reason:
+        'The recorded child transcript is missing or cannot be read safely.',
+    };
+  }
+}

package/src/workflow-status/types.ts

@@ -2,6 +2,8 @@ import type { Theme, ThemeColor } from '@earendil-works/pi-coding-agent';
 import type { TUI } from '@earendil-works/pi-tui';
 import type { LoadedWorkflow } from '../config/types.ts';
 import type { WorkflowRun, WorkflowRunStatus } from '../engine/state.ts';
+import type { StepExecutionAttempt } from '../engine/state.ts';
+import type { StepTranscriptLog } from './transcript-reader.ts';
 
 export type WorkflowStatusExecution =
   | {
@@ -28,6 +30,8 @@ export type StatusViewTui = Pick<TUI, 'requestRender'> & {
 };
 
 export type PathEntry = {
+  readonly index: number;
+  readonly historyIndex?: number;
   readonly stepId: string;
   readonly title: string;
   readonly status: StepDisplayStatus;
@@ -36,5 +40,9 @@ export type PathEntry = {
   readonly isCurrent: boolean;
 };
 
+export type StepTranscriptLoader = (
+  attempt: Extract<StepExecutionAttempt, { readonly kind: 'subagent' }>,
+) => Promise<StepTranscriptLog>;
+
 export type WorkflowStatusThemeColor = ThemeColor;
 export type WorkflowStatusTheme = Pick<Theme, 'fg' | 'bg' | 'bold'>;