@intended-inc/sdk

The TypeScript SDK for the Intended Authority runtime.

Put an agent action under governance with one call. Instead of executing directly, you wrap the action — the Intended Authority runtime classifies it, scores its risk, evaluates it against your policy, and returns ALLOW, ESCALATE, or DENY. On allow you get a signed, verifiable Authority Token; everything is written to a tamper-evident audit chain.

npm install @intended-inc/sdk

Runtime dependencies: jose and zod. Node 18+ (uses the platform fetch). Apache-2.0.

The Intended Authority runtime is a hosted service. This SDK is the typed client you talk to it with — it does not contain the decision engine itself. The one thing the SDK does fully offline is verify the signed Authority Tokens the runtime issues (RS256, via jose).

---

Quickstart — govern your first agent action

guard() is the dead-simple path. You describe the action and pass a callback. The callback runs only if the runtime returns ALLOW, and it receives the signed Authority Token. Escalate and deny never run it — fail-closed by design.

import { createIntendedSdk } from "@intended-inc/sdk";

const intended = createIntendedSdk({
  baseUrl: "https://api.intended.so",
  tenantId: "your-tenant",
  apiKey: process.env.INTENDED_API_KEY!,
});

const out = await intended.guard(
  { action: "refund customer $200", actor: "support-triage", domain: "billing" },
  async (decision) => issueRefund(200), // runs ONLY on ALLOW
);

switch (out.status) {
  case "allowed":
    // The runtime approved. `out.result` is whatever your callback returned;
    // `out.decision.token` is the signed Authority Token proving it.
    use(out.result);
    break;
  case "pending_approval":
    // ESCALATE — the action is now in your operator approval queue.
    console.log("awaiting a human:", out.escalationId);
    break;
  case "denied":
    // DENY — blocked. The callback never ran.
    console.log("blocked:", out.reason);
    break;
}

There is no path where a non-approved action runs. ALLOW, and only ALLOW, invokes the callback.

Just want the verdict?

evaluate() is the lower-level companion: it returns the decision without running anything, so you can branch yourself.

const decision = await intended.evaluate({
  action: "delete the production users table",
  actor: "data-agent",
  risk: { touchesProduction: true, containsSensitiveData: true },
});

console.log(decision.verdict);   // "ALLOW" | "ESCALATE" | "DENY"
console.log(decision.riskScore); // 0–100
console.log(decision.rationale); // why the runtime decided this way

---

How the runtime decides

The SDK sends your proposed action to the hosted runtime. Conceptually:

classify → score risk → evaluate policy → ALLOW / ESCALATE / DENY
                                              │
                          on ALLOW → mint a signed Authority Token
                                              │
                                  → append to the audit chain

Every outcome — allow, escalate, or deny — is classified, decided, and written to a tamper-evident audit chain. On ALLOW the runtime mints a short-lived, RS256-signed Authority Token that is cryptographic proof the action was authorized. The decision logic, policy evaluation, and token signing all live in the hosted runtime; this SDK is the client that calls it and the verifier that checks the tokens it returns.

---

Submit vs. simulate intents

For the full intent contract (beyond the guard() convenience wrapper) you can submit an intent for a real authority decision, or simulate one to preview the outcome with no side effects.

// Real decision — runs the full production pipeline.
const result = await intended.submitIntent({
  tenantId: "your-tenant",
  actor: { id: "agent-1", type: "service" },
  targetSystem: "intended-so/intended",
  proposedAction: "ci.workflow.dispatch",
  riskContext: {
    baseRiskScore: 35,
    policyCompliant: true,
    requiresPrivilegedAccess: false,
    touchesProduction: false,
    containsSensitiveData: false,
    github: { owner: "intended-so", repo: "intended", ref: "refs/heads/main" },
  },
});

// Dry run — same classification + policy evaluation, no execution, no token.
const preview = await intended.simulateIntent({ /* SimulateRequest */ });

Request and response shapes are fully typed and validated with zod — the contract schemas ship inside this package.

---

Offline Authority-Token verification

The runtime signs Authority Tokens with RS256. You verify them offline at the point of use — no network round-trip, no shared secret — using the issuer's public key (PEM). Verification checks the signature, the protocol version, the claims, the tenant/adapter binding, and the time window (with optional TTL and clock-skew limits).

const verification = await intended.verifyAuthorityToken({
  token,                       // the JWT from decision.token
  publicKeyPem,                // the runtime's RS256 public key (SPKI PEM)
  expectedKid: "kid-1",        // optional
  expectedTenantId: "your-tenant",
  maxTokenTtlSeconds: 300,     // optional ceiling
  clockSkewSeconds: 60,        // optional
});

if (verification.valid) {
  // verification.claims.decision === "APPROVED"
  proceed(verification.claims);
} else {
  reject(verification.reason); // e.g. TOKEN_EXPIRED, TOKEN_TENANT_MISMATCH
}

This is the one capability that is entirely local: the verification logic and contract schemas are bundled into the package, so an offline consumer can validate a token with only jose and zod present.

---

Evidence streaming

Pull the signed, hash-chained evidence bundle for any intent — the full audit trail behind a decision, with an integrity hash, a signature, and a chain-validity flag.

const evidence = await intended.getEvidenceBundle({ intentId });

console.log(evidence.eventCount, evidence.chainValid);
for (const event of evidence.events) {
  // each audit event in the chain
}

// Or query the raw audit chain directly:
const audit = await intended.getAuditEvents({ correlationId, limit: 100 });

You can also manage escalations (listEscalations, approveEscalation, rejectEscalation) and read or update the per-tenant authority configuration (getAuthorityConfig, updateAuthorityConfig).

---

Physical AI

For embodied and physical agents — robots, drones, autonomous vehicles, industrial control — there is a companion surface that classifies structured goals (ROS 2 actions, OPC-UA method calls, MAVLink commands, …) and mints short-lived, deadline-bounded Authority Tokens for physical actions.

import { createIntendedPhysicalSdk } from "@intended-inc/sdk";

const physical = createIntendedPhysicalSdk({
  apiBaseUrl: "https://api.intended.so",
  apiKey: process.env.INTENDED_API_KEY!,
});

const classification = await physical.classifyStructuredGoal(
  { schema: "ros2:action:nav2_msgs/NavigateToPose", verb: "navigate-to", /* … */ },
  { allowOfflineFallback: true }, // bundled rule-based classifier when offline
);

console.log(classification.oiCode, classification.confidence, classification.safetyBit);

The offline fallback classifier is self-contained (no extra dependencies) and fails closed — goals outside its seed corpus return a least-privilege code. Token issuance for physical actions is a cloud round-trip; local edge verification for the sub-millisecond hot path is handled by a separate verifier, not this SDK.

---

Related projects

• Open Intent taxonomy — the open OI-* code system the runtime classifies into. github.com/intended-so/open-intent · @intended-inc/open-intent
• intendedops — operational tooling for the Intended platform. github.com/intended-so/intendedops

---

API surface

Method	What it does
guard(action, onAllow)	Govern one action; run the callback only on ALLOW.
evaluate(action)	Get the authority verdict without running anything.
submitIntent(intent)	Submit a full intent for a real decision.
simulateIntent(intent)	Dry-run an intent — no execution, no token.
verifyAuthorityToken(input)	Verify a signed Authority Token offline (RS256).
getEvidenceBundle({ intentId })	Pull the signed, hash-chained evidence bundle.
getAuditEvents(query)	Query the tamper-evident audit chain.
listEscalations() / approveEscalation() / rejectEscalation()	Manage the approval queue.
getAuthorityConfig() / updateAuthorityConfig()	Read / set per-tenant thresholds.

The package also exports compileIntent, compileBusinessIntent, Domain LIM pack management, process-map, and runtime-feedback helpers — all fully typed.

License

Apache-2.0 © Intended, Inc.