agentic-engineering-harness 0.8.21 → 0.9.0

package/dist/releases/release-1791103495992-16667-285ae1e3/telemetry/efficiency.d.ts

@@ -1,434 +0,0 @@
-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";
-}>;