@cubos/agent-sdk 0.0.1153286 → 0.0.1154105

package/dist/admin/conversations.d.ts

@@ -14,6 +14,8 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         limit?: number;
         origin?: string;
         user_id?: string;
+        /** Only conversations carrying this tag (exact, case included). */
+        tag?: string;
     }, signal?: AbortSignal) => Promise<{
         agent: import("../generated/schema.js").components["schemas"]["AgentRef"] | null;
         archived_at: string | null;
@@ -31,6 +33,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         origin: string;
         parent_conversation: import("../generated/schema.js").components["schemas"]["ConversationRef"] | null;
         retry_count: number;
+        tags: string[];
         title: string | null;
         total_cost_usd: number;
         updated_at: string;
@@ -38,6 +41,12 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         user_identifier: string | null;
         user_identifier_label: string | null;
     }[]>;
+    /** Every tag the tenant's conversations carry, with how many carry each —
+     * most used first. Tags have no registry: this is the vocabulary in use. */
+    listTags: (signal?: AbortSignal) => Promise<{
+        conversations: number;
+        tag: string;
+    }[]>;
     get: (id: string, signal?: AbortSignal) => Promise<{
         agent: import("../generated/schema.js").components["schemas"]["AgentRef"] | null;
         archived_at: string | null;
@@ -55,6 +64,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         origin: string;
         parent_conversation: import("../generated/schema.js").components["schemas"]["ConversationRef"] | null;
         retry_count: number;
+        tags: string[];
         title: string | null;
         total_cost_usd: number;
         updated_at: string;
@@ -79,6 +89,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         origin: string;
         parent_conversation: import("../generated/schema.js").components["schemas"]["ConversationRef"] | null;
         retry_count: number;
+        tags: string[];
         title: string | null;
         total_cost_usd: number;
         updated_at: string;
@@ -103,6 +114,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         origin: string;
         parent_conversation: import("../generated/schema.js").components["schemas"]["ConversationRef"] | null;
         retry_count: number;
+        tags: string[];
         title: string | null;
         total_cost_usd: number;
         updated_at: string;
@@ -127,6 +139,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         origin: string;
         parent_conversation: import("../generated/schema.js").components["schemas"]["ConversationRef"] | null;
         retry_count: number;
+        tags: string[];
         title: string | null;
         total_cost_usd: number;
         updated_at: string;
@@ -152,6 +165,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         origin: string;
         parent_conversation: import("../generated/schema.js").components["schemas"]["ConversationRef"] | null;
         retry_count: number;
+        tags: string[];
         title: string | null;
         total_cost_usd: number;
         updated_at: string;
@@ -177,7 +191,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         error: string | null;
         id: string;
         injected_by_conversation_id: string | null;
-        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCallData"] | null;
+        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCall"] | null;
         model: string | null;
         parent_tool_call_id: string | null;
         provider: import("../generated/schema.js").components["schemas"]["ProviderRef"] | null;
@@ -209,7 +223,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         error: string | null;
         id: string;
         injected_by_conversation_id: string | null;
-        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCallData"] | null;
+        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCall"] | null;
         model: string | null;
         parent_tool_call_id: string | null;
         provider: import("../generated/schema.js").components["schemas"]["ProviderRef"] | null;
@@ -240,7 +254,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         error: string | null;
         id: string;
         injected_by_conversation_id: string | null;
-        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCallData"] | null;
+        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCall"] | null;
         model: string | null;
         parent_tool_call_id: string | null;
         provider: import("../generated/schema.js").components["schemas"]["ProviderRef"] | null;
@@ -276,7 +290,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         error: string | null;
         id: string;
         injected_by_conversation_id: string | null;
-        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCallData"] | null;
+        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCall"] | null;
         model: string | null;
         parent_tool_call_id: string | null;
         provider: import("../generated/schema.js").components["schemas"]["ProviderRef"] | null;
@@ -314,7 +328,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         error: string | null;
         id: string;
         injected_by_conversation_id: string | null;
-        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCallData"] | null;
+        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCall"] | null;
         model: string | null;
         parent_tool_call_id: string | null;
         provider: import("../generated/schema.js").components["schemas"]["ProviderRef"] | null;
@@ -344,7 +358,7 @@ export declare function conversationsAdminApi(t: Transport, tenantSlug: string):
         error: string | null;
         id: string;
         injected_by_conversation_id: string | null;
-        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCallData"] | null;
+        llm_call_data: import("../generated/schema.js").components["schemas"]["LlmCall"] | null;
         model: string | null;
         parent_tool_call_id: string | null;
         provider: import("../generated/schema.js").components["schemas"]["ProviderRef"] | null;

package/dist/admin/users.d.ts

@@ -7,6 +7,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     }, signal?: AbortSignal) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         primary_identifier: string | null;
@@ -17,6 +18,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     get: (id: string, signal?: AbortSignal) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
@@ -31,6 +33,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     create: (input: Schemas["CreateUserInput"]) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
@@ -45,6 +48,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     update: (id: string, input: Schemas["UpdateUserInput"]) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
@@ -60,6 +64,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     approve: (id: string, input: Schemas["ApproveUserInput"]) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
@@ -74,6 +79,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     block: (id: string) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
@@ -88,6 +94,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     unblock: (id: string) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];
@@ -102,6 +109,7 @@ export declare function usersApi(t: Transport, tenantSlug: string): {
     merge: (id: string, input: Schemas["MergeUserInput"]) => Promise<{
         created_at: string;
         display_name: string | null;
+        external_id: string | null;
         first_contact_at: string | null;
         id: string;
         identities: import("../generated/schema.js").components["schemas"]["UserIdentity"][];

package/dist/client.d.ts

@@ -199,6 +199,11 @@ export declare class AgentClient {
     listComponentLibraries(id: string, signal?: AbortSignal): Promise<EnabledComponents>;
     getConversation(id: string, signal?: AbortSignal): Promise<Conversation>;
     renameConversation(id: string, title: string, signal?: AbortSignal): Promise<Conversation>;
+    /**
+     * Replace the conversation's tags — the whole set; `[]` removes them all.
+     * The server trims, drops duplicates and sorts, and answers with the result.
+     */
+    setConversationTags(id: string, tags: 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. */

package/dist/generated/schema.d.ts

@@ -4559,6 +4559,65 @@ export interface paths {
         };
         trace?: never;
     };
+    "/api/v1/tenants/{tenantSlug}/conversation-tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List conversation tags
+         * @description Every tag carried by a conversation of the tenant, archived ones included, with how many conversations carry it — most used first, then by name. Capped at 500.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Tenant slug. */
+                    tenantSlug: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ConversationTagUsage"][];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/tenants/{tenantSlug}/conversations": {
         parameters: {
             query?: never;
@@ -4579,6 +4638,8 @@ export interface paths {
                     limit?: number;
                     /** @description Filter by origin (`interactive`, `channel`, `subagent`, `background`); omitted excludes `background`. Invalid values return 400. */
                     origin?: string;
+                    /** @description Restrict to conversations carrying this tag (exact match, case included); omit for any. */
+                    tag?: string;
                     /** @description Restrict to conversations owned by this user id; omit for all users. */
                     user_id?: string;
                 };
@@ -4666,6 +4727,12 @@ export interface paths {
                     };
                     content?: never;
                 };
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
             };
         };
         delete?: never;
@@ -4901,7 +4968,7 @@ export interface paths {
         head?: never;
         /**
          * Update conversation
-         * @description Partially updates `title`, `agent_slug`, and `metadata`; fields absent from the body keep their current value. An explicit `"title": null` clears the title, which makes the conversation fall back to its auto-generated one.
+         * @description Partially updates `title`, `agent_slug`, `metadata` and `tags`; fields absent from the body keep their current value. An explicit `"title": null` clears the title, which makes the conversation fall back to its auto-generated one. `tags` replaces the whole set (422 when a tag is invalid, 409 on a sub-conversation).
          */
         patch: {
             parameters: {
@@ -4947,6 +5014,18 @@ export interface paths {
                     };
                     content?: never;
                 };
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
             };
         };
         trace?: never;
@@ -7476,6 +7555,8 @@ export interface paths {
                     origin?: string;
                     /** @description Composite cursor `<rfc3339>|<uuid>`; streams only conversations newer than it. Overridden by `Last-Event-ID` when present; absent backfills from the epoch. */
                     since?: string;
+                    /** @description Restrict to conversations carrying this tag (exact match, case included); omit for any. */
+                    tag?: string;
                     /** @description Restrict to conversations owned by this user id; omit for all users. */
                     user_id?: string;
                 };
@@ -10773,7 +10854,7 @@ export interface paths {
         };
         /**
          * List users
-         * @description Lists the tenant's users, newest first contact first. Optionally filters by `status` and by `role` slug.
+         * @description Lists the tenant's users, newest first contact first, each with the operator's own `external_id` when one is set. Optionally filters by `status` and by `role` slug.
          */
         get: {
             parameters: {
@@ -10823,7 +10904,7 @@ export interface paths {
         put?: never;
         /**
          * Create user
-         * @description Creates a user, optionally with role slugs and channel identities. Requires a `display_name` or at least one identity; `status` defaults to `active`.
+         * @description Creates a user, optionally with role slugs, channel identities and the operator's own `external_id`. Requires a `display_name` or at least one identity; `status` defaults to `active`. 409 when `external_id` is already taken in the tenant.
          */
         post: {
             parameters: {
@@ -10990,7 +11071,7 @@ export interface paths {
         head?: never;
         /**
          * Update user
-         * @description Patches `display_name`, `timezone` (IANA name, validated), and the `user_md` notepad (capped at 32 KB). Omitted fields stay unchanged; an empty `display_name` clears it to null.
+         * @description Patches `display_name`, `external_id`, `timezone` (IANA name, validated), and the `user_md` notepad (capped at 32 KB). Omitted fields stay unchanged; an empty `display_name` or `external_id` clears it to null. 409 when `external_id` is already taken by another user of the tenant.
          */
         patch: {
             parameters: {
@@ -11036,6 +11117,12 @@ export interface paths {
                     };
                     content?: never;
                 };
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -12796,6 +12883,12 @@ export interface components {
              *     failed or after a successful close.
              */
             retry_count: number;
+            /**
+             * @description Free-form labels, as a set: trimmed, without duplicates, sorted by byte.
+             *     Case is kept. Always empty on a sub-conversation, whose work belongs to
+             *     its root.
+             */
+            tags: string[];
             /**
              * @description The name a human gave this conversation. Null until someone sets
              *     one, and never written by the engine — clients render
@@ -12915,7 +13008,7 @@ export interface components {
              *     authored it. The dashboard badges these as proactively delivered.
              */
             injected_by_conversation_id: string | null;
-            llm_call_data: components["schemas"]["LlmCallData"] | null;
+            llm_call_data: components["schemas"]["LlmCall"] | null;
             model: string | null;
             /**
              * Format: uuid
@@ -13014,6 +13107,15 @@ export interface components {
             output_tokens: number | null;
             summary_text: string;
         };
+        /** @description One tag in use in the tenant, for suggesting and filtering. */
+        ConversationTagUsage: {
+            /**
+             * Format: int64
+             * @description Conversations carrying it, archived ones included.
+             */
+            conversations: number;
+            tag: string;
+        };
         CountTokensResponse: {
             breakdown: components["schemas"]["Breakdown"] | null;
             /**
@@ -13254,6 +13356,8 @@ export interface components {
              */
             component_libraries?: string[] | null;
             metadata?: unknown;
+            /** @description Labels for the new conversation. Normalized like on `PATCH`. */
+            tags?: string[] | null;
             title?: string | null;
             /**
              * Format: uuid
@@ -13421,6 +13525,8 @@ export interface components {
         };
         CreateUserInput: {
             display_name?: string | null;
+            /** @description The operator's own id for this person. Unique per tenant; 409 if taken. */
+            external_id?: string | null;
             identities?: components["schemas"]["CreateIdentityInput"][] | null;
             role_slugs?: string[] | null;
             status?: string | null;
@@ -13901,10 +14007,14 @@ export interface components {
             /** @description PascalCase name, as written in the message: `<PriceChart … />`. */
             tag_name: string;
         };
+        /** @description One LLM round-trip whole: the prompt it was sent and what came of it. */
+        LlmCall: components["schemas"]["LlmCallData"] & {
+            request: components["schemas"]["LlmRequestSnapshot"];
+        };
         /**
-         * @description Typed payload behind the `llm_call_data` JSONB DOMAIN. One snapshot
-         *     per LLM round-trip; `error` and a populated `response` are mutually
-         *     exclusive in normal flow.
+         * @description What came of one LLM round-trip, without the prompt it was sent (see
+         *     [`LlmCall`]); the typed payload behind the `llm_call_data` JSONB DOMAIN.
+         *     `error` and a populated `response` are mutually exclusive in normal flow.
          */
         LlmCallData: {
             coerced_call: components["schemas"]["CoercedCall"] | null;
@@ -13915,7 +14025,6 @@ export interface components {
             error: string | null;
             /** Format: int64 */
             latency_ms: number;
-            request: components["schemas"]["LlmRequestSnapshot"];
             response: components["schemas"]["LlmResponseSnapshot"] | null;
             /**
              * Format: int64
@@ -13929,6 +14038,10 @@ export interface components {
              */
             seen_pending_seq: number | null;
         };
+        /**
+         * @description The prompt one LLM round-trip was sent; the typed payload behind the
+         *     `llm_request` JSONB DOMAIN.
+         */
         LlmRequestSnapshot: {
             messages: components["schemas"]["Message"][];
             system: string;
@@ -15233,6 +15346,13 @@ export interface components {
         UpdateConversationInput: {
             agent_slug?: string | null;
             metadata?: unknown;
+            /**
+             * @description Replaces the whole set; `[]` removes every tag. Each tag is trimmed,
+             *     duplicates are dropped and the set is sorted. 422 for an empty tag, one
+             *     longer than 64 characters or holding a control character, or more than
+             *     20 tags; 409 on a sub-conversation, which takes its root's.
+             */
+            tags?: string[] | null;
             /**
              * @description Tristate: absent leaves the title alone, a string sets it, and an
              *     explicit null clears it — which reveals `generated_title`
@@ -15426,6 +15546,13 @@ export interface components {
         UpdateUserInput: {
             /** @description Display name. Send an empty string to clear it back to null. */
             display_name?: string | null;
+            /**
+             * @description The operator's own id for this person — what MCP servers get as
+             *     `_meta.cubos-agent.userExternalId`. Send an empty string to clear it
+             *     back to null and fall back to the channel identity. Unique per tenant;
+             *     409 if taken.
+             */
+            external_id?: string | null;
             /** @description IANA timezone name (e.g. `America/Sao_Paulo`). 422 if not a known zone. */
             timezone?: string | null;
             /** @description Shared notepad (markdown). Capped at 32 KB, like the `update_user_md` tool. */
@@ -15454,6 +15581,13 @@ export interface components {
             /** Format: date-time */
             created_at: string;
             display_name: string | null;
+            /**
+             * @description The operator's own id for this person, or null. Set only here; nothing
+             *     in the product ever fills it in. When set it is what MCP servers
+             *     receive as `_meta.cubos-agent.userExternalId`, in place of the
+             *     channel-native identifier.
+             */
+            external_id: string | null;
             /** Format: date-time */
             first_contact_at: string | null;
             /** Format: uuid */
@@ -15489,6 +15623,12 @@ export interface components {
             /** Format: date-time */
             created_at: string;
             display_name: string | null;
+            /**
+             * @description The operator's own id for this person, or null. Set only through the
+             *     API; when set it is what MCP servers receive as
+             *     `_meta.cubos-agent.userExternalId` in place of the channel identity.
+             */
+            external_id: string | null;
             /** Format: date-time */
             first_contact_at: string | null;
             /** Format: uuid */

package/dist/index.js

@@ -804,6 +804,7 @@ function conversationsAdminApi(t, tenantSlug) {
   };
   return {
     list: (query = {}, signal) => t.request("GET", base, { query, signal }),
+    listTags: (signal) => t.request("GET", `${tenantPath(tenantSlug)}/conversation-tags`, { signal }),
     get: (id, signal) => t.request("GET", conv(id), { signal }),
     create: (input) => t.request("POST", base, { body: input }),
     update: (id, input) => t.request("PATCH", conv(id), { body: input }),
@@ -1254,6 +1255,7 @@ function toConversation(w) {
     title: w.title ?? w.generated_title ?? null,
     titleIsGenerated: w.title === null && w.generated_title !== null,
     agentSlug: w.agent?.slug ?? null,
+    tags: w.tags,
     lastActivityAt: w.last_activity_at,
     archived: w.archived_at !== null,
     isProcessing: w.is_processing,
@@ -1600,6 +1602,7 @@ class AgentClient {
         agent_slug: agentSlug,
         title: opts.title,
         metadata: opts.metadata,
+        tags: opts.tags,
         ...opts.componentLibraries === undefined ? {} : { component_libraries: opts.componentLibraries }
       },
       signal: opts.signal
@@ -1626,6 +1629,10 @@ class AgentClient {
     const row = await this.#transport.request("PATCH", `${await this.#base()}/${id}`, { body: { title }, signal });
     return toConversation(row);
   }
+  async setConversationTags(id, tags, signal) {
+    const row = await this.#transport.request("PATCH", `${await this.#base()}/${id}`, { body: { tags }, signal });
+    return toConversation(row);
+  }
   async archiveConversation(id, signal) {
     const row = await this.#transport.request("POST", `${await this.#base()}/${id}/archive`, { signal });
     return toConversation(row);
@@ -2064,5 +2071,5 @@ export {
   serveClientTools
 };
 
-//# debugId=0CBE64C57DC5535D64756E2164756E21
+//# debugId=DA5368DD2353F7BE64756E2164756E21
 //# sourceMappingURL=index.js.map