@cubos/agent-sdk 0.0.1136563

package/dist/client.d.ts

@@ -0,0 +1,427 @@
+import { type ConversationCache } from "./cache.js";
+import { type ClientTool, type ClientToolsSession, type ServeClientToolsOptions } from "./client-tools.js";
+import { type TokenSource } from "./http.js";
+import { type FetchLike } from "./sse.js";
+import type { Activity, ClientToolCall, Conversation, ConversationEvent, CreateConversationOptions, EnabledComponents, EventPage, Identity, ListConversationsOptions, Message, MessagePage, Page, PlanSnapshot, Todo, ToolActivity, WorkspaceDir } from "./types.js";
+interface CommonClientOptions {
+    /** Where the Cubos Agent core is reachable, e.g. `https://agent.acme.com`.
+     * Pass `""` for a same-origin deployment. */
+    baseUrl: string;
+    /** Tenant slug. Resolved from the token via `/me` when omitted, at the cost
+     * of one request the first time it's needed. */
+    tenant?: string;
+    /** Override for runtimes whose global `fetch` needs wrapping (proxies,
+     * instrumentation, Node < 18 polyfills). */
+    fetch?: FetchLike;
+    /** Per-request ceiling in ms; `0` disables it. Streams are exempt — they are
+     * meant to stay open. Defaults to 30s. */
+    timeoutMs?: number;
+    /** How many times a 429 is retried, honouring the server's `Retry-After`.
+     * `0` surfaces the rate limit to you instead. Defaults to 2. */
+    maxRetries?: number;
+    /**
+     * Where already-loaded conversations are kept so reopening one is instant.
+     * Defaults to a bounded in-memory LRU; pass `null` to switch it off, or your
+     * own `ConversationCache` to survive a reload.
+     */
+    cache?: ConversationCache | null;
+    /** Messages retained per conversation. Older ones are dropped from the cache
+     * (not from the server) and come back through `loadOlder`. Defaults to 300. */
+    cacheMessageLimit?: number;
+}
+/**
+ * A short-lived token, either handed over once or fetched on demand.
+ *
+ * `getToken` is what a real app wants: tokens expire, and the SDK calls it
+ * again with `forceRefresh` after a 401. `token` exists because a script or a
+ * test that already holds one shouldn't have to write a closure for it — but a
+ * static token cannot be renewed, so it eventually 401s for good.
+ */
+export type UserCredential = {
+    getToken: TokenSource;
+} | {
+    token: string;
+};
+export type ClientOptions = CommonClientOptions & UserCredential;
+export interface ConversationSubscription {
+    /** Stops the streams and releases the connections. Idempotent. */
+    close(): void;
+}
+export interface ConversationHandlers {
+    /** Fires for the backlog on connect and for each new message after. */
+    onMessage?: (message: Message) => void;
+    /**
+     * Every event, exactly as the server sent it, in stream order — before the
+     * handlers above see what it projected into.
+     *
+     * The curated handlers are a projection over this same frame, not a wall in
+     * front of it: taking `onEvent` costs no second connection, no second cursor
+     * and no second catch-up, and an app may take both. Reach for it when your UI
+     * shows the log itself rather than a conversation.
+     */
+    onEvent?: (event: ConversationEvent) => void;
+    /** The event stream is live — on first connect and after every reconnect.
+     * Whatever catches up on gaps belongs here, not before `subscribe`. */
+    onOpen?: () => void;
+    /** The agent called a client tool. Its turn is suspended until someone
+     * answers the call; see `serveClientTools`. */
+    onClientToolCall?: (call: ClientToolCall) => void;
+    /** The agent reached for a tool, or that call finished. Fires twice per client
+     * tool — once running, once resolved — and once for a server-side tool, which
+     * only reports its result. Fold them with `mergeToolActivities`. */
+    onToolActivity?: (activity: ToolActivity) => void;
+    onActivity?: (activity: Activity) => void;
+    /** A turn finished. The one signal that means the agent is done — unlike
+     * `onActivity`, which goes quiet mid-turn while a client tool is answered. */
+    onTurnDone?: (seq: number) => void;
+    /** The plan, with the `seq` that says which answer it belongs to. */
+    onTodos?: (todos: Todo[], seq: number) => void;
+    onConversation?: (conversation: Conversation) => void;
+    /** Every frame's `change_seq`, in the order delivered. Feed the last one back
+     * as `since` on the next connect — that is what lets a cache pick up where it
+     * left off instead of replaying. */
+    onCursor?: (changeSeq: number) => void;
+    /** Transient stream failures. The SDK is already reconnecting; this is for
+     * logging or a "reconnecting…" hint, not for recovery. */
+    onError?: (err: unknown) => void;
+}
+/** What `loadHistory` resolves to: a `MessagePage` plus where it came from. */
+export interface HistoryStart {
+    messages: Message[];
+    /** The tools behind those messages, folded and ordered by `seq`. */
+    toolActivity: ToolActivity[];
+    /** Every plan revision behind them, ordered by `seq`. */
+    plans: PlanSnapshot[];
+    /** Newest finished turn, or null. */
+    lastTurnDoneSeq: number | null;
+    oldestSeq: number | null;
+    /** Pass to `subscribe` as `since`. Null only for a conversation with no
+     * events at all. */
+    latestChangeSeq: number | null;
+    hasOlder: boolean;
+    /** True when nothing was fetched. The stream still reconciles it. */
+    fromCache: boolean;
+}
+export interface ListHandlers {
+    onConversation: (conversation: Conversation) => void;
+    onError?: (err: unknown) => void;
+}
+export declare class AgentClient {
+    #private;
+    constructor(options: ClientOptions);
+    /** Who the current token acts as. Cached — call `refreshIdentity` after
+     * swapping to a token for a different user. */
+    me(): Promise<Identity>;
+    refreshIdentity(): Promise<Identity>;
+    listConversations(opts?: ListConversationsOptions): Promise<Page<Conversation>>;
+    /**
+     * Every conversation, newest activity first, fetching pages as you go.
+     *
+     * `listConversations` hands back a cursor to thread through yourself; this is
+     * the same thing when you just want them all:
+     *
+     * ```ts
+     * for await (const conversation of client.iterateConversations()) { … }
+     * ```
+     *
+     * Stops on `break` without fetching the next page.
+     */
+    iterateConversations(opts?: {
+        pageSize?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<Conversation>;
+    /**
+     * The conversation's history, newest first, paging backwards as you go — so
+     * taking the first N gives you the N most recent messages.
+     *
+     * A voice message's clip and its transcription are paired within a page; if
+     * the two land on either side of a page edge, the clip surfaces with empty
+     * text. Raise `pageSize` if that matters for your history depth.
+     */
+    iterateMessages(id: string, opts?: {
+        pageSize?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<Message>;
+    createConversation(opts?: CreateConversationOptions): Promise<Conversation>;
+    /**
+     * Enable component libraries on `id` — the catalogs of interactive blocks the
+     * agent may put in a reply. Replaces the whole list, so send it complete; an
+     * empty list takes the agent back to plain markdown.
+     *
+     * The libraries themselves are authored by the operator, not here: their
+     * entries are shown to the model verbatim, and writing prompt content needs an
+     * api_key this client will never hold. What you choose is which of them apply
+     * to the screen you have open.
+     *
+     * Returns the slugs together with **every tag they resolve to**. Check that
+     * against the components you can actually draw — the agent placing a tag your
+     * app has no renderer for is a silent hole in a reply, and this is the only
+     * moment both halves are in one place.
+     *
+     * Takes effect on the agent's next turn — a turn already running keeps the
+     * catalog it started with, so what the agent was told it could use and what it
+     * is held to are always the same list.
+     */
+    setComponentLibraries(id: string, libraries: string[], signal?: AbortSignal): Promise<EnabledComponents>;
+    /**
+     * Tell the agent what your app currently has on screen — the open page, the
+     * selected record, the filters in force. Free-form: prose or JSON, whatever
+     * the agent reads best.
+     *
+     * Cheap and safe to call as often as the screen moves, **including while a
+     * turn is running**: it writes no event and starts no turn. The server copies
+     * it into the conversation the next time a turn reads it, and only when it
+     * differs from what the model was last shown — so repeating an unchanged
+     * context costs nothing at all.
+     *
+     * That is the difference from putting the context in the message text, which
+     * is what apps do without this: there it is spent on every message, it shows
+     * up in the transcript unless every render path strips it, and only the app
+     * that owns the composer can send it.
+     *
+     * `null` stops reporting. What the model was already shown stays in the log —
+     * it is the record of the screen an earlier question was asked against.
+     */
+    setContext(id: string, context: string | null, signal?: AbortSignal): Promise<void>;
+    listComponentLibraries(id: string, signal?: AbortSignal): Promise<EnabledComponents>;
+    getConversation(id: string, signal?: AbortSignal): Promise<Conversation>;
+    renameConversation(id: string, title: string, signal?: AbortSignal): Promise<Conversation>;
+    archiveConversation(id: string, signal?: AbortSignal): Promise<Conversation>;
+    /** One page of history, oldest-first. `limit` counts events, so a page may
+     * hold fewer messages than you asked for — `iterateMessages` handles that. */
+    listMessages(id: string, opts?: {
+        before?: number;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<Message[]>;
+    /**
+     * The state to open a conversation with: cached if it has been opened before,
+     * fetched otherwise.
+     *
+     * A hit costs no request. It is not stale either — the caller is expected to
+     * `subscribe` with the returned `latestChangeSeq`, and the server replays
+     * every insert and every mutation past it, so anything that happened while
+     * the app was closed arrives as a delta.
+     *
+     * A cache that throws is treated as a miss: a corrupt store degrades to the
+     * network instead of breaking the conversation.
+     */
+    loadHistory(id: string, opts?: {
+        pageSize?: number;
+        signal?: AbortSignal;
+    }): Promise<HistoryStart>;
+    /**
+     * Records the conversation's current state for the next `loadHistory`.
+     *
+     * `latestChangeSeq` must be the highest cursor folded into `messages` — the
+     * page's, or the last one `subscribe`'s `onCursor` reported. Passing a higher
+     * one would make the next connect skip the events in between; passing a lower
+     * one only costs a replay.
+     *
+     * Silently does nothing without a cache, so callers need no branch.
+     */
+    saveHistory(id: string, state: {
+        messages: Message[];
+        toolActivity?: ToolActivity[];
+        plans?: PlanSnapshot[];
+        lastTurnDoneSeq?: number | null;
+        oldestSeq: number | null;
+        latestChangeSeq: number | null;
+        hasOlder: boolean;
+    }): Promise<void>;
+    /** Forgets one conversation, or every one of this user's. */
+    forgetHistory(id?: string): Promise<void>;
+    /**
+     * `listMessages` plus the cursors a paging UI needs: `oldestSeq` to ask for
+     * the page before this one, and `latestChangeSeq` to start a subscription
+     * from here instead of replaying everything.
+     *
+     * `hasOlder` is false only when the server returned fewer events than asked
+     * for — the one honest signal that the log is exhausted, since a page can
+     * hold events that are not messages.
+     */
+    /**
+     * One page of the conversation's **event log**, oldest-first — the same rows
+     * `listMessagesPage` projects into messages, handed over as they came.
+     *
+     * Reach for this when the curated view is too small a window: an operator
+     * console showing tool calls, an audit trail, anything that has to see the
+     * event types the chat surface deliberately drops. `ConversationEvent` tracks
+     * the server rather than promising stability across refactors — that is the
+     * trade, and it is the same one the REST API already offers.
+     */
+    listEventsPage(id: string, opts?: {
+        before?: number;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<EventPage>;
+    listMessagesPage(id: string, opts?: {
+        before?: number;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<MessagePage>;
+    sendMessage(id: string, content: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * One image, with an optional caption that becomes the message's text.
+     *
+     * png, jpeg, webp and gif, up to 10 MB. The agent sees the picture natively
+     * when its chat model has vision, and otherwise a description from the
+     * agent's fallback vision model — either way this costs a turn, and is
+     * budgeted as one.
+     */
+    sendImage(id: string, image: Blob, opts?: {
+        filename?: string;
+        caption?: string;
+        label?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Up to 10 images in ONE message, so the agent reasons over the set instead of
+     * one turn per picture. `label` names an image for the model, which lets it
+     * answer about "the receipt" rather than "the second image"; `caption` is the
+     * message's own text, shared by the set.
+     */
+    sendImages(id: string, images: Array<{
+        image: Blob;
+        filename?: string;
+        label?: string;
+    }>, opts?: {
+        caption?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Sends a voice message. The agent's STT model transcribes it before the turn
+     * runs, so the reply answers what was said — the transcription then arrives as
+     * a normal `user` message on the stream, which is why nothing is returned
+     * here.
+     *
+     * `audio` is any `Blob`; a `MediaRecorder` chunk works as-is. Its `type`
+     * (codec included) is forwarded, so the provider gets what it needs to decode.
+     */
+    sendAudio(id: string, audio: Blob, opts?: {
+        filename?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * The bytes of one of a message's attachments, as a `Blob`.
+     *
+     * Bytes rather than a URL because the token travels in a header: an `<img
+     * src>` pointing at this route would arrive unauthenticated. Wrap it for the
+     * DOM, and revoke when the element goes away:
+     *
+     * ```ts
+     * const url = URL.createObjectURL(await client.fetchAttachment(convId, msg.id, att.id));
+     * ```
+     *
+     * `attachmentId` is optional only for a single-attachment message; omitted on
+     * a multi-image one, the server serves the first.
+     */
+    fetchAttachment(conversationId: string, messageId: string, attachmentId?: string, signal?: AbortSignal): Promise<Blob>;
+    /**
+     * Lists **one** directory of the conversation's files — never recursive, so a
+     * workspace with thousands of files is still one small response. `path`
+     * defaults to the root.
+     *
+     * With no `atSeq` you see exactly what the agent would be shown on its next
+     * turn, which is also the tree a write starts from — including empty, once a
+     * workspace has gone untouched for long enough to expire. `atSeq` is how you
+     * reach a past snapshot, expiry and all.
+     *
+     * None of the write methods below starts a turn. A file arriving is not a
+     * question: upload what the user dropped, then send a message if you want the
+     * agent to do something about it. It finds out either way — the harness tells
+     * it what changed at the start of its next request.
+     */
+    listFiles(id: string, opts?: {
+        path?: string;
+        atSeq?: number;
+        signal?: AbortSignal;
+    }): Promise<WorkspaceDir>;
+    /**
+     * One file's bytes, as a `Blob`. Bytes rather than a URL for the same reason
+     * as `fetchAttachment`: the token travels in a header, so an `<a href>` at
+     * this route would arrive unauthenticated.
+     */
+    readFile(id: string, path: string, opts?: {
+        atSeq?: number;
+        signal?: AbortSignal;
+    }): Promise<Blob>;
+    /** Creates or replaces one file, creating parent directories. */
+    writeFile(id: string, path: string, file: Blob, opts?: {
+        filename?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Writes several files as **one** snapshot. Worth preferring over a loop of
+     * `writeFile`: the agent is told about the upload as a single change rather
+     * than as N, and nothing ever observes half a set.
+     */
+    writeFiles(id: string, files: Array<{
+        path: string;
+        file: Blob;
+        filename?: string;
+    }>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Removes a file, or a directory with everything under it. Earlier
+     * snapshots keep resolving through `atSeq`. */
+    deleteFile(id: string, path: string, signal?: AbortSignal): Promise<void>;
+    moveFile(id: string, from: string, to: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Declares the tool set on `id` without running anything — the half of
+     * `serveClientTools` that has to happen *before* the first message, since a
+     * tool the agent was never told about can't be called.
+     *
+     * Replaces the whole set, like `setComponents`.
+     */
+    setClientTools(id: string, tools: Record<string, ClientTool<never, unknown>>, signal?: AbortSignal): Promise<void>;
+    /**
+     * Declares your functions as tools on `id` and runs them as the agent calls
+     * them — the browser half of client tools, on the end-user token.
+     *
+     * Belongs on this client and not only on the operator one: the implementation
+     * runs where the app runs, and an api_key is tenant-wide and can never be
+     * shipped to a browser. Keep the session alive for as long as the
+     * conversation is on screen, and `stop()` it when it isn't.
+     *
+     * The runner opens its own event stream by default. If you already subscribe
+     * to the conversation, pass `watch: false` and call `session.poke()` from
+     * `onOpen` and `onClientToolCall` instead: same behaviour over one connection.
+     *
+     * ```ts
+     * const session = client.serveClientTools(id, { tools, watch: false });
+     * client.subscribe(id, {
+     *   onOpen: () => session.poke(),
+     *   onClientToolCall: () => session.poke(),
+     * });
+     * ```
+     */
+    serveClientTools(id: string, options: ServeClientToolsOptions): ClientToolsSession;
+    /** Injects an instruction mid-turn: unlike `sendMessage`, it lands while the
+     * agent is already working and redirects it. */
+    steer(id: string, content: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Live view of one conversation: messages, the agent's activity, and its plan.
+     * Resumes from the last frame after a drop, so a reconnect loses nothing.
+     *
+     * By default it also backfills the whole log on connect, which makes the
+     * subscription the single source of truth for a short conversation. Pass
+     * `since` — the newest `changeSeq` you already hold, from `listMessagesPage` —
+     * to skip that backfill and receive only what is new; that is what makes
+     * paging backwards meaningful, since otherwise the stream re-delivers the
+     * history you just paged through.
+     */
+    subscribe(id: string, handlers: ConversationHandlers, opts?: {
+        since?: number;
+    }): ConversationSubscription;
+    /** Live chat list. Fires per conversation whose activity advances; upsert by
+     * id and re-sort by `lastActivityAt` locally. */
+    subscribeToConversations(handlers: ListHandlers): ConversationSubscription;
+}
+/**
+ * Client for an end user in a browser or mobile app, authenticated with a
+ * short-lived user token. Reaches only the conversation surface, and only that
+ * user's own rows — the server enforces both.
+ */
+export declare function createUserClient(options: ClientOptions): AgentClient;
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,52 @@
+/** Base for everything this SDK throws, so `catch (e) { if (e instanceof
+ * AgentError) }` covers both an HTTP failure and a connection that never got
+ * there. */
+export declare class AgentError extends Error {
+    constructor(message: string);
+}
+/** The server answered, and said no. */
+export declare class AgentApiError extends AgentError {
+    readonly status: number;
+    /** Server's `x-request-id`, when present. Worth quoting in a bug report. */
+    readonly requestId: string | null;
+    /** The response body, verbatim and untruncated. Some routes explain the
+     * failure in there (an MCP probe's reason, a rejected cron) in a form worth
+     * showing the user; `message` only carries a truncated preview. */
+    readonly body: string;
+    constructor(message: string, status: number, requestId?: string | null, body?: string);
+    /** The body parsed as JSON, or `undefined` when it isn't. */
+    json<T = unknown>(): T | undefined;
+    /** The token was rejected. The client already retried once with a fresh one,
+     * so seeing this means `getToken` is handing back something unusable. */
+    get isAuthError(): boolean;
+    get isNotFound(): boolean;
+    /** The request clashed with current state — a slug already taken, a
+     * conversation that belongs to a channel, a user already blocked. */
+    get isConflict(): boolean;
+    /** Worth retrying after a pause: the server is overloaded or briefly down. */
+    get isRetryable(): boolean;
+}
+/**
+ * The client was constructed wrong — a `baseUrl` with no scheme, most often.
+ * Thrown at construction, not on the first call, so the stack points at the
+ * mistake.
+ */
+export declare class AgentConfigError extends AgentError {
+    constructor(message: string);
+}
+/**
+ * The request never produced a response: DNS, TLS, a refused connection, CORS,
+ * or the timeout below.
+ *
+ * Without this, `fetch` rejects with a bare `TypeError: fetch failed` and the
+ * caller cannot tell a wrong `baseUrl` from a server that said 500 — the two
+ * need completely different fixes.
+ */
+export declare class AgentNetworkError extends AgentError {
+    /** Whatever `fetch` (or the abort) threw. */
+    readonly cause: unknown;
+    /** True when the SDK's own timeout fired rather than the network failing. */
+    readonly timedOut: boolean;
+    constructor(message: string, cause: unknown, timedOut?: boolean);
+}
+export declare function raiseForStatus(res: Response, fallback: string): Promise<void>;