agentic-engineering-harness 0.8.9 → 0.8.11

package/dist/releases/release-1790907061787-15660-749049ca/telemetry/efficiency.d.ts

@@ -1,362 +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";
-export declare const providerTurnUsageObservationV1Schema: 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>;
-    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<{
-        PROVIDER_REPORTED: "PROVIDER_REPORTED";
-        INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
-        UNKNOWN: "UNKNOWN";
-    }>;
-    costUsd: z.ZodNullable<z.ZodNumber>;
-    usageKnown: z.ZodBoolean;
-}, z.core.$strict>;
-export type ProviderTurnUsageObservationV1 = z.infer<typeof providerTurnUsageObservationV1Schema>;
-export declare const participantUsageObservationV1Schema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    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<{
-        PROVIDER_REPORTED: "PROVIDER_REPORTED";
-        INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
-        UNKNOWN: "UNKNOWN";
-    }>;
-    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>;
-    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>;
-        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<{
-            PROVIDER_REPORTED: "PROVIDER_REPORTED";
-            INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
-            UNKNOWN: "UNKNOWN";
-        }>;
-        costUsd: z.ZodNullable<z.ZodNumber>;
-        usageKnown: z.ZodBoolean;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export type ParticipantUsageObservationV1 = z.infer<typeof participantUsageObservationV1Schema>;
-export declare const toolCallObservationV1Schema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    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";
-        SUCCESS: "SUCCESS";
-        TOOL_ERROR: "TOOL_ERROR";
-        PERMISSION_DENIED: "PERMISSION_DENIED";
-        TIMEOUT: "TIMEOUT";
-        INVALID_ARGUMENT: "INVALID_ARGUMENT";
-        UNAVAILABLE: "UNAVAILABLE";
-        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 ToolCallObservationV1 = z.infer<typeof toolCallObservationV1Schema>;
-export declare const contextAccountingObservationV1Schema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    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 ContextAccountingObservationV1 = z.infer<typeof contextAccountingObservationV1Schema>;
-export declare const contextRetrievalObservationV1Schema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    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 ContextRetrievalObservationV1 = z.infer<typeof contextRetrievalObservationV1Schema>;
-export declare const operationEfficiencySummaryV1Schema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    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>;
-    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<{
-            PROVIDER_REPORTED: "PROVIDER_REPORTED";
-            INPUT_PLUS_OUTPUT: "INPUT_PLUS_OUTPUT";
-            UNKNOWN: "UNKNOWN";
-        }>;
-        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>;
-    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>;
-    }, 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 OperationEfficiencySummaryV1 = z.infer<typeof operationEfficiencySummaryV1Schema>;
-export interface ProviderTelemetryEvidenceV1 {
-    source: "PROVIDER_TURN_EVENTS" | "PASEO_AGENT_SNAPSHOT" | "PASEO_ADAPTER" | "UNKNOWN";
-    coverage: "COMPLETE" | "PARTIAL" | "UNKNOWN";
-    turnCount: number | null;
-    turns: ProviderTurnUsageObservationV1[];
-    toolCalls: Array<Omit<ToolCallObservationV1, "version" | "observationId" | "operationId" | "candidateId" | "candidateRevision" | "candidateDigest" | "operationExecutionRevision" | "controllerEpoch" | "participantId" | "sessionId" | "role" | "phase" | "attemptIndex" | "retryOfCallId" | "causalStatus">>;
-    snapshotUsage?: UsageMetrics;
-}
-export declare function participantUsageObservationFromSession(input: {
-    operationId: string;
-    participantId: string;
-    role: string;
-    phase: string;
-    candidate: CandidateRevisionV1;
-    session: WorkerSession;
-    providerTelemetry?: ProviderTelemetryEvidenceV1;
-    resultStatus?: ParticipantUsageObservationV1["resultStatus"];
-}): ParticipantUsageObservationV1 | undefined;
-export declare function recordParticipantUsageObservation(root: string, config: HarnessProjectConfig, observation: ParticipantUsageObservationV1): 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: ProviderTelemetryEvidenceV1["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, config: HarnessProjectConfig, observation: ContextRetrievalObservationV1): Promise<boolean>;
-export declare function writeOperationEfficiencySummary(root: string, config: HarnessProjectConfig, operation: OperationRecordV2): Promise<OperationEfficiencySummaryV1 | undefined>;
-export declare function readOperationEfficiencySummary(root: string, operation: OperationRecordV2): Promise<OperationEfficiencySummaryV1 | undefined>;
-export declare function summarizeOperationEfficiencyV1(operation: OperationRecordV2, observations: {
-    participants: ParticipantUsageObservationV1[];
-    tools: ToolCallObservationV1[];
-    context: ContextAccountingObservationV1[];
-    retrieval: ContextRetrievalObservationV1[];
-}, generatedAt?: string): OperationEfficiencySummaryV1;
-export declare function readOperationEfficiencyObservations(root: string, operationId: string): Promise<{
-    participants: ParticipantUsageObservationV1[];
-    tools: ToolCallObservationV1[];
-    context: ContextAccountingObservationV1[];
-    retrieval: ContextRetrievalObservationV1[];
-}>;
-export declare function correlateEquivalentToolCalls(observations: ProviderTelemetryEvidenceV1["toolCalls"]): Array<ProviderTelemetryEvidenceV1["toolCalls"][number] & {
-    attemptIndex: number | null;
-    retryOfCallId: string | null;
-    causalStatus: "PROVEN" | "EQUIVALENT_ONLY" | "UNKNOWN";
-}>;