@avocadostudio-ai/orchestrator-core

The Avocado Studio orchestrator as a library: session state, AI planning, the operations engine, and publishing, behind one Web-standard (Request) => Promise<Response>.

This is the package library mode is built on. If you are integrating a Next.js site you almost certainly want @avocadostudio-ai/site-sdk instead — it re-exports everything below from @avocadostudio-ai/site-sdk/server and adds the Next-specific pieces (draft mode, the page factory, the editor API route). Reach for this package directly only when your host is not Next.

Install

npm install @avocadostudio-ai/orchestrator-core

better-sqlite3 is a real dependency, not optional: session state — draft pages, undo/redo, the version log, chat history — lives in SQLite. Prebuilt binaries ship for linux-x64 (glibc 2.28+), darwin-arm64 and darwin-x64 on Node 22.

Two peers are optional: googleapis and @google/genai. They are reached through await import(...) so a deployment that uses neither need not install them — but a bundler resolves dynamic imports statically and will fail the build over a package that is deliberately absent. Mark them external. On Next, withAvocado from @avocadostudio-ai/site-sdk/next-config does it for you.

Mount it

import { createOrchestrator } from "@avocadostudio-ai/orchestrator-core"

const handler = createOrchestrator({
  basePath: "/api/avocado",
  adapter: myAdapter,
  auth: async (request) => Boolean(await getSession(request)),
})

// Any host that speaks Request/Response
export { handler as GET, handler as POST, handler as OPTIONS }

createOrchestrator gates every route. With neither an auth hook nor a credential (ACCESS_PASSWORD_HASH or ORCHESTRATOR_ACCESS_TOKEN) it refuses all requests under NODE_ENV=production rather than serving your content openly. Only /auth/status and /auth/verify are public.

The adapter

adapter is your content store. SQLite is the working copy; the adapter is the source of truth, read on a cold session and written on publish.

import type { CmsAdapter } from "@avocadostudio-ai/orchestrator-core/cms"

const myAdapter: CmsAdapter = {
  id: "my-cms",
  perspectives: true,                       // does getPages honour options.perspective?
  getPages: (options) => fetchPages(options),
  onPublish: (pages, config, context) => writeBack(pages, context?.published),
  capabilities: { createPage: false },      // static — /whoami answers it offline
}

jsonFileAdapter and editorApiAdapter are bundled from the same subpath. The full contract — including why perspectives defaults to no while capabilities default to yes, and why onPublish has to diff rather than overwrite — is documented in the site-sdk README.

What it does not do

It serves the API. It does not serve the editor UI — that is @avocadostudio-ai/cli or your own deployment of the Studio — and it does not render your pages.

/health is not a route, so a client that probes it to check compatibility gets a 405. The body lists every route that does exist.

Persistence

| variable | meaning | |---|---| | ORCHESTRATOR_DB_FILE | Path to the SQLite file. Empty for the default; :memory: to force ephemeral. Auto-:memory: under NODE_ENV=test | | ORCHESTRATOR_DB_BACKUP_INTERVAL_HOURS | Periodic VACUUM INTO snapshot interval (default 24) | | ORCHESTRATOR_DB_BACKUP_LIMIT | Rolling snapshots to keep (default 14) |

Undo/redo is capped at 50 entries per slug per direction, the version log at 100, recent edits at 10, chat history at 6 messages.

Providers

At least one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GOOGLE_GENAI_API_KEY is required for planning. Keys never leave the process that holds them.

License

Apache-2.0