From 8744cef8b9101ef148cf7b0ef00e884a23f8106a Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 03:24:53 -0800 Subject: [PATCH 1/4] docs(auto): make zero-code Node tracing easy to start (#617) * docs(auto): lead with verified zero-code setup Replace the implementation-led README with quick start, source-derived coverage, privacy defaults, deployment recipes and focused references. Preserve capture details and correct custom-exporter authentication and wire-transport claims. Add documentation regression checks and an executable consumer recipe harness. Co-Authored-By: Claude Code * test(auto): bound documentation consumer teardown Co-Authored-By: Claude Code * docs(auto): show the real quick-start trace and drop version pins - "What you get" opens with a screenshot of the README's own OpenAI example as it appears in Future AGI: a real run of @traceai/auto 0.1.0 with OpenAI SDK 7 and openai/gpt-4.1-mini through OpenRouter (model, provider, 13/3/16 tokens, cost, 885 ms, request and response). - `npm install @traceai/auto` and `npm install openai` instead of pinned versions. The quick start was verified in E2B with OpenAI SDK 5, 6 and 7.53.0 through --import, NODE_OPTIONS and CommonJS --require (one LLM span with output and usage each); @traceai/openai hooks ^4-^7. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Code --- README.md | 19 +- spec/auto-instrumentation/README.md | 2 +- typescript/packages/fi-core/README.md | 6 + typescript/packages/traceai_auto/README.md | 887 ++++-------------- .../traceai_auto/docs/ARCHITECTURE.md | 474 ++++++++++ .../traceai_auto/docs/CONFIGURATION.md | 181 ++++ .../packages/traceai_auto/docs/FRAMEWORKS.md | 159 ++++ .../docs/images/quickstart-trace.png | Bin 0 -> 100550 bytes .../traceai_auto/scripts/generate-readme.cjs | 24 + .../traceai_auto/test/docs-consumer.cjs | 138 +++ .../packages/traceai_auto/test/docs.test.ts | 47 + 11 files changed, 1249 insertions(+), 688 deletions(-) create mode 100644 typescript/packages/traceai_auto/docs/ARCHITECTURE.md create mode 100644 typescript/packages/traceai_auto/docs/CONFIGURATION.md create mode 100644 typescript/packages/traceai_auto/docs/FRAMEWORKS.md create mode 100644 typescript/packages/traceai_auto/docs/images/quickstart-trace.png create mode 100644 typescript/packages/traceai_auto/scripts/generate-readme.cjs create mode 100644 typescript/packages/traceai_auto/test/docs-consumer.cjs create mode 100644 typescript/packages/traceai_auto/test/docs.test.ts diff --git a/README.md b/README.md index 7ee65f632..f20794abe 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Trace LLM calls, agents, tools, and retrieval. Keep your application code and yo **79 integration families · 5 languages · OpenTelemetry-native · Apache 2.0** -[Get started](#quickstart) · [Integrations](#integrations) · [Documentation](https://docs.futureagi.com/docs/tracing) · [Contribute](CONTRIBUTING.md) +[Zero-code Node.js](#zero-code-tracing-for-nodejs) · [SDK quickstarts](#quickstart) · [Integrations](#integrations) · [Documentation](https://docs.futureagi.com/docs/tracing) · [Contribute](CONTRIBUTING.md) [![PyPI](https://img.shields.io/pypi/v/fi-instrumentation-otel?label=PyPI&color=555555)](https://pypi.org/project/fi-instrumentation-otel/) [![npm](https://img.shields.io/npm/v/%40traceai%2Ffi-core?label=npm&color=555555)](https://www.npmjs.com/package/@traceai/fi-core) @@ -31,9 +31,24 @@ Trace LLM calls, agents, tools, and retrieval. Keep your application code and yo - **Follow the request.** Connect model calls, retrieval, and tool execution with OpenTelemetry spans and context. - **Choose what leaves your app.** Configure content masking and export through your own OpenTelemetry pipeline. +## Zero-code tracing for Node.js + +**See your AI calls without adding tracing code.** Install [`@traceai/auto`](typescript/packages/traceai_auto/) and preload it before your app (Node.js 20.6+, ESM or CommonJS): + +```bash +npm install @traceai/auto +FI_API_KEY="your-api-key" FI_SECRET_KEY="your-secret-key" \ +FI_PROJECT_NAME="my-ai-app" \ +node --import @traceai/auto/register app.mjs +``` + +Keep your provider credentials configured as usual. Make an AI request, consume the response, then open **Observe → my-ai-app** in [Future AGI](https://app.futureagi.com). OpenAI instrumentation is included; recognized AI calls through global `fetch` are captured too. Optional framework integrations retain their own coverage limits. + +**Prompts and responses are captured by default.** Set `FI_HIDE_INPUTS=true FI_HIDE_OUTPUTS=true FI_HIDE_ERROR_DETAILS=true` before startup to hide content. [Setup, supported libraries, privacy and framework recipes →](typescript/packages/traceai_auto/) + ## Quickstart -Pick your language. These examples send traces to [Future AGI](https://app.futureagi.com); you can also supply your own OpenTelemetry tracer provider and exporter. +Prefer explicit instrumentation or another language? Pick your language. These examples send traces to [Future AGI](https://app.futureagi.com); you can also supply your own OpenTelemetry tracer provider and exporter. | Language | Instrumentation | Install / coordinates | | :--- | :--- | :--- | diff --git a/spec/auto-instrumentation/README.md b/spec/auto-instrumentation/README.md index a4e76eb22..1da863d98 100644 --- a/spec/auto-instrumentation/README.md +++ b/spec/auto-instrumentation/README.md @@ -33,7 +33,7 @@ It runs on the HTTP clients each runtime uses for AI calls: | SDK | Transports patched | | --- | --- | | Python | `httpx` and `httpx2` (sync and async), `requests`, `aiohttp` | -| TypeScript | `globalThis.fetch` (covers undici and every fetch-based SDK) | +| TypeScript | `globalThis.fetch` as observed after preload; not direct `undici.fetch`/`undici.request`, `node-fetch`, or a fetch reference cached before preload | | Go | `http.DefaultTransport` (and any `http.Client` built from it) | | C# | `HttpClient` through a `DiagnosticListener` handler | | Java | `java.net.http.HttpClient` and OkHttp when present | diff --git a/typescript/packages/fi-core/README.md b/typescript/packages/fi-core/README.md index c9abcebdd..7e053191c 100644 --- a/typescript/packages/fi-core/README.md +++ b/typescript/packages/fi-core/README.md @@ -2,6 +2,12 @@ Core OpenTelemetry instrumentation library for TypeScript applications with advanced evaluation capabilities for AI systems. +## Choose your setup + +For **zero-code Node.js tracing**, start with [`@traceai/auto`](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/README.md): install one package and preload it before your app. It includes OpenAI instrumentation, recognizes supported AI traffic through global `fetch`, and enables eligible installed integrations. Its own export route is batched; prompts and responses are captured by default, with explicit hide controls. + +Use **`@traceai/fi-core`** when you want to configure the provider, create custom spans or register instrumentors yourself. Do not add a second provider or duplicate instrumentation to an app already using the auto preload. Application-owned OpenTelemetry exporters keep their own privacy policies. + ## Overview `@traceai/fi-core` provides a comprehensive tracing solution built on OpenTelemetry that's specifically designed for AI applications. It offers custom span exporters, evaluation tags, and seamless integration with the TraceAI platform for observability and performance monitoring. diff --git a/typescript/packages/traceai_auto/README.md b/typescript/packages/traceai_auto/README.md index cc59456e7..d3860dd39 100644 --- a/typescript/packages/traceai_auto/README.md +++ b/typescript/packages/traceai_auto/README.md @@ -1,736 +1,253 @@ # @traceai/auto -Zero-code AI tracing for Node.js 20.6+ (ESM and CommonJS). Two complementary -layers cover installed traceAI integrations and recognized AI HTTP wire protocols. -This is broad process-level coverage, **not a claim that every possible AI client, -transport, or framework is supported**. See the limitations below. +**Trace your Node.js AI calls without changing your application code.** Preload once to capture supported model requests, responses, token usage and timing as OpenTelemetry spans. -## Install and run +[Quick start](#quick-start) · [Coverage](#supported-libraries-and-protocols) · [Privacy](#privacy-defaults) · [Frameworks](#frameworks-and-deployment) · [Troubleshooting](#troubleshooting) + +## Quick start + +You need **Node.js 20.6+**, an existing Node application, and a [Future AGI](https://app.futureagi.com) API key / secret key pair. Keep your model provider's credentials configured as usual; traceAI does not supply a model key. + +Install in your application's directory: ```sh npm install @traceai/auto -export FI_API_KEY=your-api-key -export FI_SECRET_KEY=your-secret-key -node --import @traceai/auto/register app.mjs ``` -Other entry points use the same singleton: +Set both FI keys through your deployment's secret manager or shell environment, then start the app with one preload: ```sh -NODE_OPTIONS="--import @traceai/auto/register" node app.js -node -r @traceai/auto/register app.cjs +FI_API_KEY="your-api-key" FI_SECRET_KEY="your-secret-key" \ +FI_PROJECT_NAME="my-ai-app" \ +node --import @traceai/auto/register app.mjs ``` -Or initialize before importing AI libraries: +Replace `app.mjs` with your entry file. **Prompts and responses are captured by default.** To hide them, set `FI_HIDE_INPUTS=true FI_HIDE_OUTPUTS=true FI_HIDE_ERROR_DETAILS=true` before startup. See [privacy defaults](#privacy-defaults) before deploying with sensitive data. -```ts -import { init } from "@traceai/auto"; -init(); -``` +Make an AI request, consume the response, then open **Observe → my-ai-app** in Future AGI. For supported calls, the trace includes the provider/model, input and output, duration, and any usage the provider returned. Streaming timing is available when the transport exposes it; missing usage is not invented. + +### Keep your existing start command -`init(options)` configures the process **once**. It retains the existing provider, -configuration and hooks on every later call, logging one diagnostic line. It returns -the **same tracer provider object**, or `undefined` when initialization is disabled or -failed. Diagnostics are returned by `report()`, not `init()`. Other exports are -`forceFlush(): Promise`, `shutdown(): Promise`, and -`registerSecret(value: unknown): void` (also exported additively by `@traceai/fi-core`). -Integrations can register credentials observed outside a transport without supplying -span context or retaining per-trace credential groups. Non-string values and strings -shorter than eight characters are ignored; registration never coerces user objects. -Shutdown removes this agent's hooks/processors but never shuts down an -application-owned global OTel provider. Reinitialization after shutdown or failed -startup, changing privacy/exporter settings, and disabling an enabled integration -by calling `init()` again are unsupported: restart the process to change configuration. -For short-lived programs, finish reading responses, then `await forceFlush()` or -`await shutdown()`. - -The preload does not perform network I/O. The first real completed span initiates -a bounded batch export, or `doctor` can explicitly send a test span. FI credentials -are required only for the default FI destination. `init({ exporter })`, -`init({ spanProcessor })`, `init({ provider })`, or an existing application OTel provider -activates instrumentation without FI credentials and without creating an FI export route. -With neither a destination nor a complete FI pair, both layers are disabled with one warning. -FI project routing never replaces application `service.name` or environment resource -identity. Export/integration failures warn once per -failure category, do not log credentials/provider bodies, and leave the app running. -A one-shot `beforeExit` handler flushes completed spans. The agent adds no SIGINT -handler. Its SIGTERM listener starts a bounded flush and preserves app-owned listeners; -without one, it restores the default action and re-raises SIGTERM (preserving the signal -exit). Explicit flush/shutdown have a five-second deadline. Shutdown reserves up to -2.5 seconds for flush and then invokes exporter shutdown with the remaining 2.5 seconds, -even if flush never resolves. A failed initialization rolls back this agent's hooks, -processor and newly installed globals; app-owned globals are retained. The first -configuration remains terminal, so a later `init()` cannot retry or rewire the -process. SIGKILL/forced termination cannot guarantee delivery. - -### Relocatable launcher payload - -The build also produces `dist/agent/`. Copy the **whole directory**, including -`runtime.cjs`, `hook.mjs`, `hook-register.cjs` and linked `.LEGAL.txt` notices. -Also copy `dist/THIRD-PARTY-NOTICES` and `dist/third-party-manifest.json` alongside -the relocated payload; the linked comments alone are not the full license texts: +With the FI variables above already set, use `NODE_OPTIONS` for an npm script or process launcher: ```sh -node --require "/absolute/agent directory/preload.cjs" app.mjs -NODE_OPTIONS='--require "/absolute/agent directory/preload.cjs"' node app.cjs +NODE_OPTIONS="--import @traceai/auto/register" npm start ``` -Use `--require`, not `--import`, for launcher injection. No `@traceai/auto` install in -the application is needed. The payload embeds OpenAI instrumentation, including support -for OpenAI v4's default node-fetch transport; app-installed instrumentors take precedence. -The ES5-only preload skips Node <18 without loading/parsing the modern payload. Node -without `module.register` keeps CJS/fetch capture, not ESM library hooks. Historical -binaries were not exercised: the unsupported-version guard is VM-tested, and a missing -`module.register` is tested in a real child process. The supported package engine is -Node >=20.6. - -## Capture layers - -### Wire layer - -The runtime reads a byte-identical packaged copy of the shared -`spec/auto-instrumentation/wire-protocols.json` catalog. It patches `globalThis.fetch`, -preserving the fetch function's name, length and custom properties via a Proxy. - -Recognized formats include: - -- OpenAI-compatible chat/completions, Responses, embeddings, image generation, - moderation, transcription/translation and speech generation; compatible gateways - and providers are recognized by the catalog. Unknown hosts use the endpoint's - protocol-specific fallback (`openai_compatible`, `anthropic_compatible`, - `gemini_compatible`, or `cohere_compatible`). -- Anthropic messages, Gemini/Vertex generate-content and embeddings, Cohere chat, - embed and rerank, Bedrock converse/invoke, Ollama chat/generate/embed. -- Deepgram listen/speak, ElevenLabs TTS/STT, AssemblyAI transcript submission and - completed polling, and Cartesia bytes/SSE TTS. - -Request-body validation prevents unrelated application endpoints from being claimed. -Request streams, opaque Request objects and over-limit bodies are captured **only for -catalog providers**, without request content and with `traceai.wire.body_unavailable` -or `traceai.wire.truncated`. Unknown proxies need a validated materialized request. -The actual fetch is invoked before inspecting materialized bodies: no request cloning, -stream read-ahead or request-side wait is added. - -Wire spans are OTel CLIENT spans with the saved parent context. Start time is the -transport handoff, before URL validation or request inspection; end time is the last -observed byte/error, captured **before** copying, decoding or parsing. Parsing is -excluded from duration. Streams are observed by tapping the existing readers and -iterators, not by replacing the body. The caller receives the **original fetch -Promise and original Response**, including subclass/helper methods and native headers, -URL/type, clone, tee, BYOB support (or its original rejection), cancellation promises, -and chunk identities. Capture copies bytes into its own bounded buffers without -transferring/detaching app storage. No read, reader lock, synthetic Response, automatic -clone or eager tee is created for an unread body. Export is never awaited between -chunks; reading multiple clone/tee branches produces at most one wire span. - -Text/JSON/SSE/NDJSON capture stops at the configured byte cap, discards buffered -content, and sets `traceai.wire.truncated`. Audio/binary responses are counted, not -buffered. JSON/SSE TTS base64 audio is counted with a bounded streaming scanner, -without accumulating or decoding audio. If a custom fetch exposes compressed JSON/SSE -TTS bytes, the compressed capture is bounded by the body cap and decoded asynchronously -after consumption; decoded chunks go straight to that scanner, not a retained audio -buffer. The decoded-work cap also applies; exceeding it sets `traceai.wire.truncated`. -FormData text fields are read independently -of upload size, each capped at 64 KiB; file bytes are never read, and only their -size/MIME/filename are retained. Catalog embedding formats record dimensions, not -vectors. Use `traceConfig.hideEmbeddingVectors` (or `FI_HIDE_EMBEDDING_VECTORS=true`) -to also hide vectors in generic JSON fallbacks and forwarded library/application spans. - -Native fetch normally decompresses responses. When a custom fetch exposes encoded -bytes, bounded asynchronous Node decoders handle gzip/deflate/Brotli before parsing, -plus zstd when Node exposes it. The Node-free layer uses Web `DecompressionStream` -for the codecs its runtime supports. Unavailable decoders -keep request-side metadata and set `traceai.wire.undecoded_encoding`. Already-decoded -JSON/SSE is not decoded twice. A transport failure mid-stream is ERROR with parsed -partial output; consumer cancellation is OK with `traceai.wire.incomplete = true`. - -Wire **span creation** is skipped for OTel-suppressed contexts, nested captures, and -LLM/EMBEDDING/RERANKER/GUARDRAIL ancestors, even through intermediate native SDK -spans. Outgoing credential observation is never skipped by these rules: fetch reads -headers/URL without inspecting suppressed request bodies. Node HTTP and Undici -diagnostic-channel subscribers also observe outgoing headers/URLs (including direct, -cached clients and non-AI routes); they do not create additional wire spans. The FI processor keeps weak live ancestry, so a model kind set after span -creation is also respected. Both `gen_ai.span.kind` and older `fi.span.kind` are -understood, including FI-wrapped spans. Uncovered CHAIN/AGENT/TOOL spans remain -eligible parents. Session, user and other fi-core context attributes are propagated. - -Wire attributes pass through fi-core's TraceConfig. Additional conservative handling -covers flattened message keys, audio transcripts, and raw body copies when content -hiding is enabled. `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, -`FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, `FI_HIDE_OUTPUT_TEXT`, -`FI_HIDE_INPUT_IMAGES`, `FI_HIDE_ERROR_DETAILS`, and `FI_PII_REDACTION` are supported. -TTS `gen_ai.audio.transcript` obeys input-hide flags; STT obeys output-hide flags. -Hidden transcripts use `[REDACTED]`, exactly like hidden input/output values. - -### Privacy - -One export-time boundary sanitizes **every span sent through the agent's exporter**: -wire spans, dedicated-library spans and forwarded application spans. It builds a -detached snapshot of the ended native span; other exporters keep the original -span/resource/context unchanged by that export policy. In auto destination mode, -foreign attributes are never rewritten by FI policy. FI-authored attributes still -receive write-time hide flags, image caps, PII and known-secret protection, so -other exporters never receive authored content that those protections hid. -Application active context uses the native span; instrumentor writes use a separate -FI wrapper. Explicit standalone `FITracer` retains its active-wrapper behavior. -This is an **interim export-built view**, not complete capture: data the host SDK -already dropped or truncated may be omitted or marked unknown, never reconstructed. -Attributes (arrays element-wise), status descriptions, event names/attributes, -link attributes/contexts, resources, instrumentation scope name/version/attributes -and tracestate values all pass through this boundary. Nonfinite numbers become -`"NaN"`, `"Infinity"` or `"-Infinity"`. Unsupported attribute objects become type -names; user attribute getters, `toString` and `toJSON` are never called. The standard -ReadableSpan context method is supported for library-generated snapshots. - -Work is bounded across each snapshot (20,000 values, 8 MiB text, 32 array levels; -credential discovery also has depth/count limits). On a sanitizer error, content, -status descriptions, events, links, scope and resource content are dropped for that -span while its identity and timing survive. Upstream wire scrubbing is best-effort, -not the security boundary. Before TraceConfig masking, every recorded string is -scrubbed: - -- Data URLs and long base64 media fields (`data`, `bytes`, `b64_json`, `file_data`, - `audio_base64`, `images` elements) become ``. Image-generation - `b64_json` uses the format contract's `` placeholder. Raw audio is - never retained, even for tiny inline audio clips: scalar/array `audio` and - `input_audio` JSON leaves, indexed flattened fields and `inlineData.data.0` with - a sibling audio MIME type all use the same no-minimum-size audio policy. - MIME metadata and transcripts remain subject to their own content-hide controls. -- Credential-named keys are replaced with `` recursively, including - `authorization_token` in MCP server settings. The only logprob-name exception - is the explicitly bound provider-root policy below; access-key identifiers - remain masked. Catalog credential shapes are checked independently of names. -- Signed URL parameters, including AWS/GCP signatures and Azure SAS fields, have their - values replaced with ``, including percent-encoded parameter names. -- A single `globalThis[Symbol.for('traceai.secrets')]` registry is shared by installed, - embedded, CJS and ESM package copies in the process/isolate. It retains at most 1024 - values of eight or more characters, evicting the least recently registered/observed - value. Immutable longest-first snapshots are cached until membership changes. At - initialization it is seeded with configured FI keys and credential-like environment - values (names containing KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL or AUTH). - Transport-observed header/query values, parsed credential fields and explicit - `registerSecret` calls augment it. Every exported span, including application-owned - instrumentation spans and unrelated/later traces, uses the current registry at - export time; there is no span-start credential inheritance or SDK-state inspection. - Credential headers and export-boundary credential fields use one shared list, - including `x-goog-api-key`, `anthropic-api-key` and `ocp-apim-subscription-key`. - Values never appear in diagnostics, reports or error messages. Every registered - value is removed from every exported string, including names, status, events, - links, resource/scope attributes and tracestate; other exporters remain unchanged. - Materialized bodies discarded by the capture cap, URLSearchParams values and - uncropped/duplicate FormData text fields still undergo bounded credential discovery - before disposal. File bytes are never inspected. Credential-discovery budget - exhaustion or failure while inspecting a materialized body drops all exported - content, not span identity, timing or status code; this also omits the truncation - marker on that fail-closed snapshot. Opaque, unparsed bodies instead follow the - scoped limitation below; their observable headers/URL still augment the registry. - Configured FI keys remain protected by the export policy even after LRU churn. - -For the closed, versioned `logprob_tokens` catalog paths, **logprob tokens are checked against registered secrets and credential shapes, not key-name rules**. -This exception is available only from the parsed OpenAI chat response root at the -instrumentation handoff: `choices[*].logprobs.content[*].token` and -`choices[*].logprobs.content[*].top_logprobs[*].token`. It does not apply to nested -JSON in user content, tool output, arbitrary attributes, or flattened key names. -If value masking changes any choice's `message.content` or `delta.content`, its -**entire logprobs block** is masked, including alternatives and byte arrays. -Buffered streaming responses are scanned by choice index before export; once a -choice is masked, earlier buffered blocks and all later blocks for that choice -are masked too. Concatenated deltas are checked for split secrets, and affected -delta text is masked. A masked individual token also loses its byte-array alias. -The staged OpenAI instrumentor exports the buffered response once, not each delta. -Other provider structures have no new exception without catalog/source evidence. - -Hide policies match semantic families, including `input.*`, `output.*`, -`gen_ai.input.*`, `gen_ai.output.*`, system instructions, tools, image/file URIs and -side-specific audio transcripts. `FI_HIDE_LLM_INVOCATION_PARAMETERS=true` additionally -hides `gen_ai.request.parameters`, explicit invocation parameters and tool schemas. -`hideEmbeddingVectors` also covers JSON fallbacks such as generic Bedrock invoke, -not only spans classified as EMBEDDING. Image hiding conservatively hides raw input -and input-message families to prevent URI aliases escaping the image policy. - -Do not put arbitrary secrets in prompts: unknown free-text secrets cannot always be -recognized. These policies cover dedicated-instrumentor spans only when they pass -through **this agent's** exporter; unrelated exporters retain their own policy. - -### Batching and Lambda lifecycle - -| Entry | Processor policy | Lifecycle | -| --- | --- | --- | -| Manual fi-core `register()` / `FITracerProvider`, omitted `batch` or explicit `batch: false` | `SimpleSpanProcessor`, preserving the manual dev default | Await provider flush/shutdown before process termination | -| Manual `batch: true` | Bounded `BatchSpanProcessor` | Await provider flush/shutdown | -| Zero-code owned provider/export route | Explicit `BatchSpanProcessor` / batch request | Auto bounded exit/signal drain; pass the returned provider to the Lambda wrapper | -| Explicit fi-core `spanProcessors` / auto `spanProcessor` | Supplied processors retain their selected policy | No silent replacement or rebatching; retain the documented owner lifecycle | - -For Lambda, create/reuse the provider outside the handler and pass the returned -provider to fi-core's `traceLambdaHandler(handler, { provider })`. The wrapper -ends its invocation span and flushes within the invocation budget; it does **not** -shut down a warm provider per invocation. R-C07 is superseded by **zero-code owned -provider batches; explicit `batch: false` honoured**. Batching and a successful -local handoff are not proof of collector acceptance. - -### Library layer - -`src/integrations.json` inventories all 45 instrumentation packages currently in the -TypeScript workspace, with their exported classes, target libraries and actual -module-hook entry points. OpenAI instrumentation is a dependency and is embedded in -the launcher payload; other dedicated packages are **not** installed implicitly. -Install the integrations you need, for example: +Preserve any other Node flags your deployment already needs. For CommonJS, either use the same `--import` preload or: ```sh -npm install @traceai/langchain +node --require @traceai/auto/register app.cjs ``` -Target/instrumentation resolution is from the application's working directory. -Install packages in that app and run from its directory. Hook registration is eager; -target patching occurs on import/require. The import-in-the-middle loader is registered -before `registerInstrumentations`, restricted to target entry points rather than -all ESM internals (which can break SDK shim live bindings). Node 26 currently emits -a deprecation warning for upstream `module.register()` when library hooks are enabled. -Both ESM and CJS patching are tested against the real OpenAI npm package, with and -without app-installed instrumentation. OpenAI v4/node-fetch can additionally emit -Node's upstream `punycode` deprecation. Neither warning is suppressed by the agent. -Disabled integrations are never loaded or registered, including integrations sharing -a target (for example DeepSeek and OpenAI). - -| Framework integration | 11-11 support | Entry point | -| --- | --- | --- | -| Mastra | Manual tracing only; no zero-code bridge at 11-11 | `createFIObservability` / `createFIMastraExporter` from `@traceai/mastra` | - -The Mastra zero-code bridge follows after 11-11. The registry reports installed -Mastra targets as `manual` and does not load `@traceai/mastra/auto` or call an enable hook. - -For Genkit and Vercel AI SDK, the registry calls an installed `enable` -entry (also accepting the integration's named enable function). It prefers the -optional `/auto` subpath. Versions without that entry are reported `manual`, not -forced into an incompatible constructor; a broken entry fails open. The entry -receives `{ tracerProvider, spanProcessor, traceConfig }` for the selected agent -branch; older no-argument entries can ignore these optional arguments and use the -initialized agent. An instrumentor returned by the entry is explicitly bound to -that provider, not an unrelated global provider. This does not replace any global -provider or synthesize FI credentials. -Manual-only integrations remain Claude Agent SDK (`wrapQuery`), Codex SDK -(`wrapCodex`/`manuallyInstrument`), Pi Coding Agent (session wrapper), and VoltAgent -(processor). Their underlying fetch AI calls can still be traced. -Existing dedicated instrumentations retain their supported-version and method -coverage constraints; registration does not expand those APIs. OpenAI Agents uses -additive processor registration (`exclusiveProcessor:false`), preserving application -processors. Shutdown recognizes processor/class-registry ownership as well as -shimmer wrappers, and leaves application-owned patches intact. - -If `@opentelemetry/instrumentation-http` is resolvable in the app, it is enabled for -incoming SERVER spans only. Outgoing non-AI HTTP calls are not traced by default: +Run from the application's directory so target libraries and optional instrumentors can be resolved. Do not add a second preload or manually patch the same client. + +### Try it with OpenAI + +If you do not have an app yet, install the OpenAI SDK (versions 4 to 7 are supported): ```sh -npm install @opentelemetry/instrumentation-http +npm install openai ``` -### Existing OTel SDKs - -An existing global SDK provider is retained, with the FI processor added beside its -existing processors. Its sampler/context manager remain authoritative. OTel JS 2.x -has no public late-add-processor API, so this uses the live MultiSpanProcessor list; -the public 1.x API is also recognized. FI project resource attributes are enriched -only on the FI export copy. If a custom provider does not expose either supported -attachment mechanism, the agent warns and uses an isolated AI provider without -replacing the global provider. This is a degraded fallback, not a promise of -processor attachment to arbitrary OTel implementations. - -## Server bundlers - -Exported adapters inject the built preload into **Node server entries only**: - -```ts -// esbuild: { platform: 'node', plugins: [traceAI()] } -import { traceAI } from '@traceai/auto/esbuild'; -// Vite: plugins: [traceAI()] — production Node SSR only, not client/webworker SSR -import { traceAI } from '@traceai/auto/vite'; -// Rollup: plugins: [traceAI({ server: true })] — explicit target required -import { traceAI } from '@traceai/auto/rollup'; -// webpack 5: { target: 'node', plugins: [new TraceAIPlugin()] } -import { TraceAIPlugin } from '@traceai/auto/webpack'; -``` +Set `OPENAI_API_KEY` and `OPENAI_MODEL` for a model your account can use. Save this ordinary application code as `app.mjs`, then use the quick-start run command. There are **no tracing imports** in the application: + +```js +import OpenAI from "openai"; -These are separate config examples, not imports to combine in one file. Adapters are -idempotent, preserve shebangs, and leave browser outputs alone. Real esbuild, Rollup, -Vite and webpack builds are tested, including plugin-only builds using external OpenAI -v4's default node-fetch transport (not just global fetch). Symlinked esbuild entries -are matched by their canonical paths; aliases, installed package entries, -extensionless entries, directory indexes and custom extensions use esbuild's own -entry-point resolver before path canonicalization. esbuild split/dynamic chunks do not get extra -preloads. CJS entries require the preload before their code while retaining strict-mode -directives (webpack uses its source-aware insertion API). A missing/broken preload warns -and leaves the application running rather than turning a deployment mistake into a crash. - -**ESM executable entries** get a tiny bootstrap at the original output path, which -initializes the agent and then dynamically imports a sibling `*.traceai-app.mjs` payload. -A static preload import alone is too late: Node has already linked the application's -static dependencies before executing it. Deploy the payload and its sourcemaps/chunks -alongside the bootstrap. The payload retains its code and mappings without an injected -line; CJS sourcemaps account for the inserted preload. - -This ESM bootstrap is for executable server entries, not library/handler modules: -exported ESM entries are rejected rather than silently losing live exports. The executing -entry's `import.meta.url` names the payload, not the bootstrap; programs relying on an -exact entry filename/main-module identity must instead use `node --require` externally. -For Next handlers, prefer `instrumentation.ts` below. Runtime/chunk code still lives in -the same directory. Bundler-specific advanced packaging modes beyond the tested cases -are unverified. - -The injected absolute path must exist at runtime: deploy `dist/agent/` to the same -path or pass `{ agentPath: '/deployed/agent/preload.cjs' }`. Do not omit sibling files. - -Preloading cannot recover package import boundaries erased by bundling. Keep AI SDKs -external for dedicated library hooks; bundled global-fetch calls still use wire capture. -Do not use these adapters for browser/edge outputs. - -### Next.js - -Prefer Next's `instrumentation.ts` with a runtime guard (works independently of the -selected Next bundler). Keep `@traceai/auto` external via `serverExternalPackages` -where your Next version supports it: - -```ts -export async function register() { - if (process.env.NEXT_RUNTIME === 'nodejs') { - await import('@traceai/auto/register'); - } -} +const response = await new OpenAI().chat.completions.create({ + model: process.env.OPENAI_MODEL, + messages: [{ role: "user", content: "Say hello in one word." }], +}); +console.log(response.choices[0].message.content); ``` -`withTraceAI(config)` from `@traceai/auto/next` is an optional **webpack-only** fallback; -it skips client/edge configs and preserves an existing webpack callback. The callback -wrapper, generated real-webpack config, and register snippet are tested. An actual -Next server build/start and Turbopack lifecycle are **unverified**; the webpack wrapper -does not cover Turbopack. Never import the Node agent in an edge instrumentation path. +The preload flushes completed spans when Node exits naturally. If your app explicitly terminates or runs inside a serverless invocation, use the [lifecycle guidance](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/FRAMEWORKS.md#aws-lambda-and-short-lived-processes). -## Edge runtime +## What you get -`@traceai/auto/edge` is an explicit fetch observer, not a zero-code Node agent: +The **Try it with OpenAI** example, as it appears in Future AGI (a real run with OpenAI SDK 7 and `openai/gpt-4.1-mini` through OpenRouter): -```ts -import { patchFetch } from '@traceai/auto/edge'; -const hook = patchFetch(4 * 1024 * 1024, (result, start, end) => { - // Adapt to the isolate's own tracer/exporter, parent context and content policy. -}); -// hook.remove() restores fetch. hook.pending contains completed-response decoding only. +![The example's chat completion span in Future AGI: model, provider, prompt and completion tokens, cost, duration, and the request and response bodies](docs/images/quickstart-trace.png) + +- **Model calls without per-call wrappers.** OpenAI instrumentation is included. Recognized AI requests through the process's global `fetch` are also captured, including compatible gateways. +- **More context from installed integrations.** Dedicated packages can add framework, agent, tool, retrieval and database spans. They retain their own method/version limits; auto-registration does not expand their coverage. +- **One trace, not two copies of each call.** Wire capture yields to covered model spans and respects OpenTelemetry suppression. Existing providers keep their sampler, context and application processors. +- **Standard OpenTelemetry.** Send to Future AGI by default, or use an [application-owned provider/exporter](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/CONFIGURATION.md#bring-your-own-opentelemetry-destination) without FI credentials. + +This is AI instrumentation, not a general-purpose APM agent. Outgoing non-AI HTTP calls, arbitrary application functions and every possible AI transport are not automatically traced. + +## Supported libraries and protocols + +**Included:** OpenAI library hooks and the global-fetch wire observer. **Optional:** other dedicated instrumentors must be installed alongside their target library. The app always owns installation of its AI SDKs. + +To see what your app needs, without installing anything: + +```sh +npx --no-install traceai-auto bootstrap ``` -Its ESM bundle has no Node APIs, Buffer, process/env access or OTel dependency. Isolated -VM tests prove JSON, rejection and streaming capture without those globals. It uses -the same catalog and privacy scrubbing. It does not install an exporter, read FI keys, -apply fi-core TraceConfig, propagate OTel context, or provide Node's suppression/dedup -layer: the adapter must supply those policies. Real Cloudflare/Vercel/Deno isolate -deployment is **unverified**. Native DecompressionStream availability is runtime-specific. +Bootstrap lists detected libraries, their status, and suggested install commands. It can also install missing instrumentors with an explicit `--install` flag; see the [CLI reference](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/CONFIGURATION.md#cli). + +### Library coverage + +The table below is generated from [`src/integrations.json`](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/src/integrations.json), the runtime registry. **Import hook** means the package registers hooks for supported target versions. **Enable entry** means automatic setup depends on the installed integration exposing its enable API. **Manual** means framework-level tracing still requires that package's explicit API; eligible underlying global-fetch calls can still be captured. + +
+All registered libraries and framework adapters + + +| Configuration name | Target library | Instrumentation package | Setup | +| --- | --- | --- | --- | +| `anthropic` | `@anthropic-ai/sdk` | `@traceai/anthropic` | Import hook | +| `bedrock` | `@aws-sdk/client-bedrock-runtime` | `@traceai/bedrock` | Import hook | +| `beeai` | `beeai-framework` | `@traceai/beeai` | Import hook | +| `cerebras` | `@cerebras/cerebras_cloud_sdk` | `@traceai/cerebras` | Import hook | +| `chromadb` | `chromadb` | `@traceai/chromadb` | Import hook | +| `claude-agent-sdk` | `@anthropic-ai/claude-agent-sdk` | `@traceai/claude-agent-sdk` | Manual | +| `codex-sdk` | `@openai/codex-sdk` | `@traceai/codex-sdk` | Manual | +| `cohere` | `cohere-ai` | `@traceai/cohere` | Import hook | +| `cursor-sdk` | `@cursor/sdk` | `@traceai/cursor-sdk` | Import hook | +| `deepseek` | `openai` | `@traceai/deepseek` | Import hook | +| `elevenlabs` | `@elevenlabs/elevenlabs-js` | `@traceai/elevenlabs` | Manual | +| `fireworks` | `openai` | `@traceai/fireworks` | Import hook | +| `genkit` | `genkit` | `@traceai/genkit` | Enable entry | +| `google-adk` | `@google/adk` | `@traceai/fi-instrumentation-google-adk` | Import hook | +| `google-genai` | `@google/generative-ai` | `@traceai/google-genai` | Import hook | +| `google-genai-sdk` | `@google/genai` | `@traceai/google-genai-sdk` | Manual | +| `groq` | `groq-sdk` | `@traceai/groq` | Import hook | +| `guardrails` | `@guardrails-ai/core` | `@traceai/guardrails` | Import hook | +| `huggingface` | `@huggingface/inference` | `@traceai/huggingface` | Import hook | +| `huggingface-transformers` | `@huggingface/transformers` | `@traceai/huggingface-transformers` | Manual | +| `instructor` | `@instructor-ai/instructor` | `@traceai/instructor` | Import hook | +| `lancedb` | `@lancedb/lancedb` | `@traceai/lancedb` | Import hook | +| `langchain` | `@langchain/core` | `@traceai/langchain` | Import hook | +| `livekit` | `livekit-client`, `@livekit/rtc-node` | `@traceai/fi-instrumentation-livekit` | Import hook | +| `llamaindex` | `llamaindex`, `@llamaindex/openai` | `@traceai/llamaindex` | Import hook | +| `mastra` | `@mastra/core`, `@mastra/observability`, `@mastra/otel-exporter` | `@traceai/mastra` | Manual | +| `mcp` | `@modelcontextprotocol/sdk` | `@traceai/mcp` | Import hook | +| `milvus` | `@zilliz/milvus2-sdk-node` | `@traceai/milvus` | Import hook | +| `mistral` | `@mistralai/mistralai` | `@traceai/mistral` | Import hook | +| `mongodb` | `mongodb` | `@traceai/mongodb` | Import hook | +| `ollama` | `ollama` | `@traceai/ollama` | Import hook | +| `openai` | `openai` | `@traceai/openai` (included) | Import hook | +| `openai-agents` | `@openai/agents` | `@traceai/openai-agents` | Import hook | +| `pgvector` | `pg`, `pgvector` | `@traceai/pgvector` | Import hook | +| `pi-coding-agent` | `@mariozechner/pi-coding-agent` | `@traceai/pi-coding-agent` | Manual | +| `pinecone` | `@pinecone-database/pinecone` | `@traceai/pinecone` | Import hook | +| `pipecat` | `@pipecat-ai/client-js` | `@traceai/fi-instrumentation-pipecat` | Import hook | +| `portkey` | `portkey-ai` | `@traceai/portkey` | Import hook | +| `qdrant` | `@qdrant/js-client-rest` | `@traceai/qdrant` | Import hook | +| `redis` | `redis` | `@traceai/redis` | Import hook | +| `strands` | `@strands-agents/sdk` | `@traceai/strands` | Import hook | +| `together` | `together-ai` | `@traceai/together` | Import hook | +| `vercel` | `ai` | `@traceai/vercel` | Enable entry | +| `vertexai` | `@google-cloud/vertexai` | `@traceai/fi-instrumentation-vertexai` | Import hook | +| `vllm` | `openai` | `@traceai/vllm` | Import hook | +| `voltagent` | `@voltagent/core` | `@traceai/voltagent` | Manual | +| `weaviate` | `weaviate-client` | `@traceai/weaviate` | Import hook | +| `xai` | `openai` | `@traceai/xai` | Import hook | + + +
+ +Dedicated instrumentors other than OpenAI are not installed implicitly. The bundled server-build adapters are inactive until you add their plugin to your build configuration. Genkit and Vercel versions without an enable entry report `manual`. Mastra is manual-only in this release. See each integration's README for supported methods and versions, and use doctor to inspect the version actually installed in your app. + +### HTTP protocol coverage + +The [wire catalog](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/src/wire/wire-protocols.json) recognizes OpenAI-compatible chat, Responses, embeddings and media endpoints; Anthropic messages; Gemini/Vertex content and embeddings; Cohere chat/embed/rerank; Bedrock converse/invoke; Ollama; and selected Deepgram, ElevenLabs, AssemblyAI and Cartesia endpoints. + +Recognition needs a matching endpoint and request shape, not just an AI-looking URL. Unknown proxy hosts can use compatible protocol fallbacks; provider-restricted endpoints still require a recognized host. Audio bytes are counted, not exported. Bedrock binary event streams are metadata-only. See [capture behavior and transport limits](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/ARCHITECTURE.md). + +## Privacy defaults + +| Surface | Default behavior | Your control | +| --- | --- | --- | +| Prompts, model outputs, tool content and transcripts | Captured where supported | `FI_HIDE_INPUTS=true`, `FI_HIDE_OUTPUTS=true`; granular message/text flags are available | +| Error details | Visible unless an input/output value, message, text or invocation-parameter hide flag implies hiding | `FI_HIDE_ERROR_DETAILS=true`; explicit `false` overrides the derived value, not secret/media masking | +| Known credentials and signed URL values | Scrubbed in traceAI's export view | Additional exact secrets can be registered with `registerSecret()`; never rely on this to detect arbitrary free-text secrets | +| PII pattern redaction | **Off** | `FI_PII_REDACTION=true`; pattern matching is not comprehensive PII detection | +| Base64 media and raw audio | Recognized payloads omitted; no audio bytes exported | Image cap defaults to `0`; increasing it does not enable base64 image export | +| Embeddings | Catalog wire formats record dimensions, not vectors | `FI_HIDE_EMBEDDING_VECTORS=true` also hides vectors on library/forwarded and generic-JSON routes | +| Extra instrumentors / server bundler plugins | Extra instrumentors are not installed; build plugins are inactive until configured | Install the integration or explicitly add a server bundler plugin | + +The agent sanitizes a detached copy for its own exporter. **Other exporters retain their own privacy policies.** Explicit application-owned processors are not silently rewritten. Host SDK limits may force the FI view to withhold content as `` rather than export a partial value. Unknown, transformed or unobserved secrets cannot always be recognized; use the hide flags for sensitive content. + +[All privacy flags and defaults](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/CONFIGURATION.md#privacy-options) · [Detailed privacy boundaries](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/ARCHITECTURE.md#privacy) ## Configuration -Precedence: code options > environment > config file > defaults. Code uses camelCase -(`projectName`, `wireCapture`, `sampleRate`, `instrumentations`, etc.); privacy flags -are under `traceConfig`. `exporter` is an optional SpanExporter override for embedding -or offline testing. It does not bypass the credential requirement. +The most-used settings are below. Set them **before** loading the agent; later `init()` calls do not reconfigure it. -| Environment | Default / meaning | +| Environment variable | Default | Purpose | +| --- | --- | --- | +| `FI_API_KEY` + `FI_SECRET_KEY` | Unset | Complete pair for the default Future AGI destination | +| `FI_PROJECT_NAME` | See full reference | Project in Observe; set explicitly for stable routing | +| `FI_BASE_URL` | `https://api.futureagi.com` | Collector base URL or full traces endpoint | +| `FI_INSTRUMENTATIONS` | All eligible integrations | Comma-separated allowlist, e.g. `openai,wire` | +| `FI_DISABLED_INSTRUMENTATIONS` | Empty | Denylist; takes precedence over the allowlist | +| `FI_WIRE_CAPTURE` | `true` | Enable global-fetch capture and transport credential observation | +| `FI_SAMPLE_RATE` | `1` | Root sampling ratio on agent-owned providers; existing providers keep their sampler | +| `FI_AUTO_DEBUG` | `false` | Print the masked startup report | +| `OTEL_SDK_DISABLED` | `false` | Disable auto-instrumentation | + +[Full configuration reference](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/CONFIGURATION.md) covers every `init()` option, environment setting, config/profile precedence, privacy flag and CLI command. + +## Frameworks and deployment + +| Environment | Start here | | --- | --- | -| `FI_API_KEY`, `FI_SECRET_KEY` | Complete pair required for the default FI destination only; prefer environment, never commit keys | -| `FI_BASE_URL` | `https://api.futureagi.com`; FI collector base or full endpoint | -| `FI_PROJECT_NAME` | `OTEL_SERVICE_NAME`, else working-directory name, else `DEFAULT_PROJECT_NAME` | -| `FI_PROJECT_TYPE` | `observe`; `experiment` is opt-in | -| `FI_INSTRUMENTATIONS` | All; comma-separated allowlist, e.g. `openai,langchain,wire,http` | -| `FI_DISABLED_INSTRUMENTATIONS` | Empty; denylist wins over allowlist | -| `FI_WIRE_CAPTURE` | `true` | -| `FI_WIRE_MAX_BODY_BYTES` | `4194304`; per request/response text buffering cap | -| `FI_SAMPLE_RATE` | `1`; clamped to [0,1], parent-based root sampling for agent-owned providers | -| `FI_AUTO_DEBUG` | `false`; print masked startup report | -| `FI_CONFIG_FILE` | `./futureagi.toml` | -| `OTEL_SDK_DISABLED` | `true` disables everything silently | - -Example `futureagi.toml`: - -```toml -project_name = "checkout-agent" -project_type = "observe" -instrumentations = ["openai", "langchain", "wire", "http"] -disabled_instrumentations = ["redis"] -wire_capture = true -wire_max_body_bytes = 4194304 -sample_rate = 0.25 -debug = false -hide_inputs = true -``` +| Node ESM or CommonJS | Use `--import` before app imports; CommonJS also supports `--require` | +| Next.js Node runtime | Use guarded `instrumentation.ts` and keep the package external; do not import it into an edge path | +| esbuild, Vite SSR, Rollup or webpack | Opt into the Node-server adapter and deploy the complete agent payload; keep AI SDKs external for library hooks | +| AWS Lambda | Initialize once outside the handler and flush at each invocation boundary, not just process exit | +| Edge / browser | The Node preload is not supported. The `/edge` subpath is a low-level fetch observer, not a configured tracing SDK | +| Existing OpenTelemetry setup | Keep one global provider; configure a single export route for each destination | -This is a flat subset, not full TOML: double-quoted strings, booleans, numbers and -single-line arrays of strings. Comments are supported, including `#` inside quoted -strings. Table declaration lines are ignored. Unknown/unsupported values are ignored. -File keys map to `FI_`; `debug` maps to `FI_AUTO_DEBUG`. +[Framework recipes and packaging requirements](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/FRAMEWORKS.md) -## Doctor, bootstrap and statuses +## Troubleshooting + +Run diagnostics from the app directory with the same FI environment as the app: ```sh -traceai-auto doctor # sends one explicit test export when enabled -traceai-auto doctor --no-check # no test export; reports resolved config/status -traceai-auto bootstrap # list coverage and suggested install commands only -traceai-auto bootstrap --install --package-manager=pnpm # explicit opt-in installation +npx --no-install traceai-auto doctor ``` -Bootstrap defaults to npm when `--package-manager` is omitted; npm/pnpm/yarn are -supported. It never installs target application libraries, only missing instrumentors -for detected targets. Restart the app after installing packages. The installation -branch is implemented but is not exercised against the public registry in tests. - -Reports are JSON, with masked credentials and collector state (`accepted`, `failed`, -or `not_tested`). Startup never probes the collector. With zero sampling, doctor may -have no sampled test span to send; `not_tested` is intentional in that case. - -- `instrumented`: wire hook, server hook, or a library module's patch callback ran. -- `pending`: hooks registered, but no compatible target patch observed yet. -- `not_installed`: no resolvable target library. -- `missing_instrumentor`: target is present but its dedicated package is absent. -- `disabled`: allowlist/denylist, credentials, capture flag, or SDK disable switch. -- `manual`: installed target needs explicit wrapping/callbacks; reason included. -- `failed`: load, registration, patch or known unsupported-version failure; reason included. - -### SDK attribute limits and streaming timing - -In **auto destination mode**, host SDK count/value limits govern native admission. -FI does not clear native attribute storage, re-order it for FI projection, or replay -earlier attributes over later application writes. FI-authored values are protected -before admission; the FI snapshot is built only at export with a late-secret recheck. -Late output or usage dropped by the host is not recovered. Absent optional usage -details are omitted rather than converted to the string `"undefined"`. - -Observed host-dropped attributes, events or links, strings at the configured value -limit (including exact equality), string arrays containing such a value, and -explicit `` / `[truncated]` suffixes trigger lineage-wide withholding. -Every FI content surface becomes ``; `session.id` stays -``, and `traceai.capture.host_data_unknown=true` marks every FI view. -Native SDK dropped counts are retained. Only a closed, typed non-content allowlist -is exempt from withholding, never from secret masking. The decision is sticky for -the native span and identity-retaining mapped/copied FI views, including later views. -There is no partial FI content view or content-derived prefix, length or digest. -Truncated MIME values never establish safe text. Values exported before a loss was -observed are not retracted; already returned snapshots are not mutated retroactively. - -Explicit standalone `FITracer` retains deterministic pre-admission projection -(spec A7), including late library output/usage priority, atomic content groups, -`traceai.capture.dropped_content_count`, and the separate SDK dropped count. -The former `traceai.attribute_projection.metadata` capsule is not produced; older -capsules are still re-sanitized by original keys at export. Host limits are not -raised in either mode. The auto interim is not a guarantee of complete capture or -of retaining canonical output at small host limits. - -`gen_ai.response.time_to_first_chunk` measures the first observed response bytes; -`gen_ai.response.time_to_first_text` separately measures the first nonempty -text/reasoning/tool/audio delta. `traceai.stream.event_arrival_seconds` records event -arrival offsets from request handoff, using byte-boundary timestamps rather than -parse completion time. Content detection includes Cohere tool chunks/reasoning, -nested Mistral content, Responses tool/code deltas, model-requested server/MCP tools -and Gemini executable code. Successful NDJSON EOF accepts a complete final JSON -record without a newline; interrupted or capture-truncated tails still require the -record delimiter, and partial JSON is never promoted to a completed frame. - -## Known limitations - -- **2026-11-05 (Q9 no auto-mode projection; Q8b):** In auto destination mode, - a span whose attributes exceed the host attribute count limit exports the - value-free `` marker for FI content once the host drop - is observed. FI does not project or reconstruct a partial content view. The same - withholding applies to names, status, resource/scope, events and links throughout - the identity-retaining lineage; `session.id` stays `` and every FI view - carries `traceai.capture.host_data_unknown=true`. A closed typed non-content - allowlist retains only its validated values, still subject to secret masking. - Values exported before a loss was observed are not retracted (Q8b residual). - Exact equality with an observed value limit is uncertain too. Native host spans - and unrelated exporters are unchanged by this export-time policy. This is not - complete capture; larger host limits reduce omissions but do not guarantee it. - To keep FI content on spans with many attributes, raise the standard - OpenTelemetry limit `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` (or `OTEL_ATTRIBUTE_COUNT_LIMIT`); - the OpenTelemetry default is 128. -- **2026-10-31 (lossy media context; updated by Q8b):** Observed SDK loss now - withholds all FI content, including ordinary text, base64, embedded/nested JSON, - URL queries and error prose, with the generic unknown marker rather than a - content-derived media-length marker. Malformed JSON tails still fail closed. - Auto records native limit and value-free loss facts before mapping; copied spans - retaining that lineage withhold all non-NON_CONTENT values rather than exporting - a mapper-shortened prefix. Native spans and host exporters - are unchanged by this export policy. Copies without source evidence consult global - SDK limits before environment settings; an unrelated global provider can cause - over-omission. Custom processors that erase identity, limits and loss evidence - can still hide loss. Use `FI_HIDE_INPUTS` / `FI_HIDE_OUTPUTS` / - `FI_HIDE_ERROR_DETAILS` for such routes; no lossless guarantee is made. -- **2026-10-31 (unterminated quoted prose; updated by I1 C3):** Detected SDK - truncation is now withheld before prose parsing. An upstream cut with no marker - or observable SDK limit remains ambiguous: free text with no enclosing JSON, - such as quoted `data`/`mimeType` after `upload failed:`, may lack the closing - delimiter needed by structural recognition. Complete long `data` values retain - catalog omission. Use `FI_HIDE_ERROR_DETAILS` for errors and `FI_HIDE_INPUTS` / - `FI_HIDE_OUTPUTS` for captured input/output prose. -- **2026-10-31 (credential prefixes; updated by I1 C3):** Exact registered-secret - matching does not recognize every unknown prefix. The FI view withholds detected - host-truncated content before that check, including span/event/link detail. - Native foreign spans intentionally keep their original bytes. Upstream/custom - truncation that erases all loss evidence is still not guaranteed detectable; - use FI hide controls and register complete credentials before authored writes. -- **2026-11-04 (option (ii), Mastra manual-only at 11-11):** This tree retains the - manual `@traceai/mastra` package from #567. Use `createFIObservability` or - `createFIMastraExporter`; the registry has no Mastra enable hook and does not - resolve an `/auto` export. The zero-code bridge follows after 11-11. The earlier - unreleased neutral-adapter note and its credential-free/partial-pair zero-code - claims do not describe this tree. No zero-code Mastra support or validation is claimed. -- **2026-10-30 (stream timing bounds):** Timing retains at most 4096 transport byte - boundaries/events. The audio byte-count path retains at most 64 KiB of timing - prefix; missing later event timings are not fabricated. Compressed custom fetch - responses without runtime decoding cannot map compressed offsets onto decoded - events. These cases set `traceai.wire.timing_incomplete`; first-chunk timing remains - available. Response content capture limits and opaque/pipe limitations still apply. -- **2026-11-05 (Q9 supersedes auto-mode A7 small-limit projection):** The host - SDK decides which native attributes it admits; FI does not reorder or reserve - auto-mode slots for output, provenance or usage. Once any host loss is observed, - Q8b withholds FI content for the lineage even when some native content survived. - A default limit such as 128 is not a promise that output survives a larger span. - Explicit standalone `FITracer` projection is separate and remains supported. - -Dated **2026-10-30**. These are coverage/environment limitations, not claims of -universal instrumentation support. - -- **2026-10-30 (S6 recognition):** Media and credential recognition follow the shared - `privacy.json` catalog, not semantic inference. With complete SDK context, unknown, - non-magic base64 outside its payload fields is not classified as media. Exact scalar data URIs own their - complete value; URIs inside prose are delimiter-scanned. Catalog depth/node/text - exhaustion fails closed, retaining span identity/timing rather than partial content. - Use the `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS` and `FI_HIDE_ERROR_DETAILS` controls - when application content requires stronger protection than structural recognition. -- **2026-10-30 (configuration):** Config/profile parsing supports flat scalar values - and string arrays, plus named `[profiles.name]` sections in `.fi/config.toml` and - `$XDG_CONFIG_HOME/fi/config.toml` (default `~/.config/fi/config.toml`). Multiline - TOML and arbitrary TOML expressions are not supported. Credential pairs resolve - atomically: explicit arguments, environment, `futureagi.toml`, fi project profile, - then fi user profile; incomplete sources are ignored with a value-free warning - naming the missing half. Ignored FI halves from every source still seed S5 and - cannot appear in diagnostics. `FI_PROFILE`/the `profile` option selects the profile. -- **2026-10-30 (ROUND5 B2 scope; zero-code/one-line init):** Credentials that never cross an instrumented - transport and have no credential marker cannot be inferred from free text. Opaque - `Request`/stream bodies are never parsed or buffered; a body-only credential echoed - as plain text can therefore remain unknown when it is neither an environment/FI - value nor explicitly registered. This includes `authorization_token` inside a native - `Request` or `ReadableStream` body; the original credential-bearing application 401 - remains unchanged. Those unparsed fields are outside ROUND5 B2's parsed-body scope. - Materialized `URLSearchParams` and native FormData text entries are harvested - before capture limits, including duplicate fields; opaque pre-encoded form strings - are not form-decoded. Suppressed calls observe headers/URL only, never bodies. - Application transformations (signature extraction, JSON encoded inside - strings, numeric re-typing, base64 or splitting) are not a general secret-detection - guarantee. Use `registerSecret` for additional exact values and the `FI_HIDE_INPUTS`, - `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_TEXT`, `FI_HIDE_OUTPUT_TEXT` and - `FI_HIDE_ERROR_DETAILS` controls for sensitive content/error surfaces. -- **2026-10-30:** One-line/manual instrumentation with transport hooks disabled has - only initialization FI/environment seeds and explicit registrations; credentials - never observed by those hooks are not automatically known. The bounded LRU can - evict old values after 1024 distinct credentials; re-register long-lived values - when reused. The same hide controls above remain available. -- **2026-10-30:** Transport credential-discovery exhaustion (more than 1024 distinct - values in one observation, excessive nesting/nodes/text or an already-materialized - body over the 4 MiB discovery cap) fails closed process-wide: subsequent FI spans - keep identity/timing but drop content on every surface. Application requests, - responses and other exporters are unchanged. This latch lasts until process restart; - it cannot safely be reset while unknown credentials could still be echoed. Ordinary - credentials longer than 8192 characters are supported within the aggregate budgets. -- **2026-10-30:** Unnamed in-memory esbuild ESM output (`write:false` without - `outfile`/`outdir`) is left byte-identical to the no-plugin build: there is no - deployable sibling path for the ESM bootstrap. Use an output path or external - `node --require` preload for instrumentation. Unnamed CJS/default outputs receive - their preload in memory, with no filesystem output access. Custom JavaScript output - extensions are supported for named CJS and ESM outputs. -- **2026-10-30 (zero-code/one-line init):** Cancelling an unused clone can finalize the shared capture before the original - branch is consumed. Cancelling a released reader can likewise finalize capture - even when the native cancellation promise rejects. Application bytes, promises - and errors remain unchanged, but the one span can be incomplete, omit later output/ - usage and end too early. These two cases were independently reproduced even when - later consumption returns the complete answer and usage. Branch-aware cancellation - finalization is deferred. -- **2026-10-30 (zero-code/one-line init):** A provider failure carried inside an HTTP 200 stream (for example OpenAI Responses - `response.failed`) can retain HTTP-derived OK status without the provider error - description, even when `gen_ai.response.finish_reasons` records `failed`. HTTP - success is not currently overridden by that in-stream provider failure. -- Native `pipeTo`/`pipeThrough` algorithms bypass instance reader methods. These - paths retain metadata-only completion (`traceai.wire.body_unavailable=true`), - without replacing the stream/sink or fabricating output bytes. Their completion - timing is the pipe/downstream completion, not a byte-level transport timestamp. - Directly borrowing prototype methods, or freezing/non-configurably replacing - custom stream methods, can bypass observation entirely. Native Response helpers - and ordinary readers/iterators/clone/tee have byte-level regression coverage. -- Custom lazy/non-native thenables are not a validated Node fetch implementation; - the Node observer does not invoke their overridden `then` to start them. Node's - observer uses V8 promise-parent notifications and native rejection mirrors to - preserve unhandled/handled rejection events and default fatal exits for ordinary - fetch/read promises. Pre-created custom promises consumed before agent startup - are not fully observable. The Node-free edge adapter lacks that Node-specific - rejection-lifecycle mechanism and is not a drop-in process agent. -- An SDK without a processor-removal API can retain one inert agent processor after - shutdown. Agent callbacks stop, application processors remain active, and init does - not add another processor. Optional enable entries own their integration's hook - cleanup when they do not return a disable handle. -- Covered ancestry traversal is bounded to 256 wrapper/native ancestors; esbuild glob - expansion is bounded to 10,000 filesystem entries and 64 recursive directory levels. - -- No outgoing **wire spans** for `node:http`/`node:https`, direct `undici.fetch`/ - `undici.request`, custom fetch implementations captured before preload, WebSocket, - native gRPC, worker processes, browsers or arbitrary non-fetch transports. HTTP/ - Undici diagnostics do harvest credentials independently of span creation. Preload - each separate Node process and worker isolate (globals/registries are not shared - across V8 isolates). OpenAI's included dedicated instrumentation covers its - supported default transport; the global fetch wire hook does not cover node-fetch. -- URL matching is limited to the catalog. Restricted-provider endpoints on a custom - proxy host may not match. No speculative interception of unknown AI protocols. -- Request objects and opaque/pre-encoded multipart streams are never cloned/read; - known provider endpoints retain metadata/body-unavailable capture only. Use native - FormData for text fields and file metadata. Binary request sizes are included only - when the body or declared content length exposes the size. -- A response must be consumed or cancelled to finish capture. Unread or never-ending - responses do not yield completed spans. Force-flush never waits for unread responses. -- Bedrock binary event-stream responses record request/status only. Audio streaming - and base64 variants count bytes but do not reconstruct audio/timestamps. No audio - bytes are exported. -- Real OpenAI calls, real Agents processor coexistence and real Cursor class ownership - are validated here; registry completeness does not imply every one of the 45 - packages works with every version. Optional enable-entry registry tests validate - the adapter contract, not each external framework deployment. Instrumentations - depending on obsolete module paths may remain pending. +Doctor sends one test span when instrumentation is enabled. Check the JSON `collector` field: `accepted`, `failed` or `not_tested (...)`. **The CLI exit code alone is not a collector-health check.** Doctor is a separate process, so its `pending` library hooks do not tell you whether your running app has imported that library. -## Legal notices +For a configuration/status report without the test export: -The published package includes `dist/THIRD-PARTY-NOTICES`, with the full installed -LICENSE, LICENCE, COPYING and NOTICE files for third-party inputs to all four -launcher/edge bundles. `dist/third-party-manifest.json` maps each bundle to its -third-party package names and versions; first-party `@traceai/*` packages are listed -separately in the notices. These files supplement, and do not replace, the existing -linked `.LEGAL.txt` output. Keep them with any redistributed launcher or edge payload. -The build fails if a bundled third-party package has no readable, nonempty license -text file; a license identifier or linked source comment alone is not sufficient. +```sh +npx --no-install traceai-auto doctor --no-check +``` -## Development and verification +| Symptom | What to check | +| --- | --- | +| Everything is `disabled` | Supply both FI keys in the same source, or configure an application destination. Check `OTEL_SDK_DISABLED` and the allowlist/denylist. | +| `collector: failed` | Check `FI_BASE_URL`, both keys, outbound connectivity and collector access. Initialization itself never probes the collector. | +| `collector: not_tested` | No completed test export yet, `--no-check`, zero sampling, or an application-owned destination. It is not a success signal. | +| `missing_instrumentor` | Install the suggested dedicated package from bootstrap, then restart. | +| Library stays `pending` | Load the agent before the SDK; check supported versions and keep the SDK external when bundling. A registered hook is not proof a call was traced. | +| Library reports `manual` | Use its explicit wrapper/processor API; automatic framework-level tracing is unavailable for that installed version. | +| No wire span | Consume or cancel the response; check the catalog and transport. Direct `undici.fetch`, `node-fetch`, WebSocket and gRPC are not global-fetch wire capture. | +| Output is missing or unknown | Check hide flags, body cap and host OTel attribute limits. Dropped/truncated host data cannot be reconstructed. | +| Duplicate spans | Remove duplicate manual instrumentation/preloads; avoid layering an invocation wrapper over another Lambda tracing layer. | + +## Limits to plan for + +- **Per process/isolate:** preload every Node worker or child process you want to observe; globals are not shared between isolates. +- **Bounded capture:** the default text body cap is 4 MiB. Request streams and opaque `Request` bodies are not consumed for inspection. Native `pipeTo`/`pipeThrough` can provide metadata-only completion. +- **Response-driven completion:** unread and never-ending responses do not produce completed wire spans. Flush does not consume them for you. Cancelling a clone can end the shared capture before another branch finishes. +- **Provider error semantics:** an error inside an HTTP 200 stream can retain HTTP-derived OK status; inspect finish reasons as well. +- **Best-effort delivery:** natural-exit/SIGTERM flushes are bounded. Hard termination, Lambda freezing and collector failures can lose spans. The agent never makes app success depend on export success. + +[Architecture, complete capture limits and redistribution notices](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/ARCHITECTURE.md) -From `typescript/`: +## Legal notices -```sh -pnpm install --ignore-scripts -pnpm run build:deps -pnpm --filter @traceai/auto run build # TS references build OpenAI and Anthropic CJS prerequisites -pnpm --filter @traceai/auto test -pnpm --filter @traceai/fi-core test --runInBand -``` +Keep `dist/THIRD-PARTY-NOTICES`, `dist/third-party-manifest.json` and the linked `.LEGAL.txt` files with any redistributed launcher or edge payload. [Redistribution details](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/traceai_auto/docs/ARCHITECTURE.md#legal-notices). + +## More resources -The agent builder requires the resolved OpenAI instrumentor to appear in esbuild's -input graph and fails the build if it is missing; it cannot silently produce a -wire-only launcher after an `--ignore-scripts` install. - -Tests load **all 4,985 shared S6 privacy fixtures** and discover the wire goldens -**recursively** under `spec/auto-instrumentation/fixtures/` (340 on 2026-11-01: 47 -baseline + 293 round6 A8/A10 files, replayed with their `chunk_sizes`, -`error_after_chunks` and per-chunk `arrival_offsets_ms`; the ten decoded-payload -Bedrock files 157-166 go to the A10 recognizer, not the wire endpoint, per the spec), -including unavailable requests, encoded gzip responses and mid-stream failures; they -assert names/status descriptions/exact attribute subsets, absence/presence and -`not_contains` privacy expectations, and compare catalog bytes. Local mock-server e2e tests spawn real Node `--import`, `-r`, and -NODE_OPTIONS entry points, using a local OTLP collector rather than Future AGI or a -real AI provider. Other tests cover body caps, nesting/suppression, binary/BYOB/audio, -configuration precedence, privacy, global SDK coexistence and incoming transactions. +[Future AGI tracing guide](https://docs.futureagi.com/docs/tracing) · [Integration guides](https://docs.futureagi.com/docs/integrations/traceai) · [Manual TypeScript SDK](https://github.com/future-agi/traceAI/blob/dev/typescript/packages/fi-core/README.md) · [Report an issue](https://github.com/future-agi/traceAI/issues) diff --git a/typescript/packages/traceai_auto/docs/ARCHITECTURE.md b/typescript/packages/traceai_auto/docs/ARCHITECTURE.md new file mode 100644 index 000000000..0ad7e2786 --- /dev/null +++ b/typescript/packages/traceai_auto/docs/ARCHITECTURE.md @@ -0,0 +1,474 @@ +# Capture architecture + +[Quick start](../README.md) · [Configuration](CONFIGURATION.md) · [Framework recipes](FRAMEWORKS.md) + +This reference describes the Node agent’s capture, privacy and lifecycle boundaries. For setup, start with the quick start. + +## Initialization and ownership + +`init(options)` configures the process **once**. It retains the existing provider, +configuration and hooks on every later call, logging one diagnostic line. It returns +the **same tracer provider object**, or `undefined` when initialization is disabled or +failed. Diagnostics are returned by `report()`, not `init()`. Other exports are +`forceFlush(): Promise`, `shutdown(): Promise`, and +`registerSecret(value: unknown): void` (also exported additively by `@traceai/fi-core`). +Integrations can register credentials observed outside a transport without supplying +span context or retaining per-trace credential groups. Non-string values and strings +shorter than eight characters are ignored; registration never coerces user objects. +Shutdown removes this agent's hooks/processors but never shuts down an +application-owned global OTel provider. Reinitialization after shutdown or failed +startup, changing privacy/exporter settings, and disabling an enabled integration +by calling `init()` again are unsupported: restart the process to change configuration. +For short-lived programs, finish reading responses, then `await forceFlush()` or +`await shutdown()`. + +The preload does not perform network I/O. The first real completed span initiates +a bounded batch export, or `doctor` can explicitly send a test span. FI credentials +are required only for the default FI destination. `init({ exporter })`, +`init({ spanProcessor })`, `init({ provider })`, or an existing application OTel provider +activates instrumentation without FI credentials and without creating an FI export route. +With neither a destination nor a complete FI pair, both layers are disabled with one warning. +FI project routing never replaces application `service.name` or environment resource +identity. Export/integration failures warn once per +failure category, do not log credentials/provider bodies, and leave the app running. +A one-shot `beforeExit` handler flushes completed spans. The agent adds no SIGINT +handler. Its SIGTERM listener starts a bounded flush and preserves app-owned listeners; +without one, it restores the default action and re-raises SIGTERM (preserving the signal +exit). Explicit flush/shutdown have a five-second deadline. Shutdown reserves up to +2.5 seconds for flush and then invokes exporter shutdown with the remaining 2.5 seconds, +even if flush never resolves. A failed initialization rolls back this agent's hooks, +processor and newly installed globals; app-owned globals are retained. The first +configuration remains terminal, so a later `init()` cannot retry or rewire the +process. SIGKILL/forced termination cannot guarantee delivery. + +## Capture layers + +### Wire layer + +The runtime reads a byte-identical packaged copy of the shared +`spec/auto-instrumentation/wire-protocols.json` catalog. It patches `globalThis.fetch`, +preserving the fetch function's name, length and custom properties via a Proxy. + +Recognized formats include: + +- OpenAI-compatible chat/completions, Responses, embeddings, image generation, + moderation, transcription/translation and speech generation; compatible gateways + and providers are recognized by the catalog. Unknown hosts use the endpoint's + protocol-specific fallback (`openai_compatible`, `anthropic_compatible`, + `gemini_compatible`, or `cohere_compatible`). +- Anthropic messages, Gemini/Vertex generate-content and embeddings, Cohere chat, + embed and rerank, Bedrock converse/invoke, Ollama chat/generate/embed. +- Deepgram listen/speak, ElevenLabs TTS/STT, AssemblyAI transcript submission and + completed polling, and Cartesia bytes/SSE TTS. + +Request-body validation prevents unrelated application endpoints from being claimed. +Request streams, opaque Request objects and over-limit bodies are captured **only for +catalog providers**, without request content and with `traceai.wire.body_unavailable` +or `traceai.wire.truncated`. Unknown proxies need a validated materialized request. +The actual fetch is invoked before inspecting materialized bodies: no request cloning, +stream read-ahead or request-side wait is added. + +Wire spans are OTel CLIENT spans with the saved parent context. Start time is the +transport handoff, before URL validation or request inspection; end time is the last +observed byte/error, captured **before** copying, decoding or parsing. Parsing is +excluded from duration. Streams are observed by tapping the existing readers and +iterators, not by replacing the body. The caller receives the **original fetch +Promise and original Response**, including subclass/helper methods and native headers, +URL/type, clone, tee, BYOB support (or its original rejection), cancellation promises, +and chunk identities. Capture copies bytes into its own bounded buffers without +transferring/detaching app storage. No read, reader lock, synthetic Response, automatic +clone or eager tee is created for an unread body. Export is never awaited between +chunks; reading multiple clone/tee branches produces at most one wire span. + +Text/JSON/SSE/NDJSON capture stops at the configured byte cap, discards buffered +content, and sets `traceai.wire.truncated`. Audio/binary responses are counted, not +buffered. JSON/SSE TTS base64 audio is counted with a bounded streaming scanner, +without accumulating or decoding audio. If a custom fetch exposes compressed JSON/SSE +TTS bytes, the compressed capture is bounded by the body cap and decoded asynchronously +after consumption; decoded chunks go straight to that scanner, not a retained audio +buffer. The decoded-work cap also applies; exceeding it sets `traceai.wire.truncated`. +FormData text fields are read independently +of upload size, each capped at 64 KiB; file bytes are never read, and only their +size/MIME/filename are retained. Catalog embedding formats record dimensions, not +vectors. Use `traceConfig.hideEmbeddingVectors` (or `FI_HIDE_EMBEDDING_VECTORS=true`) +to also hide vectors in generic JSON fallbacks and forwarded library/application spans. + +Native fetch normally decompresses responses. When a custom fetch exposes encoded +bytes, bounded asynchronous Node decoders handle gzip/deflate/Brotli before parsing, +plus zstd when Node exposes it. The Node-free layer uses Web `DecompressionStream` +for the codecs its runtime supports. Unavailable decoders +keep request-side metadata and set `traceai.wire.undecoded_encoding`. Already-decoded +JSON/SSE is not decoded twice. A transport failure mid-stream is ERROR with parsed +partial output; consumer cancellation is OK with `traceai.wire.incomplete = true`. + +Wire **span creation** is skipped for OTel-suppressed contexts, nested captures, and +LLM/EMBEDDING/RERANKER/GUARDRAIL ancestors, even through intermediate native SDK +spans. Outgoing credential observation is never skipped by these rules: fetch reads +headers/URL without inspecting suppressed request bodies. Node HTTP and Undici +diagnostic-channel subscribers also observe outgoing headers/URLs (including direct, +cached clients and non-AI routes); they do not create additional wire spans. The FI processor keeps weak live ancestry, so a model kind set after span +creation is also respected. Both `gen_ai.span.kind` and older `fi.span.kind` are +understood, including FI-wrapped spans. Uncovered CHAIN/AGENT/TOOL spans remain +eligible parents. Session, user and other fi-core context attributes are propagated. + +Wire attributes pass through fi-core's TraceConfig. Additional conservative handling +covers flattened message keys, audio transcripts, and raw body copies when content +hiding is enabled. `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_MESSAGES`, +`FI_HIDE_OUTPUT_MESSAGES`, `FI_HIDE_INPUT_TEXT`, `FI_HIDE_OUTPUT_TEXT`, +`FI_HIDE_INPUT_IMAGES`, `FI_HIDE_ERROR_DETAILS`, and `FI_PII_REDACTION` are supported. +TTS `gen_ai.audio.transcript` obeys input-hide flags; STT obeys output-hide flags. +Hidden transcripts use `[REDACTED]`, exactly like hidden input/output values. + +### Privacy + +One export-time boundary sanitizes **every span sent through the agent's exporter**: +wire spans, dedicated-library spans and forwarded application spans. It builds a +detached snapshot of the ended native span; other exporters keep the original +span/resource/context unchanged by that export policy. In auto destination mode, +foreign attributes are never rewritten by FI policy. FI-authored attributes still +receive write-time hide flags, image caps, PII and known-secret protection, so +other exporters never receive authored content that those protections hid. +Application active context uses the native span; instrumentor writes use a separate +FI wrapper. Explicit standalone `FITracer` retains its active-wrapper behavior. +This is an **interim export-built view**, not complete capture: data the host SDK +already dropped or truncated may be omitted or marked unknown, never reconstructed. +Attributes (arrays element-wise), status descriptions, event names/attributes, +link attributes/contexts, resources, instrumentation scope name/version/attributes +and tracestate values all pass through this boundary. Nonfinite numbers become +`"NaN"`, `"Infinity"` or `"-Infinity"`. Unsupported attribute objects become type +names; user attribute getters, `toString` and `toJSON` are never called. The standard +ReadableSpan context method is supported for library-generated snapshots. + +Work is bounded across each snapshot (20,000 values, 8 MiB text, 32 array levels; +credential discovery also has depth/count limits). On a sanitizer error, content, +status descriptions, events, links, scope and resource content are dropped for that +span while its identity and timing survive. Upstream wire scrubbing is best-effort, +not the security boundary. Before TraceConfig masking, every recorded string is +scrubbed: + +- Data URLs and long base64 media fields (`data`, `bytes`, `b64_json`, `file_data`, + `audio_base64`, `images` elements) become ``. Image-generation + `b64_json` uses the format contract's `` placeholder. Raw audio is + never retained, even for tiny inline audio clips: scalar/array `audio` and + `input_audio` JSON leaves, indexed flattened fields and `inlineData.data.0` with + a sibling audio MIME type all use the same no-minimum-size audio policy. + MIME metadata and transcripts remain subject to their own content-hide controls. +- Credential-named keys are replaced with `` recursively, including + `authorization_token` in MCP server settings. The only logprob-name exception + is the explicitly bound provider-root policy below; access-key identifiers + remain masked. Catalog credential shapes are checked independently of names. +- Signed URL parameters, including AWS/GCP signatures and Azure SAS fields, have their + values replaced with ``, including percent-encoded parameter names. +- A single `globalThis[Symbol.for('traceai.secrets')]` registry is shared by installed, + embedded, CJS and ESM package copies in the process/isolate. It retains at most 1024 + values of eight or more characters, evicting the least recently registered/observed + value. Immutable longest-first snapshots are cached until membership changes. At + initialization it is seeded with configured FI keys and credential-like environment + values (names containing KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL or AUTH). + Transport-observed header/query values, parsed credential fields and explicit + `registerSecret` calls augment it. Every exported span, including application-owned + instrumentation spans and unrelated/later traces, uses the current registry at + export time; there is no span-start credential inheritance or SDK-state inspection. + Credential headers and export-boundary credential fields use one shared list, + including `x-goog-api-key`, `anthropic-api-key` and `ocp-apim-subscription-key`. + Values never appear in diagnostics, reports or error messages. Every registered + value is removed from every exported string, including names, status, events, + links, resource/scope attributes and tracestate; other exporters remain unchanged. + Materialized bodies discarded by the capture cap, URLSearchParams values and + uncropped/duplicate FormData text fields still undergo bounded credential discovery + before disposal. File bytes are never inspected. Credential-discovery budget + exhaustion or failure while inspecting a materialized body drops all exported + content, not span identity, timing or status code; this also omits the truncation + marker on that fail-closed snapshot. Opaque, unparsed bodies instead follow the + scoped limitation below; their observable headers/URL still augment the registry. + Configured FI keys remain protected by the export policy even after LRU churn. + +For the closed, versioned `logprob_tokens` catalog paths, **logprob tokens are checked against registered secrets and credential shapes, not key-name rules**. +This exception is available only from the parsed OpenAI chat response root at the +instrumentation handoff: `choices[*].logprobs.content[*].token` and +`choices[*].logprobs.content[*].top_logprobs[*].token`. It does not apply to nested +JSON in user content, tool output, arbitrary attributes, or flattened key names. +If value masking changes any choice's `message.content` or `delta.content`, its +**entire logprobs block** is masked, including alternatives and byte arrays. +Buffered streaming responses are scanned by choice index before export; once a +choice is masked, earlier buffered blocks and all later blocks for that choice +are masked too. Concatenated deltas are checked for split secrets, and affected +delta text is masked. A masked individual token also loses its byte-array alias. +The staged OpenAI instrumentor exports the buffered response once, not each delta. +Other provider structures have no new exception without catalog/source evidence. + +Hide policies match semantic families, including `input.*`, `output.*`, +`gen_ai.input.*`, `gen_ai.output.*`, system instructions, tools, image/file URIs and +side-specific audio transcripts. `FI_HIDE_LLM_INVOCATION_PARAMETERS=true` additionally +hides `gen_ai.request.parameters`, explicit invocation parameters and tool schemas. +`hideEmbeddingVectors` also covers JSON fallbacks such as generic Bedrock invoke, +not only spans classified as EMBEDDING. Image hiding conservatively hides raw input +and input-message families to prevent URI aliases escaping the image policy. + +Do not put arbitrary secrets in prompts: unknown free-text secrets cannot always be +recognized. These policies cover dedicated-instrumentor spans only when they pass +through **this agent's** exporter; unrelated exporters retain their own policy. + +## Library hooks and existing providers + +Target/instrumentation resolution is from the application's working directory. +Install packages in that app and run from its directory. Hook registration is eager; +target patching occurs on import/require. The import-in-the-middle loader is registered +before `registerInstrumentations`, restricted to target entry points rather than +all ESM internals (which can break SDK shim live bindings). Node 26 currently emits +a deprecation warning for upstream `module.register()` when library hooks are enabled. +OpenAI v4/node-fetch can additionally emit +Node's upstream `punycode` deprecation. Neither warning is suppressed by the agent. +Disabled integrations are never loaded or registered, including integrations sharing +a target (for example DeepSeek and OpenAI). + +Mastra is manual-only in this release. Use `createFIObservability` or `createFIMastraExporter`; the registry does not load a Mastra auto entry. + +For Genkit and Vercel AI SDK, the registry calls an installed `enable` +entry (also accepting the integration's named enable function). It prefers the +optional `/auto` subpath. Versions without that entry are reported `manual`, not +forced into an incompatible constructor; a broken entry fails open. The entry +receives `{ tracerProvider, spanProcessor, traceConfig }` for the selected agent +branch; older no-argument entries can ignore these optional arguments and use the +initialized agent. An instrumentor returned by the entry is explicitly bound to +that provider, not an unrelated global provider. This does not replace any global +provider or synthesize FI credentials. +Manual-only integrations include Claude Agent SDK (`wrapQuery`), Codex SDK +(`wrapCodex`/`manuallyInstrument`), Pi Coding Agent (session wrapper), VoltAgent +(processor), ElevenLabs (client wrapper), Google GenAI SDK (`instrumentGoogleGenAI`) +and Hugging Face Transformers (module/pipeline wrapper). Their underlying fetch AI calls can still be traced. +Existing dedicated instrumentations retain their supported-version and method +coverage constraints; registration does not expand those APIs. OpenAI Agents uses +additive processor registration (`exclusiveProcessor:false`), preserving application +processors. Shutdown recognizes processor/class-registry ownership as well as +shimmer wrappers, and leaves application-owned patches intact. + +If `@opentelemetry/instrumentation-http` is installed and resolvable in the app, it is enabled for incoming SERVER spans only. Outgoing non-AI HTTP spans are not enabled by default. + +### Existing OTel SDKs + +An existing global SDK provider is retained, with the FI processor added beside its +existing processors. Its sampler/context manager remain authoritative. OTel JS 2.x +has no public late-add-processor API, so this uses the live MultiSpanProcessor list; +the public 1.x API is also recognized. FI project resource attributes are enriched +only on the FI export copy. If a custom provider does not expose either supported +attachment mechanism, the agent warns and uses an isolated AI provider without +replacing the global provider. This is a degraded fallback, not a promise of +processor attachment to arbitrary OTel implementations. + +## SDK attribute limits and streaming timing + +In **auto destination mode**, host SDK count/value limits govern native admission. +FI does not clear native attribute storage, re-order it for FI projection, or replay +earlier attributes over later application writes. FI-authored values are protected +before admission; the FI snapshot is built only at export with a late-secret recheck. +Late output or usage dropped by the host is not recovered. Absent optional usage +details are omitted rather than converted to the string `"undefined"`. + +Observed host-dropped attributes, events or links, strings at the configured value +limit (including exact equality), string arrays containing such a value, and +explicit `` / `[truncated]` suffixes trigger lineage-wide withholding. +Every FI content surface becomes ``; `session.id` stays +``, and `traceai.capture.host_data_unknown=true` marks every FI view. +Native SDK dropped counts are retained. Only a closed, typed non-content allowlist +is exempt from withholding, never from secret masking. The decision is sticky for +the native span and identity-retaining mapped/copied FI views, including later views. +There is no partial FI content view or content-derived prefix, length or digest. +Truncated MIME values never establish safe text. Values exported before a loss was +observed are not retracted; already returned snapshots are not mutated retroactively. + +Explicit standalone `FITracer` retains deterministic pre-admission projection +(spec A7), including late library output/usage priority, atomic content groups, +`traceai.capture.dropped_content_count`, and the separate SDK dropped count. +The former `traceai.attribute_projection.metadata` capsule is not produced; older +capsules are still re-sanitized by original keys at export. Host limits are not +raised in either mode. The auto interim is not a guarantee of complete capture or +of retaining canonical output at small host limits. + +`gen_ai.response.time_to_first_chunk` measures the first observed response bytes; +`gen_ai.response.time_to_first_text` separately measures the first nonempty +text/reasoning/tool/audio delta. `traceai.stream.event_arrival_seconds` records event +arrival offsets from request handoff, using byte-boundary timestamps rather than +parse completion time. Content detection includes Cohere tool chunks/reasoning, +nested Mistral content, Responses tool/code deltas, model-requested server/MCP tools +and Gemini executable code. Successful NDJSON EOF accepts a complete final JSON +record without a newline; interrupted or capture-truncated tails still require the +record delimiter, and partial JSON is never promoted to a completed frame. + +## Known limitations + +- In auto destination mode, + a span whose attributes exceed the host attribute count limit exports the + value-free `` marker for FI content once the host drop + is observed. FI does not project or reconstruct a partial content view. The same + withholding applies to names, status, resource/scope, events and links throughout + the identity-retaining lineage; `session.id` stays `` and every FI view + carries `traceai.capture.host_data_unknown=true`. A closed typed non-content + allowlist retains only its validated values, still subject to secret masking. + Values exported before a loss was observed are not retracted. + Exact equality with an observed value limit is uncertain too. Native host spans + and unrelated exporters are unchanged by this export-time policy. This is not + complete capture; larger host limits reduce omissions but do not guarantee it. + To keep FI content on spans with many attributes, raise the standard + OpenTelemetry limit `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` (or `OTEL_ATTRIBUTE_COUNT_LIMIT`); + the OpenTelemetry default is 128. +- Observed SDK loss now + withholds all FI content, including ordinary text, base64, embedded/nested JSON, + URL queries and error prose, with the generic unknown marker rather than a + content-derived media-length marker. Malformed JSON tails still fail closed. + Auto records native limit and value-free loss facts before mapping; copied spans + retaining that lineage withhold all non-NON_CONTENT values rather than exporting + a mapper-shortened prefix. Native spans and host exporters + are unchanged by this export policy. Copies without source evidence consult global + SDK limits before environment settings; an unrelated global provider can cause + over-omission. Custom processors that erase identity, limits and loss evidence + can still hide loss. Use `FI_HIDE_INPUTS` / `FI_HIDE_OUTPUTS` / + `FI_HIDE_ERROR_DETAILS` for such routes; no lossless guarantee is made. +- Detected SDK + truncation is now withheld before prose parsing. An upstream cut with no marker + or observable SDK limit remains ambiguous: free text with no enclosing JSON, + such as quoted `data`/`mimeType` after `upload failed:`, may lack the closing + delimiter needed by structural recognition. Complete long `data` values retain + catalog omission. Use `FI_HIDE_ERROR_DETAILS` for errors and `FI_HIDE_INPUTS` / + `FI_HIDE_OUTPUTS` for captured input/output prose. +- Exact registered-secret + matching does not recognize every unknown prefix. The FI view withholds detected + host-truncated content before that check, including span/event/link detail. + Native foreign spans intentionally keep their original bytes. Upstream/custom + truncation that erases all loss evidence is still not guaranteed detectable; + use FI hide controls and register complete credentials before authored writes. +- This tree retains the + manual `@traceai/mastra` package. Use `createFIObservability` or + `createFIMastraExporter`; the registry has no Mastra enable hook and does not + resolve an `/auto` export. No zero-code Mastra support is provided by this registry. +- Timing retains at most 4096 transport byte + boundaries/events. The audio byte-count path retains at most 64 KiB of timing + prefix; missing later event timings are not fabricated. Compressed custom fetch + responses without runtime decoding cannot map compressed offsets onto decoded + events. These cases set `traceai.wire.timing_incomplete`; first-chunk timing remains + available. Response content capture limits and opaque/pipe limitations still apply. +- The host + SDK decides which native attributes it admits; FI does not reorder or reserve + auto-mode slots for output, provenance or usage. Once any host loss is observed, + The export boundary withholds FI content for the lineage even when some native content survived. + A default limit such as 128 is not a promise that output survives a larger span. + Explicit standalone `FITracer` projection is separate and remains supported. + +- Media and credential recognition follow the shared + `privacy.json` catalog, not semantic inference. With complete SDK context, unknown, + non-magic base64 outside its payload fields is not classified as media. Exact scalar data URIs own their + complete value; URIs inside prose are delimiter-scanned. Catalog depth/node/text + exhaustion fails closed, retaining span identity/timing rather than partial content. + Use the `FI_HIDE_INPUTS`, `FI_HIDE_OUTPUTS` and `FI_HIDE_ERROR_DETAILS` controls + when application content requires stronger protection than structural recognition. +- Config/profile parsing supports flat scalar values + and string arrays, plus named `[profiles.name]` sections in `.fi/config.toml` and + `$XDG_CONFIG_HOME/fi/config.toml` (default `~/.config/fi/config.toml`). Multiline + TOML and arbitrary TOML expressions are not supported. Credential pairs resolve + atomically: explicit arguments, environment, `futureagi.toml`, fi project profile, + then fi user profile; incomplete sources are ignored with a value-free warning + naming the missing half. Ignored FI halves from every source still seed the secret registry and + cannot appear in diagnostics. `FI_PROFILE`/the `profile` option selects the profile. +- Credentials that never cross an instrumented + transport and have no credential marker cannot be inferred from free text. Opaque + `Request`/stream bodies are never parsed or buffered; a body-only credential echoed + as plain text can therefore remain unknown when it is neither an environment/FI + value nor explicitly registered. This includes `authorization_token` inside a native + `Request` or `ReadableStream` body; the original credential-bearing application 401 + remains unchanged. Those unparsed fields are outside parsed-body credential discovery. + Materialized `URLSearchParams` and native FormData text entries are harvested + before capture limits, including duplicate fields; opaque pre-encoded form strings + are not form-decoded. Suppressed calls observe headers/URL only, never bodies. + Application transformations (signature extraction, JSON encoded inside + strings, numeric re-typing, base64 or splitting) are not a general secret-detection + guarantee. Use `registerSecret` for additional exact values and the `FI_HIDE_INPUTS`, + `FI_HIDE_OUTPUTS`, `FI_HIDE_INPUT_TEXT`, `FI_HIDE_OUTPUT_TEXT` and + `FI_HIDE_ERROR_DETAILS` controls for sensitive content/error surfaces. +- One-line/manual instrumentation with transport hooks disabled has + only initialization FI/environment seeds and explicit registrations; credentials + never observed by those hooks are not automatically known. The bounded LRU can + evict old values after 1024 distinct credentials; re-register long-lived values + when reused. The same hide controls above remain available. +- Transport credential-discovery exhaustion (more than 1024 distinct + values in one observation, excessive nesting/nodes/text or an already-materialized + body over the 4 MiB discovery cap) fails closed process-wide: subsequent FI spans + keep identity/timing but drop content on every surface. Application requests, + responses and other exporters are unchanged. This latch lasts until process restart; + it cannot safely be reset while unknown credentials could still be echoed. Ordinary + credentials longer than 8192 characters are supported within the aggregate budgets. +- Unnamed in-memory esbuild ESM output (`write:false` without + `outfile`/`outdir`) is left byte-identical to the no-plugin build: there is no + deployable sibling path for the ESM bootstrap. Use an output path or external + `node --require` preload for instrumentation. Unnamed CJS/default outputs receive + their preload in memory, with no filesystem output access. Custom JavaScript output + extensions are supported for named CJS and ESM outputs. +- Cancelling an unused clone can finalize the shared capture before the original + branch is consumed. Cancelling a released reader can likewise finalize capture + even when the native cancellation promise rejects. Application bytes, promises + and errors remain unchanged, but the one span can be incomplete, omit later output/ + usage and end too early. Later consumption can still return the complete answer and usage; branch-aware cancellation finalization is not provided. +- A provider failure carried inside an HTTP 200 stream (for example OpenAI Responses + `response.failed`) can retain HTTP-derived OK status without the provider error + description, even when `gen_ai.response.finish_reasons` records `failed`. HTTP + success is not currently overridden by that in-stream provider failure. +- Native `pipeTo`/`pipeThrough` algorithms bypass instance reader methods. These + paths retain metadata-only completion (`traceai.wire.body_unavailable=true`), + without replacing the stream/sink or fabricating output bytes. Their completion + timing is the pipe/downstream completion, not a byte-level transport timestamp. + Directly borrowing prototype methods, or freezing/non-configurably replacing + custom stream methods, can bypass observation entirely. Native Response helpers + and ordinary readers/iterators/clone/tee have byte-level regression coverage. +- Custom lazy/non-native thenables are not a validated Node fetch implementation; + the Node observer does not invoke their overridden `then` to start them. Node's + observer uses V8 promise-parent notifications and native rejection mirrors to + preserve unhandled/handled rejection events and default fatal exits for ordinary + fetch/read promises. Pre-created custom promises consumed before agent startup + are not fully observable. The Node-free edge adapter lacks that Node-specific + rejection-lifecycle mechanism and is not a drop-in process agent. +- An SDK without a processor-removal API can retain one inert agent processor after + shutdown. Agent callbacks stop, application processors remain active, and init does + not add another processor. Optional enable entries own their integration's hook + cleanup when they do not return a disable handle. +- Covered ancestry traversal is bounded to 256 wrapper/native ancestors; esbuild glob + expansion is bounded to 10,000 filesystem entries and 64 recursive directory levels. + +- No outgoing **wire spans** for `node:http`/`node:https`, direct `undici.fetch`/ + `undici.request`, custom fetch implementations captured before preload, WebSocket, + native gRPC, worker processes, browsers or arbitrary non-fetch transports. HTTP/ + Undici diagnostics do harvest credentials independently of span creation. Preload + each separate Node process and worker isolate (globals/registries are not shared + across V8 isolates). OpenAI's included dedicated instrumentation covers its + supported default transport; the global fetch wire hook does not cover node-fetch. +- URL matching is limited to the catalog. Restricted-provider endpoints on a custom + proxy host may not match. No speculative interception of unknown AI protocols. +- Request objects and opaque/pre-encoded multipart streams are never cloned/read; + known provider endpoints retain metadata/body-unavailable capture only. Use native + FormData for text fields and file metadata. Binary request sizes are included only + when the body or declared content length exposes the size. +- A response must be consumed or cancelled to finish capture. Unread or never-ending + responses do not yield completed spans. Force-flush never waits for unread responses. +- Bedrock binary event-stream responses record request/status only. Audio streaming + and base64 variants count bytes but do not reconstruct audio/timestamps. No audio + bytes are exported. +- Registry completeness is not a guarantee that every instrumentor supports every upstream version. Instrumentations depending on obsolete module paths can remain pending. + +## Redistributing the launcher + +The built `dist/agent/` directory is relocatable. Keep the whole directory, including `runtime.cjs`, `hook.mjs`, `hook-register.cjs` and linked `.LEGAL.txt` notices. Use its `preload.cjs` with Node’s `--require` flag, not `--import`; no application installation of `@traceai/auto` is needed for this payload. OpenAI instrumentation is embedded; app-installed instrumentors take precedence. + +The ES5-only preload skips Node below 18 without parsing the modern payload. A runtime without `module.register` has CJS/fetch capture, not ESM hooks. These compatibility guards do not change the supported package engine: Node 20.6+. + +## Legal notices + +The published package includes `dist/THIRD-PARTY-NOTICES`, with the full installed +LICENSE, LICENCE, COPYING and NOTICE files for third-party inputs to all four +launcher/edge bundles. `dist/third-party-manifest.json` maps each bundle to its +third-party package names and versions; first-party `@traceai/*` packages are listed +separately in the notices. These files supplement, and do not replace, the existing +linked `.LEGAL.txt` output. Keep them with any redistributed launcher or edge payload. +The build fails if a bundled third-party package has no readable, nonempty license +text file; a license identifier or linked source comment alone is not sufficient. + +## Maintaining the coverage table + +The README’s library table is generated from `src/integrations.json`. Run `node scripts/generate-readme.cjs` from the package directory after changing the registry; `--check` fails if the checked-in table has drifted. Runtime classes and supported methods remain owned by the individual integrations. diff --git a/typescript/packages/traceai_auto/docs/CONFIGURATION.md b/typescript/packages/traceai_auto/docs/CONFIGURATION.md new file mode 100644 index 000000000..818301396 --- /dev/null +++ b/typescript/packages/traceai_auto/docs/CONFIGURATION.md @@ -0,0 +1,181 @@ +# Configuration reference + +[Back to quick start](../README.md) · [Framework recipes](FRAMEWORKS.md) · [Capture and privacy internals](ARCHITECTURE.md) + +Configure the agent before its first preload or `init()` call. The first configuration is process-wide and terminal, including after failed initialization or shutdown. Restart to change it. `init()` returns the selected tracer provider, or `undefined` if disabled/failed; it does not return a report. + +## Environment and init options + +Unless noted, precedence is **code option → environment → `futureagi.toml` → default**. Code options go directly into `init(options)`; privacy options go under `traceConfig`. Lists in environment variables are comma-separated, case-insensitive names from the [coverage table](../README.md#library-coverage), plus `wire` and `http`. The denylist wins. + +| Environment | `init()` option | Default and behavior | +| --- | --- | --- | +| `FI_API_KEY` | `apiKey` | Unset; resolved as a pair with the secret key | +| `FI_SECRET_KEY` | `secretKey` | Unset; required with API key only for the default FI route | +| `FI_BASE_URL` | `baseUrl` | `https://api.futureagi.com`; base or full collector endpoint. Falls back to the selected project/user profile's `base_url` before the default | +| `FI_PROJECT_NAME` | `projectName` | After code/env/file: `OTEL_SERVICE_NAME` → profile `project` → working-directory basename → `DEFAULT_PROJECT_NAME` | +| `FI_PROJECT_TYPE` | `projectType` | `observe`; `experiment` is opt-in | +| `FI_INSTRUMENTATIONS` | `instrumentations` | Empty list means all eligible integrations; e.g. `openai,wire` | +| `FI_DISABLED_INSTRUMENTATIONS` | `disabledInstrumentations` | Empty list; disable named integrations even if allowlisted | +| `FI_WIRE_CAPTURE` | `wireCapture` | `true`; enables global-fetch capture and transport credential observation when `wire` is also enabled | +| `FI_WIRE_MAX_BODY_BYTES` | `wireMaxBodyBytes` | `4194304` bytes; nonnegative finite values are rounded down, invalid values use the default. A capture cap, not an application payload-size limit | +| `FI_SAMPLE_RATE` | `sampleRate` | `1`; finite values clamped to `[0,1]`, invalid values use `1`. Parent-based root sampling for agent-owned providers only | +| `FI_AUTO_DEBUG` | `debug` | `false`; masked startup JSON report | +| `FI_CONFIG_FILE` | `configFile` | `futureagi.toml`, resolved relative to the working directory | +| `FI_PROFILE` | `profile` | `default`; selects a named profile from the FI project/user files | +| `FI_MASTRA_SPAN_PRODUCER` | `mastraSpanProducer` | `exporter`; parser accepts `exporter` or `bridge`, otherwise warns and uses `exporter`. Does **not** enable Mastra zero-code support in this release | +| `OTEL_SDK_DISABLED` | — | `false`; `true` disables initialization, including when an exporter/provider is supplied | +| — | `exporter` | Unset; standard OTel `SpanExporter`, batched by the agent. No FI credentials required; takes precedence over the default FI exporter | +| — | `spanProcessor` | Unset; explicit OTel `SpanProcessor`. Takes precedence over `exporter` and the default FI route; keeps its selected processor policy, not automatically batched | +| — | `provider` | Existing global provider, otherwise an agent-created provider. Explicit provider selects the instrumentation destination without replacing the global provider | +| — | `traceConfig` | Privacy object described below | + +Except for `hideErrorDetails`, environment booleans are true only when their case-insensitive string value is `true`; `1` is not true. Prefer the literal `true` / `false` forms. + +### Inherited SDK settings + +These are read by fi-core or the underlying OpenTelemetry SDK, not from `futureagi.toml`. The limits and batching defaults below follow the OTel 2.x SDK used by the agent; an application-owned provider/processor may configure its own values. + +| Environment | Default | Scope | +| --- | --- | --- | +| `FI_PROJECT_VERSION_NAME` | `DEFAULT` | fi-core resource version name when the agent constructs a provider; not a project-version option on `init()` | +| `OTEL_SERVICE_NAME` | SDK service default | Application `service.name`; also a fallback for FI project naming | +| `OTEL_RESOURCE_ATTRIBUTES` | Unset | Comma-separated OTel resource attributes; preserved independently of FI project routing | +| `OTEL_BSP_MAX_QUEUE_SIZE` | `2048` spans | Queue bound for the agent's batch processor | +| `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | `512` spans | Export batch size, no larger than the queue bound | +| `OTEL_BSP_SCHEDULE_DELAY` | `5000` ms | Scheduled batch-export interval | +| `OTEL_BSP_EXPORT_TIMEOUT` | `30000` ms | SDK batch-export timeout; auto flush/shutdown still have their shorter five-second deadline | +| `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` / `OTEL_ATTRIBUTE_COUNT_LIMIT` | `128` | Native attribute admission; span-specific configuration takes precedence | +| `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` / `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | Unlimited | Native string-value limit; observed loss can withhold FI content | +| `OTEL_SPAN_EVENT_COUNT_LIMIT` / `OTEL_SPAN_LINK_COUNT_LIMIT` | `128` each | Native span event/link limits | +| `OTEL_SPAN_ATTRIBUTE_PER_EVENT_COUNT_LIMIT` / `OTEL_SPAN_ATTRIBUTE_PER_LINK_COUNT_LIMIT` | `128` each | Native event/link attribute limits | + +Use `FI_SAMPLE_RATE`, not `OTEL_TRACES_SAMPLER`, for the agent-owned sampler. An existing provider keeps its own sampler. Use `FI_BASE_URL` for the default HTTP export route; gRPC transport, generic OTel exporter selection and exporter headers are not `init()` options. To choose those, supply an exporter or processor configured for your destination. The auto agent explicitly disables fi-core verbose provider/exporter logs; use `FI_AUTO_DEBUG` for its report. + +### Credentials and profiles + +Credentials are resolved **atomically**: both halves must come from the same source. The first complete pair wins: + +1. Explicit `apiKey` + `secretKey` options. +2. `FI_API_KEY` + `FI_SECRET_KEY` environment variables. +3. `api_key` + `secret_key` in the configured `futureagi.toml`. +4. Selected profile in the nearest `.fi/config.toml`, searching upward from the working directory. +5. Selected profile in `$XDG_CONFIG_HOME/fi/config.toml`, or `$HOME/.config/fi/config.toml` (OS home directory if `HOME` is unset). + +An incomplete source is ignored with a value-free warning; its half is never combined with a lower-precedence half. Only credentials, `base_url` and `project` fall back to the profile files. Keep credentials in your environment or secret manager, not a committed config file. + +### Config file + +A credential-free `futureagi.toml` can hold ordinary app settings: + +```toml +project_name = "my-ai-app" +project_type = "observe" +instrumentations = ["openai", "wire"] +wire_capture = true +wire_max_body_bytes = 4194304 +sample_rate = 1 +debug = false +hide_inputs = true +hide_outputs = true +hide_error_details = true +``` + +Keys use snake_case: `base_url`, `project_name`, `project_type`, `instrumentations`, `disabled_instrumentations`, `wire_capture`, `wire_max_body_bytes`, `sample_rate`, `debug`, `mastra_span_producer`, and the privacy keys below. File `debug` maps to `FI_AUTO_DEBUG`. `configFile` and `profile` are selected by code/environment, not by this file. + +This parser supports flat strings (single- or double-quoted), booleans, numbers and single-line string arrays, not full TOML. Comments outside quoted strings are supported. Unknown/unsupported values are ignored. A section header ends flat configuration; only `[profiles.name]` sections in the FI profile files are selected by profile name. Do not put app settings under arbitrary TOML tables. + +## Privacy options + +All code options below are nested under `traceConfig`; file keys are snake_case. Hide controls apply to traceAI-authored values and the agent-owned export view, not an unrelated exporter's native spans. + +| Environment | `traceConfig` option | Default | Effect | +| --- | --- | --- | --- | +| `FI_HIDE_INPUTS` | `hideInputs` | `false` | Hide input values and input-message families | +| `FI_HIDE_OUTPUTS` | `hideOutputs` | `false` | Hide output values and output-message families | +| `FI_HIDE_INPUT_MESSAGES` | `hideInputMessages` | `false` | Hide input message attributes | +| `FI_HIDE_OUTPUT_MESSAGES` | `hideOutputMessages` | `false` | Hide output message attributes | +| `FI_HIDE_INPUT_TEXT` | `hideInputText` | `false` | Hide input text content | +| `FI_HIDE_OUTPUT_TEXT` | `hideOutputText` | `false` | Hide output text content | +| `FI_HIDE_INPUT_IMAGES` | `hideInputImages` | `false` | Hide image input; export masking conservatively hides raw input/message aliases too | +| `FI_HIDE_EMBEDDING_VECTORS` | `hideEmbeddingVectors` | `false` | Hide vectors on library/forwarded/generic-JSON routes; catalog wire embeddings already omit vectors | +| `FI_HIDE_LLM_INVOCATION_PARAMETERS` | `hideLLMInvocationParameters` | `false` | Hide invocation parameters, `gen_ai.request.parameters` and tool schemas in the export view | +| `FI_HIDE_ERROR_DETAILS` | `hideErrorDetails` | Derived | Hide error descriptions, exception messages/stacks and related content; keep error status/type | +| `FI_PII_REDACTION` | `piiRedaction` | `false` | Apply supported PII patterns; not a guarantee of complete PII removal | +| `FI_BASE64_IMAGE_MAX_LENGTH` | `base64ImageMaxLength` | `0` | Value-level image cap. Invalid/negative/fractional values fall back to `0`; positive values do not restore base64 image export | + +When error hiding is unset, any input/output value, message or text hide flag enables it. Invocation-parameter hiding additionally implies error hiding at the export boundary. Image/vector hiding and PII do not imply it. Explicit `true` or `false` overrides the derived error setting; empty/invalid environment values mean derive. Secret and media scrubbing still run with explicit `false`. + +Known-secret redaction is always active on traceAI-owned exports. The registry is bounded to 1024 values of at least eight characters. `registerSecret(value)` adds an exact string without coercing objects. Unknown free-text credentials, transformed secrets and credentials hidden in unparsed bodies may remain unknown; hide sensitive content instead of relying on inference. + +## Bring your own OpenTelemetry destination + +With no complete FI key pair, `init({ exporter })`, `init({ spanProcessor })`, `init({ provider })`, or an existing application provider activates instrumentation **without creating an FI export route**. If neither a destination nor a complete pair exists, instrumentation is disabled. With a complete pair and a provider but no explicit exporter/processor, the agent attempts to attach its FI route to that provider. + +Keep one global provider. Existing OTel JS 1.x/2.x providers retain their sampler and context manager; the agent attaches its processor where supported. An incompatible provider may trigger a warning and an isolated AI provider rather than replacement of the global SDK. + +For an app without an existing SDK, install the exporter you want to use: + +```sh +npm install @opentelemetry/exporter-trace-otlp-http@0.202.0 +``` + +Save as `instrument.mjs`. Set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` to your collector's **full traces endpoint** and configure that exporter's authentication separately: + +```js +import { init } from "@traceai/auto"; +import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; + +init({ + projectName: "my-ai-app", + exporter: new OTLPTraceExporter({ + url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, + }), +}); +``` + +Start with your preload instead of the default one: + +```sh +node --import ./instrument.mjs app.mjs +``` + +The agent batches and sanitizes its supplied `exporter` route. A supplied `spanProcessor` is application-owned policy: configure that processor's privacy/export behavior yourself. Agent shutdown invokes the processor/exporter it attaches, but never shuts down an application-owned provider; do not hand it a processor whose lifecycle must remain independent. + +Standard `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` preserve application identity; FI project routing does not replace `service.name`. The default FI exporter uses `FI_BASE_URL`, not `OTEL_EXPORTER_OTLP_ENDPOINT`. Standard OTel attribute-count/value limits still apply (`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` / `OTEL_ATTRIBUTE_COUNT_LIMIT`, `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` / `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`). Native host loss can withhold the FI content view rather than retain a partial value. + +## Lifecycle API + +| Export | Contract | +| --- | --- | +| `init(options?)` | Initialize once; return the same provider on later calls, or `undefined` when disabled/failed | +| `report()` | Masked configuration, `active`, integration statuses and collector state; does not probe the collector | +| `forceFlush()` | Flush completed spans with a five-second deadline; does not consume unread responses | +| `shutdown()` | Idempotent hook removal and bounded drain/shutdown; no supported reinitialization afterwards | +| `registerSecret(value)` | Register an exact sensitive string of at least eight characters; ignore other values | + +## CLI + +The package installs the `traceai-auto` binary. With a local npm installation, invoke it using `npx --no-install traceai-auto` so diagnostics use the package already in your app. + +| Command suffix | Behavior | +| --- | --- | +| `doctor` | Initialize, send one sampled test span, flush, print report and shut down | +| `doctor --no-check` | Initialize and print report, without the test export | +| `bootstrap` | Print detected integrations and suggested `npm install` commands; no installation | +| `bootstrap --install` | Explicitly install missing instrumentors for detected targets, using npm | +| `bootstrap --install --package-manager=pnpm` | Same installation with pnpm; `yarn` is also supported | + +Bootstrap never installs target application libraries. Restart after installing instrumentors. Doctor's exit status can still be zero when the collector fails or the agent is disabled: inspect `active` and `collector` in JSON. Zero sampling or an application-owned destination can legitimately leave the collector `not_tested`. + +| Integration status | Meaning | +| --- | --- | +| `instrumented` | Wire/server hook enabled, or a library patch callback ran | +| `pending` | Hook registered, compatible target import not observed yet | +| `not_installed` | Target library cannot be resolved from this app | +| `missing_instrumentor` | Target found, dedicated integration absent | +| `disabled` | Disabled by config, credentials/destination, or SDK switch | +| `manual` | Explicit wrapper/processor API required | +| `failed` | Load, registration, patch or known version incompatibility; inspect the reason | + +Sources: [`config.ts`](../src/config.ts), [`index.ts`](../src/index.ts), [`cli.ts`](../src/cli.ts), and [fi-core privacy defaults](../../fi-core/src/trace/trace-config/constants.ts). diff --git a/typescript/packages/traceai_auto/docs/FRAMEWORKS.md b/typescript/packages/traceai_auto/docs/FRAMEWORKS.md new file mode 100644 index 000000000..238f95cac --- /dev/null +++ b/typescript/packages/traceai_auto/docs/FRAMEWORKS.md @@ -0,0 +1,159 @@ +# Frameworks and deployment + +[Back to quick start](../README.md) · [Configuration](CONFIGURATION.md) · [Architecture](ARCHITECTURE.md) + +All Node recipes assume `@traceai/auto` is installed in your app and the FI keys/project are configured before startup. Set hide flags before initialization if prompts, responses or error details must not leave the process. + +## ESM and CommonJS + +Prefer the package preload shown in the quick start. It executes before application imports and registers both CJS and supported ESM hooks. A top-level `init()` next to static SDK imports is not equivalent: ESM can load those dependencies before the call runs. Put custom initialization in a separate `--import` file instead. + +The package requires Node **20.6+**. Preload each child process/worker isolate separately. Keep the application working directory consistent so optional target libraries and instrumentors resolve correctly. + +## Next.js + +Use Next's `instrumentation.ts` at the project root (or inside `src` when that is where the app lives). Guard the runtime so the Node agent never enters an edge path: + +```ts +export async function register() { + if (process.env.NEXT_RUNTIME === "nodejs") { + await import("@traceai/auto/register"); + } +} +``` + +For Next versions supporting `serverExternalPackages`, merge these entries into `next.config.mjs`. Keep the SDKs you need to hook external too; this example uses OpenAI: + +```js +export default { + serverExternalPackages: ["@traceai/auto", "openai"], +}; +``` + +Set FI variables on the **server**, never as `NEXT_PUBLIC_*` variables. Trigger a Node-runtime route that calls your model. Do not add this preload to browser code or assume it instruments edge handlers. + +`withTraceAI(config)` from `@traceai/auto/next` is an optional **webpack-only** adapter. It preserves an existing webpack callback and skips client/edge configs, but does not cover Turbopack. Prefer the guarded register hook rather than combining both approaches. + +## Node server bundlers + +These opt-in plugins inject the packaged agent before Node **executable server entries**. They do not instrument browser or edge bundles. Keep AI SDKs external to preserve dedicated library import hooks; global-fetch wire capture can still observe recognized calls when application code is bundled. + +Use only the recipe for your build tool. Each example takes the quick-start `app.mjs` and builds a server executable; install the selected bundler as your normal build dependency. + +### esbuild + +Save as `build.mjs` and run `node build.mjs`: + +```js +import { build } from "esbuild"; +import { traceAI } from "@traceai/auto/esbuild"; + +await build({ + entryPoints: ["app.mjs"], + outfile: "dist/server.mjs", + bundle: true, + platform: "node", + format: "esm", + packages: "external", + plugins: [traceAI()], +}); +``` + +### Vite Node SSR + +Save as `vite.config.mjs`. The plugin applies to production **Node SSR** builds, not development, client builds or `webworker` SSR: + +```js +import { defineConfig } from "vite"; +import { traceAI } from "@traceai/auto/vite"; + +export default defineConfig({ + plugins: [traceAI()], + build: { + ssr: "app.mjs", + outDir: "dist", + rollupOptions: { output: { entryFileNames: "server.mjs" } }, + }, + ssr: { target: "node", external: ["openai"] }, +}); +``` + +### Rollup + +Save as `rollup.config.mjs`. Rollup cannot infer the server platform; `server: true` is required: + +```js +import { traceAI } from "@traceai/auto/rollup"; + +export default { + input: "app.mjs", + external: ["openai"], + output: { file: "dist/server.mjs", format: "es" }, + plugins: [traceAI({ server: true })], +}; +``` + +### webpack 5 + +Save as `webpack.config.mjs`. This recipe emits a CommonJS server executable: + +```js +import { resolve } from "node:path"; +import { TraceAIPlugin } from "@traceai/auto/webpack"; + +export default { + mode: "production", + target: "node", + entry: "./app.mjs", + experiments: { topLevelAwait: true }, + externals: { openai: "commonjs openai" }, + output: { path: resolve("dist"), filename: "server.cjs" }, + plugins: [new TraceAIPlugin()], +}; +``` + +### Deploy the build, not just its entry file + +ESM output includes a small bootstrap at the original entry path and a sibling `*.traceai-app.mjs` payload. Ship **both**, plus generated chunks and sourcemaps. Run the built entry normally; the plugin already injects tracing. + +The injected preload uses an **absolute filesystem path**. Either retain that path in your deployment or pass `agentPath` pointing to the deployment's `preload.cjs` (the file must also exist when the build resolves it). Copy the complete `dist/agent/` directory with its `runtime.cjs`, `hook.mjs`, `hook-register.cjs` and `.LEGAL.txt` files, plus `dist/THIRD-PARTY-NOTICES` and `dist/third-party-manifest.json` alongside the relocated payload. Do not copy only `preload.cjs`. + +| Plugin option | Default | Meaning | +| --- | --- | --- | +| `agentPath` | Installed package's built preload | Absolute or resolvable path to a complete deployed agent payload | +| `server` | Tool-specific detection | Rollup requires `true`; `false` disables injection. Browser/edge detection still prevents injection | + +ESM library/handler entries with exports are rejected by the executable bootstrap; use a runtime preload or a framework register hook instead. `import.meta.url` in the running ESM app identifies the sibling payload, not the bootstrap. Unnamed in-memory esbuild ESM output cannot get a deployable sibling; use an output path or external preload. + +## AWS Lambda and short-lived processes + +Do not rely on process exit in Lambda: the runtime can freeze before a batch exports. Initialize once outside the handler and flush completed spans at each invocation boundary. The fi-core wrapper handles a bounded invocation flush without shutting down a warm provider. + +Install `@traceai/fi-core` directly when importing it in your own code. Save this as a Node ESM handler (for example `index.mjs`); initialize before dynamically importing AI SDKs: + +```js +import { init } from "@traceai/auto"; +import { traceLambdaHandler } from "@traceai/fi-core"; + +const provider = init(); +const { default: OpenAI } = await import("openai"); +const client = new OpenAI(); + +export const handler = traceLambdaHandler(async () => { + const response = await client.chat.completions.create({ + model: process.env.OPENAI_MODEL, + messages: [{ role: "user", content: "Say hello in one word." }], + }); + return { statusCode: 200, body: response.choices[0].message.content }; +}, { provider, maxFlushWaitMillis: 2000, remainingTimeReserveMillis: 250 }); +``` + +Use this wrapper **instead of** an ADOT/upstream Lambda invocation wrapper, not on top of one. The invocation span is metadata-only; child model calls use your configured content policy. Do not call `shutdown()` after each warm invocation. Callback and response-streaming handlers have separate constraints in the [fi-core Lambda reference](../../fi-core/README.md#aws-lambda-invocation-lifecycle). + +In a short-lived ordinary Node program, finish consuming responses, then `await forceFlush()` or `await shutdown()` from `@traceai/auto` before an explicit exit. A five-second bound prevents indefinite shutdown waits but cannot guarantee collector acceptance, cancel a stuck exporter or survive SIGKILL. For an application-owned provider, follow that provider's lifecycle too. + +## Edge and browsers + +Do **not** preload `@traceai/auto/register` in browsers, Cloudflare Workers, Deno isolates or Next edge routes. This package's zero-code agent is Node-only. + +`@traceai/auto/edge` is a low-level, Node-free fetch observer for integration authors. It exports `patchFetch(maxBodyBytes, emit)`, returning a removable hook with pending response-decoding work. It does **not** configure an exporter, read FI keys, apply fi-core `TraceConfig`, propagate OTel context or supply the Node suppression/deduplication policy. It is not an end-to-end edge setup recipe; use a maintained native OTel integration for your runtime rather than copying a custom exporter into your app. diff --git a/typescript/packages/traceai_auto/docs/images/quickstart-trace.png b/typescript/packages/traceai_auto/docs/images/quickstart-trace.png new file mode 100644 index 0000000000000000000000000000000000000000..1c4c1eb2fd680112ad111ab49bf27f318f4d7245 GIT binary patch literal 100550 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 SbNY`ZOIm7rs+G#N;r|C|X(#*u literal 0 HcmV?d00001 diff --git a/typescript/packages/traceai_auto/scripts/generate-readme.cjs b/typescript/packages/traceai_auto/scripts/generate-readme.cjs new file mode 100644 index 000000000..a75fb9928 --- /dev/null +++ b/typescript/packages/traceai_auto/scripts/generate-readme.cjs @@ -0,0 +1,24 @@ +// Keep the public coverage table tied to the registry the loader actually uses. +const { readFileSync, writeFileSync } = require('node:fs'); +const { resolve } = require('node:path'); +const root = resolve(__dirname, '..'); +const integrations = JSON.parse(readFileSync(resolve(root, 'src/integrations.json'), 'utf8')); +const lines = [ + '| Configuration name | Target library | Instrumentation package | Setup |', + '| --- | --- | --- | --- |', + ...integrations.map(entry => { + const mode = entry.enable ? 'Enable entry' : entry.manual ? 'Manual' : 'Import hook'; + const included = entry.name === 'openai' ? ' (included)' : ''; + return `| \`${entry.name}\` | ${entry.targets.map(target => `\`${target}\``).join(', ')} | \`${entry.package}\`${included} | ${mode} |`; + }), +]; +const file = resolve(root, 'README.md'); +const before = readFileSync(file, 'utf8'); +const pattern = /[\s\S]*?/; +if (!pattern.test(before)) throw new Error('README coverage markers are missing'); +const after = before.replace(pattern, `\n${lines.join('\n')}\n`); +if (process.argv.includes('--check')) { + if (before !== after) throw new Error('README coverage is stale; run scripts/generate-readme.cjs'); +} else { + writeFileSync(file, after); +} diff --git a/typescript/packages/traceai_auto/test/docs-consumer.cjs b/typescript/packages/traceai_auto/test/docs-consumer.cjs new file mode 100644 index 000000000..ac450baa1 --- /dev/null +++ b/typescript/packages/traceai_auto/test/docs-consumer.cjs @@ -0,0 +1,138 @@ +// Run only in a disposable installed consumer: this writes app/config files and replaces dist/. +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const http = require('node:http'); +const { spawn } = require('node:child_process'); +const { createRequire } = require('node:module'); +const cwd = path.resolve(process.argv[2]); +const repo = path.resolve(__dirname, '../../../..'); +const pkg = path.join(repo, 'typescript/packages/traceai_auto'); +const read = name => fs.readFileSync(path.join(pkg, name), 'utf8'); +const blocks = text => [...text.matchAll(/```([^\n]*)\n([\s\S]*?)```/g)].map(m => ({lang:m[1],code:m[2]})); +const main = read('README.md'); +const frames = blocks(read('docs/FRAMEWORKS.md')); +const config = blocks(read('docs/CONFIGURATION.md')); +const output = []; +const captured = []; +let base; +const server = http.createServer((req,res) => { + let body=''; req.on('data',b=>body+=b); req.on('end',()=>{ + res.setHeader('content-type','application/json'); + if(req.url==='/tracer/v1/traces') {captured.push(JSON.parse(body));res.end('{}');} + else if(req.url==='/v1/chat/completions') res.end(JSON.stringify({id:'chatcmpl-docs',object:'chat.completion',created:1,model:'example-model',choices:[{index:0,message:{role:'assistant',content:'Hello.'},finish_reason:'stop'}],usage:{prompt_tokens:7,completion_tokens:2,total_tokens:9}})); + else {res.statusCode=404;res.end('{}');} + }); +}); +const spans = () => captured.flatMap(e=>e.resourceSpans||[]).flatMap(r=>r.scopeSpans||[]).flatMap(s=>s.spans||[]); +const cleanEnv = {...process.env}; +for(const key of Object.keys(cleanEnv)) if(key.startsWith('FI_')||key.startsWith('OTEL_')||key==='NODE_OPTIONS') delete cleanEnv[key]; +function environment(extra={}) { return {...cleanEnv,FI_API_KEY:'synthetic-fi-api-123',FI_SECRET_KEY:'synthetic-fi-secret-123',FI_BASE_URL:base,FI_PROJECT_NAME:'my-ai-app',OPENAI_API_KEY:'synthetic-provider-123',OPENAI_BASE_URL:base+'/v1',OPENAI_MODEL:'example-model',...extra}; } +function run(command, extra={}, dir=cwd, timeout=120000) { + return new Promise((resolve,reject)=>{ + const child=spawn('bash',['-c',command],{cwd:dir,env:environment(extra),stdio:['ignore','pipe','pipe']}); + let out='',err=''; child.stdout.on('data',b=>out+=b);child.stderr.on('data',b=>err+=b); + const timer=setTimeout(()=>{child.kill('SIGKILL');reject(new Error(`timeout: ${command}\n${err}`));},timeout); + child.on('error',error=>{clearTimeout(timer);reject(error);});child.on('close',code=>{clearTimeout(timer);code===0?resolve(out):reject(new Error(`exit ${code}: ${command}\n${out}\n${err}`));}); + }); +} +function record(test,extra={}) { const result={consumer:path.basename(cwd),test,status:'PASS',...extra};output.push(result);console.log(JSON.stringify(result)); } +function assertSpans(test,{hidden=false,min=1}={}) { + assert.ok(spans().length>=min,`${test}: ${spans().length} spans`); + const all=JSON.stringify(captured); + assert.ok(!all.includes('synthetic-provider-123')); + if(hidden) {assert.ok(!all.includes('Say hello in one word.'));assert.ok(!all.includes('Hello.'));} + else assert.ok(all.includes('Hello.'),test+' output missing'); + record(test,{spans:spans().length,names:spans().map(s=>s.name)}); +} +function write(name,text) {fs.writeFileSync(path.join(cwd,name),text);} +async function executeSnippets() { + const app=blocks(main).find(b=>b.lang==='js').code; + write('app.mjs',app); + write('app.cjs',app.replace('import OpenAI from "openai";','const OpenAI = require("openai");\n(async () => {')+'\n})();\n'); + const packagePath=path.join(cwd,'package.json'),manifest=JSON.parse(fs.readFileSync(packagePath)); + manifest.scripts={...manifest.scripts,start:'node app.mjs'};fs.writeFileSync(packagePath,JSON.stringify(manifest)); + for(const {code} of blocks(main).filter(b=>b.lang==='sh')) { + if(code.startsWith('npm install')) continue; + captured.length=0; + const command=code.replaceAll('your-api-key','synthetic-fi-api-123').replaceAll('your-secret-key','synthetic-fi-secret-123'); + const result=await run(command); + if(command.includes('bootstrap')) {assert.ok(JSON.parse(result).integrations.length>0);assert.equal(spans().length,0);record('bootstrap command');} + else if(command.includes('doctor')) {const report=JSON.parse(result);assert.equal(report.active,true);if(command.includes('--no-check')) {assert.match(report.collector,/not_tested/);assert.equal(spans().length,0);} else {assert.equal(report.collector,'accepted');assert.ok(spans().some(s=>s.name==='traceai.auto.doctor'));}record(command.trim(),{collector:report.collector});} + else {assert.match(result,/Hello\./);assertSpans(command.trim());} + } + captured.length=0; + const root=fs.readFileSync(path.join(repo, 'README.md'),'utf8').split('## Zero-code tracing for Node.js')[1].split('## Quickstart')[0]; + const rootCommand=blocks(root)[0].code.split('\n').slice(1).join('\n').replaceAll('your-api-key','synthetic-fi-api-123').replaceAll('your-secret-key','synthetic-fi-secret-123'); + await run(rootCommand);assertSpans('root quickstart'); + captured.length=0; + write('instrument.mjs',config.find(b=>b.lang==='js').code); + await run(config.find(b=>b.lang==='sh'&&b.code.startsWith('node ')).code,{FI_API_KEY:'',FI_SECRET_KEY:'',OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:base+'/tracer/v1/traces'}); + assertSpans('custom exporter without FI credentials'); + captured.length=0; + write('futureagi.toml',config.find(b=>b.lang==='toml').code); + await run('node --import @traceai/auto/register app.mjs');assertSpans('documented TOML hides content',{hidden:true}); + fs.unlinkSync(path.join(cwd,'futureagi.toml')); + for(const [name,index,command,entry] of [ + ['esbuild',2,'node build.mjs','dist/server.mjs'], + ['vite',3,'node node_modules/vite/bin/vite.js build','dist/server.mjs'], + ['rollup',4,'node node_modules/rollup/dist/bin/rollup -c','dist/server.mjs'], + ['webpack',5,'node webpack-build.cjs','dist/server.cjs'], + ]) { + captured.length=0;fs.rmSync(path.join(cwd,'dist'),{recursive:true,force:true}); + const filename={esbuild:'build.mjs',vite:'vite.config.mjs',rollup:'rollup.config.mjs',webpack:'webpack.config.mjs'}[name]; + write(filename,frames[index].code); + if(name==='webpack')write('webpack-build.cjs',`const webpack=require('webpack');import('./webpack.config.mjs').then(({default:c})=>webpack(c,(err,stats)=>{if(err||stats.hasErrors()){console.error(err||stats.toString());process.exitCode=1;}}));`); + await run(command);await run(`node ${entry}`);assertSpans('documented '+name+' recipe'); + } + captured.length=0;write('lambda.mjs',frames[6].code); + write('invoke.mjs',`import {handler} from './lambda.mjs';\nfor(let i=0;i<2;i++){const result=await handler({},{awsRequestId:'synthetic-request-'+i,functionName:'readme-example',getRemainingTimeInMillis:()=>5000});if(result.body!=='Hello.')throw new Error('bad response');}\n`); + await run('node invoke.mjs');assertSpans('documented warm Lambda handler',{min:4}); + const req=createRequire(path.join(cwd,'package.json')); + const auto=path.resolve(path.dirname(req.resolve('@traceai/auto')),'../..'); + const {resolveConfig}=req(path.join(auto,'dist/src/config.js')); + const defaults=resolveConfig({configFile:'/missing'},{}); + assert.equal(defaults.sampleRate,1);assert.equal(defaults.wireCapture,true);assert.equal(defaults.wireMaxBodyBytes,4194304);assert.equal(defaults.baseUrl,'https://api.futureagi.com');assert.equal(defaults.projectType,'observe');assert.equal(defaults.debug,false);assert.equal(defaults.mastraSpanProducer,'exporter');assert.equal(defaults.sdkDisabled,false); + assert.deepEqual(defaults.instrumentations,[]);assert.deepEqual(defaults.disabledInstrumentations,[]); + assert.equal(resolveConfig({}, {FI_WIRE_CAPTURE:'1'}).wireCapture,false); + record('configuration defaults against installed package'); + captured.length=0; + const {patchFetch}=req('@traceai/auto/edge');let edge; + const hook=patchFetch(4194304,result=>edge=result); + await (await fetch(base+'/v1/chat/completions',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({model:'example-model',messages:[{role:'user',content:'hello'}]})})).text(); + await Promise.all([...hook.pending]);hook.remove(); + assert.ok(edge);assert.equal(spans().length,0);record('edge observer has no implicit exporter'); +} +async function nextRecipe() { + const dir=path.join(cwd,'next-example');fs.mkdirSync(path.join(dir,'app/api/chat'),{recursive:true}); + fs.writeFileSync(path.join(dir,'instrumentation.ts'),frames[0].code); + fs.writeFileSync(path.join(dir,'next.config.mjs'),frames[1].code); + fs.writeFileSync(path.join(dir,'package.json'),JSON.stringify({name:'readme-next-example',private:true})); + fs.writeFileSync(path.join(dir,'app/layout.js'),`export default function Layout({children}) {return {children};}`); + fs.writeFileSync(path.join(dir,'app/page.js'),`export default function Page(){return
TraceAI documentation example
;}`); + fs.writeFileSync(path.join(dir,'app/api/chat/route.js'),`import OpenAI from 'openai';export const runtime='nodejs';export const dynamic='force-dynamic';export async function GET(){const result=await new OpenAI().chat.completions.create({model:process.env.OPENAI_MODEL,messages:[{role:'user',content:'Say hello in one word.'}]});return Response.json({message:result.choices[0].message.content});}`); + await run('node ../node_modules/next/dist/bin/next build',{NEXT_TELEMETRY_DISABLED:'1'},dir,240000); + captured.length=0; + const child=spawn(process.execPath,['../node_modules/next/dist/bin/next','start','-p','3456'],{cwd:dir,env:environment({NEXT_TELEMETRY_DISABLED:'1'})}); + const closed = new Promise(resolve=>child.once('close',resolve)); + let logs='';child.stdout.on('data',b=>logs+=b);child.stderr.on('data',b=>logs+=b); + try { + let ready=false; + for(let i=0;i<120;i++){try {const r=await fetch('http://127.0.0.1:3456/');if(r.ok){ready=true;break;}}catch{}await new Promise(r=>setTimeout(r,250));} + assert.ok(ready,logs); + const response=await fetch('http://127.0.0.1:3456/api/chat');assert.equal(response.status,200,logs);assert.equal((await response.json()).message,'Hello.'); + for(let i=0;i<80&&!spans().length;i++)await new Promise(r=>setTimeout(r,250)); + assertSpans('documented Next production build/start'); + } finally { + child.kill('SIGTERM'); + const timer=setTimeout(()=>child.kill('SIGKILL'),10000); + await closed; + clearTimeout(timer); + } +} +(async()=>{ + await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve));base=`http://127.0.0.1:${server.address().port}`; + await executeSnippets(); + await nextRecipe(); + if (process.argv[3]) { fs.mkdirSync(process.argv[3],{recursive:true}); fs.writeFileSync(path.join(process.argv[3],path.basename(cwd)+'.json'),JSON.stringify(output,null,2)); } +})().catch(error=>{console.error(error);process.exitCode=1;}).finally(()=>{server.closeAllConnections();server.close();}); diff --git a/typescript/packages/traceai_auto/test/docs.test.ts b/typescript/packages/traceai_auto/test/docs.test.ts new file mode 100644 index 000000000..c0f1f979c --- /dev/null +++ b/typescript/packages/traceai_auto/test/docs.test.ts @@ -0,0 +1,47 @@ +import { readFileSync, existsSync } from "node:fs"; +import { resolve, dirname } from "node:path"; +import { execFileSync } from "node:child_process"; + +const root = resolve(__dirname, ".."); +const repo = resolve(root, "../../.."); +const read = (file: string) => readFileSync(resolve(root, file), "utf8"); + +test("README coverage is generated from the runtime registry", () => { + expect(() => execFileSync(process.execPath, [resolve(root, "scripts/generate-readme.cjs"), "--check"])).not.toThrow(); +}); + +test("configuration documents every init option and privacy control", () => { + const config = read("src/config.ts"); + const reference = read("docs/CONFIGURATION.md"); + const options = config.split("export interface Options {")[1].split("\n}")[0]; + for (const [, option] of options.matchAll(/\b(\w+)\?:/g)) { + expect(reference).toContain(`\`${option}\``); + } + const privacy = config.split('for (const key of [')[1].split(']')[0]; + for (const [, option] of privacy.matchAll(/"(\w+)"/g)) { + expect(reference).toContain(`\`${option}\``); + } +}); + +test("documentation does not require FI credentials for custom exporters", () => { + expect(read("README.md")).not.toContain("It does not bypass the credential requirement"); + expect(read("docs/CONFIGURATION.md")).toContain("No FI credentials required"); +}); + +test("the shared contract does not claim direct Undici wire capture", () => { + const spec = readFileSync(resolve(repo, "spec/auto-instrumentation/README.md"), "utf8"); + expect(spec).not.toContain("covers undici and every fetch-based SDK"); + expect(spec).toContain("not direct `undici.fetch`/`undici.request`"); +}); + +test("package guide links resolve within the repository", () => { + const prefix = "https://github.com/future-agi/traceAI/blob/dev/"; + for (const name of ["README.md", "docs/CONFIGURATION.md", "docs/FRAMEWORKS.md", "docs/ARCHITECTURE.md"]) { + for (const [, url] of read(name).matchAll(/\]\(([^)]+)\)/g)) { + if (url.startsWith("#") || (/^https?:/.test(url) && !url.startsWith(prefix))) continue; + const target = url.split("#")[0]; + const file = target.startsWith(prefix) ? resolve(repo, target.slice(prefix.length)) : resolve(dirname(resolve(root, name)), target); + expect({ url, exists: existsSync(file) }).toEqual({ url, exists: true }); + } + } +}); From c3bd7910e56b6f13e28af6dd482362c7f3488106 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 03:33:08 -0800 Subject: [PATCH 2/4] fix(codex-plugin): recover turn metadata from rollouts (#618) * fix(codex-plugin): recover turn metadata from rollouts Restore model labels from source-turn contexts and recover evicted function-call arguments/results at terminal export. Preserve privacy and attempt-owned usage, bound recovery memory, and diagnose unavailable content. Co-Authored-By: Claude Code * chore(codex-plugin): release 0.1.1 with the model-name and tool-content fixes Bump @traceai/codex-plugin 0.1.0 -> 0.1.1 (package.json, VERSION, the Codex plugin manifest and the release-please manifest) so the #606 fix reaches npm. The agents registry test now checks that each coding-agent package's manifest entry matches its package.json version instead of hard-coding 0.1.0, so patch releases do not fail it. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Code --- .release-please-manifest.json | 2 +- .../test/integration-registry.test.cjs | 2 +- .../traceai_codex_plugin/package.json | 2 +- .../plugin/.codex-plugin/plugin.json | 2 +- .../traceai_codex_plugin/src/engine.ts | 90 ++-- .../traceai_codex_plugin/src/events.ts | 9 +- .../traceai_codex_plugin/src/index.ts | 2 +- .../traceai_codex_plugin/src/rollout.ts | 93 +++- .../traceai_codex_plugin/test/e2b.cjs | 19 +- .../test/regressions.test.cjs | 399 ++++++++++++++++++ 10 files changed, 571 insertions(+), 49 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 365b297e3..bafcf66b2 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -134,7 +134,7 @@ "python/frameworks/transformers": "0.1.0", "typescript/packages/traceai_agent_core": "0.1.0", "typescript/packages/traceai_agents": "0.1.0", - "typescript/packages/traceai_codex_plugin": "0.1.0", + "typescript/packages/traceai_codex_plugin": "0.1.1", "typescript/packages/traceai_opencode_v1_plugin": "0.1.0", "typescript/packages/traceai_antigravity_plugin": "0.1.0", "typescript/packages/traceai_copilot": "0.1.0", diff --git a/typescript/packages/traceai_agents/test/integration-registry.test.cjs b/typescript/packages/traceai_agents/test/integration-registry.test.cjs index 84240da57..5a42eebf7 100644 --- a/typescript/packages/traceai_agents/test/integration-registry.test.cjs +++ b/typescript/packages/traceai_agents/test/integration-registry.test.cjs @@ -52,7 +52,7 @@ test("all assembled packages have release metadata and explicit build coverage", assert.equal(config.packages[relative]?.["release-type"], "node", dir); assert.equal(config.packages[relative]?.["package-name"], pkg.name, dir); assert.equal(config.packages[relative]?.component, `npm-${pkg.name.replace(/^@/, "").replace("/", "-")}`, dir); - assert.equal(versions[relative], "0.1.0", dir); + assert.equal(versions[relative], pkg.version, dir); assert.ok(scripts["build:consumers"].includes(`--filter ${pkg.name} `), dir); assert.ok(scripts["test:agents"].includes(`--filter ${pkg.name} `), dir); } diff --git a/typescript/packages/traceai_codex_plugin/package.json b/typescript/packages/traceai_codex_plugin/package.json index 5bd6099e1..4442e32ca 100644 --- a/typescript/packages/traceai_codex_plugin/package.json +++ b/typescript/packages/traceai_codex_plugin/package.json @@ -1,6 +1,6 @@ { "name": "@traceai/codex-plugin", - "version": "0.1.0", + "version": "0.1.1", "description": "Native Codex CLI hooks and one-command Future AGI tracing setup", "main": "./dist/index.js", "types": "./dist/index.d.ts", diff --git a/typescript/packages/traceai_codex_plugin/plugin/.codex-plugin/plugin.json b/typescript/packages/traceai_codex_plugin/plugin/.codex-plugin/plugin.json index 17b656e42..9936f9c0f 100644 --- a/typescript/packages/traceai_codex_plugin/plugin/.codex-plugin/plugin.json +++ b/typescript/packages/traceai_codex_plugin/plugin/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "futureagi-tracing", - "version": "0.1.0", + "version": "0.1.1", "description": "Observe Codex user turns, model attempts and tool calls in Future AGI.", "hooks": "./hooks/hooks.json" } diff --git a/typescript/packages/traceai_codex_plugin/src/engine.ts b/typescript/packages/traceai_codex_plugin/src/engine.ts index 553deb2b6..46280550f 100644 --- a/typescript/packages/traceai_codex_plugin/src/engine.ts +++ b/typescript/packages/traceai_codex_plugin/src/engine.ts @@ -148,7 +148,11 @@ export class CodexEngine { string, { handle: ChildHandle; start: Event; index: number } >(); - const tools = new Map(); + const tools = new Map< + string, + { handle: ChildHandle; input?: string; start: Event } + >(); + const toolKey = (e: Event) => JSON.stringify([sourceKey(e), e.tool_use_id]); const children = new Map(); const compacts = new Map(); const laneOf = (e: Event) => @@ -229,7 +233,9 @@ export class CodexEngine { parentId, kind: "llm", name: "codex.model_attempt", - model: e.model, + model: + e.model ?? + reader?.modelAt(e.receivedAt, e.source_turn_id ?? e.turn_id!), startTime: e.receivedAt, timing: "observed-event", sourceTiming: "hook-interval", @@ -273,6 +279,7 @@ export class CodexEngine { .filter(Boolean) .join("\n") || undefined; m.handle.end({ + model: e.model, output: e.status === "failed" ? e.error : output, usage: usage(e), outcome: @@ -286,35 +293,64 @@ export class CodexEngine { models.delete(lane); break; } - case "PreToolUse": - if (e.tool_use_id) - tools.set( - e.tool_use_id, - root.child({ - id: `tool:${e.tool_use_id}`, - parentId, - kind: "tool", - name: e.tool_name, - toolCallId: e.tool_use_id, - input: e.tool_input, - startTime: e.receivedAt, - timing: "observed-event", - sourceTiming: "hook-interval", - }), - ); + case "PreToolUse": { + if (!e.tool_use_id) break; + const input = + e.tool_input ?? reader?.toolCalls.get(e.tool_use_id)?.text; + tools.set(toolKey(e), { + start: e, + input, + handle: root.child({ + id: `tool:${toolKey(e)}`, + parentId, + kind: "tool", + name: e.tool_name, + toolCallId: e.tool_use_id, + input, + startTime: e.receivedAt, + timing: "observed-event", + sourceTiming: "hook-interval", + }), + }); break; + } case "PostToolUse": { - const h = e.tool_use_id ? tools.get(e.tool_use_id) : undefined; - if (h) { - h.end({ - output: e.tool_response, - outcome: - e.failed || reader?.toolResults.get(e.tool_use_id!)?.failed - ? "error" - : "success", + const tool = e.tool_use_id ? tools.get(toolKey(e)) : undefined; + if (tool) { + const result = reader?.toolResults.get(e.tool_use_id!); + const failed = e.failed || result?.failed; + const output = + failed && this.config.hideErrorDetails + ? undefined + : (e.tool_response ?? result?.text); + let gap: string | undefined; + if (tool.input === undefined || output === undefined) { + if (!this.config.captureContent) gap = "TOOL_CONTENT_DISABLED"; + else if ( + (tool.input === undefined && this.config.hideInputs) || + (output === undefined && this.config.hideOutputs) + ) + gap = "TOOL_CONTENT_HIDDEN"; + else if (failed && this.config.hideErrorDetails) + gap = "TOOL_ERROR_DETAILS_HIDDEN"; + else if ( + result?.limited || + reader?.toolCalls.get(e.tool_use_id!)?.limited + ) + gap = "ROLLOUT_TOOL_CONTENT_LIMIT"; + else if (reader?.unsupportedTools.has(e.tool_use_id!)) + gap = "UNSUPPORTED_ROLLOUT_TOOL_CONTENT"; + else if (tool.start.content_truncated || e.content_truncated) + gap = "HOOK_CONTENT_EVICTED_ROLLOUT_UNAVAILABLE"; + else gap = "TOOL_CONTENT_NOT_PROVIDED"; + } + tool.handle.end({ + output, + gap, + outcome: failed ? "error" : "success", endTime: e.receivedAt, }); - tools.delete(e.tool_use_id!); + tools.delete(toolKey(e)); } else state.gap = true; break; } diff --git a/typescript/packages/traceai_codex_plugin/src/events.ts b/typescript/packages/traceai_codex_plugin/src/events.ts index 7e533d7b2..bab3fb1ad 100644 --- a/typescript/packages/traceai_codex_plugin/src/events.ts +++ b/typescript/packages/traceai_codex_plugin/src/events.ts @@ -50,6 +50,13 @@ export interface Event { } const id = (v: unknown): v is string => typeof v === "string" && /^[a-zA-Z0-9_.:-]{1,256}$/.test(v); +/** Model labels are not hook IDs: custom providers use names such as openai/gpt-4.1-mini. */ +export const modelName = (v: unknown): string | undefined => + typeof v === "string" && + /^[a-zA-Z0-9_.:/-]{1,128}$/.test(v) && + !v.includes("://") + ? v + : undefined; /** Shell responses wrap JSON in status text, so they are not complete JSON strings. * Decode balanced object/array fragments before the shared recursive redactor; * otherwise an escaped assignment inside a non-secret field can be overlooked. @@ -148,13 +155,13 @@ export function sanitizeEvent( for (const k of [ "turn_id", "agent_id", - "model", "tool_name", "tool_use_id", "status", "reason", ] as const) if (id(r[k])) event[k] = r[k]; + event.model = modelName(r.model); for (const k of ["transcript_path", "agent_transcript_path"] as const) if (typeof r[k] === "string" && r[k].length < 4096 && r[k].startsWith("/")) event[k] = r[k]; diff --git a/typescript/packages/traceai_codex_plugin/src/index.ts b/typescript/packages/traceai_codex_plugin/src/index.ts index 8b92b5af5..b91924902 100644 --- a/typescript/packages/traceai_codex_plugin/src/index.ts +++ b/typescript/packages/traceai_codex_plugin/src/index.ts @@ -14,7 +14,7 @@ import { type AdapterInspection, } from "@traceai/agent-core"; import { EVENTS } from "./events"; -export const VERSION = "0.1.0"; // x-release-please-version +export const VERSION = "0.1.1"; // x-release-please-version export const HOST_VERSION = "0.167.0"; export const PLUGIN_ID = "futureagi-tracing@futureagi-local"; const exec = promisify(execFile); diff --git a/typescript/packages/traceai_codex_plugin/src/rollout.ts b/typescript/packages/traceai_codex_plugin/src/rollout.ts index 5cde74152..af6b5d13d 100644 --- a/typescript/packages/traceai_codex_plugin/src/rollout.ts +++ b/typescript/packages/traceai_codex_plugin/src/rollout.ts @@ -8,7 +8,12 @@ import { ensurePrivateDirectory, } from "@traceai/agent-core/files"; import type { ResolvedConfig } from "@traceai/agent-core/config"; -import { cleanText, toolFailed } from "./events"; +import { cleanText, modelName, toolFailed } from "./events"; +interface ToolContent { + text?: string; + limited: boolean; + failed?: boolean; +} export interface Message { at: number; turnId?: string; @@ -50,7 +55,38 @@ export class RolloutReader { } gap = false; readonly messages: Message[] = []; - readonly toolResults = new Map(); + readonly toolCalls = new Map(); + readonly toolResults = new Map(); + readonly unsupportedTools = new Set(); + private models: { at: number; turnId: string; model: string }[] = []; + private toolContentBytes = 0; + /** A turn can change model after compaction; never borrow another turn's context. */ + modelAt(at: number, turnId: string): string | undefined { + const contexts = this.models.filter((m) => m.turnId === turnId); + return ( + contexts.filter((m) => m.at <= at).at(-1)?.model ?? contexts[0]?.model + ); + } + private retainToolContent( + entries: Map, + id: string, + text: string | undefined, + failed?: boolean, + ): void { + this.toolContentBytes -= Buffer.byteLength(entries.get(id)?.text ?? ""); + const bytes = Buffer.byteLength(text ?? ""); + // Bound retained memory, not bytes ever seen: repeated rows replace content. + const limited = this.toolContentBytes + bytes > 1024 * 1024; + entries.set(id, { text: limited ? undefined : text, limited, failed }); + if (!limited) this.toolContentBytes += bytes; + if (entries.size > 512) { + const oldest = entries.keys().next().value!; + this.toolContentBytes -= Buffer.byteLength( + entries.get(oldest)?.text ?? "", + ); + entries.delete(oldest); + } + } readonly completed = new Map(); constructor( private path: string, @@ -170,10 +206,23 @@ export class RolloutReader { if (r.type === "session_meta" && p?.id !== this.session) { this.gap = true; this.messages.length = 0; + this.toolCalls.clear(); + this.toolResults.clear(); + this.unsupportedTools.clear(); + this.toolContentBytes = 0; + this.models.length = 0; this.safeCursor = false; return; } - if (r.type === "turn_context") this.turn = p?.turn_id; + if (r.type === "turn_context") { + this.turn = p?.turn_id; + const model = modelName(p?.model), + at = Date.parse(r.timestamp); + if (this.retaining && this.turn && model && Number.isFinite(at)) { + this.models.push({ at, turnId: this.turn, model }); + if (this.models.length > 512) this.models.shift(); + } + } if (r.type === "event_msg" && p?.type === "task_started") this.turn = p.turn_id; this.targetSeen ||= @@ -202,19 +251,33 @@ export class RolloutReader { // A per-turn cursor may scan old history, but unrelated messages and // tool results must neither consume this turn's budget nor mark gaps. if (this.targetTurn && messageTurn !== this.targetTurn) continue; + // Custom tools have distinct failure envelopes. Do not recover their raw + // output using shell failure semantics; explain the missing content instead. + if ( + ["custom_tool_call", "custom_tool_call_output"].includes(p?.type) && + typeof p.call_id === "string" + ) { + this.unsupportedTools.add(p.call_id); + if (this.unsupportedTools.size > 512) + this.unsupportedTools.delete(this.unsupportedTools.values().next().value!); + } if ( p?.type === "function_call_output" && typeof p.call_id === "string" ) { - this.toolResults.set(p.call_id, { - failed: toolFailed( - typeof p.output === "string" - ? p.output - : JSON.stringify(p.output), - ), - }); - if (this.toolResults.size > 512) - this.toolResults.delete(this.toolResults.keys().next().value!); + const failed = toolFailed( + typeof p.output === "string" + ? p.output + : JSON.stringify(p.output), + ); + this.retainToolContent( + this.toolResults, + p.call_id, + failed && this.config.hideErrorDetails + ? undefined + : cleanText(p.output, this.config, true), + failed, + ); } const call = p?.type === "function_call"; if ( @@ -235,6 +298,12 @@ export class RolloutReader { this.gap = true; } } else if (call) argumentsValue = p.arguments; + if (call && typeof p.call_id === "string") + this.retainToolContent( + this.toolCalls, + p.call_id, + cleanText(argumentsValue, this.config), + ); const text = call ? cleanText( { tool: p.name, arguments: argumentsValue }, diff --git a/typescript/packages/traceai_codex_plugin/test/e2b.cjs b/typescript/packages/traceai_codex_plugin/test/e2b.cjs index 1e26a6048..04de8a807 100644 --- a/typescript/packages/traceai_codex_plugin/test/e2b.cjs +++ b/typescript/packages/traceai_codex_plugin/test/e2b.cjs @@ -17,6 +17,7 @@ const delay = (ms) => new Promise((r) => setTimeout(r, ms)); const nested = process.env.FI_TEST_NESTED === "true"; const nestedReuse = process.env.FI_TEST_NESTED_REUSE === "true"; const longTurn = process.env.FI_TEST_LONG_TURN === "true"; +const model = process.env.FI_TEST_MODEL ?? "gpt-5.1-codex"; const privateMarker = "native-synthetic-private-marker"; const fixtureMessages = (inputs) => inputs @@ -115,7 +116,7 @@ async function main() { response: { id: "resp_interrupt", object: "response", - model: "gpt-5.1-codex", + model, status: "in_progress", output: [], }, @@ -140,7 +141,7 @@ async function main() { }) + "\n", ).toString("base64"); const command = longTurn - ? `printf step-${count}` + ? `printf step-${count}; printf '%03000d' 0` : `printf '%s' '${encoded}' | base64 -d; exit 7`; const args = shell?.name === "exec_command" @@ -280,7 +281,7 @@ async function main() { id: "resp_" + count, object: "response", created_at: 1, - model: "gpt-5.1-codex", + model, status: "in_progress", output: [], }; @@ -331,7 +332,7 @@ async function main() { process.env.FI_API_KEY = "dummy-fi-api"; process.env.FI_SECRET_KEY = "dummy-fi-secret"; process.env.FI_OTLP_ENDPOINT = `http://127.0.0.1:${port}/tracer/v1/traces`; - const config = `model = "gpt-5.1-codex"\nmodel_provider = "mock"\n[model_providers.mock]\nname = "Local Responses"\nbase_url = "http://127.0.0.1:${port}/v1"\nwire_api = "responses"\nenv_key = "MOCK_API_KEY"\nsupports_websockets = false\n[analytics]\nenabled = false\n[feedback]\nenabled = false\n`; + const config = `model = ${JSON.stringify(model)}\nmodel_provider = "mock"\n[model_providers.mock]\nname = "Local Responses"\nbase_url = "http://127.0.0.1:${port}/v1"\nwire_api = "responses"\nenv_key = "MOCK_API_KEY"\nsupports_websockets = false\n[analytics]\nenabled = false\n[feedback]\nenabled = false\n`; await fs.writeFile(home + "/.codex/config.toml", config, { mode: 0o600 }); const cli = process.env.FI_TEST_CLI ?? @@ -539,6 +540,16 @@ async function main() { assert( toolSpans.every((s) => attrs(s)["tool.name"] && attrs(s)["tool_call.id"]), ); + assert( + spans + .filter((s) => s.name === "codex.model_attempt") + .every((s) => attrs(s)["gen_ai.request.model"] === model), + "every native request has the actual model", + ); + assert( + toolSpans.every((s) => attrs(s)["input.value"] && attrs(s)["output.value"]), + "every completed native tool has arguments and result, including evicted early hooks", + ); if (longTurn) { assert.equal(requests.length, 41); assert(toolSpans.every((s) => attrs(s)["fi.agent.outcome"] === "success")); diff --git a/typescript/packages/traceai_codex_plugin/test/regressions.test.cjs b/typescript/packages/traceai_codex_plugin/test/regressions.test.cjs index 795838499..8b757d204 100644 --- a/typescript/packages/traceai_codex_plugin/test/regressions.test.cjs +++ b/typescript/packages/traceai_codex_plugin/test/regressions.test.cjs @@ -1189,6 +1189,405 @@ test("nested serialized secrets and escaped assignments never escape direct or r assert(body.includes("visible-safe-result")); }); +test("issue 606 accepts provider-qualified hook model names", () => { + const raw = { + hook_event_name: "PreModelRequest", + session_id: "s", + cwd: "/work", + }; + assert.equal( + sanitizeEvent( + { ...raw, model: "openai/gpt-4.1-mini" }, + { captureContent: false }, + ).model, + "openai/gpt-4.1-mini", + ); + for (const model of [ + "https://private.example/model", + "model\nprivate", + "x".repeat(129), + ]) + assert.equal( + sanitizeEvent({ ...raw, model }, { captureContent: false }).model, + undefined, + ); +}); + +test("issue 606 recovers turn-scoped models and evicted Bash content from real rollout shapes", async (t) => { + const f = await fixture(t); + const { CodexEngine } = require("../dist/engine.js"); + const transcript = path.join(f.env.CODEX_HOME, "sessions/content.jsonl"); + const store = new EventStore(f.config); + const events = []; + const add = async (hook_event_name, extra = {}) => { + const e = sanitizeEvent( + { + hook_event_name, + session_id: "s", + turn_id: "t", + cwd: f.repo, + transcript_path: transcript, + ...extra, + }, + f.config, + ); + events.push(e); + await store.append(e); + }; + let rollout = + row("session_meta", { id: "s" }) + + row("turn_context", { turn_id: "old", model: "wrong-old-model" }) + + row("turn_context", { turn_id: "t", model: "openai/gpt-4.1-mini" }); + await add("UserPromptSubmit", { prompt: "long tool turn" }); + for (let i = 0; i < 29; i++) { + const call_id = `call-${i}`; + const input = { + cmd: `printf visible-input-${i}`, + password: "PRIVATE_ARGUMENT", + }; + const output = + `Process exited with code 0\nFinal output:\nvisible-output-${i} ` + + "x".repeat(3000) + + '\nPASSWORD="PRIVATE_RESULT"'; + await add("PreModelRequest"); // Codex 0.167.0 does not supply the model here. + await add("PostModelRequest", { + status: "completed", + token_usage: { input_tokens: 20, output_tokens: 8 }, + }); + await add("PreToolUse", { + tool_name: "Bash", + tool_use_id: call_id, + tool_input: input, + }); + await add("PostToolUse", { + tool_name: "Bash", + tool_use_id: call_id, + tool_response: output, + }); + const metadata = { turn_id: "t" }; + rollout += row("response_item", { + type: "function_call", + status: "completed", + id: `fc-${i}`, + name: "exec_command", + arguments: JSON.stringify(input), + call_id, + internal_chat_message_metadata_passthrough: metadata, + }); + rollout += row("response_item", { + type: "function_call_output", + id: null, + call_id, + output, + internal_chat_message_metadata_passthrough: metadata, + }); + } + rollout += + row("event_msg", { type: "task_complete", turn_id: "t" }) + + row("turn_context", { turn_id: "next", model: "wrong-next-model" }); + await fs.writeFile(transcript, rollout, { mode: 0o600 }); + const pending = await store.take(events[0]); + assert( + pending.events.some( + (e) => + e.hook_event_name === "PreToolUse" && + e.content_truncated && + e.tool_input === undefined, + ), + "exercise actual journal eviction", + ); + const engine = new CodexEngine(f.config); + for (const e of pending.events) await engine.accept(e); + await engine.accept({ + ...events[0], + hook_event_name: "Stop", + receivedAt: Date.now(), + }); + await engine.close(); + const spans = flatten(f), + models = spans.filter((s) => s.name === "codex.model_attempt"), + tools = spans.filter((s) => s.name === "Bash"); + assert.equal(models.length, 29); + await t.test("every attempt uses its own turn_context model", () => { + assert( + models.every( + (s) => attrs(s)["gen_ai.request.model"] === "openai/gpt-4.1-mini", + ), + ); + }); + await t.test( + "all 29 tools retain input and output after journal eviction", + () => { + assert.equal(tools.length, 29); + for (let i = 0; i < tools.length; i++) { + const a = attrs( + tools.find((s) => attrs(s)["tool_call.id"] === `call-${i}`), + ); + assert( + a["input.value"]?.includes(`visible-input-${i}`), + `missing input ${i}`, + ); + assert( + a["output.value"]?.includes(`visible-output-${i}`), + `missing output ${i}`, + ); + assert.equal(a["fi.agent.gap"], undefined); + } + }, + ); + assert(!JSON.stringify(spans).includes("PRIVATE_ARGUMENT")); + assert(!JSON.stringify(spans).includes("PRIVATE_RESULT")); + const { checkShape } = require("@traceai/agent-core/test/conformance"); + checkShape( + f.received.map((r) => r.body), + { calls: 29, tools: 29, inputTokens: 580, outputTokens: 232 }, + ); +}); + +for (const policy of [ + {}, + { captureContent: false }, + { hideInputs: true }, + { hideOutputs: true }, + { hideErrorDetails: true }, +]) { + test(`issue 606 rollout recovery honors privacy ${JSON.stringify(policy)}`, async (t) => { + const f = await fixture(t); + await put(path.join(f.repo, ".codex/futureagi.json"), { + schemaVersion: 1, + captureContent: policy.captureContent ?? true, + }); + const config = await core.resolveConfig({ + ...f.options, + env: { + ...f.env, + FI_HIDE_INPUTS: String(policy.hideInputs ?? false), + FI_HIDE_OUTPUTS: String(policy.hideOutputs ?? false), + FI_HIDE_ERROR_DETAILS: String(policy.hideErrorDetails ?? false), + }, + }); + const transcript = path.join( + f.env.CODEX_HOME, + "sessions/privacy-recovery.jsonl", + ); + await fs.writeFile( + transcript, + row("session_meta", { id: "s" }) + + row("turn_context", { turn_id: "t", model: "openai/gpt-4.1-mini" }) + + row("response_item", { + type: "function_call", + call_id: "call", + name: "exec_command", + arguments: JSON.stringify({ + cmd: "visible-argument", + password: "PRIVATE_ARGUMENT", + }), + }) + + row("response_item", { + type: "function_call_output", + call_id: "call", + output: + 'Process exited with code 7\nvisible-result PASSWORD="PRIVATE_RESULT"', + }), + { mode: 0o600 }, + ); + const { CodexEngine } = require("../dist/engine.js"), + engine = new CodexEngine(config); + for (const hook_event_name of [ + "UserPromptSubmit", + "PreModelRequest", + "PostModelRequest", + "PreToolUse", + "PostToolUse", + "Stop", + ]) { + await engine.accept( + sanitizeEvent( + { + hook_event_name, + session_id: "s", + turn_id: "t", + cwd: f.repo, + transcript_path: transcript, + tool_name: "Bash", + tool_use_id: "call", + status: "completed", + }, + config, + ), + ); + } + await engine.close(); + const tool = attrs(flatten(f).find((s) => s.name === "Bash")); + assert.equal(tool["fi.agent.outcome"], "error"); + assert.equal( + tool["input.value"]?.includes("visible-argument") ?? false, + config.captureContent && !config.hideInputs, + ); + assert.equal( + tool["output.value"]?.includes("visible-result") ?? false, + config.captureContent && !config.hideOutputs && !config.hideErrorDetails, + ); + assert.equal( + typeof tool["fi.agent.gap"], + Object.keys(policy).length ? "string" : "undefined", + ); + assert(!JSON.stringify(flatten(f)).includes("PRIVATE_ARGUMENT")); + assert(!JSON.stringify(flatten(f)).includes("PRIVATE_RESULT")); + assert.equal( + attrs(flatten(f).find((s) => s.name === "codex.model_attempt"))[ + "gen_ai.request.model" + ], + "openai/gpt-4.1-mini", + ); + }); +} + +test("issue 606 bounded recovery reports missing tool content instead of silently empty spans", async (t) => { + const f = await fixture(t); + const transcript = path.join( + f.env.CODEX_HOME, + "sessions/bounded-content.jsonl", + ); + let data = + row("session_meta", { id: "s" }) + + row("turn_context", { turn_id: "t", model: "openai/gpt-4.1-mini" }); + for (let i = 0; i < 60; i++) + data += row("response_item", { + type: "function_call_output", + call_id: `large-${i}`, + output: "x".repeat(20000), + }); + data += row("response_item", { + type: "custom_tool_call", + call_id: "custom", + name: "apply_patch", + input: "visible-patch", + }); + data += row("response_item", { + type: "custom_tool_call_output", + call_id: "custom", + output: "visible-patch-result", + }); + await fs.writeFile(transcript, data, { mode: 0o600 }); + const { CodexEngine } = require("../dist/engine.js"), + engine = new CodexEngine(f.config); + const emit = (hook_event_name, rest = {}) => + engine.accept( + sanitizeEvent( + { + hook_event_name, + session_id: "s", + turn_id: "t", + cwd: f.repo, + transcript_path: transcript, + ...rest, + }, + f.config, + ), + ); + await emit("UserPromptSubmit"); + for (const tool_use_id of ["large-59", "missing", "custom"]) { + await emit("PreToolUse", { tool_use_id, tool_name: "Bash" }); + await emit("PostToolUse", { tool_use_id }); + } + await emit("Stop"); + await engine.close(); + const tools = flatten(f) + .filter((s) => s.name === "Bash") + .map(attrs); + assert.equal(tools[0]["fi.agent.gap"], "ROLLOUT_TOOL_CONTENT_LIMIT"); + assert.equal(tools[1]["fi.agent.gap"], "TOOL_CONTENT_NOT_PROVIDED"); + assert.equal(tools[2]["fi.agent.gap"], "UNSUPPORTED_ROLLOUT_TOOL_CONTENT"); + assert.equal(tools[2]["input.value"], undefined); + assert.equal(tools[2]["output.value"], undefined); +}); + +test("issue 606 repeated rollout rows do not exhaust the retained-content budget", async (t) => { + const f = await fixture(t), + transcript = path.join(f.env.CODEX_HOME, "sessions/repeated-content.jsonl"); + const repeated = row("response_item", { + type: "function_call_output", + call_id: "same", + output: "x".repeat(20000), + }); + await fs.writeFile( + transcript, + row("session_meta", { id: "s" }) + + row("turn_context", { turn_id: "t", model: "mock" }) + + repeated.repeat(60), + { mode: 0o600 }, + ); + const reader = new RolloutReader(transcript, "s", f.config, "t"); + await reader.read(); + assert.equal(reader.toolResults.size, 1); + assert.equal(reader.toolResults.get("same").text.length, 20000); + assert.equal(reader.toolResults.get("same").limited, false); +}); + +test("issue 606 model changes and identical tool IDs stay scoped to source turn", async (t) => { + const f = await fixture(t), + transcript = path.join(f.env.CODEX_HOME, "sessions/scoped-content.jsonl"); + const at = (timestamp, type, payload) => + JSON.stringify({ timestamp, type, payload }) + "\n"; + const data = + row("session_meta", { id: "s" }) + + at("2026-11-06T00:00:00Z", "turn_context", { + turn_id: "t", + model: "first/model", + }) + + at("2026-11-06T00:00:02Z", "turn_context", { + turn_id: "t", + model: "second/model", + }) + + row("response_item", { + type: "function_call", + call_id: "same", + arguments: '{"cmd":"target-input"}', + }) + + row("response_item", { + type: "function_call_output", + call_id: "same", + output: "target-output", + }) + + row("turn_context", { turn_id: "other", model: "wrong/model" }) + + row("response_item", { + type: "function_call", + call_id: "same", + arguments: '{"cmd":"wrong-input"}', + }) + + row("response_item", { + type: "function_call_output", + call_id: "same", + output: "wrong-output", + }); + await fs.writeFile(transcript, data, { mode: 0o600 }); + const reader = new RolloutReader(transcript, "s", f.config, "t"); + await reader.read(); + assert.equal( + reader.modelAt(Date.parse("2026-11-06T00:00:01Z"), "t"), + "first/model", + ); + assert.equal( + reader.modelAt(Date.parse("2026-11-06T00:00:03Z"), "t"), + "second/model", + ); + assert.equal(reader.modelAt(Date.now(), "other"), undefined); + assert.equal(reader.toolCalls.get("same").text, '{"cmd":"target-input"}'); + assert.equal(reader.toolResults.get("same").text, "target-output"); + await reader.checkpoint(); + for (const name of await fs.readdir(f.config.paths.stateDir)) { + const saved = await fs.readFile( + path.join(f.config.paths.stateDir, name), + "utf8", + ); + assert( + !saved.includes("target-input") && !saved.includes("target-output"), + "no rollout content persisted", + ); + } +}); + for (const recover of [false, true]) { test(`unified core reports terminal failure and successful later retry (recover=${recover})`, async (t) => { const f = await fixture(t); From 3e96029209231463ffc7f01087345de65ea66023 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 03:33:58 -0800 Subject: [PATCH 3/4] fix(ci): align release contracts and preserve audio cache counts (#620) * fix(ci): align release contracts and preserve audio cache counts Co-Authored-By: Claude Code * test(ci): exercise candidate core and complete privacy contracts Co-Authored-By: Claude Code * test(core): honor shared privacy in native message contracts Co-Authored-By: Claude Code --------- Co-authored-by: Claude Code --- .github/workflows/google-genai-sdk-compat.yml | 19 ++++++- .release-please-manifest.json | 2 +- spec/auto-instrumentation/privacy.json | 11 +++- typescript/packages/fi-core/CHANGELOG.md | 4 ++ typescript/packages/fi-core/package.json | 2 +- .../src/__tests__/audioCacheCount.test.ts | 55 +++++++++++++++++++ .../privacyRuntimePerfEquivalence.test.ts | 4 +- typescript/packages/fi-core/src/privacy.json | 11 +++- .../fi-core/test/genai-privacy.test.cjs | 44 ++++++++++----- .../traceai_auto/src/wire/privacy.json | 11 +++- .../traceai_codex_sdk/contract/otlp_wire.mjs | 12 +++- .../test/release-regressions.test.cjs | 19 +++++-- .../test/regressions.test.cjs | 1 + .../traceai_langchain/contract/readme.mjs | 5 +- .../src/__tests__/openai.test.ts | 26 ++++++--- 15 files changed, 184 insertions(+), 42 deletions(-) create mode 100644 typescript/packages/fi-core/src/__tests__/audioCacheCount.test.ts diff --git a/.github/workflows/google-genai-sdk-compat.yml b/.github/workflows/google-genai-sdk-compat.yml index 18370f66d..9b9ae5dd2 100644 --- a/.github/workflows/google-genai-sdk-compat.yml +++ b/.github/workflows/google-genai-sdk-compat.yml @@ -33,7 +33,18 @@ jobs: - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node }} - - name: Build and pack with published shared dependencies + - name: Build and pack candidate shared dependencies + working-directory: typescript + shell: bash + run: | + set -euo pipefail + npm install --global pnpm@10.30.1 + pnpm --filter @traceai/fi-core... install --frozen-lockfile --ignore-scripts + pnpm --filter @traceai/fi-semantic-conventions run build + pnpm --filter @traceai/fi-core run build + pnpm --dir packages/fi-semantic-conventions pack --out "$RUNNER_TEMP/semconv.tgz" + pnpm --dir packages/fi-core pack --out "$RUNNER_TEMP/core.tgz" + - name: Build adapter against published shared dependencies shell: bash run: | set -euo pipefail @@ -50,8 +61,12 @@ jobs: mkdir "$RUNNER_TEMP/consumer" cd "$RUNNER_TEMP/consumer" npm init -y + # Exercise this PR's core fix, including the legacy coexistence adapter, + # rather than silently resolving the already-published broken core. + npm pkg set 'overrides.@traceai/fi-core=$@traceai/fi-core' 'overrides.@traceai/fi-semantic-conventions=$@traceai/fi-semantic-conventions' tarball=$(find "$RUNNER_TEMP" -maxdepth 1 -name 'traceai-google-genai-sdk-*.tgz' -print) - npm install --ignore-scripts "$tarball" '@google/genai@${{ matrix.sdk }}' '@opentelemetry/sdk-trace-node@2.0.1' 'typescript@5.9.3' '@types/node@22' '@traceai/google-genai@0.1.0' '@google/generative-ai@0.24.1' + npm install --ignore-scripts "$tarball" "$RUNNER_TEMP/core.tgz" "$RUNNER_TEMP/semconv.tgz" '@google/genai@${{ matrix.sdk }}' '@opentelemetry/sdk-trace-node@2.0.1' 'typescript@5.9.3' '@types/node@22' '@traceai/google-genai@0.1.0' '@google/generative-ai@0.24.1' + npm ls @traceai/fi-core @traceai/fi-semantic-conventions - name: Real SDK, OTLP, privacy and exact customer snippet without internet shell: bash env: diff --git a/.release-please-manifest.json b/.release-please-manifest.json index bafcf66b2..41ee3b0b8 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -70,7 +70,7 @@ "python/frameworks/weaviate": "0.1.2", "python/frameworks/xai": "0.1.1", "python/traceai": "0.1.0", - "typescript/packages/fi-core": "1.2.1", + "typescript/packages/fi-core": "1.2.2", "typescript/packages/fi-semantic-conventions": "1.1.0", "typescript/packages/traceai_anthropic": "0.1.5", "typescript/packages/traceai_auto": "0.1.0", diff --git a/spec/auto-instrumentation/privacy.json b/spec/auto-instrumentation/privacy.json index 319aad9e2..eac602779 100644 --- a/spec/auto-instrumentation/privacy.json +++ b/spec/auto-instrumentation/privacy.json @@ -1,17 +1,17 @@ { "version": 3, "scalar_metrics": { - "version": 5, + "version": 6, "canonical_decimal": { "ruling": "LANE-CALL-NIKM4-5A-I1-DIGIT-STRING-COUNTS-r2 with I1-R10B A-DIGIT-CONFINED", "regex": "^(0|[1-9][0-9]{0,15})$", "max_chars": 16, "base64_min_chars": 4, "keys": ["gen_ai.audio.bytes"], - "scope": "Only typed byte counters consult this rule. gen_ai.audio.bytes keeps full canonical decimal strings with a safe-integer numeric value unless they have base64 shape at or above base64_min_chars. elevenlabs.audio.bytes never grants a string role. The four-character shape threshold is not a special case for one count. Preserve accepted string types; no signs, leading zeros, fractions, exponents, whitespace or final newline. Other G4 core/detail keys retain their original scalar roles, including arbitrary strings and literal undefined. This rule does not change Q8b NON_CONTENT types." + "scope": "Only declared canonical-decimal counters consult this rule. gen_ai.audio.bytes keeps full canonical decimal strings with a safe-integer numeric value unless they have base64 shape at or above base64_min_chars. elevenlabs.audio.bytes never grants a string role. The four-character shape threshold is not a special case for one count. Preserve accepted string types; no signs, leading zeros, fractions, exponents, whitespace or final newline. Other G4 core/detail keys retain their original scalar roles, including arbitrary strings and literal undefined. This rule does not change Q8b NON_CONTENT types." }, "ruling": "TRACEAI-I1-G3-G4-POLICY-SCOPE-RULING-r1-FISEC G4", - "scope": "Closed exact complete keys in the declared usage/metrics containers only. Case, punctuation, prefixes, suffixes and array indices are not aliases. A nested object path must equal the complete key. gen_ai.audio and elevenlabs.audio are metric containers only for their listed bytes counters, not for arbitrary audio members. Their nonnegative_safe_integer value_type grants a role to finite nonnegative safe-integer numbers; only gen_ai.audio.bytes additionally accepts strings under canonical_decimal. All other inputs on these two byte counters retain the role-free media policy. Other declared metrics keep their original number/boolean/string roles without decimal validation.", + "scope": "Closed exact complete keys in the declared usage/metrics containers only. Case, punctuation, prefixes, suffixes and array indices are not aliases. A nested object path must equal the complete key. gen_ai.audio and elevenlabs.audio are metric containers only for their listed bytes counters, not for arbitrary audio members. Their nonnegative_safe_integer value_type grants a role to finite nonnegative safe-integer numbers; only gen_ai.audio.bytes additionally accepts strings under canonical_decimal. gen_ai.usage.cache_read_tokens.audio also accepts only nonnegative safe-integer numbers, never strings. All other inputs on these typed counters retain the role-free media policy. Other declared metrics keep their original number/boolean/string roles without decimal validation.", "precedence": "Scalar role only removes structural media classification caused by the metric spelling. Explicit media/type hints on any ancestor, inherited media/audio, established media payload ancestry, credential ancestry and known numeric/string secrets take precedence. On the two typed byte counters only, base64-shaped strings at or above canonical_decimal.base64_min_chars cannot obtain a role, even when numerically safe. Magic bytes, data URIs and other independent value checks still apply. A counter leaf under established media payload ancestry cannot use the usage metadata boundary to escape omission. Private payload-role ancestry survives parsed, stringified and diagnostic JSON handoffs; resetting a JSON root never grants a metric role. Metric-looking descendants reached through this retained payload origin remain payload, including numeric/bool scalars and numeric/bool arrays; ordinary metadata text boundaries are unchanged.", "arrays": "Arrays never receive the scalar metric role. Nonempty numeric/bool media payload arrays are omitted; existing string/object array walking and empty-array behavior remain unchanged.", "containers": [ @@ -28,6 +28,11 @@ "gen_ai.usage.output_tokens.reasoning" ] }, + { + "path": "gen_ai.usage", + "keys": ["gen_ai.usage.cache_read_tokens.audio"], + "value_type": "nonnegative_safe_integer" + }, { "path": "gen_ai.audio", "keys": ["gen_ai.audio.bytes"], diff --git a/typescript/packages/fi-core/CHANGELOG.md b/typescript/packages/fi-core/CHANGELOG.md index 8ab205788..8256e3551 100644 --- a/typescript/packages/fi-core/CHANGELOG.md +++ b/typescript/packages/fi-core/CHANGELOG.md @@ -1,3 +1,7 @@ +## [1.2.2] - pending release +### Fix +- Preserve numeric `gen_ai.usage.cache_read_tokens.audio` counts through admission, projection and export. The 1.2.0 shared privacy runtime mistook this modality count for an audio payload. Only nonnegative safe integers receive the metric role; strings, arrays, media ancestry and registered secrets retain their existing privacy protections. + ## [1.2.1] - pending release ### Fix - **Spans no longer carry the process command line or the OS user.** 1.2.0 added OpenTelemetry's full process detector to every provider resource, so `process.command_args`, `process.command`, `process.owner`, `process.executable.path` and `process.pid` were exported with every span. Command-line flags can hold secrets. By default fi-core now detects only `process.runtime.name`, `process.runtime.version` and `process.runtime.description`, as it detected nothing before 1.2.0. diff --git a/typescript/packages/fi-core/package.json b/typescript/packages/fi-core/package.json index a18f3482f..e8fce8874 100644 --- a/typescript/packages/fi-core/package.json +++ b/typescript/packages/fi-core/package.json @@ -1,6 +1,6 @@ { "name": "@traceai/fi-core", - "version": "1.2.1", + "version": "1.2.2", "description": "OpenTelemetry tracing for AI applications: tracer setup, span helpers, and exporters for Future AGI.", "main": "./dist/src/index.js", "module": "./dist/esm/index.js", diff --git a/typescript/packages/fi-core/src/__tests__/audioCacheCount.test.ts b/typescript/packages/fi-core/src/__tests__/audioCacheCount.test.ts new file mode 100644 index 000000000..7bd459d3f --- /dev/null +++ b/typescript/packages/fi-core/src/__tests__/audioCacheCount.test.ts @@ -0,0 +1,55 @@ +import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"; +import { privacyFilter } from "../export-privacy"; +import { projectAttributes } from "../attribute-projection"; +import { indexPrivacyHints, mediaReplacement, scrubValue } from "../privacy-runtime"; +import { FITracer } from "../trace/trace-config/FITracer"; + +const key = "gen_ai.usage.cache_read_tokens.audio"; + +test.each([false, true])("audio cache counts survive admission and export with hiding=%s", async hidden => { + const exporter = new InMemorySpanExporter(); + const provider = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] }); + const traceConfig = { hideInputs: hidden, hideOutputs: hidden }; + try { + const tracer = new FITracer({ tracer: provider.getTracer("audio-cache-count"), traceConfig }); + for (const value of [0, 2, Number.MAX_SAFE_INTEGER]) { + expect(scrubValue(value, [], key)).toBe(value); + expect(projectAttributes({ [key]: value }, 16).attributes[key]).toBe(value); + const span = tracer.startSpan("cache-count", { attributes: { + [key]: value, "input.value": "PRIVATE_INPUT", "output.value": "PRIVATE_OUTPUT", + } }); + span.end(); + const admitted = exporter.getFinishedSpans().at(-1)!; + expect(admitted.attributes[key]).toBe(value); + const first = privacyFilter(traceConfig).span(admitted); + for (const exported of [first, privacyFilter(traceConfig).span(first)]) { + expect(exported.attributes[key]).toBe(value); + if (hidden) expect(JSON.stringify(exported.attributes)).not.toMatch(/PRIVATE_INPUT|PRIVATE_OUTPUT/); + } + } + } finally { await provider.shutdown(); } +}); + +test.each([true, false, -1, 0.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1, [2]])( + "audio cache metric role rejects non-count %s", value => { + expect(mediaReplacement(value, key)).toBe(""); + expect(scrubValue(value, [], key)).toBe(""); + }, +); + +test.each(["2", "12345678", "AQIDBAUGBwgJCgsM", "private audio payload!"])( + "audio cache metric role never exempts string %s", value => { + expect(mediaReplacement(value, key)).toMatch(/^ { + expect(scrubValue(12345678, ["12345678"], key)).toBe(""); + expect(scrubValue(2, [], `secret.${key}`)).toBe(""); + expect(mediaReplacement(2, `custom.${key}`)).toBe(""); + expect(mediaReplacement(2, key, indexPrivacyHints([["type", "input_audio"]]))).toBe(""); + expect(scrubValue({ audio: { data: { [key]: 2 } } })).toEqual({ + audio: { data: { [key]: "" } }, + }); +}); diff --git a/typescript/packages/fi-core/src/__tests__/privacyRuntimePerfEquivalence.test.ts b/typescript/packages/fi-core/src/__tests__/privacyRuntimePerfEquivalence.test.ts index c7ab3097f..e9ec8dbc8 100644 --- a/typescript/packages/fi-core/src/__tests__/privacyRuntimePerfEquivalence.test.ts +++ b/typescript/packages/fi-core/src/__tests__/privacyRuntimePerfEquivalence.test.ts @@ -243,7 +243,9 @@ const ORIGINAL_BARE_MEDIA = String.raw`function bareMedia(value: string): string }`; const PARENT_RUNTIME_SHA256 = "d4601e3aff870d917336c78510ffa0544eb62204383d8e429c7ab489fc7efc17"; const BASE_RUNTIME_SHA256 = "411d30cc45c3cdc801a6a9e172ddd3cf41a6ffdc4b193861cec6962a067b95a9"; -const BASE_CATALOG_SHA256 = "2ab8d4d7618a27612251e6195c49f0a824431f2b7f34dddb0e35ef2e12946b9c"; +// fi-core 1.2.2: rebase both runtime oracles onto scalar catalog v6. The +// algorithm is unchanged; audioCacheCount.test.ts verifies the new typed key. +const BASE_CATALOG_SHA256 = "9da3fef3a84741f8cbe345a44f6a2f8c6aa7737fdf3c1a91d590f271eadb138f"; const source = readFileSync(join(__dirname, "..", "privacy-runtime.ts"), "utf8"); const catalogSource = readFileSync(join(__dirname, "..", "privacy.json"), "utf8"); const catalog = JSON.parse(catalogSource); diff --git a/typescript/packages/fi-core/src/privacy.json b/typescript/packages/fi-core/src/privacy.json index 319aad9e2..eac602779 100644 --- a/typescript/packages/fi-core/src/privacy.json +++ b/typescript/packages/fi-core/src/privacy.json @@ -1,17 +1,17 @@ { "version": 3, "scalar_metrics": { - "version": 5, + "version": 6, "canonical_decimal": { "ruling": "LANE-CALL-NIKM4-5A-I1-DIGIT-STRING-COUNTS-r2 with I1-R10B A-DIGIT-CONFINED", "regex": "^(0|[1-9][0-9]{0,15})$", "max_chars": 16, "base64_min_chars": 4, "keys": ["gen_ai.audio.bytes"], - "scope": "Only typed byte counters consult this rule. gen_ai.audio.bytes keeps full canonical decimal strings with a safe-integer numeric value unless they have base64 shape at or above base64_min_chars. elevenlabs.audio.bytes never grants a string role. The four-character shape threshold is not a special case for one count. Preserve accepted string types; no signs, leading zeros, fractions, exponents, whitespace or final newline. Other G4 core/detail keys retain their original scalar roles, including arbitrary strings and literal undefined. This rule does not change Q8b NON_CONTENT types." + "scope": "Only declared canonical-decimal counters consult this rule. gen_ai.audio.bytes keeps full canonical decimal strings with a safe-integer numeric value unless they have base64 shape at or above base64_min_chars. elevenlabs.audio.bytes never grants a string role. The four-character shape threshold is not a special case for one count. Preserve accepted string types; no signs, leading zeros, fractions, exponents, whitespace or final newline. Other G4 core/detail keys retain their original scalar roles, including arbitrary strings and literal undefined. This rule does not change Q8b NON_CONTENT types." }, "ruling": "TRACEAI-I1-G3-G4-POLICY-SCOPE-RULING-r1-FISEC G4", - "scope": "Closed exact complete keys in the declared usage/metrics containers only. Case, punctuation, prefixes, suffixes and array indices are not aliases. A nested object path must equal the complete key. gen_ai.audio and elevenlabs.audio are metric containers only for their listed bytes counters, not for arbitrary audio members. Their nonnegative_safe_integer value_type grants a role to finite nonnegative safe-integer numbers; only gen_ai.audio.bytes additionally accepts strings under canonical_decimal. All other inputs on these two byte counters retain the role-free media policy. Other declared metrics keep their original number/boolean/string roles without decimal validation.", + "scope": "Closed exact complete keys in the declared usage/metrics containers only. Case, punctuation, prefixes, suffixes and array indices are not aliases. A nested object path must equal the complete key. gen_ai.audio and elevenlabs.audio are metric containers only for their listed bytes counters, not for arbitrary audio members. Their nonnegative_safe_integer value_type grants a role to finite nonnegative safe-integer numbers; only gen_ai.audio.bytes additionally accepts strings under canonical_decimal. gen_ai.usage.cache_read_tokens.audio also accepts only nonnegative safe-integer numbers, never strings. All other inputs on these typed counters retain the role-free media policy. Other declared metrics keep their original number/boolean/string roles without decimal validation.", "precedence": "Scalar role only removes structural media classification caused by the metric spelling. Explicit media/type hints on any ancestor, inherited media/audio, established media payload ancestry, credential ancestry and known numeric/string secrets take precedence. On the two typed byte counters only, base64-shaped strings at or above canonical_decimal.base64_min_chars cannot obtain a role, even when numerically safe. Magic bytes, data URIs and other independent value checks still apply. A counter leaf under established media payload ancestry cannot use the usage metadata boundary to escape omission. Private payload-role ancestry survives parsed, stringified and diagnostic JSON handoffs; resetting a JSON root never grants a metric role. Metric-looking descendants reached through this retained payload origin remain payload, including numeric/bool scalars and numeric/bool arrays; ordinary metadata text boundaries are unchanged.", "arrays": "Arrays never receive the scalar metric role. Nonempty numeric/bool media payload arrays are omitted; existing string/object array walking and empty-array behavior remain unchanged.", "containers": [ @@ -28,6 +28,11 @@ "gen_ai.usage.output_tokens.reasoning" ] }, + { + "path": "gen_ai.usage", + "keys": ["gen_ai.usage.cache_read_tokens.audio"], + "value_type": "nonnegative_safe_integer" + }, { "path": "gen_ai.audio", "keys": ["gen_ai.audio.bytes"], diff --git a/typescript/packages/fi-core/test/genai-privacy.test.cjs b/typescript/packages/fi-core/test/genai-privacy.test.cjs index 9472479b5..f2bb67d67 100644 --- a/typescript/packages/fi-core/test/genai-privacy.test.cjs +++ b/typescript/packages/fi-core/test/genai-privacy.test.cjs @@ -8,7 +8,7 @@ const { createServer } = require('node:http'); const { once } = require('node:events'); const { test } = require('node:test'); const load = createRequire(resolve(process.env.FI_CORE_FIXTURE || __dirname + '/..', 'package.json')); -const { FITracer } = process.env.FI_CORE_FIXTURE ? load('@traceai/fi-core') : load('./dist/src/index.js'); +const { FITracer, registerSecret } = process.env.FI_CORE_FIXTURE ? load('@traceai/fi-core') : load('./dist/src/index.js'); const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor, SamplingDecision } = load('@opentelemetry/sdk-trace-base'); const { OTLPTraceExporter } = load('@opentelemetry/exporter-trace-otlp-http'); const { ROOT_CONTEXT, trace } = load('@opentelemetry/api'); @@ -116,13 +116,17 @@ for (const part of [ } } -test('hideInputImages: preserves declared non-image media and legacy text', async () => { +test('hideInputImages: preserves non-image structure and text, never audio payload bytes', async () => { const parts = [{ type: 'blob', modality: 'audio', mime_type: 'audio/wav', content: 'audio' }, { type: 'uri', modality: 'video', uri: 'https://example.invalid/video' }, { type: 'text', content: 'keep text' }]; const value = JSON.stringify([{ role: 'user', parts, content: 'keep legacy' }]); const { attributes } = await record({ hideInputImages: true }, INPUT, value); - assert.deepEqual(JSON.parse(attributes[INPUT]), JSON.parse(value)); + // Image hiding does not remove the audio part, but the shared media policy + // independently withholds its declared payload at every hide-flag setting. + assert.deepEqual(JSON.parse(attributes[INPUT]), [{ role: 'user', parts: [ + { ...parts[0], content: '' }, ...parts.slice(1), + ], content: 'keep legacy' }]); }); test('hideInputImages: opaque tool payloads and unknown parts fail closed', async () => { @@ -163,9 +167,14 @@ test('image hiding still applies PII redaction to retained text', async () => { assert.ok(attributes[INPUT].includes('')); }); -test('disabled and opposite-direction flags preserve bytes; broad flags remove messages', async () => { +test('disabled and opposite-direction flags preserve public bytes, never discovered secrets; broad flags remove messages', async () => { + const publicText = native([{ type: 'text', content: 'public-direction-control' }]); + registerSecret(SECRET); for (const config of [{}, { hideOutputText: true }]) { - assert.equal((await record(config, INPUT, text)).attributes[INPUT], text); + assert.equal((await record(config, INPUT, publicText)).attributes[INPUT], publicText); + // Turning hiding off must not make a process-wide known credential public. + assert.deepEqual(JSON.parse((await record(config, INPUT, text)).attributes[INPUT]), + [{ role: 'user', parts: [{ type: 'text', content: '' }] }]); } for (const flag of ['hideInputs', 'hideInputMessages']) { assert.equal((await record({ [flag]: true }, INPUT, text)).attributes[INPUT], undefined); @@ -182,14 +191,23 @@ test('empty messages and repeated masking are stable', async () => { assert.equal((await record(config, INPUT, onceMasked)).attributes[INPUT], onceMasked); }); -test('structured metadata and a large mixed message batch cannot carry payloads through', async () => { - const value = JSON.stringify(Array.from({ length: 1000 }, () => ({ role: 'user', - name: { data: SECRET }, parts: [{ type: 'text', content: SECRET, id: { data: SECRET } }, - { type: 'tool_call_response', response: [SECRET] }] }))); - const { attributes } = await record({ hideInputText: true }, INPUT, value); - assert.ok(!attributes[INPUT].includes(SECRET)); - assert.equal(JSON.parse(attributes[INPUT]).length, 1000); -}); +for (const count of [100, 1000]) { + test(`structured metadata in ${count} mixed messages stays private, including budget exhaustion`, async () => { + const value = JSON.stringify(Array.from({ length: count }, () => ({ role: 'user', + name: { data: SECRET }, parts: [{ type: 'text', content: SECRET, id: { data: SECRET } }, + { type: 'tool_call_response', response: [SECRET] }] }))); + const result = await record({ hideInputText: true }, INPUT, value); + assert.ok(!JSON.stringify(result).includes(SECRET)); + if (count === 100) { + assert.equal(JSON.parse(result.attributes[INPUT]).length, count); + } else { + // The shared privacy inspection budget fails closed, before the sampler, + // instead of partially retaining an uninspected oversized message batch. + assert.equal(result.attributes[INPUT], undefined); + assert.equal(result.sampled[0][INPUT], undefined); + } + }); +} test('environment privacy flags use the same native message masking', async () => { const previous = process.env.FI_HIDE_INPUT_TEXT; diff --git a/typescript/packages/traceai_auto/src/wire/privacy.json b/typescript/packages/traceai_auto/src/wire/privacy.json index 319aad9e2..eac602779 100644 --- a/typescript/packages/traceai_auto/src/wire/privacy.json +++ b/typescript/packages/traceai_auto/src/wire/privacy.json @@ -1,17 +1,17 @@ { "version": 3, "scalar_metrics": { - "version": 5, + "version": 6, "canonical_decimal": { "ruling": "LANE-CALL-NIKM4-5A-I1-DIGIT-STRING-COUNTS-r2 with I1-R10B A-DIGIT-CONFINED", "regex": "^(0|[1-9][0-9]{0,15})$", "max_chars": 16, "base64_min_chars": 4, "keys": ["gen_ai.audio.bytes"], - "scope": "Only typed byte counters consult this rule. gen_ai.audio.bytes keeps full canonical decimal strings with a safe-integer numeric value unless they have base64 shape at or above base64_min_chars. elevenlabs.audio.bytes never grants a string role. The four-character shape threshold is not a special case for one count. Preserve accepted string types; no signs, leading zeros, fractions, exponents, whitespace or final newline. Other G4 core/detail keys retain their original scalar roles, including arbitrary strings and literal undefined. This rule does not change Q8b NON_CONTENT types." + "scope": "Only declared canonical-decimal counters consult this rule. gen_ai.audio.bytes keeps full canonical decimal strings with a safe-integer numeric value unless they have base64 shape at or above base64_min_chars. elevenlabs.audio.bytes never grants a string role. The four-character shape threshold is not a special case for one count. Preserve accepted string types; no signs, leading zeros, fractions, exponents, whitespace or final newline. Other G4 core/detail keys retain their original scalar roles, including arbitrary strings and literal undefined. This rule does not change Q8b NON_CONTENT types." }, "ruling": "TRACEAI-I1-G3-G4-POLICY-SCOPE-RULING-r1-FISEC G4", - "scope": "Closed exact complete keys in the declared usage/metrics containers only. Case, punctuation, prefixes, suffixes and array indices are not aliases. A nested object path must equal the complete key. gen_ai.audio and elevenlabs.audio are metric containers only for their listed bytes counters, not for arbitrary audio members. Their nonnegative_safe_integer value_type grants a role to finite nonnegative safe-integer numbers; only gen_ai.audio.bytes additionally accepts strings under canonical_decimal. All other inputs on these two byte counters retain the role-free media policy. Other declared metrics keep their original number/boolean/string roles without decimal validation.", + "scope": "Closed exact complete keys in the declared usage/metrics containers only. Case, punctuation, prefixes, suffixes and array indices are not aliases. A nested object path must equal the complete key. gen_ai.audio and elevenlabs.audio are metric containers only for their listed bytes counters, not for arbitrary audio members. Their nonnegative_safe_integer value_type grants a role to finite nonnegative safe-integer numbers; only gen_ai.audio.bytes additionally accepts strings under canonical_decimal. gen_ai.usage.cache_read_tokens.audio also accepts only nonnegative safe-integer numbers, never strings. All other inputs on these typed counters retain the role-free media policy. Other declared metrics keep their original number/boolean/string roles without decimal validation.", "precedence": "Scalar role only removes structural media classification caused by the metric spelling. Explicit media/type hints on any ancestor, inherited media/audio, established media payload ancestry, credential ancestry and known numeric/string secrets take precedence. On the two typed byte counters only, base64-shaped strings at or above canonical_decimal.base64_min_chars cannot obtain a role, even when numerically safe. Magic bytes, data URIs and other independent value checks still apply. A counter leaf under established media payload ancestry cannot use the usage metadata boundary to escape omission. Private payload-role ancestry survives parsed, stringified and diagnostic JSON handoffs; resetting a JSON root never grants a metric role. Metric-looking descendants reached through this retained payload origin remain payload, including numeric/bool scalars and numeric/bool arrays; ordinary metadata text boundaries are unchanged.", "arrays": "Arrays never receive the scalar metric role. Nonempty numeric/bool media payload arrays are omitted; existing string/object array walking and empty-array behavior remain unchanged.", "containers": [ @@ -28,6 +28,11 @@ "gen_ai.usage.output_tokens.reasoning" ] }, + { + "path": "gen_ai.usage", + "keys": ["gen_ai.usage.cache_read_tokens.audio"], + "value_type": "nonnegative_safe_integer" + }, { "path": "gen_ai.audio", "keys": ["gen_ai.audio.bytes"], diff --git a/typescript/packages/traceai_codex_sdk/contract/otlp_wire.mjs b/typescript/packages/traceai_codex_sdk/contract/otlp_wire.mjs index 99b9c01a0..33669d97e 100644 --- a/typescript/packages/traceai_codex_sdk/contract/otlp_wire.mjs +++ b/typescript/packages/traceai_codex_sdk/contract/otlp_wire.mjs @@ -4,7 +4,8 @@ import assert from "node:assert/strict"; import http from "node:http"; import { fileURLToPath } from "node:url"; import * as InstalledCodexSDK from "@openai/codex-sdk"; -import { ProjectType, register } from "@traceai/fi-core"; +import { ROOT_CONTEXT } from "@opentelemetry/api"; +import { FITracer, ProjectType, register, setSession } from "@traceai/fi-core"; import { CodexSDKInstrumentation, shutdown } from "../dist/esm/index.js"; const CodexSDK = process.env.CODEX_SDK_ENTRY @@ -35,6 +36,11 @@ try { .startThread({ skipGitRepoCheck: true }); const result = await thread.run("synthetic prompt WIRE-SECRET-PROMPT"); assert.equal(result.items.length, 3); + // fi-core 1.2.0 exports only a session bound through the typed context API. + // A plain instrumentation attribute (Codex's thread-derived session) stays masked. + const tracer = new FITracer({ tracer: provider.getTracer("typed-session-wire-contract") }); + tracer.startActiveSpan("typed-session-control", {}, + setSession(ROOT_CONTEXT, { sessionId: "typed-wire-session" }), (span) => span.end()); await shutdown(provider); instrumentation.unpatch(); assert.ok(received.length > 0, "collector must receive OTLP export"); @@ -54,7 +60,9 @@ try { assert.equal(command.traceId, turn.traceId); assert.equal(command.parentSpanId, turn.spanId); assert.ok(turn.attributes.some((attribute) => attribute.key === "gen_ai.usage.input_tokens" && String(attribute.value.intValue) === "100")); - assert.ok(turn.attributes.some((attribute) => attribute.key === "session.id" && attribute.value.stringValue === "thread-contract-1")); + assert.ok(turn.attributes.some((attribute) => attribute.key === "session.id" && attribute.value.stringValue === "")); + const typed = spans.find((span) => span.name === "typed-session-control"); + assert.ok(typed?.attributes.some((attribute) => attribute.key === "session.id" && attribute.value.stringValue === "typed-wire-session")); assert.equal(JSON.stringify(spans).includes("WIRE-SECRET-PROMPT"), false, "private prompt leaked to OTLP"); console.log(`PASS OTLP wire (${process.env.CODEX_SDK_ENTRY ?? "installed SDK"}): ${received.length} exports`); } finally { diff --git a/typescript/packages/traceai_google_genai/test/release-regressions.test.cjs b/typescript/packages/traceai_google_genai/test/release-regressions.test.cjs index b5c1f695c..9028fa654 100644 --- a/typescript/packages/traceai_google_genai/test/release-regressions.test.cjs +++ b/typescript/packages/traceai_google_genai/test/release-regressions.test.cjs @@ -434,7 +434,13 @@ for (const option of ['hideInputs', 'hideInputText', 'hideInputMessages', 'hideI assert.doesNotMatch(JSON.stringify(exportedPayloads), /INPUT_SENTINEL|SYSTEM_PRIVATE_SENTINEL|STOP_PRIVATE_SENTINEL/); } else { assert.doesNotMatch(JSON.stringify(exportedPayloads), /OUTPUT_SENTINEL/); - assert.deepEqual(JSON.parse(attributes['gen_ai.request.parameters']), bodies[0].generationConfig); + // fi-core 1.2.0 projects request metadata for either input or output + // hiding. Only canonical configuration keys survive; provider-specific + // topP and content-bearing stopSequences remain fail-closed. + assert.deepEqual(JSON.parse(attributes['gen_ai.request.parameters']), { + temperature: 0.73, topP: '__REDACTED__', stopSequences: '__REDACTED__', + }); + assert.doesNotMatch(attributes['gen_ai.request.parameters'], /STOP_PRIVATE_SENTINEL/); } }); } finally { @@ -457,14 +463,19 @@ function toolModel() { }); } const effectiveKeys = ['generationConfig', 'safetySettings', 'tools', 'toolConfig', 'cachedContent']; -function assertEffectiveInput(attributes, wire) { +function assertEffectiveInput(attributes, wire, hideToolMetadata = false) { for (const key of ['raw.input', 'input.value']) { const captured = JSON.parse(attributes[key]); for (const field of effectiveKeys) assert.deepEqual(captured[field], wire[field], `${key}.${field}`); } const declarations = wire.tools?.flatMap(tool => tool.functionDeclarations || []); + // The shared metadata projection keeps tool identity, not descriptions/schemas, + // whenever either direction is hidden. Raw input still follows input hiding. + const expected = hideToolMetadata ? declarations?.map(tool => ({ + name: tool.name, description: '__REDACTED__', parameters: '__REDACTED__', + })) : declarations; assert.deepEqual(attributes['gen_ai.tool.definitions'] && JSON.parse(attributes['gen_ai.tool.definitions']), - declarations?.length ? declarations : undefined); + expected?.length ? expected : undefined); } for (const [name, input] of [['string', 'INPUT_SENTINEL'], ['strings', ['INPUT_SENTINEL']], @@ -601,7 +612,7 @@ for (const option of ['hideInputs', 'hideInputText', 'hideInputMessages', 'hideI assert.equal(attributes['raw.output'], undefined); assert.equal(attributes['gen_ai.output.messages'], undefined); assert.deepEqual(JSON.parse(attributes['gen_ai.input.messages']), expectedHistory); - assertEffectiveInput(attributes, bodies[1]); + assertEffectiveInput(attributes, bodies[1], true); } }); } finally { diff --git a/typescript/packages/traceai_google_genai_sdk/test/regressions.test.cjs b/typescript/packages/traceai_google_genai_sdk/test/regressions.test.cjs index 251fb4e17..5df944b60 100644 --- a/typescript/packages/traceai_google_genai_sdk/test/regressions.test.cjs +++ b/typescript/packages/traceai_google_genai_sdk/test/regressions.test.cjs @@ -1009,6 +1009,7 @@ for (const streaming of [false, true]) { const data = await exported(); assert.equal(Number(data["gen_ai.usage.input_tokens.audio"]), 6); assert.equal(Number(data["gen_ai.usage.output_tokens.image"]), 1); + assert.equal(Number(data["gen_ai.usage.cache_read_tokens.audio"]), 2); if (hidden) assert.doesNotMatch(JSON.stringify(data), /PRIVATE_INPUT|PRIVATE_OUTPUT/); } finally { h.dispose(); await provider.forceFlush(); } } diff --git a/typescript/packages/traceai_langchain/contract/readme.mjs b/typescript/packages/traceai_langchain/contract/readme.mjs index 1dd7a77b3..f69c6a94f 100644 --- a/typescript/packages/traceai_langchain/contract/readme.mjs +++ b/typescript/packages/traceai_langchain/contract/readme.mjs @@ -80,7 +80,8 @@ if (phase === "install") { } else if (request.url === "/tracer/v1/traces") { for (const resource of body.resourceSpans) { const attrs = Object.fromEntries(resource.resource.attributes.map((a) => [a.key, a.value.stringValue])); - assert.equal(attrs["service.name"], "your-project-name"); + assert.equal(attrs["project_name"], "your-project-name"); + assert.equal(attrs["service.name"], "langchain-readme-service"); for (const scope of resource.scopeSpans) spans.push(...scope.spans); } response.end("{}"); @@ -95,7 +96,7 @@ if (phase === "install") { await writeFile(join(consumer, runner[1]), source + "\n"); const baseUrl = `http://127.0.0.1:${server.address().port}`; const child = spawn("npx", runner, { cwd: consumer, env: { - ...env, FI_API_KEY: "synthetic-fi-key", FI_SECRET_KEY: "synthetic-fi-secret", + ...env, OTEL_SERVICE_NAME: "langchain-readme-service", FI_API_KEY: "synthetic-fi-key", FI_SECRET_KEY: "synthetic-fi-secret", OPENAI_API_KEY: "synthetic-openai-key", FI_BASE_URL: baseUrl, OPENAI_BASE_URL: `${baseUrl}/v1`, }, stdio: ["ignore", "pipe", "pipe"] }); let stdout = "", stderr = ""; diff --git a/typescript/packages/traceai_openai/src/__tests__/openai.test.ts b/typescript/packages/traceai_openai/src/__tests__/openai.test.ts index 19b833df2..a436787bb 100644 --- a/typescript/packages/traceai_openai/src/__tests__/openai.test.ts +++ b/typescript/packages/traceai_openai/src/__tests__/openai.test.ts @@ -318,7 +318,9 @@ describe("OpenAIInstrumentation", () => { expect(spans.length).toBe(1); const span = spans[0]; expect(span.name).toBe("OpenAI Chat Completions"); - expect(span.attributes).toMatchInlineSnapshot(` + expect(span.attributes).toMatchInlineSnapshot( + { "gen_ai.response.time_to_first_token": expect.any(Number) }, + ` { "fi.span.kind": "LLM", "gen_ai.input.messages": "[{"role":"user","content":"Say this is a test"}]", @@ -328,6 +330,7 @@ describe("OpenAIInstrumentation", () => { "gen_ai.request.model": "gpt-3.5-turbo", "gen_ai.request.parameters": "{"model":"gpt-3.5-turbo","stream":true}", "gen_ai.response.finish_reasons": "["stop"]", + "gen_ai.response.time_to_first_token": Any, "input.mime_type": "application/json", "input.value": "{"messages":[{"role":"user","content":"Say this is a test"}],"model":"gpt-3.5-turbo","stream":true}", "output.mime_type": "text/plain", @@ -749,7 +752,9 @@ describe("OpenAIInstrumentation", () => { expect(spans.length).toBe(1); const span = spans[0]; expect(span.name).toBe("OpenAI Chat Completions"); - expect(span.attributes).toMatchInlineSnapshot(` + expect(span.attributes).toMatchInlineSnapshot( + { "gen_ai.response.time_to_first_token": expect.any(Number) }, + ` { "fi.span.kind": "LLM", "gen_ai.input.messages": "[{"role":"user","content":"What's the weather today?"}]", @@ -761,6 +766,7 @@ describe("OpenAIInstrumentation", () => { "gen_ai.response.finish_reasons": "["tool_calls"]", "gen_ai.response.id": "chatcmpl-8iA39kCtuVHIVDr9AnBdJZjgSjNWL", "gen_ai.response.model": "gpt-3.5-turbo-0613", + "gen_ai.response.time_to_first_token": Any, "gen_ai.tool.definitions": "[{"type":"function","function":{"name":"getCurrentLocation","parameters":{"type":"object","properties":{}},"description":"Get the current location of the user."}},{"type":"function","function":{"name":"getWeather","description":"Get the weather for a location.","parameters":{"type":"object","properties":{"location":{"type":"string"}}}}}]", "input.mime_type": "application/json", "input.value": "{"messages":[{"role":"user","content":"What's the weather today?"}],"model":"gpt-3.5-turbo","tools":[{"type":"function","function":{"name":"getCurrentLocation","parameters":{"type":"object","properties":{}},"description":"Get the current location of the user."}},{"type":"function","function":{"name":"getWeather","description":"Get the weather for a location.","parameters":{"type":"object","properties":{"location":{"type":"string"}}}}}],"stream":true}", @@ -865,7 +871,9 @@ describe("OpenAIInstrumentation", () => { expect(spans.length).toBe(1); const span = spans[0]; expect(span.name).toBe("OpenAI Chat Completions"); - expect(span.attributes).toMatchInlineSnapshot(` + expect(span.attributes).toMatchInlineSnapshot( + { "gen_ai.response.time_to_first_token": expect.any(Number) }, + ` { "fi.span.kind": "LLM", "gen_ai.input.messages": "[{"role":"user","content":"What's the weather today?"}]", @@ -877,6 +885,7 @@ describe("OpenAIInstrumentation", () => { "gen_ai.response.finish_reasons": "["function_call"]", "gen_ai.response.id": "chatcmpl-8iA39kCtuVHIVDr9AnBdJZjgSjNWL", "gen_ai.response.model": "gpt-3.5-turbo-0613", + "gen_ai.response.time_to_first_token": Any, "input.mime_type": "application/json", "input.value": "{"messages":[{"role":"user","content":"What's the weather today?"}],"model":"gpt-3.5-turbo","functions":[{"name":"getWeather","description":"Get the weather for a location.","parameters":{"type":"object","properties":{"location":{"type":"string"}}}},{"name":"getCurrentLocation","description":"Get the current location of the user.","parameters":{"type":"object","properties":{}}}],"stream":true}", "output.mime_type": "text/plain", @@ -983,7 +992,7 @@ describe("OpenAIInstrumentation", () => { expect(span.attributes).toMatchInlineSnapshot(` { "fi.span.kind": "LLM", - "gen_ai.input.messages": "[{"role":"user","content":[{"type":"text","text":"Say this is a test"},{"type":"image_url","image_url":{"url":"data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="}}]}]", + "gen_ai.input.messages": "[{"role":"user","content":[{"type":"text","text":"Say this is a test"},{"type":"image_url","image_url":{"url":"[image-redacted]"}}]}]", "gen_ai.operation.name": "chat", "gen_ai.output.messages": "[{"role":"assistant","content":"This is a test."}]", "gen_ai.provider.name": "openai", @@ -996,10 +1005,10 @@ describe("OpenAIInstrumentation", () => { "gen_ai.usage.output_tokens": 5, "gen_ai.usage.total_tokens": 17, "input.mime_type": "application/json", - "input.value": "{"messages":[{"role":"user","content":[{"type":"text","text":"Say this is a test"},{"type":"image_url","image_url":{"url":"data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="}}]}],"model":"gpt-3.5-turbo"}", + "input.value": "{"messages":[{"role":"user","content":[{"type":"text","text":"Say this is a test"},{"type":"image_url","image_url":{"url":"[image-redacted]"}}]}],"model":"gpt-3.5-turbo"}", "output.mime_type": "application/json", "output.value": "{"id":"chatcmpl-8adq9JloOzNZ9TyuzrKyLpGXexh6p","object":"chat.completion","created":1703743645,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"message":{"role":"assistant","content":"This is a test."},"logprobs":null,"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":5,"total_tokens":17}}", - "raw.input": "{"messages":[{"role":"user","content":[{"type":"text","text":"Say this is a test"},{"type":"image_url","image_url":{"url":"data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="}}]}],"model":"gpt-3.5-turbo"}", + "raw.input": "{"messages":[{"role":"user","content":[{"type":"text","text":"Say this is a test"},{"type":"image_url","image_url":{"url":"[image-redacted]"}}]}],"model":"gpt-3.5-turbo"}", "raw.output": "{"id":"chatcmpl-8adq9JloOzNZ9TyuzrKyLpGXexh6p","object":"chat.completion","created":1703743645,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"message":{"role":"assistant","content":"This is a test."},"logprobs":null,"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":5,"total_tokens":17}}", } `); @@ -1414,7 +1423,9 @@ describe("AzureOpenAIInstrumentation", () => { expect(spans.length).toBe(1); const span = spans[0]; expect(span.name).toBe("OpenAI Chat Completions"); - expect(span.attributes).toMatchInlineSnapshot(` + expect(span.attributes).toMatchInlineSnapshot( + { "gen_ai.response.time_to_first_token": expect.any(Number) }, + ` { "fi.span.kind": "LLM", "gen_ai.input.messages": "[{"role":"user","content":"Say this is a test"}]", @@ -1424,6 +1435,7 @@ describe("AzureOpenAIInstrumentation", () => { "gen_ai.request.model": "gpt-35-turbo", "gen_ai.request.parameters": "{"model":"gpt-35-turbo","stream":true}", "gen_ai.response.finish_reasons": "["stop"]", + "gen_ai.response.time_to_first_token": Any, "input.mime_type": "application/json", "input.value": "{"messages":[{"role":"user","content":"Say this is a test"}],"model":"gpt-35-turbo","stream":true}", "output.mime_type": "text/plain", From e4aecfe128e29a942f4f637d39872fc8c355c648 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 03:54:35 -0800 Subject: [PATCH 4/4] chore(auto): release 0.1.1 with the new README (#622) * chore(auto): release 0.1.1 with the new README Publishes the rewritten README (quick start, generated coverage table, privacy defaults, real trace screenshot) to npm; 0.1.0 shipped the old internals-first README. The packed dependency floor becomes @traceai/fi-core ^1.2.1, which no longer exports process command-line arguments or the OS user. - package.json and the tracer scope version (now one VERSION constant) go to 0.1.1. - .release-please-manifest.json listed typescript/packages/traceai_auto twice; keep one entry. Co-Authored-By: Claude Opus 5.5 * chore(auto): register index.ts as a release-please extra-file The scope VERSION constant carries the x-release-please-version marker, which the release plan requires to be listed in extra-files. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .release-please-manifest.json | 5 ++--- release-please-config.json | 3 ++- typescript/packages/traceai_auto/package.json | 2 +- typescript/packages/traceai_auto/src/index.ts | 6 ++++-- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 41ee3b0b8..8fbbd06c9 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -73,7 +73,7 @@ "typescript/packages/fi-core": "1.2.2", "typescript/packages/fi-semantic-conventions": "1.1.0", "typescript/packages/traceai_anthropic": "0.1.5", - "typescript/packages/traceai_auto": "0.1.0", + "typescript/packages/traceai_auto": "0.1.1", "typescript/packages/traceai_bedrock": "0.1.3", "typescript/packages/traceai_beeai": "0.1.2", "typescript/packages/traceai_cerebras": "0.1.2", @@ -152,6 +152,5 @@ "typescript/packages/traceai_oh_my_pi_plugin": "0.1.0", "typescript/packages/traceai_opencode_plugin": "0.1.0", "typescript/packages/traceai_pi_plugin": "0.1.0", - "typescript/packages/traceai_vscode_extension": "0.1.0", - "typescript/packages/traceai_auto": "0.1.0" + "typescript/packages/traceai_vscode_extension": "0.1.0" } diff --git a/release-please-config.json b/release-please-config.json index 85e24a375..3a6261b1d 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -604,7 +604,8 @@ "typescript/packages/traceai_auto": { "release-type": "node", "component": "npm-traceai-auto", - "package-name": "@traceai/auto" + "package-name": "@traceai/auto", + "extra-files": ["src/index.ts"] }, "typescript/packages/traceai_bedrock": { "release-type": "node", diff --git a/typescript/packages/traceai_auto/package.json b/typescript/packages/traceai_auto/package.json index e2c44a57d..f1b31ae51 100644 --- a/typescript/packages/traceai_auto/package.json +++ b/typescript/packages/traceai_auto/package.json @@ -1,6 +1,6 @@ { "name": "@traceai/auto", - "version": "0.1.0", + "version": "0.1.1", "description": "Fail-open, zero-code AI auto-instrumentation for Node.js", "main": "./dist/src/index.js", "module": "./dist/esm/index.js", diff --git a/typescript/packages/traceai_auto/src/index.ts b/typescript/packages/traceai_auto/src/index.ts index 46c57a2e9..f08581ee2 100644 --- a/typescript/packages/traceai_auto/src/index.ts +++ b/typescript/packages/traceai_auto/src/index.ts @@ -10,6 +10,8 @@ import { FetchHook, patchFetch, trackCoverage } from "./wire/fetch"; import { captureSecrets, SpanResult } from "./wire/core"; import { withDeadline } from "./deadline"; import { privacyFilter } from "./export-privacy"; + +const VERSION = "0.1.1"; // x-release-please-version import { chainSigterm } from "./signals"; import { observeTransports } from "./wire/observe-node"; import { borrowConvertedSpanDestination, ConvertedSpanDestination } from "./converted-spans"; @@ -171,8 +173,8 @@ export function init(options: Options = {}): TracerProvider | undefined { // Only instrumentors get this facade; the returned/global provider remains // native. Explicit standalone FITracer users on it are unaffected. const instrumentationProvider = FITracer.autoProvider(agent.provider); - const tracer = agent.provider.getTracer("@traceai/auto", "0.1.0"); - const wireTracer = new FITracer({ tracer: instrumentationProvider.getTracer("@traceai/auto", "0.1.0"), traceConfig: options.traceConfig }); + const tracer = agent.provider.getTracer("@traceai/auto", VERSION); + const wireTracer = new FITracer({ tracer: instrumentationProvider.getTracer("@traceai/auto", VERSION), traceConfig: options.traceConfig }); const admissionPrivacy = privacyFilter(options.traceConfig, [config.apiKey, config.secretKey].filter((v): v is string => !!v)); const wirePipeline = (tracer as any)._spanProcessor; const wireDestinationReady = () => hasAutoSpanSink(wirePipeline, agent.processorIsObserver ? [processor] : []);