@supportbridge/sdk 0.9.4 → 0.9.5

package/README.md

@@ -1,345 +1,339 @@
-# SupportBridge SDK
-
-`@supportbridge/sdk` is the external, production-oriented SDK for adding tool-call telemetry, optional agent telemetry, configurable support triggers, deterministic operational policies, and MCP-compatible support experiences to software-company MCP servers.
-
-This package is independent from the internal SupportBridge demo. It does not import the demo server, dashboard, database, or test-user implementation.
-
-## What the first release provides
-
-- Framework-neutral MCP tool instrumentation
-- Tool name, timing, outcome, request correlation, sanitized arguments, and bounded result summaries
-- Optional agent-run and model-call spans
-- Async-local trace propagation from agent runs into MCP tool events
-- Immediate or non-blocking support-offer triggers
-- Repeated-failure triggers
-- Per-user, per-workspace, per-trace, or always-on trigger scopes
-- Accept, dismiss, and explicit reset decisions
-- Default secret redaction and payload-size limits
-- Batched asynchronous HTTP delivery with bounded retries
-- Queue overflow protection and fail-open behavior
-- Pluggable telemetry transport and trigger-state storage
-- Canonical, versioned policy schema with nested AND/OR/NOT conditions
-- Approved field and action registries with tenant-reference validation
-- Deterministic evaluation, traces, dry runs, conflict detection, and idempotent execution
-- Vendor-neutral natural-language compiler interface and deterministic local fake provider
-- Approval, immutable-version, rollback, and audit lifecycle primitives
-- An interactive MCP policy-builder app for Claude
-
-## Install
-
-Install the public package from npm:
-
-```bash
-npm install @supportbridge/sdk
-```
-
-To pin the current release explicitly:
-
-```bash
-npm install @supportbridge/sdk@0.9.4
-```
-
-Node.js 20 or newer is required.
-
-## Recommended one-call MCP installation
-
-For the official TypeScript MCP SDK, one call installs remote policy synchronization, support decisions, the UI-linked `talk_to_support` tool, the embedded chat app, app-only chat handlers, capability reporting, and graceful shutdown behavior:
-
-```ts
-import { SupportBridge } from "@supportbridge/sdk";
-
-const support = SupportBridge.install(server, {
-  source: "acme-mcp",
-  apiKey: process.env.SUPPORTBRIDGE_API_KEY!,
-  identify: context => ({
-    userId: context.authInfo.subject,
-    workspaceId: context.authInfo.workspaceId,
-    traits: { customer: context.authInfo.organizationName }
-  })
-});
-```
-
-Use the returned installer to wrap each business tool while keeping the same identity resolver:
-
-```ts
-server.tool(
-  "search_companies",
-  searchSchema,
-  support.instrumentTool("search_companies", searchCompanies)
-);
-```
-
-The wrapper captures bounded telemetry, enforces downloaded support triggers before execution, and retains recent sanitized failures for automatic ticket context. The installation also registers `open_policy_builder` and its embedded interactive app. No support tools or UI resources need to be registered manually.
-
-## Deterministic policy engine
-
-Natural language is never executable. A `PolicyNlpProvider` can propose a `CanonicalPolicy`, then deterministic code validates approved fields, operators, events, action parameters, and workspace-scoped references before simulation or publication.
-
-```ts
-import {
-  FakePolicyNlpProvider,
-  PolicyEngine,
-  PolicyRegistry,
-  validatePolicy
-} from "@supportbridge/sdk";
-
-const provider = new FakePolicyNlpProvider();
-const draft = await provider.compile({
-  prompt: "Route urgent enterprise billing conversations to Finance.",
-  workspaceId: "acme",
-  actorId: "admin_123",
-  references: { financeTeamId: "team_finance" }
-});
-
-const registry = new PolicyRegistry();
-const validation = validatePolicy(draft.policy, { registry });
-if (!validation.valid) throw new Error("Review the validation errors");
-
-const decision = new PolicyEngine(registry).evaluate(
-  [{ ...draft.policy, enabled: true, state: "dry_run" }],
-  { type: "conversation.created" },
-  { customer: { plan: "enterprise" }, conversation: { priority: "urgent" }, message: { classification: "billing" } },
-  { now: new Date(), eventId: "evt_1", correlationId: "corr_1", workspaceId: "acme" }
-);
-```
-
-Evaluation produces a decision plan; it never performs actions. Pass a plan to `executeDecisionPlan` with your authorized executor and durable `IdempotencyStore`. See [the policy engine guide](docs/policy-engine.md) for registries, lifecycle, simulations, and production adapters.
-
-If the embedded widget is missing or has scrolled out of view, the model calls `open_support_chat` with the existing `session_id`. Both `talk_to_support` and `open_support_chat` use the exact UI metadata and conversation lifecycle ported from the known-working SupportBridge connector. The embedded app uses `support_get_messages`, `support_send_message`, and `support_end_session` for the live conversation.
-
-Availability-gated sales and customer-success policies can assign an offer to a representative in the control plane. Eligible offers are published only while that representative is available. After the user agrees, the model calls `request_assistance`; the resulting live conversation is automatically assigned to the configured representative.
-
-Verify an installation with:
-
-```bash
-npx supportbridge doctor
-```
-
-Set `SUPPORTBRIDGE_URL` and `SUPPORTBRIDGE_API_KEY` first. The command checks health, authentication, policy retrieval, telemetry ingestion, and the packaged MCP App capability. The vendor dashboard reports the MCP source, installed SDK version, capabilities, and last-seen connection state.
-
-## Capture an MCP tool
-
-```ts
-import { SupportBridgeClient, instrumentMcpTool } from "@supportbridge/sdk";
-
-const supportbridge = new SupportBridgeClient({
-  source: "acme-mcp",
-  endpoint: "https://api.supportbridge.example",
-  apiKey: process.env.SUPPORTBRIDGE_API_KEY!,
-  triggers: [{
-    id: "climate-tech-concierge",
-    kind: "argument_match",
-    toolName: "list_companies",
-    path: "industry",
-    operator: "equals",
-    value: "Climate Tech",
-    action: "block_and_offer",
-    oncePer: "user"
-  }]
-});
-
-const listCompanies = instrumentMcpTool(
-  supportbridge,
-  "list_companies",
-  async args => ({
-    content: [{ type: "text", text: "Company results" }],
-    structuredContent: { count: 12 }
-  }),
-  {
-    identify: (_args, context) => ({
-      userId: context.auth.subject,
-      workspaceId: context.auth.workspaceId
-    })
-  }
-);
-```
-
-When the blocking trigger matches, the vendor handler is not executed. The MCP result contains:
-
-```json
-{
-  "structuredContent": {
-    "status": "awaiting_user_decision",
-    "support_available": true,
-    "support_offer_blocking": true,
-    "support_offer_status": "pending",
-    "support_offer_requires_acknowledgement": true,
-    "support_trigger_id": "climate-tech-concierge",
-    "accept_tool": "accept_support_offer",
-    "decline_tool": "dismiss_support_offer",
-    "retry_original_request_after_response": true,
-    "do_not_retry_or_bypass": true
-  }
-}
-```
-
-SupportBridge has three offer modes:
-
-- `offer` executes the business handler and attaches structured offer metadata without requiring a visible acknowledgement prompt.
-- `require_acknowledgement` executes the business handler, preserves its original `content` and `structuredContent`, and appends a transparent `LIVE ASSISTANCE AVAILABLE` notice with consent-gated accept and decline tools.
-- `block_and_offer` does not execute the business handler. It returns a successful `awaiting_user_decision` state that tells the host to pause until the user accepts or declines. It is not a tool error; genuine handler failures remain errors.
-
-MCP hosts control the visual presentation of these results. The SDK supplies portable structured state and explicit text instructions, and it never contacts a representative without the user's consent.
-
-Register the handlers returned by `supportDecisionTools` as MCP tools. After a user dismisses an offer, the original request can be retried without looping. Call `resetSupport` to make that trigger eligible again.
-
-## Embedded support chat (MCP App)
-
-`accept_support_offer` can create a durable ticket and open an inline chat in hosts that support the MCP Apps extension. Create the app kit and attach its metadata to the registered accept tool:
-
-```ts
-import {
-  createSupportChatApp,
-  supportDecisionTools
-} from "@supportbridge/sdk";
-
-const supportApp = createSupportChatApp(controlPlane);
-const decisions = supportDecisionTools(
-  supportbridge,
-  context => identifyUser(context),
-  { controlPlane, appMeta: supportApp.toolMeta }
-);
-```
-
-The MCP server must register these pieces using its framework:
-
-- `accept_support_offer`, with `supportApp.toolMeta` on the **tool definition**.
-- `dismiss_support_offer` as a normal model-visible tool.
-- `get_support_chat` and `send_support_message` from `supportApp.tools`, with app-only visibility.
-- A resource at `supportApp.resourceUri` whose read callback returns `supportApp.resourceContents()` and whose MIME type is `supportApp.mimeType`.
-
-For the official TypeScript MCP Apps SDK, use `registerAppTool` and `registerAppResource` from `@modelcontextprotocol/ext-apps/server`. The critical registration shape is:
-
-```ts
-registerAppTool(server, "accept_support_offer", {
-  description: "Open the human support conversation after the user consents.",
-  inputSchema: acceptSchema,
-  _meta: supportApp.toolMeta
-}, decisions.accept_support_offer);
-
-registerAppTool(server, "get_support_chat", {
-  inputSchema: getChatSchema,
-  _meta: { ui: { resourceUri: supportApp.resourceUri, visibility: ["app"] } }
-}, supportApp.tools.get_support_chat);
-
-registerAppTool(server, "send_support_message", {
-  inputSchema: sendMessageSchema,
-  _meta: { ui: { resourceUri: supportApp.resourceUri, visibility: ["app"] } }
-}, supportApp.tools.send_support_message);
-
-registerAppResource(server, "SupportBridge chat", supportApp.resourceUri, {
-  mimeType: supportApp.mimeType,
-  _meta: supportApp.resourceMeta
-}, async () => supportApp.resourceContents());
-```
-
-The HTML uses the standard `text/html;profile=mcp-app` resource type and MCP Apps JSON-RPC bridge. It receives the ticket ID from the accept-tool result, polls the ticket, and sends user messages through app-only MCP tools. Hosts without MCP Apps support continue to receive the ordinary text result.
-
-## Direct tool instrumentation
-
-For frameworks with custom middleware:
-
-```ts
-const result = await supportbridge.instrumentTool(
-  {
-    toolName: "search_companies",
-    arguments: { query: "fintech" },
-    identity: { userId: "user_34892", workspaceId: "acme" }
-  },
-  () => searchCompanies("fintech")
-);
-```
-
-The return value is discriminated by `kind`:
-
-- `result`: the vendor tool executed and `value` contains its result.
-- `support_offer`: execution was paused and `offer` contains the support decision payload.
-
-## Agent telemetry
-
-```ts
-import { traceAgentRun } from "@supportbridge/sdk";
-
-await traceAgentRun(
-  supportbridge,
-  {
-    agentName: "research-agent",
-    identity: { userId: "user_34892", workspaceId: "acme" }
-  },
-  async span => {
-    const startedAt = performance.now();
-    const response = await callYourModel();
-    span.recordModelCall({
-      provider: "your-provider",
-      model: "your-model",
-      startedAt,
-      inputTokens: response.usage.input,
-      outputTokens: response.usage.output
-    });
-    return response;
-  }
-);
-```
-
-Tool calls made inside `traceAgentRun` automatically inherit its trace and run identifiers through `AsyncLocalStorage`.
-
-## Privacy defaults
-
-The SDK captures sanitized tool arguments and bounded result summaries. It does **not** capture prompts or model responses unless `captureAgentContent` is explicitly enabled.
-
-Recognized credential fields are replaced with `[REDACTED]`. Payload depth, strings, arrays, and object keys are bounded before they enter the telemetry queue.
-
-```ts
-privacy: {
-  captureToolArguments: true,
-  captureToolResponses: true,
-  captureAgentContent: false,
-  sensitiveKeys: ["customer_access_code"],
-  maxStringLength: 1000
-}
-```
-
-Software companies should still document telemetry collection, obtain any required consent, and avoid sending regulated or unnecessary data.
-
-## Reliability model
-
-Telemetry is delivered outside the tool execution path. Delivery uses batches, timeouts, bounded exponential retries, and a maximum queue size. If SupportBridge is unavailable, vendor tools continue to operate and telemetry is dropped after the configured retry limit.
-
-Call `flush()` before short-lived processes exit and `close()` during graceful shutdown:
-
-```ts
-process.once("SIGTERM", () => void supportbridge.close());
-```
-
-## Trigger-state storage
-
-The default `MemoryTriggerStateStore` is appropriate for local development and a single process. Production vendors should supply a `TriggerStateStore` backed by Redis, PostgreSQL, or the SupportBridge control plane so decisions remain consistent across instances.
-
-## Development
-
-From this directory:
-
-```bash
-npm run check
-npm test
-npm run build
-```
-
-## Publishing releases
-
-npm releases are published automatically through GitHub Actions and npm Trusted Publishing. No npm token is stored in GitHub.
-
-1. Update the SDK version in `package.json` and update the changelog.
-2. Commit and push the release changes to `main`.
-3. Create and push a tag matching the package version exactly, such as `v0.8.2`.
-
-The `Publish SDK to npm` workflow verifies that the tag matches `package.json`, runs the type check and all tests, builds the package, and publishes it publicly with npm provenance. A mismatched tag or failed check stops the release before publication.
-
-The package intentionally has no runtime dependency on a particular MCP or agent framework. Framework-specific adapters can be added as separate packages without changing the core telemetry contract.
-
-See [the telemetry contract](docs/telemetry-contract.md) for backend ingestion details and [the security guide](SECURITY.md) before a production deployment.
-
-## Hosted control plane
-
-The repository also contains the first vendor-facing control plane in [`control-plane`](control-plane). It provides tenant-authenticated telemetry ingestion, SDK policy distribution, support conversations, and a live-visitor console with Visitor 360 context. See its [deployment and integration guide](control-plane/README.md).
+# SupportBridge SDK
+
+`@supportbridge/sdk` is the external, production-oriented SDK for adding tool-call telemetry, optional agent telemetry, configurable support triggers, deterministic operational policies, and MCP-compatible support experiences to software-company MCP servers.
+
+This package is independent from the internal SupportBridge demo. It does not import the demo server, dashboard, database, or test-user implementation.
+
+## What the first release provides
+
+- Framework-neutral MCP tool instrumentation
+- Tool name, timing, outcome, request correlation, sanitized arguments, and bounded result summaries
+- Optional agent-run and model-call spans
+- Async-local trace propagation from agent runs into MCP tool events
+- Immediate or non-blocking support-offer triggers
+- Repeated-failure triggers
+- Per-user, per-workspace, per-trace, or always-on trigger scopes
+- Accept, dismiss, and explicit reset decisions
+- Default secret redaction and payload-size limits
+- Batched asynchronous HTTP delivery with bounded retries
+- Queue overflow protection and fail-open behavior
+- Pluggable telemetry transport and trigger-state storage
+- Canonical, versioned policy schema with nested AND/OR/NOT conditions
+- Approved field and action registries with tenant-reference validation
+- Deterministic evaluation, traces, dry runs, conflict detection, and idempotent execution
+- Vendor-neutral natural-language compiler interface and deterministic local fake provider
+- Approval, immutable-version, rollback, and audit lifecycle primitives
+- An interactive MCP policy-builder app for Claude
+
+## Install
+
+Install the public package from npm:
+
+```bash
+npm install @supportbridge/sdk
+```
+
+Node.js 20 or newer is required.
+
+## Recommended one-call MCP installation
+
+For the official TypeScript MCP SDK, one call installs remote policy synchronization, support decisions, the UI-linked `talk_to_support` tool, the embedded chat app, app-only chat handlers, capability reporting, and graceful shutdown behavior:
+
+```ts
+import { SupportBridge } from "@supportbridge/sdk";
+
+const support = SupportBridge.install(server, {
+  source: "acme-mcp",
+  apiKey: process.env.SUPPORTBRIDGE_API_KEY!,
+  identify: context => ({
+    userId: context.authInfo.subject,
+    workspaceId: context.authInfo.workspaceId,
+    traits: { customer: context.authInfo.organizationName }
+  })
+});
+```
+
+Use the returned installer to wrap each business tool while keeping the same identity resolver:
+
+```ts
+server.tool(
+  "search_companies",
+  searchSchema,
+  support.instrumentTool("search_companies", searchCompanies)
+);
+```
+
+The wrapper captures bounded telemetry, enforces downloaded support triggers before execution, and retains recent sanitized failures for automatic ticket context. The installation also registers `open_policy_builder` and its embedded interactive app. No support tools or UI resources need to be registered manually.
+
+## Deterministic policy engine
+
+Natural language is never executable. A `PolicyNlpProvider` can propose a `CanonicalPolicy`, then deterministic code validates approved fields, operators, events, action parameters, and workspace-scoped references before simulation or publication.
+
+```ts
+import {
+  FakePolicyNlpProvider,
+  PolicyEngine,
+  PolicyRegistry,
+  validatePolicy
+} from "@supportbridge/sdk";
+
+const provider = new FakePolicyNlpProvider();
+const draft = await provider.compile({
+  prompt: "Route urgent enterprise billing conversations to Finance.",
+  workspaceId: "acme",
+  actorId: "admin_123",
+  references: { financeTeamId: "team_finance" }
+});
+
+const registry = new PolicyRegistry();
+const validation = validatePolicy(draft.policy, { registry });
+if (!validation.valid) throw new Error("Review the validation errors");
+
+const decision = new PolicyEngine(registry).evaluate(
+  [{ ...draft.policy, enabled: true, state: "dry_run" }],
+  { type: "conversation.created" },
+  { customer: { plan: "enterprise" }, conversation: { priority: "urgent" }, message: { classification: "billing" } },
+  { now: new Date(), eventId: "evt_1", correlationId: "corr_1", workspaceId: "acme" }
+);
+```
+
+Evaluation produces a decision plan; it never performs actions. Pass a plan to `executeDecisionPlan` with your authorized executor and durable `IdempotencyStore`. See [the policy engine guide](docs/policy-engine.md) for registries, lifecycle, simulations, and production adapters.
+
+If the embedded widget is missing or has scrolled out of view, the model calls `open_support_chat` with the existing `session_id`. Both `talk_to_support` and `open_support_chat` use the exact UI metadata and conversation lifecycle ported from the known-working SupportBridge connector. The embedded app uses `support_get_messages`, `support_send_message`, and `support_end_session` for the live conversation.
+
+Availability-gated sales and customer-success policies can assign an offer to a representative in the control plane. Eligible offers are published only while that representative is available. After the user agrees, the model calls `request_assistance`; the resulting live conversation is automatically assigned to the configured representative.
+
+Verify an installation with:
+
+```bash
+npx supportbridge doctor
+```
+
+Set `SUPPORTBRIDGE_URL` and `SUPPORTBRIDGE_API_KEY` first. The command checks health, authentication, policy retrieval, telemetry ingestion, and the packaged MCP App capability. The vendor dashboard reports the MCP source, installed SDK version, capabilities, and last-seen connection state.
+
+## Capture an MCP tool
+
+```ts
+import { SupportBridgeClient, instrumentMcpTool } from "@supportbridge/sdk";
+
+const supportbridge = new SupportBridgeClient({
+  source: "acme-mcp",
+  endpoint: "https://api.supportbridge.example",
+  apiKey: process.env.SUPPORTBRIDGE_API_KEY!,
+  triggers: [{
+    id: "climate-tech-concierge",
+    kind: "argument_match",
+    toolName: "list_companies",
+    path: "industry",
+    operator: "equals",
+    value: "Climate Tech",
+    action: "block_and_offer",
+    oncePer: "user"
+  }]
+});
+
+const listCompanies = instrumentMcpTool(
+  supportbridge,
+  "list_companies",
+  async args => ({
+    content: [{ type: "text", text: "Company results" }],
+    structuredContent: { count: 12 }
+  }),
+  {
+    identify: (_args, context) => ({
+      userId: context.auth.subject,
+      workspaceId: context.auth.workspaceId
+    })
+  }
+);
+```
+
+When the blocking trigger matches, the vendor handler is not executed. The MCP result contains:
+
+```json
+{
+  "structuredContent": {
+    "status": "awaiting_user_decision",
+    "support_available": true,
+    "support_offer_blocking": true,
+    "support_offer_status": "pending",
+    "support_offer_requires_acknowledgement": true,
+    "support_trigger_id": "climate-tech-concierge",
+    "accept_tool": "accept_support_offer",
+    "decline_tool": "dismiss_support_offer",
+    "retry_original_request_after_response": true,
+    "do_not_retry_or_bypass": true
+  }
+}
+```
+
+SupportBridge has three offer modes:
+
+- `offer` executes the business handler and attaches structured offer metadata without requiring a visible acknowledgement prompt.
+- `require_acknowledgement` executes the business handler, preserves its original `content` and `structuredContent`, and appends a transparent `LIVE ASSISTANCE AVAILABLE` notice with consent-gated accept and decline tools.
+- `block_and_offer` does not execute the business handler. It returns a successful `awaiting_user_decision` state that tells the host to pause until the user accepts or declines. It is not a tool error; genuine handler failures remain errors.
+
+MCP hosts control the visual presentation of these results. The SDK supplies portable structured state and explicit text instructions, and it never contacts a representative without the user's consent.
+
+Register the handlers returned by `supportDecisionTools` as MCP tools. After a user dismisses an offer, the original request can be retried without looping. Call `resetSupport` to make that trigger eligible again.
+
+## Embedded support chat (MCP App)
+
+`accept_support_offer` can create a durable ticket and open an inline chat in hosts that support the MCP Apps extension. Create the app kit and attach its metadata to the registered accept tool:
+
+```ts
+import {
+  createSupportChatApp,
+  supportDecisionTools
+} from "@supportbridge/sdk";
+
+const supportApp = createSupportChatApp(controlPlane);
+const decisions = supportDecisionTools(
+  supportbridge,
+  context => identifyUser(context),
+  { controlPlane, appMeta: supportApp.toolMeta }
+);
+```
+
+The MCP server must register these pieces using its framework:
+
+- `accept_support_offer`, with `supportApp.toolMeta` on the **tool definition**.
+- `dismiss_support_offer` as a normal model-visible tool.
+- `get_support_chat` and `send_support_message` from `supportApp.tools`, with app-only visibility.
+- A resource at `supportApp.resourceUri` whose read callback returns `supportApp.resourceContents()` and whose MIME type is `supportApp.mimeType`.
+
+For the official TypeScript MCP Apps SDK, use `registerAppTool` and `registerAppResource` from `@modelcontextprotocol/ext-apps/server`. The critical registration shape is:
+
+```ts
+registerAppTool(server, "accept_support_offer", {
+  description: "Open the human support conversation after the user consents.",
+  inputSchema: acceptSchema,
+  _meta: supportApp.toolMeta
+}, decisions.accept_support_offer);
+
+registerAppTool(server, "get_support_chat", {
+  inputSchema: getChatSchema,
+  _meta: { ui: { resourceUri: supportApp.resourceUri, visibility: ["app"] } }
+}, supportApp.tools.get_support_chat);
+
+registerAppTool(server, "send_support_message", {
+  inputSchema: sendMessageSchema,
+  _meta: { ui: { resourceUri: supportApp.resourceUri, visibility: ["app"] } }
+}, supportApp.tools.send_support_message);
+
+registerAppResource(server, "SupportBridge chat", supportApp.resourceUri, {
+  mimeType: supportApp.mimeType,
+  _meta: supportApp.resourceMeta
+}, async () => supportApp.resourceContents());
+```
+
+The HTML uses the standard `text/html;profile=mcp-app` resource type and MCP Apps JSON-RPC bridge. It receives the ticket ID from the accept-tool result, polls the ticket, and sends user messages through app-only MCP tools. Hosts without MCP Apps support continue to receive the ordinary text result.
+
+## Direct tool instrumentation
+
+For frameworks with custom middleware:
+
+```ts
+const result = await supportbridge.instrumentTool(
+  {
+    toolName: "search_companies",
+    arguments: { query: "fintech" },
+    identity: { userId: "user_34892", workspaceId: "acme" }
+  },
+  () => searchCompanies("fintech")
+);
+```
+
+The return value is discriminated by `kind`:
+
+- `result`: the vendor tool executed and `value` contains its result.
+- `support_offer`: execution was paused and `offer` contains the support decision payload.
+
+## Agent telemetry
+
+```ts
+import { traceAgentRun } from "@supportbridge/sdk";
+
+await traceAgentRun(
+  supportbridge,
+  {
+    agentName: "research-agent",
+    identity: { userId: "user_34892", workspaceId: "acme" }
+  },
+  async span => {
+    const startedAt = performance.now();
+    const response = await callYourModel();
+    span.recordModelCall({
+      provider: "your-provider",
+      model: "your-model",
+      startedAt,
+      inputTokens: response.usage.input,
+      outputTokens: response.usage.output
+    });
+    return response;
+  }
+);
+```
+
+Tool calls made inside `traceAgentRun` automatically inherit its trace and run identifiers through `AsyncLocalStorage`.
+
+## Privacy defaults
+
+The SDK captures sanitized tool arguments and bounded result summaries. It does **not** capture prompts or model responses unless `captureAgentContent` is explicitly enabled.
+
+Recognized credential fields are replaced with `[REDACTED]`. Payload depth, strings, arrays, and object keys are bounded before they enter the telemetry queue.
+
+```ts
+privacy: {
+  captureToolArguments: true,
+  captureToolResponses: true,
+  captureAgentContent: false,
+  sensitiveKeys: ["customer_access_code"],
+  maxStringLength: 1000
+}
+```
+
+Software companies should still document telemetry collection, obtain any required consent, and avoid sending regulated or unnecessary data.
+
+## Reliability model
+
+Telemetry is delivered outside the tool execution path. Delivery uses batches, timeouts, bounded exponential retries, and a maximum queue size. If SupportBridge is unavailable, vendor tools continue to operate and telemetry is dropped after the configured retry limit.
+
+Call `flush()` before short-lived processes exit and `close()` during graceful shutdown:
+
+```ts
+process.once("SIGTERM", () => void supportbridge.close());
+```
+
+## Trigger-state storage
+
+The default `MemoryTriggerStateStore` is appropriate for local development and a single process. Production vendors should supply a `TriggerStateStore` backed by Redis, PostgreSQL, or the SupportBridge control plane so decisions remain consistent across instances.
+
+## Development
+
+From this directory:
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+## Publishing releases
+
+npm releases are published automatically through GitHub Actions and npm Trusted Publishing. No npm token is stored in GitHub.
+
+1. Update the SDK version in `package.json` and update the changelog.
+2. Commit and push the release changes to `main`.
+3. Create and push a tag matching the package version exactly, such as `v0.8.2`.
+
+The `Publish SDK to npm` workflow verifies that the tag matches `package.json`, runs the type check and all tests, builds the package, and publishes it publicly with npm provenance. A mismatched tag or failed check stops the release before publication.
+
+The package intentionally has no runtime dependency on a particular MCP or agent framework. Framework-specific adapters can be added as separate packages without changing the core telemetry contract.
+
+See [the telemetry contract](docs/telemetry-contract.md) for backend ingestion details and [the security guide](SECURITY.md) before a production deployment.
+
+## Hosted control plane
+
+The repository also contains the first vendor-facing control plane in [`control-plane`](control-plane). It provides tenant-authenticated telemetry ingestion, SDK policy distribution, support conversations, and a live-visitor console with Visitor 360 context. See its [deployment and integration guide](control-plane/README.md).