@apo-ai/sdk 0.9.1 → 0.9.3

package/dist/agent-task/integrations/ai-sdk.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-CevT0hQg.js';
+import { A as AgentTaskTraceContext } from '../../tracing-Dqbuc7AK.js';
 
 /**
  * Vercel AI SDK tracing integration for apo.

package/dist/agent-task/integrations/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-CevT0hQg.js';
+import { A as AgentTaskTraceContext } from '../../tracing-Dqbuc7AK.js';
 
 /**
  * Anthropic JS SDK tracing integration for apo.

package/dist/agent-task/integrations/openai.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-CevT0hQg.js';
+import { A as AgentTaskTraceContext } from '../../tracing-Dqbuc7AK.js';
 
 /**
  * OpenAI JS SDK tracing integration for apo.

package/dist/agent-task/public.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext, a as AgentTaskTraceOptions } from '../tracing-CevT0hQg.js';
+import { A as AgentTaskTraceContext, a as AgentTaskTraceOptions } from '../tracing-Dqbuc7AK.js';
 export { CreateApoTracerOptions, createApoTracer } from './integrations/ai-sdk.js';
 export { CreateApoOpenAIOptions, createApoOpenAI } from './integrations/openai.js';
 export { CreateApoAnthropicOptions, createApoAnthropic } from './integrations/anthropic.js';
@@ -278,6 +278,61 @@ declare function getTaskTurn(): TurnFn | undefined;
 declare function resetTaskTurn(): void;
 declare function resolveTurn(adapterTurn: TurnFn | undefined, taskTurn: TurnFn | undefined): TurnFn;
 
+/**
+ * Normalized transcript model — the common shape every harness transcript
+ * parser produces, and the input to the OTLP translator.
+ *
+ * The model is deliberately lossy-but-sufficient for trace reconstruction:
+ * per turn it keeps the user/assistant text, thinking, tool calls with their
+ * results, model identity, and token usage. Anything the projection cannot
+ * use (streaming chunk boundaries, harness housekeeping) is folded away.
+ */
+type TranscriptSource = "claude-code" | "codex";
+type TranscriptUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+};
+type TranscriptToolCall = {
+    callId: string;
+    name: string;
+    /** Arguments exactly as recorded — parsed object when the harness allows, raw string otherwise. */
+    input: unknown;
+    /** Rendered result text or the raw output payload; absent when the transcript never recorded one. */
+    result?: unknown;
+    /** ISO timestamp of the call, when the transcript carries one. */
+    startedAt?: string;
+    /** ISO timestamp of the matching result, when the transcript carries one. */
+    endedAt?: string;
+};
+type TranscriptTurn = {
+    /** Zero-based position of the turn within the session. */
+    index: number;
+    /** ISO timestamp of the user message that opened the turn. */
+    startedAt: string;
+    /** ISO timestamp of the last observed event in the turn, when known. */
+    endedAt?: string;
+    model?: string;
+    userMessage?: string;
+    assistantMessage?: string;
+    /** Extended-thinking text (Claude) or reasoning summaries (Codex). */
+    thinkingText?: string;
+    /** Codex commentary-phase messages (progress narration, not reasoning). */
+    commentary?: string[];
+    toolCalls: TranscriptToolCall[];
+    usage?: TranscriptUsage;
+};
+type ParsedTranscriptSession = {
+    source: TranscriptSource;
+    sessionId: string;
+    cwd?: string;
+    turns: TranscriptTurn[];
+    /** Non-fatal parse issues: torn lines, unterminated turns, unmatched outputs. */
+    warnings: string[];
+};
+
 type ValidatableSchemaLike = {
     safeParse: (data: unknown) => {
         success: boolean;
@@ -343,6 +398,21 @@ type CleanupContext = {
     session?: AdapterSession;
     trace: AgentTaskTraceContext;
 };
+/**
+ * A harness session transcript the adapter captured on disk.
+ *
+ * Declaring one opts the run into transcript-replay capture: after the turn
+ * loop, the runner parses the session file and replays it into the run —
+ * exported spans join the live trace and projection observations join the
+ * snapshot — so a harness that cannot emit OTel (Codex CLI, plain Claude
+ * Code, anything that only writes session JSONL) still produces a fully
+ * assertable trace. The file must exist and be complete when the turn loop
+ * ends; a missing file fails the run.
+ */
+type AdapterTranscriptCapture = {
+    source: TranscriptSource;
+    path: string;
+};
 type AdapterSession = {
     /**
      * The adapter's resolved model/effort for this run. Read by
@@ -351,6 +421,12 @@ type AdapterSession = {
      * that do not report configuration.
      */
     runConfiguration?: AgentTaskRunConfiguration;
+    /**
+     * The harness session transcript this run captured. Set as soon as the
+     * path is known (typically after the first `sendUserTurn`); the runner
+     * reads it once, after the turn loop. See {@link AdapterTranscriptCapture}.
+     */
+    transcript?: AdapterTranscriptCapture;
     sendUserTurn: (turn: unknown, context: {
         trace: AgentTaskTraceContext;
         turnNumber: number;
@@ -622,13 +698,16 @@ type EvaluationItemResult = {
     /** Name of the deliverable this check was evaluated against. */
     deliverable?: string;
     /**
-     * What kind of evaluator produced this result.
-     * Registered checks use ``"code"``. LLM-backed assertions inside a check
-     * carry ``evaluator_type: "llm"`` in {@link assertions}.
+     * What kind of evaluator produced this result, derived from the recorded
+     * assertions: ``"code"`` for purely deterministic checks, ``"llm"`` when
+     * every assertion judged, ``"agent"`` for pure agentic sessions,
+     * ``"mixed"`` when a check combines judged and deterministic assertions.
+     * LLM-backed assertions also carry ``evaluator_type: "llm"`` in
+     * {@link assertions}.
      * - ``"regex"`` — pattern matching
      * Older persisted results may still use ``"llm"`` at this level.
      */
-    evaluator_type?: "llm" | "code" | "agent" | "regex";
+    evaluator_type?: "llm" | "code" | "agent" | "regex" | "mixed";
     /**
      * If this check was judged by an LLM, details about the judge call
      * (model, prompt, response, tokens, cost, latency). Populated by the
@@ -1325,6 +1404,16 @@ declare function loadTask(taskDir: string): Promise<LoadedTask>;
 
 declare function defineAdapter<const TName extends string, const TDeliverables extends Record<string, DeliverableDefinition>, TCollected extends CollectedDeliverables>(adapter: TypedAdapterDefinition<TName, TDeliverables, TCollected>): TypedAdapterDefinition<TName, TDeliverables, TCollected>;
 
+/**
+ * Env-only auth headers for apo backends: the runner's credential contract
+ * (`APO_PUBLIC_KEY`+`APO_SECRET_KEY` → Basic, `APO_AUTH_TOKEN` → Bearer)
+ * resolved with no arguments. Same name as the otel entry's builder, but
+ * that one accepts explicit keys and returns `{}` when unauthenticated —
+ * this variant reports "no headers" as `undefined` instead. Both share one
+ * implementation in `apo-auth.ts`.
+ */
+declare function buildApoAuthHeaders(): Record<string, string> | undefined;
+
 /**
  * file Artifact declaration helper.
  *
@@ -1756,7 +1845,16 @@ type AgentTaskRunSummary = {
     runConfiguration?: AgentTaskRunConfiguration;
 };
 declare function loadTaskRuntime(_taskDir: string): Promise<AgentTaskRuntime>;
-declare function runTaskDir(taskDir: string): Promise<AgentTaskRunSummary>;
+type RunTaskDirOptions = {
+    /**
+     * Receives a handle that ends the active run's root span as cancelled and
+     * flushes it. Callers that can be terminated by a signal (the CLI task
+     * child, `apo task run`) register it so the run's trace and linkage survive
+     * their own death instead of dying with the process.
+     */
+    registerCancel?: (cancel: (reason?: string) => Promise<void>) => void;
+};
+declare function runTaskDir(taskDir: string, options?: RunTaskDirOptions): Promise<AgentTaskRunSummary>;
 
 type DeliverableValidationResult = {
     results: EvaluationItemResult[];
@@ -1997,61 +2095,6 @@ declare function canonicalManifestJson(manifest: TaskRevisionManifestV1): string
 /** SHA-256 (lowercase hex) of the canonical manifest JSON's UTF-8 bytes. */
 declare function contentSha256(manifest: TaskRevisionManifestV1): string;
 
-/**
- * Normalized transcript model — the common shape every harness transcript
- * parser produces, and the input to the OTLP translator.
- *
- * The model is deliberately lossy-but-sufficient for trace reconstruction:
- * per turn it keeps the user/assistant text, thinking, tool calls with their
- * results, model identity, and token usage. Anything the projection cannot
- * use (streaming chunk boundaries, harness housekeeping) is folded away.
- */
-type TranscriptSource = "claude-code" | "codex";
-type TranscriptUsage = {
-    inputTokens?: number;
-    outputTokens?: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-    reasoningTokens?: number;
-};
-type TranscriptToolCall = {
-    callId: string;
-    name: string;
-    /** Arguments exactly as recorded — parsed object when the harness allows, raw string otherwise. */
-    input: unknown;
-    /** Rendered result text or the raw output payload; absent when the transcript never recorded one. */
-    result?: unknown;
-    /** ISO timestamp of the call, when the transcript carries one. */
-    startedAt?: string;
-    /** ISO timestamp of the matching result, when the transcript carries one. */
-    endedAt?: string;
-};
-type TranscriptTurn = {
-    /** Zero-based position of the turn within the session. */
-    index: number;
-    /** ISO timestamp of the user message that opened the turn. */
-    startedAt: string;
-    /** ISO timestamp of the last observed event in the turn, when known. */
-    endedAt?: string;
-    model?: string;
-    userMessage?: string;
-    assistantMessage?: string;
-    /** Extended-thinking text (Claude) or reasoning summaries (Codex). */
-    thinkingText?: string;
-    /** Codex commentary-phase messages (progress narration, not reasoning). */
-    commentary?: string[];
-    toolCalls: TranscriptToolCall[];
-    usage?: TranscriptUsage;
-};
-type ParsedTranscriptSession = {
-    source: TranscriptSource;
-    sessionId: string;
-    cwd?: string;
-    turns: TranscriptTurn[];
-    /** Non-fatal parse issues: torn lines, unterminated turns, unmatched outputs. */
-    warnings: string[];
-};
-
 /**
  * Claude Code session-transcript parser.
  *
@@ -2086,7 +2129,7 @@ declare function parseClaudeCodeTranscript(content: string): ParsedTranscriptSes
  *   ``commentary``), ``token_count`` (``info.last_token_usage``).
  * - ``response_item`` payloads: ``function_call`` / ``custom_tool_call`` and
  *   their ``*_output`` counterparts (paired by ``call_id``), ``reasoning``
- *   (summary text), ``web_search_call``.
+ *   (summary parts), ``web_search_call``.
  *
  * A turn is bracketed by ``task_started`` … ``task_complete``. A rollout that
  * ends mid-turn (harness killed, crash) still yields its turn — the activity
@@ -2095,6 +2138,21 @@ declare function parseClaudeCodeTranscript(content: string): ParsedTranscriptSes
 
 declare function parseCodexTranscript(content: string): ParsedTranscriptSession;
 
+/**
+ * Transcript source detection.
+ *
+ * Guesses which harness wrote a JSONL transcript from its leading lines —
+ * blank, torn, or non-object lines are scanned past until one is decisive —
+ * so `apo traces import <file>` needs no `--source` in the common case:
+ *
+ * - Codex rollouts are uniformly ``{ type: session_meta|turn_context|
+ *   event_msg|response_item, timestamp, payload }``.
+ * - Claude Code transcripts are ``{ type: "user"|"assistant", message, … }``
+ *   with the session's identity fields (``sessionId``/``cwd``) on the lines.
+ */
+
+declare function detectTranscriptSource(content: string): TranscriptSource | undefined;
+
 /**
  * Transcript → OTLP/JSON translator.
  *
@@ -2175,8 +2233,11 @@ declare function transcriptSessionToOtlp(session: ParsedTranscriptSession, optio
  * - Attempt/service token (adapter capture): the replayed spans join the live
  *   task run's trace — the runner's root span already carries the claim.
  *
- * 5xx and network failures are retried; a 4xx is a caller bug (bad token,
- * malformed payload) and fails fast with the response body excerpt.
+ * 5xx, 429, and network failures are retried — apo's admission controller
+ * 429s OTLP ingest under per-key concurrency pressure, which the runner's own
+ * simple-processor exports can create while a replay POST is in flight. Any
+ * other 4xx is a caller bug (bad token, malformed payload) and fails fast
+ * with the response body excerpt.
  */
 
 declare class TranscriptReplayError extends Error {
@@ -2186,8 +2247,10 @@ declare class TranscriptReplayError extends Error {
 type ExportOtlpTracesOptions = {
     /** apo base URL (e.g. http://localhost:8000); a full …/v1/traces URL is accepted verbatim. */
     endpoint: string;
-    /** API key or attempt token — sent as the OTLP Authorization bearer. */
-    token: string;
+    /** Attempt/service token — sent as the OTLP Authorization bearer. */
+    token?: string;
+    /** Complete headers override (e.g. buildApoAuthHeaders() for Basic API-key auth). */
+    headers?: Record<string, string>;
     /** Per-request timeout. Default 30s. */
     timeoutMs?: number;
     /** Extra attempts after the first on 5xx/network failure. Default 2. */
@@ -2197,4 +2260,53 @@ type ExportOtlpTracesOptions = {
 declare function resolveOtlpTracesUrl(base: string): string;
 declare function exportOtlpTraces(payload: OtlpTracesPayload, options: ExportOtlpTracesOptions): Promise<void>;
 
-export { type AISDKResult, type AdapterDefinition, type AdapterRuntimeState, type AdapterSession, type AgentBudget, type AgentEvidence, type AgentJudgeOptions, type AgentJudgeOutcome, type AgentJudgeSession, type AgentJudgeStep, type AgentTaskCliOptions, type AgentTaskRunConfiguration, AgentTaskRunError, type AgentTaskRunSummary, type AgentTaskRuntime, AgentTaskTraceContext, AgentTaskTraceOptions, type AgentTurnResult, type AnthropicMessage, type ApoRunContext, ApoSpanProcessor, type ArtifactUploadConfig, type CheckCompaction, type CheckContext, type CheckGroup, type CleanupContext, type CollectDeliverablesContext, type CollectedDeliverables, type DeliverableDefinition, type DeliverableSummary, type DeliverableValidationResult, type DescribeRegistration, type DurationBudgetOptions, type EvidenceFingerprint, type ExportOtlpTracesOptions, type FileArtifact, type FileArtifactOptions, type FileEntry, type Flow, type FlowEvent, FlowView, type InitializeContext, JUDGE_SEGMENT_LIMIT, type JudgeConfig, type JudgeContext, type JudgePromptBuilder, type JudgeScope, type JudgeToolsConfig, type LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type McpHttpTransport, type McpServerConfig, type McpStdioTransport, type ModeClass, type NameMatcher, type OpenAIMessage, type OtlpAttribute, type OtlpAttributeValue, type OtlpSpan, type OtlpTracesPayload, type ParsedTranscriptSession, type PreparedTaskResult, RECEIVED_VALUE_LIMIT, type RegisterApoTracingOptions, type RejudgeCheckStability, type RejudgeEndpoints, RejudgeError, type RejudgeOptions, type RejudgeOutcome, type RunTaskOptions, type StartSessionContext, TEST_METHOD_NAMES, type TaskConfig, type TaskDefinition, type TaskEvaluationResult, TaskFiles, type TaskRevisionManifestV1, type TaskRunResult, type TaskScope, type TaskTranscript, type TaskTranscriptTurn, type TestContext, type TestRegistration, type TokenBudgetOptions, type ToolCallOptions, type ToolCallStatus, TranscriptReplayError, type TranscriptReplayOptions, type TranscriptSource, type TranscriptToolCall, type TranscriptTurn, type TranscriptUsage, type TurnContext, type TurnFn, type TurnRecord, type TypedAdapterDefinition, type ValueMatcher, buildManifest, canonicalManifestJson, compactChecksForSubmission, connectMcpServers, contentSha256, defineAdapter, defineTask, describe, discoverAgentTaskDirs, equals, expandSecretPlaceholders, exportOtlpTraces, fileArtifact, filePaths, fromAISDK, fromAnthropicMessages, fromOpenAIMessages, getActiveApoRun, getTaskTurn, includes, isFileArtifact, loadTask, loadTaskRuntime, matchValue, matches, normalizeManifestPath, parseAgentTaskCliArgs, parseClaudeCodeTranscript, parseCodexTranscript, persistFileArtifacts, registerApoTracing, rejudgeTaskRun, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskTurn, resolveMcpServerPaths, resolveOtlpTracesUrl, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, sha256Hex, similarity, task, defineCheck as test, transcriptSessionToOtlp, turn, withApoRun, withApoRunSync };
+/**
+ * Adapter capture mode — replay a harness session transcript into a live
+ * Task Run.
+ *
+ * The adapter contract this serves: a harness that cannot emit OTel (Codex
+ * CLI, plain Claude Code, anything that only writes a session JSONL) declares
+ * its transcript on the session (`AdapterSession.transcript`), and the runner
+ * calls {@link replayAdapterTranscript} after the turn loop. One call does
+ * two things with the same parse:
+ *
+ * 1. **Local:** converts the translated spans into projection observations and
+ *    returns them, so the runner can inject them into the local snapshot —
+ *    `t.calledTool` / budget assertions work even on offline, unrecorded runs.
+ * 2. **Remote:** when the run has a live trace id and backend credentials, the
+ *    OTLP payload joins the run's trace (same traceId, interactions parented
+ *    under the run root) and the backend projects it exactly like native OTel
+ *    spans — the read-back snapshot the recorded path evaluates against is
+ *    indistinguishable from an instrumented run.
+ *
+ * Failure semantics are strict on purpose: the adapter *declared* a
+ * transcript, so a missing file or a failed export on a recorded run fails
+ * the run loudly — otherwise checks would starve on a projection that
+ * silently lacks the agent's activity.
+ */
+
+type ReplayAdapterTranscriptOptions = {
+    /** The live run's root span id — replayed interactions nest under it. */
+    rootSpanId: string;
+    /**
+     * The live trace id. Present only when the run has a real trace (a noop
+     * trace context yields sentinel ids); when absent the replay stays local.
+     */
+    liveTraceId?: string;
+    /** apo base URL (AGENT_TASK_TRACE_ENDPOINT). Required for remote export. */
+    endpoint?: string;
+};
+type TranscriptCaptureResult = {
+    /** Projection observations for the replayed spans (already snapshot-sorted). */
+    observations: TraceProjectionObservation[];
+    /** Total OTLP spans the translation produced (observations + resource meta). */
+    spanCount: number;
+    /** Whether the payload was exported to the backend. */
+    exported: boolean;
+    /** Parser warnings (torn lines, unterminated turns). */
+    warnings: string[];
+    turns: number;
+};
+declare function replayAdapterTranscript(capture: AdapterTranscriptCapture, options: ReplayAdapterTranscriptOptions): Promise<TranscriptCaptureResult>;
+
+export { type AISDKResult, type AdapterDefinition, type AdapterRuntimeState, type AdapterSession, type AdapterTranscriptCapture, type AgentBudget, type AgentEvidence, type AgentJudgeOptions, type AgentJudgeOutcome, type AgentJudgeSession, type AgentJudgeStep, type AgentTaskCliOptions, type AgentTaskRunConfiguration, AgentTaskRunError, type AgentTaskRunSummary, type AgentTaskRuntime, AgentTaskTraceContext, AgentTaskTraceOptions, type AgentTurnResult, type AnthropicMessage, type ApoRunContext, ApoSpanProcessor, type ArtifactUploadConfig, type CheckCompaction, type CheckContext, type CheckGroup, type CleanupContext, type CollectDeliverablesContext, type CollectedDeliverables, type DeliverableDefinition, type DeliverableSummary, type DeliverableValidationResult, type DescribeRegistration, type DurationBudgetOptions, type EvidenceFingerprint, type ExportOtlpTracesOptions, type FileArtifact, type FileArtifactOptions, type FileEntry, type Flow, type FlowEvent, FlowView, type InitializeContext, JUDGE_SEGMENT_LIMIT, type JudgeConfig, type JudgeContext, type JudgePromptBuilder, type JudgeScope, type JudgeToolsConfig, type LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type McpHttpTransport, type McpServerConfig, type McpStdioTransport, type ModeClass, type NameMatcher, type OpenAIMessage, type OtlpAttribute, type OtlpAttributeValue, type OtlpSpan, type OtlpTracesPayload, type ParsedTranscriptSession, type PreparedTaskResult, RECEIVED_VALUE_LIMIT, type RegisterApoTracingOptions, type RejudgeCheckStability, type RejudgeEndpoints, RejudgeError, type RejudgeOptions, type RejudgeOutcome, type ReplayAdapterTranscriptOptions, type RunTaskOptions, type StartSessionContext, TEST_METHOD_NAMES, type TaskConfig, type TaskDefinition, type TaskEvaluationResult, TaskFiles, type TaskRevisionManifestV1, type TaskRunResult, type TaskScope, type TaskTranscript, type TaskTranscriptTurn, type TestContext, type TestRegistration, type TokenBudgetOptions, type ToolCallOptions, type ToolCallStatus, type TranscriptCaptureResult, TranscriptReplayError, type TranscriptReplayOptions, type TranscriptSource, type TranscriptToolCall, type TranscriptTurn, type TranscriptUsage, type TurnContext, type TurnFn, type TurnRecord, type TypedAdapterDefinition, type ValueMatcher, buildApoAuthHeaders, buildManifest, canonicalManifestJson, compactChecksForSubmission, connectMcpServers, contentSha256, defineAdapter, defineTask, describe, detectTranscriptSource, discoverAgentTaskDirs, equals, expandSecretPlaceholders, exportOtlpTraces, fileArtifact, filePaths, fromAISDK, fromAnthropicMessages, fromOpenAIMessages, getActiveApoRun, getTaskTurn, includes, isFileArtifact, loadTask, loadTaskRuntime, matchValue, matches, normalizeManifestPath, parseAgentTaskCliArgs, parseClaudeCodeTranscript, parseCodexTranscript, persistFileArtifacts, registerApoTracing, rejudgeTaskRun, replayAdapterTranscript, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskTurn, resolveMcpServerPaths, resolveOtlpTracesUrl, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, sha256Hex, similarity, task, defineCheck as test, transcriptSessionToOtlp, turn, withApoRun, withApoRunSync };