@abloatai/ablo 0.34.1 → 0.35.0

package/llms.txt

@@ -1,11 +1,24 @@
 # Ablo
 
-Ablo is the state coordination layer for apps where humans and agents edit the same data.
+Ablo is the agentic coordination layer: one API for AI agents, apps, and services to claim, change, and confirm the same rows.
 
-Here is the problem it solves. Two writers touch `report_stockholm` at once. The agent claims the row, does slow work (an LLM call, a fetch), and commits; the human's UI sees the claim live and never clobbers it. Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
+Here is the problem it solves. Two agents reach for `report_stockholm` at once. One claims the row, does slow work (an LLM call, a fetch, a chain of tools), and commits. The second is neither rejected nor allowed to clobber: it waits in line, is handed the row as it now stands, and proceeds. Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so writers serialize instead of colliding. A person editing that row is simply another holder; the agent waits behind them the same way.
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
+## Surfaces — pick by who is calling
+
+Every surface reaches the same coordinated state. They are not interchangeable.
+
+- SDK, `@abloatai/ablo` with `transport: 'http'` — THE AGENTS THEMSELVES. Stateless, request/response, nothing held open; the credential is the identity. This is the main path — default to it.
+- Coordination MCP, `@abloatai/mcp` — an agent living inside an MCP host (Claude, Cursor). Two jobs: MANAGING your Ablo the way the CLI does (`get_schema`, `list_projects`, `create_project`, `tail_logs`, `get_usage`), and claim/commit as tools over your rows. Call `get_schema` first — it is the only way to learn the model names every data tool needs. `init`, `push`, `pull`, `generate` have no tools (they touch your repo); run those in a shell.
+- `humans()` with `@abloatai/ablo/react` — the interfaces a person watches agent work arrive in. The bare client is the coordination layer (commit, read, observe, claim); `humans()` is the PLUGIN that adds the local watchable copy, live queries, and presence. It `requires: { duplex: true }`, so a `transport: 'http'` agent is rejected at construction rather than left holding a subscription that never delivers. It is installed by default on a socket client with no `plugins` list. There is no `agents()` plugin — agents are the default caller, not a special one. A browser NEVER receives the secret key; mint a session token.
+- CLI, `ablo` — scaffolding, schema push, connecting a database. Terminals and CI. Agents must run it non-interactively (see the CLI section below).
+- REST, `/api/v1` — runtimes with no SDK.
+- Integration-helper MCP, hosted `/api/mcp` — teaching a coding assistant the SDK WHILE BUILDING an integration. Docs, schema lint, and scaffolds only; it has NO per-model data tools and cannot touch application rows.
+
+The two MCP servers do different jobs and are the most common mix-up: to change application rows use the SDK or the COORDINATION server; the integration-helper server cannot do it at all. Do not hand-roll HTTP against `/api/v1` when a typed SDK exists for the runtime you are in.
+
 ## Start here
 
 First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the `Ablo({ schema, apiKey })` client, and (for Next.js) the browser provider + session route. All on the current API. Edit the generated files rather than hand-writing from this doc. Connecting a database is a SEPARATE step with one path — logical replication via `npx ablo connect` (see Storage Boundary); the signed Data Source endpoint is the fallback when database credentials must stay inside the app.
@@ -24,7 +37,7 @@ Each app gets its own PROJECT inside the org — its own schema, its own sandbox
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
-TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
+TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'); the two-parameter `Model<typeof schema,'tasks'>` form is only for projects carrying multiple schemas. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
 
 
 const schema = defineSchema({
@@ -62,10 +75,12 @@ the same model API across your own Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
 Reads come in two flavors, and you pick by whether you can wait. `retrieve({ id })`
-(one row) and `list({ where })` (many) are async — they hit the server and return
-a Promise, so await them. `get(id)`, `getAll({ where })`, and `getCount({ where })`
-are synchronous — they read the local graph and are reactive in render, so no
-await. The query reads accept `where`, `filter`, `orderBy`, `limit`, `offset`,
+(one row) and `list({ where })` (many) are async — they answer from the local
+graph and fall back to the server, so await them. `local.retrieve(id)`,
+`local.list({ where })`, and `local.count({ where })` are the same reads narrowed
+to what has already synced: nothing to await, reactive in render. There is no
+second verb to learn — `local.` is the only difference. The query reads accept
+`where`, `filter`, `orderBy`, `limit`, `offset`,
 and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
 retired rows.
 
@@ -73,10 +88,10 @@ Workers import the same app schema and select `transport: 'http'`. The transport
 changes; the typed `ablo.<model>` contract does not. There is no public
 schema-less or string-keyed model client.
 
-React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.get(id))` (synchronous local read, reactive in render).
+React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.local.retrieve(id))` (synchronous local read, reactive in render).
 Use zero-argument `useAblo()` only when a component needs the client for an
-event handler or effect. The older string-keyed hooks (`useQuery`, `useOne`,
-`useReader`, and `useMutate`) are removed; do not import or recommend them.
+event handler or effect. The selector form above is the complete reactive
+surface — every read goes through it.
 
 ## Multiplayer
 
@@ -90,7 +105,7 @@ coordination until the app reports it through Data Source events.
 
 ## Change propagation
 
-A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a layer routes to `layer:` + `slide:` + `deck:`), so everyone watching the deck sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles. `reads` guards ONE commit; for a long-running actor that reads now and writes much later, register a DURABLE premise with `track`: `ablo.<model>.track({ id })` for a row, or the `track:` write option (`track: [{ group: 'deck:abc' }]`) alongside a write. A track persists server-side; the next time you commit anything, a change that landed on the tracked target rides back on your receipt's `notifications` (same `StaleNotification` shape as `onStale: 'notify'`). It is an idempotent registration, re-baselines so a change fires once, and never notifies you of your own writes. Delivery is on your next commit — a track does not yet push out of band between commits.
+A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a block routes to `block:` + `document:` + `workspace:`), so everyone watching the workspace sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'workspace:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles. `reads` guards ONE commit; for a long-running actor that reads now and writes much later, register a DURABLE premise with `track`: `ablo.<model>.track({ id })` for a row, or the `track:` write option (`track: [{ group: 'workspace:abc' }]`) alongside a write. A track persists server-side; the next time you commit anything, a change that landed on the tracked target rides back on your receipt's `notifications` (same `StaleNotification` shape as `onStale: 'notify'`). It is an idempotent registration, re-baselines so a change fires once, and never notifies you of your own writes. Delivery is on your next commit — a track does not yet push out of band between commits.
 
 ## Nouns
 
@@ -107,6 +122,13 @@ even while it is claimed. Pass `ifClaimed: 'fail'` to throw
 `AbloClaimedError`, and inspect active coordination separately through
 `ablo.<model>.claim.state({ id })`.
 
+A claim carries app metadata verbatim in `target.meta`. Declare its shape in the
+SAME register block as the schema — `interface Register { Schema: typeof schema;
+ClaimMeta: { blocks: string[] } }` — and it types both what you write
+(`claim({ id, meta })`) and every read (`claim.state`, `claim.queue`, the held
+claim), so no read needs a `typeof` guard. The per-call `claim.state<M>({ id })`
+still works and is for a program carrying more than one metadata shape.
+
 Reads never block on a claim. To wait for a row to free up, `claim({ id })` it —
 the claim queues fairly behind the current holder and is granted when the row
 frees. Use `ifClaimed: 'fail'` when you'd rather refuse to read a claimed row.
@@ -133,7 +155,7 @@ RLS GOVERNS ABLO'S WRITES. The writer role is `NOSUPERUSER NOBYPASSRLS`, and bef
 
 FALLBACK (only when Ablo can't dial the database, e.g. a private VPC with no inbound route): a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle default; Prisma and Kysely supported) — Ablo writes and confirms through it, and it owns the transaction, exactly-once idempotency, and outbox in ONE pass; your credentials never leave your infrastructure.
 
-DEPRECATED — removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the old DIAL-IN, where the CLIENT held a read/write connection string and committed directly, bypassing Ablo's coordination). It is deleted. DO NOT confuse it with the current model: today's writes also land in your Postgres, but through Ablo's SERVER-SIDE commit chokepoint and a scoped writer role Ablo provisions — coordination is never bypassed, and no connection string lives in your app. The NON-superuser / NON-BYPASSRLS role rule is NOT retired — it now applies to the scoped writer role `ablo connect` provisions (see RLS above), because Ablo does hold a scoped connection to write your rows. The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`. `ablo init` may still scaffold legacy `--storage direct`/`databaseUrl` for old projects and the CLI warns on it; prefer `ablo connect`.
+The constructor is `Ablo({ schema, apiKey })` — the app holds an API key and nothing else; no connection string ever lives in the app. The database is connected out of band with `ablo connect`: writes land in your Postgres through Ablo's server-side commit path using the scoped writer role `ablo connect` creates, and that role is always NON-superuser / NON-BYPASSRLS (see RLS above).
 
 ```ts
 // app/api/ablo/source/route.ts
@@ -151,7 +173,7 @@ export const { POST } = dataSourceNext({
 });
 ```
 
-Connect a database with `npx ablo connect` (logical replication — the one path above). The signed Data Source endpoint (code above) is the fallback when app database credentials must stay private; scaffold it with `npx ablo init --storage endpoint` — Ablo only calls the endpoint. (`--storage direct` still exists for existing dial-in projects but is deprecated; the CLI warns on it.)
+Connect a database with `npx ablo connect` (logical replication — the one path above). The signed Data Source endpoint (code above) is the fallback when app database credentials must stay private; scaffold it with `npx ablo init --storage endpoint` — Ablo only calls the endpoint.
 
 ## Sandboxes
 
@@ -163,7 +185,7 @@ when an agent is asked to "make Ablo work" in an existing app.
 Authenticated org sandboxes are real test environments. Treat the default
 sandbox like Stripe test mode: it has an isolated sync group prefix and mints
 `sk_test_*` keys. The sandbox CAN host rows in Ablo's test plane, so you can try
-Ablo with NO database — `apiKey` only, no `databaseUrl`. (In production, your own
+Ablo with NO database — `apiKey` only, nothing else. (In production, your own
 Postgres is the system of record.) Extra sandboxes can start blank or copy live
 configuration. Resetting a sandbox creates a clean future stream without
 touching live data. Use `sk_live_*` only for production.
@@ -173,6 +195,12 @@ declare schema, create the Ablo client, replace one direct mutation with a typed
 `ablo.<model>.update(...)`, use selector `useAblo` for live reads, and add a
 two-writer stale/claim smoke test.
 
+## Production
+
+A PLANE is what a credential acts on: `production` is the root, sandboxes sit beside it. Rows, the registered database, and the active schema artifact are all PER PLANE, and a key's plane is fixed at mint by its prefix (`sk_live_` → production, `sk_test_` → sandbox) — there is no runtime override, which is why app code never passes an environment. ONE ASYMMETRY: a sandbox with no schema artifact of its own READS PRODUCTION'S, so a production push reaches sandboxes; a SANDBOX push does NOT reach production — it creates a sandbox artifact that shadows production for that sandbox's readers only. Production gets models when you push to production.
+
+Going live is three things, each done with a `sk_live_` key: register the production database (`ablo connect apply` — the DIRECT host, never a pooler; a pooler refuses in the words of a wrong password), push the schema AHEAD of the code that needs it, and hold the right credential per runtime (server/serverless `sk_live_`; browser `pk_live_` read-only or an `authEndpoint` minting `ek_`). The live key `ablo login` stores is a RESTRICTED observe-only `rk_live_` and CANNOT push schema — a production push needs a dashboard `sk_live_` in `ABLO_API_KEY`. Gate a deploy on `npx ablo status --json` having an EMPTY `blockers` array; each blocker carries a `problem` and the one `fix`. Your agents do NOT each hold a database connection — they talk to Ablo, and Ablo holds at most 4 connections per plane (`application_name = 'ablo-direct-writer'`) however many callers write behind them, so size the database for that number and not for your agent count. Read `deployment` for the full path.
+
 ## Public Surface
 
 Import from these public paths only:
@@ -193,10 +221,12 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 
-- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint; `--storage direct` (deprecated, CLI warns) wires the legacy `databaseUrl`.
+- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage replication|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage replication` (the default) pairs with `ablo connect`; `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint.
 - `npx ablo connect` connects your database via logical replication — the read path (prints the `wal_level=logical` + publication + `REPLICATION`-role SQL); `npx ablo connect register` registers it, `npx ablo connect check` validates the registered database from Ablo's own side and needs only `ABLO_API_KEY` (no database credential in your environment). `npx ablo connect apply` does the whole setup from a one-time admin connection and leaves your app holding only `ABLO_API_KEY`.
 - Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo push` writes `.env.local`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
-- `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`; `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+- `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`. A PRODUCTION push (`sk_live_` key) needs `--yes`: with no TTY it REFUSES rather than deploying unattended, and interactively it demands the destination project typed by name. Destructive steps (dropped model/field, narrowed enum, lossy cast) need `--force`; a new required field on a populated table needs `--backfill model.field=value`. `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+
+- `npx ablo docs` lists every documentation page; `npx ablo docs <page>` prints one as markdown. These pages ship INSIDE the installed package, so they describe the version in `node_modules` and need no network. Prefer them over a docs URL whenever the project pins a version: a website always describes the newest release, so on an older pin it will hand you a call your package does not have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0). One-shot, safe to run unattended.
 
-Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it.
+Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `deployment`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent` — read each with `npx ablo docs <page>`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it. When the customer's database has row-level-security policies, read `session-settings` — the identity context Ablo sets before every write, and how to map it to the setting names those policies already read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -48,11 +48,6 @@
       "import": "./dist/batching/index.js",
       "default": "./dist/batching/index.js"
     },
-    "./agent": {
-      "types": "./dist/agent/index.d.ts",
-      "import": "./dist/agent/index.js",
-      "default": "./dist/agent/index.js"
-    },
     "./ai-sdk": {
       "types": "./dist/ai-sdk/index.d.ts",
       "import": "./dist/ai-sdk/index.js",
@@ -112,6 +107,11 @@
       "types": "./dist/webhooks/index.d.ts",
       "import": "./dist/webhooks/index.js",
       "default": "./dist/webhooks/index.js"
+    },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "import": "./dist/docs/index.js",
+      "default": "./dist/docs/index.js"
     }
   },
   "files": [
@@ -119,7 +119,6 @@
     "!dist/__type_probe.*",
     "docs/*.md",
     "docs/examples/*.md",
-    "docs/mcp/*.md",
     "examples",
     "AGENTS.md",
     "llms.txt",
@@ -132,7 +131,10 @@
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && npm run build:cli",
     "build:cli": "tsup --config tsup.cli.config.ts",
+    "typecheck": "npm run typecheck:src && npm run typecheck:cli && npm run typecheck:scripts",
+    "typecheck:src": "tsc -p tsconfig.json",
     "typecheck:cli": "tsc -p tsconfig.cli.json",
+    "typecheck:scripts": "tsc -p tsconfig.scripts.json",
     "prepack": "node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
@@ -207,7 +209,7 @@
     "mobx": "^6.13.7",
     "mobx-react-lite": "^4.0.0",
     "uuid": "^11.1.0",
-    "zod": "^4.1.11"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",

package/dist/agent/Agent.d.ts

@@ -1,366 +0,0 @@
-/**
- * Agent — AI SDK v6 native hooks for agent awareness.
- *
- * Slots directly into generateText / streamText / ToolLoopAgent via three
- * hooks: prepareStep (inject awareness before each step), onStepFinish
- * (announce activity after each step), and wrapTool (wrap mutation tools
- * with freshness checks). Stateless REST under the hood — works with any
- * API model, no WebSocket.
- *
- * ```ts
- * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@abloatai/ablo/agent';
- *
- * const perception = new Agent({
- *   syncServerUrl: 'http://localhost:8080',
- *   agentId: 'researcher-1',
- *   organizationId: 'org-1',
- *   syncGroups: ['deal:abc'],
- * });
- *
- * const result = await generateText({
- *   model: 'anthropic/claude-sonnet-4.5',
- *   messages,
- *   stopWhen: stepCountIs(10),
- *   tools: {
- *     updateSlide: perception.wrapTool(
- *       tool({
- *         inputSchema: z.object({ id: z.string(), title: z.string() }),
- *         execute: async ({ id, title }) => { ... },
- *       }),
- *       { entityType: 'Slide', getEntityId: (args) => args.id },
- *     ),
- *   },
- *   prepareStep: perception.prepareStep(),     // injects awareness
- *   onStepFinish: perception.onStepFinish(),   // announces activity
- * });
- * ```
- *
- * Low-level primitives (gather, checkFreshness, announce) are also exposed
- * for custom integrations outside the AI SDK.
- */
-import type { PresenceAnnouncer, AgentContext } from './types.js';
-import type { Activity, WireClaim } from '../types/streams.js';
-import { createAgentSession } from './session.js';
-export type { AgentContext } from './types.js';
-export type { WireClaim } from '../types/streams.js';
-/**
- * The record shape the sync server returns from its REST `/api/presence`
- * endpoint. This interface is internal to this module and not exported. Its
- * field names (`userId`, `isAgent`, `updatedAt`) are the wire contract the
- * presence API sends, and {@link Agent.gather} surfaces these records
- * unchanged in the `presence` array of its snapshot.
- */
-interface WirePeer {
-    userId: string;
-    isAgent?: boolean;
-    status: 'online' | 'away' | 'offline' | (string & {});
-    syncGroups?: string[];
-    activity?: Activity;
-    updatedAt?: number;
-    organizationId?: string;
-    activeClaims?: WireClaim[];
-}
-import type { SyncLogger } from '../interfaces/index.js';
-export interface AgentOptions {
-    /** Base URL of the sync server, e.g. `http://localhost:8080`. */
-    syncServerUrl: string;
-    /** Unique agent identifier — without the `agent:` prefix. */
-    agentId: string;
-    /** Organization this agent belongs to. */
-    organizationId: string;
-    /** Sync groups determine which other participants are visible. */
-    syncGroups: string[];
-    /** Optional bearer token for authenticated requests. */
-    authToken?: string;
-    /** Custom fetch — defaults to global fetch. Useful for testing. */
-    fetch?: typeof fetch;
-    /** Timeout per request in ms. Default 5000. */
-    timeoutMs?: number;
-    /**
-     * Optional presence announcer — route `announce()` through this instead
-     * of REST. Pass a connected SyncAgent here to reuse its WebSocket and
-     * avoid per-step HTTP round trips.
-     */
-    announcer?: PresenceAnnouncer;
-    /**
-     * Optional logger. The agent SDK runs in standalone Node processes
-     * that don't share the SyncEngineContext, so Agent takes
-     * its own logger handle. Defaults to a console-backed logger; pass
-     * your structured logger (Pino, Winston, etc.) to get consistent
-     * agent-worker log routing.
-     */
-    logger?: SyncLogger;
-}
-export interface GatherOptions {
-    /** Focus context on these entities — format: "ModelName:id". */
-    focusEntities?: string[];
-    /** Maximum output characters for the formatted prompt. Default 2000. */
-    maxChars?: number;
-    /** Include presence of other participants. Default true. */
-    includePresence?: boolean;
-    /** Exclude this agent's own presence from the output. Default true. */
-    excludeSelf?: boolean;
-}
-export interface AgentSnapshot {
-    timestamp: number;
-    presence: WirePeer[];
-}
-export interface GatherResult {
-    /** Natural-language summary ready to inject as a system message. */
-    prompt: string;
-    /** Structured data for programmatic use. */
-    snapshot: AgentSnapshot;
-}
-export interface FreshnessCheck {
-    stale: boolean;
-    reason?: 'ok' | 'not_found' | 'modified';
-    /** Current entity state from the server. */
-    currentState?: Record<string, unknown>;
-    lastModifiedBy?: string;
-    lastModifiedAt?: number;
-    /** Human-readable summary — feed this back to the LLM when stale. */
-    summary?: string;
-    /**
-     * Pending-mutation claims from other participants targeting this
-     * entity, with the agent's own claims filtered out. An empty array
-     * means no one else is currently generating against the entity. A
-     * non-empty array is advisory: the agent can proceed, wait, or defer.
-     */
-    pendingClaims?: WireClaim[];
-}
-/** Subset of AI SDK's ModelMessage — structural. */
-export interface AgentMessage {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: unknown;
-}
-/** Subset of AI SDK's prepareStep context. */
-export interface PrepareStepContext<M extends AgentMessage = AgentMessage> {
-    stepNumber: number;
-    steps: readonly {
-        toolCalls?: readonly {
-            toolName: string;
-            input?: unknown;
-            args?: unknown;
-        }[];
-        toolResults?: readonly unknown[];
-    }[];
-    messages: M[];
-    model?: unknown;
-}
-/** Subset of AI SDK's prepareStep return shape. */
-export interface PrepareStepResult<M extends AgentMessage = AgentMessage> {
-    messages?: M[];
-    model?: unknown;
-    toolChoice?: unknown;
-    activeTools?: string[];
-}
-/** Subset of AI SDK's onStepFinish context. */
-export interface StepFinishContext {
-    stepType?: 'initial' | 'continue' | 'tool-result';
-    finishReason?: string;
-    text?: string;
-    toolCalls?: readonly {
-        toolName: string;
-        input?: unknown;
-        args?: unknown;
-    }[];
-    toolResults?: readonly unknown[];
-    usage?: {
-        inputTokens?: number;
-        outputTokens?: number;
-        totalTokens?: number;
-    };
-}
-/** Subset of AI SDK's ToolExecutionOptions. */
-export interface ToolExecutionOptions {
-    toolCallId?: string;
-    messages?: AgentMessage[];
-    abortSignal?: AbortSignal;
-    experimental_context?: unknown;
-}
-/** Minimal tool shape — a subset of AI SDK's Tool type. */
-export interface AgentTool<TArgs = unknown, TResult = unknown> {
-    description?: string;
-    inputSchema?: unknown;
-    execute?: (args: TArgs, options: ToolExecutionOptions) => Promise<TResult> | TResult;
-    [extra: string]: unknown;
-}
-export interface PrepareStepOptions {
-    /** Max characters of awareness context to inject. Default 1500. */
-    maxChars?: number;
-    /**
-     * Derive focus entities from recent tool calls so the LLM sees participants
-     * working on the same entities. Requires a mapper from tool call to entity
-     * tokens (format: "ModelName:id"). Default: no auto-focus.
-     */
-    focusFromToolCalls?: (toolCall: {
-        toolName: string;
-        input?: unknown;
-        args?: unknown;
-    }) => string[] | undefined;
-    /** Skip awareness injection for step 0 (initial prompt). Default false. */
-    skipFirstStep?: boolean;
-}
-export interface OnStepFinishOptions {
-    /**
-     * Derive an activity announcement from the finished step. Return null to
-     * skip announcing for this step. Default: announces the last tool name
-     * if any tool was called.
-     */
-    activity?: (ctx: StepFinishContext) => Activity | null;
-}
-export interface WrapToolOptions<TArgs> {
-    /** Entity type the tool mutates — e.g. "Slide", "Sheet". */
-    entityType: string;
-    /** Extract the entity id from the tool's args. */
-    getEntityId: (args: TArgs) => string | undefined;
-    /**
-     * Resolve the timestamp the LLM last saw this entity. If omitted or it
-     * returns 0, the freshness check is skipped (no baseline to compare).
-     */
-    lastSeenAt?: (args: TArgs, options: ToolExecutionOptions) => number | undefined;
-    /**
-     * Announce that the agent is about to work on this entity before executing.
-     * Default true — the agent announces `action: "editing"` automatically.
-     */
-    announceOnExecute?: boolean;
-}
-/**
- * The console-backed logger an {@link Agent} uses when the caller does not
- * supply one. It is the same gated factory the `Ablo()` client uses
- * (`createConsoleLogger`), reads its threshold from the `ABLO_LOG_LEVEL`
- * environment variable (default `warn`), and tags each line with `[agent]` so
- * agent-runtime output is easy to spot. The level is resolved when the logger
- * is built rather than at module load, so an `ABLO_LOG_LEVEL` that the host
- * process sets before constructing an Agent is honored.
- *
- * Exported so a unit test can pin the gating behavior; consumers normally pass
- * their own `logger` option instead.
- */
-export declare function defaultAgentLogger(): SyncLogger;
-export declare class Agent implements PresenceAnnouncer {
-    private readonly opts;
-    constructor(options: AgentOptions);
-    /**
-     * Build a long-lived agent session — caches `Ablo({kind:'agent'})`
-     * instances per `(org, user, surface, target)` and refreshes capability
-     * tokens before TTL elapses. Use on the server when the same agent
-     * identity handles many requests.
-     *
-     * Returns the cache rather than an `Agent` instance: the long-lived path
-     * uses `Ablo({kind:'agent'})` over a WebSocket, while the `Agent` class
-     * itself is the short-lived REST helper for AI SDK tool loops. The static
-     * method lives here so everything agent-related sits under one namespace.
-     *
-     * ```ts
-     * const session = Agent.session({ syncServerUrl, schema, issueToken });
-     * const ablo = await session.getAgent({ userId, organizationId, surfaceClass });
-     * ```
-     */
-    static session: typeof createAgentSession;
-    /** The fully-qualified userId used on the wire: `agent:<agentId>`. */
-    get userId(): string;
-    /**
-     * Extract the Agent instance from an AI SDK tool's
-     * `experimental_context`. Use it inside a tool's `execute` function to
-     * reach the agent without capturing it in a closure.
-     *
-     * ```ts
-     * execute: async (args, { experimental_context }) => {
-     *   const perception = Agent.fromContext(experimental_context);
-     *   const check = await perception.checkFreshness('Slide', args.id, lastSeenAt);
-     *   // ...
-     * }
-     * ```
-     *
-     * Throws if the context is missing or doesn't contain an Agent.
-     * @param ctx The `experimental_context` passed to the tool.
-     * @param toolName Optional tool name for error messages.
-     */
-    static fromContext(ctx: unknown, toolName?: string): Agent;
-    /**
-     * A lenient variant of {@link fromContext} that returns `undefined` instead
-     * of throwing when no agent is present in the context. Useful for tools
-     * where awareness is optional, such as read-only tools that work without it.
-     */
-    static tryFromContext(ctx: unknown): Agent | undefined;
-    /**
-     * Announce this agent's presence/activity. Fire-and-forget — logs errors
-     * but never throws (presence failures must not block the agent loop).
-     *
-     * If a `announcer` was provided (e.g. a connected SyncAgent), routes
-     * through it to reuse the WebSocket. Otherwise falls back to REST POST.
-     */
-    announce(status: 'online' | 'away' | 'offline', activity?: Activity): Promise<void>;
-    /**
-     * Gather a snapshot of current activity by peers and format it as
-     * natural-language context for injection into the next LLM prompt.
-     */
-    gather(options?: GatherOptions): Promise<GatherResult>;
-    /**
-     * Check if an entity was modified since `lastSeenAt`. Use before
-     * executing a mutation to detect stale state.
-     *
-     * Returns `{ stale: true, summary }` when the entity changed — feed
-     * `summary` back to the LLM as a tool result so it can adjust its plan.
-     */
-    checkFreshness(entityType: string, entityId: string, lastSeenAt: number): Promise<FreshnessCheck>;
-    /**
-     * Pull the org's presence, filter to claims targeting the given
-     * entity (self-claims excluded). Advisory — returns empty on any
-     * error so `checkFreshness` stays usable when the presence endpoint
-     * is down. Case-insensitive match on entityType + entityId to absorb
-     * PascalCase / lowercase divergence.
-     */
-    private fetchPendingClaimsFor;
-    /**
-     * Build a `prepareStep` hook for AI SDK's generateText / streamText /
-     * ToolLoopAgent. Called before each step — injects a system message
-     * summarizing what other agents are doing right now.
-     *
-     * ```ts
-     * const result = await generateText({
-     *   // ...
-     *   prepareStep: perception.prepareStep({ maxChars: 1500 }),
-     * });
-     * ```
-     */
-    prepareStep<M extends AgentMessage = AgentMessage>(options?: PrepareStepOptions): (ctx: PrepareStepContext<M>) => Promise<PrepareStepResult<M> | undefined>;
-    /**
-     * Build an `onStepFinish` hook for AI SDK. Called after each step —
-     * announces the agent's activity based on the tool calls that just ran.
-     *
-     * ```ts
-     * const result = await generateText({
-     *   // ...
-     *   onStepFinish: perception.onStepFinish(),
-     * });
-     * ```
-     */
-    onStepFinish(options?: OnStepFinishOptions): (ctx: StepFinishContext) => Promise<void>;
-    /**
-     * Wrap an AI SDK tool to check entity freshness before executing. If the
-     * entity was modified by another actor since the LLM last saw it, returns
-     * a diff summary as the tool result instead of executing — the LLM adjusts
-     * its plan rather than blindly overwriting.
-     *
-     * ```ts
-     * tools: {
-     *   updateSlide: perception.wrapTool(
-     *     tool({ inputSchema: ..., execute: ... }),
-     *     { entityType: 'Slide', getEntityId: (args) => args.id },
-     *   ),
-     * }
-     * ```
-     */
-    wrapTool<TArgs, TResult, TTool extends AgentTool<TArgs, TResult>>(originalTool: TTool, config: WrapToolOptions<TArgs>): TTool;
-    private fetchPresence;
-    private formatPrompt;
-    private request;
-}
-export declare namespace Agent {
-    type Options = AgentOptions;
-    type Context = AgentContext;
-    type SessionOptions = import('./session.js').AgentSessionOptions;
-}