@openbox-ai/openbox-mastra-sdk 0.1.0

package/docs/api-reference.md

@@ -0,0 +1,348 @@
+# API Reference
+
+This document summarizes the public API exported by `@openbox-ai/openbox-mastra-sdk`.
+
+It is an integration-focused reference, not a generated type reference. Use it to decide which module to import from and which entrypoints the SDK expects you to use.
+
+## Recommended Imports
+
+Most applications should import from the package root:
+
+```ts
+import {
+  getOpenBoxRuntime,
+  withOpenBox
+} from "@openbox-ai/openbox-mastra-sdk";
+```
+
+Use subpath imports only when you want to make module ownership explicit:
+
+- `@openbox-ai/openbox-mastra-sdk/client`
+- `@openbox-ai/openbox-mastra-sdk/config`
+- `@openbox-ai/openbox-mastra-sdk/mastra`
+- `@openbox-ai/openbox-mastra-sdk/otel`
+- `@openbox-ai/openbox-mastra-sdk/span`
+- `@openbox-ai/openbox-mastra-sdk/types`
+
+The `./governance` subpath exists, but it does not currently expose a public API surface of its own.
+
+## Root Export Families
+
+The root module re-exports:
+
+- client
+- config
+- mastra integration
+- telemetry
+- span processing
+- public types
+
+## Client Module
+
+Import path:
+
+```ts
+import { OpenBoxClient } from "@openbox-ai/openbox-mastra-sdk";
+```
+
+### `type OpenBoxApiErrorPolicy`
+
+```ts
+type OpenBoxApiErrorPolicy = "fail_open" | "fail_closed";
+```
+
+Controls how API failures are treated.
+
+### `interface OpenBoxClientOptions`
+
+Key fields:
+
+- `apiKey`
+- `apiUrl`
+- `evaluateMaxRetries`
+- `evaluateRetryBaseDelayMs`
+- `fetch`
+- `onApiError`
+- `timeoutSeconds`
+
+### `class OpenBoxClient`
+
+Main methods:
+
+- `validateApiKey(): Promise<void>`
+- `evaluate(payload): Promise<GovernanceVerdictResponse | null>`
+- `pollApproval(payload): Promise<ApprovalPollResponse | null>`
+
+Use this class when you need explicit control over transport, retries, or approval polling.
+
+## Config Module
+
+Import path:
+
+```ts
+import {
+  API_KEY_PATTERN,
+  getOpenBoxConfig,
+  initializeOpenBox,
+  parseOpenBoxConfig,
+  setOpenBoxConfig,
+  validateApiKeyFormat,
+  validateUrlSecurity
+} from "@openbox-ai/openbox-mastra-sdk";
+```
+
+### `interface OpenBoxConfigInput`
+
+User-supplied config surface. See [configuration.md](./configuration.md) for the complete option table.
+
+### `interface OpenBoxConfig`
+
+Normalized runtime config with defaults applied and iterable fields converted to `Set<string>`.
+
+### `parseOpenBoxConfig(input?, env?)`
+
+Parses:
+
+- explicit config options
+- environment variables
+
+Performs:
+
+- required field checks
+- API key format validation
+- URL security validation
+- default filling
+
+### `initializeOpenBox(input?)`
+
+Parses config and, if validation is enabled, validates the API key against OpenBox Core.
+
+Use it when:
+
+- you want config initialized before wiring wrappers
+- you want startup validation separate from `withOpenBox()`
+
+### `getOpenBoxConfig()` and `setOpenBoxConfig()`
+
+Access or override the global config singleton.
+
+Use sparingly. Prefer explicit runtime injection where practical.
+
+## Mastra Module
+
+Import path:
+
+```ts
+import {
+  getOpenBoxRuntime,
+  withOpenBox,
+  wrapAgent,
+  wrapTool,
+  wrapWorkflow
+} from "@openbox-ai/openbox-mastra-sdk";
+```
+
+### `interface WrapToolOptions`
+
+Shared dependency bag used by wrappers:
+
+- `client`
+- `config`
+- `spanProcessor`
+
+### `wrapTool(tool, options)`
+
+Wraps a Mastra tool in governed activity execution.
+
+Typical effects:
+
+- boundary activity events
+- verdict enforcement
+- guardrail handling
+- approval handling
+- telemetry association
+
+### `wrapWorkflow(workflow, options)`
+
+Wraps workflow lifecycle and non-tool workflow steps.
+
+Typical effects:
+
+- workflow start, completion, and failure events
+- resume signal events
+- governed step execution
+
+### `wrapAgent(agent, options)`
+
+Wraps agent lifecycle.
+
+Typical effects:
+
+- workflow-like lifecycle events for the agent run
+- `user_input`, `resume`, and `agent_output` signals
+- agent goal propagation
+- agent-only LLM spans routed through signal telemetry
+
+### `interface WithOpenBoxOptions`
+
+Extends `OpenBoxConfigInput` and adds:
+
+- `client`
+- `dbLibraries`
+- `fetch`
+- `fileSkipPatterns`
+- `ignoredUrls`
+- `spanProcessor`
+
+### `interface OpenBoxRuntime`
+
+Runtime returned indirectly by `withOpenBox()` and accessible via `getOpenBoxRuntime()`.
+
+Fields:
+
+- `client`
+- `config`
+- `spanProcessor`
+- `telemetry`
+- `shutdown()`
+
+### `withOpenBox(target, options?)`
+
+Recommended zero-code integration.
+
+Accepts:
+
+- a Mastra instance
+- an object containing `.mastra`
+
+Creates runtime, patches Mastra, installs telemetry, and returns the same logical target.
+
+### `getOpenBoxRuntime(target)`
+
+Returns the installed runtime when available. Use it for:
+
+- shutdown
+- access to normalized config
+- direct access to the client or span processor
+
+## Telemetry Module
+
+Import path:
+
+```ts
+import {
+  setupOpenBoxOpenTelemetry,
+  traced
+} from "@openbox-ai/openbox-mastra-sdk";
+```
+
+### `interface OpenBoxTelemetryOptions`
+
+Fields:
+
+- `spanProcessor`
+- `governanceClient`
+- `captureHttpBodies`
+- `dbLibraries`
+- `fileSkipPatterns`
+- `ignoredUrls`
+- `instrumentDatabases`
+- `instrumentFileIo`
+- `onHookApiError`
+
+### `interface OpenBoxTelemetryController`
+
+Fields:
+
+- `instrumentations`
+- `tracerProvider`
+- `shutdown()`
+
+### `setupOpenBoxOpenTelemetry(options)`
+
+Installs the SDK's process-wide telemetry layer.
+
+Use it directly when:
+
+- you are not using `withOpenBox()`
+- you need explicit bootstrap order
+- you only want telemetry without full Mastra patching
+
+### `interface OpenBoxTracedOptions`
+
+Fields:
+
+- `captureArgs`
+- `captureResult`
+- `module`
+- `name`
+- `tracerName`
+
+### `traced(fn, options?)`
+
+Wraps an async function in a traced function span.
+
+Use it for:
+
+- custom operations outside standard tool or workflow boundaries
+- explicitly named operational spans
+- additional policy-relevant function telemetry
+
+## Span Module
+
+Import path:
+
+```ts
+import { OpenBoxSpanProcessor } from "@openbox-ai/openbox-mastra-sdk";
+```
+
+### `class OpenBoxSpanProcessor`
+
+Implements the OpenTelemetry `SpanProcessor` interface and manages the SDK's enriched governance span buffer.
+
+Typical usage:
+
+- pass it to `setupOpenBoxOpenTelemetry()`
+- reuse it across wrappers
+- let `withOpenBox()` create it unless you need manual control
+
+Exported companion types:
+
+- `StoredSpanBody`
+- `StoredTraceBody`
+- `StoredWorkflowVerdict`
+- `OpenBoxSpanData`
+- `OpenBoxSpanProcessorOptions`
+- `WorkflowSpanProcessor` as an alias of `OpenBoxSpanProcessor`
+
+## Types Module
+
+Import path:
+
+```ts
+import {
+  ApprovalExpiredError,
+  ApprovalPendingError,
+  ApprovalRejectedError,
+  GovernanceAPIError,
+  GovernanceVerdictResponse,
+  GovernanceHaltError,
+  GuardrailsCheckResult,
+  GuardrailsValidationError,
+  OpenBoxAuthError,
+  OpenBoxConfigError,
+  OpenBoxError,
+  OpenBoxInsecureURLError,
+  OpenBoxNetworkError,
+  Verdict,
+  WorkflowEventType,
+  WorkflowSpanBuffer
+} from "@openbox-ai/openbox-mastra-sdk";
+```
+
+Use the exported types for:
+
+- explicit error handling
+- verdict inspection
+- workflow event matching
+- testing and integration typing

package/docs/approvals-and-guardrails.md

@@ -0,0 +1,163 @@
+# Approvals And Guardrails
+
+This document explains how OpenBox verdicts are enforced by the SDK and how guardrails behave in live runs.
+
+## Verdicts
+
+The SDK understands these primary verdicts:
+
+| Verdict | Meaning | Runtime effect |
+| --- | --- | --- |
+| `allow` | continue normally | execution proceeds |
+| `constrain` | continue with advisory constraints | execution proceeds and constraints remain available in the response |
+| `require_approval` | human review required | execution suspends or polls for approval |
+| `block` | operation must not continue | execution throws a stop-style error |
+| `halt` | workflow or agent run must stop | execution throws a halt error |
+
+Legacy action strings such as `continue`, `stop`, and `require-approval` are normalized into these verdicts.
+
+## Enforcement Model
+
+The SDK enforces verdicts at boundary events.
+
+For governed activities:
+
+1. `ActivityStarted` is evaluated first
+2. input-side guardrail handling may apply
+3. the underlying tool or step executes
+4. `ActivityCompleted` is evaluated
+5. output-side guardrail handling may apply
+6. approval may be required on either side
+
+For workflows and agents:
+
+- `WorkflowStarted` can stop execution early
+- `WorkflowCompleted` can still be evaluated for policy and telemetry
+- `WorkflowFailed` records failure context
+
+## Important Live-Run Behavior
+
+In a standard OpenBox Core deployment, policy evaluates before guardrails for an event.
+
+Operational consequence:
+
+- if policy returns a non-`allow` verdict such as `require_approval`, `block`, or `halt`, guardrails for that event may not run
+- if you are testing a guardrail live and it does not fire, inspect the policy verdict first
+
+This is the most common reason a guardrail UI test passes while the live run still shows no guardrail result.
+
+## Guardrail Input And Output Handling
+
+OpenBox responses may contain `guardrails_result`.
+
+The SDK uses it in two ways.
+
+### Input Redaction
+
+If the response for `ActivityStarted` includes:
+
+- `guardrails_result.input_type = "activity_input"`
+- `guardrails_result.redacted_input`
+
+the SDK applies the redacted input before calling the underlying tool or step.
+
+### Output Redaction
+
+If the response for `ActivityCompleted` includes:
+
+- `guardrails_result.input_type = "activity_output"`
+- `guardrails_result.redacted_input`
+
+the SDK applies that redacted output before returning it to the caller.
+
+### Validation Failure
+
+If `guardrails_result.validation_passed` is `false`, the SDK throws `GuardrailsValidationError`.
+
+## Guardrail Field Selection Guidance
+
+For live activity guardrails, match against `ActivityStarted` fields whenever possible.
+
+Recommended field targets:
+
+| Activity type | Field to check | Example use |
+| --- | --- | --- |
+| `writeFile` | `input.content` | banned content or PII in file contents |
+| `writeFile` | `input.path` | path-based restrictions |
+| `runCommand` | `input.command` | banned shell commands |
+
+Important:
+
+- agent prompts are emitted as `SignalReceived(user_input)`, not as `ActivityStarted`
+- if your OpenBox deployment only evaluates guardrails on activity events, a `user_input` guardrail will not inspect agent prompts directly
+
+## Human Approval Flow
+
+The approval path depends on where execution is happening.
+
+### Workflow-Backed Activity Execution
+
+When a tool or step executes inside a workflow context and OpenBox returns `require_approval`:
+
+- the SDK creates approval state
+- the workflow suspends through Mastra suspend or resume behavior
+- approval context is stored in the approval registry
+- later resume paths emit `SignalReceived` and poll approval status
+
+This is the preferred path for long-running human review.
+
+### Non-Workflow Activity Execution
+
+When there is no workflow suspend context available, the SDK polls approval inline.
+
+Current inline polling characteristics:
+
+- total timeout: 5 minutes
+- initial poll interval: 2.5 seconds
+- exponential backoff up to 15 seconds
+
+If approval does not resolve in time, the SDK throws `ApprovalPendingError`.
+
+## Approval Outcomes
+
+While polling approval status:
+
+- `allow` marks the activity approved and execution continues
+- `block` or `halt` throws `ApprovalRejectedError`
+- expired approval throws `ApprovalExpiredError`
+- missing or temporary approval API failures retry with backoff until timeout
+
+## Output-Time Approval
+
+Approval is not limited to `ActivityStarted`.
+
+If `ActivityCompleted` returns `require_approval`, the SDK can:
+
+- suspend the workflow after execution and before returning output
+- or poll inline when no workflow suspension context exists
+
+This is useful when policy wants to review actual output, not just the requested action.
+
+## Agents And Approval
+
+Wrapped agents also participate in approval handling through their workflow-like lifecycle.
+
+Because agent runs emit `user_input`, `resume`, and `agent_output`, approval state can be resumed consistently across retries or resume calls.
+
+## Runtime Errors You Should Expect
+
+| Error | Meaning |
+| --- | --- |
+| `GovernanceHaltError` | OpenBox returned a stop or halt verdict, or a fail-closed API failure was converted into a halt |
+| `GuardrailsValidationError` | guardrail validation failed |
+| `ApprovalPendingError` | approval is still pending or inline polling timed out |
+| `ApprovalRejectedError` | approval explicitly rejected the activity |
+| `ApprovalExpiredError` | approval expired before resolution |
+
+## Production Recommendations
+
+1. Keep approval policy focused on business boundary events.
+2. Treat hook-triggered telemetry as internal by default.
+3. When testing guardrails live, make sure policy returns `allow` for that event.
+4. Use `ActivityStarted` field selectors for tool-input guardrails.
+5. Do not rely on `SignalReceived(user_input)` guardrails unless your OpenBox deployment explicitly supports guardrails on signals.

package/docs/architecture.md

@@ -0,0 +1,186 @@
+# Architecture
+
+This document explains how the SDK is structured so you can reason about deployment behavior, ownership, and operational tradeoffs.
+
+## Design Goals
+
+The SDK is built around four goals:
+
+1. keep governance decisions at clear business boundaries
+2. attach operational telemetry to those boundaries without building a custom tracing layer
+3. preserve approval state across workflow and agent resume paths
+4. make the default integration path safe enough for production bootstrap
+
+## High-Level Layout
+
+```text
+Mastra application
+|- tools
+|- workflows
+`- agents
+    |
+    v
+OpenBox Mastra SDK
+|- Mastra wrappers
+|  |- wrapTool()
+|  |- wrapWorkflow()
+|  |- wrapAgent()
+|  `- withOpenBox()
+|- Governance runtime
+|  |- OpenBoxClient
+|  |- config parsing
+|  `- approval registry
+|- Telemetry runtime
+|  |- OpenBoxSpanProcessor
+|  |- OpenTelemetry instrumentation
+|  `- hook-governance bridge
+`- Public type surface
+    |- verdicts
+    |- guardrails
+    |- workflow events
+    `- runtime errors
+    |
+    v
+OpenBox Core
+|- /api/v1/auth/validate
+|- /api/v1/governance/evaluate
+`- /api/v1/governance/approval
+```
+
+## Main Runtime Components
+
+### `withOpenBox()`
+
+Responsibilities:
+
+- create the OpenBox runtime
+- install process-wide telemetry
+- patch current and future Mastra registries
+- expose a runtime handle for shutdown and diagnostics
+
+Operational implication:
+
+- one governed Mastra process should normally have one active OpenBox runtime
+
+### `OpenBoxClient`
+
+Responsibilities:
+
+- validate the API key
+- send evaluate requests
+- poll approval status
+- apply retry and timeout policy
+- summarize debug logging when `OPENBOX_DEBUG=true`
+
+Operational implication:
+
+- API failure behavior is controlled centrally through `onApiError`
+
+### `OpenBoxSpanProcessor`
+
+Responsibilities:
+
+- buffer spans by workflow and run
+- associate child telemetry with parent activity or workflow context
+- hold captured HTTP bodies and headers until governance payload assembly
+- queue agent-only LLM telemetry until the `agent_output` signal is emitted
+
+Operational implication:
+
+- telemetry is enriched inside the SDK before it becomes an OpenBox governance payload
+
+### Approval Registry
+
+Responsibilities:
+
+- track approval state across resume paths
+- keep workflow-backed approval flows coherent
+- prevent approval handling from being tied only to a single stack frame
+
+Operational implication:
+
+- approval state is runtime control data, not a persistence layer
+
+## Boundary And Telemetry Model
+
+The SDK distinguishes between two kinds of data:
+
+- business boundary events such as `ActivityStarted`, `ActivityCompleted`, and workflow lifecycle events
+- internal operational telemetry such as HTTP, database, file, and traced-function spans
+
+This distinction matters because:
+
+- policy is usually easiest to reason about at business boundaries
+- hook-triggered telemetry can be noisy if treated as a second user action
+- approvals become harder to operate if both layers are governed the same way
+
+## Execution Flows
+
+### Tool Or Step Execution
+
+```text
+boundary starts
+-> ActivityStarted
+-> verdict and guardrail handling
+-> underlying execution
+-> telemetry capture during execution
+-> ActivityCompleted
+-> output verdict and guardrail handling
+-> return or suspend
+```
+
+### Workflow Execution
+
+```text
+workflow starts
+-> WorkflowStarted
+-> governed steps run
+-> optional SignalReceived on resume
+-> WorkflowCompleted or WorkflowFailed
+```
+
+### Agent Execution
+
+```text
+agent run starts
+-> WorkflowStarted
+-> SignalReceived(user_input)
+-> underlying agent execution
+-> agent LLM and hook telemetry captured
+-> SignalReceived(agent_output)
+-> WorkflowCompleted or WorkflowFailed
+```
+
+## Why Signals Matter
+
+Signals are not just a workflow resume mechanism in this SDK. They also carry agent-specific lifecycle state.
+
+Production implications:
+
+- agent prompt input is emitted as `SignalReceived(user_input)`
+- agent output and agent-only LLM spans are emitted through `SignalReceived(agent_output)`
+- if you suppress or ignore those signals, you lose the main observability path for agent-level prompt and completion context
+
+## Telemetry Ownership
+
+`setupOpenBoxOpenTelemetry()` manages one active telemetry controller per process.
+
+Operational implications:
+
+- initializing telemetry twice replaces the previous controller
+- shutdown should happen during process termination
+- the OpenBox API URL should be ignored to avoid tracing and governing the SDK's own API traffic
+
+## Failure Model
+
+The SDK treats these as distinct classes of failure:
+
+- OpenBox API failure
+- governance stop or halt verdict
+- approval pending, rejected, or expired
+- guardrail validation failure
+- underlying tool, workflow, or agent failure
+
+Those differences are preserved in the surfaced runtime errors so application code can respond intentionally.
+
+See [approvals-and-guardrails.md](./approvals-and-guardrails.md) for enforcement details and [troubleshooting.md](./troubleshooting.md) for common failure modes.