@blazingagents/sdk 0.14.0 → 0.16.0

package/README.md

@@ -21,14 +21,17 @@ requires Node.js 24 or newer.
 - Public Zod contracts for validating API requests and responses.
 - Cursor pagination and binary transfers.
 - Request correlation and a typed, forward-compatible error model.
+- End-user scoped clients for user-owned resources and generation.
 
 ## Installation
 
 ```console
-npm install @blazingagents/sdk ai@7.0.84
+npm install @blazingagents/sdk ai@^7.0.84 zod@^4.5.4
 ```
 
-`ai` is a peer dependency. The SDK re-exports its `UIMessage` type.
+`ai` (`^7.0.84`) and `zod` (`^4.5.4`) are peer dependencies. The SDK
+re-exports AI SDK message types and Zod schemas, so consumers share these
+dependencies with the SDK.
 
 ## Quick start
 
@@ -70,232 +73,3 @@ npm run test:consumer
 ## License
 
 [MIT](LICENSE)
-
-### Thinking level
-
-Agent create/update accepts `thinkingLevel: "high"`, `"off"`, `"max"`, or
-another nonempty string supported by the selected Model. Omission on creation
-means Provider default; omission on update preserves the saved value, while
-`thinkingLevel: null` clears it. Agent and Version responses include the
-selection, and `restoreVersion` restores it through ordinary validation.
-Use `client.providers.getThinkingLevels({ providerId, model })` to read
-`{ known, levels }`. Unknown capabilities permit custom values that can still
-be rejected during execution. Levels control reasoning, not a token/cost cap.
-
-For native clients whose `Response` constructor does not support streaming bodies,
-use `result.toStream()` on chat or terminal continuation results to read the
-original SSE bytes. It shares one-shot ownership with `toResponse()`; choose one
-accessor per result. Stream errors and cancellation retain the same behavior.
-
-### Relay browser chat
-
-Tenant browser apps use `BlazingAgentsChatTransport` with their own backend.
-The backend holds the Tenant API key and authorizes each Session. The transport
-sends the newest user message and resumes with the server-minted Session ID.
-
-### Direct chat with the SDK
-
-For the platform dashboard or another runtime with an authorized credential,
-use `BlazingAgentsDirectChatTransport` with AI SDK `useChat`. It sends through
-`client.chat()` and decodes the stream without constructing a streaming
-`Response`. Inject a native streaming fetch implementation into `BlazingAgents`
-when the runtime requires one.
-
-```tsx
-import { useMemo } from "react";
-import { useChat } from "@ai-sdk/react";
-import { BlazingAgents, BlazingAgentsDirectChatTransport } from "@blazingagents/sdk";
-
-function Chat({ getCredential, agentId, initialSessionId, saveSessionId }) {
-  const transport = useMemo(
-    () => new BlazingAgentsDirectChatTransport({
-      getClient: async () => new BlazingAgents({ apiKey: await getCredential() }),
-      agentId,
-      sessionId: initialSessionId,
-      onSessionId: saveSessionId,
-    }),
-    [getCredential, agentId, initialSessionId, saveSessionId],
-  );
-  const chat = useChat({ transport });
-  // Render chat.messages and submit using chat.sendMessage({ text }).
-}
-```
-
-Install `@ai-sdk/react` for the React hook. Keep the transport stable for one
-Session; remount the chat with a new transport when switching Agents or
-Sessions. `getClient` runs before each request, so it can read a current
-dashboard credential. Return a `BlazingAgents` client with that credential.
-
-On Session creation, `version` pins the Agent Version, and `userId` and
-`metadata` set attribution. To invoke a stored Prompt, pass `promptId` and
-optional `variables` to the transport. Its first Turn sends those fields in
-place of the `useChat` user message. Later Turns send user messages and omit
-the create options, including `version`.
-
-`onSessionId` runs once for a newly created Session before stream consumption,
-so it can be saved even if streaming later fails. The transport preserves user
-message IDs, regeneration targets, and `useChat` cancellation. Regeneration
-requires an existing Session. When `useChat` submits tool approval responses,
-the transport sends each decision in order and streams the continuation. After
-reload, `reconnectToStream` joins a queued or running continuation for the
-supplied `sessionId`. It returns `null` when there is no active continuation.
-It does not retry an interrupted ordinary Turn.
-
-### Cancel requests
-
-Pass an optional `abortSignal` in the request object for reads, writes, uploads,
-and generation:
-
-```ts
-const controller = new AbortController();
-const agents = client.agents.list({ abortSignal: controller.signal });
-controller.abort();
-await agents; // Rejects with the SDK's typed cancellation error.
-```
-
-SDK response parsing strips unknown object fields while validating required
-fields and known field types. Request validation remains strict.
-
-### Migrating from 0.2.x to 0.3.0
-
-Resource and generation methods take a single request object, optional when no
-fields are required. Move positional identifiers, body fields, and request
-options into that object. Use `abortSignal` instead of
-`signal`; custom fetch implementations still receive the native `signal`.
-
-```ts
-// Before (0.2.x)
-client.agents.update(agentId, { name: "Builder" });
-client.sessions.messages(agentId, sessionId, { signal });
-client.agent(agentId).skills.list();
-
-// After (0.3.0)
-client.agents.update({ agentId, name: "Builder", abortSignal: signal });
-client.sessions.messages({ agentId, sessionId, abortSignal: signal });
-client.agent({ agentId }).skills.list({ abortSignal: signal });
-```
-
-`ResourceRequestOptions` replaces `ResourceReadOptions`. Cancellation stops the
-request; it does not roll back a mutation already accepted by the server.
-
-## Interactive resend
-
-Successful interactive exchanges are saved together. Failed or canceled execution
-leaves saved history unchanged, including the previous answer during regeneration;
-executed usage and Tool effects remain. Retain submitted text/images until success
-and resend edited or unchanged input through ordinary chat with a fresh message ID.
-Stop requests cancellation; a lost response can hide a saved exchange. Reuse the
-returned Session ID and load history normally on return. No outcome polling or
-automatic generation retry is needed. See the [chatbot guide](https://docs.blazingagents.com/getting-started/chatbot)
-and [working examples](https://github.com/blazingagents/examples).
-
-## Automatic context compaction
-
-Agents enable automatic compaction by default with a 16,384-token reserve.
-A larger reserve compacts earlier. Settings are included in Agent Versions.
-Compaction summarizes older history for the model while retaining the full
-Session transcript; summarization calls contribute to token usage.
-
-```ts
-await client.agents.update({
-  agentId: "ag_...",
-  autoCompaction: true,
-  compactionReserveTokens: 32768,
-});
-```
-
-### Tool approval policies (0.8.0)
-
-Agents and immutable Agent Versions expose separate `approvalInChat` and
-`approvalInTasks` policies. Create and update them through the ordinary Agent API:
-
-```ts
-await client.agents.update({
-  agentId,
-  approvalInChat: {
-    default: "full",
-    overrides: [
-      { tool: { type: "builtin", name: "bash" }, decision: "manual" },
-      {
-        tool: { type: "mcp", connectionId: "mcp_0123456789abcdef", name: "send_mail" },
-        decision: "auto",
-      },
-    ],
-  },
-  approvalInTasks: { default: "deny", overrides: [] },
-});
-```
-
-An exact tool override wins over the default. Both policies default to `full`
-with no overrides. `full` allows available tools, `deny` blocks execution,
-`manual` requires human review, and `auto` uses backend LLM review. Review errors
-block execution; escalation without an available human also blocks execution.
-Policies do not grant tool access. MCP references use the original remote tool
-name and connection ID; the backend validates attachment and discovery.
-
-Omitting a policy from an update preserves it. Supplying one replaces that whole
-policy; omitted or empty `overrides` clears its overrides. `restoreVersion`
-restores both policies alongside the other versioned fields.
-
-Interactive Sessions reuse `client.sessions.toolApprovals`,
-`client.sessions.decideToolApproval`, and
-`client.sessions.joinToolApprovalContinuation`. A configured backend human
-reviewer path is required. Tasks and stateless generations have no human
-continuation path and block manual or escalated calls; stateless generation uses
-`approvalInChat`. The SDK does not run an approval reviewer.
-
-Approval rows retain optional `tool`, `assistantMessageId`, `createdAt`, and
-`decidedAt` metadata. `tool` and `decidedAt` may be null (admin tools have no
-ordinary-policy reference). Persisted approval decisions remain
-`pending | approved | denied`; policy modes are `full | deny | manual | auto`.
-The root package exports `ApprovalDecision`, `ApprovalPolicy`, `ToolReference`,
-and `ToolApprovalState`; runtime policy schemas are exported from
-`@blazingagents/sdk/contracts`.
-
-## Slack and Telegram
-
-Use the [connection example](https://github.com/blazingagents/typescript-sdk/blob/main/examples/chat-integrations.md) to connect an existing
-Agent through REST. BA hosts the Chat SDK runtime, conversation history, and
-approval cards; no additional SDK resource is required.
-
-`client.chatDeliveries.list` reads the Tenant-wide delivery feed across all
-Chat Connections, newest first. `status` accepts `failed` and/or `ambiguous`;
-omitting it returns both. For example, the failed and ambiguous deliveries
-since a timestamp:
-
-```ts
-const page = await client.chatDeliveries.list({
-  status: ["failed", "ambiguous"],
-  since: "2026-09-01T00:00:00.000Z",
-});
-```
-
-## Merchant monetization
-
-Bill your own customers for model-token usage through your Polar or Dodo
-merchant account. Blazing Agents records usage per Turn and delivers it to
-your provider; your provider owns billing.
-
-```ts
-const client = new BlazingAgents({ apiKey: "ba_..." });
-
-// One-time: connect your merchant account (dashboard or API).
-await client.merchantConnection.create({
-  provider: "polar",
-  environment: "sandbox",
-  credential: "polar_oat_...", // organization access token
-});
-
-// On user onboarding in your backend: bind your user id to the
-// provider-side customer so usage is attributed correctly.
-await client.merchantBindings.put({
-  userId: "user_123",
-  customerId: "cust_polar_...",
-});
-```
-
-`client.merchantUsageEvents` exposes the delivery ledger (`list`, `get`,
-`summary`) and the operator actions `retry`, `release`, and `discard`. The
-optional eligibility guard (`guard` on the connection) refuses new
-executions when the bound customer lacks the required subscription or
-balance; it is a provider-reported check, not a spending lock.

package/dist/approvals.d.ts

@@ -0,0 +1,15 @@
+import { type UIMessage } from "ai";
+import type { BlazingAgents } from "./client.ts";
+interface ApprovalTarget {
+    abortSignal?: AbortSignal;
+    agentId: string;
+    sessionId: string;
+}
+/**
+ * Records each approval response in the assistant message's last step and
+ * returns the continuation they decide, or `undefined` when there are none.
+ */
+export declare function decideApprovalResponses(client: Pick<BlazingAgents, "sessions">, { message, ...target }: ApprovalTarget & {
+    message: UIMessage;
+}): Promise<string | undefined>;
+export {};

package/dist/approvals.js

@@ -0,0 +1,20 @@
+import { isToolUIPart } from "ai";
+/**
+ * Records each approval response in the assistant message's last step and
+ * returns the continuation they decide, or `undefined` when there are none.
+ */
+export async function decideApprovalResponses(client, { message, ...target }) {
+    const lastStep = message.parts.findLastIndex((part) => part.type === "step-start");
+    let continuationId;
+    for (const part of message.parts.slice(lastStep + 1)) {
+        if (isToolUIPart(part) && part.state === "approval-responded") {
+            ({ continuationId } = await client.sessions.decideToolApproval({
+                ...target,
+                approvalId: part.approval.id,
+                approved: part.approval.approved,
+                reason: part.approval.reason,
+            }));
+        }
+    }
+    return continuationId;
+}

package/dist/chat-transport.js

@@ -1,4 +1,4 @@
-import { DefaultChatTransport, } from "ai";
+import { DefaultChatTransport, lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
 import { sessionIdSchema } from "./contracts/ids.js";
 /**
  * Adapts AI SDK chat requests to the Blazing Agents backend-relay shape and
@@ -31,7 +31,14 @@ export class BlazingAgentsChatTransport {
                 return response;
             },
             prepareSendMessagesRequest: ({ body, messageId, messages, trigger }) => {
-                const message = messages.findLast((candidate) => candidate.role === "user");
+                const approvals = messages.at(-1)?.role === "assistant" &&
+                    lastAssistantMessageIsCompleteWithApprovalResponses({ messages });
+                if (approvals && this.#sessionId === undefined) {
+                    throw new Error("Tool approval requires an existing Session.");
+                }
+                const message = approvals
+                    ? messages.at(-1)
+                    : messages.findLast((candidate) => candidate.role === "user");
                 if (!message) {
                     throw new Error("Chat submission requires a user message.");
                 }

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentClient, AgentsResource, ArtifactsResource, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatConnectionsResource, ChatDeliveriesResource, ChatInput, ChatResult, CompletionInput, CompletionResult, McpConnectionsResource, MemoriesResource, MerchantBindingsResource, MerchantConnectionResource, MerchantUsageEventsResource, ObjectInput, ObjectResult, PromptsResource, ProvidersResource, SessionsResource, TasksResource, TenantResource, UsageResource, WorkspacesResource } from "./types.ts";
+import type { AgentClient, AgentsResource, ArtifactsResource, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatConnectionsResource, ChatDeliveriesResource, ChatInput, ChatResult, CompletionInput, CompletionResult, McpConnectionsResource, MemoriesResource, MerchantBindingsResource, MerchantConnectionResource, MerchantUsageEventsResource, ObjectInput, ObjectResult, PromptsResource, ProvidersResource, ResumeChatInput, SessionsResource, TasksResource, TenantResource, UsageResource, UserClient, WorkspacesResource } from "./types.ts";
 export declare class BlazingAgents {
     private readonly config;
     readonly chatConnections: ChatConnectionsResource;
@@ -21,12 +21,19 @@ export declare class BlazingAgents {
     agent({ agentId }: {
         agentId: string;
     }): AgentClient;
+    /** Scope requests to one end user. IDs use printable ASCII, at most 256 characters, without leading or trailing spaces. */
+    forUser(userId: string): UserClient;
     /**
      * `POST /v1/agents/:agentId/sessions` (create, no `sessionId`) or
      * `POST /v1/agents/:agentId/sessions/:sessionId` (resume). Returns the
      * session id and a byte-compatible SSE relay for `useChat`.
      */
     chat(input: ChatInput): Promise<ChatResult>;
+    /**
+     * Reattaches function handlers after human tool approval and starts or
+     * joins the Session's continuation. Returns the continuation SSE relay.
+     */
+    resumeChat(input: ResumeChatInput): Promise<ChatResult>;
     /**
      * `POST /v1/agents/:agentId/generation` — stateless one-shot text
      * stream. Returns `textStream` + `await result.text` + `toResponse()`.

package/dist/client.js

@@ -1,4 +1,5 @@
-import { chat, completion, objectGeneration } from "./generation.js";
+import { z } from "zod";
+import { chat, completion, objectGeneration, resumeChat, } from "./generation.js";
 import { createAgentsResource } from "./resources/agents.js";
 import { createArtifactsResource } from "./resources/artifacts.js";
 import { createChatConnectionsResource } from "./resources/chat-connections.js";
@@ -18,6 +19,31 @@ import { createUsageResource } from "./resources/usage.js";
 import { createWorkspacesResource } from "./resources/workspaces.js";
 const DEFAULT_BASE_URL = "https://api.blazingagents.com";
 const TRAILING_SLASH_RE = /\/+$/;
+const scopedUserIdSchema = z
+    .string()
+    .max(256)
+    .regex(/^[\x21-\x7E](?:[\x20-\x7E]*[\x21-\x7E])?$/);
+function createUserClient(config) {
+    const usage = createUsageResource(config);
+    return {
+        agents: createAgentsResource(config),
+        sessions: createSessionsResource(config),
+        prompts: createPromptsResource(config),
+        tasks: createTasksResource(config),
+        artifacts: createArtifactsResource(config),
+        workspaces: createWorkspacesResource(config),
+        memories: createMemoriesResource(config),
+        usage: { get: usage.get, sessions: usage.sessions },
+        agent: ({ agentId }) => ({
+            skills: createAgentSkillsResource(config, agentId),
+        }),
+        chat: (input) => chat(config, input),
+        completion: (input) => completion(config, input),
+        object: (input) => objectGeneration(config, input),
+        resumeChat: (input) => resumeChat(config, input),
+        withOptions: (options) => createUserClient({ ...config, clientRequestId: options.clientRequestId }),
+    };
+}
 export class BlazingAgents {
     config;
     chatConnections;
@@ -66,6 +92,13 @@ export class BlazingAgents {
     agent({ agentId }) {
         return { skills: createAgentSkillsResource(this.config, agentId) };
     }
+    /** Scope requests to one end user. IDs use printable ASCII, at most 256 characters, without leading or trailing spaces. */
+    forUser(userId) {
+        return createUserClient({
+            ...this.config,
+            scopeUserId: scopedUserIdSchema.parse(userId),
+        });
+    }
     /**
      * `POST /v1/agents/:agentId/sessions` (create, no `sessionId`) or
      * `POST /v1/agents/:agentId/sessions/:sessionId` (resume). Returns the
@@ -74,6 +107,13 @@ export class BlazingAgents {
     chat(input) {
         return chat(this.config, input);
     }
+    /**
+     * Reattaches function handlers after human tool approval and starts or
+     * joins the Session's continuation. Returns the continuation SSE relay.
+     */
+    resumeChat(input) {
+        return resumeChat(this.config, input);
+    }
     /**
      * `POST /v1/agents/:agentId/generation` — stateless one-shot text
      * stream. Returns `textStream` + `await result.text` + `toResponse()`.

package/dist/contracts/api.d.ts

@@ -23,13 +23,15 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     agent_disabled: "agent_disabled";
     agent_mcp_connection_not_found: "agent_mcp_connection_not_found";
     agent_mcp_connections_invalid: "agent_mcp_connections_invalid";
-    agent_name_conflict: "agent_name_conflict";
     agent_version_not_found: "agent_version_not_found";
     api_key_limit_reached: "api_key_limit_reached";
     artifact_session_cap_reached: "artifact_session_cap_reached";
     chat_webhook_conflict: "chat_webhook_conflict";
     chat_webhook_registration_failed: "chat_webhook_registration_failed";
     checkout_evidence_mismatch: "checkout_evidence_mismatch";
+    forbidden: "forbidden";
+    function_call_conflict: "function_call_conflict";
+    idempotency_conflict: "idempotency_conflict";
     internal: "internal";
     invalid_cursor: "invalid_cursor";
     invalid_request: "invalid_request";
@@ -59,8 +61,6 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     model_not_found: "model_not_found";
     model_validation_unavailable: "model_validation_unavailable";
     not_found: "not_found";
-    prompt_limit_reached: "prompt_limit_reached";
-    prompt_name_conflict: "prompt_name_conflict";
     prompt_variable_missing: "prompt_variable_missing";
     prompt_variable_unknown: "prompt_variable_unknown";
     provider_historical_use: "provider_historical_use";
@@ -102,13 +102,15 @@ export declare const apiErrorSchema: z.ZodObject<{
         agent_disabled: "agent_disabled";
         agent_mcp_connection_not_found: "agent_mcp_connection_not_found";
         agent_mcp_connections_invalid: "agent_mcp_connections_invalid";
-        agent_name_conflict: "agent_name_conflict";
         agent_version_not_found: "agent_version_not_found";
         api_key_limit_reached: "api_key_limit_reached";
         artifact_session_cap_reached: "artifact_session_cap_reached";
         chat_webhook_conflict: "chat_webhook_conflict";
         chat_webhook_registration_failed: "chat_webhook_registration_failed";
         checkout_evidence_mismatch: "checkout_evidence_mismatch";
+        forbidden: "forbidden";
+        function_call_conflict: "function_call_conflict";
+        idempotency_conflict: "idempotency_conflict";
         internal: "internal";
         invalid_cursor: "invalid_cursor";
         invalid_request: "invalid_request";
@@ -138,8 +140,6 @@ export declare const apiErrorSchema: z.ZodObject<{
         model_not_found: "model_not_found";
         model_validation_unavailable: "model_validation_unavailable";
         not_found: "not_found";
-        prompt_limit_reached: "prompt_limit_reached";
-        prompt_name_conflict: "prompt_name_conflict";
         prompt_variable_missing: "prompt_variable_missing";
         prompt_variable_unknown: "prompt_variable_unknown";
         provider_historical_use: "provider_historical_use";
@@ -186,13 +186,15 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             agent_disabled: "agent_disabled";
             agent_mcp_connection_not_found: "agent_mcp_connection_not_found";
             agent_mcp_connections_invalid: "agent_mcp_connections_invalid";
-            agent_name_conflict: "agent_name_conflict";
             agent_version_not_found: "agent_version_not_found";
             api_key_limit_reached: "api_key_limit_reached";
             artifact_session_cap_reached: "artifact_session_cap_reached";
             chat_webhook_conflict: "chat_webhook_conflict";
             chat_webhook_registration_failed: "chat_webhook_registration_failed";
             checkout_evidence_mismatch: "checkout_evidence_mismatch";
+            forbidden: "forbidden";
+            function_call_conflict: "function_call_conflict";
+            idempotency_conflict: "idempotency_conflict";
             internal: "internal";
             invalid_cursor: "invalid_cursor";
             invalid_request: "invalid_request";
@@ -222,8 +224,6 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             model_not_found: "model_not_found";
             model_validation_unavailable: "model_validation_unavailable";
             not_found: "not_found";
-            prompt_limit_reached: "prompt_limit_reached";
-            prompt_name_conflict: "prompt_name_conflict";
             prompt_variable_missing: "prompt_variable_missing";
             prompt_variable_unknown: "prompt_variable_unknown";
             provider_historical_use: "provider_historical_use";

package/dist/contracts/api.js

@@ -18,8 +18,10 @@ export const apiErrorIssueSchema = z
  */
 export const apiErrorCodeSchema = z.enum([
     "invalid_request",
+    "idempotency_conflict",
     "validation_failed",
     "unauthorized",
+    "forbidden",
     "not_found",
     "quota_exceeded",
     "subscription_required",
@@ -33,14 +35,11 @@ export const apiErrorCodeSchema = z.enum([
     "agent_version_not_found",
     "agent_mcp_connection_not_found",
     "agent_mcp_connections_invalid",
-    "agent_name_conflict",
     "provider_required",
     "api_key_limit_reached",
     "artifact_session_cap_reached",
     "invalid_cursor",
     "message_not_found",
-    "prompt_limit_reached",
-    "prompt_name_conflict",
     "prompt_variable_missing",
     "prompt_variable_unknown",
     "provider_in_use",
@@ -66,6 +65,7 @@ export const apiErrorCodeSchema = z.enum([
     "session_version_mismatch",
     "tool_approval_continuation_not_found",
     "tool_approval_decision_conflict",
+    "function_call_conflict",
     "skill_invalid_archive",
     "skill_invalid_markdown",
     "skill_limit_reached",

package/dist/contracts/entities/agent-approval.d.ts

@@ -28,6 +28,37 @@ export declare const toolReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     connectionId: z.ZodString;
     name: z.ZodString;
 }, z.core.$strict>], "type">;
+/**
+ * Identifies the tool behind one execution or approval record. Caller-local
+ * functions appear here for display and audit only; approval policies keep
+ * `toolReferenceSchema`, so function names never become Agent configuration.
+ */
+export declare const toolExecutionReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"builtin">;
+    name: z.ZodEnum<{
+        activate_skill: "activate_skill";
+        bash: "bash";
+        delete_memory: "delete_memory";
+        edit: "edit";
+        get_memory: "get_memory";
+        glob: "glob";
+        grep: "grep";
+        publish_artifacts: "publish_artifacts";
+        read: "read";
+        save_memory: "save_memory";
+        search_memories: "search_memories";
+        update_memory: "update_memory";
+        write: "write";
+        write_todos: "write_todos";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"mcp">;
+    connectionId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    name: z.ZodString;
+}, z.core.$strict>], "type">;
 export declare const approvalPolicySchema: z.ZodObject<{
     default: z.ZodEnum<{
         auto: "auto";
@@ -69,4 +100,5 @@ export declare const approvalPolicySchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ApprovalPolicy = z.infer<typeof approvalPolicySchema>;
 export type ToolReference = z.infer<typeof toolReferenceSchema>;
+export type ToolExecutionReference = z.infer<typeof toolExecutionReferenceSchema>;
 export type ApprovalDecision = z.infer<typeof approvalDecisionSchema>;

package/dist/contracts/entities/agent-approval.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { mcpConnectionIdSchema } from "../ids.js";
-import { AGENT_TOOL_CATALOG } from "./agent-tools.js";
+import { AGENT_TOOL_CATALOG, chatFunctionNameSchema } from "./agent-tools.js";
 export const approvalDecisionSchema = z.enum([
     "full",
     "deny",
@@ -25,6 +25,17 @@ export const toolReferenceSchema = z.discriminatedUnion("type", [
     })
         .strict(),
 ]);
+/**
+ * Identifies the tool behind one execution or approval record. Caller-local
+ * functions appear here for display and audit only; approval policies keep
+ * `toolReferenceSchema`, so function names never become Agent configuration.
+ */
+export const toolExecutionReferenceSchema = z.discriminatedUnion("type", [
+    ...toolReferenceSchema.options,
+    z
+        .object({ type: z.literal("function"), name: chatFunctionNameSchema })
+        .strict(),
+]);
 export const approvalPolicySchema = z
     .object({
     default: approvalDecisionSchema,

package/dist/contracts/entities/agent-tools.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /** Tool groups an Agent can attach. File operations use its durable Workspace. */
 export declare const agentToolGroupIds: readonly ["workspace", "write_todos", "memory"];
 export type AgentToolGroupId = (typeof agentToolGroupIds)[number];
@@ -24,3 +25,8 @@ export declare const AGENT_TOOL_CATALOG: readonly [{
     readonly tools: readonly ["save_memory", "get_memory", "search_memories", "update_memory", "delete_memory"];
 }];
 export declare function expandToolGroups(ids: Iterable<string>): Set<string>;
+/**
+ * A model-facing tool name. Built-in tool names and the `mcp__` prefix used
+ * for MCP tools are reserved so a caller function never shadows them.
+ */
+export declare const chatFunctionNameSchema: z.ZodString;

package/dist/contracts/entities/agent-tools.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /** Tool groups an Agent can attach. File operations use its durable Workspace. */
 export const agentToolGroupIds = [
     "workspace",
@@ -50,3 +51,15 @@ export function expandToolGroups(ids) {
     }
     return result;
 }
+const RESERVED_CHAT_FUNCTION_NAMES = new Set([
+    ...AGENT_TOOL_CATALOG.flatMap((group) => group.tools),
+    "activate_skill",
+]);
+/**
+ * A model-facing tool name. Built-in tool names and the `mcp__` prefix used
+ * for MCP tools are reserved so a caller function never shadows them.
+ */
+export const chatFunctionNameSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/)
+    .refine((name) => !(RESERVED_CHAT_FUNCTION_NAMES.has(name) || name.startsWith("mcp__")), { message: "Function name is reserved for a built-in or MCP tool." });

package/dist/contracts/entities/agents.d.ts

@@ -121,7 +121,7 @@ export declare const agentSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export declare const agentsResponseSchema: z.ZodObject<{
-    agents: z.ZodArray<z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
         approvalInChat: z.ZodDefault<z.ZodObject<{
             default: z.ZodEnum<{
                 auto: "auto";
@@ -228,6 +228,7 @@ export declare const agentsResponseSchema: z.ZodObject<{
             disabled: "disabled";
         }>;
     }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const agentResponseSchema: z.ZodObject<{
     approvalInChat: z.ZodDefault<z.ZodObject<{
@@ -337,6 +338,8 @@ export declare const agentResponseSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export declare const agentsListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userId: z.ZodOptional<z.ZodString>;
     workspaceId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;