@autonoma-ai/sdk

Core protocol layer for the Autonoma Environment Factory. Handles HMAC verification, JWT-signed teardown tokens, template resolution, FK graph ordering, and the discover/up/down request lifecycle.

This package is the shared dependency of all ORM and server adapters — you don't need to install it directly unless you're building a custom adapter.

Install

pnpm add @autonoma-ai/sdk

What's exported

handleRequest(config, request)

Main entry point. Routes discover, up, and down actions, verifies HMAC, and delegates to the ORM adapter.

import { handleRequest } from '@autonoma-ai/sdk'

const response = await handleRequest(config, { body, headers })
// { status: 200, body: { ... } }

checkScenario(adapter, scenario)

Dry-run a scenario against a real database — full create-then-teardown cycle. Use this in integration tests to validate scenario data before deploying.

import { checkScenario } from '@autonoma-ai/sdk'

const result = await checkScenario(adapter, {
  create: {
    Organization: [{
      name: 'Test [{{testRunId}}]',
      slug: 'test-{{testRunId}}',
      users: [{ email: 'admin-{{testRunId}}@test.com', name: 'Admin' }],
    }],
  },
})

// result.valid   → true/false
// result.phase   → 'ok' | 'up' | 'down'
// result.errors  → [{ message, fix }]
// result.timing  → { upMs, downMs }

checkAllScenarios(adapter, scenarios)

Runs checkScenario for each scenario definition and returns all results.

Graph utilities (@autonoma-ai/sdk/graph)

Exported from the /graph subpath for use in ORM adapters:

import { topoSort, findDeferrableEdge } from '@autonoma-ai/sdk/graph'

• topoSort(edges) — Kahn's algorithm + Tarjan's SCC for FK-ordered entity creation
• findDeferrableEdge(scc, edges) — finds a nullable FK in a cycle to break it

Other exports

| Export | Use | |--------|-----| | signBody / verifySignature | HMAC-SHA256 signing for request auth | | signRefs / verifyRefs | JWT-like token for signing teardown refs | | resolveTemplate | Resolve {{testRunId}}, {{index}}, {{cycle(...)}}, etc. | | resolveTree | Nested scenario tree → flat entity list with auto-wired FKs | | fingerprint | Deterministic hash of scenario definitions |

CLI

The package ships an autonoma CLI:

# Validate a scenario against a schema
npx autonoma validate <schema.json> <scenario.json>

# Convert Prisma DMMF to autonoma-schema.json
npx autonoma schema convert <dmmf.json> --scope-field <field>

Documentation

Full docs: docs/ — start with overview or read everything in one file.