@vauban-org/agent-sdk 1.2.0 → 1.3.0

package/CONTRACT.md

@@ -1,6 +1,6 @@
 # @vauban-org/agent-sdk — Public API Contract
 
-**Version:** 0.8.2 | **Status:** public-experimental | **Generated:** 2026-05-15
+**Version:** 0.8.2 | **Status:** public-experimental | **Generated:** 2026-05-16
 
 > Vauban agent primitives: loop, budget, routing, HITL, permissions, tracking, durable execution
 
@@ -477,6 +477,15 @@ export interface AgentResult {
     stopReason: "complete" | "budget_exhausted" | "error" | string;
 }
 
+// Warning: (ae-missing-release-tag) "AgentRunFinalStatus" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `AgentRunFinalStatus`
+
+```typescript
+export type AgentRunFinalStatus = "success" | "failed" | "timeout" | "incoherent";
+
 // Warning: (ae-missing-release-tag) "AgentRunFinish" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 ```
@@ -486,8 +495,6 @@ export interface AgentResult {
 ```typescript
 export interface AgentRunFinish {
     errorMessage?: string;
-    // Warning: (ae-forgotten-export) The symbol "AgentRunFinalStatus" needs to be exported by the entry point index.d.ts
-    //
     status: AgentRunFinalStatus;
     stopReason?: string;
 }
@@ -1181,6 +1188,18 @@ export interface BestOfNRewardModel<TOutput> {
 
 ```typescript
 export function bestOfNStrategy<TInput, TOutput>(opts: BestOfNOptions<TInput, TOutput>): Strategy<TInput, TOutput>;
+```
+
+### `BinaryExecutionOptions`
+
+```typescript
+export interface BinaryExecutionOptions {
+    cwd?: string;
+    executionId?: string;
+    extraEnv?: Record<string, string>;
+    mode?: string;
+    timeoutSeconds?: number;
+}
 
 // Warning: (ae-missing-release-tag) "BonMavOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -1540,6 +1559,19 @@ export interface BuildOrientPromptOpts {
 
 ```typescript
 export function buildPersonaPromptBlock(persona: AgentPersona): string;
+```
+
+### `buildProtocolEnv`
+
+```typescript
+export function buildProtocolEnv(args: {
+    executionId: string;
+    automationName: string;
+    input: unknown;
+    timeoutSeconds: number;
+    mode?: string;
+    extraEnv?: Readonly<Record<string, string>>;
+}): Record<string, string>;
 
 // Warning: (ae-missing-release-tag) "buildSkillRegistry" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -1765,6 +1797,12 @@ export interface BusinessHoursOptions {
     windowEnd: string;
     windowStart: string;
 }
+```
+
+### `calculateDelay`
+
+```typescript
+export function calculateDelay(config: RetryConfig, attempt: number): number;
 
 // Warning: (ae-forgotten-export) The symbol "CalendarCheckInput" needs to be exported by the entry point index.d.ts
 // Warning: (ae-missing-release-tag) "calendarCheck" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -2691,6 +2729,52 @@ export interface ConsoleChannelConfig {
 
 ```typescript
 export type ConsumerMode = "strict" | "permissive" | "audit_only";
+```
+
+### `ContainerExecutionOptions`
+
+```typescript
+export interface ContainerExecutionOptions {
+    cpuQuota?: number;
+    executionId?: string;
+    extraEnv?: Record<string, string>;
+    memoryMb?: number;
+    mode?: string;
+    networkMode?: "none" | "outbound" | "bridge";
+    readOnlyRoot?: boolean;
+    timeoutSeconds?: number;
+}
+```
+
+### `ContainerRuntime`
+
+```typescript
+export class ContainerRuntime {
+    constructor(opts?: ContainerRuntimeOptions);
+    executeBinary<T = unknown>(command: string[], automationName: string, input: unknown, options?: BinaryExecutionOptions): Promise<ExecutionResult<T>>;
+    executeContainer<T = unknown>(image: string, automationName: string, input: unknown, options?: ContainerExecutionOptions): Promise<ExecutionResult<T>>;
+}
+```
+
+### `ContainerRuntimeOptions`
+
+```typescript
+export interface ContainerRuntimeOptions {
+    defaultTimeoutSeconds?: number;
+    sandbox?: SandboxExecutor;
+    spawnFn?: ContainerSpawnFn;
+}
+```
+
+### `ContainerSpawnFn`
+
+```typescript
+export type ContainerSpawnFn = (cmd: string, args: string[], opts: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    stdio: ["pipe", "pipe", "pipe"];
+    signal?: AbortSignal;
+}) => ChildProcess;
 
 // Warning: (ae-missing-release-tag) "ContentClaim" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -2957,6 +3041,40 @@ export function createRunsClient(opts: RunsClientOptions): RunsClient;
 
 ```typescript
 export function createSimpleAgent<TContext, TOrient, TFeedback>(deps: AgentFactoryDeps, opts: SimpleAgentOptions<TContext, TOrient, TFeedback>): Promise<OODAAgent>;
+```
+
+### `createSkillContext`
+
+```typescript
+export function createSkillContext(opts: CreateSkillContextOptions): SkillContext;
+```
+
+### `CreateSkillContextOptions`
+
+```typescript
+export interface CreateSkillContextOptions {
+    db: DbClient;
+    dryRunMocks?: Record<string, (input: unknown) => unknown>;
+    executionId?: string;
+    isReplay?: boolean;
+    logger: LoggerPort;
+    progress?: ProgressCallback;
+    secrets?: SecretsAccessor;
+    startedAt?: Date;
+    timeoutSeconds?: number;
+}
+
+// Warning: (ae-missing-release-tag) "createTelemetryBus" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `createTelemetryBus`
+
+```typescript
+export function createTelemetryBus(opts: TelemetryBusOptions): TelemetrySink & {
+    counters: TelemetryCounters;
+    flush(): Promise<void>;
+};
 
 // Warning: (ae-missing-release-tag) "cronSessionGuard" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -3583,6 +3701,12 @@ export const DEFAULT_PERSONA: AgentPersona;
 
 ```typescript
 export const DEFAULT_POLICIES: Record<string, AxiomPolicy>;
+```
+
+### `DEFAULT_PROTOCOL_MODE`
+
+```typescript
+export const DEFAULT_PROTOCOL_MODE = "execute";
 
 // Warning: (ae-missing-release-tag) "DEFAULT_RECENCY_HALFLIFE_MS" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -4408,20 +4532,20 @@ export const EventSchemas: {
         schemaVersion: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         type: "INTERESTED" | "NOT_INTERESTED" | "BOUNCE" | "SPAM" | "OTHER";
+        signal: string;
         priority: "HIGH" | "MEDIUM" | "LOW";
         timestamp: string;
         schemaVersion: string;
-        signal: string;
         from: string;
         subject: string;
         uid: string;
         nextAction: string;
     }, {
         type: "INTERESTED" | "NOT_INTERESTED" | "BOUNCE" | "SPAM" | "OTHER";
+        signal: string;
         priority: "HIGH" | "MEDIUM" | "LOW";
         timestamp: string;
         schemaVersion: string;
-        signal: string;
         from: string;
         subject: string;
         uid: string;
@@ -4432,11 +4556,11 @@ export const EventSchemas: {
         score: z.ZodNumber;
         source: z.ZodEnum<["inbound", "outbound", "referral"]>;
     }, "strict", z.ZodTypeAny, {
-        source: "inbound" | "outbound" | "referral";
+        source: "outbound" | "inbound" | "referral";
         score: number;
         leadId: string;
     }, {
-        source: "inbound" | "outbound" | "referral";
+        source: "outbound" | "inbound" | "referral";
         score: number;
         leadId: string;
     }>;
@@ -4959,6 +5083,31 @@ export function executeStep(step: PlanStep, executor: (step: PlanStep) => Promis
 
 ```typescript
 export type ExecutionMode = "dry-run" | "live";
+```
+
+### `ExecutionResult`
+
+```typescript
+export interface ExecutionResult<T = unknown> {
+    readonly automationName: string;
+    readonly completedAt: Date;
+    readonly durationMs: number;
+    readonly error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    readonly executionId: string;
+    readonly input: unknown;
+    readonly logs: ReadonlyArray<{
+        readonly level: string;
+        readonly message: string;
+        readonly timestamp: string;
+    }>;
+    readonly output?: T;
+    readonly startedAt: Date;
+    readonly status: "completed" | "failed" | "timeout";
+}
 
 // Warning: (ae-missing-release-tag) "ExhaustResourcesOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -5970,6 +6119,17 @@ export class InMemoryReceiptQueue implements ReceiptQueue {
     }>;
     size(): Promise<number>;
 }
+```
+
+### `InMemorySecretsAccessor`
+
+```typescript
+export class InMemorySecretsAccessor implements SecretsAccessor {
+    constructor(secrets?: Readonly<Record<string, string>>);
+    get accessedSecrets(): ReadonlySet<string>;
+    get(name: string, defaultValue?: string): string;
+    has(name: string): boolean;
+}
 
 // Warning: (ae-missing-release-tag) "innerMonologue" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -6528,6 +6688,27 @@ export interface LoadRecentMemoryOptions {
 ```typescript
 export function loadSkillMd(filePath: string): Promise<ParsedSkillFile>;
 
+// Warning: (ae-missing-release-tag) "localSqliteTelemetrySink" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `localSqliteTelemetrySink`
+
+```typescript
+export function localSqliteTelemetrySink(opts?: LocalSqliteTelemetrySinkOptions): TelemetrySink;
+
+// Warning: (ae-missing-release-tag) "LocalSqliteTelemetrySinkOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `LocalSqliteTelemetrySinkOptions`
+
+```typescript
+export interface LocalSqliteTelemetrySinkOptions {
+    path?: string;
+    readonly?: boolean;
+}
+
 // Warning: (ae-missing-release-tag) "LoggerFlushError" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 ```
@@ -7153,6 +7334,12 @@ export interface MultiModalObservation {
 export function multiModalToAnthropicContent(obs: MultiModalObservation): AnthropicContentBlock[];
 ```
 
+### `NO_RETRY`
+
+```typescript
+export const NO_RETRY: RetryConfig;
+```
+
 ### `NonceStore`
 
 ```typescript
@@ -7184,6 +7371,21 @@ export class NonSerializablePayloadError extends Error {
     constructor(reason: string, path: string[]);
     readonly path: string[];
 }
+```
+
+### `NOOP_SECRETS`
+
+```typescript
+export const NOOP_SECRETS: SecretsAccessor;
+
+// Warning: (ae-missing-release-tag) "NOOP_TELEMETRY_SINK" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `NOOP_TELEMETRY_SINK`
+
+```typescript
+export const NOOP_TELEMETRY_SINK: TelemetrySink;
 
 // Warning: (ae-missing-release-tag) "noopLogger" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -7349,6 +7551,7 @@ export interface OODAAgentConfig<TConfig = unknown, TObs = unknown, TOrient = un
     readonly riskGuards?: readonly RiskGuard[];
     readonly sessionGuards?: readonly SessionGuard[];
     readonly skills?: SkillRegistry;
+    readonly telemetry?: TelemetrySink;
     readonly timestamping?: {
         readonly port: TimestampPort;
         readonly queue?: ReceiptQueue;
@@ -7558,6 +7761,30 @@ export interface OtlpSpan {
     traceId: string;
 }
 
+// Warning: (ae-missing-release-tag) "otlpTelemetrySink" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `otlpTelemetrySink`
+
+```typescript
+export function otlpTelemetrySink(opts: OtlpTelemetrySinkOptions): TelemetrySink;
+
+// Warning: (ae-missing-release-tag) "OtlpTelemetrySinkOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `OtlpTelemetrySinkOptions`
+
+```typescript
+export interface OtlpTelemetrySinkOptions {
+    fetchImpl?: typeof fetch;
+    headers?: Record<string, string>;
+    serviceName?: string;
+    timeoutMs?: number;
+    url: string;
+}
+
 // Warning: (ae-missing-release-tag) "Outcome" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 ```
@@ -7837,6 +8064,12 @@ export interface ParsedSkillFile {
     manifest: SkillManifest;
     tier: VaubanSkillTier;
 }
+```
+
+### `parseProtocolOutput`
+
+```typescript
+export function parseProtocolOutput<T = unknown>(stdout: string): ProtocolResult<T>;
 
 // Warning: (ae-missing-release-tag) "parseSkillMd" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -7846,6 +8079,16 @@ export interface ParsedSkillFile {
 
 ```typescript
 export function parseSkillMd(raw: string, source?: string): ParsedSkillFile;
+```
+
+### `parseStderrLogs`
+
+```typescript
+export function parseStderrLogs(stderr: string): Array<{
+    level: string;
+    message: string;
+    timestamp: string;
+}>;
 
 // Warning: (ae-missing-release-tag) "parseStructuredOutput" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -8442,6 +8685,12 @@ export const PROFITABLE: Axiom;
 
 ```typescript
 export const profitableScorer: ScoringFunction;
+```
+
+### `ProgressCallback`
+
+```typescript
+export type ProgressCallback = (value: number, message?: string) => void;
 
 // Warning: (ae-missing-release-tag) "ProofChain" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -8476,6 +8725,49 @@ export interface ProofChainEntry {
 
 ```typescript
 export type ProofGrade = "attestation" | "attestation_custody_compatible" | "custody";
+```
+
+### `PROTOCOL_ENV`
+
+```typescript
+export const PROTOCOL_ENV: {
+    readonly EXECUTION_ID: "VAUBAN_EXECUTION_ID";
+    readonly AUTOMATION_NAME: "VAUBAN_AUTOMATION_NAME";
+    readonly INPUT: "VAUBAN_INPUT";
+    readonly TIMEOUT: "VAUBAN_TIMEOUT";
+    readonly MODE: "VAUBAN_MODE";
+};
+```
+
+### `ProtocolParseError`
+
+```typescript
+export class ProtocolParseError extends Error {
+    constructor(reason: string, rawTail: string);
+    readonly rawTail: string;
+}
+```
+
+### `ProtocolResult`
+
+```typescript
+export type ProtocolResult<T = unknown> = {
+    readonly status: "completed";
+    readonly output: T;
+} | {
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details?: unknown;
+    };
+};
+```
+
+### `ProtocolStatus`
+
+```typescript
+export type ProtocolStatus = "completed" | "failed";
 
 // Warning: (ae-missing-release-tag) "ProviderRouter" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -9337,6 +9629,77 @@ export interface ResumeWorkflowOpts {
     readonly leaseTtlSeconds?: number;
     readonly workerId: string;
 }
+```
+
+### `retry`
+
+```typescript
+export function retry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+```
+
+### `RETRY_AGGRESSIVE`
+
+```typescript
+export const RETRY_AGGRESSIVE: RetryConfig;
+```
+
+### `RETRY_PATIENT`
+
+```typescript
+export const RETRY_PATIENT: RetryConfig;
+```
+
+### `RETRY_TRANSIENT`
+
+```typescript
+export const RETRY_TRANSIENT: RetryConfig;
+```
+
+### `RetryConfig`
+
+```typescript
+export interface RetryConfig {
+    readonly baseDelayMs: number;
+    readonly exponentialBase: number;
+    readonly jitter: boolean;
+    readonly maxAttempts: number;
+    readonly maxDelayMs: number;
+    readonly retryIf?: (err: unknown) => boolean;
+    readonly retryOn?: ReadonlyArray<new (...args: never[]) => Error>;
+}
+```
+
+### `RetryContext`
+
+```typescript
+export class RetryContext {
+    constructor(opts: RetryOptions & {
+        config: RetryConfig;
+    });
+    get attempt(): number;
+    handleError(err: unknown): Promise<void>;
+    get shouldContinue(): boolean;
+}
+```
+
+### `RetryExhaustedError`
+
+```typescript
+export class RetryExhaustedError extends Error {
+    constructor(attempts: number, lastError: unknown);
+    readonly attempts: number;
+    readonly lastError: unknown;
+}
+```
+
+### `RetryOptions`
+
+```typescript
+export interface RetryOptions {
+    config?: RetryConfig;
+    onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+    sleepFn?: SleepFn;
+}
 
 // Warning: (ae-missing-release-tag) "RiskGuard" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -9638,6 +10001,43 @@ export type RunStreamEventName = "step_existing" | "step_new" | "run_complete" |
 
 ```typescript
 export function runTwoPhaseOrient<C, O, R>(config: TwoPhaseOrientConfig<C, O, R>, context: C): Promise<TwoPhaseOrientResult<O, R>>;
+```
+
+### `SandboxExecutor`
+
+```typescript
+export interface SandboxExecutor {
+    run(job: SandboxJob): Promise<SandboxResult>;
+}
+```
+
+### `SandboxJob`
+
+```typescript
+export interface SandboxJob {
+    command: string[];
+    cpuQuota?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+    image: string;
+    memoryMb?: number;
+    networkMode?: "none" | "outbound" | "bridge";
+    readOnlyRoot?: boolean;
+    stdin?: string;
+    timeoutMs: number;
+}
+```
+
+### `SandboxResult`
+
+```typescript
+export interface SandboxResult {
+    durationMs: number;
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+    timedOut: boolean;
+}
 
 // Warning: (ae-missing-release-tag) "SanitizedItem" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -9896,6 +10296,25 @@ export interface SealedSprintClaim {
 
 ```typescript
 export const SECRET_PATTERN: RegExp;
+```
+
+### `SecretNotFoundError`
+
+```typescript
+export class SecretNotFoundError extends Error {
+    constructor(secretName: string);
+    readonly secretName: string;
+}
+```
+
+### `SecretsAccessor`
+
+```typescript
+export interface SecretsAccessor {
+    readonly accessedSecrets: ReadonlySet<string>;
+    get(name: string, defaultValue?: string): string;
+    has(name: string): boolean;
+}
 
 // Warning: (ae-forgotten-export) The symbol "SendEmailInput" needs to be exported by the entry point index.d.ts
 // Warning: (ae-missing-release-tag) "sendEmail" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -10033,6 +10452,12 @@ export function sha256(input: string | Uint8Array): Promise<string>;
 
 ```typescript
 export function shouldLearn(trigger: LearningTrigger): boolean;
+```
+
+### `shouldRetry`
+
+```typescript
+export function shouldRetry(config: RetryConfig, err: unknown, attempt: number): boolean;
 
 // Warning: (ae-missing-release-tag) "SignalBrainPort" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -10132,8 +10557,13 @@ export interface SkillBuilderDeps {
 export interface SkillContext {
     readonly db: DbClient;
     readonly dryRunMocks: Record<string, (input: unknown) => unknown>;
+    readonly elapsedSeconds?: number;
+    readonly executionId?: string;
     readonly isReplay: boolean;
     readonly logger: LoggerPort;
+    readonly progress?: ProgressCallback;
+    readonly remainingSeconds?: number;
+    readonly secrets?: SecretsAccessor;
 }
 
 // Warning: (ae-missing-release-tag) "SkillExecutionError" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -10710,6 +11140,12 @@ export interface SlackTriggerContext {
     channelId: string;
     userId: string;
 }
+```
+
+### `SleepFn`
+
+```typescript
+export type SleepFn = (ms: number) => Promise<void>;
 
 // Warning: (ae-missing-release-tag) "SolvencyClaim" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -10825,6 +11261,27 @@ export interface StartWorkflowOpts {
     readonly workflowVersion: string;
 }
 
+// Warning: (ae-missing-release-tag) "stdoutTelemetrySink" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `stdoutTelemetrySink`
+
+```typescript
+export function stdoutTelemetrySink(opts?: StdoutTelemetrySinkOptions): TelemetrySink;
+
+// Warning: (ae-missing-release-tag) "StdoutTelemetrySinkOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `StdoutTelemetrySinkOptions`
+
+```typescript
+export interface StdoutTelemetrySinkOptions {
+    json?: boolean;
+    stream?: NodeJS.WritableStream;
+}
+
 // Warning: (ae-missing-release-tag) "StepCountExceededError" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 ```
@@ -11253,6 +11710,137 @@ export interface TelegramTriggerContext {
     };
 }
 
+// Warning: (ae-missing-release-tag) "TelemetryBusOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryBusOptions`
+
+```typescript
+export interface TelemetryBusOptions {
+    logger?: TelemetryLogger;
+    maxQueueDepth?: number;
+    nonBlocking?: boolean;
+    sinks: readonly TelemetrySink[];
+}
+
+// Warning: (ae-missing-release-tag) "TelemetryCounters" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryCounters`
+
+```typescript
+export interface TelemetryCounters {
+    readonly dispatched: number;
+    readonly dropped: number;
+    readonly sinkErrors: number;
+}
+
+// Warning: (ae-missing-release-tag) "TelemetryLogger" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryLogger`
+
+```typescript
+export interface TelemetryLogger {
+    error(obj: Record<string, unknown>, msg?: string): void;
+    warn(obj: Record<string, unknown>, msg?: string): void;
+}
+
+// Warning: (ae-missing-release-tag) "TelemetryRunFinish" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryRunFinish`
+
+```typescript
+export interface TelemetryRunFinish {
+    errorMessage?: string;
+    finishedAt: string;
+    status: TelemetryRunStatus;
+    stopReason?: string;
+    totalCostUsd?: number;
+    totalInputTokens?: number;
+    totalOutputTokens?: number;
+    totalToolCalls?: number;
+}
+
+// Warning: (ae-missing-release-tag) "TelemetryRunStart" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryRunStart`
+
+```typescript
+export interface TelemetryRunStart {
+    agentId: string;
+    agentVersion: string;
+    model: string;
+    provider: string;
+    runId: string;
+    startedAt: string;
+    tenantId?: string;
+    traceId?: string;
+}
+
+// Warning: (ae-missing-release-tag) "TelemetryRunStatus" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryRunStatus`
+
+```typescript
+export type TelemetryRunStatus = "success" | "failed" | "skipped" | "timeout" | "incoherent";
+
+// Warning: (ae-missing-release-tag) "TelemetryRunStep" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetryRunStep`
+
+```typescript
+export interface TelemetryRunStep {
+    costUsd: number;
+    durationMs?: number;
+    inputTokens: number;
+    kind: string;
+    metadata?: Record<string, unknown>;
+    outputTokens: number;
+    status: "completed" | "failed" | "skipped";
+    stepIndex: number;
+    toolCalls?: number;
+}
+
+// Warning: (ae-missing-release-tag) "TelemetrySink" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetrySink`
+
+```typescript
+export interface TelemetrySink {
+    finish(runId: string, event: TelemetryRunFinish): Promise<void>;
+    flush?(): Promise<void>;
+    readonly name: string;
+    start(event: TelemetryRunStart): Promise<string | void>;
+    step(runId: string, delta: TelemetryRunStep): Promise<void>;
+}
+
+// Warning: (ae-missing-release-tag) "TelemetrySinkError" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+```
+
+### `TelemetrySinkError`
+
+```typescript
+export class TelemetrySinkError extends Error {
+    constructor(message: string, sinkName: string, cause?: unknown | undefined);
+    readonly cause?: unknown | undefined;
+    readonly sinkName: string;
+}
+
 // Warning: (ae-missing-release-tag) "TenantContext" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 ```