@navels/neal 0.1.0

package/dist/neal/run-lock.js

@@ -0,0 +1,334 @@
+import { hostname } from 'node:os';
+import process from 'node:process';
+import { readFileSync, rmSync } from 'node:fs';
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { writeTextAtomic } from './atomic-write.js';
+import { ACTIVE_RUN_LOCK_FILE, getActiveRunLockPath as getStorageActiveRunLockPath } from './storage-paths.js';
+export class ActiveRunLockError extends Error {
+    kind;
+    lockPath;
+    lock;
+    constructor(kind, lockPath, lock, message) {
+        super(message);
+        this.name = 'ActiveRunLockError';
+        this.kind = kind;
+        this.lockPath = lockPath;
+        this.lock = lock;
+    }
+}
+const LOCK_VERSION = 1;
+export function getActiveRunLockPath(cwd) {
+    return getStorageActiveRunLockPath(cwd);
+}
+export async function inspectActiveRunLock(cwd, requestedRunId) {
+    const lockPath = getActiveRunLockPath(resolve(cwd));
+    let lock;
+    try {
+        lock = await readActiveRunLock(lockPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return { kind: 'none' };
+        }
+        return {
+            kind: 'unreadable',
+            lockPath,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (lock.hostname !== hostname()) {
+        return {
+            kind: 'cross_host',
+            runId: lock.runId,
+            lockPath,
+            pid: lock.pid,
+            hostname: lock.hostname,
+        };
+    }
+    const live = isProcessAlive(lock.pid);
+    if (lock.runId === requestedRunId) {
+        return {
+            kind: live ? 'live_same_run' : 'stale_same_run',
+            runId: lock.runId,
+            lockPath,
+            pid: lock.pid,
+            hostname: lock.hostname,
+        };
+    }
+    return {
+        kind: live ? 'live_different_run' : 'stale_different_run',
+        runId: lock.runId,
+        lockPath,
+        pid: lock.pid,
+        hostname: lock.hostname,
+    };
+}
+export async function clearStaleActiveRunLockForResume(cwd, evidence) {
+    if (evidence.kind !== 'stale_same_run' && evidence.kind !== 'stale_different_run') {
+        return;
+    }
+    const lockPath = evidence.lockPath ?? getActiveRunLockPath(resolve(cwd));
+    let lock;
+    try {
+        lock = await readActiveRunLock(lockPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return;
+        }
+        throw error;
+    }
+    if (lock.hostname !== hostname() ||
+        lock.runId !== evidence.runId ||
+        lock.pid !== evidence.pid ||
+        isProcessAlive(lock.pid)) {
+        return;
+    }
+    await rm(lockPath, { force: true });
+}
+export async function acquireActiveRunLock(args) {
+    const cwd = resolve(args.cwd);
+    const lockPath = getActiveRunLockPath(cwd);
+    const now = new Date().toISOString();
+    const lock = {
+        version: LOCK_VERSION,
+        runId: args.runId,
+        runStatePath: toRepoRelativePath(cwd, args.runStatePath),
+        planDoc: args.planDoc,
+        topLevelMode: args.topLevelMode,
+        pid: process.pid,
+        hostname: hostname(),
+        cwd,
+        startedAt: now,
+        updatedAt: now,
+    };
+    await mkdir(dirname(lockPath), { recursive: true });
+    try {
+        const file = await open(lockPath, 'wx');
+        try {
+            await file.writeFile(JSON.stringify(lock, null, 2) + '\n', 'utf8');
+        }
+        finally {
+            await file.close();
+        }
+        return createOwnedHandle(lockPath, lock);
+    }
+    catch (error) {
+        if (!isFileExistsError(error)) {
+            throw error;
+        }
+    }
+    const existing = await readActiveRunLock(lockPath).catch((error) => {
+        throw new ActiveRunLockError('unreadable', lockPath, null, [
+            '[neal] could not read the active Neal writer lock',
+            `[neal] lock: ${lockPath}`,
+            `[neal] error: ${error instanceof Error ? error.message : String(error)}`,
+            '[neal] inspect the lock file before starting another writer run.',
+        ].join('\n'));
+    });
+    assertCanShareExistingLock(lockPath, existing, args.runId);
+    return {
+        lockPath,
+        lock: existing,
+        acquired: false,
+        async release() { },
+        async refresh() { },
+    };
+}
+export async function refreshActiveRunLock(args) {
+    const cwd = resolve(args.cwd);
+    const lockPath = getActiveRunLockPath(cwd);
+    let lock;
+    try {
+        lock = await readActiveRunLock(lockPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return;
+        }
+        throw error;
+    }
+    if (lock.runId !== args.runId || lock.pid !== process.pid || lock.hostname !== hostname()) {
+        return;
+    }
+    const nextLock = {
+        ...lock,
+        runStatePath: toRepoRelativePath(cwd, args.runStatePath),
+        planDoc: args.planDoc,
+        topLevelMode: args.topLevelMode,
+        updatedAt: new Date().toISOString(),
+    };
+    // Replace the lock via temp-file rename so a crash mid-refresh can never
+    // leave a truncated lock that later commands classify as unreadable.
+    await writeTextAtomic(lockPath, JSON.stringify(nextLock, null, 2) + '\n');
+}
+export async function releaseActiveRunLock(cwd, runId) {
+    const lockPath = getActiveRunLockPath(resolve(cwd));
+    let lock;
+    try {
+        lock = await readActiveRunLock(lockPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return;
+        }
+        throw error;
+    }
+    if (lock.runId !== runId || lock.pid !== process.pid || lock.hostname !== hostname()) {
+        return;
+    }
+    await rm(lockPath, { force: true });
+}
+export function releaseActiveRunLockSync(cwd, runId) {
+    const lockPath = getActiveRunLockPath(resolve(cwd));
+    let lock;
+    try {
+        lock = parseActiveRunLock(JSON.parse(readFileSync(lockPath, 'utf8')), lockPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return;
+        }
+        return;
+    }
+    if (lock.runId !== runId || lock.pid !== process.pid || lock.hostname !== hostname()) {
+        return;
+    }
+    rmSync(lockPath, { force: true });
+}
+export async function readActiveRunLock(lockPathOrCwd) {
+    const lockPath = lockPathOrCwd.endsWith(ACTIVE_RUN_LOCK_FILE) ? lockPathOrCwd : getActiveRunLockPath(lockPathOrCwd);
+    const content = await readFile(lockPath, 'utf8');
+    return parseActiveRunLock(JSON.parse(content), lockPath);
+}
+function createOwnedHandle(lockPath, lock) {
+    return {
+        lockPath,
+        lock,
+        acquired: true,
+        release: () => releaseActiveRunLock(lock.cwd, lock.runId),
+        refresh: () => refreshActiveRunLock({
+            cwd: lock.cwd,
+            runId: lock.runId,
+            runStatePath: lock.runStatePath,
+            planDoc: lock.planDoc,
+            topLevelMode: lock.topLevelMode,
+        }),
+    };
+}
+function assertCanShareExistingLock(lockPath, lock, requestedRunId) {
+    if (lock.hostname !== hostname()) {
+        throw new ActiveRunLockError('cross_host', lockPath, lock, formatCrossHostLockMessage(lockPath, lock));
+    }
+    if (!isProcessAlive(lock.pid)) {
+        throw new ActiveRunLockError('stale_same_host', lockPath, lock, formatStaleLockMessage(lockPath, lock));
+    }
+    if (lock.runId !== requestedRunId) {
+        throw new ActiveRunLockError('active_different_run', lockPath, lock, formatActiveLockMessage(lockPath, lock));
+    }
+    // Sharing an existing lock is only legitimate for the same process
+    // re-entering its own run. A live same-run lock under another pid means a
+    // concurrent writer already owns this run's state and worktree.
+    if (lock.pid !== process.pid) {
+        throw new ActiveRunLockError('active_same_run', lockPath, lock, formatActiveSameRunLockMessage(lockPath, lock));
+    }
+}
+function formatActiveLockMessage(lockPath, lock) {
+    return [
+        '[neal] another Neal writer run is active in this checkout',
+        `[neal] active run: ${lock.runId}`,
+        `[neal] plan: ${lock.planDoc}`,
+        `[neal] pid: ${lock.pid}`,
+        `[neal] lock: ${lockPath}`,
+        `[neal] use \`neal resume --run ${lock.runId}\` to continue it, or wait for the active run to finish.`,
+    ].join('\n');
+}
+function formatActiveSameRunLockMessage(lockPath, lock) {
+    return [
+        '[neal] another Neal process is already resuming this run',
+        `[neal] active run: ${lock.runId}`,
+        `[neal] plan: ${lock.planDoc}`,
+        `[neal] owning pid: ${lock.pid}`,
+        `[neal] lock: ${lockPath}`,
+        `[neal] wait for that process to finish, or inspect it with \`neal status --run ${lock.runId}\`.`,
+    ].join('\n');
+}
+function formatStaleLockMessage(lockPath, lock) {
+    return [
+        '[neal] stale Neal writer lock found in this checkout',
+        `[neal] active run: ${lock.runId}`,
+        `[neal] plan: ${lock.planDoc}`,
+        `[neal] pid: ${lock.pid}`,
+        `[neal] lock: ${lockPath}`,
+        '[neal] no process with that PID is running on this host.',
+        `[neal] inspect the run, then remove ${lockPath} if no Neal writer process is active.`,
+        `[neal] exact resume command: neal resume --run ${lock.runId}`,
+    ].join('\n');
+}
+function formatCrossHostLockMessage(lockPath, lock) {
+    return [
+        '[neal] Neal writer lock belongs to another host',
+        `[neal] active run: ${lock.runId}`,
+        `[neal] plan: ${lock.planDoc}`,
+        `[neal] pid: ${lock.pid}`,
+        `[neal] host: ${lock.hostname}`,
+        `[neal] lock: ${lockPath}`,
+        '[neal] inspect the other host before removing this lock or starting another writer run.',
+        `[neal] exact resume command on that checkout: neal resume --run ${lock.runId}`,
+    ].join('\n');
+}
+function parseActiveRunLock(value, lockPath) {
+    if (!value || typeof value !== 'object') {
+        throw new Error(`Invalid active Neal writer lock at ${lockPath}: expected object`);
+    }
+    const lock = value;
+    if (lock.version !== LOCK_VERSION ||
+        typeof lock.runId !== 'string' ||
+        typeof lock.runStatePath !== 'string' ||
+        typeof lock.planDoc !== 'string' ||
+        (lock.topLevelMode !== 'plan' && lock.topLevelMode !== 'execute') ||
+        typeof lock.pid !== 'number' ||
+        typeof lock.hostname !== 'string' ||
+        typeof lock.cwd !== 'string' ||
+        typeof lock.startedAt !== 'string' ||
+        typeof lock.updatedAt !== 'string') {
+        throw new Error(`Invalid active Neal writer lock at ${lockPath}: malformed lock`);
+    }
+    return {
+        version: LOCK_VERSION,
+        runId: lock.runId,
+        runStatePath: lock.runStatePath,
+        planDoc: lock.planDoc,
+        topLevelMode: lock.topLevelMode,
+        pid: lock.pid,
+        hostname: lock.hostname,
+        cwd: lock.cwd,
+        startedAt: lock.startedAt,
+        updatedAt: lock.updatedAt,
+    };
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' ? error.code : null;
+        return code === 'EPERM';
+    }
+}
+function toRepoRelativePath(cwd, path) {
+    const absolutePath = isAbsolute(path) ? path : resolve(cwd, path);
+    const relativePath = relative(cwd, absolutePath);
+    return relativePath && !relativePath.startsWith('..') && !isAbsolute(relativePath) ? relativePath : absolutePath;
+}
+function isFileExistsError(error) {
+    return Boolean(error && typeof error === 'object' && error.code === 'EEXIST');
+}
+function isNotFoundError(error) {
+    return Boolean(error && typeof error === 'object' && error.code === 'ENOENT');
+}

package/dist/neal/run-metrics.js

@@ -0,0 +1,355 @@
+import { formatMaybePublicPhase } from './phase-display.js';
+const EMPTY_USAGE = {
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    cacheCreationInputTokens: 0,
+    cacheReadInputTokens: 0,
+    outputTokens: 0,
+    reasoningOutputTokens: 0,
+    totalTokens: 0,
+};
+function validIso(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+function timeMs(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function addUsage(target, value) {
+    if (!isRecord(value)) {
+        return;
+    }
+    target.inputTokens += numberValue(value.input_tokens) + numberValue(value.inputTokens);
+    target.cachedInputTokens += numberValue(value.cached_input_tokens) + numberValue(value.cachedInputTokens);
+    target.cacheCreationInputTokens +=
+        numberValue(value.cache_creation_input_tokens) + numberValue(value.cacheCreationInputTokens);
+    target.cacheReadInputTokens += numberValue(value.cache_read_input_tokens) + numberValue(value.cacheReadInputTokens);
+    target.outputTokens += numberValue(value.output_tokens) + numberValue(value.outputTokens);
+    target.reasoningOutputTokens +=
+        numberValue(value.reasoning_output_tokens) + numberValue(value.reasoningOutputTokens);
+    target.totalTokens += numberValue(value.total_tokens) + numberValue(value.totalTokens);
+}
+function hasUsage(usage) {
+    return Object.values(usage).some((value) => value > 0);
+}
+function cloneEmptyUsage() {
+    return { ...EMPTY_USAGE };
+}
+function usageSortValue(summary) {
+    const usage = summary.usage;
+    return (usage.inputTokens +
+        usage.cachedInputTokens +
+        usage.cacheCreationInputTokens +
+        usage.cacheReadInputTokens +
+        usage.outputTokens +
+        usage.reasoningOutputTokens +
+        usage.totalTokens);
+}
+function providerKey(data) {
+    const provider = stringValue(data.provider) ?? 'unknown';
+    const role = stringValue(data.role) ?? 'unknown';
+    const label = stringValue(data.label);
+    return {
+        provider,
+        role,
+        label,
+        key: `${provider}\0${role}\0${label ?? ''}`,
+    };
+}
+function commandIsNonZero(event) {
+    const exitCode = event.data?.exitCode;
+    if (typeof exitCode === 'number') {
+        return exitCode !== 0;
+    }
+    return event.data?.status === 'failed';
+}
+function commandIsSuccess(event) {
+    return event.data?.exitCode === 0;
+}
+function commandKey(event) {
+    const command = stringValue(event.data?.command);
+    if (!command) {
+        return null;
+    }
+    const cwd = stringValue(event.data?.cwd) ?? '';
+    return `${cwd}\0${command}`;
+}
+function findResolvedNonZeroCommandIndexes(items) {
+    const successfulCommands = new Set();
+    const resolvedIndexes = new Set();
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (!item || item.event.type !== 'provider.command_completed') {
+            continue;
+        }
+        const key = commandKey(item.event);
+        if (!key) {
+            continue;
+        }
+        if (commandIsSuccess(item.event)) {
+            successfulCommands.add(key);
+            continue;
+        }
+        if (commandIsNonZero(item.event) && successfulCommands.has(key)) {
+            resolvedIndexes.add(item.index);
+        }
+    }
+    return resolvedIndexes;
+}
+function createPhase(event, index) {
+    const phase = stringValue(event.data?.phase);
+    if (!phase) {
+        return null;
+    }
+    return {
+        phase,
+        startedAt: validIso(event.ts),
+        completedAt: null,
+        durationMs: null,
+        providerTurns: 0,
+        commandCount: 0,
+        nonZeroCommandCount: 0,
+        resolvedNonZeroCommandCount: 0,
+        unresolvedNonZeroCommandCount: 0,
+        toolEventCount: 0,
+        fileChangeEventCount: 0,
+        startIndex: index,
+        endIndex: null,
+    };
+}
+function completePhase(phase, event, index) {
+    phase.completedAt = validIso(event.ts);
+    phase.endIndex = index;
+    const start = timeMs(phase.startedAt);
+    const end = timeMs(phase.completedAt);
+    phase.durationMs = start !== null && end !== null && end >= start ? end - start : null;
+}
+function findOpenPhase(phases, phaseName) {
+    for (let index = phases.length - 1; index >= 0; index -= 1) {
+        const phase = phases[index];
+        if (phase?.phase === phaseName && phase.endIndex === null) {
+            return phase;
+        }
+    }
+    return null;
+}
+function phaseForEvent(phases, eventIndex) {
+    for (let index = phases.length - 1; index >= 0; index -= 1) {
+        const phase = phases[index];
+        if (!phase || phase.startIndex > eventIndex) {
+            continue;
+        }
+        if (phase.endIndex === null || phase.endIndex >= eventIndex) {
+            return phase;
+        }
+    }
+    return null;
+}
+export function summarizeRunMetrics(events) {
+    const normalizedEvents = events
+        .map((event, index) => ({ event, index, ts: validIso(event.ts) }))
+        .filter((item) => item.ts !== null);
+    const hasDedicatedUsageEvents = normalizedEvents.some((item) => item.event.type === 'provider.usage_reported');
+    const firstTimestamp = normalizedEvents[0]?.ts ?? null;
+    const lastTimestamp = normalizedEvents.at(-1)?.ts ?? null;
+    const firstTime = timeMs(firstTimestamp);
+    const lastTime = timeMs(lastTimestamp);
+    const phases = [];
+    const providers = new Map();
+    let providerTurns = 0;
+    let commandCount = 0;
+    let nonZeroCommandCount = 0;
+    let resolvedNonZeroCommandCount = 0;
+    let unresolvedNonZeroCommandCount = 0;
+    let toolEventCount = 0;
+    let fileChangeEventCount = 0;
+    const resolvedNonZeroCommandIndexes = findResolvedNonZeroCommandIndexes(normalizedEvents);
+    for (const { event, index } of normalizedEvents) {
+        if (event.type === 'phase.start') {
+            const phase = createPhase(event, index);
+            if (phase) {
+                phases.push(phase);
+            }
+        }
+        else if (event.type === 'phase.complete') {
+            const phaseName = stringValue(event.data?.phase);
+            const phase = phaseName ? findOpenPhase(phases, phaseName) : null;
+            if (phase) {
+                completePhase(phase, event, index);
+            }
+        }
+    }
+    for (const { event, index } of normalizedEvents) {
+        const phase = phaseForEvent(phases, index);
+        if (event.type === 'provider.turn_completed') {
+            providerTurns += 1;
+            if (phase) {
+                phase.providerTurns += 1;
+            }
+            const data = event.data ?? {};
+            const identity = providerKey(data);
+            const existing = providers.get(identity.key) ?? {
+                provider: identity.provider,
+                role: identity.role,
+                label: identity.label,
+                turns: 0,
+                usage: cloneEmptyUsage(),
+            };
+            existing.turns += 1;
+            if (!hasDedicatedUsageEvents) {
+                addUsage(existing.usage, data.usage);
+            }
+            providers.set(identity.key, existing);
+        }
+        else if (event.type === 'provider.usage_reported') {
+            const data = event.data ?? {};
+            const identity = providerKey(data);
+            const existing = providers.get(identity.key) ?? {
+                provider: identity.provider,
+                role: identity.role,
+                label: identity.label,
+                turns: 0,
+                usage: cloneEmptyUsage(),
+            };
+            addUsage(existing.usage, data.usage);
+            providers.set(identity.key, existing);
+        }
+        else if (event.type === 'provider.command_completed') {
+            commandCount += 1;
+            if (commandIsNonZero(event)) {
+                nonZeroCommandCount += 1;
+                if (resolvedNonZeroCommandIndexes.has(index)) {
+                    resolvedNonZeroCommandCount += 1;
+                }
+                else {
+                    unresolvedNonZeroCommandCount += 1;
+                }
+            }
+            if (phase) {
+                phase.commandCount += 1;
+                if (commandIsNonZero(event)) {
+                    phase.nonZeroCommandCount += 1;
+                    if (resolvedNonZeroCommandIndexes.has(index)) {
+                        phase.resolvedNonZeroCommandCount += 1;
+                    }
+                    else {
+                        phase.unresolvedNonZeroCommandCount += 1;
+                    }
+                }
+            }
+        }
+        else if (event.type === 'provider.tool_started' || event.type === 'provider.tool_progress') {
+            toolEventCount += 1;
+            if (phase) {
+                phase.toolEventCount += 1;
+            }
+        }
+        else if (event.type === 'provider.file_changed') {
+            fileChangeEventCount += 1;
+            if (phase) {
+                phase.fileChangeEventCount += 1;
+            }
+        }
+    }
+    for (const phase of phases) {
+        if (phase.durationMs !== null || phase.endIndex !== null) {
+            continue;
+        }
+        const start = timeMs(phase.startedAt);
+        const end = timeMs(lastTimestamp);
+        phase.durationMs = start !== null && end !== null && end >= start ? end - start : null;
+    }
+    const publicPhases = phases.map(({ startIndex: _startIndex, endIndex: _endIndex, ...phase }) => phase);
+    return {
+        observedStartedAt: firstTimestamp,
+        observedCompletedAt: lastTimestamp,
+        observedDurationMs: firstTime !== null && lastTime !== null && lastTime >= firstTime ? lastTime - firstTime : null,
+        providerTurns,
+        commandCount,
+        nonZeroCommandCount,
+        resolvedNonZeroCommandCount,
+        unresolvedNonZeroCommandCount,
+        toolEventCount,
+        fileChangeEventCount,
+        phases: publicPhases,
+        providers: [...providers.values()].sort((left, right) => {
+            const turns = right.turns - left.turns;
+            if (turns !== 0) {
+                return turns;
+            }
+            return usageSortValue(right) - usageSortValue(left);
+        }),
+    };
+}
+function formatDuration(value) {
+    if (value === null) {
+        return 'unknown';
+    }
+    const totalSeconds = Math.max(0, Math.round(value / 1_000));
+    const hours = Math.floor(totalSeconds / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+        return `${hours}h ${String(minutes).padStart(2, '0')}m ${String(seconds).padStart(2, '0')}s`;
+    }
+    return `${minutes}m ${String(seconds).padStart(2, '0')}s`;
+}
+function formatNumber(value) {
+    return value === 0 ? '0' : value.toLocaleString('en-US');
+}
+function formatPhaseName(phase) {
+    return formatMaybePublicPhase(phase) ?? phase;
+}
+function formatPhaseDuration(phase) {
+    const formatted = formatDuration(phase.durationMs);
+    return phase.completedAt || phase.durationMs === null ? formatted : `>= ${formatted}`;
+}
+function formatProviderName(summary) {
+    const label = summary.label ? `:${summary.label}` : '';
+    return `${summary.provider} / ${summary.role}${label}`;
+}
+function usageCell(value) {
+    return value > 0 ? formatNumber(value) : '-';
+}
+export function renderRunMetricsMarkdown(metrics) {
+    const commandSummary = metrics.resolvedNonZeroCommandCount > 0
+        ? `- Commands: ${metrics.commandCount} total, ${metrics.unresolvedNonZeroCommandCount} unresolved non-zero or failed, ${metrics.resolvedNonZeroCommandCount} resolved by later passing rerun`
+        : `- Commands: ${metrics.commandCount} total, ${metrics.nonZeroCommandCount} non-zero or failed`;
+    const lines = [
+        `- Observed duration: ${formatDuration(metrics.observedDurationMs)}`,
+        `- Provider turns: ${metrics.providerTurns}`,
+        commandSummary,
+        `- Tool events: ${metrics.toolEventCount}`,
+        `- File change events: ${metrics.fileChangeEventCount}`,
+    ];
+    if (metrics.phases.length > 0) {
+        lines.push('', '### Phase Timing', '', '| Phase | Duration | Provider turns | Commands | Non-zero commands | Tool events | File changes |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: |', ...metrics.phases.map((phase) => `| ${formatPhaseName(phase.phase)} | ${formatPhaseDuration(phase)} | ${phase.providerTurns} | ${phase.commandCount} | ${phase.nonZeroCommandCount} | ${phase.toolEventCount} | ${phase.fileChangeEventCount} |`));
+    }
+    const providersWithUsage = metrics.providers.filter((provider) => provider.turns > 0 || hasUsage(provider.usage));
+    if (providersWithUsage.length > 0) {
+        lines.push('', '### Provider Usage', '', '| Provider / role | Turns | Input | Cached input | Cache created | Cache read | Output | Reasoning output | Total |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |', ...providersWithUsage.map((provider) => {
+            const usage = provider.usage;
+            return `| ${formatProviderName(provider)} | ${provider.turns} | ${usageCell(usage.inputTokens)} | ${usageCell(usage.cachedInputTokens)} | ${usageCell(usage.cacheCreationInputTokens)} | ${usageCell(usage.cacheReadInputTokens)} | ${usageCell(usage.outputTokens)} | ${usageCell(usage.reasoningOutputTokens)} | ${usageCell(usage.totalTokens)} |`;
+        }));
+    }
+    else {
+        lines.push('', '### Provider Usage', '', '- No provider usage events recorded.');
+    }
+    return lines.join('\n');
+}

package/dist/neal/run-narrative-types.js

@@ -0,0 +1 @@
+export {};