@autonoma-ai/sdk

Core protocol layer for the Autonoma Environment Factory. Handles HMAC verification, JWT-signed teardown tokens, dependency ordering from _alias/_ref graphs, and the discover/up/down request lifecycle.

This package is the shared dependency of all 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 registered factories.

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

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

defineFactory({ inputSchema, create, teardown?, refSchema? })

Defines a factory for a model. inputSchema is a Zod schema that the SDK uses to derive the discover response — no database introspection needed.

import { defineFactory } from '@autonoma-ai/sdk'
import { z } from 'zod'

const Organization = defineFactory({
  inputSchema: z.object({ name: z.string(), slug: z.string() }),
  create: async (data, ctx) => {
    const org = await db.organization.create({ data })
    return { id: org.id, ...data }
  },
  teardown: async (record, ctx) => {
    await db.organization.delete({ where: { id: record.id } })
  },
})

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 Org',
      slug: 'test-org',
      _alias: 'org1',
    }],
  },
})

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

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

Exported from the /graph subpath:

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

• topoSort(edges) — Kahn's algorithm + Tarjan's SCC for dependency ordering
• 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 | | fingerprint | Deterministic hash of scenario definitions |

Documentation

Full docs ship inside this package under docs/ so a coding agent reads the version-matched API. Start with docs/implement.md; AGENTS.md is the agent pointer.