agentic-engineering-harness 0.8.9 → 0.8.11

package/dist/releases/release-1791006063459-16409-661eedf2/telemetry/efficiency.d.ts

@@ -0,0 +1,434 @@
+import { z } from "zod";
+import type { HarnessProjectConfig, UsageMetrics, WorkerSession } from "../core/types.js";
+import { type OperationRecordV2 } from "../operations/state.js";
+import type { CandidateRevisionV1 } from "../operations/v2Contracts.js";
+import { type ExecutionActivityEventV1 } from "../operations/executionLiveness.js";
+export declare const providerTurnUsageObservationV2Schema: z.ZodObject<{
+    turnId: z.ZodNullable<z.ZodString>;
+    turnIndex: z.ZodNullable<z.ZodNumber>;
+    runtimeSessionId: z.ZodNullable<z.ZodString>;
+    provider: z.ZodString;
+    at: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    finishedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    inputTokens: z.ZodNullable<z.ZodNumber>;
+    cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+    outputTokens: z.ZodNullable<z.ZodNumber>;
+    reasoningOutputTokens: z.ZodNullable<z.ZodNumber>;
+    totalTokens: z.ZodNullable<z.ZodNumber>;
+    totalTokensBasis: z.ZodEnum<{
+        UNKNOWN: "UNKNOWN";
+        PROVIDER_REPORTED: "PROVIDER_REPORTED";
+        INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
+    }>;
+    costUsd: z.ZodNullable<z.ZodNumber>;
+    usageKnown: z.ZodBoolean;
+}, z.core.$strict>;
+export type ProviderTurnUsageObservationV2 = z.infer<typeof providerTurnUsageObservationV2Schema>;
+export declare const participantUsageObservationV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    observationId: z.ZodString;
+    operationId: z.ZodString;
+    candidateId: z.ZodString;
+    candidateRevision: z.ZodNumber;
+    candidateDigest: z.ZodString;
+    operationExecutionRevision: z.ZodNumber;
+    controllerEpoch: z.ZodNumber;
+    participantId: z.ZodString;
+    generation: z.ZodNullable<z.ZodString>;
+    role: z.ZodString;
+    phase: z.ZodString;
+    provider: z.ZodString;
+    model: z.ZodNullable<z.ZodString>;
+    runtimeSessionId: z.ZodNullable<z.ZodString>;
+    turnCount: z.ZodNullable<z.ZodNumber>;
+    inputTokens: z.ZodNullable<z.ZodNumber>;
+    cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+    outputTokens: z.ZodNullable<z.ZodNumber>;
+    reasoningOutputTokens: z.ZodNullable<z.ZodNumber>;
+    totalTokens: z.ZodNullable<z.ZodNumber>;
+    totalTokensBasis: z.ZodEnum<{
+        UNKNOWN: "UNKNOWN";
+        PROVIDER_REPORTED: "PROVIDER_REPORTED";
+        INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
+    }>;
+    costUsd: z.ZodNullable<z.ZodNumber>;
+    usageKnown: z.ZodBoolean;
+    usageSource: z.ZodEnum<{
+        UNKNOWN: "UNKNOWN";
+        PROVIDER_TURN_EVENTS: "PROVIDER_TURN_EVENTS";
+        PASEO_AGENT_SNAPSHOT: "PASEO_AGENT_SNAPSHOT";
+        PASEO_ADAPTER: "PASEO_ADAPTER";
+        AEH_TEXT_EXTRACTION: "AEH_TEXT_EXTRACTION";
+    }>;
+    usageCoverage: z.ZodEnum<{
+        PARTIAL: "PARTIAL";
+        UNKNOWN: "UNKNOWN";
+        COMPLETE: "COMPLETE";
+    }>;
+    startedAt: z.ZodNullable<z.ZodString>;
+    lastActivityAt: z.ZodNullable<z.ZodString>;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    resultStatus: z.ZodEnum<{
+        BLOCKED: "BLOCKED";
+        SUCCEEDED: "SUCCEEDED";
+        FAILED: "FAILED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    turnUsage: z.ZodArray<z.ZodObject<{
+        turnId: z.ZodNullable<z.ZodString>;
+        turnIndex: z.ZodNullable<z.ZodNumber>;
+        runtimeSessionId: z.ZodNullable<z.ZodString>;
+        provider: z.ZodString;
+        at: z.ZodNullable<z.ZodString>;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        finishedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        inputTokens: z.ZodNullable<z.ZodNumber>;
+        cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+        outputTokens: z.ZodNullable<z.ZodNumber>;
+        reasoningOutputTokens: z.ZodNullable<z.ZodNumber>;
+        totalTokens: z.ZodNullable<z.ZodNumber>;
+        totalTokensBasis: z.ZodEnum<{
+            UNKNOWN: "UNKNOWN";
+            PROVIDER_REPORTED: "PROVIDER_REPORTED";
+            INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
+        }>;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        usageKnown: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ParticipantUsageObservationV2 = z.infer<typeof participantUsageObservationV2Schema>;
+export declare const toolCallObservationV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    observationId: z.ZodString;
+    operationId: z.ZodString;
+    candidateId: z.ZodString;
+    candidateRevision: z.ZodNumber;
+    candidateDigest: z.ZodString;
+    operationExecutionRevision: z.ZodNumber;
+    controllerEpoch: z.ZodNumber;
+    participantId: z.ZodString;
+    sessionId: z.ZodString;
+    role: z.ZodString;
+    phase: z.ZodString;
+    turnId: z.ZodNullable<z.ZodString>;
+    turnIndex: z.ZodNullable<z.ZodNumber>;
+    timelineSequence: z.ZodNullable<z.ZodNumber>;
+    toolServer: z.ZodNullable<z.ZodString>;
+    provider: z.ZodNullable<z.ZodString>;
+    toolName: z.ZodString;
+    callId: z.ZodNullable<z.ZodString>;
+    attemptIndex: z.ZodNullable<z.ZodNumber>;
+    argumentsDigest: z.ZodString;
+    argumentsByteLength: z.ZodNullable<z.ZodNumber>;
+    startedAt: z.ZodNullable<z.ZodString>;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    outcome: z.ZodEnum<{
+        CANCELLED: "CANCELLED";
+        UNAVAILABLE: "UNAVAILABLE";
+        SUCCESS: "SUCCESS";
+        TOOL_ERROR: "TOOL_ERROR";
+        PERMISSION_DENIED: "PERMISSION_DENIED";
+        TIMEOUT: "TIMEOUT";
+        INVALID_ARGUMENT: "INVALID_ARGUMENT";
+        UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    }>;
+    resultByteLength: z.ZodNullable<z.ZodNumber>;
+    errorFingerprint: z.ZodNullable<z.ZodString>;
+    retryOfCallId: z.ZodNullable<z.ZodString>;
+    causalStatus: z.ZodEnum<{
+        UNKNOWN: "UNKNOWN";
+        PROVEN: "PROVEN";
+        EQUIVALENT_ONLY: "EQUIVALENT_ONLY";
+    }>;
+}, z.core.$strict>;
+export type ToolCallObservationV2 = z.infer<typeof toolCallObservationV2Schema>;
+export declare const contextAccountingObservationV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    observationId: z.ZodString;
+    operationId: z.ZodString;
+    candidateId: z.ZodString;
+    candidateRevision: z.ZodNumber;
+    candidateDigest: z.ZodString;
+    operationExecutionRevision: z.ZodNumber;
+    controllerEpoch: z.ZodNumber;
+    participantId: z.ZodString;
+    generation: z.ZodNullable<z.ZodString>;
+    role: z.ZodString;
+    logicalAgent: z.ZodString;
+    phase: z.ZodString;
+    runtimeSessionId: z.ZodNullable<z.ZodString>;
+    envelopeDigest: z.ZodString;
+    rawContextTokens: z.ZodNullable<z.ZodNumber>;
+    projectedContextTokens: z.ZodNullable<z.ZodNumber>;
+    deliveredContextTokens: z.ZodNullable<z.ZodNumber>;
+    retrievalRequestCount: z.ZodNumber;
+    retrievalDeliveredTokens: z.ZodNumber;
+    fragmentIdentities: z.ZodArray<z.ZodObject<{
+        fragmentId: z.ZodString;
+        contentDigest: z.ZodString;
+        deliveredTokens: z.ZodNumber;
+    }, z.core.$strict>>;
+    tokenBasis: z.ZodLiteral<"AEH_ESTIMATOR">;
+}, z.core.$strict>;
+export type ContextAccountingObservationV2 = z.infer<typeof contextAccountingObservationV2Schema>;
+export declare const contextRetrievalObservationV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    operationId: z.ZodString;
+    candidateId: z.ZodString;
+    candidateRevision: z.ZodNumber;
+    candidateDigest: z.ZodString;
+    operationExecutionRevision: z.ZodNumber;
+    controllerEpoch: z.ZodNumber;
+    participantId: z.ZodString;
+    generation: z.ZodNullable<z.ZodString>;
+    role: z.ZodString;
+    phase: z.ZodString;
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    fragmentId: z.ZodString;
+    contentDigest: z.ZodString;
+    estimatedTokens: z.ZodNumber;
+    repeated: z.ZodBoolean;
+    retrievedAt: z.ZodString;
+    tokenBasis: z.ZodLiteral<"AEH_ESTIMATOR">;
+}, z.core.$strict>;
+export type ContextRetrievalObservationV2 = z.infer<typeof contextRetrievalObservationV2Schema>;
+export declare const operationEfficiencySummaryV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    operationId: z.ZodString;
+    terminalStatus: z.ZodEnum<{
+        SUCCEEDED: "SUCCEEDED";
+        FAILED: "FAILED";
+        CANCELLED: "CANCELLED";
+        UNKNOWN: "UNKNOWN";
+    }>;
+    route: z.ZodNullable<z.ZodString>;
+    assurance: z.ZodNullable<z.ZodString>;
+    currentCandidateId: z.ZodNullable<z.ZodString>;
+    currentCandidateRevision: z.ZodNullable<z.ZodNumber>;
+    currentCandidateDigest: z.ZodNullable<z.ZodString>;
+    participants: z.ZodNumber;
+    participantGenerations: z.ZodNumber;
+    providerTurns: z.ZodNullable<z.ZodNumber>;
+    budgets: z.ZodObject<{
+        providerTurns: z.ZodObject<{
+            scope: z.ZodLiteral<"PER_PARTICIPANT">;
+            participantCount: z.ZodNumber;
+            observed: z.ZodNullable<z.ZodNumber>;
+            initialPerParticipant: z.ZodNullable<z.ZodNumber>;
+            initialAggregateEquivalent: z.ZodNullable<z.ZodNumber>;
+            currentAllowanceAggregate: z.ZodNullable<z.ZodNumber>;
+            supervisorCeilingPerParticipant: z.ZodNullable<z.ZodNumber>;
+            supervisorCeilingAggregateEquivalent: z.ZodNullable<z.ZodNumber>;
+            hardCeilingPerParticipant: z.ZodNullable<z.ZodNumber>;
+            hardCeilingAggregateEquivalent: z.ZodNullable<z.ZodNumber>;
+            softThreshold: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        toolCalls: z.ZodObject<{
+            observed: z.ZodNullable<z.ZodNumber>;
+            hardLimit: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        tokenUsage: z.ZodObject<{
+            observed: z.ZodNullable<z.ZodNumber>;
+            hardLimit: z.ZodNullable<z.ZodNumber>;
+            coverage: z.ZodEnum<{
+                PARTIAL: "PARTIAL";
+                UNKNOWN: "UNKNOWN";
+                COMPLETE: "COMPLETE";
+            }>;
+        }, z.core.$strict>;
+        cost: z.ZodObject<{
+            observedUsd: z.ZodNullable<z.ZodNumber>;
+            hardLimitUsd: z.ZodNullable<z.ZodNumber>;
+            coverage: z.ZodEnum<{
+                PARTIAL: "PARTIAL";
+                UNKNOWN: "UNKNOWN";
+                COMPLETE: "COMPLETE";
+            }>;
+        }, z.core.$strict>;
+        recovery: z.ZodObject<{
+            localRetries: z.ZodNullable<z.ZodNumber>;
+            localRetryLimit: z.ZodNullable<z.ZodNumber>;
+            participantRestarts: z.ZodNullable<z.ZodNumber>;
+            participantRestartLimit: z.ZodNullable<z.ZodNumber>;
+            noProgressRenewals: z.ZodNullable<z.ZodNumber>;
+            progressLeaseRenewals: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        hardDeadlineAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNullable<z.ZodNumber>;
+        cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+        outputTokens: z.ZodNullable<z.ZodNumber>;
+        reasoningOutputTokens: z.ZodNullable<z.ZodNumber>;
+        totalTokens: z.ZodNullable<z.ZodNumber>;
+        totalTokensBasis: z.ZodEnum<{
+            UNKNOWN: "UNKNOWN";
+            PROVIDER_REPORTED: "PROVIDER_REPORTED";
+            INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
+        }>;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        knownParticipants: z.ZodNumber;
+        participantCount: z.ZodNumber;
+        costKnownParticipants: z.ZodNumber;
+        completeObservations: z.ZodNumber;
+        partialObservations: z.ZodNumber;
+        unknownObservations: z.ZodNumber;
+        byParticipant: z.ZodArray<z.ZodObject<{
+            participantId: z.ZodString;
+            generations: z.ZodNumber;
+            roles: z.ZodArray<z.ZodString>;
+            inputTokens: z.ZodNullable<z.ZodNumber>;
+            cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+            outputTokens: z.ZodNullable<z.ZodNumber>;
+            reasoningOutputTokens: z.ZodNullable<z.ZodNumber>;
+            totalTokens: z.ZodNullable<z.ZodNumber>;
+            costUsd: z.ZodNullable<z.ZodNumber>;
+            usageKnown: z.ZodBoolean;
+            usageCoverage: z.ZodEnum<{
+                PARTIAL: "PARTIAL";
+                UNKNOWN: "UNKNOWN";
+                COMPLETE: "COMPLETE";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    context: z.ZodObject<{
+        rawContextTokens: z.ZodNumber;
+        projectedContextTokens: z.ZodNumber;
+        deliveredContextTokens: z.ZodNumber;
+        retrievalRequestCount: z.ZodNumber;
+        retrievalDeliveredTokens: z.ZodNumber;
+        crossParticipantRepeatedFragmentTokens: z.ZodNumber;
+        tokenBasis: z.ZodLiteral<"AEH_ESTIMATOR">;
+    }, z.core.$strict>;
+    tools: z.ZodObject<{
+        toolCalls: z.ZodNumber;
+        firstAttemptSuccesses: z.ZodNumber;
+        failedFirstAttempts: z.ZodNumber;
+        retryCalls: z.ZodNumber;
+        recoveredAfterRetry: z.ZodNumber;
+        repeatedEquivalentCalls: z.ZodNumber;
+        unrecoveredToolFailures: z.ZodNumber;
+        unknownCausalRetries: z.ZodNumber;
+        failuresByClass: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        retryAssociatedInputTokens: z.ZodNullable<z.ZodNumber>;
+        retryAssociatedOutputTokens: z.ZodNullable<z.ZodNumber>;
+        retryAssociatedTotalTokens: z.ZodNullable<z.ZodNumber>;
+        retryUsageCoverage: z.ZodEnum<{
+            PARTIAL: "PARTIAL";
+            UNKNOWN: "UNKNOWN";
+            COMPLETE: "COMPLETE";
+        }>;
+    }, z.core.$strict>;
+    activity: z.ZodObject<{
+        timeToFirstToolCallMs: z.ZodNullable<z.ZodNumber>;
+        timeToFirstMutationMs: z.ZodNullable<z.ZodNumber>;
+        timeSinceLastMeaningfulProgressMs: z.ZodNullable<z.ZodNumber>;
+        toolCallsBeforeFirstMutation: z.ZodNullable<z.ZodNumber>;
+        turnsBeforeFirstMutation: z.ZodNullable<z.ZodNumber>;
+        tokensBeforeFirstMutation: z.ZodNullable<z.ZodNumber>;
+        repositoryMutationCount: z.ZodNullable<z.ZodNumber>;
+        artifactCount: z.ZodNullable<z.ZodNumber>;
+        validationCount: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    workflow: z.ZodObject<{
+        repairRounds: z.ZodNumber;
+        candidateRevisions: z.ZodNumber;
+        reviewRounds: z.ZodNumber;
+        humanInterventions: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    timing: z.ZodObject<{
+        totalDurationMs: z.ZodNullable<z.ZodNumber>;
+        participantDurationMs: z.ZodNullable<z.ZodNumber>;
+        activeProviderDurationMs: z.ZodNullable<z.ZodNumber>;
+        toolWaitDurationMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    outcome: z.ZodObject<{
+        accepted: z.ZodNullable<z.ZodBoolean>;
+        delivered: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>;
+    generatedAt: z.ZodString;
+}, z.core.$strict>;
+export type OperationEfficiencySummaryV2 = z.infer<typeof operationEfficiencySummaryV2Schema>;
+export interface ProviderTelemetryEvidenceV2 {
+    version: 2;
+    source: "PROVIDER_TURN_EVENTS" | "PASEO_AGENT_SNAPSHOT" | "PASEO_ADAPTER" | "UNKNOWN";
+    coverage: "COMPLETE" | "PARTIAL" | "UNKNOWN";
+    turnCount: number | null;
+    turns: ProviderTurnUsageObservationV2[];
+    toolCalls: ProviderToolCallEvidenceV2[];
+    snapshotUsage?: UsageMetrics;
+}
+export type ProviderToolCallEvidenceV2 = Omit<ToolCallObservationV2, "version" | "observationId" | "operationId" | "candidateId" | "candidateRevision" | "candidateDigest" | "operationExecutionRevision" | "controllerEpoch" | "participantId" | "sessionId" | "role" | "phase" | "attemptIndex" | "retryOfCallId" | "causalStatus"> & {
+    retryOfCallId?: string | null;
+};
+export declare function participantUsageObservationFromSession(input: {
+    operationId: string;
+    participantId: string;
+    role: string;
+    phase: string;
+    candidate: CandidateRevisionV1;
+    session: WorkerSession;
+    providerTelemetry?: ProviderTelemetryEvidenceV2;
+    lastActivityAt?: string;
+    resultStatus?: ParticipantUsageObservationV2["resultStatus"];
+}): ParticipantUsageObservationV2 | undefined;
+export declare function recordParticipantUsageObservation(root: string, config: HarnessProjectConfig, observation: ParticipantUsageObservationV2): Promise<boolean>;
+export declare function recordToolCallObservations(root: string, config: HarnessProjectConfig, input: {
+    operationId: string;
+    participantId: string;
+    role: string;
+    phase: string;
+    candidate: CandidateRevisionV1;
+    operationExecutionRevision: number;
+    controllerEpoch: number;
+    participantGeneration: string;
+    sessionId: string;
+    observations: ProviderTelemetryEvidenceV2["toolCalls"];
+}): Promise<number>;
+export declare function recordContextAccountingObservation(root: string, config: HarnessProjectConfig, input: {
+    operationId: string;
+    participantId?: string;
+    generation?: string;
+    role: string;
+    logicalAgent: string;
+    phase: string;
+    candidate: CandidateRevisionV1;
+    operationExecutionRevision: number;
+    controllerEpoch: number;
+    runtimeSessionId?: string;
+    envelopeDigest: string;
+    rawContextTokens: number;
+    projectedContextTokens: number;
+    deliveredContextTokens: number;
+    fragmentIdentities: Array<{
+        fragmentId: string;
+        contentDigest: string;
+        deliveredTokens: number;
+    }>;
+}): Promise<boolean>;
+export declare function recordContextRetrievalObservation(root: string, observation: ContextRetrievalObservationV2): Promise<boolean>;
+export declare function writeOperationEfficiencySummary(root: string, config: HarnessProjectConfig, operation: OperationRecordV2): Promise<OperationEfficiencySummaryV2 | undefined>;
+export declare function readOperationEfficiencySummary(root: string, operation: OperationRecordV2): Promise<OperationEfficiencySummaryV2 | undefined>;
+export declare function summarizeOperationEfficiencyV2(operation: OperationRecordV2, observations: {
+    participants: ParticipantUsageObservationV2[];
+    tools: ToolCallObservationV2[];
+    context: ContextAccountingObservationV2[];
+    retrieval: ContextRetrievalObservationV2[];
+    activity?: ExecutionActivityEventV1[];
+}, generatedAt?: string): OperationEfficiencySummaryV2;
+export declare function readOperationEfficiencyObservations(root: string, operationId: string): Promise<{
+    participants: ParticipantUsageObservationV2[];
+    tools: ToolCallObservationV2[];
+    context: ContextAccountingObservationV2[];
+    retrieval: ContextRetrievalObservationV2[];
+    activity: ExecutionActivityEventV1[];
+}>;
+export declare function correlateEquivalentToolCalls(observations: ProviderTelemetryEvidenceV2["toolCalls"]): Array<Omit<ProviderTelemetryEvidenceV2["toolCalls"][number], "retryOfCallId"> & {
+    attemptIndex: number | null;
+    retryOfCallId: string | null;
+    causalStatus: "PROVEN" | "EQUIVALENT_ONLY" | "UNKNOWN";
+}>;