@abloatai/ablo 0.34.1 → 0.36.0

package/dist/agent/index.js

@@ -1,128 +0,0 @@
-/**
- * @abloatai/ablo/agent — Agent SDK helpers
- *
- * Two entry points depending on agent lifetime:
- *
- * ─────────────────────────────────────────────────────────────────────────
- * Long-lived agents (browser, daemon, persistent Node process)
- * ─────────────────────────────────────────────────────────────────────────
- * Use the unified `Ablo({...})` factory directly with `kind: 'agent'`.
- * The factory holds the WebSocket, reactive subscriptions, mutations, and
- * presence/claims — same surface as a browser user, just with a
- * server-issued capability token instead of session cookies.
- *
- * ```ts
- * import Ablo from '@abloatai/ablo';
- *
- * const ablo = Ablo({
- *   schema,
- *   url: 'wss://api.example.com',
- *   organizationId,
- *   kind: 'agent',
- *   agentId: 'reviewer-bot',
- *   capabilityToken: mintedToken,
- *   syncGroups: [`org:${organizationId}`],
- *   inMemory: true,  // Node has no IndexedDB
- * });
- *
- * await ablo.ready();
- * for (const task of ablo.tasks.list({ where: { status: 'pending_review' } })) {
- *   await ablo.tasks.update(task.id, { status: 'reviewed' });
- * }
- * ```
- *
- * For server-side caching across requests, use {@link Agent.session}
- * — it caches one engine per identity and refreshes capability tokens
- * before expiry.
- *
- * ─────────────────────────────────────────────────────────────────────────
- * Short-lived agents (queue consumer, serverless, API route)
- * ─────────────────────────────────────────────────────────────────────────
- * Use {@link Agent}. Stateless REST hooks that slot directly into
- * the Vercel AI SDK's `generateText` / `streamText`. No WebSocket. Ideal
- * for agent-worker jobs that process one task and exit.
- *
- * ```ts
- * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@abloatai/ablo/agent';
- *
- * const perception = new Agent({
- *   syncServerUrl: 'http://localhost:8080',
- *   agentId: job.id,
- *   organizationId: job.organizationId,
- *   syncGroups: [`org:${job.organizationId}`],
- * });
- *
- * await generateText({
- *   model: 'anthropic/claude-sonnet-4.5',
- *   messages,
- *   stopWhen: stepCountIs(10),
- *   tools: {
- *     updateSlide: perception.wrapTool(tool({ ... }), {
- *       entityType: 'Slide',
- *       getEntityId: (args) => args.id,
- *     }),
- *   },
- *   prepareStep: perception.prepareStep(),
- *   onStepFinish: perception.onStepFinish(),
- * });
- * ```
- *
- * ─────────────────────────────────────────────────────────────────────────
- * Idiomatic tool pattern
- * ─────────────────────────────────────────────────────────────────────────
- * Tools are factory functions that pull ambient state from
- * `experimental_context`. The caller builds an {@link AgentContext} once
- * and passes it to `generateText`; every tool reaches in.
- *
- * ```ts
- * import { tool } from 'ai';
- * import { z } from 'zod';
- * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
- *
- * export const updateSlideTool = () => tool({
- *   description: 'Update a slide title',
- *   inputSchema: z.object({ id: z.string(), title: z.string() }),
- *   execute: async (args, { experimental_context }) => {
- *     const perception = Agent.fromContext(experimental_context, 'updateSlide');
- *     const check = await perception.checkFreshness('Slide', args.id, Date.now() - 5000);
- *     if (check.stale) return check.summary;
- *     return { ok: true };
- *   },
- * });
- * ```
- *
- * ─────────────────────────────────────────────────────────────────────────
- * Composed usage (a long-lived `Ablo({kind:'agent'})` plus an Agent)
- * ─────────────────────────────────────────────────────────────────────────
- * If you have a long-lived `Ablo` instance AND want AI SDK hooks, pass it
- * as the `announcer` to Agent — presence announcements route
- * through the existing WebSocket instead of opening new HTTP calls.
- *
- * ```ts
- * const ablo = Ablo({ kind: 'agent', schema, capabilityToken, ... });
- * await ablo.ready();
- *
- * const perception = new Agent({
- *   ...sharedConfig,
- *   announcer: ablo,  // reuse the WebSocket
- * });
- * ```
- *
- * Both `Ablo` and `Agent` implement the
- * {@link PresenceAnnouncer} interface.
- */
-// ── The entire `/agent` surface — one symbol ────────────────────────────
-//
-// `Agent` is both the class and the namespace for its types. Reach for
-// options, context, and session options via dot access:
-//
-//   import { Agent } from '@abloatai/ablo/agent';
-//   const opts: Agent.Options = { ... };
-//   const ctx:  Agent.Context = { perception };
-//   const s:    Agent.SessionOptions = { ... };
-//
-// Everything else (Activity, Claim, Peer, ActiveClaim, ...)
-// lives on the `Ablo.*` namespace via
-// `import type { Ablo } from '@abloatai/ablo'`.
-export { Agent } from './Agent.js';

package/dist/agent/session.d.ts

@@ -1,93 +0,0 @@
-/**
- * Caches and manages the lifecycle of long-lived agent connections on a server.
- *
- * Server code that runs AI agents typically needs the same four things, and this
- * module handles all of them:
- *   1. Reuse one connected agent per (organization, user, surface, target)
- *      instead of connecting anew on every request.
- *   2. Re-issue the agent's capability token before it expires.
- *   3. Request exactly the sync groups the token allows, so the two lists
- *      overlap. If they don't, the agent subscribes to nothing and every
- *      broadcast is silently filtered out.
- *   4. Connect, disconnect, and dispose cleanly.
- *
- * Everything except obtaining the token is the same for every caller and lives
- * here. Obtaining the token depends on how you authenticate — cookie forwarding,
- * API-key exchange, OAuth, and so on — so you supply that step through the
- * {@link AgentSessionOptions.issueToken} callback. The module itself depends on
- * nothing outside this package.
- */
-import { Ablo } from '../client/Ablo.js';
-import type { Schema, SchemaRecord } from '../schema/schema.js';
-interface IssuedToken {
-    readonly token: string;
-    readonly expiresAtMs: number;
-    /**
-     * The sync groups this token grants access to. It must include every group the
-     * agent needs to subscribe to. The agent's effective subscription is the
-     * overlap between the groups it requests and the groups listed here, so a list
-     * that omits a needed group leaves the agent subscribed to nothing and silently
-     * receiving no broadcasts.
-     */
-    readonly syncGroups: readonly string[];
-}
-interface AgentIdentity {
-    readonly userId: string;
-    readonly organizationId: string;
-    /**
-     * The kind of surface making the request, such as `'chat'`, `'mcp'`, or
-     * `'agent_worker'`. The cache keys on this value, so two surfaces never share a
-     * token or a WebSocket connection.
-     */
-    readonly surfaceClass: string;
-    readonly target?: {
-        readonly entityType: string;
-        readonly entityId: string;
-    } | null;
-}
-export interface AgentSessionOptions<R extends SchemaRecord = SchemaRecord> {
-    /** WebSocket URL of your sync server, such as `wss://sync.example.com` or `ws://localhost:3001`. */
-    readonly syncServerUrl: string;
-    /**
-     * Your schema, used to build the typed model proxy on the returned client. The
-     * agent client exposes it as `agent.<model>.create/update/delete`.
-     */
-    readonly schema: Schema<R>;
-    /**
-     * Issues a capability token for the given identity. The session calls it on a
-     * cache miss or when the current token is near expiry. Because this callback
-     * carries out your authentication flow — cookie forwarding, API-key exchange,
-     * OAuth, and so on — the rest of the session stays independent of how you
-     * authenticate.
-     */
-    readonly issueToken: (identity: AgentIdentity) => Promise<IssuedToken>;
-    /**
-     * How long before a token's true expiry the session should re-issue it, in
-     * milliseconds. Defaults to 30 seconds. The buffer absorbs clock skew so a
-     * token never expires mid-use.
-     */
-    readonly reissueBufferMs?: number;
-    /**
-     * How to derive the agent's identifier from the request identity. Defaults to
-     * `${surfaceClass}:${userId}`. Override it when you want a different shape for
-     * attribution.
-     */
-    readonly agentIdFor?: (identity: AgentIdentity) => string;
-}
-/**
- * Creates a session that hands out connected agents on demand. Its `getAgent`
- * method handles caching, token issuance, sync-group alignment, and connection
- * lifecycle; call `disposeAll` from your process's shutdown hook to close every
- * open connection.
- *
- * Treat the session as a long-lived singleton shared across requests. The cache
- * key combines organization, user, surface, and target, so two concurrent
- * requests for the same combination share one agent and one WebSocket, while
- * requests for different combinations get independent agents.
- */
-export declare function createAgentSession<R extends SchemaRecord = SchemaRecord>(options: AgentSessionOptions<R>): {
-    getAgent: (identity: AgentIdentity) => Promise<Ablo<R>>;
-    evict: (identity: AgentIdentity) => void;
-    disposeAll: () => void;
-};
-export {};

package/dist/agent/session.js

@@ -1,149 +0,0 @@
-/**
- * Caches and manages the lifecycle of long-lived agent connections on a server.
- *
- * Server code that runs AI agents typically needs the same four things, and this
- * module handles all of them:
- *   1. Reuse one connected agent per (organization, user, surface, target)
- *      instead of connecting anew on every request.
- *   2. Re-issue the agent's capability token before it expires.
- *   3. Request exactly the sync groups the token allows, so the two lists
- *      overlap. If they don't, the agent subscribes to nothing and every
- *      broadcast is silently filtered out.
- *   4. Connect, disconnect, and dispose cleanly.
- *
- * Everything except obtaining the token is the same for every caller and lives
- * here. Obtaining the token depends on how you authenticate — cookie forwarding,
- * API-key exchange, OAuth, and so on — so you supply that step through the
- * {@link AgentSessionOptions.issueToken} callback. The module itself depends on
- * nothing outside this package.
- */
-import { Ablo } from '../client/Ablo.js';
-import { AbloConnectionError } from '../errors.js';
-import { getContext } from '../context.js';
-/**
- * Creates a session that hands out connected agents on demand. Its `getAgent`
- * method handles caching, token issuance, sync-group alignment, and connection
- * lifecycle; call `disposeAll` from your process's shutdown hook to close every
- * open connection.
- *
- * Treat the session as a long-lived singleton shared across requests. The cache
- * key combines organization, user, surface, and target, so two concurrent
- * requests for the same combination share one agent and one WebSocket, while
- * requests for different combinations get independent agents.
- */
-export function createAgentSession(options) {
-    const reissueBufferMs = options.reissueBufferMs ?? 30_000;
-    const agentIdFor = options.agentIdFor ??
-        ((id) => `${id.surfaceClass}:${id.userId}`);
-    const cacheByKey = new Map();
-    function cacheKey(id) {
-        const targetSeg = id.target
-            ? `:${id.target.entityType}:${id.target.entityId}`
-            : '';
-        return `${id.organizationId}:${id.userId}:${id.surfaceClass}${targetSeg}`;
-    }
-    async function getAgent(identity) {
-        const key = cacheKey(identity);
-        const cached = cacheByKey.get(key);
-        if (cached && cached.expiresAtMs - Date.now() > reissueBufferMs) {
-            return cached.agent;
-        }
-        // Best-effort cleanup of stale agent — don't let a stuck cached
-        // entry block fresh issuance.
-        if (cached) {
-            try {
-                await cached.agent.dispose();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        const minted = await options.issueToken(identity);
-        // Request the same sync groups the token grants. The groups requested here
-        // and the groups the token allows must overlap; otherwise their intersection
-        // is empty and every broadcast is filtered out. The token's allowed list is
-        // exactly what to request, since the caller decided what went into it.
-        //
-        // Pass the URL as `baseURL`, the field the client reads. Any other field name
-        // is ignored, in which case the client would fall back to its default host,
-        // so `baseURL` keeps the caller's URL the single source of truth.
-        const wsUrl = toWsUrl(options.syncServerUrl);
-        const agentOptions = {
-            baseURL: wsUrl,
-            schema: options.schema,
-            kind: 'agent',
-            capabilityToken: minted.token,
-            agentId: agentIdFor(identity),
-            organizationId: identity.organizationId,
-            syncGroups: [...minted.syncGroups],
-            // Agents run in Node — no IDB available, no need for it.
-            inMemory: true,
-        };
-        const agent = Ablo(agentOptions);
-        try {
-            await agent.ready();
-        }
-        catch (err) {
-            const e = err;
-            const code = e.cause?.code;
-            const causeMsg = e.cause?.message;
-            // Best-effort dispose so the failed agent doesn't leak ws state.
-            try {
-                await agent.dispose();
-            }
-            catch { /* ignore */ }
-            // Log through the level-gated logger so it honors ABLO_LOG_LEVEL: an
-            // `error` headline naming the unreachable URL and code, plus a `debug`
-            // companion carrying the structured fields for deeper diagnosis.
-            const log = getContext().logger;
-            log.error(`Agent could not connect to the sync server at ${wsUrl}${code ? ` (${code})` : ''}.`);
-            log.debug('[Agent.session] ws bootstrap failed', {
-                url: wsUrl,
-                surfaceClass: identity.surfaceClass,
-                orgId: identity.organizationId,
-                userId: identity.userId,
-                code,
-                causeMsg,
-                err,
-            });
-            throw new AbloConnectionError(`ws bootstrap ${wsUrl} failed: ${e.message ?? 'bootstrap failed'}` +
-                (code ? ` (${code})` : ''), { code: 'bootstrap_fetch_timeout', cause: err });
-        }
-        cacheByKey.set(key, { agent, expiresAtMs: minted.expiresAtMs });
-        return agent;
-    }
-    function disposeAll() {
-        for (const { agent } of cacheByKey.values()) {
-            try {
-                void agent.dispose();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        cacheByKey.clear();
-    }
-    /**
-     * Removes and disposes one cached agent. Call it when you know the agent's
-     * token is no longer valid — after a revocation or role change, for example —
-     * so the next `getAgent` call issues a fresh one.
-     */
-    function evict(identity) {
-        const key = cacheKey(identity);
-        const cached = cacheByKey.get(key);
-        if (cached) {
-            try {
-                void cached.agent.dispose();
-            }
-            catch {
-                /* ignore */
-            }
-            cacheByKey.delete(key);
-        }
-    }
-    return { getAgent, evict, disposeAll };
-}
-/** `https://host` → `wss://host`; `http://host` → `ws://host`. */
-function toWsUrl(url) {
-    return url.replace(/^http/, 'ws');
-}

package/dist/agent/types.d.ts

@@ -1,68 +0,0 @@
-/**
- * Types specific to running AI agents. The shared data vocabulary — `Peer`,
- * {@link Activity}, `Claim`, `ActiveClaim`, `PresenceUpdatePayload`, and
- * `PresenceKind` — lives in the streams module. This file adds only the two
- * pieces the agent layer needs on top of it: {@link PresenceAnnouncer}, a
- * transport-agnostic way to announce presence, and {@link AgentContext}, the bag
- * of ambient state passed to AI SDK tools.
- */
-import type { Activity } from '../types/streams.js';
-/**
- * A minimal interface for announcing an agent's presence, independent of how it
- * connects. Both the WebSocket-based agent client and the REST-based agent
- * implement it, so higher-level code can depend on this interface without caring
- * which transport is in use.
- */
-export interface PresenceAnnouncer {
-    announce(status: 'online' | 'away' | 'offline', activity?: Activity): Promise<void>;
-}
-/**
- * The ambient state passed to AI SDK tools through the AI SDK's
- * `experimental_context`. Build one {@link AgentContext} per agent invocation and
- * pass it as `experimental_context`; each tool's `execute` function then reads
- * what it needs from `options.experimental_context` rather than closing over
- * shared module state.
- *
- * Passing context this way, rather than capturing it in each tool's closure,
- * keeps tools as plain module exports that any agent can reuse, types the context
- * in one place, and lets a new tool read any field without changing its
- * signature.
- *
- * ```ts
- * import { generateText, tool } from 'ai';
- * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
- *
- * const updateSlideTool = () => tool({
- *   inputSchema: z.object({ id: z.string(), title: z.string() }),
- *   execute: async (args, { experimental_context }) => {
- *     const perception = Agent.fromContext(experimental_context);
- *     const check = await perception.checkFreshness('Slide', args.id, Date.now() - 5000);
- *     if (check.stale) return check.summary;
- *     // ... actual mutation
- *   },
- * });
- *
- * await generateText({
- *   model: 'anthropic/claude-sonnet-4.5',
- *   tools: { updateSlide: updateSlideTool() },
- *   experimental_context: { perception, organizationId, userId } satisfies AgentContext,
- * });
- * ```
- *
- * Extend {@link AgentContext} with your own fields through module augmentation or
- * by intersecting it with your own context type.
- */
-export interface AgentContext {
-    /** Announces presence and checks whether an entity has changed since a given time. Required. */
-    perception: PresenceAnnouncer & {
-        checkFreshness?: (entityType: string, entityId: string, lastSeenAt: number) => Promise<unknown>;
-    };
-    /** The organization every operation is scoped to. */
-    organizationId?: string;
-    /** Identifier for the user or agent. Agents use the form `agent:<id>`. */
-    userId?: string;
-    /** The sync groups this agent belongs to. */
-    syncGroups?: string[];
-    /** Room for your own product-specific fields. */
-    [key: string]: unknown;
-}

package/dist/agent/types.js

@@ -1,9 +0,0 @@
-/**
- * Types specific to running AI agents. The shared data vocabulary — `Peer`,
- * {@link Activity}, `Claim`, `ActiveClaim`, `PresenceUpdatePayload`, and
- * `PresenceKind` — lives in the streams module. This file adds only the two
- * pieces the agent layer needs on top of it: {@link PresenceAnnouncer}, a
- * transport-agnostic way to announce presence, and {@link AgentContext}, the bag
- * of ambient state passed to AI SDK tools.
- */
-export {};