@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.0

package/dist/wire/errors.js

@@ -0,0 +1,143 @@
+import { DEFAULT_LANGUAGE, render, } from "../i18n/index.js";
+/** 全部业务码；用于校验与测试遍历 */
+export const BIZ_CODES = [
+    "unauthorized",
+    "invalid_params",
+    "not_found",
+    "busy",
+    "payload_too_large",
+    "unsupported",
+    "internal",
+    "config_invalid",
+    "mcp_unavailable",
+    "model_unsupported",
+    "handoff_declined",
+    "question_pending",
+    "context_guard",
+];
+/** 业务码 → 默认文案键（`HostError` 不指定 `messageKey` 时用它） */
+const DEFAULT_MESSAGE_KEY = {
+    unauthorized: "error.unauthorized",
+    invalid_params: "error.invalidParams",
+    not_found: "error.notFound",
+    busy: "error.busy",
+    payload_too_large: "error.payloadTooLarge",
+    unsupported: "error.unsupported",
+    internal: "error.internal",
+    config_invalid: "error.configInvalid",
+    mcp_unavailable: "error.mcpUnavailable",
+    model_unsupported: "error.modelUnsupported",
+    handoff_declined: "error.handoffDeclined",
+    question_pending: "error.questionPending",
+    context_guard: "error.contextGuard",
+};
+/**
+ * 业务码 → JSON-RPC 数字码。
+ *
+ * 标准里只有少数几个数字码有意义（-32700 解析、-32600 非法请求、-32601 无此方法、
+ * -32602 参数、-32603 内部）；产品层面的处境统一落在 `-32000 .. -32099` 这段
+ * 「实现自定义」区间，真伪以 `data.code` 为准（PRD A4：不按标准的错误码空间走）。
+ */
+const JSON_RPC_CODE = {
+    invalid_params: -32602,
+    internal: -32603,
+    unauthorized: -32001,
+    not_found: -32004,
+    busy: -32005,
+    payload_too_large: -32006,
+    unsupported: -32601,
+    config_invalid: -32008,
+    mcp_unavailable: -32009,
+    model_unsupported: -32010,
+    handoff_declined: -32011,
+    question_pending: -32012,
+    context_guard: -32013,
+};
+/** 业务码对应的 JSON-RPC 数字码 */
+export function jsonRpcCode(code) {
+    return JSON_RPC_CODE[code];
+}
+/** 业务码对应的默认文案键 */
+export function defaultMessageKey(code) {
+    return DEFAULT_MESSAGE_KEY[code];
+}
+/** 运行时判断一个值是不是已知业务码 */
+export function isBizCode(value) {
+    return typeof value === "string" && BIZ_CODES.includes(value);
+}
+/**
+ * 宿主抛给接线的错误：带业务码、文案键与渲染参数，出网时按连接语言渲染。
+ *
+ * 业务层只管用码与参数描述「哪里不对」，不拼句子、不碰语言 —— 语言是连接的事。
+ */
+export class HostError extends Error {
+    code;
+    messageKey;
+    params;
+    detail;
+    constructor(code, options = {}) {
+        const messageKey = options.messageKey ?? defaultMessageKey(code);
+        // `Error.message` 只给日志和调试看：固定用默认语言渲染一份，免得日志里出现空消息
+        super(render(DEFAULT_LANGUAGE, messageKey, options.params));
+        this.name = "HostError";
+        this.code = code;
+        this.messageKey = messageKey;
+        this.params = options.params;
+        this.detail = options.detail;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+    /** 渲染成错误帧里的 `data`（PRD D8：按连接语言出人话） */
+    toErrorData(language = DEFAULT_LANGUAGE) {
+        const params = this.params ?? {};
+        const data = {
+            code: this.code,
+            message: render(language, this.messageKey, params),
+            params,
+        };
+        if (this.detail !== undefined) {
+            data.detail = this.detail;
+        }
+        return data;
+    }
+    /** 换一条更适合当前上下文的文案键（例如带上具体实体名），返回新实例 */
+    withMessage(messageKey, params) {
+        return new HostError(this.code, {
+            messageKey,
+            params: params ?? this.params,
+            detail: this.detail,
+            cause: this.cause,
+        });
+    }
+    /** 追加结构化事实后返回新实例 */
+    withDetail(detail) {
+        return new HostError(this.code, {
+            messageKey: this.messageKey,
+            params: this.params,
+            detail,
+            cause: this.cause,
+        });
+    }
+    /** 判断任意值是不是 `HostError`（跨模块实例判断用不到 `instanceof` 的场合） */
+    static is(value) {
+        return value instanceof HostError;
+    }
+}
+/**
+ * 把任意抛出物收敛成 `ErrorData`。
+ *
+ * 接线层只会写一次 `catch`，其它错误（`TypeError`、SDK 抛的、字符串）都在这里被兜成
+ * `internal`，原始信息进 `detail.reason` 供排查 —— 于是界面上是一句人话，而不是一堆堆栈。
+ */
+export function toErrorData(error, language = DEFAULT_LANGUAGE) {
+    if (HostError.is(error))
+        return error.toErrorData(language);
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+        code: "internal",
+        message: render(language, "error.internal"),
+        params: {},
+        detail: { reason },
+    };
+}

package/dist/wire/events.d.ts

@@ -0,0 +1,102 @@
+import type { AgentNS } from "@ai-zen/agents-core";
+import type { NoticeView, QuestionView, RunState, UsageSnapshot } from "./states.js";
+/**
+ * 事件（宿主 → 客户端的推送，见 architecture §7）。
+ *
+ * 推送是 JSON-RPC 通知（无 id），`params` 里带事件名与数据；不重放、不需要 ack —— 断线即作废，
+ * 重连由客户端按 D5 自己拉状态与消息。所以这里的每个事件都只是「在线时的一脚提醒」：
+ * 真正的事实要能从 `conversation.state` / `message.list` 再拉出来（PRD L5）。
+ *
+ * 一条约定：事件只描述「发生了什么变化」，客户端需要完整对象时回宿主拉 ——
+ * 这样多端同时在线时不会出现「一份数据在推送里长成另一种形状」。
+ *
+ * 流式增量的载荷是 core 的 `AgentNS.Delta` 原样：它描述的正是一片 chunk 带来了什么
+ * （`content` / `reasoning_content` / `tool_calls` / …），`applyChunk` 吃的是同一份，
+ * 所以客户端攒出来的消息与宿主存下来的那条逐字一致。
+ */
+/**
+ * `run.state`：一段对话的运行状态变化（六态见 `states.ts` 的 `GenerationState`）。
+ *
+ * 发全量快照而不是「变成第几态」的差量：客户端任何时刻拿到一条就能直接替换本地状态，
+ * 不必先对齐历史（重连时尤其要紧，PRD L5）。
+ */
+export interface RunStatePayload {
+    conversationId: string;
+    run: RunState;
+    /** 生成这份快照的时刻 */
+    at: string;
+}
+/**
+ * `message.delta`：一条消息的流式增量（PRD L5：在线时推送；断线后靠 `message.list` 补拉）。
+ *
+ * 增量本体是 core 的 `AgentNS.Delta`，这一片属于哪一段由它自己带的字段说明：`content` 是
+ * 正文、`reasoning_content` 是思考、`tool_calls` 是工具调用（PRD F-I2 的那三段）。
+ * 外壳只带定位信息：哪个对话、哪条消息、这条消息内的第几片。
+ *
+ * `seq` 是这条消息内的递增序号，客户端用它发现「漏了一片」并在重连后重拉整条。
+ */
+export interface MessageDeltaPayload {
+    conversationId: string;
+    messageId: string;
+    /** 这条消息内的序号，从 0 开始递增 */
+    seq: number;
+    /** 这一片增量，core 原样 */
+    delta: AgentNS.Delta;
+    /** 这次推送的时刻 */
+    at: string;
+}
+/**
+ * 结构变化的种类。客户端看到它就去拉对应的东西（PRD L5 / `conversation.changed`）。
+ *
+ * 事件的用途是「告诉客户端该去拉了」，所以这里只给变化的名字与够用的定位信息，
+ * 不试图把变化后的整个对象塞进推送里。
+ */
+export type ConversationChangeKind = "created" | "renamed" | "pinned" | "messages_persisted" | "message_removed" | "settings_changed" | "deleted";
+/** `conversation.changed`：改名、置顶、新增消息已落库、删除等结构变化 */
+export interface ConversationChangedPayload {
+    conversationId: string;
+    /** 所属 Workspace；对话被删后仍带上，便于客户端把它从对应列表里摘掉 */
+    workspaceId: string | null;
+    change: ConversationChangeKind;
+    /** 变化后这段对话的消息条数（删掉整段对话时为空） */
+    messageCount: number | null;
+    at: string;
+}
+/** `notice`：新通知（三档语气 + `duration`，PRD L3 / F-I8） */
+export interface NoticePayload {
+    notice: NoticeView;
+    at: string;
+}
+/** `question`：问题对象被创建或被回答（多端看到同一个，PRD D22 / F-I9） */
+export interface QuestionPayload {
+    question: QuestionView;
+    at: string;
+}
+/** `usage`：用量变化（本轮 / 累计 / 速率，PRD F-I5） */
+export interface UsagePayload {
+    conversationId: string;
+    usage: UsageSnapshot;
+    at: string;
+}
+/**
+ * 事件名 → 载荷。
+ *
+ * 名称按 architecture §7 定：`run.state`、`message.delta`、`conversation.changed`、
+ * `notice`、`question`、`usage`。
+ */
+export interface EventMap {
+    "run.state": RunStatePayload;
+    "message.delta": MessageDeltaPayload;
+    "conversation.changed": ConversationChangedPayload;
+    notice: NoticePayload;
+    question: QuestionPayload;
+    usage: UsagePayload;
+}
+/** 事件名 */
+export type EventName = keyof EventMap;
+/** 取某个事件的载荷类型 */
+export type EventPayload<E extends EventName> = EventMap[E];
+/** 全部事件名（接线层注册推送、测试遍历用） */
+export declare const EVENT_NAMES: readonly ["run.state", "message.delta", "conversation.changed", "notice", "question", "usage"];
+/** 运行时判断一个字符串是不是已知事件名 */
+export declare function isEventName(value: unknown): value is EventName;

package/dist/wire/events.js

@@ -0,0 +1,13 @@
+/** 全部事件名（接线层注册推送、测试遍历用） */
+export const EVENT_NAMES = [
+    "run.state",
+    "message.delta",
+    "conversation.changed",
+    "notice",
+    "question",
+    "usage",
+];
+/** 运行时判断一个字符串是不是已知事件名 */
+export function isEventName(value) {
+    return typeof value === "string" && EVENT_NAMES.includes(value);
+}

package/dist/wire/frames.d.ts

@@ -0,0 +1,106 @@
+import type { Language } from "../i18n/index.js";
+import { type ErrorData } from "./errors.js";
+import type { EventName, EventPayload } from "./events.js";
+/**
+ * JSON-RPC 2.0 帧（architecture §6）。
+ *
+ * 以标准为底，产品形状长在 `params` / `result`（PRD A4）。标准里对我们有负担的部分不用，
+ * 具体是：
+ *   - **批量请求**：帧是数组时直接拒（`unsupported`）—— 一条连接上并发靠多条请求就够，
+ *     批量会带来「数组里部分成功」这种没法向用户解释的结果；
+ *   - 强制错误码空间：数字码只做粗分类，真伪看 `error.data.code`（见 `errors.ts`）；
+ *   - 「通知必须无 id」：标准里带 id 的帧就是请求，而我们出网的通知不带 id（客户端也不需要回什么）。
+ *
+ * 入站只可能收到 request / notification；response 两种在客户端侧解析时用得着，
+ * 所以守卫函数也一并给全，客户端可以直接复用这一份代码。
+ */
+/** 请求 id：字符串或数字（宿主分配或回显客户端给的；`null` 只出现在错误响应里） */
+export type JsonRpcId = string | number;
+/** 请求帧（要回一个响应） */
+export interface JsonRpcRequestFrame {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+/** 通知帧（不需要响应） */
+export interface JsonRpcNotificationFrame {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+}
+/** 错误对象：数字码 + 一句短描述 + `data`（业务码、人话、结构化事实） */
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data: ErrorData;
+}
+/** 成功响应帧 */
+export interface JsonRpcSuccessFrame {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result: unknown;
+}
+/** 错误响应帧；`id` 为 `null` 表示「连 id 都没解析出来」 */
+export interface JsonRpcErrorFrame {
+    jsonrpc: "2.0";
+    id: JsonRpcId | null;
+    error: JsonRpcError;
+}
+/** 两种响应帧 */
+export type JsonRpcResponseFrame = JsonRpcSuccessFrame | JsonRpcErrorFrame;
+/**
+ * 解析后的帧：分好类、参数已挑出来。
+ *
+ * 分四类而不是三类，是因为「客户端发来的错误响应」在宿主看来是一种不该来的东西，
+ * 与「客户端发来的成功响应」需要分别处置；两者都保留形状，方便客户端复用本模块。
+ */
+export type Frame = {
+    kind: "request";
+    id: JsonRpcId;
+    method: string;
+    params: unknown;
+} | {
+    kind: "notification";
+    method: string;
+    params: unknown;
+} | {
+    kind: "response";
+    id: JsonRpcId;
+    result: unknown;
+} | {
+    kind: "error";
+    id: JsonRpcId | null;
+    error: JsonRpcError;
+};
+/** 是不是请求帧 */
+export declare function isRequestFrame(value: unknown): value is JsonRpcRequestFrame;
+/** 是不是通知帧（无 id，或 id 为 null —— 后者在标准里含糊，按通知处理） */
+export declare function isNotificationFrame(value: unknown): value is JsonRpcNotificationFrame;
+/** 是不是成功响应帧（含 `result`） */
+export declare function isSuccessFrame(value: unknown): value is JsonRpcSuccessFrame;
+/** 是不是错误响应帧（含 `error`） */
+export declare function isErrorFrame(value: unknown): value is JsonRpcErrorFrame;
+/** 是不是任一方向的响应帧 */
+export declare function isResponseFrame(value: unknown): value is JsonRpcResponseFrame;
+/**
+ * 把一条入站消息解析成 `Frame`。
+ *
+ * 三种拒绝各有稳定业务码：
+ *   - 不是合法 JSON / 不是对象 → `invalid_params`（`detail.reason` 说明是哪一步坏的）；
+ *   - 数组（批量请求）→ `unsupported`，`detail.reason` 为 `batch_not_supported`；
+ *   - 缺 `jsonrpc` / 缺 `method` / id 类型不对 → `invalid_params`，`detail.field` 指出字段。
+ */
+export declare function parseFrame(input: unknown): Frame;
+/** 成功响应 */
+export declare function okResponse(id: JsonRpcId, result: unknown): JsonRpcSuccessFrame;
+/**
+ * 错误响应。
+ *
+ * `error.message` 与 `error.data.message` 都是**按连接语言渲染好的那句话**：前者满足标准
+ * 对「一句短描述」的要求，后者是客户端真正显示的东西（PRD D8）。
+ * 传入非 `HostError` 时会被收敛成 `internal`（`detail.reason` 留着原始信息）。
+ */
+export declare function errResponse(id: JsonRpcId | null, error: unknown, language: Language): JsonRpcErrorFrame;
+/** 通知帧：宿主推送事件用（`notification("run.state", payload)`） */
+export declare function notification<E extends EventName>(event: E, payload: EventPayload<E>): JsonRpcNotificationFrame;

package/dist/wire/frames.js

@@ -0,0 +1,156 @@
+import { HostError, jsonRpcCode, toErrorData } from "./errors.js";
+// ---------------------------------------------------------------------------
+// 守卫
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isId(value) {
+    return typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+}
+function hasProtocol(value) {
+    return value.jsonrpc === "2.0";
+}
+/** 是不是请求帧 */
+export function isRequestFrame(value) {
+    if (!isRecord(value))
+        return false;
+    if (!hasProtocol(value))
+        return false;
+    return typeof value.method === "string" && value.method !== "" && isId(value.id);
+}
+/** 是不是通知帧（无 id，或 id 为 null —— 后者在标准里含糊，按通知处理） */
+export function isNotificationFrame(value) {
+    if (!isRecord(value))
+        return false;
+    if (!hasProtocol(value))
+        return false;
+    if (typeof value.method !== "string" || value.method === "")
+        return false;
+    return value.id === undefined || value.id === null;
+}
+/** 是不是成功响应帧（含 `result`） */
+export function isSuccessFrame(value) {
+    if (!isRecord(value))
+        return false;
+    if (!hasProtocol(value))
+        return false;
+    return isId(value.id) && "result" in value && !("error" in value);
+}
+/** 是不是错误响应帧（含 `error`） */
+export function isErrorFrame(value) {
+    if (!isRecord(value))
+        return false;
+    if (!hasProtocol(value))
+        return false;
+    const id = value.id;
+    if (!(id === null || isId(id)))
+        return false;
+    return isRecord(value.error);
+}
+/** 是不是任一方向的响应帧 */
+export function isResponseFrame(value) {
+    return isSuccessFrame(value) || isErrorFrame(value);
+}
+// ---------------------------------------------------------------------------
+// 解析
+// ---------------------------------------------------------------------------
+function invalidFrame(detail, field) {
+    return new HostError("invalid_params", {
+        params: { field },
+        detail,
+    });
+}
+/**
+ * 把一条入站消息解析成 `Frame`。
+ *
+ * 三种拒绝各有稳定业务码：
+ *   - 不是合法 JSON / 不是对象 → `invalid_params`（`detail.reason` 说明是哪一步坏的）；
+ *   - 数组（批量请求）→ `unsupported`，`detail.reason` 为 `batch_not_supported`；
+ *   - 缺 `jsonrpc` / 缺 `method` / id 类型不对 → `invalid_params`，`detail.field` 指出字段。
+ */
+export function parseFrame(input) {
+    let value = input;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch (error) {
+            throw invalidFrame({ reason: "not_json", text: error instanceof Error ? error.message : String(error) }, "jsonrpc");
+        }
+    }
+    if (Array.isArray(value)) {
+        throw new HostError("unsupported", {
+            params: { what: "batch requests" },
+            detail: { reason: "batch_not_supported", count: value.length },
+        });
+    }
+    if (!isRecord(value)) {
+        throw invalidFrame({ reason: "not_an_object" }, "jsonrpc");
+    }
+    if (!hasProtocol(value)) {
+        throw invalidFrame({ reason: "bad_protocol", got: value.jsonrpc ?? null }, "jsonrpc");
+    }
+    if (typeof value.method === "string") {
+        if (value.method === "") {
+            throw invalidFrame({ reason: "empty_method" }, "method");
+        }
+        const params = value.params ?? {};
+        if (isId(value.id)) {
+            return { kind: "request", id: value.id, method: value.method, params };
+        }
+        if (value.id === undefined || value.id === null) {
+            return { kind: "notification", method: value.method, params };
+        }
+        throw invalidFrame({ reason: "bad_id", got: value.id }, "id");
+    }
+    if ("error" in value) {
+        const error = value.error;
+        if (!isRecord(error)) {
+            throw invalidFrame({ reason: "bad_error_object" }, "error");
+        }
+        return { kind: "error", id: isId(value.id) ? value.id : null, error: parseErrorObject(error) };
+    }
+    if ("result" in value) {
+        if (!isId(value.id)) {
+            throw invalidFrame({ reason: "bad_id", got: value.id ?? null }, "id");
+        }
+        return { kind: "response", id: value.id, result: value.result };
+    }
+    throw invalidFrame({ reason: "neither_method_nor_result" }, "method");
+}
+/** 解析入站的错误对象；字段缺失时按 `internal` 兜底，让解析不至于半路炸掉 */
+function parseErrorObject(value) {
+    const code = typeof value.code === "number" && Number.isFinite(value.code) ? value.code : -32603;
+    const message = typeof value.message === "string" ? value.message : "";
+    const data = isRecord(value.data) ? value.data : null;
+    return { code, message, data: data ?? { code: "internal", message, params: {} } };
+}
+// ---------------------------------------------------------------------------
+// 构造
+// ---------------------------------------------------------------------------
+/** 成功响应 */
+export function okResponse(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+/**
+ * 错误响应。
+ *
+ * `error.message` 与 `error.data.message` 都是**按连接语言渲染好的那句话**：前者满足标准
+ * 对「一句短描述」的要求，后者是客户端真正显示的东西（PRD D8）。
+ * 传入非 `HostError` 时会被收敛成 `internal`（`detail.reason` 留着原始信息）。
+ */
+export function errResponse(id, error, language) {
+    const data = toErrorData(error, language);
+    // 数字码表与 errors.ts 同源，一处维护
+    const numericCode = HostError.is(error) ? jsonRpcCode(error.code) : -32603;
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: numericCode, message: data.message, data },
+    };
+}
+/** 通知帧：宿主推送事件用（`notification("run.state", payload)`） */
+export function notification(event, payload) {
+    return { jsonrpc: "2.0", method: event, params: payload };
+}

package/dist/wire/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 契约层出口。
+ *
+ * 客户端照这份形状接线；宿主接线层（`net/`）按 `MethodMap` 分发、按 `EventMap` 推送。
+ * 这里只做再导出，不新增语义。
+ *
+ * core 的消息相关类型一并再导出：客户端 `import type { AgentNS } from "@ai-zen/agents-host"`
+ * 就能拿到消息、消息内容段、工具调用、状态、角色、结束原因、增量与用量的**同一份定义**，
+ * 不必自己再抄一份 —— 抄出来的第二份迟早与宿主存下来的那条对不上。
+ */
+export * from "./errors.js";
+export * from "./states.js";
+export * from "./methods.js";
+export * from "./events.js";
+export * from "./frames.js";
+/**
+ * `AgentNS` 既是类型空间的容器（`AgentNS.Message` / `AgentNS.MessageContent` /
+ * `AgentNS.ToolCall` / `AgentNS.Delta` / `AgentNS.Usage` …），也是运行期的枚举表
+ * （`AgentNS.Role` / `AgentNS.MessageStatus` / `AgentNS.FinishReason` 的取值）。
+ */
+export { AgentNS } from "@ai-zen/agents-core";
+/**
+ * 用量的零值、逐字段相加与求和：`sumUsage` 会把消息自身用量与子 Agent 用量一起累加，
+ * 累计口径与计费一致。客户端做本地估算时直接用它，免得自己写第二套加法。
+ */
+export { ZERO_USAGE, addUsage, sumUsage } from "@ai-zen/agents-core";
+/**
+ * 把一片增量攒进一条消息。宿主自己是这么攒的，客户端折 `message.delta` 时用同一份实现，
+ * 攒出来的消息与宿主存下来的逐字一致。
+ */
+export { applyChunk } from "@ai-zen/agents-core";

package/dist/wire/index.js

@@ -0,0 +1,31 @@
+/**
+ * 契约层出口。
+ *
+ * 客户端照这份形状接线；宿主接线层（`net/`）按 `MethodMap` 分发、按 `EventMap` 推送。
+ * 这里只做再导出，不新增语义。
+ *
+ * core 的消息相关类型一并再导出：客户端 `import type { AgentNS } from "@ai-zen/agents-host"`
+ * 就能拿到消息、消息内容段、工具调用、状态、角色、结束原因、增量与用量的**同一份定义**，
+ * 不必自己再抄一份 —— 抄出来的第二份迟早与宿主存下来的那条对不上。
+ */
+export * from "./errors.js";
+export * from "./states.js";
+export * from "./methods.js";
+export * from "./events.js";
+export * from "./frames.js";
+/**
+ * `AgentNS` 既是类型空间的容器（`AgentNS.Message` / `AgentNS.MessageContent` /
+ * `AgentNS.ToolCall` / `AgentNS.Delta` / `AgentNS.Usage` …），也是运行期的枚举表
+ * （`AgentNS.Role` / `AgentNS.MessageStatus` / `AgentNS.FinishReason` 的取值）。
+ */
+export { AgentNS } from "@ai-zen/agents-core";
+/**
+ * 用量的零值、逐字段相加与求和：`sumUsage` 会把消息自身用量与子 Agent 用量一起累加，
+ * 累计口径与计费一致。客户端做本地估算时直接用它，免得自己写第二套加法。
+ */
+export { ZERO_USAGE, addUsage, sumUsage } from "@ai-zen/agents-core";
+/**
+ * 把一片增量攒进一条消息。宿主自己是这么攒的，客户端折 `message.delta` 时用同一份实现，
+ * 攒出来的消息与宿主存下来的逐字一致。
+ */
+export { applyChunk } from "@ai-zen/agents-core";