@openagentry/core

Public TypeScript SDK for OpenAgentry. Defines adapter interfaces, plugin protocol, and runtime helpers — imported by every official scaffold and adapter.

Zero vendor coupling. Vendor implementations live in @openagentry/adapter-* packages.

Install

npm install @openagentry/core
# or
pnpm add @openagentry/core

Use

import {
  AgentryError,
  registerAdapter,
  useAdapter,
  type HostAdapter,
} from '@openagentry/core';

// At app startup the runtime registers configured adapters
registerAdapter('host', cloudflareHostAdapter);

// Scaffold code uses the resolver — never imports a specific adapter
const host = useAdapter<HostAdapter>('host');
await host.deploy(project, 'prod');

Adapter categories

Shipped (interfaces in src/adapters/<category>.ts): host, db, auth, email, llm, storage, domain, repo, wiki.

Reserved (valid manifest values; interfaces land in later releases): kv (filled by host adapter where bundled), cron (filled by host adapter), billing, push.

Plugin manifest

Plugins declare an openagentry block in their package.json:

{
  "openagentry": {
    "type": "adapter",
    "category": "host",
    "id": "host-cloudflare",
    "protocolVersion": "1",
    "envVars": [
      { "name": "CLOUDFLARE_API_TOKEN", "secret": true, "required": true }
    ],
    "fillsSlots": ["host", "kv", "storage"],
    "capabilities": { "deploy": true, "rollback": true, "cron": true },
    "aiFriendly": {
      "structuredErrors": true,
      "dryRun": true,
      "idempotent": ["deploy", "setEnv", "attachDomain"],
      "queryableState": true
    },
    "llmDocs": "./LLM.md"
  }
}

Validate with validateManifest(json) — throws AgentryError on bad input.

Errors

Every adapter operation throws AgentryError on failure. AI-friendly: errors carry code, phase, suggestedFix, docs, and context so an agent can recover without asking the user.

License

Apache-2.0