@abloatai/ablo 0.34.1 → 0.36.0

package/dist/agent/Agent.js

@@ -1,514 +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 { createAgentSession } from './session.js';
-import { createConsoleLogger, resolveLogLevel } from '../client/consoleLogger.js';
-import { AbloValidationError } from '../errors.js';
-// ── Agent ───────────────────────────────────────────────────────
-/**
- * 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 function defaultAgentLogger() {
-    const gated = createConsoleLogger(resolveLogLevel());
-    return {
-        debug: (msg, ...args) => { gated.debug('[agent]', msg, ...args); },
-        info: (msg, ...args) => { gated.info('[agent]', msg, ...args); },
-        warn: (msg, ...args) => { gated.warn('[agent]', msg, ...args); },
-        error: (msg, ...args) => { gated.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 ?? defaultAgentLogger(),
-        };
-    }
-    /**
-     * 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 = 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 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, 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;
-    }
-    /**
-     * 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) {
-        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) {
-                // Best-effort presence; failing only means peers don't see this
-                // agent's status. Not consumer-actionable → maintainer register.
-                this.opts.logger.debug('[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.debug(`[perception] announce failed: ${res.status} ${res.statusText}`);
-            }
-        }
-        catch (err) {
-            this.opts.logger.debug('[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
-        // claims (other agents about to mutate). Both are advisory — if
-        // either request fails the check still returns a usable result.
-        const [queryRes, pendingClaims] = 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.fetchPendingClaimsFor(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')}`,
-                    pendingClaims,
-                };
-            }
-            const body = (await (res).json());
-            const rows = body.results?.[0];
-            const entity = rows?.[0];
-            if (!entity) {
-                return {
-                    stale: true,
-                    reason: 'not_found',
-                    summary: `${entityType} ${entityId} no longer exists. Another actor may have deleted it.`,
-                    pendingClaims,
-                };
-            }
-            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.`,
-                    pendingClaims,
-                };
-            }
-            return {
-                stale: false,
-                reason: 'ok',
-                currentState: entity,
-                lastModifiedBy,
-                lastModifiedAt,
-                pendingClaims,
-            };
-        }
-        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}`,
-                pendingClaims,
-            };
-        }
-    }
-    /**
-     * 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.
-     */
-    async fetchPendingClaimsFor(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.activeClaims)
-                continue;
-            for (const claim of entry.activeClaims) {
-                if (claim.entityType.toLowerCase() === etLower &&
-                    claim.entityId.toLowerCase() === idLower) {
-                    result.push(claim);
-                }
-            }
-        }
-        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

@@ -1,115 +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.
- */
-export { Agent } from './Agent.js';