@cubos/agent-sdk 0.0.1154105 → 0.0.1154782

package/dist/admin/agents.d.ts

@@ -208,6 +208,7 @@ export declare function agentsApi(t: Transport, tenantSlug: string): {
     listAutoCallTools: (agentSlug: string, signal?: AbortSignal) => Promise<{
         available: import("../generated/schema.js").components["schemas"]["AutoCallableTool"][];
         enabled_mcp_count: number;
+        gated?: import("../generated/schema.js").components["schemas"]["GatedAutoCallTool"][];
     }>;
     putAutoCallTools: (agentSlug: string, tools: Schemas["AutoCallToolRef"][]) => Promise<void>;
 };

package/dist/generated/schema.d.ts

@@ -1545,7 +1545,7 @@ export interface paths {
         };
         /**
          * List auto-call tools
-         * @description Lists every eligible auto-call candidate for the agent, each flagged with whether it is currently selected, plus the count of attached MCPs. A tool is eligible when its MCP is attached, the tool is enabled, present upstream, within the agent's allowlist, and accepts `{}` as input.
+         * @description Lists every eligible auto-call candidate for the agent, each flagged with whether it is currently selected, plus the count of attached MCPs. A tool is eligible when its MCP is attached, the tool is enabled, present upstream, within the agent's allowlist, accepts `{}` as input, and no skill gates it — an auto-call runs before the model can read a skill. A selected tool that a skill gated afterwards is listed under `gated` instead: the harness skips it.
          */
         get: {
             parameters: {
@@ -1591,7 +1591,7 @@ export interface paths {
         };
         /**
          * Replace auto-call tools
-         * @description Replaces the agent's entire auto-call selection with the request body, in one transaction. Each entry is checked against the same eligibility rules as the list endpoint; one ineligible entry rejects the whole request with `422`.
+         * @description Replaces the agent's entire auto-call selection with the request body, in one transaction. Each entry is checked against the same eligibility rules as the list endpoint — a tool a skill gates included; one ineligible entry rejects the whole request with `422`, whose body names every refused tool and the first rule it fails.
          */
         put: {
             parameters: {
@@ -1635,12 +1635,14 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description One of the tools is not eligible */
+                /** @description One or more tools are not eligible; the body names each and why */
                 422: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": components["schemas"]["AutoCallToolsRefused"];
+                    };
                 };
             };
         };
@@ -5041,7 +5043,7 @@ export interface paths {
         put?: never;
         /**
          * Archive conversation
-         * @description Soft-archives the conversation by setting `archived_at` and bumping `last_activity_at` so list subscribers see the change. Idempotent: re-archiving keeps the original timestamp and emits no SSE delta.
+         * @description Soft-archives the conversation by setting `archived_at` and bumping `last_activity_at` so list subscribers see the change. Idempotent: re-archiving keeps the original timestamp and emits no SSE delta. Archiving settles what was pending on the conversation — open client tool calls are closed unanswered, a parent conversation waiting on it gets what it had already said of its reply, marked as cut short, and a knowledge-base curation run it carried is abandoned.
          */
         post: {
             parameters: {
@@ -5348,7 +5350,7 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Another claimant holds a live lease. */
+                /** @description Another claimant holds a live lease — or, as a plain-text body, the conversation is archived. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -6076,7 +6078,7 @@ export interface paths {
         };
         /**
          * Create or replace a filesystem file
-         * @description Writes one file into the conversation's filesystem, creating parent directories and overwriting whatever was at `path`. The body is `multipart/form-data` with a single `file` part. Starts no turn: the agent is told about the change as part of its next request, so send a message or a steer if you want an answer now. 409 when the conversation's agent has `feature_filesystem` off; 413 when the file or the resulting tree is over the size cap.
+         * @description Writes one file into the conversation's filesystem, creating parent directories and overwriting whatever was at `path`. The body is `multipart/form-data` with a single `file` part. Starts no turn: the agent is told about the change as part of its next request, so send a message or a steer if you want an answer now. 409 when the conversation's agent has `feature_filesystem` off or the conversation is archived; 413 when the file or the resulting tree is over the size cap.
          */
         put: {
             parameters: {
@@ -6663,7 +6665,7 @@ export interface paths {
         put?: never;
         /**
          * Steer the agent
-         * @description Appends an `agent_directive` — an operator/system instruction (e.g. a failed payment to resolve) the agent acts on and replies to the user about, rendered to the model distinctly from the user's own words — and wakes the dispatcher. Works on any conversation, including channel-backed ones. Empty content returns 400.
+         * @description Appends an `agent_directive` — an operator/system instruction (e.g. a failed payment to resolve) the agent acts on and replies to the user about, rendered to the model distinctly from the user's own words — and wakes the dispatcher. Works on any conversation, including channel-backed ones, as long as it is not archived: an archived conversation takes no new event and returns 409. Empty content returns 400.
          */
         post: {
             parameters: {
@@ -6715,6 +6717,13 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description The conversation is archived. */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
             };
         };
         delete?: never;
@@ -6858,7 +6867,7 @@ export interface paths {
         put?: never;
         /**
          * Send a user message
-         * @description Appends a `user_message` to the conversation log with a serialized, monotonically increasing `seq`, and wakes the dispatcher so a turn runs. Only for conversations without a channel — a channel-backed conversation (Telegram/WhatsApp/…) receives the user's words through the channel itself, so injecting one here would forge a message the user never sent; that returns 409. Empty content returns 400.
+         * @description Appends a `user_message` to the conversation log with a serialized, monotonically increasing `seq`, and wakes the dispatcher so a turn runs. Only for conversations without a channel — a channel-backed conversation (Telegram/WhatsApp/…) receives the user's words through the channel itself, so injecting one here would forge a message the user never sent; that returns 409. An archived conversation takes no new event and also returns 409. Empty content returns 400.
          */
         post: {
             parameters: {
@@ -6910,6 +6919,7 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description The conversation is channel-backed, or archived. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -6935,7 +6945,7 @@ export interface paths {
         put?: never;
         /**
          * Send a voice message
-         * @description Appends a `user_message` carrying an audio attachment and wakes the dispatcher. `multipart/form-data` with an `audio` part. The bytes are stored content-addressed; the harness transcribes them through the agent's STT model before the turn runs and records a `media_transcription` event, so the reply answers what was said. The message content is empty by design — the transcription is the text. Same channel rule as the text route: a channel-backed conversation returns 409.
+         * @description Appends a `user_message` carrying an audio attachment and wakes the dispatcher. `multipart/form-data` with an `audio` part. The bytes are stored content-addressed; the harness transcribes them through the agent's STT model before the turn runs and records a `media_transcription` event, so the reply answers what was said. The message content is empty by design — the transcription is the text. Same rules as the text route: a channel-backed or archived conversation returns 409.
          */
         post: {
             parameters: {
@@ -6988,7 +6998,7 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description The conversation is channel-backed. */
+                /** @description The conversation is channel-backed, or archived. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -7021,7 +7031,7 @@ export interface paths {
         put?: never;
         /**
          * Send a user message with images
-         * @description Appends one `user_message` carrying up to 10 image attachments. `multipart/form-data` with repeated `file` parts (any `image/*` type), optional repeated `label` text parts (the i-th label names the i-th file — the model sees it next to that image and can refer to images by name), and an optional `caption` text part shared by the set. The harness shows the images to the model natively when the agent's chat model has vision, or describes them with the agent's fallback vision model — in both cases after the image plugin has normalized them (oriented, downscaled, re-encoded as PNG or JPEG); a type no plugin reads reaches the model as a placeholder. Same channel rule as the plain user-message route: channel-backed conversations return 409.
+         * @description Appends one `user_message` carrying up to 10 image attachments. `multipart/form-data` with repeated `file` parts (any `image/*` type), optional repeated `label` text parts (the i-th label names the i-th file — the model sees it next to that image and can refer to images by name), and an optional `caption` text part shared by the set. The harness shows the images to the model natively when the agent's chat model has vision, or describes them with the agent's fallback vision model — in both cases after the image plugin has normalized them (oriented, downscaled, re-encoded as PNG or JPEG); a type no plugin reads reaches the model as a placeholder. Same channel rule as the plain user-message route: channel-backed conversations return 409, and so do archived ones.
          */
         post: {
             parameters: {
@@ -7074,6 +7084,7 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description The conversation is channel-backed, or archived. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -12501,6 +12512,12 @@ export interface components {
             selected: boolean;
             tool_name: string;
         };
+        /**
+         * @description Why a tool cannot be auto-called. Checked in this order; a refused tool
+         *     carries the first that applies.
+         * @enum {string}
+         */
+        AutoCallRefusal: "unknown_mcp" | "unknown_tool" | "mcp_not_attached" | "disabled" | "disappeared" | "not_in_allowlist" | "required_arguments" | "gated";
         AutoCallToolRef: {
             mcp_slug: string;
             tool_name: string;
@@ -12508,7 +12525,8 @@ export interface components {
         AutoCallToolsConfig: {
             /**
              * @description Tools the operator can pick from: enabled MCPs for the agent, in
-             *     the allowlist if any, present upstream, and accept `{}` as input.
+             *     the allowlist if any, present upstream, accept `{}` as input, and
+             *     no skill gates them.
              */
             available: components["schemas"]["AutoCallableTool"][];
             /**
@@ -12518,6 +12536,22 @@ export interface components {
              *     `available = []` because every tool has required arguments.
              */
             enabled_mcp_count: number;
+            /**
+             * @description Tools in the agent's selection that a skill gated after they were
+             *     picked. The harness never calls them: an auto-call runs before the
+             *     model can read any skill. They are not in `available`, so the next
+             *     save of the selection drops them.
+             */
+            gated?: components["schemas"]["GatedAutoCallTool"][];
+        };
+        /**
+         * @description Body of the `422` that refuses an auto-call selection: every refused tool
+         *     and why, plus all of it in one sentence under `error` — the shape the
+         *     MCP routes' errors already have.
+         */
+        AutoCallToolsRefused: {
+            error: string;
+            rejected: components["schemas"]["RejectedAutoCallTool"][];
         };
         /**
          * @description One segment of an agent message.
@@ -13844,6 +13878,16 @@ export interface components {
          * @enum {string}
          */
         FinishError: "length" | "content_filter";
+        /**
+         * @description A tool still in the agent's auto-call selection that the harness skips
+         *     because a skill gates it.
+         */
+        GatedAutoCallTool: {
+            /** @description Slugs of the MCP's skills that unlock the tool. */
+            gating_skills: string[];
+            mcp_slug: string;
+            tool_name: string;
+        };
         /**
          * @description Returned by the generate/rotate-secret route: the new plaintext, shown
          *     only here.
@@ -14702,6 +14746,18 @@ export interface components {
             default: string;
             options: string[];
         };
+        /** @description One tool the `PUT` refused. */
+        RejectedAutoCallTool: {
+            /** @description Slugs of the MCP's skills that unlock the tool, for `gated`. */
+            gating_skills?: string[];
+            mcp_slug: string;
+            /** @description `mcp/tool: why`, in prose, ready to show an operator. */
+            message: string;
+            reason: components["schemas"]["AutoCallRefusal"];
+            /** @description The arguments the tool requires, for `required_arguments`. */
+            required_arguments?: string[];
+            tool_name: string;
+        };
         ReplaceAgentMcpRolesInput: {
             role_slugs: string[];
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubos/agent-sdk",
-  "version": "0.0.1154105",
+  "version": "0.0.1154782",
   "type": "module",
   "description": "Client for the Cubos Agent conversation API. Runs anywhere fetch does.",
   "license": "SEE LICENSE IN LICENSE",