@agwab/pi-workflow 0.3.0 → 0.4.0

package/dist/types.d.ts

@@ -167,6 +167,10 @@ export interface ArtifactGraphStageSpec {
     from?: string | string[] | {
         source: string;
         path: string;
+        streaming?: {
+            enabled: true;
+            minChunk?: number;
+        };
     };
     after?: string | string[];
     sourcePolicy?: "success" | "partial" | "require-success";
@@ -177,6 +181,7 @@ export interface ArtifactGraphStageSpec {
     inputPolicy?: {
         requiredReads?: string[];
         enforcement?: "fail";
+        artifactAccess?: "enabled" | "none";
     };
     output?: {
         controlSchema?: string;
@@ -188,6 +193,9 @@ export interface ArtifactGraphStageSpec {
             minItems?: number;
         };
         maxDigestChars?: number;
+        partial?: {
+            paths: string[];
+        };
     };
     each?: Record<string, unknown>;
     stages?: ArtifactGraphStageSpec[];
@@ -433,8 +441,12 @@ export interface CompiledArtifactGraphTask {
         controlSchema?: string;
         controlSchemaPath?: string;
         maxDigestChars?: number;
+        partial?: {
+            paths: string[];
+        };
     };
     requiredReads: string[];
+    artifactAccess: "enabled" | "none";
     sourceProjection?: {
         include?: string[];
         maxChars?: number;
@@ -486,6 +498,10 @@ export interface CompiledTask {
     };
     foreachGenerated?: {
         placeholderSpecId: string;
+        itemHash?: string;
+        itemSourceSpecId?: string;
+        itemSourceKind?: "control" | "partial";
+        itemRef?: string;
     };
     loopChild?: CompiledLoopChildTaskRef;
     loopPlaceholder?: {
@@ -499,6 +515,80 @@ export interface CompiledTask {
 }
 export type TaskRunStatus = "pending" | "running" | "blocked" | "completed" | "failed" | "skipped" | "interrupted";
 export type WorkflowRunStatus = "running" | "blocked" | "completed" | "failed" | "interrupted";
+export interface WorkflowTaskUsageValues {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    totalTokens?: number | null;
+    cachedInputTokens?: number | null;
+    cacheCreationInputTokens?: number | null;
+    cacheReadInputTokens?: number | null;
+    reasoningTokens?: number | null;
+    costUsd?: number | null;
+}
+export interface WorkflowTaskUsageAttemptRecord extends WorkflowTaskUsageValues {
+    source: string;
+    capturedAt: string;
+    provider?: string;
+    model?: string;
+    thinking?: ThinkingLevel | string;
+    backendRunId?: string;
+    backendAttemptId?: string;
+    unavailable?: true;
+    raw?: unknown;
+}
+export interface WorkflowTaskUsageAggregateRecord extends WorkflowTaskUsageValues {
+    attempts: number;
+    incomplete?: boolean;
+}
+export interface WorkflowTaskUsageRecord extends WorkflowTaskUsageValues {
+    source: "pi-subagent";
+    capturedAt: string;
+    provider?: string;
+    model?: string;
+    thinking?: ThinkingLevel | string;
+    incomplete?: boolean;
+    aggregate?: WorkflowTaskUsageAggregateRecord;
+    attempts?: WorkflowTaskUsageAttemptRecord[];
+}
+export interface WorkflowTaskTimingAttemptRecord {
+    source: string;
+    capturedAt: string;
+    backendRunId?: string;
+    backendAttemptId?: string;
+    launchQueuedAt?: string;
+    launchStartedAt?: string;
+    launchCompletedAt?: string;
+    launchWaitMs?: number;
+    launchDurationMs?: number;
+    executionStartedAt?: string;
+    executionCompletedAt?: string;
+    executionMs?: number | null;
+    totalMs?: number;
+}
+export interface WorkflowTaskTimingAggregateRecord {
+    attempts: number;
+    launchWaitMs?: number | null;
+    launchDurationMs?: number | null;
+    executionMs?: number | null;
+    totalMs?: number | null;
+    incomplete?: boolean;
+}
+export interface WorkflowTaskTimingRecord {
+    source: "pi-workflow";
+    capturedAt: string;
+    launchQueuedAt?: string;
+    launchStartedAt?: string;
+    launchCompletedAt?: string;
+    launchWaitMs?: number;
+    launchDurationMs?: number;
+    launchSlotReleaseDelayMs?: number;
+    executionStartedAt?: string;
+    executionCompletedAt?: string;
+    executionMs?: number | null;
+    totalMs?: number;
+    aggregate?: WorkflowTaskTimingAggregateRecord;
+    attempts?: WorkflowTaskTimingAttemptRecord[];
+}
 export interface WorkflowTaskRunRecord {
     taskId: string;
     specId: string;
@@ -537,6 +627,8 @@ export interface WorkflowTaskRunRecord {
     startedAt?: string;
     completedAt?: string;
     elapsedMs?: number;
+    usage?: WorkflowTaskUsageRecord;
+    timing?: WorkflowTaskTimingRecord;
     exitCode?: number;
     files: {
         systemPrompt: string;
@@ -567,6 +659,10 @@ export interface WorkflowTaskRunRecord {
     };
     foreachGenerated?: {
         placeholderSpecId: string;
+        itemHash?: string;
+        itemSourceSpecId?: string;
+        itemSourceKind?: "control" | "partial";
+        itemRef?: string;
     };
     launchRetry?: {
         attempts: number;
@@ -660,7 +756,11 @@ export interface WorkflowIndexRecord {
         rootRunId?: string;
         round?: number;
         fanout?: unknown[];
-        tasks: Array<{
+        /**
+         * Deprecated compatibility projection. New index writes omit task rows;
+         * consumers that need task-level details should load runJson/run.json.
+         */
+        tasks?: Array<{
             taskId: string;
             displayName: string;
             agent: string;

package/dist/verification-ontology.d.ts

@@ -0,0 +1,31 @@
+export declare const VERIFICATION_STATUS: Readonly<{
+    readonly VERIFIED: "verified";
+    readonly PARTIALLY_SUPPORTED: "partially_supported";
+    readonly UNSUPPORTED: "unsupported";
+    readonly CONFLICTING: "conflicting";
+    readonly VERIFICATION_BLOCKED: "verification_blocked";
+    readonly UNVERIFIED: "unverified";
+}>;
+export type VerificationStatus = (typeof VERIFICATION_STATUS)[keyof typeof VERIFICATION_STATUS];
+export type TerminalVerificationStatus = Exclude<VerificationStatus, (typeof VERIFICATION_STATUS)["UNVERIFIED"]>;
+export declare const VERIFICATION_STATUS_VALUES: readonly ["verified", "partially_supported", "unsupported", "conflicting", "verification_blocked"];
+export declare const VERIFICATION_STATUS_BUCKETS: Readonly<{
+    readonly verified: "verified";
+    readonly partially_supported: "partiallySupported";
+    readonly unsupported: "unsupported";
+    readonly conflicting: "conflicting";
+    readonly verification_blocked: "verificationBlocked";
+}>;
+export declare const VERIFICATION_STATUS_LABELS: Readonly<{
+    readonly verified: "verified";
+    readonly partially_supported: "partially supported";
+    readonly unsupported: "unsupported";
+    readonly conflicting: "conflicting";
+    readonly verification_blocked: "verification blocked";
+    readonly unverified: "unverified";
+}>;
+export declare function canonicalVerificationStatus(status: unknown): VerificationStatus;
+export declare function verificationStatusBucket(status: unknown): string;
+export declare function isVerifiedStatus(status: unknown): boolean;
+export declare function isVerificationBlockedStatus(status: unknown): boolean;
+export declare function isNonVerifiedTerminalStatus(status: unknown): boolean;

package/dist/verification-ontology.js

@@ -0,0 +1,66 @@
+export const VERIFICATION_STATUS = Object.freeze({
+    VERIFIED: "verified",
+    PARTIALLY_SUPPORTED: "partially_supported",
+    UNSUPPORTED: "unsupported",
+    CONFLICTING: "conflicting",
+    VERIFICATION_BLOCKED: "verification_blocked",
+    UNVERIFIED: "unverified",
+});
+export const VERIFICATION_STATUS_VALUES = Object.freeze([
+    VERIFICATION_STATUS.VERIFIED,
+    VERIFICATION_STATUS.PARTIALLY_SUPPORTED,
+    VERIFICATION_STATUS.UNSUPPORTED,
+    VERIFICATION_STATUS.CONFLICTING,
+    VERIFICATION_STATUS.VERIFICATION_BLOCKED,
+]);
+export const VERIFICATION_STATUS_BUCKETS = Object.freeze({
+    [VERIFICATION_STATUS.VERIFIED]: "verified",
+    [VERIFICATION_STATUS.PARTIALLY_SUPPORTED]: "partiallySupported",
+    [VERIFICATION_STATUS.UNSUPPORTED]: "unsupported",
+    [VERIFICATION_STATUS.CONFLICTING]: "conflicting",
+    [VERIFICATION_STATUS.VERIFICATION_BLOCKED]: "verificationBlocked",
+});
+export const VERIFICATION_STATUS_LABELS = Object.freeze({
+    [VERIFICATION_STATUS.VERIFIED]: "verified",
+    [VERIFICATION_STATUS.PARTIALLY_SUPPORTED]: "partially supported",
+    [VERIFICATION_STATUS.UNSUPPORTED]: "unsupported",
+    [VERIFICATION_STATUS.CONFLICTING]: "conflicting",
+    [VERIFICATION_STATUS.VERIFICATION_BLOCKED]: "verification blocked",
+    [VERIFICATION_STATUS.UNVERIFIED]: "unverified",
+});
+export function canonicalVerificationStatus(status) {
+    const text = String(status ?? "").trim();
+    if (!text)
+        return VERIFICATION_STATUS.UNVERIFIED;
+    if (text === "partiallySupported") {
+        return VERIFICATION_STATUS.PARTIALLY_SUPPORTED;
+    }
+    if (text === "verificationBlocked" || text === "blocked") {
+        return VERIFICATION_STATUS.VERIFICATION_BLOCKED;
+    }
+    return Object.values(VERIFICATION_STATUS).includes(text)
+        ? text
+        : VERIFICATION_STATUS.UNVERIFIED;
+}
+export function verificationStatusBucket(status) {
+    const canonical = canonicalVerificationStatus(status);
+    return canonical in VERIFICATION_STATUS_BUCKETS
+        ? VERIFICATION_STATUS_BUCKETS[canonical]
+        : "other";
+}
+export function isVerifiedStatus(status) {
+    return canonicalVerificationStatus(status) === VERIFICATION_STATUS.VERIFIED;
+}
+export function isVerificationBlockedStatus(status) {
+    return (canonicalVerificationStatus(status) ===
+        VERIFICATION_STATUS.VERIFICATION_BLOCKED);
+}
+const NON_VERIFIED_TERMINAL_STATUSES = new Set([
+    VERIFICATION_STATUS.PARTIALLY_SUPPORTED,
+    VERIFICATION_STATUS.UNSUPPORTED,
+    VERIFICATION_STATUS.CONFLICTING,
+    VERIFICATION_STATUS.VERIFICATION_BLOCKED,
+]);
+export function isNonVerifiedTerminalStatus(status) {
+    return NON_VERIFIED_TERMINAL_STATUSES.has(canonicalVerificationStatus(status));
+}

package/dist/workflow-artifact-tool.js

@@ -23,7 +23,7 @@ const WORKFLOW_ARTIFACT_KIND_SET = new Set(WORKFLOW_ARTIFACT_KINDS);
 const DEFAULT_MAX_BYTES = 50 * 1024;
 const DEFAULT_MAX_LINES = 2000;
 const SOURCE_NAME_PATTERN = /^[A-Za-z0-9_.:-]+$/;
-const SIMPLE_JSON_PATH_PATTERN = /^(\$|\$(\.[A-Za-z0-9_-]+(\[(\*|\d+|\d*:\d*)\])?)+)$/;
+const SIMPLE_JSON_PATH_PATTERN = /^(\$|\$(\.[A-Za-z0-9_-]+)+)$/;
 const JSON_PATH_SEGMENT_ALIASES = {
     axes: "researchAxes",
     claimVerdicts: "claimVerdictLedger",
@@ -226,14 +226,13 @@ async function readProjectedWorkflowArtifact(options) {
         path: effectivePath,
     });
     const serialized = JSON.stringify(sliced.value, null, 2);
-    const preview = options.maxChars !== undefined && serialized.length > options.maxChars
-        ? serialized.slice(0, options.maxChars)
-        : serialized;
+    const maxChars = options.maxChars ?? DEFAULT_MAX_BYTES;
+    const preview = serialized.length > maxChars ? serialized.slice(0, maxChars) : serialized;
     const projection = {
         path: effectivePath,
         valueType: jsonValueType(resolved),
         ...(options.maxItems === undefined ? {} : { maxItems: options.maxItems }),
-        ...(options.maxChars === undefined ? {} : { maxChars: options.maxChars }),
+        maxChars,
         ...(sliced.totalItems === undefined
             ? {}
             : { totalItems: sliced.totalItems }),
@@ -501,7 +500,7 @@ function normalizeProjectionPath(value) {
     if (path === undefined)
         return undefined;
     if (!SIMPLE_JSON_PATH_PATTERN.test(path)) {
-        throw new Error("path must be $ or a simple dot JSON path like $.claims.items");
+        throw new Error("path must be $ or a simple dot JSON path like $.claims.items; array selectors are not supported");
     }
     return path;
 }

package/dist/workflow-artifacts.d.ts

@@ -4,6 +4,13 @@ export interface WorkflowTelemetrySummary {
     taskCount: number;
     wallClockMs: number | null;
     statusCounts: StatusCounts;
+    completion: {
+        health: "clean" | "repaired" | "incomplete";
+        clean: boolean;
+        repaired: boolean;
+        repairEvents: number;
+        contextLimitFailures: number;
+    };
     retryCounts: {
         output: number;
         launch: number;

package/dist/workflow-artifacts.js

@@ -25,10 +25,21 @@ export function summarizeWorkflowTelemetry(run, options = {}) {
         stage.durationMs += taskDurationMs(task);
         stage.outputBytes += taskOutputBytes;
     }
+    const repairEvents = accumulator.outputRetries +
+        accumulator.launchRetries +
+        accumulator.resumeEvents;
+    const health = completionHealth(tasks, repairEvents, accumulator);
     return {
         taskCount: tasks.length,
         wallClockMs: durationBetween(run.createdAt, run.updatedAt),
         statusCounts,
+        completion: {
+            health,
+            clean: health === "clean",
+            repaired: health === "repaired",
+            repairEvents,
+            contextLimitFailures: accumulator.contextLimitFailures,
+        },
         retryCounts: {
             output: accumulator.outputRetries,
             launch: accumulator.launchRetries,
@@ -50,12 +61,15 @@ function createWorkflowTelemetryAccumulator() {
         launchRetries: 0,
         resumeEvents: 0,
         resumedTasks: 0,
+        contextLimitFailures: 0,
         retryReasons: { output: {}, launch: {} },
         resumeStatusCounts: {},
         outputRepairCounts: { sameSession: 0, newSession: 0, unknown: 0 },
     };
 }
 function accumulateTaskReliability(task, accumulator) {
+    if (taskHasContextLimitFailure(task))
+        accumulator.contextLimitFailures += 1;
     const currentOutputAttempts = positiveCount(task.outputRetry?.attempts);
     accumulator.outputRetries += currentOutputAttempts;
     if (currentOutputAttempts > 0) {
@@ -76,15 +90,29 @@ function accumulateTaskReliability(task, accumulator) {
     for (const event of resumeEvents)
         accumulateResumeEvent(event, accumulator);
 }
+function completionHealth(tasks, repairEvents, accumulator) {
+    const allCompleted = tasks.length > 0 && tasks.every((task) => task.status === "completed");
+    if (!allCompleted)
+        return "incomplete";
+    return repairEvents === 0 && accumulator.contextLimitFailures === 0
+        ? "clean"
+        : "repaired";
+}
 function accumulateResumeEvent(event, accumulator) {
     accumulator.resumeStatusCounts[event.fromStatus] =
         (accumulator.resumeStatusCounts[event.fromStatus] ?? 0) + 1;
+    if (resumeEventHasContextLimitFailure(event))
+        accumulator.contextLimitFailures += 1;
     const previousOutputAttempts = positiveCount(event.outputRetryAttempts);
     accumulator.outputRetries += previousOutputAttempts;
-    if (previousOutputAttempts === 0)
-        return;
-    countReason(accumulator.retryReasons.output, event.outputRetryReason);
-    countRepairMode(accumulator.outputRepairCounts, event.outputRetryRepairMode);
+    if (previousOutputAttempts > 0) {
+        countReason(accumulator.retryReasons.output, event.outputRetryReason);
+        countRepairMode(accumulator.outputRepairCounts, event.outputRetryRepairMode);
+    }
+    const previousLaunchAttempts = positiveCount(event.launchRetryAttempts);
+    accumulator.launchRetries += previousLaunchAttempts;
+    if (previousLaunchAttempts > 0)
+        countReason(accumulator.retryReasons.launch, event.launchRetryReason);
 }
 function positiveCount(value) {
     if (value === undefined || !Number.isFinite(value))
@@ -103,6 +131,29 @@ function countRepairMode(counts, mode) {
     else
         counts.unknown += 1;
 }
+function taskHasContextLimitFailure(task) {
+    return [
+        task.statusDetail,
+        task.lastMessage,
+        task.outputRetry?.reason,
+        task.outputRetry?.message,
+        task.launchRetry?.reason,
+        task.launchRetry?.message,
+    ].some(isContextLimitText);
+}
+function resumeEventHasContextLimitFailure(event) {
+    return [
+        event.fromStatusDetail,
+        event.lastMessage,
+        event.outputRetryReason,
+        event.launchRetryReason,
+    ].some(isContextLimitText);
+}
+function isContextLimitText(value) {
+    const text = value?.toLowerCase() ?? "";
+    return (text.includes("context_or_request_too_large") ||
+        /context (window|length)|maximum context|request too large|token limit/.test(text));
+}
 export function buildSourceContextPacket(run, options = {}) {
     const maxPreviewChars = Math.max(0, Math.floor(options.maxPreviewChars ?? 1200));
     const maxStructuredChars = normalizeOptionalCharCap(options.maxStructuredChars);

package/dist/workflow-fetch-cache-extension.d.ts

@@ -4,6 +4,7 @@ export interface WorkflowFetchCacheConfig {
     runId: string;
     taskId: string;
     cacheDir: string;
+    maxInlineChars?: number;
 }
 export interface WorkflowFetchCacheExtensionWrapperOptions {
     wrapperPath: string;

package/dist/workflow-fetch-cache-extension.js

@@ -5,7 +5,7 @@ import { pathToFileURL } from "node:url";
 export const WORKFLOW_FETCH_CONTENT_CACHE_SCHEMA = "workflow-fetch-content-cache-v1";
 export const WORKFLOW_FETCH_CONTENT_CACHE_EVENT_SCHEMA = "workflow-fetch-content-cache-event-v1";
 export function registerWorkflowFetchCacheExtension(pi, config, webAccessExtension, storage) {
-    let capturedFetchData;
+    const capturedFetchDataByResponseId = new Map();
     const adapter = new Proxy(pi, {
         get(target, property, receiver) {
             if (property === "registerTool") {
@@ -19,22 +19,25 @@ export function registerWorkflowFetchCacheExtension(pi, config, webAccessExtensi
                         execute: async (toolCallId, params, signal, onUpdate) => {
                             const cacheKey = cacheKeyForParams(params);
                             if (!cacheKey) {
-                                return await tool.execute(toolCallId, params, signal, onUpdate);
+                                return capFetchContentInlineResult(await tool.execute(toolCallId, params, signal, onUpdate), config.maxInlineChars);
                             }
                             const hit = await readCacheRecord(config, cacheKey.key);
                             if (hit) {
                                 await recordCacheEvent(config, "hit", cacheKey);
-                                return materializeCacheHit(pi, storage, hit);
+                                return capFetchContentInlineResult(materializeCacheHit(pi, storage, hit), config.maxInlineChars);
                             }
                             await recordCacheEvent(config, "miss", cacheKey);
-                            capturedFetchData = undefined;
                             const result = await tool.execute(toolCallId, params, signal, onUpdate);
-                            const storedData = capturedFetchData;
-                            capturedFetchData = undefined;
+                            const responseId = stringValue(result.details?.responseId);
+                            const storedData = responseId
+                                ? capturedFetchDataByResponseId.get(responseId)
+                                : undefined;
+                            if (responseId)
+                                capturedFetchDataByResponseId.delete(responseId);
                             const writeReason = cacheWriteSkipReason(result, storedData);
                             if (writeReason) {
                                 await recordCacheEvent(config, "skip", cacheKey, writeReason);
-                                return result;
+                                return capFetchContentInlineResult(result, config.maxInlineChars);
                             }
                             await writeCacheRecord(config, {
                                 schema: WORKFLOW_FETCH_CONTENT_CACHE_SCHEMA,
@@ -46,7 +49,7 @@ export function registerWorkflowFetchCacheExtension(pi, config, webAccessExtensi
                                 storedData: storedData,
                             });
                             await recordCacheEvent(config, "write", cacheKey);
-                            return withCacheDetails(result, { hit: false });
+                            return capFetchContentInlineResult(withCacheDetails(result, { hit: false }), config.maxInlineChars);
                         },
                     });
                 };
@@ -54,7 +57,10 @@ export function registerWorkflowFetchCacheExtension(pi, config, webAccessExtensi
             if (property === "appendEntry") {
                 return (type, data) => {
                     if (type === "web-search-results" && isFetchStoredData(data)) {
-                        capturedFetchData = cloneJsonObject(data);
+                        const cloned = cloneJsonObject(data);
+                        const responseId = stringValue(cloned?.id);
+                        if (responseId && cloned)
+                            capturedFetchDataByResponseId.set(responseId, cloned);
                     }
                     return pi.appendEntry?.(type, data);
                 };
@@ -176,6 +182,45 @@ function withCacheDetails(result, options) {
         },
     };
 }
+function capFetchContentInlineResult(result, maxInlineChars) {
+    const maxChars = normalizeInlineCharCap(maxInlineChars);
+    if (maxChars === undefined || !Array.isArray(result.content))
+        return result;
+    let truncated = false;
+    const content = result.content.map((entry) => {
+        if (entry.type !== "text" || typeof entry.text !== "string")
+            return entry;
+        if (entry.text.length <= maxChars)
+            return entry;
+        truncated = true;
+        return {
+            ...entry,
+            text: entry.text.slice(0, maxChars) +
+                `\n\n[Workflow inline fetch content capped at ${maxChars} chars; full source content remains in workflow source cache.]`,
+        };
+    });
+    if (!truncated)
+        return result;
+    return {
+        ...result,
+        content,
+        details: {
+            ...(result.details ?? {}),
+            truncated: true,
+            workflowInlineContentCap: {
+                type: "fetch_content",
+                maxChars,
+                truncated: true,
+            },
+        },
+    };
+}
+function normalizeInlineCharCap(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return undefined;
+    const cap = Math.floor(value);
+    return cap > 0 ? cap : undefined;
+}
 function cacheWriteSkipReason(result, storedData) {
     if (!storedData)
         return "missing-stored-data";
@@ -227,6 +272,9 @@ function cloneJsonObject(value) {
         return undefined;
     return JSON.parse(JSON.stringify(value));
 }
+function stringValue(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
 function isFetchStoredData(value) {
     return isRecord(value) && value.type === "fetch" && Array.isArray(value.urls);
 }

package/dist/workflow-metrics.d.ts

@@ -0,0 +1,113 @@
+import type { TaskRunStatus, WorkflowRunRecord, WorkflowRunStatus, WorkflowRunType } from "./types.js";
+export declare const WORKFLOW_METRICS_SCHEMA_VERSION = 1;
+export declare const WORKFLOW_METRICS_PRICING_MODEL_VERSION = "provider-reported-v1";
+export type WorkflowMetricsSchemaVersion = typeof WORKFLOW_METRICS_SCHEMA_VERSION;
+export type WorkflowMetricsPricingModelVersion = typeof WORKFLOW_METRICS_PRICING_MODEL_VERSION;
+export type WorkflowMetricsPricingSource = "provider-reported";
+export type WorkflowMetricValue = number | null;
+export interface WorkflowUsageMetrics {
+    inputTokens: WorkflowMetricValue;
+    outputTokens: WorkflowMetricValue;
+    totalTokens: WorkflowMetricValue;
+    cachedInputTokens: WorkflowMetricValue;
+    cacheCreationInputTokens: WorkflowMetricValue;
+    cacheReadInputTokens: WorkflowMetricValue;
+    reasoningTokens: WorkflowMetricValue;
+    /**
+     * Provider-reported cost only. This helper intentionally never derives cost
+     * from token counts or model names.
+     */
+    costUsd: WorkflowMetricValue;
+    attempts: number;
+    unavailable: boolean;
+    incomplete: boolean;
+    unavailableTaskIds: string[];
+    incompleteTaskIds: string[];
+}
+export interface WorkflowLaunchTimingMetrics {
+    launchWaitMs: WorkflowMetricValue;
+    launchDurationMs: WorkflowMetricValue;
+    executionMs: WorkflowMetricValue;
+    totalMs: WorkflowMetricValue;
+    launchSlotReleaseDelayMs: WorkflowMetricValue;
+    attempts: number;
+    unavailable: boolean;
+    incomplete: boolean;
+    unavailableTaskIds: string[];
+    incompleteTaskIds: string[];
+}
+export interface WorkflowRetryMetrics {
+    launchRetries: number;
+    outputRetries: number;
+    resumeEvents: number;
+    totalRetryEvents: number;
+    tasksWithRetries: number;
+}
+export interface WorkflowTaskStatusCounts {
+    pending: number;
+    running: number;
+    blocked: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    interrupted: number;
+    total: number;
+}
+export interface WorkflowRunMetricsRollup {
+    taskCount: number;
+    statusCounts: WorkflowTaskStatusCounts;
+    usage: WorkflowUsageMetrics;
+    launchTiming: WorkflowLaunchTimingMetrics;
+    retries: WorkflowRetryMetrics;
+}
+export interface WorkflowTaskMetrics {
+    taskId: string;
+    specId: string;
+    displayName: string;
+    agent: string;
+    status: TaskRunStatus;
+    statusDetail: string;
+    stageId: string | null;
+    kind: string | null;
+    provider: string | null;
+    model: string | null;
+    thinking: string | null;
+    usage: WorkflowUsageMetrics;
+    launchTiming: WorkflowLaunchTimingMetrics;
+    retries: WorkflowRetryMetrics;
+}
+export interface WorkflowStageMetrics extends WorkflowRunMetricsRollup {
+    stageId: string | null;
+}
+export interface WorkflowRunMetricsMetadata {
+    usageUnavailableTaskIds: string[];
+    usageIncompleteTaskIds: string[];
+    launchTimingUnavailableTaskIds: string[];
+    launchTimingIncompleteTaskIds: string[];
+    incomplete: boolean;
+    unavailable: boolean;
+}
+export interface WorkflowRunMetrics {
+    schemaVersion: WorkflowMetricsSchemaVersion;
+    pricingModelVersion: WorkflowMetricsPricingModelVersion;
+    pricingSource: WorkflowMetricsPricingSource;
+    costsAreProviderReported: true;
+    run: {
+        runId: string;
+        name?: string;
+        type: WorkflowRunType;
+        status: WorkflowRunStatus;
+        createdAt: string;
+        updatedAt: string;
+    };
+    totals: WorkflowRunMetricsRollup;
+    byStage: WorkflowStageMetrics[];
+    byTask: WorkflowTaskMetrics[];
+    metadata: WorkflowRunMetricsMetadata;
+}
+/**
+ * Build a deterministic, JSON-serializable metrics export from a persisted
+ * workflow run record. The helper is intentionally pure: it reads only the
+ * supplied record, performs no pricing inference, and does not mutate the run.
+ */
+export declare function buildWorkflowRunMetrics(run: WorkflowRunRecord): WorkflowRunMetrics;