Doc-201TypeScript SDK

Typed enforcement for agent calls.

The zero-dependency SDK wraps the inspection API, handles retries and timeouts, and provides guard helpers for model input and output.

1.0

Install

Terminal

npm install @otonomi/sdk
export OTONOMI_API_KEY="oton_sk_..."

The npm package ships with the first release. Until then, install it from the repository checkout (the built dist/ is committed):

Install from the repository

git clone https://github.com/Moisekenge/otonmi-v2
npm install ./otonmi-v2/packages/otonomi-sdk

2.0

Inspect directly

TypeScript

import { Otonomi } from '@otonomi/sdk';

const client = new Otonomi();
const result = await client.inspect({
  role: 'tool',
  content: toolOutput,
  tool_call: { name: 'read_file', arguments: { path } },
});

if (result.verdict === 'block') {
  throw new Error('Agent action blocked');
}

3.0

Guard a model call

TypeScript

import { Otonomi, guard, BlockedError } from '@otonomi/sdk';

const secured = guard(new Otonomi(), { checkOutput: true });

try {
  const { output } = await secured.chat(message, runModel, {
    extract: (response) => response.text,
  });
} catch (error) {
  if (error instanceof BlockedError) {
    console.error(error.phase, error.inspection.findings);
  }
}

4.0

Client options

baseUrl — override the hosted endpoint for self-hosting or tests. Precedence: explicit option → OTONOMI_BASE_URL env → hosted default.
apiKey — precedence: explicit option → OTONOMI_API_KEY env.
timeoutMs — per-attempt timeout; default 10 seconds.
maxRetries — retries for 429, 5xx, and transport failures; default 2.
fetch — inject a custom fetch implementation.
headers — attach caller-specific tracing headers.

5.0

Retries, timeouts, backoff

The client retries 429s, 5xxs, and transport failures (including timeouts) up to maxRetries times with exponential backoff — min(2000ms, 250ms × 2^attempt) — and honors the server's Retry-After header on 429 when it exceeds the computed backoff. Each attempt is bounded by timeoutMs via AbortController; when the budget is exhausted the SDK throws OtonomiError (e.g. “Inspection timed out after 10000ms”) with the HTTP status and request_id attached when available. 4xx errors other than 429 are not retried — they indicate a caller bug.

6.0

Blocking policy

guard() throws BlockedError when a verdict matches blockOn (default ['block']). The error carries phase ('input' or 'output') and the full inspection result, so your handler can log findings or route to review. For stricter gates, treat flags as blocking too:

TypeScript

const secured = guard(new Otonomi(), {
  checkOutput: true,
  blockOn: ['block', 'flag'],   // default: ['block']
});

7.0

Failure policy

The SDK surfaces transport errors and never chooses fail-open or fail-closed for you. Consumer assistants may fail open with logging; agents capable of destructive or financial actions should generally fail closed. Document the choice per workflow.