anbaric 1.20.1 → 1.21.0

package/README.md

@@ -24,6 +24,13 @@ Run locally as usual (`npm run start`) or deploy to the Anbaric Cloud (`anbaric
 
 Anbaric is open source and you can self-host the platform or sign up at https://cloud.anbaric.ai to use the hosted version.
 
+## Documentation
+
+A full user guide — split into **features**, **patterns** and **API reference**
+(TypeScript and web) — lives in [`anbaric/docs`](anbaric/docs/README.md). Start
+with [Core concepts](anbaric/docs/features/core-concepts.md), then the
+[Build your first app](anbaric/docs/patterns/first-app.md) walkthrough.
+
 ## What the code looks like
 
 Anbaric has a collection of features that can be used in your application. Here are some examples:
@@ -163,8 +170,11 @@ const rows = await sql.query(actor, "SELECT id, body FROM notes");
 ### Serve a web UI
 
 An app can serve its own HTTP frontend. Listen on `process.env.PORT` and the
-platform's app proxy routes `<platform>/<app-name>/*` to it — combine it with
-the persistence and state-machine APIs above to put your data on a page.
+platform's app proxy serves it at `<platform>/app/<name>/*`, stripping the
+`/app/<name>` prefix before the request reaches your app — combine it with the
+persistence and state-machine APIs above to put your data on a page. See
+[Web APIs](anbaric/docs/api/web.md) for the full proxy contract (forwarded
+headers, the absolute-URL caveat).
 
 ```ts
 import {createServer} from "node:http";
@@ -263,14 +273,14 @@ to the platform automatically. The same applies to `JsonStoreFactory`
 `SqlStoreFactory` (a relational store) from `anbaric-data-store`.
 
 The SQL store is backed by SQLite locally (in-memory by default) and, once
-deployed, by the tenant's PostgreSQL in a dedicated `anbaric_app_data` schema
-shared by all of the tenant's apps. Write portable SQL where you can — the two
+deployed, by the tenant's PostgreSQL in a schema named after your app — its own,
+isolated from every other app in the tenant. Write portable SQL where you can — the two
 differ in a few places, notably parameter placeholders (`?` for SQLite, `$1`
 for PostgreSQL); see the [`anbaric-data-store`](anbaric-data-store/README.md)
 docs for the full list.
 
 If your app serves HTTP, listen on `process.env.PORT` and users reach it at
-`<platform>/<app-name>`. All front-end must be React and use the Anbaric
+`<platform>/app/<name>`. All front-end must be React and use the Anbaric
 design system (`anbaric-design-system`) — see the living style guide by
 opening `anbaric-design-system/dist/index.html`.
 

package/docs/README.md

@@ -0,0 +1,59 @@
+# Anbaric user guide
+
+Everything you need to build a real application on Anbaric — from your first
+state machine to a deployed app with a human-in-the-loop workflow, a database, a
+web UI and an audit trail.
+
+Anbaric models an application as one or more **state machines**: long-lived
+**jobs** move through named **states**, driven by **actions** and **transitions**,
+with their data validated against a schema and every change recorded. The same
+code runs in-memory on your laptop and platform-backed once deployed — you never
+write deployment details into your app.
+
+New here? Read [Core concepts](features/core-concepts.md), then work through the
+[Build your first app](patterns/first-app.md) walkthrough.
+
+## Features
+
+What the framework gives you, one capability at a time.
+
+- [Core concepts](features/core-concepts.md) — jobs, states, actions, transitions, actors
+- [State machines](features/state-machines.md) — defining and running a workflow
+- [Actions and actors](features/actions-and-actors.md) — who does the work, and how
+- [Awaiting input](features/awaiting-input.md) — pausing a job for a human or external system
+- [AI agents](features/ai-agents.md) — letting a model drive a state
+- [Documents and secrets](features/documents-and-secrets.md) — the JSON and secret stores
+- [The SQL store](features/sql-store.md) — a relational database for structured data
+- [Auditing](features/auditing.md) — the record of who changed what
+- [Serving a web UI](features/serving-a-web-ui.md) — putting your data on a page
+- [The admin console and widgets](features/admin-console-and-widgets.md) — dashboards and plugins
+- [Deploying](features/deploying.md) — from laptop to Anbaric Cloud
+
+## Patterns
+
+How to put the features together to build something real.
+
+- [Build your first app](patterns/first-app.md) — an end-to-end walkthrough
+- [Structuring an application](patterns/app-structure.md) — files, entry point, wiring
+- [Modelling a workflow](patterns/modelling-workflows.md) — turning a process into states
+- [Human-in-the-loop](patterns/human-in-the-loop.md) — approvals, forms and hand-offs
+- [Integrating external systems](patterns/integrating-external-systems.md) — waiting on callbacks and webhooks
+- [Authorization with actors and roles](patterns/authorization.md) — who is allowed to do what
+- [Testing your app](patterns/testing.md) — driving a machine in memory
+
+## API reference
+
+The surface you build against.
+
+- [TypeScript API](api/typescript.md) — the full app-facing library
+  - [State machines](api/state-machine.md) — `StateMachine`, `State`, `Action`, `Await`, `Transition`, `Job`, `PropertyDefinition`
+  - [Actors and agents](api/actors-and-agents.md) — `Code`, `Human`, `Agent`, AI actions
+  - [Stores](api/stores.md) — `JsonStore`, `SecretStore`, `SqlStore` and their factories
+  - [Environment and factories](api/environment.md) — the `ANBARIC_*` variables
+- [Web APIs](api/web.md) — serving HTTP, the app proxy, and the platform endpoints you call
+- [CLI reference](api/cli.md) — the `anbaric` command
+
+---
+
+Everything in this guide is app-author-facing: the public library, the CLI and
+the web surface. You never need to know how the platform is built to build on it.

package/docs/api/actors-and-agents.md

@@ -0,0 +1,164 @@
+# API — Actors and agents
+
+Who performs work, and how AI models plug in. Import from `anbaric`.
+
+```ts
+import {Code, Human, SystemActor, Agent, OpenAIAgent, RemoteLLMAgenticAction} from "anbaric";
+import type {Actor, ActorType} from "anbaric";
+```
+
+---
+
+## Actors
+
+Every actor is `{ type, id, roles }`. Concrete actor constructors accept a single
+role string **or** an array; a bare string is normalised to a one-element array.
+
+### `Code`
+
+Automated work that runs as jobs are processed.
+
+```ts
+class Code implements Actor
+// type = "CODE"
+constructor(id : string, roles : Array<string> | string = "code")
+```
+
+```ts
+new Code("billing");                 // roles: ["code"]
+new Code("billing", "payments");     // roles: ["payments"]
+```
+
+### `Human`
+
+Work performed by a person.
+
+```ts
+class Human implements Actor
+// type = "HUMAN"
+constructor(id : string, roles : Array<string> | string)     // roles required
+
+static async fromSession(
+    source : string | IncomingMessage,
+    resolver? : SessionResolver,
+) : Promise<Human>
+```
+
+`fromSession` accepts either the `anbaric_session` **token string** or a Node
+`IncomingMessage` (it reads the cookie). It resolves the session against the
+platform and returns a `Human` with the resolved id and roles, or throws
+`Could not resolve the session` if the token is missing/invalid/expired. See
+[Web APIs](web.md#sessions) for the endpoint it uses.
+
+```ts
+new Human("ada", "admin");
+new Human("ada", ["admin", "finance"]);
+const user = await Human.fromSession(request);
+```
+
+### `SystemActor`
+
+The framework itself. Use the shared singleton.
+
+```ts
+class SystemActor implements Actor    // type = "SYSTEM", id = "_SYSTEM", roles = ["_SYSTEM"]
+static actor : SystemActor
+```
+
+```ts
+SystemActor.actor
+```
+
+---
+
+## Agents and AI
+
+### `Agent`
+
+Pure identity plus an injected client that calls a model. The `Agent` itself
+holds no model logic.
+
+```ts
+class Agent implements Actor
+// type = "AGENT"
+constructor(id : string, roles : Array<string> | string, client : Agent.Client)
+
+// The client contract:
+namespace Agent {
+    abstract class Client {
+        abstract generate(request : AgentRequest) : Promise<Record<string, any>>
+    }
+}
+```
+
+Supporting types:
+
+```ts
+type AgentMessage = { role : "system" | "user" | "assistant", content : string }
+type AgentRequest = { messages : Array<AgentMessage>, outputSchema : object }
+```
+
+Implement `Agent.Client` to target any model provider, then
+`new Agent("id", "role", myClient)`.
+
+### `RemoteLLMAgenticAction`
+
+An `Action` that asks an agent to generate structured properties from a prompt
+and applies them to the job. The job's current properties are appended to the
+prompt automatically.
+
+```ts
+class RemoteLLMAgenticAction extends Action
+constructor(
+    name : string,
+    agent : Agent,
+    messages : Array<AgentMessage>,   // the prompt
+    outputSchema : object,            // JSON Schema for the properties to return
+    description? : string,
+    id? : string,
+)
+```
+
+```ts
+const triage = new RemoteLLMAgenticAction(
+    "Triage the ticket",
+    triager,
+    [{ role: "system", content: "Decide the priority from the subject." }],
+    { type: "object", properties: { priority: { type: "string", enum: ["low", "high"] } } },
+);
+```
+
+### `OpenAIAgent`
+
+An `Agent` backed by an OpenAI-compatible chat-completions endpoint (uses strict
+JSON-schema structured output).
+
+```ts
+class OpenAIAgent extends Agent
+constructor(id : string, role : string, connection : OpenAIConnection, fetchFn? : FetchFn)
+
+type OpenAIConnection = {
+    apiKey : string,
+    model : string,
+    baseUrl? : string,        // default "https://api.openai.com/v1"
+    organization? : string,
+}
+```
+
+```ts
+const triager = new OpenAIAgent("triager", "support", {
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-5.4-mini",
+});
+```
+
+The optional `fetchFn` lets you inject a custom fetch (useful in tests). Requests
+that fail throw `The OpenAI request failed with status <n>`.
+
+---
+
+### See also
+
+- [Actions and actors](../features/actions-and-actors.md) — the concepts
+- [AI agents](../features/ai-agents.md) — a worked example
+- [State machines API](state-machine.md) — `Action`, `Actor`

package/docs/api/cli.md

@@ -0,0 +1,74 @@
+# API — CLI reference
+
+The `anbaric` command authorizes your terminal against a platform, deploys apps,
+and inspects and drives their jobs. Install it globally:
+
+```bash
+npm install -g anbaric-cli
+```
+
+After a one-time `anbaric login`, the `app` commands run from anywhere inside a
+project — they walk up to the nearest `package.json`.
+
+## Authentication
+
+| Command | Purpose |
+| --- | --- |
+| `anbaric login` | Choose a platform and authorize this terminal (browser flow; keypair saved to `~/.anbaric/`). |
+| `anbaric logout` | Revoke this terminal's key on the platform and delete the local keypair. |
+
+## Apps
+
+| Command | Purpose |
+| --- | --- |
+| `anbaric apps` | List deployed apps (name, status, port). |
+| `anbaric app configure` | Create or update `.anbaric/app-config.json` (`name`, `internalPort`). |
+| `anbaric app deploy` | Deploy the app and wait until it is live (prompts before replacing a running one). |
+| `anbaric app update` | Deploy, replacing a running app **without** prompting. |
+| `anbaric app status <name>` | Show deploy state, liveness, and recent logs. |
+| `anbaric app tail <name>` | Stream the app's runtime logs. |
+| `anbaric app tear-down <name>` | Stop and remove the app (prompts unless `--yes`). |
+
+## State machines and jobs
+
+| Command | Purpose |
+| --- | --- |
+| `anbaric state-machines` | List registered state machines. |
+| `anbaric jobs create <sm-id> <start-state> [k=v …]` | Create a job and queue it for processing. |
+| `anbaric jobs list [state-machine-id]` | List jobs, optionally filtered by workflow. |
+| `anbaric jobs stats` | Job counts per state and the queue size. |
+| `anbaric jobs watch <job-id>` | Follow a job's state and property changes live. |
+| `anbaric jobs set-state <job-id> <state>` | Move a job to a state and re-queue it. |
+| `anbaric jobs update <job-id> <k=v …>` | Update job properties and re-queue. |
+| `anbaric jobs kill <job-id>` | Kill a job so it stops progressing. |
+| `anbaric jobs kill-old <age>` | Kill jobs not updated within `<age>` (e.g. `24h`, `7d`; units `s`/`m`/`h`/`d`/`w`). Prompts unless `--yes`. |
+
+## Flags
+
+Every command accepts these; they supply the answers a prompt would otherwise
+ask for, so the CLI runs unattended in scripts and CI.
+
+| Flag | Applies to | Notes |
+| --- | --- | --- |
+| `--platform-url <url>` | all | The platform to talk to. Falls back to `ANBARIC_CLOUD_URL`, stored config, then `http://localhost:8787`. |
+| `--environment <local\|staging\|production>` | all + `login` | Shorthand for a platform URL (`local` → localhost:8787). |
+| `--tenant <tenant>` | all | Target tenant. Falls back to `ANBARIC_TENANT`, then stored config. |
+| `--name <name>` | `app configure`/`deploy`/`update` | App name; prompts if omitted (suggested from `package.json`). |
+| `--port <port>` | `app configure`/`deploy`/`update` | Internal port (1–65535); prompts if omitted. |
+| `--yes` | `app deploy`, `app tear-down`, `jobs kill-old` | Skip confirmation. (`app update` implies it.) |
+| `--help`, `-h` | all | Print usage. |
+
+## Configuration and storage
+
+The CLI stores config under `~/.anbaric` (override with `ANBARIC_CONFIG_DIR`):
+`config.json` holds the platform URL and tenant; `key.json` (mode `0600`) holds
+your authorized keypair. Manage your keys in the browser at
+`<platform>/manage-keys`.
+
+The CLI also reads `ANBARIC_CLOUD_URL` and `ANBARIC_TENANT` from the environment
+as defaults.
+
+## See also
+
+- [Deploying](../features/deploying.md)
+- [Build your first app](../patterns/first-app.md)

package/docs/api/environment.md

@@ -0,0 +1,81 @@
+# API — Environment and factories
+
+Anbaric never hard-wires a backend. Persistence, queueing, stores and auditing
+come from **factories** that read `ANBARIC_*` environment variables. With none
+set, everything is in-memory and the app runs in one process; the platform sets
+them to `cloud` when your app is deployed.
+
+> **Don't set the factory `*_TYPE` variables yourself.** The platform injects
+> them so the same code runs locally and deployed. Setting them by hand breaks
+> that guarantee.
+
+## The golden rule
+
+```ts
+// This is all your code does — the factory decides the implementation:
+const machine = new StateMachine("onboarding", states);
+const sql = SqlStoreFactory.instance();
+```
+
+Locally: in-memory persistence, queue and stores; console auditing.
+Deployed: the same calls talk to the platform.
+
+## Factory variables
+
+Each factory switches on a `*_TYPE` variable (typically `cloud` when deployed,
+defaulting to a local implementation otherwise).
+
+| Variable | Selects | Local default |
+| --- | --- | --- |
+| `ANBARIC_JOB_PERSISTENCE_TYPE` | where jobs are stored | in-memory |
+| `ANBARIC_QUEUE_TYPE` | the job queue | in-memory |
+| `ANBARIC_AUDITOR_TYPE` | the audit sink (`cloud` → platform) | console |
+| `ANBARIC_JSON_STORE_TYPE` | the JSON document store | in-memory |
+| `ANBARIC_SECRET_STORE_TYPE` | the secret store | in-memory (encrypted) |
+| `ANBARIC_SQL_STORE_TYPE` | the SQL store (`sqlite` / `cloud`\|`postgres`) | SQLite |
+| `ANBARIC_SESSION_RESOLVER_TYPE` | how `Human.fromSession` resolves sessions | in-memory |
+
+## Store configuration
+
+Used by the store implementations the factories return:
+
+| Variable | Used by | Meaning |
+| --- | --- | --- |
+| `ANBARIC_SQL_FILE` | SQLite | file path to persist to (default `:memory:`) |
+| `ANBARIC_SQL_DATABASE_URL` | PostgreSQL | connection string |
+
+Deployed, the PostgreSQL schema defaults to your **app's name** (each app gets
+its own, isolated schema); pass a schema to the store constructor to override.
+
+## Platform-injected variables
+
+When your app is deployed, the platform also sets these — informational; **don't
+set or depend on their exact values**:
+
+| Variable | Meaning |
+| --- | --- |
+| `PORT` | the port your app should listen on |
+| `ANBARIC_APP_ID` | your app's name; scopes your workflows, documents, secrets and SQL schema |
+| `ANBARIC_CLOUD_URL` | the platform endpoint the cloud clients call |
+| `ANBARIC_ADMIN_PORT` | the built-in admin/liveness port |
+| `ANBARIC_CONSUMER_PORT` / `ANBARIC_CONSUMER_URL` | job-consumer wiring |
+
+## Local development
+
+With no variables set you get the full in-memory stack — no database, no
+platform. Run your entry file directly with `tsx`:
+
+```bash
+npx tsx src/main.ts
+```
+
+To persist SQL data across local runs, set a file:
+
+```bash
+ANBARIC_SQL_FILE=./dev.db npx tsx src/main.ts
+```
+
+## See also
+
+- [Stores](stores.md) — the store APIs and their variables
+- [Deploying](../features/deploying.md) — what the platform injects