@abloatai/ablo 0.34.1 → 0.36.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;
-}