@openbox-ai/openbox-mastra-sdk 0.1.0

package/docs/integration-patterns.md

@@ -0,0 +1,214 @@
+# Integration Patterns
+
+This SDK supports three integration patterns:
+
+1. `withOpenBox()` for standard application bootstrap
+2. manual wrapping with `wrapTool()`, `wrapWorkflow()`, and `wrapAgent()`
+3. telemetry-only setup with `setupOpenBoxOpenTelemetry()` and optional `traced()`
+
+## Choose The Right Pattern
+
+| Pattern | Use it when |
+| --- | --- |
+| `withOpenBox()` | you want one production runtime to govern the whole Mastra instance |
+| manual wrappers | you need explicit startup order or selective adoption |
+| telemetry-only | you want OpenBox span capture without full Mastra wrapping |
+
+## `withOpenBox()`
+
+`withOpenBox()` is the recommended integration path for most applications.
+
+```ts
+import { withOpenBox } from "@openbox-ai/openbox-mastra-sdk";
+
+const governedMastra = await withOpenBox(mastra, {
+  apiKey: process.env.OPENBOX_API_KEY,
+  apiUrl: process.env.OPENBOX_URL
+});
+```
+
+What it does:
+
+- parses and validates configuration
+- creates an `OpenBoxClient`
+- creates an `OpenBoxSpanProcessor`
+- installs process-wide telemetry
+- wraps current top-level tools, workflows, and agents
+- patches future `addTool()`, `addWorkflow()`, and `addAgent()` calls
+- hydrates agent-local tool and workflow registries where Mastra exposes them
+
+### Idempotency
+
+Calling `withOpenBox()` again on the same Mastra instance reuses the existing runtime instead of creating a second one.
+
+### Accepted Targets
+
+`withOpenBox()` accepts either:
+
+- a Mastra instance
+- an object with a `.mastra` property
+
+Example:
+
+```ts
+await withOpenBox({ mastra }, {
+  apiKey: process.env.OPENBOX_API_KEY,
+  apiUrl: process.env.OPENBOX_URL
+});
+```
+
+## Manual Wrapping
+
+Use manual wiring when you need to control bootstrap order or govern only a subset of components.
+
+```ts
+import {
+  OpenBoxClient,
+  OpenBoxSpanProcessor,
+  parseOpenBoxConfig,
+  setupOpenBoxOpenTelemetry,
+  wrapAgent,
+  wrapTool,
+  wrapWorkflow
+} from "@openbox-ai/openbox-mastra-sdk";
+
+const config = parseOpenBoxConfig({
+  apiKey: process.env.OPENBOX_API_KEY,
+  apiUrl: process.env.OPENBOX_URL
+});
+
+const client = new OpenBoxClient({
+  apiKey: config.apiKey,
+  apiUrl: config.apiUrl,
+  evaluateMaxRetries: config.evaluateMaxRetries,
+  evaluateRetryBaseDelayMs: config.evaluateRetryBaseDelayMs,
+  onApiError: config.onApiError,
+  timeoutSeconds: config.governanceTimeout
+});
+
+const spanProcessor = new OpenBoxSpanProcessor({
+  ignoredUrlPrefixes: [config.apiUrl]
+});
+
+const telemetry = setupOpenBoxOpenTelemetry({
+  captureHttpBodies: config.httpCapture,
+  governanceClient: client,
+  ignoredUrls: [config.apiUrl],
+  instrumentDatabases: config.instrumentDatabases,
+  instrumentFileIo: config.instrumentFileIo,
+  spanProcessor
+});
+
+const governedTool = wrapTool(tool, {
+  client,
+  config,
+  spanProcessor
+});
+
+const governedWorkflow = wrapWorkflow(workflow, {
+  client,
+  config,
+  spanProcessor
+});
+
+const governedAgent = wrapAgent(agent, {
+  client,
+  config,
+  spanProcessor
+});
+
+await telemetry.shutdown();
+```
+
+Use this pattern when:
+
+- another subsystem owns telemetry bootstrap order
+- you only want to govern selected tools, workflows, or agents
+- you need a custom `OpenBoxClient` or `OpenBoxSpanProcessor`
+
+## Telemetry-Only Setup
+
+If you want telemetry capture without automatic Mastra patching, install the telemetry layer directly:
+
+```ts
+import {
+  OpenBoxClient,
+  OpenBoxSpanProcessor,
+  setupOpenBoxOpenTelemetry,
+  traced
+} from "@openbox-ai/openbox-mastra-sdk";
+
+const client = new OpenBoxClient({
+  apiKey: process.env.OPENBOX_API_KEY!,
+  apiUrl: process.env.OPENBOX_URL!
+});
+
+const spanProcessor = new OpenBoxSpanProcessor({
+  ignoredUrlPrefixes: [process.env.OPENBOX_URL!]
+});
+
+const telemetry = setupOpenBoxOpenTelemetry({
+  governanceClient: client,
+  ignoredUrls: [process.env.OPENBOX_URL!],
+  spanProcessor
+});
+
+const governedFn = traced(
+  async function sendEmail(input: { to: string }) {
+    return { delivered: true, to: input.to };
+  },
+  {
+    captureArgs: true,
+    captureResult: true,
+    module: "email"
+  }
+);
+
+await telemetry.shutdown();
+```
+
+This pattern is useful when:
+
+- orchestration is not fully Mastra-managed
+- you want function-level tracing without wrapping all Mastra boundaries
+- you intend to emit lifecycle events yourself
+
+## Wrapper Behavior Summary
+
+### `wrapTool()`
+
+`wrapTool()` adds:
+
+- `ActivityStarted` and `ActivityCompleted`
+- verdict enforcement
+- guardrail input and output handling
+- approval suspension or polling
+- telemetry association for work performed during the tool call
+
+### `wrapWorkflow()`
+
+`wrapWorkflow()` adds:
+
+- `WorkflowStarted`, `WorkflowCompleted`, and `WorkflowFailed`
+- `SignalReceived` on resume
+- governed execution for non-tool workflow steps
+
+Tool component steps are intentionally not double-wrapped.
+
+### `wrapAgent()`
+
+`wrapAgent()` models an agent run as a workflow-like unit and adds:
+
+- workflow lifecycle events for the agent run
+- `SignalReceived` for `user_input`, `resume`, and `agent_output`
+- agent goal propagation
+- agent-only LLM spans routed through `agent_output`
+
+## Bootstrap Guidance
+
+For production services:
+
+1. initialize the SDK once during process startup
+2. keep a reference to the governed Mastra instance or runtime
+3. shut telemetry down during process termination
+4. avoid calling `setupOpenBoxOpenTelemetry()` multiple times in the same process unless you intentionally want to replace the active controller

package/docs/security-and-privacy.md

@@ -0,0 +1,174 @@
+# Security And Privacy
+
+This SDK is designed for governance-sensitive workloads. The defaults are conservative where transport, capture, and failure behavior matter most.
+
+## Transport Security
+
+The SDK rejects insecure non-localhost OpenBox URLs.
+
+Allowed:
+
+- `https://openbox.example.com`
+- `http://localhost:8086`
+- `http://127.0.0.1:8086`
+- `http://[::1]:8086`
+
+Rejected:
+
+- `http://openbox.example.com`
+
+Reason:
+
+- API keys must not be sent over plaintext HTTP outside local development
+
+## API Key Validation
+
+API keys must match:
+
+- `obx_live_*`
+- `obx_test_*`
+
+When `validate` is `true`, startup also verifies the key against OpenBox Core using `/api/v1/auth/validate`.
+
+Use `validate: false` only for:
+
+- tests
+- mock servers
+- deliberately offline local development
+
+## Capture Boundary
+
+The SDK can capture request and response bodies for HTTP telemetry, but it does so inside its own runtime rather than exposing that data as ordinary OTel span attributes.
+
+Key properties:
+
+- HTTP bodies are not stored as ordinary OTel span attributes
+- bodies and headers are buffered inside the SDK span processor
+- the data is merged into governance payloads only when required
+
+This reduces accidental leakage through generic tracing exporters.
+
+## Default Capture Posture
+
+| Setting | Default | Why |
+| --- | --- | --- |
+| `httpCapture` | `true` | useful governance and incident context |
+| `instrumentDatabases` | `true` | low-friction visibility into data access |
+| `instrumentFileIo` | `false` | file telemetry can be noisy and sensitive |
+
+If your environment is highly sensitive:
+
+- consider disabling `httpCapture`
+- enable it selectively in lower environments first
+- review OpenBox retention and policy posture before broad rollout
+
+## Text-Only HTTP Body Capture
+
+The SDK only treats text-like content as body-capturable text.
+
+Examples:
+
+- `text/*`
+- `application/json`
+- `application/xml`
+- `application/javascript`
+- `application/x-www-form-urlencoded`
+
+This avoids nonsensical capture of binary payloads.
+
+## File I/O Is Opt-In
+
+File instrumentation is disabled by default.
+
+When enabled, the SDK still skips common system and binary paths such as:
+
+- `/dev/`
+- `/proc/`
+- `/sys/`
+- `__pycache__`
+- `.so`
+- `.dylib`
+
+Do not enable file telemetry broadly unless you have a concrete policy or audit requirement for it.
+
+## Ignore Internal Service URLs
+
+Always ignore service URLs that should not be governed.
+
+Minimum recommendation:
+
+- ignore your OpenBox Core URL
+
+Why:
+
+- prevents the SDK from tracing and governing its own API calls
+- reduces noise
+- avoids governance loops
+
+`withOpenBox()` already adds `apiUrl` to the ignored URL set.
+
+## API Failure Policy
+
+`onApiError` controls what happens if OpenBox cannot be reached.
+
+### `fail_open`
+
+Use when:
+
+- service availability is more important than strict governance enforcement
+- governance outages must not stop production traffic
+
+Tradeoff:
+
+- requests can continue without a live governance decision
+
+### `fail_closed`
+
+Use when:
+
+- governance enforcement is mandatory
+- ungoverned execution is unacceptable
+
+Tradeoff:
+
+- OpenBox outages become execution blockers
+
+## Payload Size And Data Minimization
+
+The SDK limits large governance payloads through `maxEvaluatePayloadBytes`.
+
+When agent completion payloads are too large:
+
+- the SDK retries with a compact version
+- then retries with an ultra-minimal version if needed
+
+This keeps governance requests bounded without requiring unbounded payload growth.
+
+## Debug Logging
+
+`OPENBOX_DEBUG=true` enables summarized request and response logging.
+
+It logs:
+
+- event type
+- activity and workflow identity
+- presence of inputs, outputs, spans, and errors
+- retry attempts
+- verdict metadata summary
+
+It does not try to print full raw governance payloads by default.
+
+Recommendation:
+
+- enable it in development, staging, and incident response
+- keep it disabled by default in steady-state production unless your logging posture explicitly allows it
+
+## Production Hardening Checklist
+
+1. Use HTTPS for OpenBox Core.
+2. Keep `validate` enabled in production.
+3. Keep OpenBox Core ignored in telemetry capture.
+4. Decide explicitly between `fail_open` and `fail_closed`.
+5. Enable file I/O capture only if you need it.
+6. Review policy so hook-triggered telemetry is not mistaken for a second user action.
+7. Use OpenBox guardrails and retention controls for sensitive prompts or outputs.

package/docs/telemetry.md

@@ -0,0 +1,196 @@
+# Telemetry
+
+This SDK uses OpenTelemetry internally, but it does not simply forward raw spans to OpenBox. It captures, buffers, enriches, and normalizes telemetry into governance-ready payloads.
+
+## What The SDK Captures
+
+### HTTP
+
+Enabled by default through `httpCapture: true`.
+
+The SDK installs:
+
+- Node HTTP instrumentation
+- Undici instrumentation
+- fetch patching for request and response body capture
+
+This covers:
+
+- `fetch`
+- Node `http` and `https`
+- Undici-based clients
+
+Captured fields can include:
+
+- method
+- URL
+- request headers
+- response headers
+- request body
+- response body
+- status code
+
+Only text-like content types are treated as body-capturable text. Binary payloads are not captured as text.
+
+### Databases
+
+Enabled by default through `instrumentDatabases: true`.
+
+Supported selectors:
+
+- `pg`
+- `postgres`
+- `mysql`
+- `mysql2`
+- `mongodb`
+- `mongoose`
+- `redis`
+- `ioredis`
+- `knex`
+- `oracledb`
+- `cassandra`
+- `tedious`
+
+If `dbLibraries` is omitted, the SDK enables every supported DB instrumentation it can resolve.
+
+### File I/O
+
+Disabled by default through `instrumentFileIo: false`.
+
+When enabled, the SDK can emit spans for file operations such as:
+
+- open
+- read
+- write
+- readline
+- readlines
+- writelines
+- close
+
+Built-in skip patterns include:
+
+- `/dev/`
+- `/proc/`
+- `/sys/`
+- `\\?\pipe\`
+- `__pycache__`
+- `.pyc`
+- `.pyo`
+- `.so`
+- `.dylib`
+
+Override them with `fileSkipPatterns` when you install telemetry manually.
+
+### Traced Functions
+
+You can create explicit function spans with `traced()`:
+
+```ts
+import { traced } from "@openbox-ai/openbox-mastra-sdk";
+
+const summarize = traced(
+  async function summarize(text: string) {
+    return text.slice(0, 120);
+  },
+  {
+    captureArgs: true,
+    captureResult: true,
+    module: "summary"
+  }
+);
+```
+
+Supported options:
+
+- `captureArgs`
+- `captureResult`
+- `module`
+- `name`
+- `tracerName`
+
+## How Telemetry Reaches OpenBox
+
+The SDK has two telemetry paths:
+
+1. buffered spans attached to later workflow, activity, or signal payloads
+2. hook-triggered governance payloads sent during execution
+
+Hook-triggered payloads are used for internal operational spans such as HTTP, DB, file, and traced-function activity.
+
+## Hook Payload Characteristics
+
+Hook payloads:
+
+- include `hook_trigger: true`
+- include normalized OpenBox spans under `spans`
+- carry one started or completed span phase per hook event
+- attach to an existing parent workflow, activity, or agent context
+
+For agent-only LLM traffic with no separate business activity parent:
+
+- spans are queued
+- they are later emitted on `SignalReceived(agent_output)`
+
+## Privacy Boundary
+
+Bodies and headers are not stored as ordinary OTel span attributes. Instead:
+
+1. the SDK captures them into its internal span processor
+2. the SDK merges them into governance payloads when required
+3. generic OTel exporters are not relied on to carry those bodies
+
+This keeps OpenBox-specific governance context separate from generic tracing infrastructure.
+
+## Ignored URLs
+
+Always ignore URLs that should not be governed. At minimum, ignore your OpenBox Core URL.
+
+`withOpenBox()` already does this automatically by adding `apiUrl` to the ignored URL set.
+
+If you install telemetry manually, do the same:
+
+```ts
+const telemetry = setupOpenBoxOpenTelemetry({
+  governanceClient: client,
+  ignoredUrls: [config.apiUrl],
+  spanProcessor
+});
+```
+
+## Payload Budgeting
+
+Agent `WorkflowCompleted` payloads can grow large because they may include:
+
+- workflow output
+- model metadata
+- usage metrics
+- buffered spans
+
+The SDK handles this by attempting progressively smaller payloads:
+
+1. full payload
+2. compact payload
+3. ultra-minimal payload
+
+The threshold is controlled by `maxEvaluatePayloadBytes`.
+
+## Operational Recommendations
+
+- Keep `httpCapture` enabled unless payload sensitivity or volume makes that unacceptable.
+- Keep `instrumentDatabases` enabled in most environments.
+- Enable `instrumentFileIo` only when you need file-governance visibility.
+- Keep `ignoredUrls` aligned with internal service endpoints that should not be governed.
+- Do not initialize telemetry twice in the same process unless you intentionally want to replace the active controller.
+
+## Common Policy Interaction
+
+If policy treats hook-triggered telemetry as a second user action, you can see:
+
+- duplicate approvals
+- noisy `http_request`, `db_query`, `file_operation`, or `function_call` rows
+- approval loops while a parent activity is already pending approval
+
+Recommended policy behavior:
+
+- govern workflow and activity boundary events
+- treat hook-triggered payloads as internal telemetry unless you have a specific reason to gate them directly