@lynxops/sdk 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@lynxops/sdk` will be documented in this file.
+
+## 1.0.2
+
+- Added production-safe background delivery defaults.
+- Added delivery timeout, queue overflow, retry, and circuit breaker controls.
+- Added `flush()`, `shutdown()`, and `getStatus()` lifecycle APIs.
+- Added semantic event helpers for user input, decisions, context, memory, and
+  outcomes.
+- Added local-first `guardTool()` policy evaluation.
+- Added `full`, `metadata-only`, and `smart` capture modes.
+- Added sensitive payload masking before delivery.
+- Added OpenAI, Anthropic, Google, Vercel AI SDK, LangChain, Ollama, and Cohere
+  instrumentation helpers.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Haven / Lynx
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,470 +1,496 @@
-# Lynx SDK
-
-TypeScript SDK for tracing, debugging, and governing AI agent runs with Lynx.
-
-Lynx records what happened during an agent run: user input, agent decisions,
-LLM calls, tool calls, context loading, policy decisions, retries, errors, and
-the final outcome. The SDK is designed for production services, so event
-delivery failures do not stop your application by default.
-
-## Installation
-
-```bash
-pnpm add @lynxops/sdk
-```
-
-```bash
-npm install @lynxops/sdk
-```
-
-```bash
-yarn add @lynxops/sdk
-```
-
-## Quick Start
-
-```ts
-import { LynxTracer } from "@lynxops/sdk";
-
-const lynx = new LynxTracer({
-  clientId: "support-api",
-  apiKey: process.env.LYNX_API_KEY,
-  workspaceId: process.env.LYNX_WORKSPACE_ID,
-  environment: "production",
-});
-
-await lynx.run("SupportAgent", async () => {
-  lynx.userInput("I want a refund", { userId: "usr_123" });
-  lynx.setAttributes({ orderId: "order_123" });
-
-  lynx.context("refund-policy", {
-    refundWindowDays: 30,
-  });
-
-  lynx.decision({
-    name: "select_refund_workflow",
-    selected: "refund",
-    confidence: 0.82,
-    reason: "Order is inside the refund window",
-  });
-
-  lynx.outcome({
-    status: "COMPLETED",
-    businessStatus: "SUCCEEDED",
-    reason: "Refund request was accepted",
-  });
-});
-```
-
-By default, events are sent to:
-
-```text
-https://api.lynxops.co
-```
-
-Use `endpoint` or `LYNX_ENDPOINT` for local development or self-hosted
-deployments.
-
-## Default Instance
-
-The SDK exports a default `lynx` instance configured from environment
-variables.
-
-```ts
-import { lynx } from "@lynxops/sdk";
-
-await lynx.run("ResearchAgent", async () => {
-  lynx.userInput("Find the latest invoice policy");
-  lynx.decision("search internal docs first");
-});
-```
-
-```bash
-LYNX_CLIENT_ID=support-api
-LYNX_API_KEY=lynx_sk_...
-LYNX_WORKSPACE_ID=...
-LYNX_ENVIRONMENT=production
-```
-
-## Production Delivery Model
-
-The SDK prioritizes your application over event delivery.
-
-Production-oriented defaults:
-
-| Option | Default |
-| --- | --- |
-| `endpoint` | `https://api.lynxops.co` |
-| `delivery.mode` | `BACKGROUND` |
-| `delivery.timeoutMs` | `1000` |
-| `delivery.flushOnRunEnd` | `false` |
-| `delivery.flushIntervalMs` | `3000` |
-| `delivery.batchSize` | `50` |
-| `delivery.maxQueueSize` | `1000` |
-| `delivery.overflowStrategy` | `DROP_OLDEST` |
-| `circuitBreaker.enabled` | `true` |
-| `circuitBreaker.failureThreshold` | `3` |
-| `circuitBreaker.cooldownMs` | `30000` |
-
-Recommended production configuration:
-
-```ts
-const lynx = new LynxTracer({
-  clientId: "support-api",
-  apiKey: process.env.LYNX_API_KEY,
-  workspaceId: process.env.LYNX_WORKSPACE_ID,
-
-  delivery: {
-    mode: "BACKGROUND",
-    timeoutMs: 1000,
-    flushOnRunEnd: false,
-    flushIntervalMs: 5000,
-    batchSize: 50,
-    maxQueueSize: 10_000,
-    overflowStrategy: "DROP_OLDEST",
-  },
-
-  circuitBreaker: {
-    enabled: true,
-    failureThreshold: 3,
-    cooldownMs: 30_000,
-  },
-});
-```
-
-If the Lynx API is unavailable, the SDK:
-
-- catches network, timeout, and non-2xx delivery errors
-- queues events in memory
-- retries with backoff
-- opens a circuit breaker after repeated failures
-- drops events according to the configured overflow strategy when the queue is
-  full
-
-With the default background delivery mode, `run()` does not wait for event
-HTTP requests.
-
-## Capturing Agent Runs
-
-Use `run()` as the unit of work for one agent execution.
-
-```ts
-await lynx.run(
-  "InvoiceAgent",
-  async () => {
-    lynx.userInput("Can this invoice be paid?");
-    lynx.decision("verify vendor and payment policy");
-  },
-  {
-    workspaceId: "workspace_123",
-    agentId: "agent_invoice",
-    sessionId: "session_456",
-  },
-);
-```
-
-Useful identifiers:
-
-| Field | Purpose |
-| --- | --- |
-| `runId` | Unique execution id for one agent run. Generated automatically unless provided. |
-| `sessionId` | Groups multiple runs or events into a user-visible session. |
-| `workspaceId` | Tenant boundary for Lynx ingestion and dashboards. |
-| `agentId` | Stable agent identifier. |
-| `agentName` | Human-readable agent name shown in debugging views. |
-| `environment` | Runtime environment such as `production`, `staging`, or `local`. |
-| `appVersion` | Application release metadata. |
-| `deploymentId` | Deployment metadata for incident correlation. |
-| `promptVersion` | Prompt version metadata attached to LLM and reasoning events. |
-| `policyVersion` | Guardrail or policy version metadata. |
-
-## Semantic Events
-
-Prefer semantic helpers over raw event logging. They make Lynx debugging views
-more useful.
-
-```ts
-lynx.userInput("Book a flight to Seoul", { userId: "usr_123" });
-
-lynx.context("calendar-availability", {
-  daysLoaded: 14,
-  source: "calendar-api",
-});
-
-lynx.decision({
-  name: "choose_booking_tool",
-  selected: "flight_search",
-  alternatives: ["email_assistant", "manual_handoff"],
-  confidence: 0.76,
-  reason: "The user requested a travel booking action",
-});
-
-lynx.log("tool.timeout", {
-  error: "Travel API timed out",
-  toolName: "travel.search",
-});
-
-lynx.outcome({
-  status: "FAILED",
-  businessStatus: "FAILED",
-  reason: "The external travel API timed out",
-  userImpact: "MEDIUM",
-});
-```
-
-## Record LLM calls
-
-Use `instrumentLLM()` to wrap a model client. The returned proxy preserves the
-original client shape while recording supported model calls.
-
-```ts
-const instrumentedClient = lynx.instrumentLLM(client, {
-  modelLabel: "openai.gpt-4.1-mini",
-});
-
-await lynx.run("SupportAgent", async () => {
-  await instrumentedClient.responses.create({
-    model: "gpt-4.1-mini",
-    input: "Summarize this support ticket",
-    metadata: {
-      promptVersion: "support-summary-v3",
-    },
-  });
-});
-```
-
-## Record tool calls
-
-Use `instrumentTool()` to wrap a reusable tool function.
-
-```ts
-const postSlackMessage = lynx.instrumentTool(
-  "slack.postMessage",
-  async (input: { channel: string; text: string }) => {
-    return await slack.chat.postMessage(input);
-  },
-  {
-    sideEffect: true,
-    riskLevel: "MEDIUM",
-    externalTarget: "slack",
-  },
-);
-
-await postSlackMessage({
-  channel: "C123",
-  text: "Refund approved",
-});
-```
-
-## Local Guardrails
-
-`guardTool()` evaluates your policy locally before a tool runs. Lynx server
-availability does not decide whether the tool is blocked.
-
-```ts
-import { LynxPolicyError } from "@lynxops/sdk";
-
-const refund = lynx.guardTool(
-  "refund.create",
-  async ({ amount }: { amount: number }) => {
-    return { refunded: amount };
-  },
-  {
-    sideEffect: true,
-    riskLevel: "HIGH",
-    failureMode: "FAIL_CLOSED",
-    beforeCall: ({ input }) => {
-      if (input.amount > 100) {
-        return {
-          action: "BLOCK",
-          policyId: "refund-limit",
-          reason: "Refund amount is over the approved limit",
-          severity: "HIGH",
-        };
-      }
-
-      return {
-        action: "ALLOW",
-        policyId: "refund-limit",
-      };
-    },
-  },
-);
-
-try {
-  await lynx.run("SupportAgent", () => refund({ amount: 500 }));
-} catch (error) {
-  if (error instanceof LynxPolicyError) {
-    console.log(error.action, error.policyId, error.reason);
-  }
-}
-```
-
-Policy behavior:
-
-| Policy result | Behavior |
-| --- | --- |
-| `ALLOW` | Runs the tool and records policy evaluation metadata. |
-| `WARN` | Runs the tool and records a warning. |
-| `BLOCK` | Blocks the tool and throws `LynxPolicyError`. |
-| `REQUIRE_APPROVAL` | Blocks the tool and throws `LynxPolicyError`. |
-
-If policy evaluation itself throws, `failureMode` decides the fallback:
-
-| Failure mode | Behavior |
-| --- | --- |
-| `FAIL_OPEN` | Allows the tool call and records the policy error. |
-| `FAIL_CLOSED` | Blocks the tool call. |
-| `REQUIRE_APPROVAL` | Blocks with `action: "REQUIRE_APPROVAL"`. |
-
-## Capture Modes
-
-Lynx does not require you to store full payloads.
-
-| Mode | Behavior |
-| --- | --- |
-| `full` | Captures input and output payloads according to `captureInput` and `captureOutput`. |
-| `metadata-only` | Keeps structure, timing, token usage, cost, status, errors, tool names, and trace metadata without raw content. |
-| `smart` | Captures metadata for normal events and preserves richer detail for failures, policy violations, and abnormal latency. |
-
-```ts
-const lynx = new LynxTracer({
-  clientId: "support-api",
-  apiKey: process.env.LYNX_API_KEY,
-  captureMode: "smart",
-  maxPayloadLength: 16_000,
-});
-```
-
-## Flush, Shutdown, and Health
-
-Use `flush()` to send the current queue while keeping the SDK active.
-
-```ts
-await lynx.flush();
-```
-
-Use `shutdown()` when the process is about to exit, in serverless handlers, or
-in tests.
-
-```ts
-await lynx.shutdown({ timeoutMs: 1000 });
-```
-
-Use `getStatus()` for local diagnostics.
-
-```ts
-const status = lynx.getStatus();
-
-console.log({
-  queueSize: status.queueSize,
-  droppedEvents: status.droppedEvents,
-  circuitState: status.circuitState,
-  pendingTransmissions: status.pendingTransmissions,
-});
-```
-
-## Configuration Reference
-
-```ts
-const lynx = new LynxTracer({
-  clientId: "support-api",
-  endpoint: "https://api.lynxops.co",
-  workspaceId: "workspace_123",
-  agentId: "agent_support",
-  apiKey: process.env.LYNX_API_KEY,
-  appVersion: "2026.06.29",
-  deploymentId: "deploy_123",
-  environment: "production",
-  policyVersion: "policy_2026_06",
-  sampleRate: 1,
-  captureInput: true,
-  captureOutput: true,
-  captureMode: "smart",
-  maxPayloadLength: 16_000,
-  delivery: {
-    mode: "BACKGROUND",
-    timeoutMs: 1000,
-    flushOnRunEnd: false,
-    flushIntervalMs: 3000,
-    batchSize: 50,
-    maxQueueSize: 1000,
-    overflowStrategy: "DROP_OLDEST",
-  },
-  circuitBreaker: {
-    enabled: true,
-    failureThreshold: 3,
-    cooldownMs: 30_000,
-  },
-});
-```
-
-| Option | Description |
-| --- | --- |
-| `clientId` | Required service or client identifier. |
-| `endpoint` | Lynx API endpoint. Defaults to `https://api.lynxops.co`. |
-| `workspaceId` | Default workspace id attached to events. |
-| `agentId` | Default agent id attached to events. |
-| `apiKey` | Lynx ingestion API key. Sent as a bearer token. |
-| `appVersion` | Application version metadata. |
-| `deploymentId` | Deployment id metadata. |
-| `environment` | Runtime environment metadata. |
-| `policyVersion` | Default policy version metadata. |
-| `sampleRate` | Trace sampling ratio from `0` to `1`. |
-| `captureInput` | Whether input payloads can be captured. |
-| `captureOutput` | Whether output payloads can be captured. |
-| `captureMode` | `full`, `metadata-only`, or `smart`. |
-| `maxPayloadLength` | Maximum serialized payload length per event. |
-| `delivery.mode` | `BACKGROUND` or `BLOCKING`. |
-| `delivery.timeoutMs` | Timeout for one event delivery request. |
-| `delivery.flushOnRunEnd` | Whether `run()` tries to flush after the wrapped work finishes. |
-| `delivery.flushIntervalMs` | Background flush interval. |
-| `delivery.batchSize` | Batch size for delivery. |
-| `delivery.maxQueueSize` | Maximum queued events in memory. |
-| `delivery.overflowStrategy` | `DROP_OLDEST` or `DROP_NEWEST`. |
-| `circuitBreaker.enabled` | Enables delivery circuit breaker protection. |
-| `circuitBreaker.failureThreshold` | Consecutive delivery failures before opening the breaker. |
-| `circuitBreaker.cooldownMs` | Cooldown before retrying after the breaker opens. |
-
-## Environment Variables
-
-The default `lynx` export reads these variables:
-
-| Variable | Description |
-| --- | --- |
-| `LYNX_CLIENT_ID` | Client or service identifier. Defaults to `local_dev_env`. |
-| `LYNX_ENDPOINT` | Optional Lynx API endpoint override. |
-| `LYNX_API_KEY` | Lynx ingestion API key. |
-| `LYNX_WORKSPACE_ID` | Default workspace id. |
-| `LYNX_AGENT_ID` | Default agent id. |
-| `LYNX_SESSION_ID` | Default session id when `run()` does not receive one. |
-| `LYNX_SAMPLE_RATE` | Sampling rate from `0` to `1`. |
-| `LYNX_CAPTURE_INPUT` | `true` or `false`. |
-| `LYNX_CAPTURE_OUTPUT` | `true` or `false`. |
-| `LYNX_CAPTURE_MODE` | `full`, `metadata-only`, or `smart`. |
-| `LYNX_MAX_PAYLOAD_LENGTH` | Maximum payload string length. |
-| `LYNX_APP_VERSION` | Application version metadata. |
-| `LYNX_DEPLOYMENT_ID` | Deployment id metadata. |
-| `LYNX_ENVIRONMENT` | Runtime environment metadata. Falls back to `NODE_ENV`. |
-| `LYNX_POLICY_VERSION` | Default policy version metadata. |
-| `LYNX_DELIVERY_MODE` | `BACKGROUND` or `BLOCKING`. |
-| `LYNX_DELIVERY_TIMEOUT_MS` | Delivery timeout in milliseconds. |
-| `LYNX_DELIVERY_FLUSH_ON_RUN_END` | `true` or `false`. |
-| `LYNX_DELIVERY_FLUSH_INTERVAL_MS` | Flush interval in milliseconds. |
-| `LYNX_DELIVERY_BATCH_SIZE` | Batch size. |
-| `LYNX_DELIVERY_MAX_QUEUE_SIZE` | Maximum queued event count. |
-| `LYNX_DELIVERY_OVERFLOW_STRATEGY` | `DROP_OLDEST` or `DROP_NEWEST`. |
-| `LYNX_CIRCUIT_BREAKER_ENABLED` | `true` or `false`. |
-| `LYNX_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | Consecutive failure count before opening the breaker. |
-| `LYNX_CIRCUIT_BREAKER_COOLDOWN_MS` | Circuit breaker cooldown in milliseconds. |
-
-## Development
-
-```bash
-pnpm install
-pnpm build
-pnpm test
-```
-
-The SDK is ESM-first and also publishes a CommonJS build through package
-exports.
+# Lynx SDK
+
+TypeScript SDK for tracing, debugging, and governing AI agent runs with Lynx.
+
+Lynx records what happened during an agent run: user input, agent decisions,
+LLM calls, tool calls, context loading, policy decisions, retries, errors, and
+the final outcome. The SDK is designed for production services, so event
+delivery failures do not stop your application by default.
+
+This SDK is designed for Node.js server-side runtimes. Browser and edge runtime
+support are not guaranteed yet.
+
+## Installation
+
+```bash
+pnpm add @lynxops/sdk
+```
+
+```bash
+npm install @lynxops/sdk
+```
+
+```bash
+yarn add @lynxops/sdk
+```
+
+## Quick Start
+
+```ts
+import { LynxTracer } from "@lynxops/sdk";
+
+const lynx = new LynxTracer({
+  clientId: "support-api",
+  apiKey: process.env.LYNX_API_KEY,
+  workspaceId: process.env.LYNX_WORKSPACE_ID,
+  environment: "production",
+});
+
+await lynx.run("SupportAgent", async () => {
+  lynx.userInput("I want a refund", { userId: "usr_123" });
+  lynx.setAttributes({ orderId: "order_123" });
+
+  lynx.context("refund-policy", {
+    refundWindowDays: 30,
+  });
+
+  lynx.decision({
+    name: "select_refund_workflow",
+    selected: "refund",
+    confidence: 0.82,
+    reason: "Order is inside the refund window",
+  });
+
+  lynx.outcome({
+    status: "COMPLETED",
+    businessStatus: "SUCCEEDED",
+    reason: "Refund request was accepted",
+  });
+});
+```
+
+In serverless functions, CLI scripts, tests, or other short-lived processes,
+call `shutdown()` before the process exits so queued background events can be
+flushed.
+
+```ts
+await lynx.shutdown({ timeoutMs: 1000 });
+```
+
+By default, events are sent to:
+
+```text
+https://api.lynxops.co
+```
+
+Use `endpoint` or `LYNX_ENDPOINT` for local development or self-hosted
+deployments.
+
+## Default Instance
+
+The SDK exports a default `lynx` instance configured from environment
+variables.
+
+```ts
+import { lynx } from "@lynxops/sdk";
+
+await lynx.run("ResearchAgent", async () => {
+  lynx.userInput("Find the latest invoice policy");
+  lynx.decision("search internal docs first");
+});
+```
+
+```bash
+LYNX_CLIENT_ID=support-api
+LYNX_API_KEY=lynx_sk_...
+LYNX_WORKSPACE_ID=...
+LYNX_ENVIRONMENT=production
+```
+
+## Production Delivery Model
+
+The SDK prioritizes your application over event delivery.
+
+Production-oriented defaults:
+
+| Option | Default |
+| --- | --- |
+| `endpoint` | `https://api.lynxops.co` |
+| `delivery.mode` | `BACKGROUND` |
+| `delivery.timeoutMs` | `1000` |
+| `delivery.flushOnRunEnd` | `false` |
+| `delivery.flushIntervalMs` | `3000` |
+| `delivery.batchSize` | `50` |
+| `delivery.maxQueueSize` | `1000` |
+| `delivery.overflowStrategy` | `DROP_OLDEST` |
+| `circuitBreaker.enabled` | `true` |
+| `circuitBreaker.failureThreshold` | `3` |
+| `circuitBreaker.cooldownMs` | `30000` |
+
+Recommended production configuration:
+
+```ts
+const lynx = new LynxTracer({
+  clientId: "support-api",
+  apiKey: process.env.LYNX_API_KEY,
+  workspaceId: process.env.LYNX_WORKSPACE_ID,
+
+  delivery: {
+    mode: "BACKGROUND",
+    timeoutMs: 1000,
+    flushOnRunEnd: false,
+    flushIntervalMs: 5000,
+    batchSize: 50,
+    maxQueueSize: 10_000,
+    overflowStrategy: "DROP_OLDEST",
+  },
+
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 3,
+    cooldownMs: 30_000,
+  },
+});
+```
+
+If the Lynx API is unavailable, the SDK:
+
+- catches network, timeout, and non-2xx delivery errors
+- queues events in memory
+- retries with backoff
+- opens a circuit breaker after repeated failures
+- drops events according to the configured overflow strategy when the queue is
+  full
+
+With the default background delivery mode, `run()` does not wait for event
+HTTP requests.
+
+## Capturing Agent Runs
+
+Use `run()` as the unit of work for one agent execution.
+
+```ts
+await lynx.run(
+  "InvoiceAgent",
+  async () => {
+    lynx.userInput("Can this invoice be paid?");
+    lynx.decision("verify vendor and payment policy");
+  },
+  {
+    workspaceId: "workspace_123",
+    agentId: "agent_invoice",
+    sessionId: "session_456",
+  },
+);
+```
+
+Useful identifiers:
+
+| Field | Purpose |
+| --- | --- |
+| `runId` | Unique execution id for one agent run. Generated automatically unless provided. |
+| `sessionId` | Groups multiple runs or events into a user-visible session. |
+| `workspaceId` | Tenant boundary for Lynx ingestion and dashboards. |
+| `agentId` | Stable agent identifier. |
+| `agentName` | Human-readable agent name shown in debugging views. |
+| `environment` | Runtime environment such as `production`, `staging`, or `local`. |
+| `appVersion` | Application release metadata. |
+| `deploymentId` | Deployment metadata for incident correlation. |
+| `promptVersion` | Prompt version metadata attached to LLM and reasoning events. |
+| `policyVersion` | Guardrail or policy version metadata. |
+
+## Semantic Events
+
+Prefer semantic helpers over raw event logging. They make Lynx debugging views
+more useful.
+
+```ts
+lynx.userInput("Book a flight to Seoul", { userId: "usr_123" });
+
+lynx.context("calendar-availability", {
+  daysLoaded: 14,
+  source: "calendar-api",
+});
+
+lynx.decision({
+  name: "choose_booking_tool",
+  selected: "flight_search",
+  alternatives: ["email_assistant", "manual_handoff"],
+  confidence: 0.76,
+  reason: "The user requested a travel booking action",
+});
+
+lynx.log("tool.timeout", {
+  error: "Travel API timed out",
+  toolName: "travel.search",
+});
+
+lynx.outcome({
+  status: "FAILED",
+  businessStatus: "FAILED",
+  reason: "The external travel API timed out",
+  userImpact: "MEDIUM",
+});
+```
+
+## Record LLM calls
+
+Use `instrumentLLM()` to wrap a model client. The returned proxy preserves the
+original client shape while recording supported model calls.
+
+```ts
+const instrumentedClient = lynx.instrumentLLM(client, {
+  modelLabel: "openai.gpt-4.1-mini",
+});
+
+await lynx.run("SupportAgent", async () => {
+  await instrumentedClient.responses.create({
+    model: "gpt-4.1-mini",
+    input: "Summarize this support ticket",
+    metadata: {
+      promptVersion: "support-summary-v3",
+    },
+  });
+});
+```
+
+## Record tool calls
+
+Use `instrumentTool()` to wrap a reusable tool function.
+
+```ts
+const postSlackMessage = lynx.instrumentTool(
+  "slack.postMessage",
+  async (input: { channel: string; text: string }) => {
+    return await slack.chat.postMessage(input);
+  },
+  {
+    sideEffect: true,
+    riskLevel: "MEDIUM",
+    externalTarget: "slack",
+  },
+);
+
+await postSlackMessage({
+  channel: "C123",
+  text: "Refund approved",
+});
+```
+
+## Local Guardrails
+
+`guardTool()` evaluates your policy locally before a tool runs. Lynx server
+availability does not decide whether the tool is blocked.
+
+```ts
+import { LynxPolicyError } from "@lynxops/sdk";
+
+const refund = lynx.guardTool(
+  "refund.create",
+  async ({ amount }: { amount: number }) => {
+    return { refunded: amount };
+  },
+  {
+    sideEffect: true,
+    riskLevel: "HIGH",
+    failureMode: "FAIL_CLOSED",
+    beforeCall: ({ input }) => {
+      if (input.amount > 100) {
+        return {
+          action: "BLOCK",
+          policyId: "refund-limit",
+          reason: "Refund amount is over the approved limit",
+          severity: "HIGH",
+        };
+      }
+
+      return {
+        action: "ALLOW",
+        policyId: "refund-limit",
+      };
+    },
+  },
+);
+
+try {
+  await lynx.run("SupportAgent", () => refund({ amount: 500 }));
+} catch (error) {
+  if (error instanceof LynxPolicyError) {
+    console.log(error.action, error.policyId, error.reason);
+  }
+}
+```
+
+Policy behavior:
+
+| Policy result | Behavior |
+| --- | --- |
+| `ALLOW` | Runs the tool and records policy evaluation metadata. |
+| `WARN` | Runs the tool and records a warning. |
+| `BLOCK` | Blocks the tool and throws `LynxPolicyError`. |
+| `REQUIRE_APPROVAL` | Blocks the tool and throws `LynxPolicyError`. |
+
+If policy evaluation itself throws, `failureMode` decides the fallback:
+
+| Failure mode | Behavior |
+| --- | --- |
+| `FAIL_OPEN` | Allows the tool call and records the policy error. |
+| `FAIL_CLOSED` | Blocks the tool call. |
+| `REQUIRE_APPROVAL` | Blocks with `action: "REQUIRE_APPROVAL"`. |
+
+## Capture Modes
+
+Lynx does not require you to store full payloads.
+
+| Mode | Behavior |
+| --- | --- |
+| `full` | Captures input and output payloads according to `captureInput` and `captureOutput`. |
+| `metadata-only` | Keeps structure, timing, token usage, cost, status, errors, tool names, and trace metadata without raw content. |
+| `smart` | Captures metadata for normal events and preserves richer detail for failures, policy violations, and abnormal latency. |
+
+```ts
+const lynx = new LynxTracer({
+  clientId: "support-api",
+  apiKey: process.env.LYNX_API_KEY,
+  captureMode: "smart",
+  maxPayloadLength: 16_000,
+});
+```
+
+## Flush, Shutdown, and Health
+
+Use `flush()` to send the current queue while keeping the SDK active.
+
+```ts
+await lynx.flush();
+```
+
+Use `shutdown()` when the process is about to exit, in serverless handlers, or
+in tests.
+
+```ts
+await lynx.shutdown({ timeoutMs: 1000 });
+```
+
+Use `getStatus()` for local diagnostics.
+
+```ts
+const status = lynx.getStatus();
+
+console.log({
+  queueSize: status.queueSize,
+  droppedEvents: status.droppedEvents,
+  circuitState: status.circuitState,
+  pendingTransmissions: status.pendingTransmissions,
+});
+```
+
+## Configuration Reference
+
+```ts
+const lynx = new LynxTracer({
+  clientId: "support-api",
+  endpoint: "https://api.lynxops.co",
+  workspaceId: "workspace_123",
+  agentId: "agent_support",
+  apiKey: process.env.LYNX_API_KEY,
+  appVersion: "2026.06.29",
+  deploymentId: "deploy_123",
+  environment: "production",
+  policyVersion: "policy_2026_06",
+  sampleRate: 1,
+  captureInput: true,
+  captureOutput: true,
+  captureMode: "smart",
+  maxPayloadLength: 16_000,
+  delivery: {
+    mode: "BACKGROUND",
+    timeoutMs: 1000,
+    flushOnRunEnd: false,
+    flushIntervalMs: 3000,
+    batchSize: 50,
+    maxQueueSize: 1000,
+    overflowStrategy: "DROP_OLDEST",
+  },
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 3,
+    cooldownMs: 30_000,
+  },
+});
+```
+
+| Option | Description |
+| --- | --- |
+| `clientId` | Required service or client identifier. |
+| `endpoint` | Lynx API endpoint. Defaults to `https://api.lynxops.co`. |
+| `workspaceId` | Default workspace id attached to events. |
+| `agentId` | Default agent id attached to events. |
+| `apiKey` | Lynx ingestion API key. Sent as a bearer token. |
+| `appVersion` | Application version metadata. |
+| `deploymentId` | Deployment id metadata. |
+| `environment` | Runtime environment metadata. |
+| `policyVersion` | Default policy version metadata. |
+| `sampleRate` | Trace sampling ratio from `0` to `1`. |
+| `captureInput` | Whether input payloads can be captured. |
+| `captureOutput` | Whether output payloads can be captured. |
+| `captureMode` | `full`, `metadata-only`, or `smart`. |
+| `maxPayloadLength` | Maximum serialized payload length per event. |
+| `delivery.mode` | `BACKGROUND` or `BLOCKING`. |
+| `delivery.timeoutMs` | Timeout for one event delivery request. |
+| `delivery.flushOnRunEnd` | Whether `run()` tries to flush after the wrapped work finishes. |
+| `delivery.flushIntervalMs` | Background flush interval. |
+| `delivery.batchSize` | Batch size for delivery. |
+| `delivery.maxQueueSize` | Maximum queued events in memory. |
+| `delivery.overflowStrategy` | `DROP_OLDEST` or `DROP_NEWEST`. |
+| `circuitBreaker.enabled` | Enables delivery circuit breaker protection. |
+| `circuitBreaker.failureThreshold` | Consecutive delivery failures before opening the breaker. |
+| `circuitBreaker.cooldownMs` | Cooldown before retrying after the breaker opens. |
+
+## Environment Variables
+
+The default `lynx` export reads these variables:
+
+| Variable | Description |
+| --- | --- |
+| `LYNX_CLIENT_ID` | Client or service identifier. Defaults to `local_dev_env`. |
+| `LYNX_ENDPOINT` | Optional Lynx API endpoint override. |
+| `LYNX_API_KEY` | Lynx ingestion API key. |
+| `LYNX_WORKSPACE_ID` | Default workspace id. |
+| `LYNX_AGENT_ID` | Default agent id. |
+| `LYNX_SESSION_ID` | Default session id when `run()` does not receive one. |
+| `LYNX_SAMPLE_RATE` | Sampling rate from `0` to `1`. |
+| `LYNX_CAPTURE_INPUT` | `true` or `false`. |
+| `LYNX_CAPTURE_OUTPUT` | `true` or `false`. |
+| `LYNX_CAPTURE_MODE` | `full`, `metadata-only`, or `smart`. |
+| `LYNX_MAX_PAYLOAD_LENGTH` | Maximum payload string length. |
+| `LYNX_APP_VERSION` | Application version metadata. |
+| `LYNX_DEPLOYMENT_ID` | Deployment id metadata. |
+| `LYNX_ENVIRONMENT` | Runtime environment metadata. Falls back to `NODE_ENV`. |
+| `LYNX_POLICY_VERSION` | Default policy version metadata. |
+| `LYNX_DELIVERY_MODE` | `BACKGROUND` or `BLOCKING`. |
+| `LYNX_DELIVERY_TIMEOUT_MS` | Delivery timeout in milliseconds. |
+| `LYNX_DELIVERY_FLUSH_ON_RUN_END` | `true` or `false`. |
+| `LYNX_DELIVERY_FLUSH_INTERVAL_MS` | Flush interval in milliseconds. |
+| `LYNX_DELIVERY_BATCH_SIZE` | Batch size. |
+| `LYNX_DELIVERY_MAX_QUEUE_SIZE` | Maximum queued event count. |
+| `LYNX_DELIVERY_OVERFLOW_STRATEGY` | `DROP_OLDEST` or `DROP_NEWEST`. |
+| `LYNX_CIRCUIT_BREAKER_ENABLED` | `true` or `false`. |
+| `LYNX_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | Consecutive failure count before opening the breaker. |
+| `LYNX_CIRCUIT_BREAKER_COOLDOWN_MS` | Circuit breaker cooldown in milliseconds. |
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+The SDK is ESM-first and also publishes a CommonJS build through package
+exports.
+
+## Runtime Support
+
+`@lynxops/sdk` supports Node.js 18 and newer. It uses Node runtime APIs such as
+`AsyncLocalStorage`, global `fetch`, `AbortSignal.timeout`, and process
+lifecycle hooks.
+
+## Security
+
+Please report security issues privately to `security@lynxops.co`. See
+`SECURITY.md` for details.
+
+## License
+
+ISC

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+Lynx SDK runs inside customer applications, so we treat security reports with
+high priority.
+
+## Supported Versions
+
+Security fixes are provided for the latest published version of `@lynxops/sdk`.
+
+## Reporting a Vulnerability
+
+Please do not open a public GitHub issue for sensitive security reports.
+
+Send vulnerability details to:
+
+```text
+security@lynxops.co
+```
+
+Include:
+
+- affected package version
+- runtime and framework details
+- reproduction steps or proof of concept
+- potential impact
+- any relevant logs or traces with secrets removed
+
+We will acknowledge reports as soon as possible and coordinate remediation
+before public disclosure.

package/dist/index.cjs

@@ -123,6 +123,35 @@ var PII_RULES = patterns_default.piiRules.map((rule) => ({
   replacement: rule.replacement
 }));
 var SENSITIVE_KEY_PATTERN = /(?:api[-_]?key|authorization|auth[-_]?token|bearer|client[-_]?secret|cookie|credential|jwt|password|private[-_]?key|refresh[-_]?token|secret|session[-_]?token|token)/i;
+var SAFE_TOKEN_METRIC_KEYS = /* @__PURE__ */ new Set([
+  "completiontokens",
+  "completiontokencount",
+  "completion_tokens",
+  "inputtokens",
+  "inputtokencount",
+  "input_tokens",
+  "maxtokens",
+  "maxoutputtokens",
+  "max_tokens",
+  "outputtokens",
+  "outputtokencount",
+  "output_tokens",
+  "prompttokens",
+  "prompttokencount",
+  "prompt_tokens",
+  "totaltokens",
+  "totaltokencount",
+  "total_tokens"
+]);
+function normalizeKey(key) {
+  return key.replace(/[-_]/g, "").toLowerCase();
+}
+function isSensitiveKey(key) {
+  if (SAFE_TOKEN_METRIC_KEYS.has(normalizeKey(key))) {
+    return false;
+  }
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
 function maskPIIString(text) {
   let masked = text;
   for (const rule of PII_RULES) {
@@ -141,7 +170,7 @@ function recursiveMaskPII(obj) {
   if (typeof obj === "object") {
     const res = {};
     for (const key of Object.keys(obj)) {
-      if (SENSITIVE_KEY_PATTERN.test(key)) {
+      if (isSensitiveKey(key)) {
         res[key] = "[MASKED_SECRET]";
       } else {
         res[key] = recursiveMaskPII(obj[key]);
@@ -354,6 +383,7 @@ function instrumentLLM(tracer, instance, optionsOrLabel = "llm.inference") {
     }
     const pathStr = path.join(".");
     return pathStr === "chat.completions.create" || // OpenAI
+    pathStr === "responses.create" || // OpenAI Responses API
     pathStr === "messages.create" || // Anthropic (Claude)
     pathStr === "models.generateContent" || // Google Gen AI 신규
     pathStr === "generateContent" || // Google Generative AI 기존
@@ -498,8 +528,10 @@ function instrumentTool(tracer, toolName, fn, metadata = {}) {
   });
 }
 
+// src/version.ts
+var SDK_VERSION = "1.0.3";
+
 // src/core/tracer.ts
-var SDK_VERSION = "1.0.0";
 var DEFAULT_ENDPOINT = "https://api.lynxops.co";
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 var DEFAULT_BATCH_SIZE = 50;

package/dist/index.js

@@ -92,6 +92,35 @@ var PII_RULES = patterns_default.piiRules.map((rule) => ({
   replacement: rule.replacement
 }));
 var SENSITIVE_KEY_PATTERN = /(?:api[-_]?key|authorization|auth[-_]?token|bearer|client[-_]?secret|cookie|credential|jwt|password|private[-_]?key|refresh[-_]?token|secret|session[-_]?token|token)/i;
+var SAFE_TOKEN_METRIC_KEYS = /* @__PURE__ */ new Set([
+  "completiontokens",
+  "completiontokencount",
+  "completion_tokens",
+  "inputtokens",
+  "inputtokencount",
+  "input_tokens",
+  "maxtokens",
+  "maxoutputtokens",
+  "max_tokens",
+  "outputtokens",
+  "outputtokencount",
+  "output_tokens",
+  "prompttokens",
+  "prompttokencount",
+  "prompt_tokens",
+  "totaltokens",
+  "totaltokencount",
+  "total_tokens"
+]);
+function normalizeKey(key) {
+  return key.replace(/[-_]/g, "").toLowerCase();
+}
+function isSensitiveKey(key) {
+  if (SAFE_TOKEN_METRIC_KEYS.has(normalizeKey(key))) {
+    return false;
+  }
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
 function maskPIIString(text) {
   let masked = text;
   for (const rule of PII_RULES) {
@@ -110,7 +139,7 @@ function recursiveMaskPII(obj) {
   if (typeof obj === "object") {
     const res = {};
     for (const key of Object.keys(obj)) {
-      if (SENSITIVE_KEY_PATTERN.test(key)) {
+      if (isSensitiveKey(key)) {
         res[key] = "[MASKED_SECRET]";
       } else {
         res[key] = recursiveMaskPII(obj[key]);
@@ -323,6 +352,7 @@ function instrumentLLM(tracer, instance, optionsOrLabel = "llm.inference") {
     }
     const pathStr = path.join(".");
     return pathStr === "chat.completions.create" || // OpenAI
+    pathStr === "responses.create" || // OpenAI Responses API
     pathStr === "messages.create" || // Anthropic (Claude)
     pathStr === "models.generateContent" || // Google Gen AI 신규
     pathStr === "generateContent" || // Google Generative AI 기존
@@ -467,8 +497,10 @@ function instrumentTool(tracer, toolName, fn, metadata = {}) {
   });
 }
 
+// src/version.ts
+var SDK_VERSION = "1.0.3";
+
 // src/core/tracer.ts
-var SDK_VERSION = "1.0.0";
 var DEFAULT_ENDPOINT = "https://api.lynxops.co";
 var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 var DEFAULT_BATCH_SIZE = 50;

package/package.json

@@ -1,56 +1,59 @@
-{
-  "name": "@lynxops/sdk",
-  "version": "1.0.2",
-  "description": "TypeScript SDK for tracing, debugging, and governing AI agent runs with Lynx.",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --clean --dts",
-    "obfuscate": "javascript-obfuscator ./dist/index.js --output ./dist/index.js --config obfuscator.config.json && javascript-obfuscator ./dist/index.cjs --output ./dist/index.cjs --config obfuscator.config.json",
-    "build:prod": "pnpm build && pnpm obfuscate",
-    "check-types": "tsc --noEmit",
-    "test": "pnpm build && node --test test/*.mjs"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "observability",
-    "tracing",
-    "debugging",
-    "guardrails",
-    "lynx"
-  ],
-  "author": "Lynx",
-  "license": "ISC",
-  "devDependencies": {
-    "@types/node": "^25.9.1",
-    "javascript-obfuscator": "^4.1.1",
-    "tsup": "^8.3.5",
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {},
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hvnn-oss/lynx-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/hvnn-oss/lynx-sdk/issues"
-  },
-  "homepage": "https://github.com/hvnn-oss/lynx-sdk#readme",
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
-  }
-}
+{
+  "name": "@lynxops/sdk",
+  "version": "1.0.3",
+  "description": "TypeScript SDK for tracing, debugging, and governing AI agent runs with Lynx.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --clean --dts",
+    "check-types": "tsc --noEmit",
+    "test": "pnpm build && node --test test/*.mjs"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "observability",
+    "tracing",
+    "debugging",
+    "guardrails",
+    "lynx"
+  ],
+  "author": "Lynx",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hvnn-oss/lynx-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hvnn-oss/lynx-sdk/issues"
+  },
+  "homepage": "https://docs.lynxops.co",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}