engineering-behavior-observatory 0.2.1

package/dist/src/agent-sdk.d.ts

@@ -0,0 +1,294 @@
+import { type HookEvent, type HookInput, type Options, type PermissionMode, type SDKMessage, type SDKResultMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { AttemptIdentity, EvidenceSink, HarnessExecutionContext, HarnessExecutionResult, RunIdentity } from "./lifecycle.js";
+export type ClaudeAgentSdkConfiguration = {
+    prompt: string;
+    model: string;
+    tools: string[];
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    permissionMode: PermissionMode;
+    allowDangerouslySkipPermissions?: boolean;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    env?: NodeJS.ProcessEnv;
+    telemetry?: ClaudeAgentSdkTelemetryConfiguration;
+};
+export type ClaudeAgentSdkTelemetrySignal = "traces" | "metrics" | "logs";
+export type ClaudeAgentSdkTelemetryCorrelation = {
+    type: "resource-attributes";
+    attributes: {
+        "ebo.run.id": string;
+        "ebo.attempt.id": string;
+        "ebo.attempt.number": string;
+    };
+};
+export type ClaudeAgentSdkTelemetryReceipt = {
+    status: "received";
+    signals: ClaudeAgentSdkTelemetrySignal[];
+} | {
+    status: "missing";
+    signals: ClaudeAgentSdkTelemetrySignal[];
+    reason: "not-received" | "collector-unreachable" | "process-interrupted" | "partial-receipt" | "receipt-check-failed";
+} | {
+    status: "not-checked";
+    signals: [];
+    reason: "no-receipt-check";
+};
+export type ClaudeAgentSdkTelemetryConfiguration = {
+    endpoint: string;
+    protocol?: "http/protobuf" | "http/json" | "grpc";
+    exportIntervalMs?: number;
+    logUserPrompts?: boolean;
+    logToolDetails?: boolean;
+    logToolContent?: boolean;
+    logRawApiBodies?: boolean;
+    detailedHookSpans?: {
+        endpoint: string;
+    };
+    checkReceipt?: (correlation: ClaudeAgentSdkTelemetryCorrelation) => ClaudeAgentSdkTelemetryReceipt | Promise<ClaudeAgentSdkTelemetryReceipt>;
+};
+export type ClaudeAgentSdkTelemetryEvidence = {
+    effectiveSettings: {
+        endpoint: string;
+        protocol: "http/protobuf" | "http/json" | "grpc";
+        exporters: Record<ClaudeAgentSdkTelemetrySignal, "otlp">;
+        exportIntervalMs: Record<ClaudeAgentSdkTelemetrySignal, number>;
+        diagnostics: "stderr";
+        content: {
+            userPrompts: boolean;
+            toolDetails: boolean;
+            toolContent: boolean;
+            rawApiBodies: boolean;
+        };
+        secretHeadersConfigured: boolean;
+    };
+    correlation: ClaudeAgentSdkTelemetryCorrelation & {
+        inheritedResourceAttributesPreserved: boolean;
+    };
+    traces: {
+        status: "beta";
+    };
+    hookSpans: {
+        status: "disabled";
+    } | {
+        status: "enabled";
+        stability: "detailed-beta";
+        endpoint: string;
+    };
+    receipt: ClaudeAgentSdkTelemetryReceipt;
+};
+export type ClaudeAgentSdkEnvironment = {
+    env: NodeJS.ProcessEnv;
+    telemetry?: ClaudeAgentSdkTelemetryEvidence;
+};
+export type ClaudeAgentSdkLifecycleEvent = {
+    type: "started";
+    at: string;
+} | {
+    type: "abort-requested";
+    at: string;
+    reason?: string;
+} | {
+    type: "completed";
+    at: string;
+    messageCount: number;
+} | {
+    type: "failed";
+    at: string;
+    messageCount: number;
+    error: string;
+};
+export type ClaudeAgentSdkMessageDiagnostic = {
+    sequence: number;
+    code: "unknown-native-type";
+    nativeType: string;
+};
+export type ClaudeAgentSdkMessageRecord = {
+    schemaVersion: "ebo.agent-sdk-message/v1";
+    sequence: number;
+    capturedAt: string;
+    nativeType: string;
+    nativeSubtype?: string;
+    sessionId?: string;
+    message: SDKMessage;
+    diagnostics?: ClaudeAgentSdkMessageDiagnostic[];
+};
+export type ClaudeAgentSdkCaptureReport = {
+    schemaVersion: "ebo.agent-sdk-capture/v1";
+    status: "complete" | "partial";
+    artifact: {
+        path: string;
+        kind: "session";
+        authority: "semantic";
+        mediaType: "application/x-ndjson";
+        sharingClass: "restricted";
+    };
+    capabilities: {
+        typedMessageStream: {
+            status: "available";
+            messageCount: number;
+        };
+        sessionIdentity: {
+            status: "available";
+            sessionId: string;
+            source: "sdk-result.session_id" | "sdk-message.session_id";
+        } | {
+            status: "missing";
+            reason: "not-emitted";
+        };
+    };
+    result?: {
+        uuid: string;
+        subtype: string;
+        sessionId: string;
+    };
+    diagnostics: {
+        count: number;
+        retained: ClaudeAgentSdkMessageDiagnostic[];
+        truncated: boolean;
+    };
+};
+export type ClaudeAgentSdkEvidenceSink = EvidenceSink & {
+    message: (message: SDKMessage) => void | Promise<void>;
+    stderr: (data: string) => void;
+    hook: (event: HookEvent, input: HookInput, toolUseId: string | undefined, signal: AbortSignal) => void | Promise<void>;
+    lifecycle: (event: ClaudeAgentSdkLifecycleEvent) => void | Promise<void>;
+};
+export type ClaudeAgentSdkHookRecord = {
+    schemaVersion: "ebo.claude-agent-hook/v1";
+    sequence: number;
+    callbackAt: string;
+    hook: HookEvent;
+    sessionId: string;
+    transcriptPath: string;
+    cwd: string;
+    promptId?: string;
+    toolUseId?: string;
+    agentId?: string;
+    agentType?: string;
+    signalAborted: boolean;
+    callbackOutput: Record<string, never>;
+    nativePayload: HookInput;
+};
+export type ClaudeAgentSdkHookCapture = {
+    path: string;
+    hook: ClaudeAgentSdkEvidenceSink["hook"];
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+};
+export type ClaudeAgentSdkCaptureWarnings = {
+    count: number;
+    diagnostic: string;
+    sizeBytes: number;
+    truncated: boolean;
+};
+export type ClaudeAgentSdkStreamCapture = ClaudeAgentSdkEvidenceSink & {
+    path: string;
+    flush: () => Promise<void>;
+    report: () => ClaudeAgentSdkCaptureReport;
+    close: () => Promise<void>;
+};
+export type ClaudeAgentSdkCapabilities = {
+    sdkVersion: string;
+    claudeCodeVersion: string;
+    query: {
+        status: "available";
+    };
+    typedMessageStream: {
+        status: "available";
+    };
+    stderr: {
+        status: "available";
+    };
+    abort: {
+        status: "available";
+    };
+    hookLifecycleMessages: {
+        status: "available";
+    };
+    hooks: Record<HookEvent, {
+        status: "available";
+        evidence: "callback";
+    }>;
+    unsupportedHooks: string[];
+    hookOccurrenceAuthority: "hooks.jsonl";
+    telemetry: {
+        metrics: {
+            status: "available";
+            stability: "stable";
+        };
+        logs: {
+            status: "available";
+            stability: "stable";
+        };
+        traces: {
+            status: "available";
+            stability: "beta";
+        };
+        hookSpans: {
+            status: "optional";
+            stability: "detailed-beta";
+        };
+    };
+    detailedBetaHookSpanTiming: {
+        status: "unsupported";
+        optional: true;
+        reason: string;
+    };
+    missingEvidence: Array<{
+        capability: "detailed-beta-hook-span-timing";
+        reason: string;
+    }>;
+};
+export type ClaudeAgentSdkQueryHandle = AsyncIterable<SDKMessage> & {
+    close: () => void;
+};
+export type ClaudeAgentSdkQuery = (input: {
+    prompt: string;
+    options?: Options;
+}) => ClaudeAgentSdkQueryHandle;
+export type ClaudeAgentSdkAttemptEvidence = {
+    runtime: Array<{
+        source: "anthropic";
+        name: "agent-sdk" | "agent-cli";
+        version: string;
+    }>;
+    effectiveConfiguration: {
+        model: string;
+        tools: string[];
+        allowedTools: string[];
+        disallowedTools: string[];
+        permissionMode: PermissionMode;
+        environment: {
+            parentPreserved: true;
+            overridesApplied: boolean;
+        };
+        budget: {
+            wallClockMs?: number;
+            maxTurns?: number;
+            maxBudgetUsd?: number;
+        };
+        workingDirectory: "attempt-workspace";
+    };
+    capabilities: ClaudeAgentSdkCapabilities;
+    telemetry?: ClaudeAgentSdkTelemetryEvidence;
+    usage?: {
+        source: "sdk-result";
+        totalCostUsd: number;
+        numTurns: number;
+        mainLoop: SDKResultMessage["usage"];
+        byModel: SDKResultMessage["modelUsage"];
+    };
+    captureWarnings: ClaudeAgentSdkCaptureWarnings;
+};
+export declare function openClaudeAgentSdkHookCapture(path: string, now?: () => string): Promise<ClaudeAgentSdkHookCapture>;
+export declare function openClaudeAgentSdkStreamCapture(path: string, sink: ClaudeAgentSdkEvidenceSink, now?: () => string): Promise<ClaudeAgentSdkStreamCapture>;
+export declare function probeClaudeAgentSdkCapabilities(): ClaudeAgentSdkCapabilities;
+export declare function buildClaudeAgentSdkEnvironment(input: {
+    inherited: NodeJS.ProcessEnv;
+    overrides?: NodeJS.ProcessEnv;
+    telemetry?: ClaudeAgentSdkTelemetryConfiguration;
+    run: RunIdentity;
+    attempt: AttemptIdentity;
+}): ClaudeAgentSdkEnvironment;
+export declare function executeClaudeAgentSdk(context: HarnessExecutionContext, configuration: ClaudeAgentSdkConfiguration, sink: ClaudeAgentSdkEvidenceSink, queryFunction?: ClaudeAgentSdkQuery): Promise<HarnessExecutionResult>;