@cubos/agent-sdk 0.0.1136563

package/dist/types.d.ts

@@ -0,0 +1,263 @@
+import type { Schemas } from "./schemas.js";
+/** A conversation between one end user and one agent. */
+export interface Conversation {
+    id: string;
+    /** What to show: the name a human gave it, or the one the engine derived from
+     * the opening turns. Null until there is anything nameable in it. */
+    title: string | null;
+    /** True when `title` came from the engine rather than from a person. */
+    titleIsGenerated: boolean;
+    /** Slug of the agent answering, or null for a conversation opened without one. */
+    agentSlug: string | null;
+    /** Sorts the chat list; bumped by any activity, including the agent's own. */
+    lastActivityAt: string;
+    archived: boolean;
+    /** A replica is actively running a turn right now. */
+    isProcessing: boolean;
+    /** There is an unanswered user message. True before `isProcessing` flips. */
+    hasPendingTurn: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export type MessageRole = "user" | "agent";
+export type AttachmentKind = "image" | "audio";
+/** Media the user sent with a message. Fetch the bytes with
+ * `fetchAttachment(conversationId, message.id, attachment.id)`. */
+export interface Attachment {
+    id: string;
+    kind: AttachmentKind;
+    mimeType: string;
+    /** Size in bytes, so a UI can decide before downloading. */
+    bytes: number;
+    /** Name the sender gave an image, which the model also sees next to it. Null
+     * when unnamed, and always null for audio. */
+    label: string | null;
+}
+/** One visible turn of the conversation. Tool calls and internal bookkeeping
+ * events are not messages and never surface here. */
+/** The component libraries enabled on a conversation, and what they add up to.
+ *
+ * A library is authored by the operator — its entries reach the model verbatim,
+ * so writing one needs an api_key. A client picks which of them apply to the
+ * screen it has open, and gets back `tags`: every component the agent may now
+ * instantiate, in the order it sees them indexed.
+ *
+ * `tags` is the half worth acting on. A tag with no renderer in your app is a
+ * block the agent will happily write and nothing will draw — a silent hole in a
+ * reply — and this response is the only place the catalog and your component map
+ * meet. The reverse is fine and expected: renderers with no tag are what draws
+ * the components of older messages, after a library stopped offering them. */
+export interface EnabledComponents {
+    libraries: string[];
+    tags: string[];
+}
+/** A rendered segment of an agent message.
+ *
+ * `markdown` carries the raw markdown of that stretch of the reply; `component`
+ * is one of the components registered on the conversation, with props already
+ * parsed and validated. Anything the client doesn't recognise should fall back
+ * to rendering nothing rather than the tag text — but that only happens for a
+ * component dropped from the set after the message was written.
+ *
+ * A block that is not a `component` always has `text`. Future block kinds will
+ * keep that guarantee, so rendering `text` is always a safe fallback. */
+export type Block = {
+    type: "markdown";
+    text: string;
+} | {
+    type: "component";
+    tag: string;
+    props: Record<string, unknown>;
+};
+export interface Message {
+    id: string;
+    role: MessageRole;
+    /** An image's caption, or the transcript of a voice note. Empty for an
+     * unlabelled image, and for a voice note until STT has run, so render
+     * `attachments` even when this is blank. */
+    content: string;
+    /** Media the user attached, in upload order: the images of one message, or
+     * the single clip of a voice note. */
+    attachments: Attachment[];
+    /** Voice notes only: whether STT has finished. False while the clip waits,
+     * true once its transcription landed — *including* when it landed empty,
+     * which is what a silent recording produces. Without this a client cannot
+     * tell "still transcribing" from "transcribed, and there was no speech":
+     * `content` is the empty string in both. */
+    transcribed?: boolean;
+    /** Per-conversation ordering. Stable across reconnects. */
+    seq: number;
+    at: string;
+    /** The agent's reply split into renderable segments — present on agent
+     * messages only. Plain prose is a single `markdown` block, so a client that
+     * renders blocks needs no special case for "no components here". */
+    blocks?: Block[];
+}
+/** A client tool the agent is waiting on. The arguments are not here: the
+ * runner reads them from the pending list, which is also what makes a call
+ * survive a client that reconnects after the frame went out. */
+export interface ClientToolCall {
+    toolCallId: string;
+    toolName: string;
+}
+/**
+ * A tool the agent used, for showing its work — "how I got here".
+ *
+ * Two events make one of these: the call and its result. A **client tool**
+ * reports both. A server-side tool reports only its result, so the arguments
+ * are read off the `llm_call` that issued it — which means `arguments` is
+ * populated for every tool, but only once that call has been seen. A client
+ * that connects mid-turn, or pages back to a result whose call is on an older
+ * page, gets the entry with none until the page carrying it loads. Treat it as
+ * optional, not as a promise.
+ *
+ * The name is the agent's, not a label: map the ones worth showing to your own
+ * wording and hide the rest, or the trail reads like a stack trace.
+ */
+export interface ToolActivity {
+    toolCallId: string;
+    toolName: string;
+    /** What the agent passed. Undefined until the call that carries them has
+     * been seen — see above. */
+    arguments?: Record<string, unknown>;
+    /** `running` until the result lands, which is also how it arrives live. */
+    status: "running" | "ok" | "error";
+    /** Whatever the tool returned, shaped by the tool itself. */
+    result?: unknown;
+    /** Set when `status` is `error`. */
+    error?: string;
+    /** Server-measured wall clock of the call. */
+    durationMs?: number;
+    /** Log order, so a trail can be placed against the messages around it. */
+    seq: number;
+    at: string;
+}
+export type TodoStatus = "pending" | "in_progress" | "completed";
+/** The agent's own plan for a multi-step request, when the agent chose to keep
+ * one. Nothing forces it to, so an empty list is normal. */
+export interface Todo {
+    title: string;
+    status: TodoStatus;
+}
+/**
+ * The plan as it stood at one point in the log.
+ *
+ * `update_todo` overwrites the whole list on every call, so the log holds one
+ * of these per revision. A client that wants "the plan behind this answer"
+ * takes the last snapshot before the message and ignores the rest: the
+ * intermediate revisions are how the agent got there, not what it decided.
+ */
+export interface PlanSnapshot {
+    todos: Todo[];
+    seq: number;
+}
+/** What the agent is doing right now — the "typing…" signal. */
+export interface Activity {
+    isProcessing: boolean;
+    hasPendingTurn: boolean;
+}
+export interface ListConversationsOptions {
+    /** Page size, 1..=200. Defaults to the server's 30. */
+    limit?: number;
+    /** Cursor from a previous page's `nextCursor`. */
+    before?: string;
+    signal?: AbortSignal;
+}
+export interface Page<T> {
+    items: T[];
+    /** Pass as `before` to fetch the next (older) page; null when exhausted. */
+    nextCursor: string | null;
+}
+/** One page of history plus the cursors needed to page backwards and to start a
+ * subscription from where the page ends. */
+/**
+ * One row of the conversation's event log, exactly as the server sends it.
+ *
+ * The public conversation surface (`Message`, `Todo`, `Activity`) is curated and
+ * stable across internal refactors. This is the other side of that promise: it
+ * is the server's own DTO, so a new event type or field appears here the moment
+ * the server ships one. That is the right trade for an operator console or an
+ * audit view, and the wrong one for a chat bubble.
+ *
+ * It is not a lower tier of access — the REST API already returns exactly this,
+ * so nothing is being unlocked. What differs is only which promise you are
+ * holding.
+ */
+export type ConversationEvent = Schemas["ConversationEvent"];
+export interface EventPage {
+    /** Oldest first. */
+    events: ConversationEvent[];
+    /** Pass as `before` to fetch the page before this one; null on an empty
+     * page. */
+    oldestSeq: number | null;
+    /** The newest `change_seq` on this page — feed it to `subscribe` as `since`
+     * so the stream delivers only what came after. */
+    latestChangeSeq: number | null;
+    /** The page came back full, so there is probably more behind it. */
+    hasOlder: boolean;
+}
+export interface MessagePage {
+    /** Oldest first. */
+    messages: Message[];
+    /** The tools behind those messages, folded and ordered by `seq`. Counted
+     * against the page's event `limit` like anything else in the log, which is
+     * one more reason a page of events is not a page of messages. */
+    toolActivity: ToolActivity[];
+    /** Every revision of the plan on this page, ordered by `seq`. */
+    plans: PlanSnapshot[];
+    /** The `seq` of the newest finished turn on this page, or null if none
+     * finished. Compare with the newest message's `seq` to know whether a turn is
+     * still running — `isProcessing` alone cannot tell you, because a client tool
+     * suspends the turn while it waits. */
+    lastTurnDoneSeq: number | null;
+    /** Pass as `before` to fetch the page before this one; null on an empty page. */
+    oldestSeq: number | null;
+    /** Pass as `since` to `subscribe` so the stream delivers only what is newer. */
+    latestChangeSeq: number | null;
+    /** False when the server returned a short page, meaning the log is exhausted. */
+    hasOlder: boolean;
+}
+/** One entry of a workspace directory listing. */
+export interface WorkspaceEntry {
+    name: string;
+    kind: "file" | "dir" | "symlink";
+    /** A file's bytes, or a directory's recursive total. */
+    size: number;
+    /** Detected content type. Empty for directories, symlinks, and files written
+     * before entries carried it. */
+    mime: string;
+    /** Content hash — of the bytes for a file, of the subtree for a directory.
+     * Two entries sharing it are byte-identical, which makes it a cache key. */
+    sha256: string | null;
+    exec: boolean;
+    symlinkTarget: string | null;
+}
+/** A directory of the conversation's files, as it stood at one snapshot. */
+export interface WorkspaceDir {
+    /** Absolute path that was listed. */
+    path: string;
+    entries: WorkspaceEntry[];
+    /** The snapshot the listing came from; null when the conversation has no
+     * files at all. Pass it around to render a stable view while writes land. */
+    rootEventId: string | null;
+    rootSeq: number | null;
+}
+export interface CreateConversationOptions {
+    /** Which agent to talk to. Must be one the token was minted for; the server
+     * refuses anything else. Optional only when the token names exactly one. */
+    agentSlug?: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    /** Component libraries to enable on the new conversation in the same
+     * round-trip. Equivalent to calling `setComponentLibraries` right after. */
+    componentLibraries?: string[];
+    signal?: AbortSignal;
+}
+/** Identity behind the current token, as the server resolves it. */
+export interface Identity {
+    userId: string;
+    displayName: string;
+    tenantSlug: string;
+    /** Agents this token may open a conversation with. */
+    agentSlugs: string[];
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cubos/agent-sdk",
+  "version": "0.0.1136563",
+  "type": "module",
+  "description": "Client for the Cubos Agent conversation API. Runs anywhere fetch does.",
+  "license": "SEE LICENSE IN LICENSE",
+  "keywords": [
+    "cubos",
+    "agent",
+    "llm",
+    "chat",
+    "sdk",
+    "conversational-ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.cubos.io/agent/cubos-agent.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://git.cubos.io/agent/cubos-agent/-/tree/main/packages/sdk",
+  "bugs": {
+    "url": "https://git.cubos.io/agent/cubos-agent/-/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sse": {
+      "types": "./dist/sse.d.ts",
+      "default": "./dist/sse.js"
+    }
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "gen:api": "bun scripts/gen-api.ts",
+    "typecheck": "tsgo --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "openapi-typescript": "^7.13.0"
+  }
+}