@tencent-ai/agent-sdk 0.3.252 → 0.3.253

package/cli/dist-server/types/node/agent/openai-agents-types.d.ts

@@ -26,8 +26,8 @@
  * 未 preload 直接用 `new Agent(...)` 会 fail-loud（TypeError: undefined is not
  * a constructor）——刻意设计，静默 sync require 回退会让整个 lazy 化归零。
  */
-import type { Agent as AgentTypeCtor, AgentConfiguration, AgentInputItem as OriginalAgentInputItem, AgentOptions, AssistantMessageItem as OriginalAssistantMessageItem, ComputerCallResultItem as OriginalComputerCallResultItem, ComputerUseCallItem as OriginalComputerUseCallItem, FunctionCallItem as OriginalFunctionCallItem, FunctionCallResultItem as OriginalFunctionCallResultItem, FunctionTool as FunctionToolTypeCtor, Handoff as HandoffTypeCtor, handoff as handoffFn, HostedToolCallItem as OriginalHostedToolCallItem, Model as ModelType, ModelProvider as ModelProviderType, NonStreamRunOptions, OpenAIChatCompletionsModel as OpenAIChatCompletionsModelTypeCtor, ReasoningItem as OriginalReasoningItem, ResponseStreamEvent, RunConfig, RunContext as RunContextTypeCtor, RunItem, Runner as RunnerTypeCtor, RunResult as RunResultTypeCtor, RunState as RunStateTypeCtor, RunToolApprovalItem as RunToolApprovalItemTypeCtor, StreamedRunResult as RawStreamedRunResultTypeCtor, StreamRunOptions, SystemMessageItem as OriginalSystemMessageItem, Tool as OpenAIToolType, tool as toolTypeCtor, ToolExecuteArgument, UnknownItem as OriginalUnknownItem, Usage as UsageTypeCtor, UserMessageItem as OriginalUserMessageItem, addTraceProcessor as addTraceProcessorFn, setTraceProcessors as setTraceProcessorsFn } from '@openai/agents';
-import type { AgentOutputType, MaxTurnsExceededError as MaxTurnsExceededErrorTypeCtor, ModelBehaviorError as ModelBehaviorErrorTypeCtor, getAllMcpTools as getAllMcpToolsFn } from '@openai/agents-core';
+import type { addTraceProcessor as addTraceProcessorFn, Agent as AgentTypeCtor, AgentConfiguration, AgentInputItem as OriginalAgentInputItem, AgentOptions, AssistantMessageItem as OriginalAssistantMessageItem, ComputerCallResultItem as OriginalComputerCallResultItem, ComputerUseCallItem as OriginalComputerUseCallItem, FunctionCallItem as OriginalFunctionCallItem, FunctionCallResultItem as OriginalFunctionCallResultItem, FunctionTool as FunctionToolTypeCtor, Handoff as HandoffTypeCtor, handoff as handoffFn, HostedToolCallItem as OriginalHostedToolCallItem, Model as ModelType, ModelProvider as ModelProviderType, NonStreamRunOptions, OpenAIChatCompletionsModel as OpenAIChatCompletionsModelTypeCtor, ReasoningItem as OriginalReasoningItem, ResponseStreamEvent, RunConfig, RunContext as RunContextTypeCtor, RunItem, Runner as RunnerTypeCtor, RunResult as RunResultTypeCtor, RunState as RunStateTypeCtor, RunToolApprovalItem as RunToolApprovalItemTypeCtor, setTraceProcessors as setTraceProcessorsFn, StreamedRunResult as RawStreamedRunResultTypeCtor, StreamRunOptions, SystemMessageItem as OriginalSystemMessageItem, Tool as OpenAIToolType, tool as toolTypeCtor, ToolExecuteArgument, UnknownItem as OriginalUnknownItem, Usage as UsageTypeCtor, UserMessageItem as OriginalUserMessageItem } from '@openai/agents';
+import type { AgentOutputType, getAllMcpTools as getAllMcpToolsFn, MaxTurnsExceededError as MaxTurnsExceededErrorTypeCtor, ModelBehaviorError as ModelBehaviorErrorTypeCtor } from '@openai/agents-core';
 import type { TextOutput, UnknownContext, UserContent } from '@openai/agents-core/types';
 import { FileHistorySnapshotItem, ResendForkNoticeItem } from './custom-input-item-types';
 export * from './custom-input-item-types';
@@ -58,16 +58,16 @@ export declare let tool: typeof toolTypeCtor;
 export declare let Handoff: typeof HandoffTypeCtor;
 export declare let handoff: typeof handoffFn;
 export declare let OpenAIChatCompletionsModel: typeof OpenAIChatCompletionsModelTypeCtor;
-export declare let addTraceProcessor: typeof addTraceProcessorFn;
-export declare let setTraceProcessors: typeof setTraceProcessorsFn;
 export declare let getAllMcpTools: typeof getAllMcpToolsFn;
 export declare let MaxTurnsExceededError: typeof MaxTurnsExceededErrorTypeCtor;
 export declare let ModelBehaviorError: typeof ModelBehaviorErrorTypeCtor;
+export declare function addTraceProcessor(processor: Parameters<typeof addTraceProcessorFn>[0]): void;
+export declare function setTraceProcessors(processors: Parameters<typeof setTraceProcessorsFn>[0]): void;
 /**
  * 拉起 `@openai/agents` + `@openai/agents-core` lazy chunk 并 assign runtime 值。
  * 幂等；并发 caller 复用同一次加载 promise。
  */
-export declare function preloadOpenaiAgentsTypes(): Promise<void>;
+export declare function preloadOpenaiAgentsTypes(): Promise<typeof import('@openai/agents')>;
 /** 等价 `err instanceof MaxTurnsExceededError`；无需 preload 即可用。 */
 export declare function isMaxTurnsExceededError(err: unknown): boolean;
 /** 等价 `err instanceof ModelBehaviorError`；无需 preload 即可用。 */

package/cli/dist-server/types/node/mcp/mcp-sdk-values.d.ts

@@ -22,7 +22,7 @@
  * `mcp-server-override.connect`，都在 activate 之后 MCP config resolve 完成时才走。
  * 在 `McpReadyService.doInit`（activate coordinator 触发点）里 preload 一次即可。
  */
-import type { OAuthClientProvider, OAuthDiscoveryState, auth as authFn, discoverAuthorizationServerMetadata as discoverAuthorizationServerMetadataFn, discoverOAuthProtectedResourceMetadata as discoverOAuthProtectedResourceMetadataFn, discoverOAuthServerInfo as discoverOAuthServerInfoFn, exchangeAuthorization as exchangeAuthorizationFn, extractResourceMetadataUrl as extractResourceMetadataUrlFn } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { auth as authFn, discoverAuthorizationServerMetadata as discoverAuthorizationServerMetadataFn, discoverOAuthProtectedResourceMetadata as discoverOAuthProtectedResourceMetadataFn, discoverOAuthServerInfo as discoverOAuthServerInfoFn, exchangeAuthorization as exchangeAuthorizationFn, extractResourceMetadataUrl as extractResourceMetadataUrlFn, OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
 import type { Client as ClientTypeCtor } from '@modelcontextprotocol/sdk/client/index.js';
 import type { SSEClientTransport as SSEClientTransportTypeCtor, SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
 import type { StdioClientTransport as StdioClientTransportTypeCtor, StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';

package/cli/dist-server/types/node/model/model-provider.d.ts

@@ -1,7 +1,7 @@
 import { RestOperations } from '@celljs/http';
 import { AuthenticationManager } from '@genie/authentication';
 import { ClientInfoProvider, LanguageModel, ProductManager } from '@genie/product';
-import { Logger } from '@genie/telemetry';
+import { Logger, TraceService } from '@genie/telemetry';
 import { OpenAI } from 'openai';
 import { AgentManager } from '../agent';
 import { GalileoTimingHook } from '../galileo';
@@ -93,6 +93,7 @@ export declare class ModelProviderImpl implements ModelProvider {
     protected readonly clientInfoProvider: ClientInfoProvider;
     protected readonly agentManager: AgentManager;
     protected readonly logger: Logger;
+    protected readonly traceService?: TraceService;
     protected readonly defaultInputItemProcessor: DefaultInputItemProcessor;
     protected readonly functionCallResultAgentInputItemProcessor: FunctionCallResultAgentInputItemProcessor;
     protected readonly modelErrorAnalyzer: ModelErrorAnalyzer;
@@ -273,6 +274,7 @@ export declare class ModelProviderImpl implements ModelProvider {
      * AbortSignal 已触发时一律不重试（尊重取消语义）。env 运行时 live 读（prewarm 契约）。
      */
     private requestWithConnectionRetry;
+    private getModelTracer;
     /**
      * MVP 验证：agent-cli 模型请求最终走 OpenAI SDK 的自定义 fetch adapter，
      * 不一定会被 Galileo SDK 的 global fetch/http instrumentation 捕获。

package/cli/dist-server/types/node/tools/a2a-get-task-tool.d.ts

@@ -19,26 +19,37 @@ declare const A2AGetTaskParameters: z.ZodObject<{
     task_id: string;
 }>;
 export declare const ENV_POLL_INTERVAL_MS = "CODEBUDDY_A2A_POLL_INTERVAL_MS";
-export declare const ENV_POLL_BACKOFF_MULTIPLIER = "CODEBUDDY_A2A_POLL_BACKOFF_MULTIPLIER";
-export declare const ENV_POLL_MAX_INTERVAL_MS = "CODEBUDDY_A2A_POLL_MAX_INTERVAL_MS";
-export declare const ENV_POLL_MAX_ATTEMPTS = "CODEBUDDY_A2A_POLL_MAX_ATTEMPTS";
 export declare const ENV_POLL_MAX_DURATION_MS = "CODEBUDDY_A2A_POLL_MAX_DURATION_MS";
 export interface A2APollPolicy {
-    /** Initial poll interval, ms. Default 2s. */
-    initialIntervalMs: number;
-    /** Exponential backoff multiplier applied after each poll. Default 1.5x. */
-    backoffMultiplier: number;
-    /** Interval cap the backoff schedule never exceeds. Default 30s. */
-    maxIntervalMs: number;
-    /** Hard cap on poll attempts — a secondary, independent circuit breaker from `maxDurationMs`. Default 60. */
-    maxAttempts: number;
-    /** Overall wall-clock budget for the whole loop, ms. Default 15 minutes. */
+    /**
+     * Constant gap between polls, ms. Default 500ms.
+     *
+     * Flat rather than exponentially backed off. Backoff optimizes for the
+     * long tail, but the tail is exactly where it hurts: it used to stretch
+     * to a 30s gap, so a task finishing at second 31 was reported up to 30
+     * seconds late, and the user watching the progress line saw a stall. A
+     * remote task the user is actively waiting on is worth one cheap request
+     * every half second.
+     */
+    intervalMs: number;
+    /**
+     * Wall-clock budget for the whole loop, ms. Default 30 minutes.
+     *
+     * A HARD cap: when it runs out the remote task is canceled, so this is
+     * the longest a single outbound task may run — not merely the longest a
+     * single call waits.
+     */
     maxDurationMs: number;
 }
 /**
  * Resolve the effective poll policy, applying any env overrides on top of
  * `DEFAULT_POLL_POLICY`. Read fresh on every `execute()` call — not cached
  * — so a test/host can change the env between calls.
+ *
+ * Only these two knobs are exposed. The retry schedule for a FAILED request
+ * (see a2a-poll-retry.ts) is fixed, because the cadence and the budget are
+ * the only two a host has a reason to tune and every additional dial is one
+ * more way to configure the loop into a request storm.
  */
 export declare function resolvePollPolicy(): A2APollPolicy;
 /** Exported so `A2ASendMessageTool` can classify its own (single, non-looping) result the same way — see that tool's artifact-download integration. */
@@ -54,17 +65,28 @@ export declare function __resetUserStoppedTasksForTest(): void;
  * Every non-terminal status — including `input-required`/`auth-required` —
  * is relayed (A.2's live-progress mechanism, reusing the foreground Bash
  * tool's `session.inputSubject.next({status: 'in_progress', ...})` pattern)
- * and polled straight through with exponential backoff (A.3), never treated
- * as a stop condition (A.5). Only the 4 true terminal states
- * (`completed`/`failed`/`canceled`/`rejected`) or one of the two independent
- * circuit breakers (`maxAttempts`/`maxDurationMs`, both env-overridable — see
- * `resolvePollPolicy()`) stop the loop.
+ * and polled straight through at a fixed interval (A.3), never treated as a
+ * stop condition (A.5).
+ *
+ * Three things stop the loop, and only one of them is a plain success:
+ *
+ * - one of the 4 terminal states (`completed`/`failed`/`canceled`/`rejected`);
+ * - the wall-clock budget running out;
+ * - `tasks/get` failing in a way that survives the retry schedule.
+ *
+ * The last two both END the remote task: the loop issues `tasks/cancel` and
+ * reports what that cancel actually did. This is a deliberate reversal of the
+ * older "give up for now, let the model re-poll" contract, which left a
+ * remote task running with nobody watching it whenever the model chose not to
+ * call back. The cost is that the budget is now a ceiling on the TASK, not
+ * just on the call — a task that needs longer than `maxDurationMs` cannot
+ * finish, and the host has to raise the budget for it.
  *
  * **One exception, added in issue #107183: approval interrupts.** When a poll
  * observes a `snapshot.approval` payload (an out-of-band approval the remote
  * agent is waiting on — see `A2aTaskSnapshot.approval`), relaying opaque
- * `(N pending approval)` text and polling on for 15 minutes gives the user no
- * way to act. So the loop PAUSES and raises a real ACP `elicitation/create`
+ * `(N pending approval)` text and polling on until the budget runs out gives
+ * the user no way to act. So the loop PAUSES and raises an ACP `elicitation/create`
  * card carrying the approval tokens, then resumes or stops per the answer:
  *
  * - `accept` — resume polling and do nothing else. The host delivers the
@@ -119,7 +141,39 @@ export declare class A2AGetTaskTool extends BaseTool implements Tool {
     execute(input: z.infer<typeof A2AGetTaskParameters>, context: RunContext<Session>, details?: {
         toolCall: FunctionCallItem;
     }): Promise<ToolResult>;
-    private pollOnce;
+    /**
+     * One logical poll: a `tasks/get`, plus up to
+     * {@link POLL_RETRY_MAX_ATTEMPTS} retries when the failure looks
+     * transient.
+     *
+     * Retrying at all is the point. Before this, a single hiccup — a 502 from
+     * a load balancer mid-deploy, a reset socket — ended a poll the user had
+     * been waiting minutes for. What is NOT retried is a 400-409: those say
+     * the request itself is wrong (bad task id, no permission), and repeating
+     * it five times just delays telling the model something it needs to act
+     * on. See `classifyPollFailure` for where that line is drawn and why it
+     * is not simply "all of 4xx".
+     *
+     * Three ways out:
+     * - a snapshot, on the first try or a later one;
+     * - a THROWN `ToolExecutionError`, for a non-retryable failure or a user
+     *   abort — the model gets the error, the task is left alone;
+     * - `give-up`, when the retries (or the budget) ran out. The caller ends
+     *   the remote task and reports; this is not an exception because it is a
+     *   reportable outcome, not a broken call.
+     */
+    private pollWithRetry;
+    private abortedError;
+    /**
+     * Error text for a failure the model has to act on itself.
+     *
+     * Leads with the HTTP status because that is what tells a 404 (wrong task
+     * id — the model may have one from an earlier turn) apart from a 403
+     * (this agent is not allowed here — retrying will never help), and
+     * carries the remote's own response body, which is where an agent
+     * normally puts the part a human can act on.
+     */
+    private formatRequestFailure;
     /**
      * A.2's live-progress relay — the SAME `session.inputSubject.next({...})`
      * shape the foreground Bash tool uses for its own streaming updates
@@ -165,24 +219,44 @@ export declare class A2AGetTaskTool extends BaseTool implements Tool {
     /**
      * Model-facing result after a user ended a task from an approval card.
      *
-     * Three things have to be in here, and the first is the one that is easy
-     * to get wrong: this tool's own `description` tells the model in
-     * MUST-level wording to immediately re-poll any non-final result, so the
-     * text has to say plainly that polling is over. The other two are what
-     * was refused (the model cannot pick a next step if it only knows "an
-     * approval was declined") and what we actually did to the remote task.
+     * Written as named sections — what was shown, what happened, and the
+     * host's reason — rather than one prose paragraph, because the single
+     * line that has to win was getting buried mid-sentence: this tool's own
+     * `description` tells the model in MUST-level wording to immediately
+     * re-poll any non-final result, so the text has to say plainly that
+     * polling is over.
+     *
+     * Only counter-intuitive instructions are spelled out. Telling the user
+     * the action did not happen is what a model does anyway; not re-polling,
+     * closing an unconfirmed cancel out with `A2ACancelTask`, and reporting a
+     * real terminal state instead of the refusal are the three it would
+     * otherwise get wrong.
      *
      * When the cancel revealed the task was already terminal — commonly
      * because the approval was granted through the approving system's own UI
      * while our card sat open — the REAL state is reported through the
      * existing `formatTerminalContent()`, so a completed task is never
      * reported as a refusal.
+     *
+     * No agent id anywhere: it is the registry's routing key and is not
+     * guaranteed to match the card's display name (see `A2aRegisteredAgent`),
+     * while `taskId` alone already identifies the task uniquely.
      */
     private buildApprovalStopResult;
+    /** Blank line between sections, reasons always last — see {@link appendApprovalResponseNotes}. */
+    private composeSections;
     /**
-     * Add host-supplied reasons to the model result without granting them
-     * instruction authority. JSON string encoding keeps arbitrary newlines and
-     * delimiter-looking text inside one explicit data value.
+     * Append host-supplied reasons as the LAST section of the result.
+     *
+     * The JSON encoding is the actual guard, not formatting: it collapses
+     * newlines and heading-looking text into a single string literal, so a
+     * reason cannot forge a section of its own. Keeping it last means no
+     * instruction ever follows client-controlled text.
+     *
+     * A lone reason needs no action label — the section above it already said
+     * what the user did. Several reasons only happen when one call raised more
+     * than one card (accepting one approval, then declining another), and
+     * there the labels are what keep two opposite answers apart.
      */
     private appendApprovalResponseNotes;
     /**
@@ -201,11 +275,42 @@ export declare class A2AGetTaskTool extends BaseTool implements Tool {
      */
     private formatTerminalContent;
     /**
-     * Fallback result when a circuit breaker (not a terminal status) stops
-     * the loop. Per A.5: surfaces the last observed status/clarification —
-     * useful context even though it wasn't treated as a stop condition, the
-     * loop stopped because of the budget, not because of an interrupt.
+     * The ordinary end of a poll: the task reached a terminal state, so wait
+     * out its artifact downloads and hand the model the result.
+     *
+     * Shared with the stop path below, which lands here whenever a cancel
+     * discovers the task had already finished. That sharing is the point —
+     * a task that completed WITH attachments in the second before we tried to
+     * cancel it must not lose them to a different, artifact-unaware code
+     * path.
+     *
+     * Assumes its snapshot's downloads have already been kicked off; both
+     * callers do that, the loop on every tick and the stop path for the
+     * snapshot the cancel read back.
+     */
+    private buildTerminalResult;
+    /**
+     * End the remote task and tell the model what that actually did.
+     *
+     * Reached when the loop gives up on a task that never finished — the
+     * budget ran out, or `tasks/get` kept failing. Both used to return "still
+     * running, call me again", which read fine but left a real task running
+     * on the remote agent for as long as it liked whenever the model decided
+     * not to call back. Ending it here means the ceiling is enforced rather
+     * than merely reported.
+     *
+     * The cancel is what produces the text, not a guess made before it:
+     *
+     * - `already-terminal` — the task crossed the finish line while we were
+     *   canceling it, so there is nothing to narrate. It goes back through
+     *   the normal terminal path and the model sees an ordinary result,
+     *   artifacts and all.
+     * - `canceled` — say so, and name the state the remote reported rather
+     *   than assuming CANCELED; nothing in the spec pins `tasks/cancel` to
+     *   one value.
+     * - `unknown` — we could not confirm anything, so the model is told the
+     *   task may still be running and pointed at `A2ACancelTask`.
      */
-    private buildBudgetExceededResult;
+    private buildPollStoppedResult;
 }
 export {};

package/cli/dist-server/types/node/tools/a2a-poll-retry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Retry policy for a FAILED `tasks/get` REQUEST — distinct from
+ * `A2APollPolicy`, which governs the cadence of SUCCESSFUL polls. A request
+ * that never produced a task snapshot is retried on this schedule; a request
+ * that did is subject to the poll interval instead.
+ *
+ * Fixed rather than env-overridable: the poll interval and the overall budget
+ * are the two knobs a host has a legitimate reason to tune, and every extra
+ * one is a way to misconfigure the loop into a request storm.
+ */
+export declare const POLL_RETRY_MAX_ATTEMPTS = 5;
+export declare const POLL_RETRY_BASE_INTERVAL_MS = 1000;
+export declare const POLL_RETRY_BACKOFF_MULTIPLIER = 1.5;
+export interface PollFailureClassification {
+    /**
+     * The HTTP status behind this failure, when one could be established.
+     * Absent for transport failures that never got a response at all (DNS,
+     * connection reset, the client's own timeout) — deliberately not defaulted
+     * to 500, so the model is never told a status the wire did not carry.
+     */
+    httpStatus?: number;
+    /** Whether the poll loop should retry rather than give up. */
+    retryable: boolean;
+    /** The SDK's error text, verbatim. */
+    message: string;
+    /**
+     * What the remote actually said: the `Response:` tail of the SDK's HTTP
+     * error text, or a JSON-RPC error's structured `data`. Absent when the
+     * failure produced no body.
+     */
+    responseBody?: string;
+}
+/**
+ * Decide whether a failed `tasks/get` request is worth retrying, and pull out
+ * the detail the model needs either way.
+ *
+ * Knows nothing about aborts on purpose. A user cancel and the client's own
+ * 120s request timeout reach this function as the SAME error text (see
+ * `A2aClientService.withAbortAndClient`), so only the caller — which can read
+ * `session.abortSignal` — can tell them apart. This classifies the timeout
+ * reading of that message (retryable) and leaves the cancel reading to the
+ * poll loop.
+ */
+export declare function classifyPollFailure(err: unknown): PollFailureClassification;
+/** Wait before the `retryIndex`-th (0-based) retry: 1s, 1.5s, 2.25s, 3.375s, 5.0625s. */
+export declare function pollRetryDelayMs(retryIndex: number): number;

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-ai/codebuddy-code",
-  "version": "2.144.0",
+  "version": "2.145.0",
   "description": "Use CodeBuddy, Tencent's AI assistant, right from your terminal. CodeBuddy can understand your codebase, edit files, run terminal commands, and handle entire workflows for you.",
   "main": "lib/node/index.js",
   "typings": "lib/node/index.d.ts",

package/cli/product.cloudhosted.json

@@ -822,6 +822,6 @@
     "SelectImage": true,
     "SkipToolCallSupportCheck": true
   },
-  "commit": "8d037fece0be1978272cf60f906f7bd144e32408",
-  "date": "2026-09-04T14:07:37.499Z"
+  "commit": "6582f0c18fc69b31f97ca6fc98673eaf2a0666a1",
+  "date": "2026-09-05T05:39:52.463Z"
 }

package/cli/product.internal.json

@@ -832,6 +832,6 @@
       }
     }
   },
-  "commit": "8d037fece0be1978272cf60f906f7bd144e32408",
-  "date": "2026-09-04T14:07:37.420Z"
+  "commit": "6582f0c18fc69b31f97ca6fc98673eaf2a0666a1",
+  "date": "2026-09-05T05:39:52.458Z"
 }

package/cli/product.ioa.json

@@ -1325,6 +1325,6 @@
       }
     }
   },
-  "commit": "8d037fece0be1978272cf60f906f7bd144e32408",
-  "date": "2026-09-04T14:07:37.426Z"
+  "commit": "6582f0c18fc69b31f97ca6fc98673eaf2a0666a1",
+  "date": "2026-09-05T05:39:52.459Z"
 }

package/cli/product.json

@@ -1245,11 +1245,11 @@
     },
     {
       "name": "tool-a2asendmessage-description",
-      "template": "Send a message to one outbound A2A (Agent2Agent) agent authorized for this conversation.\n\nParameters:\n- `agent_name` (required): the target agent's name, exactly as returned by A2AGetAgentCard (the Agent Card `name`), or from an explicit @Agent mention.\n- `message` (required): a concise, self-contained task or question. Do not paste the whole conversation — state the goal and only the context the agent actually needs (the agent has no visibility into this conversation otherwise).\n- `skill_id` (optional): route directly to one declared skill, for @Agent.Skill-style precise dispatch. Only effective when A2AGetAgentCard reported `supports_skill_routing: true` for that agent; otherwise this is ignored.\n- `attachments` (optional): a list of files to attach to the message, each referenced by a fetchable `url` (plus optional `filename` and `media_type`). Each is sent to the agent as a standard A2A file part. The `url` must already be reachable by the remote agent — this tool sends it as-is and does NOT upload, host, or transform the file. Use this when you already have a URL for a file you want the agent to work on; obtain that URL through whatever mechanism your environment provides.\n\nThis call is NOT synchronous: it returns immediately with whatever single reply the agent gave, and does not wait for the task to finish. Check the returned status: only completed/failed/canceled/rejected are final. For ANY other status — working, submitted, input-required, or auth-required — you MUST immediately call A2AGetTask with the returned task_id, in the same turn, before doing anything else with this task. Do not wait, and do not ask the user for permission first.\n\nauth-required and input-required are NOT a signal to stop and hand off to the user by themselves — calling A2AGetTask to check status is just reading state, not performing a login or filling credentials on the user's behalf, so it does not conflict with any policy against automating logins. A2AGetTask polls automatically with backoff, relays the agent's own request (e.g. \"please sign in\", a clarifying question) to the user exactly once, and keeps waiting for the remote task to advance — it will surface the eventual outcome once the user (or the agent) resolves whatever it was waiting on.\n\nBehavior notes:\n- Calling the same `agent_id` (and `skill_id`, if used) again in a later turn continues the same conversation with that agent automatically — you don't need to restate prior context.\n- To message multiple agents in one turn, call this tool once per agent as parallel tool calls — one agent failing does not affect the others.\n- Any files or links the agent produced are returned as part of the result text.\n- Not available inside a sub-agent or team-member session — only the main conversation can call outbound A2A agents.\n"
+      "template": "Send a message to one outbound A2A (Agent2Agent) agent authorized for this conversation.\n\nParameters:\n- `agent_name` (required): the target agent's name, exactly as returned by A2AGetAgentCard (the Agent Card `name`), or from an explicit @Agent mention.\n- `message` (required): a concise, self-contained task or question. Do not paste the whole conversation — state the goal and only the context the agent actually needs (the agent has no visibility into this conversation otherwise).\n- `skill_id` (optional): route directly to one declared skill, for @Agent.Skill-style precise dispatch. Only effective when A2AGetAgentCard reported `supports_skill_routing: true` for that agent; otherwise this is ignored.\n- `attachments` (optional): a list of files to attach to the message, each referenced by a fetchable `url` (plus optional `filename` and `media_type`). Each is sent to the agent as a standard A2A file part. The `url` must already be reachable by the remote agent — this tool sends it as-is and does NOT upload, host, or transform the file. Use this when you already have a URL for a file you want the agent to work on; obtain that URL through whatever mechanism your environment provides.\n\nThis call is NOT synchronous: it returns immediately with whatever single reply the agent gave, and does not wait for the task to finish. Check the returned status: only completed/failed/canceled/rejected are final. For ANY other status — working, submitted, input-required, or auth-required — you MUST immediately call A2AGetTask with the returned task_id, in the same turn, before doing anything else with this task. Do not wait, and do not ask the user for permission first.\n\nauth-required and input-required are NOT a signal to stop and hand off to the user by themselves — calling A2AGetTask to check status is just reading state, not performing a login or filling credentials on the user's behalf, so it does not conflict with any policy against automating logins. A2AGetTask polls automatically, relays the agent's own request (e.g. \"please sign in\", a clarifying question) to the user exactly once, and keeps waiting for the remote task to advance — it will surface the eventual outcome once the user (or the agent) resolves whatever it was waiting on.\n\nBehavior notes:\n- Calling the same `agent_id` (and `skill_id`, if used) again in a later turn continues the same conversation with that agent automatically — you don't need to restate prior context.\n- To message multiple agents in one turn, call this tool once per agent as parallel tool calls — one agent failing does not affect the others.\n- Any files or links the agent produced are returned as part of the result text.\n- Not available inside a sub-agent or team-member session — only the main conversation can call outbound A2A agents.\n"
     },
     {
       "name": "tool-a2agettask-description",
-      "template": "Wait for a previously created outbound A2A task to finish, polling automatically.\n\nParameters:\n- `agent_name` (required): the same agent name passed to the original A2ASendMessage call.\n- `task_id` (required): the taskId from a prior A2ASendMessage or A2AGetTask result.\n\nThis call polls the remote task's real, current state with backoff, showing live progress as it goes, up to a bounded time/attempt limit. It returns once the task reaches a final state (completed/failed/canceled/rejected), or a \"still running\" result if the bound is hit first — if you get \"still running\", immediately call A2AGetTask again with the same task_id to keep waiting; do not give up after one bounded call.\n\nIf the task is waiting on external input or auth (input-required/auth-required), that request is relayed to the user once and polling continues with backoff — the next call/round of polling reflects the task's real state at that later point in time, not a repeat of what you already saw. Checking status this way is just reading state, not performing a login or filling credentials on the user's behalf, so calling this while the task is waiting on the user to complete a login/approval step out of band does not conflict with any policy against automating logins.\n\nNot available inside a sub-agent or team-member session — only the main conversation can query outbound A2A tasks.\n"
+      "template": "Wait for a previously created outbound A2A task to finish, polling automatically.\n\nParameters:\n- `agent_name` (required): the same agent name passed to the original A2ASendMessage call.\n- `task_id` (required): the taskId from a prior A2ASendMessage or A2AGetTask result.\n\nThis call polls the remote task's real, current state at a steady interval, showing live progress as it goes, and returns once the task reaches a final state (completed/failed/canceled/rejected).\n\nThis is the only wait the task gets. If it runs past the time limit, or the remote agent stops answering, the task is canceled and this returns telling you exactly that. Whatever this returns is therefore final: never call A2AGetTask again with the same task_id. If the work is still needed, start it over with A2ASendMessage.\n\nIf the task is waiting on external input or auth (input-required/auth-required), that request is relayed to the user once and polling continues — this call keeps waiting for the task to advance rather than handing back a stale copy of what you already saw. Checking status this way is just reading state, not performing a login or filling credentials on the user's behalf, so calling this while the task is waiting on the user to complete a login/approval step out of band does not conflict with any policy against automating logins.\n\nNot available inside a sub-agent or team-member session — only the main conversation can query outbound A2A tasks.\n"
     },
     {
       "name": "tool-a2acanceltask-description",
@@ -2226,6 +2226,6 @@
       "description": "tool-a2acanceltask-description"
     }
   ],
-  "commit": "8d037fece0be1978272cf60f906f7bd144e32408",
-  "date": "2026-09-04T14:07:37.503Z"
+  "commit": "6582f0c18fc69b31f97ca6fc98673eaf2a0666a1",
+  "date": "2026-09-05T05:39:52.468Z"
 }

package/cli/product.selfhosted.json

@@ -359,6 +359,6 @@
     "ScheduledTasks": true,
     "SkipToolCallSupportCheck": true
   },
-  "commit": "8d037fece0be1978272cf60f906f7bd144e32408",
-  "date": "2026-09-04T14:07:37.416Z"
+  "commit": "6582f0c18fc69b31f97ca6fc98673eaf2a0666a1",
+  "date": "2026-09-05T05:39:52.487Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-ai/agent-sdk",
-  "version": "0.3.252",
+  "version": "0.3.253",
   "description": "CodeBuddy Code SDK for JavaScript/TypeScript",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

package/cli/dist-server/types/node/acp/acp-view-rewind-to.d.ts

@@ -1,34 +0,0 @@
-/**
- * rewindTo — 统一回退操作（Phase 1 核心收敛点）
- *
- * 将 applyResendFork() 和 CheckpointService.updateHistory() 两处重复的
- * "回退历史指针 + 标记 conversationReverted" 逻辑统一到此函数。
- *
- * 职责分离：
- *   - rewindTo()     → 纯状态变更（lastMessageId + conversationReverted）
- *   - reason 分支    → 副作用差异（persist notice / historyReloadSubject）
- *   - 调用方        → 负责解析 fork 点（resolveResendForkPoint / checkpoint.parentId）
- *
- * @see issue #50495 / docs/plans/2026-06-20-resend-edit-unified-plan.md
- */
-import type { Session } from '../session/session-protocol';
-/** 回退原因，决定 rewindTo 的副作用行为 */
-export type RewindReason = 'resend_edit' | 'checkpoint_revert';
-export interface RewindOptions {
-    /** resend_edit 时需要持久化的被编辑消息 ID */
-    editedUserItemId?: string;
-    /** 持久化函数（仅 resend_edit 使用）— 通常为 sessionManager.addHistory */
-    addHistory?: (session: Session, items: any[]) => Promise<void>;
-}
-/**
- * 将会话历史指针回退到指定 fork 点。
- *
- * 统一行为：
- *   1. session.lastMessageId = forkPointId
- *   2. session.conversationReverted = true
- *
- * 按 reason 触发不同副作用：
- *   - 'resend_edit':       调用 addHistory 持久化 fork 墓碑标记
- *   - 'checkpoint_revert': 触发 historyReloadSubject 通知前端刷新
- */
-export declare function rewindTo(session: Session, forkPointId: string | undefined, reason: RewindReason, options?: RewindOptions): Promise<void>;

package/cli/dist-server/types/node/acp/acp-web-ui-client.d.ts

@@ -1,22 +0,0 @@
-/**
- * Web UI ACP 握手身份。WorkBuddy / Zed 等 --acp 客户端不带这个名字。
- * 刷新快照、busy 工具、/goal drain 只对这个客户端生效，避免改到共用 --acp 语义。
- */
-export declare const ACP_WEB_UI_CLIENT_NAME = "codebuddy-web-ui";
-export declare function isWebUiAcpClientName(name: unknown): boolean;
-export declare function isWebUiAcpSession(session: {
-    options?: object;
-}): boolean;
-/**
- * Keep the in-memory Web-ACP marker aligned with the connection that most
- * recently admitted the session.
- *
- * A same-id session may be reused instead of deserialized again.  In that
- * case simply doing nothing for non-Web clients leaves a stale `webUiAcp`
- * bit behind and lets WorkBuddy enter Web-only goal/follow-up behaviour.
- * The marker is transport state, not durable session identity, so an
- * unopted ACP client must actively clear it.
- */
-export declare function syncWebUiAcpSessionFlag<T extends {
-    options?: object;
-}>(session: T, webUiAcp: boolean): void;

package/cli/dist-server/types/node/acp/usage-by-category-calculator.d.ts

@@ -1,45 +0,0 @@
-/**
- * 上下文消耗 5 类目细拆 · 字符分类 + 反向归一化分配。
- * 严格守恒：sum(usageByCategory) === input.totalTokens（即 ACP usage_update.used）。
- */
-/** 5 类目细拆结果。schema 版本字段 `version` 为后续扩展预留。 */
-export interface UsageByCategory {
-    systemPrompt: number;
-    conversation: number;
-    tools: number;
-    mcp: number;
-    skills: number;
-    /** schema 版本：未来扩展加字段时 +1，客户端按 version 兼容。 */
-    version: 1;
-}
-/** 单个 tool 定义的最小契约（仅消费 name + description；其它字段透传 JSON.stringify）。 */
-export interface ToolLike {
-    name: string;
-    description?: string;
-    /** OpenAI Agent SDK 的 tool 通常带 parameters/schema；calculator 不解析，只 JSON.stringify。 */
-    input_schema?: unknown;
-    parameters?: unknown;
-}
-/** 单条 history item 的结构松约束（结构不规范时 calculator 跳过，不抛错）。 */
-export interface HistoryItemLike {
-    type?: string;
-    role?: string;
-    content?: unknown;
-    callId?: string;
-    name?: string;
-    arguments?: unknown;
-    output?: unknown;
-}
-export interface UsageByCategoryInput {
-    /** 当前请求最终发给模型的 system prompt 渲染产物（已 resolve 为字符串）。 */
-    systemPrompt: string;
-    /** 当前请求装载的 tool 定义列表（用作字符代理：JSON.stringify 每个 tool）。 */
-    tools: ReadonlyArray<ToolLike>;
-    /** session.history（user/assistant 消息 + function_call / function_call_result）。 */
-    history: ReadonlyArray<HistoryItemLike>;
-    /** ACP usage_update.used，作为最终归一化的总分母。 */
-    totalTokens: number;
-}
-export declare class UsageByCategoryCalculator {
-    static compute(input: UsageByCategoryInput): UsageByCategory;
-}

package/cli/dist-server/types/node/acp/usage-by-category-char-weight.d.ts

@@ -1,9 +0,0 @@
-/**
- * 字符权重 · 上下文消耗 5 类目细拆专用。
- * CJK / ASCII 字母空白 / 其它字符分别按 1.2 / 0.25 / 0.7 折算。
- */
-/**
- * 按字符权重把字符串折算成「token 数」估算量（用于 5 类目反向归一化的相对比例）。
- * 真实 token 数由 ACP usage_update.used 决定；本函数仅用作类目分配权重。
- */
-export declare function weighted(text: string): number;

package/cli/dist-server/types/node/acp/usage-by-category-distribute.d.ts

@@ -1,6 +0,0 @@
-/**
- * 守恒分配函数 —— 把 totalTokens 按 5 类目权重分配到非负整数桶里，sum 严格守恒。
- * 算法：floor 分配 + 按余数从大到小补 1。
- */
-export type UsageByCategoryKey = 'systemPrompt' | 'conversation' | 'tools' | 'mcp' | 'skills';
-export declare function distributeWithConservation(estimates: Record<UsageByCategoryKey, number>, totalTokens: number): Record<UsageByCategoryKey, number>;

package/cli/dist-server/types/node/acp/usage-by-category-tools-split.d.ts

@@ -1,11 +0,0 @@
-/**
- * Skills / MCP 切分 · 上下文消耗 5 类目细拆专用。
- * Skill 的 `<available_skills>` 归 skills；ToolSearch 的 `mcp__` 行归 mcp。
- */
-import type { ToolLike } from './usage-by-category-calculator';
-export interface ToolsBuckets {
-    toolsChars: string;
-    mcpChars: string;
-    skillsChars: string;
-}
-export declare function collectToolsBuckets(tools: ReadonlyArray<ToolLike>): ToolsBuckets;