agentic-engineering-harness 0.8.7 → 0.8.8

package/dist/releases/release-1790896171560-15571-736bf3d2/telemetry/efficiency.js

@@ -0,0 +1,765 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { sha256Canonical, sha256Utf8 } from "../core/digest.js";
+import { loadOperation, resolveOperationStateRoot } from "../operations/state.js";
+import { extractUsageMetrics } from "../metrics/usage.js";
+const nullableCount = z.number().int().nonnegative().nullable();
+const nullableCost = z.number().finite().nonnegative().nullable();
+const nullableTime = z.string().datetime().nullable();
+export const providerTurnUsageObservationV1Schema = z.object({
+    turnId: z.string().min(1).nullable(),
+    turnIndex: z.number().int().nonnegative().nullable(),
+    runtimeSessionId: z.string().min(1).nullable(),
+    provider: z.string().min(1),
+    at: nullableTime,
+    inputTokens: nullableCount,
+    cachedInputTokens: nullableCount,
+    outputTokens: nullableCount,
+    reasoningOutputTokens: nullableCount,
+    totalTokens: nullableCount,
+    totalTokensBasis: z.enum(["PROVIDER_REPORTED", "INPUT_PLUS_OUTPUT", "UNKNOWN"]),
+    costUsd: nullableCost,
+    usageKnown: z.boolean()
+}).strict();
+export const participantUsageObservationV1Schema = z.object({
+    version: z.literal(1),
+    observationId: z.string().regex(/^[a-f0-9]{64}$/),
+    operationId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateRevision: z.number().int().positive(),
+    candidateDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    operationExecutionRevision: z.number().int().positive(),
+    controllerEpoch: z.number().int().nonnegative(),
+    participantId: z.string().min(1),
+    generation: z.string().min(1).nullable(),
+    role: z.string().min(1),
+    phase: z.string().min(1),
+    provider: z.string().min(1),
+    model: z.string().min(1).nullable(),
+    runtimeSessionId: z.string().min(1).nullable(),
+    turnCount: z.number().int().nonnegative().nullable(),
+    inputTokens: nullableCount,
+    cachedInputTokens: nullableCount,
+    outputTokens: nullableCount,
+    reasoningOutputTokens: nullableCount,
+    totalTokens: nullableCount,
+    totalTokensBasis: z.enum(["PROVIDER_REPORTED", "INPUT_PLUS_OUTPUT", "UNKNOWN"]),
+    costUsd: nullableCost,
+    usageKnown: z.boolean(),
+    usageSource: z.enum(["PROVIDER_TURN_EVENTS", "PASEO_AGENT_SNAPSHOT", "PASEO_ADAPTER", "AEH_TEXT_EXTRACTION", "UNKNOWN"]),
+    usageCoverage: z.enum(["COMPLETE", "PARTIAL", "UNKNOWN"]),
+    startedAt: nullableTime,
+    finishedAt: nullableTime,
+    durationMs: nullableCount,
+    resultStatus: z.enum(["SUCCEEDED", "FAILED", "BLOCKED", "UNKNOWN"]),
+    turnUsage: z.array(providerTurnUsageObservationV1Schema)
+}).strict();
+export const toolCallObservationV1Schema = z.object({
+    version: z.literal(1),
+    observationId: z.string().regex(/^[a-f0-9]{64}$/),
+    operationId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateRevision: z.number().int().positive(),
+    candidateDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    operationExecutionRevision: z.number().int().positive(),
+    controllerEpoch: z.number().int().nonnegative(),
+    participantId: z.string().min(1),
+    sessionId: z.string().min(1),
+    role: z.string().min(1),
+    phase: z.string().min(1),
+    turnId: z.string().min(1).nullable(),
+    turnIndex: z.number().int().nonnegative().nullable(),
+    timelineSequence: z.number().int().nonnegative().nullable(),
+    toolServer: z.string().min(1).nullable(),
+    provider: z.string().min(1).nullable(),
+    toolName: z.string().min(1),
+    callId: z.string().min(1).nullable(),
+    attemptIndex: z.number().int().positive().nullable(),
+    argumentsDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    argumentsByteLength: z.number().int().nonnegative().nullable(),
+    startedAt: nullableTime,
+    finishedAt: nullableTime,
+    durationMs: nullableCount,
+    outcome: z.enum(["SUCCESS", "TOOL_ERROR", "PERMISSION_DENIED", "TIMEOUT", "INVALID_ARGUMENT", "UNAVAILABLE", "CANCELLED", "UNKNOWN_ERROR"]),
+    resultByteLength: z.number().int().nonnegative().nullable(),
+    errorFingerprint: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    retryOfCallId: z.string().min(1).nullable(),
+    causalStatus: z.enum(["PROVEN", "EQUIVALENT_ONLY", "UNKNOWN"])
+}).strict();
+export const contextAccountingObservationV1Schema = z.object({
+    version: z.literal(1),
+    observationId: z.string().regex(/^[a-f0-9]{64}$/),
+    operationId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateRevision: z.number().int().positive(),
+    candidateDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    operationExecutionRevision: z.number().int().positive(),
+    controllerEpoch: z.number().int().nonnegative(),
+    participantId: z.string().min(1),
+    generation: z.string().min(1).nullable(),
+    role: z.string().min(1),
+    logicalAgent: z.string().min(1),
+    phase: z.string().min(1),
+    runtimeSessionId: z.string().min(1).nullable(),
+    envelopeDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    rawContextTokens: nullableCount,
+    projectedContextTokens: nullableCount,
+    deliveredContextTokens: nullableCount,
+    retrievalRequestCount: z.number().int().nonnegative(),
+    retrievalDeliveredTokens: z.number().int().nonnegative(),
+    fragmentIdentities: z.array(z.object({ fragmentId: z.string().min(1), contentDigest: z.string().regex(/^[a-f0-9]{64}$/), deliveredTokens: z.number().int().nonnegative() }).strict()),
+    tokenBasis: z.literal("AEH_ESTIMATOR")
+}).strict();
+export const contextRetrievalObservationV1Schema = z.object({
+    version: z.literal(1),
+    operationId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateRevision: z.number().int().positive(),
+    candidateDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    operationExecutionRevision: z.number().int().positive(),
+    controllerEpoch: z.number().int().nonnegative(),
+    participantId: z.string().min(1),
+    generation: z.string().min(1).nullable(),
+    role: z.string().min(1),
+    phase: z.string().min(1),
+    sessionId: z.string().min(1),
+    requestId: z.string().min(1),
+    fragmentId: z.string().min(1),
+    contentDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    estimatedTokens: z.number().int().nonnegative(),
+    repeated: z.boolean(),
+    retrievedAt: z.string().datetime(),
+    tokenBasis: z.literal("AEH_ESTIMATOR")
+}).strict();
+export const operationEfficiencySummaryV1Schema = z.object({
+    version: z.literal(1),
+    operationId: z.string().min(1),
+    terminalStatus: z.enum(["SUCCEEDED", "FAILED", "CANCELLED", "UNKNOWN"]),
+    route: z.string().nullable(),
+    assurance: z.string().nullable(),
+    currentCandidateId: z.string().min(1).nullable(),
+    currentCandidateRevision: z.number().int().positive().nullable(),
+    currentCandidateDigest: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    participants: z.number().int().nonnegative(),
+    participantGenerations: z.number().int().nonnegative(),
+    providerTurns: z.number().int().nonnegative().nullable(),
+    usage: z.object({
+        inputTokens: nullableCount,
+        cachedInputTokens: nullableCount,
+        outputTokens: nullableCount,
+        reasoningOutputTokens: nullableCount,
+        totalTokens: nullableCount,
+        totalTokensBasis: z.enum(["PROVIDER_REPORTED", "INPUT_PLUS_OUTPUT", "UNKNOWN"]),
+        costUsd: nullableCost,
+        knownParticipants: z.number().int().nonnegative(),
+        participantCount: z.number().int().nonnegative(),
+        costKnownParticipants: z.number().int().nonnegative(),
+        completeObservations: z.number().int().nonnegative(),
+        partialObservations: z.number().int().nonnegative(),
+        unknownObservations: z.number().int().nonnegative(),
+        byParticipant: z.array(z.object({
+            participantId: z.string().min(1),
+            generations: z.number().int().nonnegative(),
+            roles: z.array(z.string().min(1)),
+            inputTokens: nullableCount,
+            cachedInputTokens: nullableCount,
+            outputTokens: nullableCount,
+            reasoningOutputTokens: nullableCount,
+            totalTokens: nullableCount,
+            costUsd: nullableCost,
+            usageKnown: z.boolean(),
+            usageCoverage: z.enum(["COMPLETE", "PARTIAL", "UNKNOWN"])
+        }).strict())
+    }).strict(),
+    context: z.object({
+        rawContextTokens: z.number().int().nonnegative(),
+        projectedContextTokens: z.number().int().nonnegative(),
+        deliveredContextTokens: z.number().int().nonnegative(),
+        retrievalRequestCount: z.number().int().nonnegative(),
+        retrievalDeliveredTokens: z.number().int().nonnegative(),
+        crossParticipantRepeatedFragmentTokens: z.number().int().nonnegative(),
+        tokenBasis: z.literal("AEH_ESTIMATOR")
+    }).strict(),
+    tools: z.object({
+        toolCalls: z.number().int().nonnegative(),
+        firstAttemptSuccesses: z.number().int().nonnegative(),
+        failedFirstAttempts: z.number().int().nonnegative(),
+        retryCalls: z.number().int().nonnegative(),
+        recoveredAfterRetry: z.number().int().nonnegative(),
+        repeatedEquivalentCalls: z.number().int().nonnegative(),
+        unrecoveredToolFailures: z.number().int().nonnegative(),
+        unknownCausalRetries: z.number().int().nonnegative(),
+        failuresByClass: z.record(z.string(), z.number().int().nonnegative()),
+        retryAssociatedInputTokens: nullableCount,
+        retryAssociatedOutputTokens: nullableCount,
+        retryAssociatedTotalTokens: nullableCount,
+        retryUsageCoverage: z.enum(["COMPLETE", "PARTIAL", "UNKNOWN"])
+    }).strict(),
+    workflow: z.object({ repairRounds: z.number().int().nonnegative(), candidateRevisions: z.number().int().nonnegative(), reviewRounds: z.number().int().nonnegative(), humanInterventions: z.number().int().nonnegative().nullable() }).strict(),
+    timing: z.object({ totalDurationMs: nullableCount, participantDurationMs: nullableCount }).strict(),
+    outcome: z.object({ accepted: z.boolean().nullable(), delivered: z.boolean().nullable() }).strict(),
+    generatedAt: z.string().datetime()
+}).strict();
+const EFFICIENCY_ROOT = path.join(".harness", "telemetry", "efficiency", "operations");
+export function participantUsageObservationFromSession(input) {
+    const binding = input.session.executionBinding;
+    if (!binding || binding.participantId !== input.participantId || binding.operationId !== input.operationId
+        || binding.candidateRevision !== input.candidate.revision || binding.candidateDigest !== input.candidate.identityDigest)
+        return undefined;
+    const telemetry = input.providerTelemetry;
+    const turns = (telemetry?.turns ?? []).map((turn) => ({ ...turn, runtimeSessionId: binding.runtime.sessionId }));
+    let usageSource = "UNKNOWN";
+    let usageCoverage = "UNKNOWN";
+    let metrics = {};
+    let totalTokensBasis = "UNKNOWN";
+    let turnCount = telemetry?.turnCount ?? null;
+    if (turns.some((turn) => turn.usageKnown)) {
+        usageSource = "PROVIDER_TURN_EVENTS";
+        usageCoverage = telemetry?.coverage ?? "PARTIAL";
+        turnCount = telemetry?.turnCount ?? new Set(turns.map((turn) => turn.turnId ?? `index:${turn.turnIndex}`)).size;
+        metrics = sumTurnUsage(turns);
+        const knownTotalBases = new Set(turns.filter((turn) => turn.totalTokens !== null).map((turn) => turn.totalTokensBasis));
+        totalTokensBasis = knownTotalBases.size === 1 ? [...knownTotalBases][0] : "UNKNOWN";
+    }
+    else if (telemetry?.snapshotUsage && Object.values(telemetry.snapshotUsage).some((value) => value !== undefined)) {
+        usageSource = "PASEO_AGENT_SNAPSHOT";
+        usageCoverage = "PARTIAL";
+        metrics = { ...telemetry.snapshotUsage };
+        totalTokensBasis = metrics.totalTokens !== undefined ? "PROVIDER_REPORTED" : "UNKNOWN";
+    }
+    else if (input.session.metrics && Object.values(input.session.metrics).some((value) => value !== undefined)) {
+        usageSource = "PASEO_ADAPTER";
+        usageCoverage = "PARTIAL";
+        metrics = { ...input.session.metrics };
+        totalTokensBasis = metrics.totalTokens !== undefined ? "PROVIDER_REPORTED" : "UNKNOWN";
+    }
+    else {
+        const extracted = extractUsageMetrics(`${input.session.stdout}\n${input.session.stderr}`);
+        if (Object.keys(extracted).length) {
+            usageSource = "AEH_TEXT_EXTRACTION";
+            usageCoverage = "PARTIAL";
+            metrics = extracted;
+            totalTokensBasis = "UNKNOWN";
+        }
+    }
+    const startedAt = validTimestamp(input.session.startedAt);
+    const finishedAt = validTimestamp(input.session.finishedAt);
+    const durationMs = startedAt && finishedAt ? Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)) : null;
+    const usageKnown = usageCoverage !== "UNKNOWN" && Object.values(metrics).some((value) => value !== undefined);
+    const body = {
+        version: 1,
+        operationId: input.operationId,
+        candidateId: input.candidate.candidateId,
+        candidateRevision: input.candidate.revision,
+        candidateDigest: input.candidate.identityDigest,
+        operationExecutionRevision: binding.operationExecutionRevision,
+        controllerEpoch: binding.controllerEpoch,
+        participantId: input.participantId,
+        generation: binding.participantGeneration,
+        role: input.role,
+        phase: input.phase,
+        provider: telemetry?.turns[0]?.provider ?? input.session.provider,
+        model: input.session.model ?? binding.runtime.model,
+        runtimeSessionId: input.session.id ?? binding.runtime.sessionId,
+        turnCount,
+        inputTokens: metrics.inputTokens ?? null,
+        cachedInputTokens: metrics.cachedInputTokens ?? null,
+        outputTokens: metrics.outputTokens ?? null,
+        reasoningOutputTokens: metrics.reasoningOutputTokens ?? null,
+        totalTokens: metrics.totalTokens ?? null,
+        totalTokensBasis,
+        costUsd: metrics.costUsd ?? null,
+        usageKnown,
+        usageSource,
+        usageCoverage,
+        startedAt,
+        finishedAt,
+        durationMs,
+        resultStatus: input.resultStatus ?? (input.session.exitCode === 0 ? "SUCCEEDED" : "FAILED"),
+        turnUsage: turns
+    };
+    return participantUsageObservationV1Schema.parse({ ...body, observationId: sha256Canonical(body) });
+}
+export async function recordParticipantUsageObservation(root, config, observation) {
+    if (config.telemetry?.enabled !== true)
+        return false;
+    const parsed = participantUsageObservationV1Schema.parse(observation);
+    if (!await currentEfficiencyBindingMatches(root, parsed))
+        return false;
+    return writeObservationOnce(root, parsed.operationId, "participants", parsed.observationId, parsed);
+}
+export async function recordToolCallObservations(root, config, input) {
+    if (config.telemetry?.enabled !== true)
+        return 0;
+    const correlated = correlateEquivalentToolCalls(input.observations);
+    const complete = correlated.map((observation) => {
+        const base = {
+            version: 1,
+            operationId: input.operationId,
+            candidateId: input.candidate.candidateId,
+            candidateRevision: input.candidate.revision,
+            candidateDigest: input.candidate.identityDigest,
+            operationExecutionRevision: input.operationExecutionRevision,
+            controllerEpoch: input.controllerEpoch,
+            participantId: input.participantId,
+            sessionId: input.sessionId,
+            role: input.role,
+            phase: input.phase,
+            ...observation
+        };
+        const identity = sha256Canonical(base);
+        return toolCallObservationV1Schema.parse({ ...base, observationId: identity });
+    });
+    let stored = 0;
+    for (const observation of complete) {
+        if (!await currentEfficiencyBindingMatches(root, observation))
+            continue;
+        if (await writeObservationOnce(root, observation.operationId, "tools", observation.observationId, observation))
+            stored += 1;
+    }
+    return stored;
+}
+export async function recordContextAccountingObservation(root, config, input) {
+    if (config.telemetry?.enabled !== true || !input.participantId)
+        return false;
+    const body = {
+        version: 1,
+        operationId: input.operationId,
+        candidateId: input.candidate.candidateId,
+        candidateRevision: input.candidate.revision,
+        candidateDigest: input.candidate.identityDigest,
+        operationExecutionRevision: input.operationExecutionRevision,
+        controllerEpoch: input.controllerEpoch,
+        participantId: input.participantId,
+        generation: input.generation ?? null,
+        role: input.role,
+        logicalAgent: input.logicalAgent,
+        phase: input.phase,
+        runtimeSessionId: input.runtimeSessionId ?? null,
+        envelopeDigest: input.envelopeDigest,
+        rawContextTokens: input.rawContextTokens,
+        projectedContextTokens: input.projectedContextTokens,
+        deliveredContextTokens: input.deliveredContextTokens,
+        retrievalRequestCount: 0,
+        retrievalDeliveredTokens: 0,
+        fragmentIdentities: input.fragmentIdentities,
+        tokenBasis: "AEH_ESTIMATOR"
+    };
+    const observation = contextAccountingObservationV1Schema.parse({ ...body, observationId: sha256Canonical(body) });
+    if (!await currentEfficiencyBindingMatches(root, observation))
+        return false;
+    return writeObservationOnce(root, observation.operationId, "context", observation.observationId, observation);
+}
+export async function recordContextRetrievalObservation(root, config, observation) {
+    if (config.telemetry?.enabled !== true)
+        return false;
+    const parsed = contextRetrievalObservationV1Schema.parse(observation);
+    if (!await currentEfficiencyBindingMatches(root, parsed))
+        return false;
+    return writeObservationOnce(root, parsed.operationId, "retrieval", sha256Canonical(parsed), parsed);
+}
+export async function writeOperationEfficiencySummary(root, config, operation) {
+    if (config.telemetry?.enabled !== true)
+        return undefined;
+    const observations = await readOperationEfficiencyObservations(root, operation.id);
+    const summary = summarizeOperationEfficiencyV1(operation, observations);
+    await writeJsonAtomic(summaryFile(root, operation.id), summary);
+    return summary;
+}
+export async function readOperationEfficiencySummary(root, operation) {
+    try {
+        const summary = operationEfficiencySummaryV1Schema.parse(JSON.parse(await fs.readFile(summaryFile(root, operation.id), "utf8")));
+        if (summary.operationId !== operation.id || summary.currentCandidateId !== (operation.candidateRevision?.candidateId ?? null)
+            || summary.currentCandidateDigest !== (operation.candidateRevision?.identityDigest ?? null))
+            return undefined;
+        return summary;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function summarizeOperationEfficiencyV1(operation, observations, generatedAt = new Date().toISOString()) {
+    const participants = deduplicateParticipantUsage(observations.participants.filter((item) => item.operationId === operation.id));
+    const tools = observations.tools.filter((item) => item.operationId === operation.id);
+    const contexts = observations.context.filter((item) => item.operationId === operation.id);
+    const retrievals = observations.retrieval.filter((item) => item.operationId === operation.id);
+    const sumField = (items, key) => {
+        const known = items.map((item) => item[key]).filter((value) => typeof value === "number");
+        return known.length ? known.reduce((sum, value) => sum + value, 0) : null;
+    };
+    const knownParticipants = new Set(participants.filter((item) => item.usageKnown).map((item) => item.participantId)).size;
+    const costKnownParticipants = new Set(participants.filter((item) => item.costUsd !== null).map((item) => item.participantId)).size;
+    const totalParticipants = new Set(participants.map((item) => item.participantId)).size;
+    const usageComplete = participants.length > 0 && participants.every((item) => item.usageKnown && item.usageCoverage === "COMPLETE");
+    const tokenBases = new Set(participants.filter((item) => item.totalTokens !== null).map((item) => item.totalTokensBasis));
+    const totalTokenBasis = tokenBases.size === 1 ? [...tokenBases][0] : "UNKNOWN";
+    const distinctGenerations = new Set(participants.flatMap((item) => item.generation ? [`${item.participantId}:${item.generation}`] : [])).size;
+    const providerTurns = participants.every((item) => item.turnCount !== null)
+        ? participants.reduce((sum, item) => sum + (item.turnCount ?? 0), 0)
+        : null;
+    const repeatedFragmentTokens = repeatedCrossParticipantFragmentTokens(contexts, retrievals);
+    const firstAttemptSuccesses = tools.filter((item) => item.attemptIndex === 1 && item.outcome === "SUCCESS").length;
+    const failedFirstAttempts = tools.filter((item) => item.attemptIndex === 1 && item.outcome !== "SUCCESS").length;
+    const retryCalls = tools.filter((item) => item.retryOfCallId !== null && item.causalStatus === "PROVEN").length;
+    const recoveredAfterRetry = tools.filter((item) => item.attemptIndex === 1 && item.outcome !== "SUCCESS" && retrySequenceRecovered(item, tools)).length;
+    const failureClasses = new Map();
+    for (const tool of tools)
+        if (tool.outcome !== "SUCCESS")
+            failureClasses.set(tool.outcome, (failureClasses.get(tool.outcome) ?? 0) + 1);
+    const retryTurnIds = retryAssociatedTurnIds(tools);
+    const usageByTurn = new Map();
+    for (const participant of participants)
+        for (const turn of participant.turnUsage) {
+            if (turn.runtimeSessionId && turn.turnId)
+                usageByTurn.set(`${turn.runtimeSessionId}\0${turn.turnId}`, turn);
+        }
+    const retryTurnUsage = [...retryTurnIds].flatMap((key) => usageByTurn.has(key) ? [usageByTurn.get(key)] : []);
+    const retryUsageCoverage = retryTurnIds.size === 0 ? "UNKNOWN" : retryTurnUsage.length === retryTurnIds.size
+        && retryTurnUsage.every((turn) => turn.inputTokens !== null && turn.outputTokens !== null && turn.totalTokens !== null)
+        ? "COMPLETE" : "PARTIAL";
+    const durationMs = operation.startedAt && operation.finishedAt ? Math.max(0, Date.parse(operation.finishedAt) - Date.parse(operation.startedAt)) : null;
+    const resultRecord = operation.result && typeof operation.result === "object" ? operation.result : undefined;
+    const acceptanceValue = resultRecord?.acceptanceOracle;
+    const acceptanceDisposition = acceptanceValue && typeof acceptanceValue === "object" ? acceptanceValue.disposition : undefined;
+    const deliveryValue = resultRecord?.delivery;
+    const deliveryStatus = deliveryValue && typeof deliveryValue === "object" ? deliveryValue.status : undefined;
+    const summary = {
+        version: 1,
+        operationId: operation.id,
+        terminalStatus: operation.status === "SUCCEEDED" || operation.status === "FAILED" || operation.status === "CANCELLED" ? operation.status : "UNKNOWN",
+        route: operation.intent?.route ?? null,
+        assurance: operation.intent?.assurance ?? null,
+        currentCandidateId: operation.candidateRevision?.candidateId ?? null,
+        currentCandidateRevision: operation.candidateRevision?.revision ?? null,
+        currentCandidateDigest: operation.candidateRevision?.identityDigest ?? null,
+        participants: totalParticipants,
+        participantGenerations: distinctGenerations,
+        providerTurns,
+        usage: {
+            inputTokens: sumField(participants, "inputTokens"),
+            cachedInputTokens: sumField(participants, "cachedInputTokens"),
+            outputTokens: sumField(participants, "outputTokens"),
+            reasoningOutputTokens: sumField(participants, "reasoningOutputTokens"),
+            totalTokens: sumField(participants, "totalTokens"),
+            totalTokensBasis: totalTokenBasis,
+            costUsd: usageComplete && participants.every((item) => item.costUsd !== null) ? sumField(participants, "costUsd") : null,
+            knownParticipants,
+            participantCount: totalParticipants,
+            costKnownParticipants,
+            completeObservations: participants.filter((item) => item.usageCoverage === "COMPLETE").length,
+            partialObservations: participants.filter((item) => item.usageCoverage === "PARTIAL").length,
+            unknownObservations: participants.filter((item) => item.usageCoverage === "UNKNOWN").length,
+            byParticipant: participantUsageById(participants)
+        },
+        context: {
+            rawContextTokens: contexts.reduce((sum, item) => sum + (item.rawContextTokens ?? 0), 0),
+            projectedContextTokens: contexts.reduce((sum, item) => sum + (item.projectedContextTokens ?? 0), 0),
+            deliveredContextTokens: contexts.reduce((sum, item) => sum + (item.deliveredContextTokens ?? 0), 0),
+            retrievalRequestCount: contexts.reduce((sum, item) => sum + item.retrievalRequestCount, 0) + new Set(retrievals.map((item) => item.requestId)).size,
+            retrievalDeliveredTokens: contexts.reduce((sum, item) => sum + item.retrievalDeliveredTokens, 0) + retrievals.reduce((sum, item) => sum + item.estimatedTokens, 0),
+            crossParticipantRepeatedFragmentTokens: repeatedFragmentTokens,
+            tokenBasis: "AEH_ESTIMATOR"
+        },
+        tools: {
+            toolCalls: tools.length,
+            firstAttemptSuccesses,
+            failedFirstAttempts,
+            retryCalls,
+            recoveredAfterRetry,
+            repeatedEquivalentCalls: tools.filter((item) => item.attemptIndex !== null && item.attemptIndex > 1 && item.causalStatus === "PROVEN").length,
+            unrecoveredToolFailures: tools.filter((item) => item.attemptIndex === 1 && item.outcome !== "SUCCESS" && !retrySequenceRecovered(item, tools)).length,
+            unknownCausalRetries: tools.filter((item) => item.causalStatus === "UNKNOWN" && item.attemptIndex !== null && item.attemptIndex > 1).length,
+            failuresByClass: Object.fromEntries([...failureClasses.entries()].sort(([a], [b]) => a.localeCompare(b))),
+            retryAssociatedInputTokens: retryUsageCoverage === "UNKNOWN" ? null : sumField(retryTurnUsage, "inputTokens"),
+            retryAssociatedOutputTokens: retryUsageCoverage === "UNKNOWN" ? null : sumField(retryTurnUsage, "outputTokens"),
+            retryAssociatedTotalTokens: retryUsageCoverage === "UNKNOWN" ? null : sumField(retryTurnUsage, "totalTokens"),
+            retryUsageCoverage
+        },
+        workflow: {
+            repairRounds: new Set(participants.filter((item) => item.role === "Repairer").map((item) => `${item.participantId}:${item.generation}`)).size,
+            candidateRevisions: candidateRevisionCount(operation, [...participants.map((item) => item.candidateRevision), ...contexts.map((item) => item.candidateRevision), ...tools.map((item) => item.candidateRevision)]),
+            reviewRounds: new Set(participants.filter((item) => item.role === "Reviewer").map((item) => `${item.participantId}:${item.generation}`)).size,
+            humanInterventions: null
+        },
+        timing: {
+            totalDurationMs: durationMs,
+            participantDurationMs: participants.every((item) => item.durationMs !== null) ? participants.reduce((sum, item) => sum + (item.durationMs ?? 0), 0) : null
+        },
+        outcome: {
+            accepted: typeof acceptanceDisposition === "string" ? acceptanceDisposition === "ACCEPTED" : null,
+            delivered: typeof deliveryStatus === "string" ? ["FINALIZED", "HANDOFF_ONLY", "NO_CHANGES"].includes(deliveryStatus) : null
+        },
+        generatedAt
+    };
+    return operationEfficiencySummaryV1Schema.parse(summary);
+}
+export async function readOperationEfficiencyObservations(root, operationId) {
+    const directory = operationDirectory(root, operationId);
+    const [participants, tools, context, retrieval] = await Promise.all([
+        readObservationDirectory(directory, "participants", participantUsageObservationV1Schema),
+        readObservationDirectory(directory, "tools", toolCallObservationV1Schema),
+        readObservationDirectory(directory, "context", contextAccountingObservationV1Schema),
+        readObservationDirectory(directory, "retrieval", contextRetrievalObservationV1Schema)
+    ]);
+    return { participants, tools, context, retrieval };
+}
+async function currentEfficiencyBindingMatches(root, observation) {
+    try {
+        const operation = await loadOperation(resolveOperationStateRoot(root), observation.operationId);
+        const candidate = operation.candidateRevision;
+        const participant = operation.participants?.[observation.participantId];
+        const agent = operation.agents?.find((item) => item.id === observation.participantId || item.id === observation.runtimeSessionId || item.id === observation.sessionId);
+        const binding = participant?.executionBinding ?? agent?.executionBinding;
+        if (!candidate || candidate.candidateId !== observation.candidateId || candidate.revision !== observation.candidateRevision || candidate.identityDigest !== observation.candidateDigest
+            || operation.operationExecutionRevision !== observation.operationExecutionRevision || (operation.controller?.epoch ?? 0) !== observation.controllerEpoch || !participant && !agent)
+            return false;
+        if (!binding)
+            return !observation.generation && !(observation.runtimeSessionId ?? observation.sessionId);
+        if (observation.generation && binding.participantGeneration !== observation.generation)
+            return false;
+        const expectedSession = observation.runtimeSessionId ?? observation.sessionId;
+        if (expectedSession && binding.runtime.sessionId !== expectedSession)
+            return false;
+        return binding.operationExecutionRevision === observation.operationExecutionRevision
+            && binding.candidateRevision === observation.candidateRevision
+            && binding.candidateDigest === observation.candidateDigest
+            && binding.controllerEpoch === observation.controllerEpoch;
+    }
+    catch {
+        return false;
+    }
+}
+function sumTurnUsage(turns) {
+    const result = {};
+    const sum = (field) => {
+        const values = turns.map((turn) => turn[field]).filter((value) => typeof value === "number");
+        return values.length ? values.reduce((total, value) => total + value, 0) : undefined;
+    };
+    result.inputTokens = sum("inputTokens");
+    result.cachedInputTokens = sum("cachedInputTokens");
+    result.outputTokens = sum("outputTokens");
+    result.reasoningOutputTokens = sum("reasoningOutputTokens");
+    result.totalTokens = sum("totalTokens");
+    result.costUsd = sum("costUsd");
+    if (result.totalTokens === undefined && result.inputTokens !== undefined && result.outputTokens !== undefined)
+        result.totalTokens = result.inputTokens + result.outputTokens;
+    return result;
+}
+function repeatedCrossParticipantFragmentTokens(contexts, retrievals) {
+    const recipients = new Map();
+    const add = (participantId, fragmentId, contentDigest, deliveredTokens) => {
+        const key = `${fragmentId}\0${contentDigest}`;
+        const participants = recipients.get(key) ?? new Map();
+        participants.set(participantId, Math.max(participants.get(participantId) ?? 0, deliveredTokens));
+        recipients.set(key, participants);
+    };
+    for (const observation of contexts) {
+        for (const fragment of observation.fragmentIdentities)
+            add(observation.participantId, fragment.fragmentId, fragment.contentDigest, fragment.deliveredTokens);
+    }
+    for (const observation of retrievals)
+        add(observation.participantId, observation.fragmentId, observation.contentDigest, observation.estimatedTokens);
+    let repeated = 0;
+    for (const participants of recipients.values()) {
+        const sorted = [...participants.entries()].sort(([a], [b]) => a.localeCompare(b));
+        for (const [, tokens] of sorted.slice(1))
+            repeated += tokens;
+    }
+    return repeated;
+}
+function retryAssociatedTurnIds(tools) {
+    return new Set(tools.filter((item) => item.retryOfCallId !== null && item.causalStatus === "PROVEN" && item.turnId)
+        .map((item) => `${item.sessionId}\0${item.turnId}`));
+}
+function retrySequenceRecovered(first, tools) {
+    if (!first.callId)
+        return false;
+    const visited = new Set();
+    const pending = [first.callId];
+    while (pending.length) {
+        const priorCallId = pending.shift();
+        if (visited.has(priorCallId))
+            continue;
+        visited.add(priorCallId);
+        for (const retry of tools.filter((item) => item.retryOfCallId === priorCallId && item.causalStatus === "PROVEN")) {
+            if (retry.outcome === "SUCCESS")
+                return true;
+            if (retry.callId)
+                pending.push(retry.callId);
+        }
+    }
+    return false;
+}
+function deduplicateParticipantUsage(observations) {
+    const groups = new Map();
+    for (const item of observations) {
+        const key = [item.participantId, item.generation ?? "", item.runtimeSessionId ?? "", item.provider, item.model ?? ""].join("\0");
+        const group = groups.get(key) ?? [];
+        group.push(item);
+        groups.set(key, group);
+    }
+    return [...groups.values()].map((group) => {
+        const latest = [...group].sort((a, b) => (b.finishedAt ?? b.startedAt ?? "").localeCompare(a.finishedAt ?? a.startedAt ?? "") || a.observationId.localeCompare(b.observationId))[0];
+        if (group.length === 1)
+            return latest;
+        if (!group.every((item) => item.usageSource === "PROVIDER_TURN_EVENTS") || group.some((item) => item.turnUsage.some((turn) => !turn.turnId))) {
+            // Snapshot and adapter totals can be cumulative. Keep only the latest value and
+            // make the loss of interval detail explicit instead of summing a snapshot twice.
+            return { ...latest, usageCoverage: "PARTIAL", totalTokensBasis: latest.totalTokensBasis };
+        }
+        const turns = new Map();
+        for (const item of group)
+            for (const turn of item.turnUsage) {
+                const prior = turns.get(turn.turnId);
+                if (!prior || (turn.at ?? "") > (prior.at ?? ""))
+                    turns.set(turn.turnId, turn);
+            }
+        const uniqueTurns = [...turns.values()].sort((a, b) => (a.turnIndex ?? Number.MAX_SAFE_INTEGER) - (b.turnIndex ?? Number.MAX_SAFE_INTEGER) || (a.at ?? "").localeCompare(b.at ?? ""));
+        const metrics = sumTurnUsage(uniqueTurns);
+        const reportedTurnCounts = group.map((item) => item.turnCount).filter((value) => value !== null);
+        const observedTurnCount = reportedTurnCounts.length ? Math.max(...reportedTurnCounts) : uniqueTurns.length || null;
+        const completeCapture = group.some((item) => item.usageCoverage === "COMPLETE" && item.turnCount === uniqueTurns.length);
+        const totalTokenBases = new Set(uniqueTurns.filter((turn) => turn.totalTokens !== null).map((turn) => turn.totalTokensBasis));
+        const totalTokensBasis = totalTokenBases.size === 1 ? [...totalTokenBases][0]
+            : "UNKNOWN";
+        const startedAt = group.map((item) => item.startedAt).filter((value) => value !== null).sort()[0] ?? null;
+        const finishedAt = group.map((item) => item.finishedAt).filter((value) => value !== null).sort().at(-1) ?? null;
+        return {
+            ...latest,
+            turnCount: observedTurnCount,
+            inputTokens: metrics.inputTokens ?? null,
+            cachedInputTokens: metrics.cachedInputTokens ?? null,
+            outputTokens: metrics.outputTokens ?? null,
+            reasoningOutputTokens: metrics.reasoningOutputTokens ?? null,
+            totalTokens: metrics.totalTokens ?? null,
+            totalTokensBasis,
+            costUsd: metrics.costUsd ?? null,
+            usageKnown: Object.values(metrics).some((value) => value !== undefined),
+            usageCoverage: completeCapture && uniqueTurns.every((turn) => turn.usageKnown) ? "COMPLETE" : "PARTIAL",
+            startedAt,
+            finishedAt,
+            durationMs: Math.max(...group.map((item) => item.durationMs ?? 0)) || null,
+            turnUsage: uniqueTurns
+        };
+    });
+}
+function participantUsageById(participants) {
+    const groups = new Map();
+    for (const item of participants) {
+        const group = groups.get(item.participantId) ?? [];
+        group.push(item);
+        groups.set(item.participantId, group);
+    }
+    const sum = (items, field) => {
+        const known = items.map((item) => item[field]).filter((value) => value !== null);
+        return known.length ? known.reduce((total, value) => total + value, 0) : null;
+    };
+    return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([participantId, items]) => ({
+        participantId,
+        generations: new Set(items.map((item) => item.generation).filter((value) => value !== null)).size,
+        roles: [...new Set(items.map((item) => item.role))].sort(),
+        inputTokens: sum(items, "inputTokens"),
+        cachedInputTokens: sum(items, "cachedInputTokens"),
+        outputTokens: sum(items, "outputTokens"),
+        reasoningOutputTokens: sum(items, "reasoningOutputTokens"),
+        totalTokens: sum(items, "totalTokens"),
+        costUsd: items.length > 0 && items.every((item) => item.usageKnown && item.usageCoverage === "COMPLETE" && item.costUsd !== null) ? items.reduce((total, item) => total + (item.costUsd ?? 0), 0) : null,
+        usageKnown: items.some((item) => item.usageKnown),
+        usageCoverage: items.every((item) => item.usageCoverage === "UNKNOWN") ? "UNKNOWN" : items.every((item) => item.usageKnown && item.usageCoverage === "COMPLETE") ? "COMPLETE" : "PARTIAL"
+    }));
+}
+export function correlateEquivalentToolCalls(observations) {
+    const ordered = [...observations].sort((a, b) => (a.timelineSequence ?? Number.MAX_SAFE_INTEGER) - (b.timelineSequence ?? Number.MAX_SAFE_INTEGER) || (a.startedAt ?? "").localeCompare(b.startedAt ?? ""));
+    const groups = new Map();
+    for (let index = 0; index < ordered.length; index += 1) {
+        const item = ordered[index];
+        if (!item.callId)
+            continue;
+        const identity = [item.toolServer ?? "", item.provider ?? "", item.toolName, item.argumentsDigest].join("\0");
+        const key = item.turnId ? `${identity}\0turn:${item.turnId}` : `${identity}\0unknown-turn`;
+        const group = groups.get(key) ?? [];
+        group.push(index);
+        groups.set(key, group);
+    }
+    return ordered.map((item, index) => {
+        if (!item.callId)
+            return { ...item, attemptIndex: null, retryOfCallId: null, causalStatus: "UNKNOWN" };
+        const identity = [item.toolServer ?? "", item.provider ?? "", item.toolName, item.argumentsDigest].join("\0");
+        const key = item.turnId ? `${identity}\0turn:${item.turnId}` : `${identity}\0unknown-turn`;
+        const group = groups.get(key) ?? [];
+        const position = group.indexOf(index);
+        const prior = position > 0 ? ordered[group[position - 1]] : undefined;
+        const attemptIndex = position + 1;
+        const priorFailure = prior && prior.outcome !== "SUCCESS" && prior.outcome !== "CANCELLED";
+        const retryOfCallId = priorFailure && prior?.callId && item.turnId ? prior.callId : null;
+        const causalStatus = !item.turnId && group.length > 1 ? "UNKNOWN" : "PROVEN";
+        return { ...item, attemptIndex, retryOfCallId, causalStatus };
+    });
+}
+function candidateRevisionCount(operation, revisions) {
+    const values = new Set(revisions);
+    if (operation.candidateRevision)
+        values.add(operation.candidateRevision.revision);
+    for (const receipt of Object.values(operation.candidateAssemblyReceipts ?? {})) {
+        const revision = receipt.candidate?.revision;
+        if (typeof revision === "number" && Number.isSafeInteger(revision))
+            values.add(revision);
+    }
+    return values.size;
+}
+async function writeObservationOnce(root, operationId, kind, observationId, value) {
+    const directory = path.join(operationDirectory(root, operationId), kind);
+    await fs.mkdir(directory, { recursive: true });
+    const file = path.join(directory, `${observationId}.json`);
+    const serialized = `${JSON.stringify(value, null, 2)}\n`;
+    try {
+        const handle = await fs.open(file, "wx");
+        try {
+            await handle.writeFile(serialized);
+        }
+        finally {
+            await handle.close();
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            return false;
+        try {
+            return sha256Utf8(await fs.readFile(file, "utf8")) === sha256Utf8(serialized);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+async function readObservationDirectory(directory, kind, schema) {
+    const folder = path.join(directory, kind);
+    const files = await fs.readdir(folder).catch(() => []);
+    const observations = [];
+    for (const name of files.filter((item) => item.endsWith(".json")).sort()) {
+        try {
+            observations.push(schema.parse(JSON.parse(await fs.readFile(path.join(folder, name), "utf8"))));
+        }
+        catch { /* malformed local observations do not affect deterministic operation state */ }
+    }
+    return observations;
+}
+function operationDirectory(root, operationId) {
+    return path.join(resolveOperationStateRoot(root), EFFICIENCY_ROOT, sha256Utf8(operationId));
+}
+function summaryFile(root, operationId) {
+    return path.join(operationDirectory(root, operationId), "summary.json");
+}
+async function writeJsonAtomic(file, value) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`);
+    await fs.rename(temporary, file);
+}
+function validTimestamp(value) {
+    return value && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
+}
+//# sourceMappingURL=efficiency.js.map