@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/plugin-read-summary.d.ts

@@ -0,0 +1,61 @@
+import { type PluginInfo } from './plugin-protocol.js';
+export interface PluginReadCommandSummary {
+    name: string;
+    description?: string;
+    argumentHint?: string;
+    /**
+     * Resolved command file used by the private Harness skills inventory.
+     * Metadata-only fallbacks intentionally omit this field because they do
+     * not prove that an executable command artifact exists on disk.
+     */
+    path?: string;
+}
+export interface PluginReadAgentSummary {
+    name: string;
+    description?: string;
+}
+export interface PluginReadSkillSummary {
+    name: string;
+    description: string;
+    enabled: boolean;
+    path?: string;
+    shortDescription?: string;
+}
+export interface PluginReadOutputStyleSummary {
+    name: string;
+    description?: string;
+}
+/**
+ * Metadata-only projection used by the shared server Resource API.
+ *
+ * This is a hard serialization boundary. It must never contain prompt bodies,
+ * agent instructions, hook handlers, MCP/LSP connection configuration, plugin
+ * settings, or user credentials.
+ */
+export interface PluginReadComponentSummary {
+    agents: PluginReadAgentSummary[];
+    /**
+     * Private discovery diagnostic used by Harness skills/list. Public
+     * plugin/read projection must strip this field.
+     */
+    ambiguousCommandNames?: string[];
+    commands: PluginReadCommandSummary[];
+    hooks: Record<string, never[]>;
+    lspServers: string[];
+    mcpServers: string[];
+    outputStyles: PluginReadOutputStyleSummary[];
+    skills: PluginReadSkillSummary[];
+}
+export interface PluginReadComponentOptions {
+    /** Locally materialized marketplace root used for pre-install discovery. */
+    marketplacePath?: string;
+}
+/**
+ * Read public plugin component metadata without loading runtime components.
+ *
+ * This function performs bounded, read-only access within the real plugin
+ * root. In particular, it does not call getPluginComponents(), interpolate
+ * plugin options/environment variables, download MCP bundles, extract
+ * archives, register hooks, or start MCP/LSP processes.
+ */
+export declare function readPluginComponentSummary(plugin: PluginInfo, options?: PluginReadComponentOptions): Promise<PluginReadComponentSummary>;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/plugin-runtime-refresh-service.d.ts

@@ -0,0 +1,262 @@
+import { CliRuntimeOptions } from '../../../../../node/cli/cli-runtime-options.js';
+import { CommandManager } from '../../../../../node/command/command-protocol.js';
+import { LSPManager } from '../../../../../node/lsp/lsp-protocol.js';
+import { McpManager } from '../../../../../node/mcp/mcp-protocol.js';
+import { OutputStyleManager } from '../../../../../node/output-style/output-style-protocol.js';
+import { SkillProductProvider } from '../../../../../node/product/skill-product-provider.js';
+import { CliSettingSourcesProvider } from '../../../../../node/settings/cli-setting-sources-provider.js';
+import { CliSettingsProvider } from '../../../../../node/settings/cli-settings-provider.js';
+import { SettingsManager } from '../../../../../node/settings/settings-protocol.js';
+import { ToolManager } from '../../../../../node/tools/tool-protocol.js';
+import { AgentManager } from '../../../../cbc-core/lib/node/index.js';
+import { ProductManager } from '../../../../product/lib/common/index.js';
+import { EventService, Logger } from '../../../../telemetry/lib/common/index.js';
+import { type ActivePluginRuntimeEntry, type PluginInfo, PluginManager, type PluginRuntimeLoadError } from './plugin-protocol.js';
+export type PluginRuntimeRefreshReason = 'startup' | 'prewarm-activate' | 'background-management' | 'reload-command' | 'acp-host-reconcile' | 'acp-host-refresh' | 'api-explicit-refresh';
+export interface PluginRuntimeRefreshResult {
+    readonly activePlugins: readonly ActivePluginRuntimeEntry[];
+    readonly errors: readonly PluginRuntimeLoadError[];
+    readonly repairedDependencies: readonly string[];
+    /** Effective enabled roots verified by a strict reconcile, when requested. */
+    readonly reconciledPluginIds?: readonly string[];
+}
+export interface PluginRuntimeRefreshOptions {
+    /**
+     * Re-read persisted settings/install state before activation. The
+     * temporary in-memory API switch sets this to false because its
+     * `persist:false` selection intentionally lives only in PluginManager memory.
+     */
+    readonly reloadDesiredState?: boolean;
+    /**
+     * Refuse to publish a reload that changes plugin MCP server names. The
+     * command enables this only when an existing prompt cache would be
+     * invalidated and the effective agent has no ToolSearch support.
+     */
+    readonly blockMcpToolChanges?: boolean;
+    /** @internal Strict roots checked before publishing a reconciled snapshot. */
+    readonly requiredPluginIds?: readonly string[];
+}
+export interface PluginReconcileDiagnostic {
+    readonly code: 'management-failed' | 'required-plugin-missing' | 'runtime-load-failed' | 'timeout';
+    readonly message: string;
+    readonly pluginId?: string;
+}
+export interface PluginReconcileResult {
+    readonly ready: boolean;
+    readonly requiredPluginIds: readonly string[];
+    readonly missingPluginIds: readonly string[];
+    readonly errors: readonly PluginReconcileDiagnostic[];
+}
+export interface PluginReconcileOptions {
+    readonly reason?: string;
+    readonly requiredPluginIds?: readonly string[];
+}
+export interface ConfiguredPluginReconcileOptions {
+    /** Bounds only this caller's wait; it never cancels the shared mutation. */
+    readonly signal?: AbortSignal;
+    /** Optional caller diagnostic label; it never changes reconcile semantics. */
+    readonly reason?: string;
+    /** Complete Product snapshot supplied by the long-lived Host. */
+    readonly productConfig?: Record<string, unknown>;
+}
+export declare class PluginManagementDisabledError extends Error {
+    readonly code = "PLUGIN_MANAGEMENT_DISABLED";
+    constructor();
+}
+export declare class ConfiguredPluginReconcileTimeoutError extends Error {
+    readonly code = "PLUGIN_RECONCILE_TIMEOUT";
+    constructor();
+}
+export declare class ConfiguredPluginReconcileAbortedError extends Error {
+    readonly code = "PLUGIN_RECONCILE_ABORTED";
+    constructor();
+}
+export declare class PluginReconcileError extends Error {
+    readonly result: PluginReconcileResult;
+    readonly code = "PLUGIN_RECONCILE_FAILED";
+    constructor(result: PluginReconcileResult);
+}
+export declare class PluginMcpToolChangeBlockedError extends Error {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+    constructor(added: readonly string[], removed: readonly string[]);
+}
+export interface PluginReloadSummary {
+    readonly plugins: number;
+    readonly disabledPlugins: number;
+    readonly commands: number;
+    readonly agents: number;
+    readonly skills: number;
+    readonly hooks: number;
+    readonly mcpServers: number;
+    readonly lspServers: number;
+    readonly errors: number;
+}
+export declare function summarizePluginReload(activePlugins: readonly ActivePluginRuntimeEntry[], installedPlugins: readonly PluginInfo[], loadErrors: readonly PluginRuntimeLoadError[]): PluginReloadSummary;
+/**
+ * Claude Code-style active-plugin refresh.
+ *
+ * Management operations update settings/install state before entering this
+ * serialized projection path. `/reload-plugins` only clears runtime discovery
+ * caches and reprojects the already-selected plugins; it never turns a runtime
+ * refresh into marketplace installation or broad dependency repair.
+ */
+export declare class PluginRuntimeRefreshService {
+    protected readonly pluginManager: PluginManager;
+    protected readonly productManager: ProductManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly cliSettingsProvider: CliSettingsProvider;
+    protected readonly cliSettingSourcesProvider: CliSettingSourcesProvider;
+    protected readonly cliRuntimeOptions?: CliRuntimeOptions;
+    protected readonly agentManager?: AgentManager;
+    protected readonly mcpManager?: McpManager;
+    protected readonly commandManager?: CommandManager;
+    protected readonly lspManager?: LSPManager;
+    protected readonly toolManager?: ToolManager;
+    protected readonly outputStyleManager?: OutputStyleManager;
+    protected readonly skillProductProvider?: SkillProductProvider;
+    protected readonly eventService?: EventService;
+    protected readonly logger: Logger;
+    private refreshTail;
+    /** Single-flight final argv/settings publication without holding remote I/O. */
+    private settingsPreparation?;
+    /**
+     * The configured marketplace/plugin mutation itself. It is deliberately
+     * separate from caller waiters so a timeout or disconnect never starts an
+     * overlapping writer while the first pass still owns filesystem locks.
+     */
+    private configuredPluginPreparation?;
+    /**
+     * Product snapshots are complete replacements, so preserve request order
+     * while keeping timeout/cancellation scoped to each waiter.
+     */
+    private configuredPluginPreparationTail;
+    /**
+     * Latched once the composed system prompt has been projected. Later
+     * enable/disable of a compose plugin travels through settings reconcile,
+     * which republishes agents behind `waitForRefreshSettled`, so the first-turn
+     * gate never has to re-arm.
+     */
+    private composePluginsProjected;
+    private composePluginsGate?;
+    /** The first committed runtime snapshot starts exactly one manager pass. */
+    private backgroundPluginManagementStarted;
+    private backgroundPluginManagementTask?;
+    /** Startup projection has handed persistent desired state to this owner. */
+    private settingsReconcileEnabled;
+    /**
+     * Persisted settings may be edited by another process after startup. Keep
+     * those writes on the long-lived management owner instead of deferring
+     * cache materialization until a later Agent Session happens to need the
+     * plugin. A generation loop closes the small race where another settings
+     * commit arrives while the previous reconcile is reprojecting.
+     */
+    private settingsReconcileGeneration;
+    private settingsReconcileTask?;
+    private pluginSettingsSnapshot?;
+    private settingsObservationGeneration;
+    protected init(): void;
+    private readPluginSettingsSnapshot;
+    private observePluginSettingsChange;
+    private enqueueSettingsReconcile;
+    private startSettingsReconcile;
+    private startBackgroundPluginManagementAfter;
+    private runBackgroundPluginManagement;
+    private reprojectBackgroundPluginState;
+    /**
+     * @deprecated Read-only compatibility for hosts that still submit
+     * requiredPluginIds to /plugins/reconcile. This verifies the committed
+     * registry under the request-local settings projection; it never installs,
+     * changes enablement, publishes PluginManager caches, or activates runtime
+     * components.
+     */
+    reconcileConfiguredPlugins(options?: PluginReconcileOptions): Promise<PluginReconcileResult>;
+    verifyCommittedPlugins(options?: PluginReconcileOptions): Promise<PluginReconcileResult>;
+    /**
+     * Explicit, host-neutral management boundary for API clients that need the
+     * complete configured plugin state to be materialized.
+     * Unlike the ordinary headless fallback, this must not silently degrade to
+     * cache-only behavior when management is disabled.
+     */
+    reconcileAllConfiguredPlugins(options?: ConfiguredPluginReconcileOptions): Promise<void>;
+    private startConfiguredPluginPreparation;
+    private waitForConfiguredPluginReconcile;
+    private runConfiguredPluginPreparation;
+    private prepareRuntimeDesiredState;
+    /**
+     * Wait for the runtime projection currently being applied.
+     *
+     * Startup refreshes are launched before the HTTP server begins listening,
+     * because stdio plugin MCP servers need that HTTP endpoint in their child
+     * process environment. Agent entry points join this barrier before using
+     * Product/Agent state, while health/readiness endpoints remain available.
+     * The tail intentionally absorbs refresh failures: startup plugin failures
+     * degrade with the warning emitted below instead of making the CLI unusable.
+     */
+    waitForRefreshSettled(): Promise<void>;
+    waitForBackgroundWorkToSettle(): Promise<void>;
+    /**
+     * Hold a turn until the plugins that build the system prompt are live.
+     *
+     * WorkBuddy's persona is not passed in as an argument: it is assembled by
+     * `composePluginAgent` from templates that the `workbuddy-builtin` plugins
+     * contribute. Startup and prewarm activation deliberately publish a
+     * cache-first active snapshot and hand installation to the background pass
+     * (see `refresh`), so on a cold plugin cache the first model request can be
+     * built while that snapshot is still empty. Compose then finds no root
+     * plugin, returns the agent untouched, and the turn silently runs on the
+     * CLI's generic persona.
+     *
+     * `waitForRefreshSettled` cannot cover this: it only awaits the projection
+     * tail, and the background pass is intentionally not on that tail.
+     *
+     * The wait is deliberately narrow and fails open. It tracks only compose
+     * plugins, never the remote marketplaces installed alongside them, and a
+     * timeout emits a warning plus telemetry rather than blocking the user.
+     */
+    waitForComposePluginsReady(): Promise<void>;
+    private runComposePluginsGate;
+    protected getComposePluginReadyTimeoutMs(): number;
+    private reportComposeGate;
+    /**
+     * Block until every expected compose plugin is committed to the installed
+     * registry, or the deadline passes. Returns the plugins still missing.
+     */
+    private awaitComposePluginInstallation;
+    /** Resolves true on the next PluginManager mutation, false on timeout. */
+    private waitForPluginManagerChange;
+    private findUnprojectedComposePlugins;
+    private findUninstalledComposePlugins;
+    /**
+     * Compose plugins this session is supposed to end up with.
+     *
+     * Two sources, because neither alone covers every host.
+     *
+     * WorkBuddy Desktop declares every compose plugin with `autoEnable: false`
+     * (they are pre-materialized, then picked per session), so the product
+     * declarations contribute nothing here and `enabledPlugins` carries the
+     * whole set - the daemon passes it through `--settings` at activation,
+     * before the first turn. A host that instead relies on product-declared
+     * first-run defaults has the opposite shape: the declaration is the only
+     * standing truth, because settings gain those ids only *after* the install
+     * writes them, which is exactly the moment this gate exists for.
+     *
+     * Settings still wins when it explicitly disables a declared plugin, and it
+     * adds anything a host enabled directly.
+     */
+    private readDesiredComposePluginIds;
+    /**
+     * Effective `enabledPlugins` under the same scope precedence PluginManager
+     * applies, so the gate never waits for a plugin the settings would not
+     * enable.
+     */
+    private readEnabledPluginSettings;
+    /**
+     * Run a Resource-side Plugin operation on the same queue as runtime
+     * refreshes. The operation may materialize immutable Plugin cache entries,
+     * so treating it as a plain read would allow refreshActivePlugins() to
+     * observe only part of a dependency closure.
+     */
+    runWithPluginState<T>(operation: () => Promise<T>): Promise<T>;
+    refresh(reason: PluginRuntimeRefreshReason, options?: PluginRuntimeRefreshOptions): Promise<PluginRuntimeRefreshResult>;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/plugin-validator.d.ts

@@ -0,0 +1,48 @@
+import { PluginValidator as IPluginValidator } from './plugin-protocol.js';
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+export interface ValidationResult {
+    success: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    filePath: string;
+    fileType: 'plugin' | 'marketplace';
+}
+/**
+ * 清单验证失败错误
+ */
+export declare class ManifestValidationError extends Error {
+    filePath: string;
+    validationResult: ValidationResult;
+    constructor(message: string, filePath: string, validationResult: ValidationResult);
+}
+/**
+ * 插件验证器实现
+ * 负责验证插件和市场清单文件的有效性
+ */
+export declare class PluginValidatorImpl implements IPluginValidator {
+    /**
+     * 验证插件或市场清单
+     * @param inputPath 文件或目录路径
+     */
+    validateManifest(inputPath: string): Promise<ValidationResult>;
+    /**
+     * 验证目录中的清单文件
+     */
+    private validateDirectory;
+    /**
+     * 验证文件
+     */
+    private validateFile;
+    /**
+     * 验证插件清单文件
+     */
+    private validatePluginManifestFile;
+    /**
+     * 验证市场清单文件
+     */
+    private validateMarketplaceManifestFile;
+    private validateDependencies;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/session-plugin-snapshot.d.ts

@@ -0,0 +1,5 @@
+import { type Session } from '../../../../cbc-core/lib/node/index.js';
+import type { ActivePluginRuntimeEntry } from './plugin-protocol.js';
+export declare function setSessionPluginSnapshot(session: Session, plugins: readonly ActivePluginRuntimeEntry[] | undefined): void;
+export declare function getSessionPluginSnapshot(session: Session | undefined): readonly ActivePluginRuntimeEntry[] | undefined;
+export declare function currentSessionPluginSnapshot(): readonly ActivePluginRuntimeEntry[] | undefined;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/zip-utils.d.ts

@@ -0,0 +1,94 @@
+import { Logger } from '../../../../telemetry/lib/common/index.js';
+import * as http from 'http';
+/**
+ * 从 zip URL 里提取 UUID 版本号，用于内置市场更新检查。
+ *
+ * 命中规则：URL basename 必须是 `<name>-<UUID>.zip`，UUID 形如
+ *     `cb_teams_marketplace-e4456ec2-6d1a-4af9-86a9-83a4bea4bbda.zip`
+ * 只接受标准 UUID v4 字面量（8-4-4-4-12），不做其他兜底解析；解析失败返回
+ * `null`，由调用方决定是否走 ETag 兜底。
+ *
+ * 外部更新调度与 CLI checker 必须共用本函数；同一个 URL 若被解析成不同版本，
+ * 两层更新判据会出现无限震荡。
+ */
+export declare function parseVersionFromUrl(url: string): string | null;
+/**
+ * ZIP metadata persisted after a successful install/update.
+ * Used to decide whether a remote source has new content without re-downloading the archive.
+ */
+export interface ZipMetadata {
+    /** Source URL or local file path this archive came from. */
+    url: string;
+    /** Last-Modified header value returned by the server (or local file mtime). */
+    lastModified?: string;
+    /** ETag header value returned by the server. */
+    etag?: string;
+    /** ISO timestamp of when this archive was downloaded. */
+    downloadedAt: string;
+    /**
+     * Indicates the install/extract step finished without error.
+     * Absent on legacy metadata, which we treat as "unverified" and trigger re-download.
+     */
+    installComplete?: boolean;
+}
+/** Headers captured from a successful download response. */
+export interface DownloadResult {
+    lastModified?: string;
+    etag?: string;
+}
+/** Result of a freshness check against a remote (or local) archive source. */
+export interface ZipUpdateCheckResult {
+    needsUpdate: boolean;
+    lastModified?: string;
+    etag?: string;
+}
+/** Resolve the metadata path for a given install location. */
+export declare function getMetadataPath(installLocation: string): string;
+/** Read metadata if it exists; returns undefined on any read/parse error. */
+export declare function readZipMetadata(installLocation: string): Promise<ZipMetadata | undefined>;
+/** Write metadata to the install location. */
+export declare function writeZipMetadata(installLocation: string, metadata: ZipMetadata): Promise<void>;
+/** A "local file path" is anything that isn't an HTTP or HTTPS URL. */
+export declare function isLocalFilePath(source: string): boolean;
+/** Detect whether a URL points to a ZIP/TGZ/TAR.GZ archive by extension. */
+export declare function isZipUrl(url: string): boolean;
+/**
+ * Fetch headers via HEAD request, following up to `maxRedirects` redirects.
+ * Some hosts (e.g. git archive URLs) reject HEAD; callers should fall back to
+ * treating that as "needs update" rather than a hard failure.
+ */
+export declare function getRemoteHeaders(url: string, maxRedirects?: number): Promise<http.IncomingHttpHeaders>;
+/**
+ * Fetch a small UTF-8 text resource with bounded connect/read time and
+ * redirect handling. Used for Product-declared marketplace version metadata.
+ */
+export declare function fetchText(url: string, timeoutMs?: number, maxRedirects?: number): Promise<string>;
+/**
+ * Download `url` to `destPath`, handling HTTP redirects.
+ * Returns the ETag / Last-Modified headers so the caller can persist them for future freshness checks.
+ */
+export declare function downloadFile(url: string, destPath: string, maxRedirects?: number): Promise<DownloadResult>;
+/** Copy a local archive to a destination path; mirrors downloadFile's return shape. */
+export declare function copyLocalFile(sourcePath: string, destPath: string): Promise<DownloadResult>;
+/**
+ * Decide whether a remote ZIP needs to be re-downloaded by comparing ETag/Last-Modified.
+ *
+ * The precedence mirrors `agent-craft`'s implementation:
+ *   1. No existing metadata → update (first install)
+ *   2. `installComplete` flag missing → update (legacy or interrupted install)
+ *   3. URL changed → update
+ *   4. ETag available on both sides → trust ETag equality
+ *   5. Last-Modified available on both sides → compare timestamps
+ *   6. HEAD request failed or server returns neither header → update (safe default)
+ */
+export declare function checkZipNeedsUpdate(url: string, installLocation: string, maxRedirects?: number): Promise<ZipUpdateCheckResult>;
+/** Decide whether a local-path ZIP has changed since last install by comparing mtime. */
+export declare function checkLocalZipNeedsUpdate(sourcePath: string, installLocation: string): Promise<ZipUpdateCheckResult>;
+/**
+ * Extract a ZIP / TGZ / TAR.GZ archive to `targetDir`.
+ *
+ * @param flatten When a single top-level directory is detected in a .zip (common for
+ *   `git archive` output), move its contents up one level. Ignores `__MACOSX`.
+ *   Defaults to true.
+ */
+export declare function extractZip(zipPath: string, targetDir: string, flatten?: boolean, logger?: Pick<Logger, 'warn'>): Promise<void>;

package/cli/dist-server/types/workspace/cbc-shared/lib/node/agent/custom-input-item-types.d.ts

@@ -1,4 +1,24 @@
 export declare const CUSTOM_INPUT_ITEM_TYPES: string[];
+/**
+ * 主模型自身响应之外结算的积分（子代理 / 团队成员、生图等生成工具），按主对话轮次记账。
+ * Metadata only：不送模型、不渲染。主模型的积分仍记在其输出条目的 `rawUsage.credit` 上，
+ * 两者相加即该轮总消耗，与 ACP `usage_update.cost` 推送口径一致。
+ */
+export interface CreditUsageItem {
+    type: 'credit-usage';
+    id: string;
+    parentId?: string;
+    timestamp: number;
+    providerData: Record<string, unknown> & {
+        /** 积分归属的主对话轮次（与 `usage_update._meta['codebuddy.ai/requestId']` 同源） */
+        conversationRequestId: string;
+        credit: number;
+        source: 'team_member' | 'generation_tool';
+        /** 结算阶段唯一标识，回放按它去重 */
+        stageId: string;
+        messageId?: string;
+    };
+}
 /** A completed model response whose usage has no committed output item.
  * Metadata only: never submitted to the model or displayed as a message.
  * Uses the same provider usage and generation identity as normal output items.

package/cli/dist-server/types/workspace/cbc-shared/lib/node/agent/openai-agents-types.d.ts

@@ -29,7 +29,7 @@
 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 type { AcpTerminalStateItem, FileHistorySnapshotItem, ModelUsageItem, ResendForkNoticeItem } from './custom-input-item-types.js';
+import type { AcpTerminalStateItem, CreditUsageItem, FileHistorySnapshotItem, ModelUsageItem, ResendForkNoticeItem } from './custom-input-item-types.js';
 export * from './custom-input-item-types.js';
 export type { RunStreamEvent } from '@openai/agents-core';
 export type Agent<TContext = UnknownContext, TOutput extends AgentOutputType = TextOutput> = AgentTypeCtor<TContext, TOutput>;
@@ -98,7 +98,7 @@ export type UnknownItem = OriginalUnknownItem & ExtendedProperties;
 /**
  * Extended AgentInputItem with additional properties for conversation tree structure
  */
-export type AgentInputItem = (OriginalAgentInputItem | CustomTitleItem | TopicItem | AiTitleItem | FileHistorySnapshotItem | SummaryItem | GoalResultItem | GoalProgressItem | TurnMetricsItem | ResendForkNoticeItem | AcpTerminalStateItem | ModelUsageItem) & ExtendedProperties;
+export type AgentInputItem = (OriginalAgentInputItem | CustomTitleItem | TopicItem | AiTitleItem | FileHistorySnapshotItem | SummaryItem | GoalResultItem | GoalProgressItem | TurnMetricsItem | ResendForkNoticeItem | AcpTerminalStateItem | ModelUsageItem | CreditUsageItem) & ExtendedProperties;
 export interface CustomTitleItem {
     type: 'custom-title';
     customTitle: string;

package/cli/dist-server/types/workspace/cbc-shared/lib/node/index.d.ts

@@ -1,6 +1,7 @@
 export * from './agent/openai-agents-types.js';
 export * from './agent-home/agent-home-envelope-body.js';
 export * from './utils/abort-utils.js';
+export * from './utils/concurrency-utils.js';
 export * from './utils/retry-backoff.js';
 export * from './utils/retry-policy.js';
 export * from './settings/settings-types.js';

package/cli/dist-server/types/workspace/cbc-shared/lib/node/model/model-errors.d.ts

@@ -95,6 +95,14 @@ export declare class ModelConfigError extends CustomError {
  * 详见 `docs/error-codes.md` 的「文案来源：后端下发优先，前端 i18n 兜底」。
  */
 export declare const customModelMissingUrlMessage: (modelId: string) => string;
+/**
+ * 自定义模型缺少 API Key 时的 message 模板。
+ *
+ * 与 {@link customModelMissingUrlMessage} 同构、同一个错误码（4100）——两者都是
+ * 「本地自定义模型请求前必需字段缺失」，前端按 4100 统一展示合并文案（不区分具体
+ * 缺哪个字段），本 message 只面向日志 / CLI 终端排障。
+ */
+export declare const customModelMissingApiKeyMessage: (modelId: string) => string;
 /**
  * 本地拉起模型（`local: true`，GGUF + llama-server）缺少接入地址时的 message 模板。
  *
@@ -109,19 +117,28 @@ export declare const CUSTOM_MODEL_CONFIG_ERROR_CATEGORY = "custom_model_config";
 /**
  * 自定义模型配置错误
  *
- * 自定义模型没有可用的接入地址时抛出。这类请求既不能发往用户自己的端点（地址就是缺的那一项），
+ * 自定义模型缺少 id / url / apiKey 三项必需字段任一时抛出。这类请求既不能发往用户自己的
+ * 端点（地址本身就缺，或缺 key 发出去也只会把 accessToken 泄露给第三方端点后收到 401），
  * 也**不允许**回落到产品默认网关：裸模型名在我方模型表里必然查不到，只会换回一个 11102
  * 「当前模型不可用，请切换其他模型」，把用户的配置问题误导成模型问题，且用户无法自助修复。
  *
  * `data` 由 ACP 层的 `extractStructuredErrorData` 读取后透传到客户端（headless 的
- * `errors_info[]` 同样会带上），前端按 4100 查 i18n 给出本地化的可操作文案。
+ * `errors_info[]` 同样会带上），前端按 4100 查 i18n 给出本地化的合并文案（不区分具体缺
+ * 哪个字段）。
  *
- * message 请用 {@link customModelMissingUrlMessage} 构造，保持与同族错误一致的英文口径。
+ * message 请用 {@link customModelMissingUrlMessage} / {@link customModelMissingApiKeyMessage}
+ * 构造，保持与同族错误一致的英文口径。
+ *
+ * `modelId` 是本轮出错的模型身份（issue #136649）：4100 在模型调用前拦截，本轮不会有任何
+ * 带 `requestModelId` 的响应行落盘，唯一落到 JSONL 的是 InterruptionService 的 skipRun 错误
+ * 行，它只从本错误的 `data` 里取得到模型 id。缺了它，重启后客户端恢复出的「前往配置」提示卡
+ * 拿不到 modelId，跳转会退化成打开模型设置列表，而不是该模型的编辑页。
  */
 export declare class CustomModelConfigError extends CustomError {
     readonly data: Readonly<{
-        code: 4100;
-        category: "custom_model_config";
+        code: number;
+        category: string;
+        modelId?: string;
     }>;
-    constructor(message: string);
+    constructor(message: string, modelId?: string);
 }

package/cli/dist-server/types/workspace/cbc-shared/lib/node/tools/tool-names.d.ts

@@ -35,6 +35,8 @@ export declare enum ToolNames {
     IMAGE_EDIT = "ImageEdit",
     ARTIFACT = "Artifact",
     ARTIFACT_CONTROL = "ArtifactControl",
+    /** 资料库上传：把本地单个文件上传为资料库节点。工具名按既有外部契约固定为下划线风格。 */
+    LIBRARY_UPLOAD = "LibraryUpload",
     TEAM_CREATE = "TeamCreate",
     TEAM_DELETE = "TeamDelete",
     SEND_MESSAGE = "SendMessage",

package/cli/dist-server/types/workspace/cbc-shared/lib/node/utils/concurrency-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Map items with a bounded number of async workers while preserving input
+ * order in the returned results.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], concurrency: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;