@agwab/pi-workflow 0.2.1 → 0.4.0

package/src/types.ts

@@ -203,7 +203,14 @@ export interface ArtifactGraphStageSpec {
 	maxRuntimeMs?: number;
 	maxConcurrency?: number;
 	maxItems?: number;
-	from?: string | string[] | { source: string; path: string };
+	from?:
+		| string
+		| string[]
+		| {
+				source: string;
+				path: string;
+				streaming?: { enabled: true; minChunk?: number };
+		  };
 	after?: string | string[];
 	sourcePolicy?: "success" | "partial" | "require-success";
 	sourceProjection?: {
@@ -213,12 +220,14 @@ export interface ArtifactGraphStageSpec {
 	inputPolicy?: {
 		requiredReads?: string[];
 		enforcement?: "fail";
+		artifactAccess?: "enabled" | "none";
 	};
 	output?: {
 		controlSchema?: string;
 		analysis?: { required?: boolean };
 		refs?: { required?: boolean; minItems?: number };
 		maxDigestChars?: number;
+		partial?: { paths: string[] };
 	};
 	each?: Record<string, unknown>;
 	stages?: ArtifactGraphStageSpec[];
@@ -490,8 +499,10 @@ export interface CompiledArtifactGraphTask {
 		controlSchema?: string;
 		controlSchemaPath?: string;
 		maxDigestChars?: number;
+		partial?: { paths: string[] };
 	};
 	requiredReads: string[];
+	artifactAccess: "enabled" | "none";
 	sourceProjection?: {
 		include?: string[];
 		maxChars?: number;
@@ -542,6 +553,13 @@ export interface CompiledTask {
 		branchId?: string;
 		outputProfile?: string;
 	};
+	foreachGenerated?: {
+		placeholderSpecId: string;
+		itemHash?: string;
+		itemSourceSpecId?: string;
+		itemSourceKind?: "control" | "partial";
+		itemRef?: string;
+	};
 	loopChild?: CompiledLoopChildTaskRef;
 	loopPlaceholder?: {
 		loopId: string;
@@ -568,6 +586,89 @@ export type WorkflowRunStatus =
 	| "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;
@@ -606,6 +707,8 @@ export interface WorkflowTaskRunRecord {
 	startedAt?: string;
 	completedAt?: string;
 	elapsedMs?: number;
+	usage?: WorkflowTaskUsageRecord;
+	timing?: WorkflowTaskTimingRecord;
 	exitCode?: number;
 	files: {
 		systemPrompt: string;
@@ -634,6 +737,13 @@ export interface WorkflowTaskRunRecord {
 		branchId?: string;
 		outputProfile?: string;
 	};
+	foreachGenerated?: {
+		placeholderSpecId: string;
+		itemHash?: string;
+		itemSourceSpecId?: string;
+		itemSourceKind?: "control" | "partial";
+		itemRef?: string;
+	};
 	launchRetry?: {
 		attempts: number;
 		maxAttempts?: number;
@@ -724,7 +834,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/src/verification-ontology.ts

@@ -0,0 +1,88 @@
+export const VERIFICATION_STATUS = Object.freeze({
+	VERIFIED: "verified",
+	PARTIALLY_SUPPORTED: "partially_supported",
+	UNSUPPORTED: "unsupported",
+	CONFLICTING: "conflicting",
+	VERIFICATION_BLOCKED: "verification_blocked",
+	UNVERIFIED: "unverified",
+} as const);
+
+export type VerificationStatus =
+	(typeof VERIFICATION_STATUS)[keyof typeof VERIFICATION_STATUS];
+
+export type TerminalVerificationStatus = Exclude<
+	VerificationStatus,
+	(typeof VERIFICATION_STATUS)["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,
+] as const satisfies readonly TerminalVerificationStatus[]);
+
+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",
+} as const satisfies Record<TerminalVerificationStatus, string>);
+
+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",
+} as const satisfies Record<VerificationStatus, string>);
+
+export function canonicalVerificationStatus(
+	status: unknown,
+): VerificationStatus {
+	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 as VerificationStatus)
+		? (text as VerificationStatus)
+		: VERIFICATION_STATUS.UNVERIFIED;
+}
+
+export function verificationStatusBucket(status: unknown): string {
+	const canonical = canonicalVerificationStatus(status);
+	return canonical in VERIFICATION_STATUS_BUCKETS
+		? VERIFICATION_STATUS_BUCKETS[canonical as TerminalVerificationStatus]
+		: "other";
+}
+
+export function isVerifiedStatus(status: unknown): boolean {
+	return canonicalVerificationStatus(status) === VERIFICATION_STATUS.VERIFIED;
+}
+
+export function isVerificationBlockedStatus(status: unknown): boolean {
+	return (
+		canonicalVerificationStatus(status) ===
+		VERIFICATION_STATUS.VERIFICATION_BLOCKED
+	);
+}
+
+const NON_VERIFIED_TERMINAL_STATUSES = new Set<VerificationStatus>([
+	VERIFICATION_STATUS.PARTIALLY_SUPPORTED,
+	VERIFICATION_STATUS.UNSUPPORTED,
+	VERIFICATION_STATUS.CONFLICTING,
+	VERIFICATION_STATUS.VERIFICATION_BLOCKED,
+]);
+
+export function isNonVerifiedTerminalStatus(status: unknown): boolean {
+	return NON_VERIFIED_TERMINAL_STATUSES.has(
+		canonicalVerificationStatus(status),
+	);
+}

package/src/workflow-artifact-tool.ts

@@ -147,8 +147,7 @@ const WORKFLOW_ARTIFACT_KIND_SET = new Set<string>(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: Record<string, string> = {
 	axes: "researchAxes",
 	claimVerdicts: "claimVerdictLedger",
@@ -466,15 +465,14 @@ async function readProjectedWorkflowArtifact(options: {
 		path: effectivePath,
 	});
 	const serialized = JSON.stringify(sliced.value, null, 2);
+	const maxChars = options.maxChars ?? DEFAULT_MAX_BYTES;
 	const preview =
-		options.maxChars !== undefined && serialized.length > options.maxChars
-			? serialized.slice(0, options.maxChars)
-			: serialized;
+		serialized.length > maxChars ? serialized.slice(0, maxChars) : serialized;
 	const projection: WorkflowArtifactProjectionMetadata = {
 		path: effectivePath,
 		valueType: jsonValueType(resolved),
 		...(options.maxItems === undefined ? {} : { maxItems: options.maxItems }),
-		...(options.maxChars === undefined ? {} : { maxChars: options.maxChars }),
+		maxChars,
 		...(sliced.totalItems === undefined
 			? {}
 			: { totalItems: sliced.totalItems }),
@@ -810,7 +808,7 @@ function normalizeProjectionPath(value: unknown): string | undefined {
 	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",
+			"path must be $ or a simple dot JSON path like $.claims.items; array selectors are not supported",
 		);
 	}
 	return path;

package/src/workflow-artifacts.ts

@@ -9,6 +9,7 @@ interface WorkflowTelemetryAccumulator {
 	launchRetries: number;
 	resumeEvents: number;
 	resumedTasks: number;
+	contextLimitFailures: number;
 	retryReasons: WorkflowTelemetrySummary["retryReasons"];
 	resumeStatusCounts: StatusCounts;
 	outputRepairCounts: OutputRepairCounts;
@@ -18,6 +19,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 };
 	retryReasons: {
 		output: Record<string, number>;
@@ -77,10 +85,23 @@ export function summarizeWorkflowTelemetry(
 		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,
@@ -103,6 +124,7 @@ function createWorkflowTelemetryAccumulator(): WorkflowTelemetryAccumulator {
 		launchRetries: 0,
 		resumeEvents: 0,
 		resumedTasks: 0,
+		contextLimitFailures: 0,
 		retryReasons: { output: {}, launch: {} },
 		resumeStatusCounts: {},
 		outputRepairCounts: { sameSession: 0, newSession: 0, unknown: 0 },
@@ -113,6 +135,7 @@ function accumulateTaskReliability(
 	task: Partial<WorkflowTaskRunRecord>,
 	accumulator: WorkflowTelemetryAccumulator,
 ): void {
+	if (taskHasContextLimitFailure(task)) accumulator.contextLimitFailures += 1;
 	const currentOutputAttempts = positiveCount(task.outputRetry?.attempts);
 	accumulator.outputRetries += currentOutputAttempts;
 	if (currentOutputAttempts > 0) {
@@ -137,17 +160,40 @@ function accumulateTaskReliability(
 	for (const event of resumeEvents) accumulateResumeEvent(event, accumulator);
 }
 
+function completionHealth(
+	tasks: Array<Partial<WorkflowTaskRunRecord>>,
+	repairEvents: number,
+	accumulator: WorkflowTelemetryAccumulator,
+): WorkflowTelemetrySummary["completion"]["health"] {
+	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: NonNullable<WorkflowTaskRunRecord["resumeEvents"]>[number],
 	accumulator: WorkflowTelemetryAccumulator,
 ): void {
 	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: number | undefined): number {
@@ -172,6 +218,40 @@ function countRepairMode(
 	else counts.unknown += 1;
 }
 
+function taskHasContextLimitFailure(
+	task: Partial<WorkflowTaskRunRecord>,
+): boolean {
+	return [
+		task.statusDetail,
+		task.lastMessage,
+		task.outputRetry?.reason,
+		task.outputRetry?.message,
+		task.launchRetry?.reason,
+		task.launchRetry?.message,
+	].some(isContextLimitText);
+}
+
+function resumeEventHasContextLimitFailure(
+	event: NonNullable<WorkflowTaskRunRecord["resumeEvents"]>[number],
+): boolean {
+	return [
+		event.fromStatusDetail,
+		event.lastMessage,
+		event.outputRetryReason,
+		event.launchRetryReason,
+	].some(isContextLimitText);
+}
+
+function isContextLimitText(value: string | undefined): boolean {
+	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 interface SourceContextPacket {
 	tasks: SourceContextTask[];
 	byStage: Record<

package/src/workflow-fetch-cache-extension.ts

@@ -18,6 +18,7 @@ export interface WorkflowFetchCacheConfig {
 	runId: string;
 	taskId: string;
 	cacheDir: string;
+	maxInlineChars?: number;
 }
 
 export interface WorkflowFetchCacheExtensionWrapperOptions {
@@ -83,7 +84,7 @@ export function registerWorkflowFetchCacheExtension(
 	webAccessExtension: WebAccessExtension,
 	storage: WebAccessStorage,
 ): void {
-	let capturedFetchData: Record<string, unknown> | undefined;
+	const capturedFetchDataByResponseId = new Map<string, Record<string, unknown>>();
 	const adapter = new Proxy(pi, {
 		get(target, property, receiver) {
 			if (property === "registerTool") {
@@ -97,32 +98,43 @@ export function registerWorkflowFetchCacheExtension(
 						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,
@@ -134,7 +146,10 @@ export function registerWorkflowFetchCacheExtension(
 								storedData: storedData!,
 							});
 							await recordCacheEvent(config, "write", cacheKey);
-							return withCacheDetails(result, { hit: false });
+							return capFetchContentInlineResult(
+								withCacheDetails(result, { hit: false }),
+								config.maxInlineChars,
+							);
 						},
 					});
 				};
@@ -142,7 +157,10 @@ export function registerWorkflowFetchCacheExtension(
 			if (property === "appendEntry") {
 				return (type: string, data: unknown) => {
 					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);
 				};
@@ -300,6 +318,49 @@ function withCacheDetails(
 	};
 }
 
+function capFetchContentInlineResult(
+	result: ToolResult,
+	maxInlineChars: number | undefined,
+): ToolResult {
+	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: number | undefined): number | undefined {
+	if (value === undefined || !Number.isFinite(value)) return undefined;
+	const cap = Math.floor(value);
+	return cap > 0 ? cap : undefined;
+}
+
 function cacheWriteSkipReason(
 	result: ToolResult,
 	storedData: Record<string, unknown> | undefined,
@@ -366,6 +427,10 @@ function cloneJsonObject(value: unknown): Record<string, unknown> | undefined {
 	return JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
 }
 
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" && value ? value : undefined;
+}
+
 function isFetchStoredData(value: unknown): value is Record<string, unknown> {
 	return isRecord(value) && value.type === "fetch" && Array.isArray(value.urls);
 }