@abloatai/ablo 0.3.0

package/dist/agent/Agent.js

@@ -0,0 +1,500 @@
+/**
+ * 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 '@ablo/sync-engine-internal/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 { createAgentSession } from './session.js';
+import { AbloValidationError } from '../errors.js';
+// ── Agent ───────────────────────────────────────────────────────
+// Console-backed default logger. Local to this module so the agent
+// SDK doesn't take a transitive dependency on `getContext()` (which
+// belongs to the web-app context, not standalone agent workers).
+const consoleLogger = {
+    debug: (msg, ...args) => console.debug('[agent]', msg, ...args),
+    info: (msg, ...args) => console.info('[agent]', msg, ...args),
+    warn: (msg, ...args) => console.warn('[agent]', msg, ...args),
+    error: (msg, ...args) => console.error('[agent]', msg, ...args),
+};
+export class Agent {
+    opts;
+    constructor(options) {
+        this.opts = {
+            authToken: options.authToken,
+            announcer: options.announcer,
+            syncServerUrl: options.syncServerUrl.replace(/\/+$/, ''),
+            agentId: options.agentId,
+            organizationId: options.organizationId,
+            syncGroups: options.syncGroups,
+            fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+            timeoutMs: options.timeoutMs ?? 5_000,
+            logger: options.logger ?? consoleLogger,
+        };
+    }
+    /**
+     * 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, NOT an `Agent` instance: the long-lived path
+     * uses `Ablo({kind:'agent'})` over WebSocket, while the `Agent` class
+     * itself is the short-lived REST helper for AI SDK tool loops. The
+     * static method lives here so consumers reach for everything
+     * agent-related under one namespace.
+     *
+     * ```ts
+     * const session = Agent.session({ syncServerUrl, schema, issueToken });
+     * const ablo = await session.getAgent({ userId, organizationId, surfaceClass });
+     * ```
+     */
+    static session = createAgentSession;
+    /** The fully-qualified userId used on the wire: `agent:<agentId>`. */
+    get userId() {
+        return `agent:${this.opts.agentId}`;
+    }
+    /**
+     * Extract the Agent instance from an AI SDK tool's
+     * `experimental_context`. Use inside tool `execute` functions to reach
+     * the perception without closure-capturing it.
+     *
+     * ```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, toolName) {
+        if (!ctx ||
+            typeof ctx !== 'object' ||
+            !('perception' in ctx) ||
+            !(ctx.perception instanceof Agent)) {
+            const where = toolName ? ` (tool: ${toolName})` : '';
+            throw new AbloValidationError(`Agent.fromContext: experimental_context must contain an Agent in \`perception\`.${where} ` +
+                `Set \`experimental_context: { perception } satisfies AgentContext\` when calling generateText/streamText.`, { code: 'agent_perception_missing_context' });
+        }
+        return ctx.perception;
+    }
+    /**
+     * Narrower variant of {@link fromContext} that returns `undefined` instead
+     * of throwing when perception isn't in context. Useful for tools where
+     * awareness is optional (e.g., read-only tools that work without it).
+     */
+    static tryFromContext(ctx) {
+        if (!ctx ||
+            typeof ctx !== 'object' ||
+            !('perception' in ctx) ||
+            !(ctx.perception instanceof Agent)) {
+            return undefined;
+        }
+        return ctx.perception;
+    }
+    // ── Outbound: announce activity ──────────────────────────────────────
+    /**
+     * 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.
+     */
+    async announce(status, activity) {
+        // Prefer injected announcer (WebSocket) over REST
+        if (this.opts.announcer) {
+            try {
+                await this.opts.announcer.announce(status, activity);
+            }
+            catch (err) {
+                this.opts.logger.warn('[perception] announcer error', {
+                    error: err.message,
+                });
+            }
+            return;
+        }
+        try {
+            const res = await this.request('POST', '/api/presence', {
+                userId: this.userId,
+                organizationId: this.opts.organizationId,
+                status,
+                activity,
+                syncGroups: this.opts.syncGroups,
+            });
+            if (!res.ok) {
+                this.opts.logger.warn(`[perception] announce failed: ${res.status} ${res.statusText}`);
+            }
+        }
+        catch (err) {
+            this.opts.logger.warn('[perception] announce error', {
+                error: err.message,
+            });
+        }
+    }
+    // ── Inbound: gather context for next LLM call ────────────────────────
+    /**
+     * Gather a snapshot of current activity by peers and format it as
+     * natural-language context for injection into the next LLM prompt.
+     */
+    async gather(options) {
+        const opts = {
+            maxChars: 2000,
+            includePresence: true,
+            excludeSelf: true,
+            ...options,
+        };
+        const snapshot = {
+            timestamp: Date.now(),
+            presence: [],
+        };
+        if (opts.includePresence) {
+            snapshot.presence = await this.fetchPresence(opts.excludeSelf);
+        }
+        const prompt = this.formatPrompt(snapshot, opts);
+        return { prompt, snapshot };
+    }
+    // ── Freshness check: run before mutations ────────────────────────────
+    /**
+     * 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.
+     */
+    async checkFreshness(entityType, entityId, lastSeenAt) {
+        // Parallel fan-out: freshness (entity state vs lastSeenAt) + pending
+        // intents (other agents about to mutate). Both are advisory — if
+        // either request fails the check still returns a usable result.
+        const [queryRes, pendingIntents] = await Promise.all([
+            this.request('POST', '/api/sync/query', {
+                organizationId: this.opts.organizationId,
+                queries: [{ model: entityType, ids: [entityId] }],
+            }).catch((err) => ({ ok: false, status: 0, _err: err })),
+            this.fetchPendingIntentsFor(entityType, entityId),
+        ]);
+        try {
+            const res = queryRes;
+            if (!('ok' in res) || !res.ok) {
+                return {
+                    stale: false,
+                    reason: 'ok',
+                    summary: `Freshness check inconclusive: ${('status' in res ? res.status : 'error')}`,
+                    pendingIntents,
+                };
+            }
+            const body = (await res.json());
+            const rows = body.results?.[0];
+            if (!rows || rows.length === 0) {
+                return {
+                    stale: true,
+                    reason: 'not_found',
+                    summary: `${entityType} ${entityId} no longer exists. Another actor may have deleted it.`,
+                    pendingIntents,
+                };
+            }
+            const entity = rows[0];
+            const updatedAtRaw = entity.updated_at ?? entity.updatedAt;
+            const lastModifiedBy = entity.updated_by ??
+                entity.updatedBy ??
+                entity.created_by;
+            const lastModifiedAt = typeof updatedAtRaw === 'string'
+                ? Date.parse(updatedAtRaw)
+                : typeof updatedAtRaw === 'number'
+                    ? updatedAtRaw
+                    : undefined;
+            if (lastModifiedAt !== undefined && lastModifiedAt > lastSeenAt) {
+                const ago = Math.round((Date.now() - lastModifiedAt) / 1000);
+                return {
+                    stale: true,
+                    reason: 'modified',
+                    currentState: entity,
+                    lastModifiedBy,
+                    lastModifiedAt,
+                    summary: `${entityType} ${entityId} was modified by ${lastModifiedBy ?? 'another actor'} ` +
+                        `${ago}s ago. Your planned change is based on stale state. ` +
+                        `Re-read the entity and adjust your approach.`,
+                    pendingIntents,
+                };
+            }
+            return {
+                stale: false,
+                reason: 'ok',
+                currentState: entity,
+                lastModifiedBy,
+                lastModifiedAt,
+                pendingIntents,
+            };
+        }
+        catch (err) {
+            // Freshness check is advisory — on error, assume ok and let the
+            // mutation proceed. Better than blocking the agent on a flaky query.
+            return {
+                stale: false,
+                reason: 'ok',
+                summary: `Freshness check error: ${err.message}`,
+                pendingIntents,
+            };
+        }
+    }
+    /**
+     * Pull the org's presence, filter to intents targeting the given
+     * entity (self-intents 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.
+     */
+    async fetchPendingIntentsFor(entityType, entityId) {
+        const etLower = entityType.toLowerCase();
+        const idLower = entityId.toLowerCase();
+        const entries = await this.fetchPresence(true);
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.activeIntents)
+                continue;
+            for (const intent of entry.activeIntents) {
+                if (intent.entityType.toLowerCase() === etLower &&
+                    intent.entityId.toLowerCase() === idLower) {
+                    result.push(intent);
+                }
+            }
+        }
+        return result;
+    }
+    // ── AI SDK hooks ─────────────────────────────────────────────────────
+    /**
+     * 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(options) {
+        const maxChars = options?.maxChars ?? 1500;
+        const focusFromToolCalls = options?.focusFromToolCalls;
+        const skipFirstStep = options?.skipFirstStep ?? false;
+        return async ({ stepNumber, steps, messages }) => {
+            if (skipFirstStep && stepNumber === 0)
+                return undefined;
+            // Derive focus entities from recent tool calls if configured
+            let focusEntities;
+            if (focusFromToolCalls && steps.length > 0) {
+                const focus = new Set();
+                for (const step of steps) {
+                    for (const call of step.toolCalls ?? []) {
+                        const tokens = focusFromToolCalls(call);
+                        if (tokens)
+                            tokens.forEach((t) => focus.add(t));
+                    }
+                }
+                if (focus.size > 0)
+                    focusEntities = [...focus];
+            }
+            const { prompt } = await this.gather({ maxChars, focusEntities });
+            const awareness = { role: 'system', content: prompt };
+            return {
+                messages: [...messages, awareness],
+            };
+        };
+    }
+    /**
+     * 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) {
+        const resolveActivity = options?.activity ??
+            ((ctx) => {
+                const lastCall = ctx.toolCalls?.[ctx.toolCalls.length - 1];
+                if (!lastCall)
+                    return null;
+                return {
+                    entityType: 'Tool',
+                    entityId: lastCall.toolName,
+                    action: 'executed',
+                    detail: lastCall.toolName,
+                };
+            });
+        return async (ctx) => {
+            const activity = resolveActivity(ctx);
+            if (activity) {
+                await this.announce('online', activity);
+            }
+        };
+    }
+    /**
+     * 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(originalTool, config) {
+        const originalExecute = originalTool.execute;
+        if (!originalExecute)
+            return originalTool;
+        const self = this;
+        const announceOnExecute = config.announceOnExecute ?? true;
+        const wrappedExecute = async (args, opts) => {
+            const entityId = config.getEntityId(args);
+            // No id → nothing to guard, just execute
+            if (!entityId) {
+                return originalExecute(args, opts);
+            }
+            // Freshness check (skipped when no baseline timestamp is provided)
+            const lastSeen = config.lastSeenAt?.(args, opts);
+            if (lastSeen !== undefined && lastSeen > 0) {
+                const check = await self.checkFreshness(config.entityType, entityId, lastSeen);
+                if (check.stale && check.summary) {
+                    return check.summary;
+                }
+            }
+            // Announce activity before executing (fire-and-forget)
+            if (announceOnExecute) {
+                void self.announce('online', {
+                    entityType: config.entityType,
+                    entityId,
+                    action: 'editing',
+                });
+            }
+            return originalExecute(args, opts);
+        };
+        return {
+            ...originalTool,
+            execute: wrappedExecute,
+        };
+    }
+    // ── Internal ─────────────────────────────────────────────────────────
+    async fetchPresence(excludeSelf) {
+        try {
+            const url = `/api/presence?orgId=${encodeURIComponent(this.opts.organizationId)}`;
+            const res = await this.request('GET', url);
+            if (!res.ok)
+                return [];
+            const body = (await res.json());
+            const entries = body.entries ?? [];
+            // Filter by overlapping sync groups (presence API returns all org
+            // entries — the SDK narrows to our scope)
+            const ours = new Set(this.opts.syncGroups);
+            return entries.filter((e) => {
+                if (excludeSelf && e.userId === this.userId)
+                    return false;
+                return (e.syncGroups ?? []).some((g) => ours.has(g));
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    formatPrompt(snapshot, opts) {
+        const lines = [];
+        const now = new Date(snapshot.timestamp).toISOString();
+        lines.push(`[Team context as of ${now}]`);
+        const focus = new Set(opts.focusEntities ?? []);
+        const hasFocus = focus.size > 0;
+        // Sort: focused entities first, then agents, then humans
+        const relevant = hasFocus
+            ? snapshot.presence.filter((e) => e.activity && focus.has(`${e.activity.entityType}:${e.activity.entityId}`))
+            : snapshot.presence;
+        if (relevant.length === 0) {
+            lines.push('No other participants active in your scope.');
+        }
+        else {
+            lines.push(hasFocus
+                ? `Participants working on focused entities (${opts.focusEntities.join(', ')}):`
+                : `Active participants:`);
+            for (const entry of relevant) {
+                const role = entry.isAgent ? 'agent' : 'human';
+                const base = `- ${role} ${entry.userId} [${entry.status}]`;
+                if (entry.activity) {
+                    const act = entry.activity;
+                    const detail = act.detail ? ` (${act.detail})` : '';
+                    lines.push(`${base}: ${act.action} ${act.entityType}:${act.entityId}${detail}`);
+                }
+                else {
+                    lines.push(base);
+                }
+            }
+            if (hasFocus && relevant.length < snapshot.presence.length) {
+                const others = snapshot.presence.length - relevant.length;
+                lines.push(`(${others} other participant${others === 1 ? '' : 's'} active on unrelated entities)`);
+            }
+        }
+        let result = lines.join('\n');
+        if (result.length > opts.maxChars) {
+            result = result.slice(0, opts.maxChars - 3) + '...';
+        }
+        return result;
+    }
+    async request(method, path, body) {
+        const url = `${this.opts.syncServerUrl}${path}`;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.opts.authToken) {
+            headers.Authorization = `Bearer ${this.opts.authToken}`;
+        }
+        return this.opts.fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(this.opts.timeoutMs),
+        });
+    }
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @ablo/sync-engine-internal/agent — Agent SDK helpers
+ *
+ * Two entry points depending on agent lifetime:
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * LONG-LIVED AGENT (browser, daemon, persistent Node process)
+ * ─────────────────────────────────────────────────────────────────────────
+ * Use the unified `Ablo({...})` factory directly with `kind: 'agent'`.
+ * The factory holds the WebSocket, reactive subscriptions, mutations, and
+ * presence/intents — same surface as a browser user, just with a
+ * server-issued capability token instead of session cookies.
+ *
+ * ```ts
+ * import Ablo from '@ablo/sync-engine';
+ *
+ * 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 AGENT (SQS 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 '@ablo/sync-engine-internal/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 (ported from vercel-labs/open-agents)
+ * ─────────────────────────────────────────────────────────────────────────
+ * 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 '@ablo/sync-engine-internal/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 (long-lived `Ablo({kind:'agent'})` + Agent together)
+ * ─────────────────────────────────────────────────────────────────────────
+ * 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.
+ */
+export { Agent } from './Agent.js';