@apo-ai/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sami Kuikka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# apo SDK
+
+TypeScript/JavaScript SDK for the [apo](.) backend — an agent testing and
+observability platform. The SDK has three entry points:
+
+- **`@apo-ai/sdk`** — config + error types shared across the surface.
+- **`@apo-ai/sdk/otel`** — OpenTelemetry-native tracing. Wrap your LLM calls and
+  agent steps so they land in apo as structured spans, then attach scores.
+- **`@apo-ai/sdk/agent-task`** — the agent-task evaluation framework. Define tasks,
+  adapters, and checks; run them against an agent and collect structured
+  results.
+
+## Installation
+
+```bash
+pnpm add @apo-ai/sdk
+# or: npm install @apo-ai/sdk / yarn add @apo-ai/sdk
+```
+
+Requires Node.js ≥ 20. The package ships compiled ESM + `.d.ts` (built via
+`tsup`), so no TypeScript-transpiling runtime and no `allowImportingTsExtensions`
+tsconfig flag are required on the consumer side.
+
+For TypeScript consumers, also install `@types/node` (the SDK's emitted
+declarations reference Node globals like `Buffer`):
+
+```bash
+pnpm add -D @types/node
+```
+
+## Releases
+
+See [RELEASING.md](./RELEASING.md) for the maintainer runbook. The package
+is published to npm via GitHub OIDC trusted publishing from `sdk-v*` tags —
+no long-lived npm token is stored in the repository.
+
+## Configuration
+
+`readConfig()` reads backend/project/credentials from environment variables.
+
+| Field       | Env var (server)            | Env var (Next.js, browser-safe)      | Required |
+|-------------|-----------------------------|--------------------------------------|----------|
+| `endpoint`  | `APO_BACKEND_URL`           | `NEXT_PUBLIC_APO_BACKEND_URL`        | yes      |
+| `project`   | `APO_PROJECT`               | `NEXT_PUBLIC_APO_PROJECT`            | yes      |
+| `publicKey` | `APO_PUBLIC_KEY`            | — *(server-side only — see below)*   | two-key  |
+| `secretKey` | `APO_SECRET_KEY`            | —                                    | two-key  |
+| `apiKey`    | `APO_API_KEY`               | —                                    | legacy   |
+
+The Next.js (`NEXT_PUBLIC_*`) variants are read first, then the plain server
+variants. `apiKey` is the legacy single-key format (`sk-…`); prefer the
+two-key model (`publicKey` + `secretKey`, generated as `pk-apo-…` / `sk-apo-…`
+in the dashboard).
+
+there is no browser-safe variant of `APO_PUBLIC_KEY`. The public
+identifier alone does not authorize ingestion, and exposing it in a
+browser bundle creates a misleading direct-browser integration.
+`NEXT_PUBLIC_APO_PUBLIC_KEY` is intentionally not read. Telemetry
+submission always requires both halves of an API-key pair sent as HTTP
+Basic (`base64("pk-apo-…:sk-apo-…")`); the SDK never synthesizes partial
+Basic credentials from only one half.
+
+```ts
+import { readConfig, type EnvConfig } from "@apo-ai/sdk";
+
+const config: EnvConfig = readConfig();
+```
+
+## API reference — `@apo-ai/sdk`
+
+The root entry is intentionally thin: shared types + config + errors. The
+actual tracing surface lives at `@apo-ai/sdk/otel`.
+
+### Types
+
+The trace/observation parameter types used by the OTel helpers:
+`CreateTraceParams`, `CreateSpanParams`, `EndSpanParams`, `TraceRunContext`,
+`TraceRunOptions`, `TraceStepOptions`, `TraceEventOptions`, `IngestionEvent`,
+`CreateScoreParams`, `ClientOptions`, `ParameterOverrides`, `ObserveOptions`,
+`ObservationContext`.
+
+### `readConfig(): EnvConfig`
+
+Read endpoint/project/keys from environment variables (table above).
+
+### Errors
+
+`ClientError` (Effect `Data.TaggedError`), `ConfigurationError`,
+`ClientErrorCode`. `ClientError` carries a `code` field for categorising
+failures.
+
+## Tracing — `@apo-ai/sdk/otel`
+
+The canonical tracing path is OpenTelemetry via `@apo-ai/sdk/otel`. The old
+`TraceTracker` / `createClient` custom protocol has been removed.
+
+```ts
+import {
+  configureApoTelemetry,
+  withApoTrace,
+  traceTool,
+  traceAgent,
+  traceRetriever,
+  score,
+  injectTraceparent,
+  extractTraceparent,
+} from "@apo-ai/sdk/otel";
+```
+
+### `configureApoTelemetry(options)`
+
+Sets up an OTel tracer provider with an OTLP exporter pointing at apo. Requires
+`takeOwnership: true` (explicit permission to own the OTel lifecycle — don't
+call this if your app already configures OTel itself).
+
+```ts
+const handle = await configureApoTelemetry({
+  takeOwnership: true,
+  endpoint: process.env.APO_OTLP_ENDPOINT ?? "http://localhost:8000/v1/otlp",
+  // headers, resource attributes, batch/simple processor, etc.
+});
+
+// …your traced work…
+
+await handle.shutdown();  // flush + tear down
+```
+
+### `withApoTrace(name, fn, options?)`
+
+Open a root span, run `fn` inside it, end the span, and return the result.
+
+```ts
+const summary = await withApoTrace("analyze-doc", async (span) => {
+  span.setAttribute("apo.flow.name", "analyze-doc");
+  return runAnalysis();
+});
+```
+
+### Typed observation helpers
+
+For non-LLM work (tools, retrievers, chains, agents), each helper emits a
+correctly-typed GenAI span:
+
+```ts
+const docs = await traceRetriever("what is apo?", async () => [...]);
+const out  = await traceAgent("research-agent", async () => ({ ... }));
+const tool = await traceTool("search", async () => ({ hits: 3 }));
+```
+
+Available: `traceTool`, `traceAgent`, `traceRetriever`, `traceChain`.
+
+### Scoring
+
+Attach scores (numeric / categorical / boolean) to a run or observation:
+
+```ts
+await score(
+  { traceId: runId, name: "correctness", value: 0.92, source: "EVAL" },
+  { endpoint: config.endpoint, headers: { Authorization: `Bearer ${token}` } },
+);
+```
+
+### Trace-context propagation
+
+`injectTraceparent(carrier, fields)` / `extractTraceparent(carrier)` use the W3C
+Trace Context propagator (correctly handles `traceparent`/`tracestate` parsing,
+versioning, and edge cases) — for bridging spans across service boundaries.
+
+### Other exports
+
+`createApoTraceExporter`, `createApoSpanProcessor`, `buildApoAuthHeaders`,
+`ApoSpanProcessor`, plus the option types (`ConfigureApoTelemetryOptions`,
+`ApoTelemetryHandle`, `ApoTraceExporterOptions`, `ApoSpanProcessorOptions`,
+`ApoTraceOptions`, `ScoreOptions`).
+
+## Agent-task evaluation — `@apo-ai/sdk/agent-task`
+
+The product's primary surface: define an agent task and its checks, wire an
+adapter to the agent under test, then run it and collect structured results.
+Import from the subpath:
+
+```ts
+import {
+  task,
+  defineAdapter,
+  runTask,
+  turn,
+  includes,
+} from "@apo-ai/sdk/agent-task";
+```
+
+### Core building blocks
+
+- **`task(id, { adapter, deliverables, … })`** — register the task definition
+  and return its adapter-typed `test`.
+- **`defineAdapter({ initialize, startSession, collectDeliverables, cleanup })`**
+  — the contract between apo and the agent under test (init, run a session,
+  collect deliverables, tear down).
+- **`turn(fn)`** — optionally define task-specific single- or multi-turn input.
+- **`test(id, fn)`** — register a test through the scope returned by `task()`.
+  The callback receives `t` (flat, eve-style assertions over the run's flow)
+  and the task-selected deliverables, inferred from the adapter.
+- **`runTask(task, adapter, options?)`** — execute a single task and return a
+  `TaskRunResult` (transcript + evaluation).
+- **`loadTask(dir)` / `discoverAgentTaskDirs()`** — load tasks from disk.
+- **`createAgentTaskTraceClient(config)`** — the adapter-side trace client
+  passed into runs; the auth token is supplied by the backend runner via
+  `APO_AUTH_TOKEN`.
+
+### Testing (`*.eval.ts`)
+
+One `<task-id>.eval.ts` file holds the task definition, optional turn behavior, and code or
+LLM-backed checks. Checks read both the run's **flow** (what the agent did) and
+its **deliverables** (what it produced).
+Checks are written with a flat `t` context and value matchers — the single way
+to assert. Every assertion is recorded (no die-on-first), so each check reports
+all of its failures.
+
+```ts
+import { task, includes, satisfies } from "@apo-ai/sdk/agent-task";
+import { myAdapter } from "./adapter";
+
+const { test } = task("review-output", {
+  adapter: myAdapter,
+  deliverables: ["result", "stats"],
+});
+
+test("used-the-right-tools", (t) => {
+  t.calledTool("read_file");                       // did it call this tool
+  t.notCalledTool(/delete_/);                      // did it avoid this tool
+  t.toolOrder(["read_file", "search_content"]);    // tools ran in this order
+  t.maxToolCalls(30);                              // didn't flail
+  t.noFailedActions();                             // nothing errored
+});
+
+test("output-correct", (t, { deliverables }) => {
+  // result and stats are inferred from myAdapter.collectDeliverables().
+  t.check(deliverables.result, includes("finding"));
+  t.check(deliverables.stats, satisfies((s: { turn_count: number }) => s.turn_count > 0, "has turns"));
+});
+```
+
+The global `test<TDeliverables>(...)` export remains available for
+framework-agnostic checks and existing task files. Prefer the `test` returned
+by `task()` for new task files: it requires no manual generic or cast and
+exposes only the deliverables selected by that task.
+
+**`t` — flow assertions** (read the run's trace, automatically captured):
+`calledTool(name, opts?)`, `notCalledTool(name, opts?)`, `toolOrder([...])`,
+`usedNoTools()`, `maxToolCalls(n)`, `noFailedActions()`, `loadedSkill(skill)`,
+`calledSubagent(agent)`, `messageIncludes(token)`, `maxTurns(n)`,
+`maxDurationMs(n)`, `assert(label, predicate)`.
+
+`calledTool` / `notCalledTool` take optional constraints to match a call's
+**input**, **output**, and **status** (and `count` for an exact number). Each
+constraint accepts a literal (partial-deep for objects), a RegExp, or a
+predicate:
+
+```ts
+t.calledTool("read_file", { input: { path: "source.py" } });        // exact arg
+t.calledTool("read_file", { input: { path: /^src\// }, count: 2 }); // regex + count
+t.calledTool("compute", { output: (v) => v === 42 });               // predicate on output
+t.calledTool("flakey_tool", { status: "error" });                    // a failed call
+```
+
+`t.assert(label, predicate)` is the escape hatch — assert any predicate over the
+typed flow view when the named methods don't cover your case:
+
+```ts
+t.assert("read before write", (flow) =>
+  flow.toolNamesInOrder.indexOf("read_file") < flow.toolNamesInOrder.indexOf("write_file"),
+);
+```
+
+**`t.check(value, matcher)` — value assertions** (deliverables, parsed JSON,
+anything). Matchers: `includes(substring|RegExp)`, `equals(value)` (deep),
+`matches(standardSchema)` (Zod/Valibot — anything with `safeParse`),
+`satisfies(predicate, label)`, `similarity(expected, threshold = 0.8)` (fuzzy,
+normalized Levenshtein).
+
+For apo tasks the flow is built automatically from the run's trace (via
+`createFlowTee`) — no extra wiring.
+
+**`t.judge(value, instruction)` — LLM-backed assertions.** Configure the judge
+with `runTask(dir, { judge: { model, apiKey?, baseURL? } })`, or set
+`OPENROUTER_MODEL`/`OPENAI_MODEL` for the CLI runtime. Judge verdicts use the
+same recorder and result format as code assertions, including model, prompt,
+response, token usage, and latency metadata.
+
+**Testing agents not built on apo's adapter.** Build a `Flow` from the
+framework's own output with a normalizer, then run the same checks:
+
+```ts
+import { runFlowChecks, test } from "@apo-ai/sdk/agent-task";
+import { fromAISDK } from "@apo-ai/sdk/agent-task";        // or fromOpenAIMessages / fromAnthropicMessages
+
+const flow = fromAISDK(myGenerateTextResult);          // their framework → Flow
+test("used-tools", (t) => { t.calledTool("read_file"); });
+const results = await runFlowChecks({ flow, deliverables: { reply: myGenerateTextResult.text } });
+```
+
+`fromOpenAIMessages(messages)`, `fromAnthropicMessages(messages)`, and
+`fromAISDK(result)` each convert one source into the neutral `Flow` the checks
+read — the plugs that make the testing framework reusable across agent stacks.
+
+### CLI / runtime
+
+`parseAgentTaskCliArgs`, `runAgentTaskCli`, `loadTaskRuntime`, `runTaskDir`,
+`AgentTaskRuntime` — used by the `apo` CLI and the backend's agent-task runner.
+
+See the `apo` CLI (`pnpm apo`) and the agent-task specs for end-to-end usage.
+
+## License
+
+MIT

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

@@ -0,0 +1,121 @@
+import { A as AgentTaskTraceContext } from '../../tracing-DtbhYQV6.js';
+import '../../types-C-nrDEVf.js';
+
+/**
+ * Vercel AI SDK tracing integration for apo.
+ *
+ * Pass the result of {@link createApoTracer} to `generateText`'s
+ * `experimental_telemetry` option. The AI SDK already emits OpenTelemetry
+ * spans natively (e.g. `ai.toolCall`, `ai.generateText`); this tracer
+ * intercepts them and translates them into apo trace spans. The FlowTee
+ * picks up TOOL/GENERATION observations and builds the Flow that
+ * `t.calledTool`, `t.noFailedActions`, and `t.messageIncludes` read.
+ *
+ * The adapter author writes zero manual span code.
+ *
+ * @example
+ * ```ts
+ * import { generateText } from "ai";
+ * import { createApoTracer } from "@apo-ai/sdk/agent-task";
+ *
+ * async sendUserTurn(turn, { trace, parentSpanId }) {
+ *   const result = await generateText({
+ *     model, system, messages, tools,
+ *     experimental_telemetry: createApoTracer({ trace, parentSpanId }),
+ *   });
+ *   return { response: result.text };
+ * }
+ * ```
+ *
+ * @module
+ */
+
+type OTelAttributeValue = string | number | boolean | null | undefined | Array<string | number | boolean | null | undefined>;
+type OTelAttributes = Record<string, OTelAttributeValue>;
+interface OTelSpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+interface OTelSpanStatus {
+    code: number;
+    message?: string;
+}
+interface OTelException {
+    name: string;
+    message: string;
+    stack?: string;
+}
+/**
+ * Minimal `Span` implementation. The AI SDK calls:
+ * - `setAttributes` / `setAttribute` (tool result, response text)
+ * - `setStatus` / `recordException` (errors)
+ * - `end()` (finalises the span)
+ *
+ * Other methods (`addEvent`, `addLink`, `updateName`) are no-ops but must
+ * exist on the object for structural type compatibility with the OTel `Span`
+ * interface the AI SDK expects.
+ */
+interface ApoSpan {
+    spanContext(): OTelSpanContext;
+    setAttribute(key: string, value: OTelAttributeValue): this;
+    setAttributes(attrs: OTelAttributes): this;
+    addEvent(name: string, attributesOrStartTime?: unknown, startTime?: unknown): this;
+    addLink(link: unknown): this;
+    addLinks(links: unknown[]): this;
+    setStatus(status: OTelSpanStatus): this;
+    updateName(name: string): this;
+    end(endTime?: unknown): void;
+    isRecording(): boolean;
+    recordException(exception: OTelException | string, time?: unknown): this;
+}
+/**
+ * Minimal `Tracer` implementation. The AI SDK's `recordSpan` uses
+ * `startActiveSpan(name, { attributes }, fn)`. We also implement
+ * `startSpan(name, opts)` for structural compatibility — it returns a span
+ * without invoking a callback, and the caller is responsible for `.end()`.
+ */
+interface ApoTracer {
+    startSpan(name: string, options?: {
+        attributes?: OTelAttributes;
+    }): ApoSpan;
+    startActiveSpan<T>(name: string, options: {
+        attributes?: OTelAttributes;
+    }, fn: (span: ApoSpan) => Promise<T> | T): Promise<T>;
+    startActiveSpan<T>(name: string, options: {
+        attributes?: OTelAttributes;
+    }, context: unknown, fn: (span: ApoSpan) => Promise<T> | T): Promise<T>;
+    startActiveSpan<T>(name: string, fn: (span: ApoSpan) => Promise<T> | T): Promise<T>;
+}
+interface CreateApoTracerOptions {
+    /** The tee'd trace context from `sendUserTurn`'s second argument. */
+    trace: AgentTaskTraceContext;
+    /** The parent span id for this turn (from `sendUserTurn`'s context). */
+    parentSpanId?: string;
+    /** Optional task id, surfaced in span metadata. */
+    taskId?: string;
+    /** Optional turn number, surfaced in span metadata. */
+    turnNumber?: number;
+}
+/**
+ * Build a `Tracer` compatible with the Vercel AI SDK's
+ * `experimental_telemetry.tracer` option. The returned object satisfies the
+ * shape `{ isEnabled: true, tracer }` so it can be passed directly to
+ * `experimental_telemetry`.
+ *
+ * The AI SDK emits spans named `ai.generateText`, `ai.generateText.doGenerate`,
+ * and `ai.toolCall`. We translate the load-bearing ones:
+ *
+ * - `ai.toolCall` → a TOOL span (so `t.calledTool(name)` works)
+ * - `ai.generateText` → a GENERATION span (so `t.messageIncludes(text)` works)
+ *   and error status → `t.noFailedActions()` catches it
+ *
+ * Other spans (`ai.generateText.doGenerate`, etc.) are ignored — the FlowTee
+ * only cares about TOOL/AGENT/GENERATION observation types.
+ */
+declare function createApoTracer(options: CreateApoTracerOptions): {
+    isEnabled: true;
+    tracer: ApoTracer;
+};
+
+export { type CreateApoTracerOptions, createApoTracer };

package/dist/agent-task/integrations/ai-sdk.js

@@ -0,0 +1,10 @@
+// Auto-generated by `pnpm --filter @apo-ai/sdk build` (tsup.config.ts).
+// Do not edit by hand — edit the src/ originals and rebuild.
+import {
+  createApoTracer
+} from "../../chunk-HKLBPIB4.js";
+import "../../chunk-HWZVL6TS.js";
+export {
+  createApoTracer
+};
+//# sourceMappingURL=ai-sdk.js.map

package/dist/agent-task/integrations/ai-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -0,0 +1,67 @@
+import { A as AgentTaskTraceContext } from '../../tracing-DtbhYQV6.js';
+import '../../types-C-nrDEVf.js';
+
+/**
+ * Anthropic JS SDK tracing integration for apo.
+ *
+ * Wraps an `Anthropic` client so `messages.create()` calls are
+ * automatically traced. Tool calls and generations are captured without
+ * any manual span code in the adapter.
+ *
+ * @example
+ * ```ts
+ * import Anthropic from "@anthropic-ai/sdk";
+ * import { createApoAnthropic } from "@apo-ai/sdk/agent-task";
+ *
+ * async sendUserTurn(turn, { trace, parentSpanId }) {
+ *   const client = createApoAnthropic(
+ *     new Anthropic({ apiKey }),
+ *     { trace, parentSpanId, taskId: ctx.task.id, turnNumber }
+ *   );
+ *   const response = await client.messages.create({
+ *     model: "claude-sonnet-4-20250514",
+ *     max_tokens: 1024,
+ *     messages: [{ role: "user", content: String(turn) }],
+ *     tools: [...],
+ *   });
+ *   const text = response.content.filter(b => b.type === "text").map(b => b.text).join("");
+ *   return { response: text };
+ * }
+ * ```
+ *
+ * @module
+ */
+
+interface CreateApoAnthropicOptions {
+    /** The tee'd trace context from `sendUserTurn`'s second argument. */
+    trace: AgentTaskTraceContext;
+    /** The parent span id for this turn (from `sendUserTurn`'s context). */
+    parentSpanId?: string;
+    /** Optional task id, surfaced in span metadata. */
+    taskId?: string;
+    /** Optional turn number, surfaced in span metadata. */
+    turnNumber?: number;
+}
+/**
+ * Minimal structural shape of the Anthropic client we intercept.
+ */
+interface AnthropicClientLike {
+    messages: {
+        create: (...args: any[]) => Promise<any>;
+    };
+    [key: string]: any;
+}
+/**
+ * Wrap an Anthropic client so `messages.create()` is traced.
+ * Returns a Proxy-wrapped client — call it exactly as you would the
+ * original. Non-streaming only; streaming responses pass through
+ * untraced.
+ *
+ * For SDKs that emit OpenTelemetry natively (Claude Agent SDK, Vercel AI
+ * SDK), prefer `configureApoTelemetry()` instead — no wrapper needed.
+ * This manual wrapper is for the raw `@anthropic-ai/sdk` package or
+ * custom clients that don't emit OTel on their own.
+ */
+declare function createApoAnthropic<T extends AnthropicClientLike>(client: T, options: CreateApoAnthropicOptions): T;
+
+export { type CreateApoAnthropicOptions, createApoAnthropic };

package/dist/agent-task/integrations/anthropic.js

@@ -0,0 +1,10 @@
+// Auto-generated by `pnpm --filter @apo-ai/sdk build` (tsup.config.ts).
+// Do not edit by hand — edit the src/ originals and rebuild.
+import {
+  createApoAnthropic
+} from "../../chunk-SZDSIPXC.js";
+import "../../chunk-GDB6SDGN.js";
+export {
+  createApoAnthropic
+};
+//# sourceMappingURL=anthropic.js.map

package/dist/agent-task/integrations/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -0,0 +1,77 @@
+import { A as AgentTaskTraceContext } from '../../tracing-DtbhYQV6.js';
+import '../../types-C-nrDEVf.js';
+
+/**
+ * OpenAI JS SDK tracing integration for apo.
+ *
+ * Wraps an `OpenAI` client so `chat.completions.create()` calls are
+ * automatically traced. Tool calls and generations are captured without
+ * any manual span code in the adapter.
+ *
+ * Uses a Proxy to intercept the `create` method, then emits GENERATION +
+ * TOOL spans through the trace context. The FlowTee picks these up and
+ * builds the Flow that `t.calledTool` reads.
+ *
+ * @example
+ * ```ts
+ * import OpenAI from "openai";
+ * import { createApoOpenAI } from "@apo-ai/sdk/agent-task";
+ *
+ * async sendUserTurn(turn, { trace, parentSpanId }) {
+ *   const client = createApoOpenAI(
+ *     new OpenAI({ apiKey, baseURL: "https://openrouter.ai/api/v1" }),
+ *     { trace, parentSpanId, taskId: ctx.task.id, turnNumber }
+ *   );
+ *   const response = await client.chat.completions.create({
+ *     model: "google/gemini-2.5-flash-lite",
+ *     messages: [{ role: "user", content: String(turn) }],
+ *     tools: [...],
+ *   });
+ *   return { response: response.choices[0].message.content ?? "" };
+ * }
+ * ```
+ *
+ * @module
+ */
+
+interface CreateApoOpenAIOptions {
+    /** The tee'd trace context from `sendUserTurn`'s second argument. */
+    trace: AgentTaskTraceContext;
+    /** The parent span id for this turn (from `sendUserTurn`'s context). */
+    parentSpanId?: string;
+    /** Optional task id, surfaced in span metadata. */
+    taskId?: string;
+    /** Optional turn number, surfaced in span metadata. */
+    turnNumber?: number;
+}
+/**
+ * Minimal structural shape of the OpenAI client we need to intercept.
+ * We avoid importing `openai` at the type level so this module doesn't
+ * take a runtime dependency — the wrapper works with any client that has
+ * `chat.completions.create`.
+ *
+ * The `create` signature uses a broad type so the OpenAI SDK's overloaded
+ * `create` method (which has specific param types) is assignable to this.
+ */
+interface OpenAIClientLike {
+    chat: {
+        completions: {
+            create: (...args: any[]) => Promise<any>;
+        };
+    };
+    [key: string]: any;
+}
+/**
+ * Wrap an OpenAI client so `chat.completions.create()` is traced.
+ * Returns a Proxy-wrapped client — call it exactly as you would the
+ * original. Non-streaming only; streaming responses pass through
+ * untraced.
+ *
+ * For SDKs that emit OpenTelemetry natively (OpenAI Agents SDK, Vercel AI
+ * SDK, Claude Agent SDK), prefer `configureApoTelemetry()` instead — no
+ * wrapper needed. This manual wrapper is for the raw `openai` package or
+ * custom clients that don't emit OTel on their own.
+ */
+declare function createApoOpenAI<T extends OpenAIClientLike>(client: T, options: CreateApoOpenAIOptions): T;
+
+export { type CreateApoOpenAIOptions, createApoOpenAI };

package/dist/agent-task/integrations/openai.js

@@ -0,0 +1,10 @@
+// Auto-generated by `pnpm --filter @apo-ai/sdk build` (tsup.config.ts).
+// Do not edit by hand — edit the src/ originals and rebuild.
+import {
+  createApoOpenAI
+} from "../../chunk-DT2LMB7O.js";
+import "../../chunk-GDB6SDGN.js";
+export {
+  createApoOpenAI
+};
+//# sourceMappingURL=openai.js.map

package/dist/agent-task/integrations/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}