@cubos/agent-sdk 0.0.1136563

package/dist/admin/users.d.ts

@@ -0,0 +1,208 @@
+import type { Transport } from "../http.js";
+import type { Schemas } from "../schemas.js";
+export declare function usersApi(t: Transport, tenantSlug: string): {
+    list: (query?: {
+        status?: string;
+        role?: string;
+    }, signal?: AbortSignal) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        primary_identifier: string | null;
+        status: string;
+        updated_at: string;
+        user_md_length: number;
+    }[]>;
+    get: (id: string, signal?: AbortSignal) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    create: (input: Schemas["CreateUserInput"]) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    update: (id: string, input: Schemas["UpdateUserInput"]) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    delete: (id: string) => Promise<void>;
+    approve: (id: string, input: Schemas["ApproveUserInput"]) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    block: (id: string) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    unblock: (id: string) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    merge: (id: string, input: Schemas["MergeUserInput"]) => Promise<{
+        created_at: string;
+        display_name: string | null;
+        first_contact_at: string | null;
+        id: string;
+        identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
+        primary_identifier: string | null;
+        role_slugs: string[];
+        status: string;
+        timezone: string;
+        total_cost_usd: number;
+        updated_at: string;
+        user_md: string;
+    }>;
+    attachRole: (id: string, roleSlug: string) => Promise<void>;
+    detachRole: (id: string, roleSlug: string) => Promise<void>;
+    addIdentity: (id: string, input: Schemas["CreateIdentityInput"]) => Promise<{
+        channel_type: import("../generated/schema.js").components["schemas"]["ChannelType"];
+        created_at: string;
+        id: string;
+        identifier: string;
+        label: string | null;
+    }>;
+    deleteIdentity: (id: string, identityId: string) => Promise<void>;
+    listKnowledgeBases: (id: string, signal?: AbortSignal) => Promise<{
+        created_at: string;
+        display_name: string;
+        id: string;
+        pending_count: number;
+        slug: string;
+        updated_at: string;
+    }[]>;
+    attachKnowledgeBase: (id: string, kbSlug: string) => Promise<void>;
+    detachKnowledgeBase: (id: string, kbSlug: string) => Promise<void>;
+    getMemory: (id: string, signal?: AbortSignal) => Promise<{
+        created_at: string;
+        id: string;
+        profile: string | null;
+        updated_at: string;
+    }>;
+    listMemoryObservations: (id: string, signal?: AbortSignal) => Promise<{
+        content: string;
+        id: string;
+        memory_id: string;
+        metadata: Record<string, unknown>;
+        recorded_at: string;
+        source_conversation: null | import("../generated/schema.js").components["schemas"]["ConversationRef"];
+    }[]>;
+    createMemoryObservation: (id: string, input: Schemas["CreateMemoryObservationInput"]) => Promise<{
+        content: string;
+        id: string;
+        memory_id: string;
+        metadata: Record<string, unknown>;
+        recorded_at: string;
+        source_conversation: null | import("../generated/schema.js").components["schemas"]["ConversationRef"];
+    }>;
+    deleteMemoryObservation: (id: string, observationId: string) => Promise<void>;
+    updateMemoryProfile: (id: string, input: Schemas["UpdateMemoryProfileInput"]) => Promise<{
+        profile: string | null;
+    }>;
+};
+export declare function userRolesApi(t: Transport, tenantSlug: string): {
+    list: (signal?: AbortSignal) => Promise<{
+        created_at: string;
+        description: string;
+        display_name: string;
+        id: string;
+        slug: string;
+        updated_at: string;
+    }[]>;
+    get: (slug: string, signal?: AbortSignal) => Promise<{
+        created_at: string;
+        description: string;
+        display_name: string;
+        id: string;
+        slug: string;
+        updated_at: string;
+    }>;
+    create: (input: Schemas["CreateUserRoleInput"]) => Promise<{
+        created_at: string;
+        description: string;
+        display_name: string;
+        id: string;
+        slug: string;
+        updated_at: string;
+    }>;
+    update: (slug: string, input: Schemas["UpdateUserRoleInput"]) => Promise<{
+        created_at: string;
+        description: string;
+        display_name: string;
+        id: string;
+        slug: string;
+        updated_at: string;
+    }>;
+    delete: (slug: string) => Promise<void>;
+};
+/**
+ * Mints the short-lived tokens a browser SDK runs on (see `createUserClient`).
+ * Call this from your own backend only — it needs an api_key, which must never
+ * reach a browser.
+ */
+export declare function userTokensApi(t: Transport, tenantSlug: string): {
+    create: (input: Schemas["CreateUserTokenInput"]) => Promise<{
+        expires_at: string;
+        token: string;
+    }>;
+};

package/dist/cache.d.ts

@@ -0,0 +1,68 @@
+import type { Message, PlanSnapshot, ToolActivity } from "./types.js";
+/** Bumped when the cached shape changes; entries written by an older SDK are
+ * dropped rather than misread. */
+export declare const CACHE_VERSION = 3;
+export interface CachedConversation {
+    version: number;
+    /** Oldest first, as `listMessagesPage` returns them. */
+    messages: Message[];
+    /** The tools behind those messages, folded. Absent on entries written before
+     * the trail existed, which the version bump already invalidates — typed
+     * optional only so a hand-written cache doesn't have to supply it. */
+    toolActivity?: ToolActivity[];
+    /** Plan revisions, same optionality and the same reason. */
+    plans?: PlanSnapshot[];
+    /** Newest finished turn, so a reload does not show a turn as running. */
+    lastTurnDoneSeq?: number | null;
+    /** Highest `change_seq` folded in. Pass to `subscribe` as `since`. */
+    latestChangeSeq: number;
+    /** Cursor for the page before the oldest message held. */
+    oldestSeq: number | null;
+    hasOlder: boolean;
+}
+/**
+ * Where a client keeps conversations it has already loaded.
+ *
+ * Async on purpose: the in-memory default doesn't need it, but IndexedDB,
+ * AsyncStorage and SQLite all do, and a synchronous interface would shut them
+ * out. Keys are opaque strings already scoped to tenant and user by the client —
+ * an implementation must not reinterpret them.
+ *
+ * Failures should reject rather than throw synchronously; the client treats any
+ * rejection as a cache miss, so a broken store degrades to the network path
+ * instead of breaking the app.
+ */
+export interface ConversationCache {
+    read(key: string): Promise<CachedConversation | null>;
+    write(key: string, entry: CachedConversation): Promise<void>;
+    /** Drops one key, or everything when called with no argument. */
+    clear(key?: string): Promise<void>;
+}
+export interface MemoryConversationCacheOptions {
+    /** How many conversations to retain, least-recently-used evicted first. */
+    maxConversations?: number;
+}
+/**
+ * The default: a bounded LRU in a `Map`, lost on reload.
+ *
+ * Bounded because the natural failure mode of a chat cache is a user who opens
+ * fifty conversations in one session and never reloads.
+ */
+export declare class MemoryConversationCache implements ConversationCache {
+    #private;
+    constructor(options?: MemoryConversationCacheOptions);
+    read(key: string): Promise<CachedConversation | null>;
+    write(key: string, entry: CachedConversation): Promise<void>;
+    clear(key?: string): Promise<void>;
+    /** Retained conversations. For tests and diagnostics. */
+    get size(): number;
+}
+/**
+ * Trims an entry to the newest `limit` messages before it is stored.
+ *
+ * Dropping the front changes what the caller may still page back to, so the
+ * cursors move with it: `oldestSeq` becomes the retained head's `seq` (the
+ * server's `before` is exclusive, so that page picks up right behind it) and
+ * `hasOlder` becomes true, because there now demonstrably is.
+ */
+export declare function trimCached(entry: CachedConversation, limit: number): CachedConversation;

package/dist/client-tools.d.ts

@@ -0,0 +1,96 @@
+import type { Transport } from "./http.js";
+import type { Schemas } from "./schemas.js";
+/** One tool: its declaration and the function that implements it. */
+export interface ClientTool<Args = Record<string, unknown>, Result = unknown> {
+    description?: string;
+    /** JSON Schema for the arguments. Defaults to an open object, which leaves
+     * the model to guess — worth writing. */
+    inputSchema?: Record<string, unknown>;
+    /** JSON Schema for what you return. The server validates against it before
+     * the model sees anything, so a bug in your handler surfaces as a rejected
+     * submit rather than as nonsense in the transcript. */
+    outputSchema?: Record<string, unknown>;
+    /** `true` promises the call mutates nothing, which exempts it from the
+     * agent's guardrail. Don't claim it lightly. */
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    /** `true` promises the call is safe to run twice. Without it the server
+     * assumes it isn't, and pins the lease to the call's deadline so no second
+     * client can pick the call up mid-execution — safer, but a client that dies
+     * holds the call until it times out instead of failing over. */
+    idempotentHint?: boolean;
+    /** Seconds the server waits before failing the call on your behalf.
+     * Defaults to 90. Keep it tight: a pending call also holds back any user
+     * message that arrives meanwhile. */
+    timeoutSeconds?: number;
+    handler: (args: Args, ctx: ClientToolContext) => Promise<Result> | Result;
+}
+export interface ClientToolContext {
+    /** The call's id, echoed on the result. Handy for logs. */
+    toolCallId: string;
+    conversationId: string;
+    /** Aborts when the session stops, so a long handler can bail out. */
+    signal: AbortSignal;
+}
+export interface ServeClientToolsOptions {
+    tools: Record<string, ClientTool<never, unknown>>;
+    /** Stops the session. Same effect as calling `stop()`. */
+    signal?: AbortSignal;
+    /** Identifies this runner when leasing calls. Defaults to a random id, which
+     * is what you want unless you're deliberately resuming another runner's
+     * leases. */
+    claimant?: string;
+    /** Lease length in seconds; the runner renews at half of it. Defaults to 70.
+     * Ignored for a tool that writes and isn't declared `idempotentHint: true` —
+     * the server pins that lease to the call's deadline, because handing such a
+     * call to a second client is worse than making the first one wait. */
+    claimTtlSeconds?: number;
+    /** Skip the declaration sync — for when the tools are already declared and
+     * you only want to execute. */
+    declare?: boolean;
+    /**
+     * Open the conversation's event stream to watch for calls. On by default.
+     *
+     * Turn it off when you already hold that stream — a chat UI does — and drive
+     * the session with `poke()` instead: once for every `client_tool_call` frame,
+     * and once each time the stream (re)connects. One connection instead of two,
+     * and the server caps how many a user may hold open at once.
+     */
+    watch?: boolean;
+    /** Reported failures that the runner recovered from: a stream drop, a
+     * handler that threw. Losing a claim race is not one of them — that is
+     * ordinary coordination, and the runner keeps watching the call instead. */
+    onError?: (err: unknown) => void;
+}
+export interface ClientToolsSession {
+    stop(): void;
+    /**
+     * Look for calls to run, now. Cheap and safe to call spuriously: it reads the
+     * pending list, and a call already being handled is skipped.
+     *
+     * Only needed with `watch: false`, where something else owns the stream.
+     */
+    poke(): void;
+    /** Resolves when the session has stopped and no handler is still running. */
+    done: Promise<void>;
+}
+/**
+ * Declares `tools` on the conversation, then executes every call the agent
+ * makes against them until stopped.
+ *
+ * `conversationPath` is a thunk rather than a string because the two clients
+ * learn the tenant differently: the operator client is constructed with the
+ * slug, while an end-user client discovers it from the token via `me()` and so
+ * can only answer asynchronously.
+ *
+ * The cycle per call is claim → handler → submit. The claim is what keeps two
+ * runners on the same conversation from both executing it; it is renewed while
+ * the handler runs, so a slow handler doesn't lose the call, and it lapses if
+ * this process dies, so the call isn't stranded either.
+ *
+ * A handler that throws submits the failure rather than swallowing it: the
+ * agent needs to hear that the tool failed, otherwise it waits out the
+ * server-side deadline for no reason.
+ */
+export declare function serveClientTools(t: Transport, conversationPath: () => Promise<string>, conversationId: string, options: ServeClientToolsOptions): ClientToolsSession;
+export declare function declarations(tools: Record<string, ClientTool<never, unknown>>): Schemas["NamedClientToolInput"][];