@supportbridge/sdk 0.8.1

package/dist/types.d.ts

@@ -0,0 +1,221 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface SupportIdentity {
+    userId: string;
+    workspaceId?: string;
+    tenantId?: string;
+    traits?: Record<string, JsonPrimitive>;
+}
+export interface TraceContext {
+    traceId: string;
+    runId?: string;
+    parentSpanId?: string;
+    identity?: SupportIdentity;
+}
+export type ToolOutcome = "success" | "error" | "timeout" | "empty" | "blocked" | "cancelled";
+export interface TelemetryBase {
+    id: string;
+    type: "tool_call" | "agent_run" | "model_call" | "support_decision" | "policy_evaluation" | "sdk_diagnostic";
+    timestamp: string;
+    sdkName: "@supportbridge/sdk";
+    sdkVersion: string;
+    source: string;
+    serviceVersion?: string;
+    environment?: string;
+    identity?: SupportIdentity;
+    traceId?: string;
+    runId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    attributes?: Record<string, JsonValue>;
+}
+export interface ToolCallEvent extends TelemetryBase {
+    type: "tool_call";
+    toolName: string;
+    outcome: ToolOutcome;
+    durationMs: number;
+    arguments?: JsonValue;
+    responseSummary?: JsonValue;
+    errorCode?: string;
+    errorMessage?: string;
+    triggerId?: string;
+    requestId?: string;
+}
+export interface AgentRunEvent extends TelemetryBase {
+    type: "agent_run";
+    agentName: string;
+    phase: "started" | "completed";
+    outcome?: "success" | "error" | "cancelled";
+    durationMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface ModelCallEvent extends TelemetryBase {
+    type: "model_call";
+    provider: string;
+    model: string;
+    outcome: "success" | "error" | "timeout";
+    durationMs: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    prompt?: JsonValue;
+    response?: JsonValue;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface SupportDecisionEvent extends TelemetryBase {
+    type: "support_decision";
+    triggerId: string;
+    decision: "offered" | "presented" | "accepted" | "dismissed" | "expired" | "reset";
+    reason?: string;
+}
+export interface PolicyEvaluationEvent extends TelemetryBase {
+    type: "policy_evaluation";
+    policyId: string;
+    policyVersion: number;
+    eventId: string;
+    correlationId: string;
+    workspaceId: string;
+    matchResult: boolean;
+    durationMs: number;
+    conditionTrace: JsonValue;
+    proposedActions: JsonValue;
+    suppressedActions: JsonValue;
+    skippedReason?: string;
+    missingFields?: string[];
+}
+export interface SdkDiagnosticEvent extends TelemetryBase {
+    type: "sdk_diagnostic";
+    code: "queue_overflow" | "delivery_failed" | "invalid_identity" | "installation_verified" | "doctor_check";
+    message: string;
+    droppedEvents?: number;
+    capabilities?: Record<string, JsonValue>;
+}
+export interface SupportBrief {
+    issue: string;
+    errorCode?: string;
+    customer?: string;
+    recentToolCalls: Array<{
+        timestamp: string;
+        toolName: string;
+        outcome: ToolOutcome;
+        arguments?: JsonValue;
+        errorCode?: string;
+        errorMessage?: string;
+    }>;
+}
+export type TelemetryEvent = ToolCallEvent | AgentRunEvent | ModelCallEvent | SupportDecisionEvent | PolicyEvaluationEvent | SdkDiagnosticEvent;
+export type TelemetryEventBase = Omit<TelemetryBase, "type">;
+export interface PrivacyOptions {
+    captureToolArguments?: boolean;
+    captureToolResponses?: boolean;
+    captureAgentContent?: boolean;
+    sensitiveKeys?: string[];
+    maxStringLength?: number;
+    maxArrayLength?: number;
+    maxObjectKeys?: number;
+    maxDepth?: number;
+    redactionText?: string;
+}
+export interface ResolvedPrivacyOptions {
+    captureToolArguments: boolean;
+    captureToolResponses: boolean;
+    captureAgentContent: boolean;
+    sensitiveKeys: string[];
+    maxStringLength: number;
+    maxArrayLength: number;
+    maxObjectKeys: number;
+    maxDepth: number;
+    redactionText: string;
+}
+export interface ArgumentTrigger {
+    id: string;
+    kind: "argument_match";
+    toolName: string | RegExp;
+    path: string;
+    operator: "equals" | "contains" | "matches";
+    value: string;
+    action: "offer" | "require_acknowledgement" | "block_and_offer";
+    oncePer?: "user" | "workspace" | "trace" | "always";
+    reason?: string;
+    motion?: "support" | "assistance";
+    assignedRep?: {
+        id: string;
+        name: string;
+        status: string;
+    };
+}
+export interface RepeatedFailureTrigger {
+    id: string;
+    kind: "repeated_failure";
+    toolName?: string | RegExp;
+    threshold: number;
+    windowMs: number;
+    sameErrorCode?: boolean;
+    action: "offer" | "require_acknowledgement" | "block_and_offer";
+    oncePer?: "user" | "workspace" | "trace" | "always";
+    reason?: string;
+    motion?: "support" | "assistance";
+    assignedRep?: {
+        id: string;
+        name: string;
+        status: string;
+    };
+}
+export type SupportTrigger = ArgumentTrigger | RepeatedFailureTrigger;
+export interface SupportOffer {
+    triggerId: string;
+    reason: string;
+    blocking: boolean;
+    requiresAcknowledgement: boolean;
+    message: string;
+    retryOriginalRequestAfterDecision: boolean;
+    motion?: "support" | "assistance";
+    assignedRep?: {
+        id: string;
+        name: string;
+        status: string;
+    };
+}
+export type SupportDecision = "accepted" | "dismissed";
+export interface ToolInvocation<TArguments = unknown> {
+    toolName: string;
+    arguments: TArguments;
+    identity?: SupportIdentity;
+    requestId?: string;
+    traceId?: string;
+    runId?: string;
+    parentSpanId?: string;
+    attributes?: Record<string, JsonValue>;
+}
+export type InstrumentedToolResult<TResult> = {
+    kind: "result";
+    value: TResult;
+    offer?: SupportOffer;
+} | {
+    kind: "support_offer";
+    offer: SupportOffer;
+};
+export interface AgentRunOptions {
+    agentName: string;
+    identity?: SupportIdentity;
+    traceId?: string;
+    runId?: string;
+    attributes?: Record<string, JsonValue>;
+}
+export interface ModelCallOptions {
+    provider: string;
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    prompt?: unknown;
+    response?: unknown;
+    error?: unknown;
+    startedAt?: number;
+    attributes?: Record<string, JsonValue>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/policy-engine.md

@@ -0,0 +1,47 @@
+# Policy engine
+
+SupportBridge policies have one executable form: `CanonicalPolicy` schema version `1.0`. Both the natural-language and manual authoring experiences operate on that object. The original prompt is audit context, never executable input.
+
+## Safety boundary
+
+- Only paths in `PolicyRegistry.fields` can be read.
+- Each field declares its value type and allowed operators.
+- Only actions in `PolicyRegistry.actions` can enter a decision plan.
+- Action parameters are typed and reference parameters can be checked by a `PolicyReferenceResolver`.
+- Unknown paths, operators, events, actions, parameters, unsafe patterns, and cross-workspace references fail validation.
+- Evaluation receives an explicit clock, has bounded condition depth and action counts, and prevents a policy from reprocessing an event it emitted.
+- Simulations call the pure evaluator and never call an action executor.
+
+## Authoring pipeline
+
+`PolicyNlpProvider` is vendor-neutral. Its `compile` method returns a canonical draft, assumptions, ambiguities, unsupported requests, confidence, and an explanation. `FakePolicyNlpProvider` is deterministic and intended for local development and automated tests. A production LLM provider must use schema-constrained output and still pass the result through `validatePolicy`.
+
+The MCP installation registers `open_policy_builder`, `generate_policy_draft`, `validate_policy_draft`, and `simulate_policy_draft`, plus `ui://supportbridge/policy-builder.html`. The embedded app visibly supports “Describe with AI” and “Build manually.” The draft stays in one canonical object while the administrator switches modes.
+
+## Evaluation and execution
+
+`PolicyEngine.evaluate` sorts by priority, category, then stable policy ID. It returns condition traces, proposed or dry-run-suppressed actions, missing fields, conflicts, and deterministic deduplication keys. It does not perform side effects.
+
+Use `executeDecisionPlan` only after authorization. Supply a persistent `IdempotencyStore` in distributed production systems; `MemoryIdempotencyStore` is for local or single-process use.
+
+## Governance
+
+`MemoryPolicyStore` demonstrates the lifecycle contract:
+
+1. Create and update a revision-checked draft.
+2. Validate and request approval.
+3. Require another authorized actor to approve.
+4. Publish an immutable version, initially in dry-run mode by default.
+5. Disable or roll back by appending a new version.
+6. Retain workspace-scoped audit events and version diffs.
+
+Production control planes should implement the same contract with durable transactions, tenant authorization, encrypted storage, rate limits, and an append-only audit log.
+
+## Production extension points
+
+- Add approved domain fields and resolvers through `PolicyRegistry`.
+- Add typed actions and tenant reference kinds through action definitions.
+- Implement `PolicyReferenceResolver` against the active tenant catalog.
+- Implement `PolicyNlpProvider` for the chosen model vendor.
+- Implement durable policy, evaluation-log, action-execution, and idempotency repositories.
+- Send policy evaluation metrics and redacted traces through the existing telemetry transport.

package/docs/telemetry-contract.md

@@ -0,0 +1,29 @@
+# Telemetry contract
+
+All events include `eventId`, `type`, `timestamp`, `source`, `environment`, and `sdkVersion`. When available, they also include `traceId`, `spanId`, `parentSpanId`, `runId`, `requestId`, `serviceVersion`, and a sanitized identity.
+
+## Tool calls
+
+`tool_call` records the tool name, start and end time, duration, outcome, sanitized arguments, a bounded result summary, and normalized error details. Tool events can also include a support offer and the trigger that produced it.
+
+## Agent runs
+
+`agent_run` records the agent name, timing, status, and optional metadata. Prompt or response content is collected only when `captureAgentContent` is enabled.
+
+## Model calls
+
+`model_call` records provider, model, timing, status, token counts, and optional error details. Input and output content follow the same explicit opt-in rule as agent content.
+
+## Delivery
+
+Events are queued in memory and sent in JSON batches:
+
+```json
+{
+  "events": []
+}
+```
+
+The HTTP transport sends `content-type: application/json`, `user-agent: supportbridge-sdk/0.1.0`, and, when configured, `authorization: Bearer <apiKey>`. A non-2xx response is retried by the buffered transport up to its configured limit. Delivery failures do not change the vendor tool result.
+
+Event types are exported from the package so a backend can validate and persist the same contract without depending on internal implementation files.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@supportbridge/sdk",
+  "version": "0.8.1",
+  "description": "Production-oriented MCP tool-call and agent telemetry SDK for SupportBridge",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "supportbridge": "./dist/doctor.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "telemetry",
+    "support",
+    "agents",
+    "observability"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js"
+  }
+}