From 8217982eea7d8bc0a01ace6322b02c76567ef347 Mon Sep 17 00:00:00 2001 From: zhanglei Date: Mon, 16 Nov 2026 15:55:36 +0800 Subject: [PATCH 1/4] =?UTF-8?q?feat(usage):=20=E5=90=88=E5=B9=B6=E8=B5=84?= =?UTF-8?q?=E6=BA=90=E7=94=A8=E9=87=8F=E6=9F=A5=E8=AF=A2=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E4=B8=BA=20getUsageSummary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 listModelUsage、listToolUsage 及相关类型和接口 - 新增 getUsageSummary 及其请求和响应类型支持多维度统一查询 - 请求参数 scope 改为 dimension,时间范围改为带时区的 RFC 3339 字符串格式 - 移除分页和名称筛选,明细数据一次性返回 total、models 和 tools 三视图 - 指标结构统一为 { value, unit },支持空指标值为 null,响应无数据时 data_updated_at 返回 null - 更新文档示例和导出接口,所有用量查询适配百炼官方 Usage API 新规范 - 增加请求参数验证,防止维度与参数不匹配情况发生 - 单元测试覆盖新的接口调用和错误验证,兼容性提升 --- .changeset/usage-summary.md | 10 + docs/reference/sdk.md | 54 +++-- packages/sdk/src/index.ts | 26 +-- .../sdk/src/internal/core/usage-runtime.ts | 33 +-- .../src/internal/providers/bailian/adapter.ts | 20 +- .../src/internal/providers/bailian/usage.ts | 117 +++++----- .../sdk/src/internal/providers/interface.ts | 21 +- packages/sdk/src/internal/types/usage.ts | 174 +++++++++------ packages/sdk/tests/unit/bailian-usage.test.ts | 211 +++++++++++------- 9 files changed, 358 insertions(+), 308 deletions(-) create mode 100644 .changeset/usage-summary.md diff --git a/.changeset/usage-summary.md b/.changeset/usage-summary.md new file mode 100644 index 00000000..97c57ada --- /dev/null +++ b/.changeset/usage-summary.md @@ -0,0 +1,10 @@ +--- +"@openagentpack/sdk": minor +--- + +**BREAKING**:用量查询公开面合并为 `getUsageSummary`,按百炼官方 Usage API(`POST /api/v1/agentstudio/usage/summary`)的 `dimension` 契约一次返回 `total + models + tools`。 + +- 移除 `listModelUsage` / `listToolUsage` 及 `ModelUsagePage`、`ModelUsageRequest`、`ModelUsageItem`、`ToolUsagePage`、`ToolUsageRequest`、`ToolUsageItem`、`UsageScope`、`UsagePage`、`UsageTokenStats` 等类型 +- 新增 `getUsageSummary(ctx, request, options)` 与 `UsageSummaryRequest`、`UsageSummaryResponse`、`UsageSummary`、`UsageMetric`、`UsageTotal`、`UsageModelRow`、`UsageToolRow`、`UsageDimension`、`UsageGranularity` +- 请求变化:`scope{type,...}` → `dimension` 判别联合;毫秒 `time_range` → 带时区偏移的 RFC 3339 字符串;分页与 `model_name`/`source`/`tool_name` 服务端筛选移除(明细随汇总一次返回) +- 响应变化:指标统一为 `{ value, unit }`,未知指标 `value: null`、已知零值 `0`;无统计记录时 `data_updated_at: null` diff --git a/docs/reference/sdk.md b/docs/reference/sdk.md index d4b6404b..ab82b909 100644 --- a/docs/reference/sdk.md +++ b/docs/reference/sdk.md @@ -246,42 +246,38 @@ Session 的单一事件流获取;子线程状态不表示主会话执行结束 `SessionThreadListOptions` 和 `SessionThreadPage` 也通过 `./session-events` 导出类型, 浏览器可复用合同而无需加载 SDK 主入口或 Provider 凭据。 -### 资源用量查询 +### 资源用量汇总 -资源用量(模型调用明细 / 工具调用明细)对接百炼 app-control 的 -`usage.listModelUsage` 与 `usage.listToolUsage`,按 scope 维度返回聚合行。REST 映射 -与百炼侧约定为 AgentStudio 资源风格(`POST /usage/models`、`POST /usage/tools`, -顶层请求体);公网 AgentStudio 环境尚未启用这两个端点(网关 404),启用后无需改动 -即可调通: +用量汇总对接百炼 app-control 的 `usage.summary`,REST 映射为 AgentStudio 的 +`POST /api/v1/agentstudio/usage/summary`:一次请求同时返回整段范围的 `total`、模型明细 +`models[]` 与工具明细 `tools[]`,不存在按表分页或按名称筛选的端点。 | SDK 方法 | 百炼路径 | 结果 | | --- | --- | --- | -| `listModelUsage(ctx, request, options)` | `POST /usage/models` | `ModelUsagePage` | -| `listToolUsage(ctx, request, options)` | `POST /usage/tools` | `ToolUsagePage` | - -`scope` 按 `type` 区分三种形态:`workspace`(必传非空 `workspace_ids`,可加 `agent_id`)、 -`agent`(必传 `agent_id`,可加 `workspace_ids` 与 `agent_version`)、`session`(必传 -`session_id`)。`time_range` 为毫秒级 Unix 区间:workspace/agent 必传,session 禁止 -(复用 Session 自身窗口);校验在发起请求前完成。模型明细支持 -`model_name` 过滤与 `call_count/failed_count/input_tokens/output_tokens` 排序;工具明细 -支持 `source`(`builtin/mcp/custom`)与 `tool_name` 过滤,排序仅限调用次数相关字段。 -分页 `page_no` 从 1 开始,`page_size` 限 1..100;表头总数取 `total_call_count`,分页总数取 -`total`,无匹配时 `items` 为空、总数为 0。两者均支持 `AbortSignal`。当前仅百炼实现, -其他 Provider 返回明确的 unsupported 错误。 +| `getUsageSummary(ctx, request, options)` | `POST /usage/summary` | `UsageSummaryResponse` | + +`request` 用 `dimension` 区分三种维度:`workspace`(只传 `time_range` 与可选 `granularity`)、 +`agent`(必传 `agent_id` 与 `time_range`,可传 `agent_version`)、`session`(只传 +`session_id`;`time_range` 与 `granularity` 禁止,复用 Session 自身窗口)。`time_range` +必须是带时区偏移的 RFC 3339 字符串(响应统一 `+08:00`,区间左闭右开);`granularity` 取 +`hour/day/month`,缺省由服务端按跨度选择。校验在发起请求前完成。 + +响应 `data` 含 `query_range`(服务端按粒度对齐后的实际区间)、`data_updated_at`(无记录为 +`null`)与 `usage`;`usage.total`、`models`、`tools` 是同一范围的三个视图,不得相加。每个 +指标都是 `{ value, unit }`:未知指标 `value` 为 `null` 且保留 `unit`,已知零值为 `0`。单次 +响应模型与工具明细合计上限 10 万条。当前仅百炼实现,其他 Provider 返回明确的 unsupported +错误;支持 `AbortSignal`。 ```ts -import { listModelUsage, listToolUsage } from "@openagentpack/sdk"; +import { getUsageSummary } from "@openagentpack/sdk"; -const models = await listModelUsage(ctx, { - scope: { type: "workspace", workspace_ids: [workspaceId] }, - time_range: { start_time, end_time }, - page_no: 1, page_size: 20, sort_by: "call_count", sort_order: "desc", -}); -const tools = await listToolUsage(ctx, { - scope: { type: "agent", agent_id }, - time_range: { start_time, end_time }, - source: "mcp", tool_name: "file-parser", +const summary = await getUsageSummary(ctx, { + dimension: "workspace", + time_range: { start_time: "2026-11-02T10:00:00+08:00", end_time: "2026-11-02T15:00:00+08:00" }, }); +const { total, models, tools } = summary.data.usage; + +const sessionSummary = await getUsageSummary(ctx, { dimension: "session", session_id: sessionId }); ``` ### 自建后端原始事件的浏览器转换 @@ -362,7 +358,7 @@ The public entry exposes domain workflows that return structured domain results | Files & skills | `uploadFile`, `listFiles`, `getFileInfo`, `getFileDownloadUrl`, `deleteFile`, `createSkillFromFileId`, `listSkills`, `getSkillInfo`, `deleteSkill` | | Deployment | `listDeploymentsForContext`, `getDeploymentDetailsForContext`, `getDeploymentRuntimeProviderForContext`, `runDeploymentForContext` | | Models | `listProviderModelsForContext`, `listProviderNames` | -| Usage | `listModelUsage`, `listToolUsage` | +| Usage | `getUsageSummary` | | State | `StateManager`, `LocalFileStateBackend`, `parseStateAddress` | | Runtime context | `createProjectRuntime`, `readProjectRuntime`, `writeProjectRuntime` | | Provider config | `resolveProviderConfigFromEnv`, `applyProviderConfigToEnv`, `loadDotEnv`, `bootstrapRuntimeCredentials` (and sync variants), `resolveActiveProvider`, `AGENTS_CONFIG_PROVIDERS`, `AGENTS_PROVIDER_FIELDS` | diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts index 485e21a9..c679c588 100644 --- a/packages/sdk/src/index.ts +++ b/packages/sdk/src/index.ts @@ -376,24 +376,22 @@ export type { export type { ProviderFileInfo } from "./internal/types/file.ts"; export { listSessionThreadEvents, listSessionThreads } from "./internal/core/session-thread-runtime.ts"; export type { SessionThread, SessionThreadListOptions, SessionThreadPage } from "./internal/types/session-thread.ts"; -export { listModelUsage, listToolUsage } from "./internal/core/usage-runtime.ts"; +export { getUsageSummary } from "./internal/core/usage-runtime.ts"; export type { UsageRuntimeOptions } from "./internal/core/usage-runtime.ts"; export type { - ModelUsageItem, - ModelUsagePage, - ModelUsageRequest, - ModelUsageSortBy, - ToolUsageItem, - ToolUsagePage, - ToolUsageRequest, - ToolUsageSortBy, - UsagePage, + UsageDimension, + UsageGranularity, + UsageMetric, + UsageModelMetrics, + UsageModelRow, UsageQueryOptions, - UsageScope, - UsageSortOrder, + UsageSummary, + UsageSummaryRequest, + UsageSummaryResponse, UsageTimeRange, - UsageTokenStats, - UsageToolSource, + UsageToolMetrics, + UsageToolRow, + UsageTotal, } from "./internal/types/usage.ts"; export type { ProviderSkillInfo } from "./internal/types/skill-info.ts"; diff --git a/packages/sdk/src/internal/core/usage-runtime.ts b/packages/sdk/src/internal/core/usage-runtime.ts index 1c9e42cd..ab363fc0 100644 --- a/packages/sdk/src/internal/core/usage-runtime.ts +++ b/packages/sdk/src/internal/core/usage-runtime.ts @@ -1,10 +1,4 @@ -import type { - ModelUsagePage, - ModelUsageRequest, - ToolUsagePage, - ToolUsageRequest, - UsageQueryOptions, -} from "../types/usage.ts"; +import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../types/usage.ts"; import { type ManagedApiContext, requireManagedApiMethod, resolveManagedApiAdapter } from "./managed-api-context.ts"; export interface UsageRuntimeOptions extends UsageQueryOptions { @@ -12,24 +6,17 @@ export interface UsageRuntimeOptions extends UsageQueryOptions { provider?: string; } -/** Aggregated model usage (calls, failures, token breakdowns) for a workspace/agent/session scope. */ -export async function listModelUsage( +/** + * Aggregated usage for one dimension (app-control usage.summary). Model and tool + * details are returned by the same call, so callers render both tables from one + * response instead of issuing per-table requests. + */ +export async function getUsageSummary( ctx: ManagedApiContext, - request: ModelUsageRequest, + request: UsageSummaryRequest, options: UsageRuntimeOptions = {}, -): Promise { +): Promise { const adapter = resolveManagedApiAdapter(ctx, options.provider); - const method = requireManagedApiMethod(adapter.listModelUsage, adapter.name, "model usage listing"); - return method.call(adapter, request, { signal: options.signal }); -} - -/** Aggregated tool usage (calls, failures by tool source) for a workspace/agent/session scope. */ -export async function listToolUsage( - ctx: ManagedApiContext, - request: ToolUsageRequest, - options: UsageRuntimeOptions = {}, -): Promise { - const adapter = resolveManagedApiAdapter(ctx, options.provider); - const method = requireManagedApiMethod(adapter.listToolUsage, adapter.name, "tool usage listing"); + const method = requireManagedApiMethod(adapter.getUsageSummary, adapter.name, "usage summary"); return method.call(adapter, request, { signal: options.signal }); } diff --git a/packages/sdk/src/internal/providers/bailian/adapter.ts b/packages/sdk/src/internal/providers/bailian/adapter.ts index a00a6718..62dabffb 100644 --- a/packages/sdk/src/internal/providers/bailian/adapter.ts +++ b/packages/sdk/src/internal/providers/bailian/adapter.ts @@ -76,13 +76,7 @@ import type { SessionThreadListOptions, SessionThreadPage } from "../../types/se import type { SkillFile } from "../../types/skill-file.ts"; import type { ProviderSkillInfo } from "../../types/skill-info.ts"; import type { ResourceType } from "../../types/state.ts"; -import type { - ModelUsagePage, - ModelUsageRequest, - ToolUsagePage, - ToolUsageRequest, - UsageQueryOptions, -} from "../../types/usage.ts"; +import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../../types/usage.ts"; import type { CreateWebhookEndpointInput, UpdateWebhookEndpointInput, @@ -150,7 +144,7 @@ import { } from "./mapper.ts"; import { streamBailianSessionEvents } from "./session-stream.ts"; import { listBailianSessionThreadEvents, listBailianSessionThreads } from "./session-threads.ts"; -import { listBailianModelUsage, listBailianToolUsage } from "./usage.ts"; +import { getBailianUsageSummary } from "./usage.ts"; export class BailianAdapter implements ProviderAdapter { readonly name = "bailian" as const; @@ -1312,14 +1306,10 @@ export class BailianAdapter implements ProviderAdapter { return listBailianSessionThreadEvents(this.client, sessionId, threadId, options); } - // --- Usage (app-control usage.*) --- - - listModelUsage(request: ModelUsageRequest, options?: UsageQueryOptions): Promise { - return listBailianModelUsage(this.client, request, options); - } + // --- Usage (app-control usage.summary) --- - listToolUsage(request: ToolUsageRequest, options?: UsageQueryOptions): Promise { - return listBailianToolUsage(this.client, request, options); + getUsageSummary(request: UsageSummaryRequest, options?: UsageQueryOptions): Promise { + return getBailianUsageSummary(this.client, request, options); } // --- Files --- diff --git a/packages/sdk/src/internal/providers/bailian/usage.ts b/packages/sdk/src/internal/providers/bailian/usage.ts index fbafb74f..0d911658 100644 --- a/packages/sdk/src/internal/providers/bailian/usage.ts +++ b/packages/sdk/src/internal/providers/bailian/usage.ts @@ -1,73 +1,86 @@ import { UserError } from "../../errors.ts"; -import type { - ModelUsagePage, - ModelUsageRequest, - ToolUsagePage, - ToolUsageRequest, - UsageQueryOptions, - UsageScope, -} from "../../types/usage.ts"; +import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../../types/usage.ts"; import type { BailianClient } from "./client.ts"; -// The app-control usage RPCs (`ziel:dashy::bailian-app-control.usage.*`) map to the -// AgentStudio resource paths below (confirmed with the usage contract owner). The -// public AgentStudio deployment has not enabled them yet (404 at the gateway); -// once it does, these calls go through without further changes. If the deployed -// envelope differs from the top-level body, only the unwrapping below needs to change. -const MODEL_USAGE_PATH = "/usage/models"; -const TOOL_USAGE_PATH = "/usage/tools"; +// The app-control usage RPC (`ziel:dashy::bailian-app-control.usage.summary`) is +// published as the AgentStudio summary endpoint below (Usage API reference: +// `POST /api/v1/agentstudio/usage/summary`). Model and tool details are two views +// of the same response, so one call covers both tables — there is no per-table +// endpoint, pagination or server-side name filter. +const SUMMARY_PATH = "/usage/summary"; + +const DIMENSIONS = new Set(["workspace", "agent", "session"]); +const GRANULARITIES = new Set(["hour", "day", "month"]); /** * Cross-field request rules from the usage contract, enforced before the call: - * workspace/agent scopes require an explicit time_range (session scopes reuse the - * Session's own window and must not send one), workspace scopes must list at least - * one workspace, and pagination is 1-based with a 1..100 page size. + * - `workspace` requires a time_range and takes no agent/session; + * - `agent` requires agent_id + time_range, may pin agent_version, takes no session; + * - `session` requires session_id and forbids time_range/granularity/agent fields; + * - `granularity` is only valid for `workspace`/`agent`. */ -export function assertUsageRequest(request: ModelUsageRequest | ToolUsageRequest): void { - const scope: UsageScope = request.scope; - if (scope.type === "workspace" && !scope.workspace_ids?.length) { - throw new UserError("Usage scope 'workspace' requires a non-empty workspace_ids list."); +export function assertUsageRequest(request: UsageSummaryRequest): void { + if (!DIMENSIONS.has(request.dimension)) { + throw new UserError(`Unknown usage dimension '${request.dimension}'.`); + } + if (request.granularity !== undefined && !GRANULARITIES.has(request.granularity)) { + throw new UserError(`Unknown usage granularity '${request.granularity}'.`); + } + if (request.dimension === "session") { + assertSessionRequest(request); + return; + } + if (request.session_id !== undefined) { + throw new UserError(`Usage dimension '${request.dimension}' forbids session_id.`); + } + if (!request.time_range) { + throw new UserError(`Usage dimension '${request.dimension}' requires time_range.`); + } + assertTimeRange(request.time_range.start_time, request.time_range.end_time); + if (request.dimension === "agent") { + if (!request.agent_id) throw new UserError("Usage dimension 'agent' requires agent_id."); + return; } - if (scope.type === "session") { - if (request.time_range !== undefined) { - throw new UserError("Usage scope 'session' forbids time_range; the Session's own window is used."); - } - } else if (!request.time_range) { - throw new UserError(`Usage scope '${scope.type}' requires time_range.`); + if (request.agent_id !== undefined || request.agent_version !== undefined) { + throw new UserError("Usage dimension 'workspace' forbids agent_id and agent_version."); } - if (request.page_no !== undefined && (!Number.isInteger(request.page_no) || request.page_no < 1)) { - throw new UserError("page_no must be an integer >= 1."); +} + +function assertSessionRequest(request: UsageSummaryRequest): void { + if (!request.session_id) throw new UserError("Usage dimension 'session' requires session_id."); + if (request.time_range !== undefined) { + throw new UserError("Usage dimension 'session' forbids time_range; the Session's own window is used."); } - if ( - request.page_size !== undefined && - (!Number.isInteger(request.page_size) || request.page_size < 1 || request.page_size > 100) - ) { - throw new UserError("page_size must be an integer between 1 and 100."); + if (request.granularity !== undefined) throw new UserError("Usage dimension 'session' forbids granularity."); + if (request.agent_id !== undefined || request.agent_version !== undefined) { + throw new UserError("Usage dimension 'session' forbids agent_id and agent_version."); } } -/** The endpoint answers with `{ data: UsagePageDTO }`; tolerate a bare page for forward compatibility. */ -function unwrapPage(result: unknown): T { - const page = (result as { data?: T } | null)?.data; - return (page ?? (result as T)) as T; +/** RFC 3339 with an explicit offset; also rejects an empty or reversed window. */ +function assertTimeRange(start: string, end: string): void { + const startMs = Date.parse(start); + const endMs = Date.parse(end); + if (Number.isNaN(startMs) || Number.isNaN(endMs)) { + throw new UserError("time_range must use RFC 3339 timestamps with an explicit offset."); + } + if (startMs >= endMs) throw new UserError("time_range start_time must be before end_time."); } -export async function listBailianModelUsage( - client: BailianClient, - request: ModelUsageRequest, - options: UsageQueryOptions = {}, -): Promise { - assertUsageRequest(request); - const result = await client.post(MODEL_USAGE_PATH, request, options.signal ? { signal: options.signal } : undefined); - return unwrapPage(result); +/** The endpoint answers with `{ request_id, data: UsageSummary }`; `data` is mandatory. */ +function unwrapSummary(result: unknown): UsageSummaryResponse { + const body = result as Partial | null; + const data = body?.data; + if (!data) throw new UserError("Usage summary response is missing `data`."); + return { request_id: body.request_id ?? "", data }; } -export async function listBailianToolUsage( +export async function getBailianUsageSummary( client: BailianClient, - request: ToolUsageRequest, + request: UsageSummaryRequest, options: UsageQueryOptions = {}, -): Promise { +): Promise { assertUsageRequest(request); - const result = await client.post(TOOL_USAGE_PATH, request, options.signal ? { signal: options.signal } : undefined); - return unwrapPage(result); + const result = await client.post(SUMMARY_PATH, request, options.signal ? { signal: options.signal } : undefined); + return unwrapSummary(result); } diff --git a/packages/sdk/src/internal/providers/interface.ts b/packages/sdk/src/internal/providers/interface.ts index a54a46a9..d85d715a 100644 --- a/packages/sdk/src/internal/providers/interface.ts +++ b/packages/sdk/src/internal/providers/interface.ts @@ -74,13 +74,7 @@ import type { SessionThreadListOptions, SessionThreadPage } from "../types/sessi import type { SkillFile } from "../types/skill-file.ts"; import type { ProviderSkillInfo } from "../types/skill-info.ts"; import type { ResourceType } from "../types/state.ts"; -import type { - ModelUsagePage, - ModelUsageRequest, - ToolUsagePage, - ToolUsageRequest, - UsageQueryOptions, -} from "../types/usage.ts"; +import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../types/usage.ts"; import type { CreateWebhookEndpointInput, UpdateWebhookEndpointInput, @@ -490,16 +484,11 @@ export interface ProviderAdapter { listModels?(): Promise; /** - * Aggregated model usage rows for a scope (app-control usage.listModelUsage). - * Bailian-only today; other providers reject at the runtime seam. - */ - listModelUsage?(request: ModelUsageRequest, options?: UsageQueryOptions): Promise; - - /** - * Aggregated tool usage rows for a scope (app-control usage.listToolUsage). - * Bailian-only today; other providers reject at the runtime seam. + * Aggregated usage summary (model and tool details) for one dimension + * (app-control usage.summary). Bailian-only today; other providers reject at + * the runtime seam. */ - listToolUsage?(request: ToolUsageRequest, options?: UsageQueryOptions): Promise; + getUsageSummary?(request: UsageSummaryRequest, options?: UsageQueryOptions): Promise; /** * Download all remote skills and return their extracted file content. diff --git a/packages/sdk/src/internal/types/usage.ts b/packages/sdk/src/internal/types/usage.ts index 58ef3b14..053acd4b 100644 --- a/packages/sdk/src/internal/types/usage.ts +++ b/packages/sdk/src/internal/types/usage.ts @@ -1,97 +1,123 @@ /** - * Usage-query scope, discriminated by `type` (app-control usage.* endpoints): - * - `workspace`: aggregated over the listed workspaces (overview page); `agent_id` narrows to one Agent. - * - `agent`: one Agent (optionally a pinned version); `workspace_ids` may pin a single workspace, - * otherwise the caller's identity workspace is used. - * - `session`: one Session; the Session's own window is used, so `time_range` is forbidden and - * `workspace_ids` (if sent) is ignored. + * Usage summary scope, discriminated by `dimension` (app-control usage.summary): + * - `workspace`: aggregated over the caller's workspace; `agent_id` narrows to one Agent. + * - `agent`: one Agent (optionally a pinned version). + * - `session`: one Session; its lifecycle totals are used, so `time_range` and + * `granularity` must not be sent. */ -export type UsageScope = - | { type: "workspace"; workspace_ids: string[]; agent_id?: string } - | { type: "agent"; agent_id: string; workspace_ids?: string[]; agent_version?: string } - | { type: "session"; session_id: string }; +export type UsageDimension = "workspace" | "agent" | "session"; -/** Millisecond-precision epoch window. Required for workspace/agent scopes; forbidden for session. */ +/** Bucket size of the returned `query_range`; omitted lets the server pick from the span. */ +export type UsageGranularity = "hour" | "day" | "month"; + +/** RFC 3339 window carrying an explicit offset, e.g. `2026-11-02T10:00:00+08:00`. */ export interface UsageTimeRange { - start_time: number; - end_time: number; + start_time: string; + end_time: string; } -export type ModelUsageSortBy = "call_count" | "failed_count" | "input_tokens" | "output_tokens"; -export type ToolUsageSortBy = "call_count" | "failed_count"; -export type UsageSortOrder = "asc" | "desc"; - -export interface ModelUsageRequest { - scope: UsageScope; +export interface UsageSummaryRequest { + dimension: UsageDimension; + /** Required for the `agent` dimension; forbidden for `session`. */ + agent_id?: string; + /** Only meaningful for the `agent` dimension; null means every version. */ + agent_version?: string | null; + /** Required for the `session` dimension; forbidden for `workspace`/`agent`. */ + session_id?: string; + /** Required for `workspace`/`agent`; forbidden for `session` (the Session window is used). */ time_range?: UsageTimeRange; - /** Exact model name; omitted/null means all models. */ - model_name?: string | null; - /** 1-based page number. */ - page_no?: number; - /** Page size, clamped to 1..100 by the endpoint. */ - page_size?: number; - sort_by?: ModelUsageSortBy; - sort_order?: UsageSortOrder; + /** Only for `workspace`/`agent`; forbidden for `session`. */ + granularity?: UsageGranularity; } -export type UsageToolSource = "builtin" | "mcp" | "custom"; +/** + * Every indicator carries its own unit. An unknown indicator keeps its unit with a + * `null` value; a known zero stays `0` and must not be treated as unknown. + */ +export interface UsageMetric { + value: number | null; + unit: string; +} -export interface ToolUsageRequest { - scope: UsageScope; - time_range?: UsageTimeRange; - /** Exact tool source; omitted/null means all sources. Unknown provider values are preserved. */ - source?: UsageToolSource | null; - /** Exact tool name; omitted/null means all tools. */ - tool_name?: string | null; - page_no?: number; - page_size?: number; - /** Tool usage does not support token sorts — only call_count / failed_count. */ - sort_by?: ToolUsageSortBy; - sort_order?: UsageSortOrder; +/** Per-model indicators (`usage.models[].usage`). */ +export interface UsageModelMetrics { + input_tokens: UsageMetric; + output_tokens: UsageMetric; + total_tokens: UsageMetric; + cache_read_tokens: UsageMetric; + cache_creation_tokens: UsageMetric; + cache_hit_ratio: UsageMetric; + call_count: UsageMetric; + failed_count: UsageMetric; } -export interface UsageTokenStats { - input_tokens: number; - output_tokens: number; - cache_read_tokens: number; - cache_creation_tokens: number; - total_tokens: number; - cache_hit_ratio: number; +/** Per-tool indicators (`usage.tools[].usage`); tools carry no token or runtime columns. */ +export interface UsageToolMetrics { + call_count: UsageMetric; + failed_count: UsageMetric; } -/** One aggregated row. The paging key is workspace_id + model_name: the same model in different workspaces is not merged. */ -export interface ModelUsageItem { - workspace_id: string; - model_name: string; - call_count: number; - failed_count: number; - tokens: UsageTokenStats; +/** Whole-scope indicators (`usage.total`). */ +export interface UsageTotal { + input_tokens: UsageMetric; + output_tokens: UsageMetric; + total_tokens: UsageMetric; + cache_read_tokens: UsageMetric; + cache_creation_tokens: UsageMetric; + cache_hit_ratio: UsageMetric; + model_call_count: UsageMetric; + tool_call_count: UsageMetric; + builtin_tool_call_count: UsageMetric; + mcp_tool_call_count: UsageMetric; + custom_tool_call_count: UsageMetric; + turns: UsageMetric; + steps: UsageMetric; + interrupt_error_count: UsageMetric; + model_failed_count: UsageMetric; + tool_failed_count: UsageMetric; + runtime_ms: UsageMetric; } -/** One aggregated row. The paging key is workspace_id + source + tool_name: same-name tools from different sources are separate rows. */ -export interface ToolUsageItem { - workspace_id: string; - tool_name: string; - /** builtin | mcp | custom; unknown future values are preserved verbatim. */ - source: string; - call_count: number; - failed_count: number; +/** + * One aggregated model row. `model_name` is null when the provider could not + * attribute the calls; ordering is not guaranteed. + */ +export interface UsageModelRow { + model_name: string | null; + usage: UsageModelMetrics; } -/** Header totals come from the aggregates: token columns sum `items[].tokens`, the call total is `total_call_count`. */ -export interface UsagePage { - items: TItem[]; - /** Total rows across all pages (the paging count). */ - total: number; - /** Total calls across all pages (the headline "N calls" figure). */ - total_call_count: number; - page_no: number; - page_size: number; - data_updated_at: number; +/** + * One aggregated tool row. Rows are keyed by `source` + `tool_name`, so + * same-name tools from different sources stay separate. + */ +export interface UsageToolRow { + source: string | null; + tool_name: string | null; + usage: UsageToolMetrics; } -export type ModelUsagePage = UsagePage; -export type ToolUsagePage = UsagePage; +/** + * Aggregated usage for one scope. `total`, `models` and `tools` are three views + * of the same query — never add the total to the detail rows. + */ +export interface UsageSummary { + /** Effective window after the server aligned it to `granularity` (UTC+8). */ + query_range: UsageTimeRange; + /** Latest known data refresh time; null when no statistics exist. */ + data_updated_at: string | null; + usage: { + total: UsageTotal; + models: UsageModelRow[]; + tools: UsageToolRow[]; + }; +} + +export interface UsageSummaryResponse { + /** Server-side request id, kept for support triage. */ + request_id: string; + data: UsageSummary; +} export interface UsageQueryOptions { signal?: AbortSignal; diff --git a/packages/sdk/tests/unit/bailian-usage.test.ts b/packages/sdk/tests/unit/bailian-usage.test.ts index 2c7a7e35..9722b13d 100644 --- a/packages/sdk/tests/unit/bailian-usage.test.ts +++ b/packages/sdk/tests/unit/bailian-usage.test.ts @@ -1,139 +1,180 @@ import { afterEach, expect, test } from "bun:test"; -import { createManagedApiContext, listModelUsage, listToolUsage } from "../../src/index.ts"; +import { createManagedApiContext, getUsageSummary } from "../../src/index.ts"; import { type FetchLike, setDefaultFetch } from "../../src/internal/transport.ts"; -import type { UsageScope } from "../../src/internal/types/usage.ts"; +import type { UsageSummaryRequest } from "../../src/internal/types/usage.ts"; afterEach(() => setDefaultFetch(undefined)); const baseUrl = "https://bailian.test/api/v1/agentstudio"; const context = () => createManagedApiContext({ providers: { bailian: { api_key: "test", base_url: baseUrl } } }); -const workspaceScope: UsageScope = { type: "workspace", workspace_ids: ["ws_one"] }; -const timeRange = { start_time: 1791730260000, end_time: 1792335080000 }; +const timeRange = { start_time: "2026-11-02T10:00:00+08:00", end_time: "2026-11-02T15:00:00+08:00" }; +const metric = (value: number | null, unit = "count") => ({ value, unit }); -const modelPage = { - items: [ - { - workspace_id: "ws_one", - model_name: "qwen3-max", - call_count: 14, - failed_count: 2, - tokens: { - input_tokens: 268080, - output_tokens: 7506, - cache_read_tokens: 164000, - cache_creation_tokens: 0, - total_tokens: 275500, - cache_hit_ratio: 0.61194, - }, +const summary = { + query_range: timeRange, + data_updated_at: "2026-11-02T14:10:00+08:00", + usage: { + total: { + input_tokens: metric(1000, "tokens"), + output_tokens: metric(200, "tokens"), + total_tokens: metric(1200, "tokens"), + cache_read_tokens: metric(400, "tokens"), + cache_creation_tokens: metric(100, "tokens"), + cache_hit_ratio: metric(0.4, "ratio"), + model_call_count: metric(5), + tool_call_count: metric(3), + builtin_tool_call_count: metric(0), + mcp_tool_call_count: metric(3), + custom_tool_call_count: metric(0), + turns: metric(2), + steps: metric(8), + interrupt_error_count: metric(0), + model_failed_count: metric(1), + tool_failed_count: metric(1), + runtime_ms: metric(60000, "ms"), }, - ], - total: 1, - total_call_count: 14, - page_no: 1, - page_size: 20, - data_updated_at: 1792328000000, + models: [ + { + model_name: "qwen-plus", + usage: { + input_tokens: metric(1000, "tokens"), + output_tokens: metric(200, "tokens"), + total_tokens: metric(1200, "tokens"), + cache_read_tokens: metric(400, "tokens"), + cache_creation_tokens: metric(100, "tokens"), + cache_hit_ratio: metric(0.4, "ratio"), + call_count: metric(5), + failed_count: metric(1), + }, + }, + ], + tools: [ + { + source: "mcp", + tool_name: "web_search", + usage: { call_count: metric(3), failed_count: metric(1) }, + }, + ], + }, }; -const toolPage = { - items: [{ workspace_id: "ws_one", tool_name: "file-parser", source: "mcp", call_count: 4, failed_count: 2 }], - total: 1, - total_call_count: 6, - page_no: 1, - page_size: 20, - data_updated_at: 1792328000000, -}; +const envelope = { request_id: "req_summary_example", data: summary }; function urlOf(input: Parameters[0]) { return new URL(input instanceof Request ? input.url : input.toString()); } -test("model usage posts a top-level body on the resource path and unwraps the data page", async () => { +test("workspace summary posts the dimension body and unwraps request_id/data", async () => { let path = ""; const bodies: unknown[] = []; setDefaultFetch(async (input, init) => { path = urlOf(input).pathname; bodies.push(JSON.parse(String(init?.body ?? "{}"))); - return Response.json({ data: modelPage }); - }); - const page = await listModelUsage(context(), { - scope: workspaceScope, - time_range: timeRange, - page_no: 2, - page_size: 50, - sort_by: "input_tokens", - sort_order: "asc", - }); - expect(path).toBe("/api/v1/agentstudio/usage/models"); - expect(page).toEqual(modelPage); - expect(bodies[0]).toEqual({ - scope: workspaceScope, - time_range: timeRange, - page_no: 2, - page_size: 50, - sort_by: "input_tokens", - sort_order: "asc", + return Response.json(envelope); }); + const result = await getUsageSummary(context(), { dimension: "workspace", time_range: timeRange }); + expect(path).toBe("/api/v1/agentstudio/usage/summary"); + expect(result).toEqual(envelope); + expect(bodies[0]).toEqual({ dimension: "workspace", time_range: timeRange }); }); -test("tool usage forwards source/tool filters and tolerates a bare page without the data envelope", async () => { - let path = ""; +test("agent summary forwards agent_id, agent_version and granularity", async () => { let body: Record | undefined; - setDefaultFetch(async (input, init) => { - path = urlOf(input).pathname; + setDefaultFetch(async (_input, init) => { body = JSON.parse(String(init?.body ?? "{}")); - return Response.json(toolPage); + return Response.json(envelope); }); - const page = await listToolUsage(context(), { - scope: { type: "agent", agent_id: "agent_one" }, + await getUsageSummary(context(), { + dimension: "agent", + agent_id: "agent_one", + agent_version: null, time_range: timeRange, - source: "mcp", - tool_name: "file-parser", + granularity: "day", }); - expect(path).toBe("/api/v1/agentstudio/usage/tools"); expect(body).toEqual({ - scope: { type: "agent", agent_id: "agent_one" }, + dimension: "agent", + agent_id: "agent_one", + agent_version: null, time_range: timeRange, - source: "mcp", - tool_name: "file-parser", + granularity: "day", }); - expect(page).toEqual(toolPage); +}); + +test("session summary sends only dimension/session_id and keeps null metrics as null", async () => { + let body: Record | undefined; + setDefaultFetch(async (_input, init) => { + body = JSON.parse(String(init?.body ?? "{}")); + return Response.json({ + request_id: "req_session", + data: { + ...summary, + data_updated_at: null, + usage: { + ...summary.usage, + total: { ...summary.usage.total, input_tokens: metric(null, "tokens") }, + models: [], + tools: [], + }, + }, + }); + }); + const result = await getUsageSummary(context(), { dimension: "session", session_id: "sesn_one" }); + expect(body).toEqual({ dimension: "session", session_id: "sesn_one" }); + expect(result.data.usage.total.input_tokens).toEqual({ value: null, unit: "tokens" }); + expect(result.data.data_updated_at).toBeNull(); + expect(result.data.usage.models).toEqual([]); }); test("usage requests reject cross-field violations before any HTTP call", async () => { let requests = 0; setDefaultFetch(async () => { requests += 1; - return Response.json({ data: modelPage }); + return Response.json(envelope); }); const ctx = context(); - await expect( - listModelUsage(ctx, { scope: { type: "session", session_id: "sesn_one" }, time_range: timeRange }), - ).rejects.toThrow("forbids time_range"); - await expect(listModelUsage(ctx, { scope: { type: "agent", agent_id: "agent_one" } })).rejects.toThrow( - "requires time_range", + const reject = (request: UsageSummaryRequest, message: string) => + expect(getUsageSummary(ctx, request)).rejects.toThrow(message); + + await reject({ dimension: "session", session_id: "sesn_one", time_range: timeRange }, "forbids time_range"); + await reject({ dimension: "session", session_id: "sesn_one", granularity: "day" }, "forbids granularity"); + await reject({ dimension: "session" }, "requires session_id"); + await reject({ dimension: "agent", time_range: timeRange }, "requires agent_id"); + await reject({ dimension: "agent", agent_id: "agent_one" }, "requires time_range"); + await reject({ dimension: "workspace" }, "requires time_range"); + await reject({ dimension: "workspace", time_range: timeRange, agent_id: "agent_one" }, "forbids agent_id"); + await reject({ dimension: "workspace", time_range: timeRange, session_id: "sesn_one" }, "forbids session_id"); + await reject( + { dimension: "workspace", time_range: { start_time: "2026-11-03T00:00:00+08:00", end_time: timeRange.start_time } }, + "before end_time", ); - await expect( - listModelUsage(ctx, { scope: { type: "workspace", workspace_ids: [] }, time_range: timeRange }), - ).rejects.toThrow("non-empty workspace_ids"); - await expect(listToolUsage(ctx, { scope: workspaceScope, time_range: timeRange, page_size: 101 })).rejects.toThrow( - "between 1 and 100", + await reject( + { dimension: "workspace", time_range: { start_time: "2026-11-02 10:00:00", end_time: timeRange.end_time } }, + "RFC 3339", + ); + await reject( + { dimension: "workspace", time_range: timeRange, granularity: "week" as never }, + "Unknown usage granularity", ); expect(requests).toBe(0); }); -test("unsupported providers reject usage operations before making a request", async () => { +test("a response without data is rejected instead of yielding an empty summary", async () => { + setDefaultFetch(async () => Response.json({ request_id: "req_missing" })); + await expect(getUsageSummary(context(), { dimension: "workspace", time_range: timeRange })).rejects.toThrow( + "missing `data`", + ); +}); + +test("unsupported providers reject usage summary before making a request", async () => { const ctx = createManagedApiContext({ providers: { claude: { api_key: "test" } } }); let requests = 0; setDefaultFetch(async () => { requests += 1; - return Response.json({ data: modelPage }); + return Response.json(envelope); }); - await expect(listModelUsage(ctx, { scope: workspaceScope, time_range: timeRange })).rejects.toThrow( - "does not support model usage listing", - ); - await expect(listToolUsage(ctx, { scope: workspaceScope, time_range: timeRange })).rejects.toThrow( - "does not support tool usage listing", + await expect(getUsageSummary(ctx, { dimension: "workspace", time_range: timeRange })).rejects.toThrow( + "does not support usage summary", ); expect(requests).toBe(0); }); From a81ca4ede164aed1a211e07a84ad5cc291ae9334 Mon Sep 17 00:00:00 2001 From: kapla73 Date: Tue, 17 Nov 2026 15:04:56 +0800 Subject: [PATCH 2/4] =?UTF-8?q?feat(usage):=20=E6=96=B0=E5=A2=9E=E8=B5=84?= =?UTF-8?q?=E6=BA=90=E7=94=A8=E9=87=8F=E8=B6=8B=E5=8A=BF=E6=9F=A5=E8=AF=A2?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=20getUsageTrend?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .changeset/usage-trend.md | 10 ++ docs/reference/sdk.md | 67 ++++--- packages/sdk/docs/public-api-layers.md | 9 +- packages/sdk/src/index.ts | 8 +- .../sdk/src/internal/core/usage-runtime.ts | 23 ++- .../src/internal/providers/bailian/adapter.ts | 16 +- .../src/internal/providers/bailian/usage.ts | 117 +++++++++++-- .../sdk/src/internal/providers/interface.ts | 15 +- packages/sdk/src/internal/types/usage.ts | 75 ++++++-- .../tests/unit/bailian-usage-trend.test.ts | 165 ++++++++++++++++++ packages/sdk/tests/unit/bailian-usage.test.ts | 61 +++++++ 11 files changed, 509 insertions(+), 57 deletions(-) create mode 100644 .changeset/usage-trend.md create mode 100644 packages/sdk/tests/unit/bailian-usage-trend.test.ts diff --git a/.changeset/usage-trend.md b/.changeset/usage-trend.md new file mode 100644 index 00000000..54a95210 --- /dev/null +++ b/.changeset/usage-trend.md @@ -0,0 +1,10 @@ +--- +"@openagentpack/sdk": minor +--- + +用量查询补齐百炼官方 Usage API 的 trend 端点,并收紧 summary 契约: + +- 新增 `getUsageTrend(ctx, request, options)`(`POST /api/v1/agentstudio/usage/trend`)与 `UsageTrendRequest`、`UsageTrend`、`UsageTrendPoint`、`UsageTrendResponse`、`UsageTrendDimension`;支持 workspace/agent 维度、`hour/day/month` 分桶、`page_size`(1..100)与 `page_token` 游标分页,`has_more` / `next_page_token` 原样透传,缺数据的桶不补零 +- 抽出 `UsageBreakdown`(`total/models/tools`),summary 与 trend 共用 +- `UsageSummary.query_range` 改为可选:`session` 维度复用会话自身窗口,响应可能没有该字段 +- 请求校验对齐文档:`time_range` 只接受秒级、带偏移的 RFC 3339(拒绝小数秒与无偏移时间);`agent_id` / `session_id` / `agent_version` 不接受空白串;`granularity` 显式传 `null` 被拒绝;trend 的 `page_size` / `page_token` 非法值在发请求前拒绝 diff --git a/docs/reference/sdk.md b/docs/reference/sdk.md index ab82b909..b534c3fe 100644 --- a/docs/reference/sdk.md +++ b/docs/reference/sdk.md @@ -246,38 +246,61 @@ Session 的单一事件流获取;子线程状态不表示主会话执行结束 `SessionThreadListOptions` 和 `SessionThreadPage` 也通过 `./session-events` 导出类型, 浏览器可复用合同而无需加载 SDK 主入口或 Provider 凭据。 -### 资源用量汇总 +### 资源用量汇总与趋势 -用量汇总对接百炼 app-control 的 `usage.summary`,REST 映射为 AgentStudio 的 -`POST /api/v1/agentstudio/usage/summary`:一次请求同时返回整段范围的 `total`、模型明细 -`models[]` 与工具明细 `tools[]`,不存在按表分页或按名称筛选的端点。 +用量对接百炼 app-control 的 `usage.summary` / `usage.trend`,REST 映射为 AgentStudio 的 +`POST /api/v1/agentstudio/usage/summary` 与 `POST /api/v1/agentstudio/usage/trend`。汇总一次 +请求返回整段范围的 `total`、模型明细 `models[]` 与工具明细 `tools[]`,不存在按表分页或按 +名称筛选的端点;趋势按 `hour/day/month` 分桶返回同样的三个视图,用 `page_token` 游标分页。 | SDK 方法 | 百炼路径 | 结果 | | --- | --- | --- | | `getUsageSummary(ctx, request, options)` | `POST /usage/summary` | `UsageSummaryResponse` | - -`request` 用 `dimension` 区分三种维度:`workspace`(只传 `time_range` 与可选 `granularity`)、 -`agent`(必传 `agent_id` 与 `time_range`,可传 `agent_version`)、`session`(只传 -`session_id`;`time_range` 与 `granularity` 禁止,复用 Session 自身窗口)。`time_range` -必须是带时区偏移的 RFC 3339 字符串(响应统一 `+08:00`,区间左闭右开);`granularity` 取 -`hour/day/month`,缺省由服务端按跨度选择。校验在发起请求前完成。 - -响应 `data` 含 `query_range`(服务端按粒度对齐后的实际区间)、`data_updated_at`(无记录为 -`null`)与 `usage`;`usage.total`、`models`、`tools` 是同一范围的三个视图,不得相加。每个 -指标都是 `{ value, unit }`:未知指标 `value` 为 `null` 且保留 `unit`,已知零值为 `0`。单次 -响应模型与工具明细合计上限 10 万条。当前仅百炼实现,其他 Provider 返回明确的 unsupported -错误;支持 `AbortSignal`。 +| `getUsageTrend(ctx, request, options)` | `POST /usage/trend` | `UsageTrendResponse` | + +汇总的 `request` 用 `dimension` 区分三种维度:`workspace`(只传 `time_range` 与可选 +`granularity`)、`agent`(必传 `agent_id` 与 `time_range`,可传 `agent_version`)、 +`session`(只传 `session_id`;`time_range` 与 `granularity` 禁止,复用 Session 自身窗口)。 +趋势没有 `session` 维度:`workspace` 只传 `time_range` 与可选 `granularity`;`agent` 必传 +`agent_id` 与 `time_range`,可传 `agent_version`。趋势翻页用 `page_size`(1..100,缺省 100) +与上一页返回的 `next_page_token`;游标有效期 15 分钟,过期返回 `410`,需从第一页重新开始。 + +`time_range` 必须是秒级、带时区偏移的 RFC 3339 字符串(拒绝小数秒与无偏移本地时间;响应 +统一 `+08:00`,区间左闭右开);`granularity` 取 `hour/day/month`,缺省由服务端按跨度选择, +显式传 `null` 会被拒绝。校验在发起请求前完成。 + +汇总响应 `data` 含 `query_range`(服务端按粒度对齐后的实际区间;`session` 维度复用会话 +自身窗口,可能没有该字段)、`data_updated_at`(无记录为 `null`)与 `usage`; +`usage.total`、`models`、`tools` 是同一范围的三个视图,不得相加。每个指标都是 +`{ value, unit }`:未知指标 `value` 为 `null` 且保留 `unit`,已知零值为 `0`。汇总单次响应 +模型与工具明细合计上限 10 万条。 + +趋势响应 `data` 含 `query_range`、`granularity`、`points[]`(每个桶的 `start_time`、 +`end_time` 与同样的 `total/models/tools` 视图)以及 `has_more` / `next_page_token`。 +没有数据的桶直接缺省,不会补零;不要依赖桶数量,按 `start_time` 渲染。当前仅百炼实现, +其他 Provider 返回明确的 unsupported 错误;两个入口都支持 `AbortSignal`。 ```ts -import { getUsageSummary } from "@openagentpack/sdk"; +import { getUsageSummary, getUsageTrend } from "@openagentpack/sdk"; -const summary = await getUsageSummary(ctx, { - dimension: "workspace", - time_range: { start_time: "2026-11-02T10:00:00+08:00", end_time: "2026-11-02T15:00:00+08:00" }, -}); +const window = { start_time: "2026-11-02T10:00:00+08:00", end_time: "2026-11-02T15:00:00+08:00" }; + +const summary = await getUsageSummary(ctx, { dimension: "workspace", time_range: window }); const { total, models, tools } = summary.data.usage; const sessionSummary = await getUsageSummary(ctx, { dimension: "session", session_id: sessionId }); + +let page = await getUsageTrend(ctx, { dimension: "workspace", time_range: window, granularity: "hour" }); +const points = [...page.data.points]; +while (page.data.has_more && page.data.next_page_token) { + page = await getUsageTrend(ctx, { + dimension: "workspace", + time_range: window, + granularity: "hour", + page_token: page.data.next_page_token, + }); + points.push(...page.data.points); +} ``` ### 自建后端原始事件的浏览器转换 @@ -358,7 +381,7 @@ The public entry exposes domain workflows that return structured domain results | Files & skills | `uploadFile`, `listFiles`, `getFileInfo`, `getFileDownloadUrl`, `deleteFile`, `createSkillFromFileId`, `listSkills`, `getSkillInfo`, `deleteSkill` | | Deployment | `listDeploymentsForContext`, `getDeploymentDetailsForContext`, `getDeploymentRuntimeProviderForContext`, `runDeploymentForContext` | | Models | `listProviderModelsForContext`, `listProviderNames` | -| Usage | `getUsageSummary` | +| Usage | `getUsageSummary`, `getUsageTrend` | | State | `StateManager`, `LocalFileStateBackend`, `parseStateAddress` | | Runtime context | `createProjectRuntime`, `readProjectRuntime`, `writeProjectRuntime` | | Provider config | `resolveProviderConfigFromEnv`, `applyProviderConfigToEnv`, `loadDotEnv`, `bootstrapRuntimeCredentials` (and sync variants), `resolveActiveProvider`, `AGENTS_CONFIG_PROVIDERS`, `AGENTS_PROVIDER_FIELDS` | diff --git a/packages/sdk/docs/public-api-layers.md b/packages/sdk/docs/public-api-layers.md index cb3b9844..b0ebcdc1 100644 --- a/packages/sdk/docs/public-api-layers.md +++ b/packages/sdk/docs/public-api-layers.md @@ -36,11 +36,10 @@ New CLI and WebUI behavior should start here. planning, and sync. - Managed-resource reads: environment, skill/version/download, vault, and file metadata/content APIs with opaque cursor preservation. -- Usage analytics: 百炼的 `listModelUsage` 与 `listToolUsage` 提供 workspace/agent/session - scope 的模型调用与工具调用聚合(调用/失败次数、Token 明细、来源与名称过滤、分页排序)。 - REST 映射与百炼侧约定为 `POST /usage/models`、`POST /usage/tools`(顶层请求体); - 公网 AgentStudio 环境尚未启用(网关 404),启用后调用即通。仅百炼实现,其他 - Provider 返回明确的 unsupported 错误。 +- Usage analytics: 百炼的 `getUsageSummary` 提供 workspace/agent/session 维度的整段汇总 + (`total/models/tools` 三个视图),`getUsageTrend` 提供 workspace/agent 维度的分桶趋势 + 与游标分页;REST 映射为 `POST /usage/summary` 与 `POST /usage/trend`(顶层请求体)。 + 仅百炼实现,其他 Provider 返回明确的 unsupported 错误。 - Session workflows: creation, list/get/update/archive/delete, runs, follow-up messages, raw event send/list/stream, and summaries. 百炼子 Agent 的 `listSessionThreads` 与 `listSessionThreadEvents` 提供 Thread 列表和分页历史; diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts index c679c588..1473b88f 100644 --- a/packages/sdk/src/index.ts +++ b/packages/sdk/src/index.ts @@ -376,9 +376,10 @@ export type { export type { ProviderFileInfo } from "./internal/types/file.ts"; export { listSessionThreadEvents, listSessionThreads } from "./internal/core/session-thread-runtime.ts"; export type { SessionThread, SessionThreadListOptions, SessionThreadPage } from "./internal/types/session-thread.ts"; -export { getUsageSummary } from "./internal/core/usage-runtime.ts"; +export { getUsageSummary, getUsageTrend } from "./internal/core/usage-runtime.ts"; export type { UsageRuntimeOptions } from "./internal/core/usage-runtime.ts"; export type { + UsageBreakdown, UsageDimension, UsageGranularity, UsageMetric, @@ -392,6 +393,11 @@ export type { UsageToolMetrics, UsageToolRow, UsageTotal, + UsageTrend, + UsageTrendDimension, + UsageTrendPoint, + UsageTrendRequest, + UsageTrendResponse, } from "./internal/types/usage.ts"; export type { ProviderSkillInfo } from "./internal/types/skill-info.ts"; diff --git a/packages/sdk/src/internal/core/usage-runtime.ts b/packages/sdk/src/internal/core/usage-runtime.ts index ab363fc0..4ee403d8 100644 --- a/packages/sdk/src/internal/core/usage-runtime.ts +++ b/packages/sdk/src/internal/core/usage-runtime.ts @@ -1,4 +1,10 @@ -import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../types/usage.ts"; +import type { + UsageQueryOptions, + UsageSummaryRequest, + UsageSummaryResponse, + UsageTrendRequest, + UsageTrendResponse, +} from "../types/usage.ts"; import { type ManagedApiContext, requireManagedApiMethod, resolveManagedApiAdapter } from "./managed-api-context.ts"; export interface UsageRuntimeOptions extends UsageQueryOptions { @@ -20,3 +26,18 @@ export async function getUsageSummary( const method = requireManagedApiMethod(adapter.getUsageSummary, adapter.name, "usage summary"); return method.call(adapter, request, { signal: options.signal }); } + +/** + * Bucketed usage trend (app-control usage.trend) for `workspace`/`agent`. + * Each page carries the same `total/models/tools` views plus a `next_page_token` + * cursor; callers follow the cursor instead of assuming a fixed page count. + */ +export async function getUsageTrend( + ctx: ManagedApiContext, + request: UsageTrendRequest, + options: UsageRuntimeOptions = {}, +): Promise { + const adapter = resolveManagedApiAdapter(ctx, options.provider); + const method = requireManagedApiMethod(adapter.getUsageTrend, adapter.name, "usage trend"); + return method.call(adapter, request, { signal: options.signal }); +} diff --git a/packages/sdk/src/internal/providers/bailian/adapter.ts b/packages/sdk/src/internal/providers/bailian/adapter.ts index 62dabffb..e19b86ce 100644 --- a/packages/sdk/src/internal/providers/bailian/adapter.ts +++ b/packages/sdk/src/internal/providers/bailian/adapter.ts @@ -76,7 +76,13 @@ import type { SessionThreadListOptions, SessionThreadPage } from "../../types/se import type { SkillFile } from "../../types/skill-file.ts"; import type { ProviderSkillInfo } from "../../types/skill-info.ts"; import type { ResourceType } from "../../types/state.ts"; -import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../../types/usage.ts"; +import type { + UsageQueryOptions, + UsageSummaryRequest, + UsageSummaryResponse, + UsageTrendRequest, + UsageTrendResponse, +} from "../../types/usage.ts"; import type { CreateWebhookEndpointInput, UpdateWebhookEndpointInput, @@ -144,7 +150,7 @@ import { } from "./mapper.ts"; import { streamBailianSessionEvents } from "./session-stream.ts"; import { listBailianSessionThreadEvents, listBailianSessionThreads } from "./session-threads.ts"; -import { getBailianUsageSummary } from "./usage.ts"; +import { getBailianUsageSummary, getBailianUsageTrend } from "./usage.ts"; export class BailianAdapter implements ProviderAdapter { readonly name = "bailian" as const; @@ -1312,6 +1318,12 @@ export class BailianAdapter implements ProviderAdapter { return getBailianUsageSummary(this.client, request, options); } + // --- Usage trend (app-control usage.trend) --- + + getUsageTrend(request: UsageTrendRequest, options?: UsageQueryOptions): Promise { + return getBailianUsageTrend(this.client, request, options); + } + // --- Files --- async uploadFile(filePath: string, options?: { name?: string; purpose?: string }): Promise { diff --git a/packages/sdk/src/internal/providers/bailian/usage.ts b/packages/sdk/src/internal/providers/bailian/usage.ts index 0d911658..92b908dd 100644 --- a/packages/sdk/src/internal/providers/bailian/usage.ts +++ b/packages/sdk/src/internal/providers/bailian/usage.ts @@ -1,16 +1,33 @@ import { UserError } from "../../errors.ts"; -import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../../types/usage.ts"; +import type { + UsageQueryOptions, + UsageSummaryRequest, + UsageSummaryResponse, + UsageTrendRequest, + UsageTrendResponse, +} from "../../types/usage.ts"; import type { BailianClient } from "./client.ts"; // The app-control usage RPC (`ziel:dashy::bailian-app-control.usage.summary`) is // published as the AgentStudio summary endpoint below (Usage API reference: // `POST /api/v1/agentstudio/usage/summary`). Model and tool details are two views // of the same response, so one call covers both tables — there is no per-table -// endpoint, pagination or server-side name filter. +// endpoint, pagination or server-side name filter. The trend endpoint +// (`POST /api/v1/agentstudio/usage/trend`) serves the same breakdown per bucket, +// cursor-paged and without a `session` dimension. const SUMMARY_PATH = "/usage/summary"; +const TREND_PATH = "/usage/trend"; -const DIMENSIONS = new Set(["workspace", "agent", "session"]); +const SUMMARY_DIMENSIONS = new Set(["workspace", "agent", "session"]); +const TREND_DIMENSIONS = new Set(["workspace", "agent"]); const GRANULARITIES = new Set(["hour", "day", "month"]); +const MAX_PAGE_SIZE = 100; + +// Second precision with an explicit offset; fractional seconds and offset-less +// local times are rejected by the contract before reaching the server. +const RFC3339_SECONDS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:Z|[+-]\d{2}:\d{2})$/; + +const blank = (value: string | null | undefined): boolean => value == null || value.trim() === ""; /** * Cross-field request rules from the usage contract, enforced before the call: @@ -20,12 +37,10 @@ const GRANULARITIES = new Set(["hour", "day", "month"]); * - `granularity` is only valid for `workspace`/`agent`. */ export function assertUsageRequest(request: UsageSummaryRequest): void { - if (!DIMENSIONS.has(request.dimension)) { + if (!SUMMARY_DIMENSIONS.has(request.dimension)) { throw new UserError(`Unknown usage dimension '${request.dimension}'.`); } - if (request.granularity !== undefined && !GRANULARITIES.has(request.granularity)) { - throw new UserError(`Unknown usage granularity '${request.granularity}'.`); - } + assertGranularity(request.granularity); if (request.dimension === "session") { assertSessionRequest(request); return; @@ -38,7 +53,8 @@ export function assertUsageRequest(request: UsageSummaryRequest): void { } assertTimeRange(request.time_range.start_time, request.time_range.end_time); if (request.dimension === "agent") { - if (!request.agent_id) throw new UserError("Usage dimension 'agent' requires agent_id."); + if (blank(request.agent_id)) throw new UserError("Usage dimension 'agent' requires agent_id."); + assertAgentVersion(request.agent_version); return; } if (request.agent_id !== undefined || request.agent_version !== undefined) { @@ -46,8 +62,40 @@ export function assertUsageRequest(request: UsageSummaryRequest): void { } } +/** + * Trend rules: no `session` dimension, time_range always required, agent fields + * only for `agent`, and cursor pagination bounded by the contract. + */ +export function assertUsageTrendRequest(request: UsageTrendRequest): void { + if (!TREND_DIMENSIONS.has(request.dimension)) { + throw new UserError( + `Unknown usage trend dimension '${request.dimension}'; trend supports 'workspace' and 'agent'.`, + ); + } + assertGranularity(request.granularity); + if (!request.time_range) { + throw new UserError(`Usage trend dimension '${request.dimension}' requires time_range.`); + } + assertTimeRange(request.time_range.start_time, request.time_range.end_time); + if (request.dimension === "agent") { + if (blank(request.agent_id)) throw new UserError("Usage trend dimension 'agent' requires agent_id."); + assertAgentVersion(request.agent_version); + } else if (request.agent_id !== undefined || request.agent_version !== undefined) { + throw new UserError("Usage trend dimension 'workspace' forbids agent_id and agent_version."); + } + if ( + request.page_size !== undefined && + (!Number.isInteger(request.page_size) || request.page_size < 1 || request.page_size > MAX_PAGE_SIZE) + ) { + throw new UserError(`page_size must be an integer between 1 and ${MAX_PAGE_SIZE}.`); + } + if (request.page_token !== undefined && (typeof request.page_token !== "string" || blank(request.page_token))) { + throw new UserError("page_token must be a non-empty cursor string."); + } +} + function assertSessionRequest(request: UsageSummaryRequest): void { - if (!request.session_id) throw new UserError("Usage dimension 'session' requires session_id."); + if (blank(request.session_id)) throw new UserError("Usage dimension 'session' requires session_id."); if (request.time_range !== undefined) { throw new UserError("Usage dimension 'session' forbids time_range; the Session's own window is used."); } @@ -57,17 +105,40 @@ function assertSessionRequest(request: UsageSummaryRequest): void { } } -/** RFC 3339 with an explicit offset; also rejects an empty or reversed window. */ +function assertGranularity(granularity: unknown): void { + if (granularity === null) { + throw new UserError("usage granularity must be omitted rather than null; the server picks it from the span."); + } + if (granularity !== undefined && !GRANULARITIES.has(granularity as string)) { + throw new UserError(`Unknown usage granularity '${String(granularity)}'.`); + } +} + +function assertAgentVersion(agentVersion: string | null | undefined): void { + if (agentVersion != null && blank(agentVersion)) { + throw new UserError("agent_version must be a version string or null."); + } +} + +/** Second-precision RFC 3339 with an explicit offset; also rejects a reversed window. */ function assertTimeRange(start: string, end: string): void { + const message = + "time_range must use second-precision RFC 3339 timestamps with an explicit offset, e.g. 2026-11-02T10:00:00+08:00."; + if ( + typeof start !== "string" || + typeof end !== "string" || + !RFC3339_SECONDS.test(start) || + !RFC3339_SECONDS.test(end) + ) { + throw new UserError(message); + } const startMs = Date.parse(start); const endMs = Date.parse(end); - if (Number.isNaN(startMs) || Number.isNaN(endMs)) { - throw new UserError("time_range must use RFC 3339 timestamps with an explicit offset."); - } + if (Number.isNaN(startMs) || Number.isNaN(endMs)) throw new UserError(message); if (startMs >= endMs) throw new UserError("time_range start_time must be before end_time."); } -/** The endpoint answers with `{ request_id, data: UsageSummary }`; `data` is mandatory. */ +/** The summary endpoint answers with `{ request_id, data: UsageSummary }`; `data` is mandatory. */ function unwrapSummary(result: unknown): UsageSummaryResponse { const body = result as Partial | null; const data = body?.data; @@ -75,6 +146,14 @@ function unwrapSummary(result: unknown): UsageSummaryResponse { return { request_id: body.request_id ?? "", data }; } +/** The trend endpoint answers with `{ request_id, data: UsageTrend }`; `data` is mandatory. */ +function unwrapTrend(result: unknown): UsageTrendResponse { + const body = result as Partial | null; + const data = body?.data; + if (!data) throw new UserError("Usage trend response is missing `data`."); + return { request_id: body.request_id ?? "", data }; +} + export async function getBailianUsageSummary( client: BailianClient, request: UsageSummaryRequest, @@ -84,3 +163,13 @@ export async function getBailianUsageSummary( const result = await client.post(SUMMARY_PATH, request, options.signal ? { signal: options.signal } : undefined); return unwrapSummary(result); } + +export async function getBailianUsageTrend( + client: BailianClient, + request: UsageTrendRequest, + options: UsageQueryOptions = {}, +): Promise { + assertUsageTrendRequest(request); + const result = await client.post(TREND_PATH, request, options.signal ? { signal: options.signal } : undefined); + return unwrapTrend(result); +} diff --git a/packages/sdk/src/internal/providers/interface.ts b/packages/sdk/src/internal/providers/interface.ts index d85d715a..51184ede 100644 --- a/packages/sdk/src/internal/providers/interface.ts +++ b/packages/sdk/src/internal/providers/interface.ts @@ -74,7 +74,13 @@ import type { SessionThreadListOptions, SessionThreadPage } from "../types/sessi import type { SkillFile } from "../types/skill-file.ts"; import type { ProviderSkillInfo } from "../types/skill-info.ts"; import type { ResourceType } from "../types/state.ts"; -import type { UsageQueryOptions, UsageSummaryRequest, UsageSummaryResponse } from "../types/usage.ts"; +import type { + UsageQueryOptions, + UsageSummaryRequest, + UsageSummaryResponse, + UsageTrendRequest, + UsageTrendResponse, +} from "../types/usage.ts"; import type { CreateWebhookEndpointInput, UpdateWebhookEndpointInput, @@ -490,6 +496,13 @@ export interface ProviderAdapter { */ getUsageSummary?(request: UsageSummaryRequest, options?: UsageQueryOptions): Promise; + /** + * Bucketed usage trend for workspace/agent (app-control usage.trend). + * Cursor-paged via `page_size`/`page_token`; Bailian-only today, other + * providers reject at the runtime seam. + */ + getUsageTrend?(request: UsageTrendRequest, options?: UsageQueryOptions): Promise; + /** * Download all remote skills and return their extracted file content. * Used by `agents sync` to materialize skill sources locally. diff --git a/packages/sdk/src/internal/types/usage.ts b/packages/sdk/src/internal/types/usage.ts index 053acd4b..d695518f 100644 --- a/packages/sdk/src/internal/types/usage.ts +++ b/packages/sdk/src/internal/types/usage.ts @@ -1,13 +1,19 @@ /** * Usage summary scope, discriminated by `dimension` (app-control usage.summary): - * - `workspace`: aggregated over the caller's workspace; `agent_id` narrows to one Agent. + * - `workspace`: aggregated over the caller's whole workspace; no agent/session narrowing. * - `agent`: one Agent (optionally a pinned version). * - `session`: one Session; its lifecycle totals are used, so `time_range` and * `granularity` must not be sent. */ export type UsageDimension = "workspace" | "agent" | "session"; -/** Bucket size of the returned `query_range`; omitted lets the server pick from the span. */ +/** Trend scope: the trend endpoint has no `session` dimension. */ +export type UsageTrendDimension = "workspace" | "agent"; + +/** + * Bucket size of `query_range` and trend points. Omit it and the server picks + * from the span; do not send an explicit `null`. + */ export type UsageGranularity = "hour" | "day" | "month"; /** RFC 3339 window carrying an explicit offset, e.g. `2026-11-02T10:00:00+08:00`. */ @@ -30,6 +36,22 @@ export interface UsageSummaryRequest { granularity?: UsageGranularity; } +/** Bucketed trend for `workspace`/`agent`; `session` has no trend dimension. */ +export interface UsageTrendRequest { + dimension: UsageTrendDimension; + /** Required for the `agent` dimension; forbidden for `workspace`. */ + agent_id?: string; + /** Only meaningful for the `agent` dimension; null means every version. */ + agent_version?: string | null; + time_range: UsageTimeRange; + /** Omit to let the server pick the bucket from the span; never send null. */ + granularity?: UsageGranularity; + /** Page size 1..100; omitted means the server default (100). */ + page_size?: number; + /** Opaque cursor from the previous page's `next_page_token`; valid for 15 minutes. */ + page_token?: string; +} + /** * Every indicator carries its own unit. An unknown indicator keeps its unit with a * `null` value; a known zero stays `0` and must not be treated as unknown. @@ -98,19 +120,25 @@ export interface UsageToolRow { } /** - * Aggregated usage for one scope. `total`, `models` and `tools` are three views - * of the same query — never add the total to the detail rows. + * `total`, `models` and `tools` are three views of the same query — never add + * the total to the detail rows. */ +export interface UsageBreakdown { + total: UsageTotal; + models: UsageModelRow[]; + tools: UsageToolRow[]; +} + +/** Aggregated usage for one scope (summary endpoint). */ export interface UsageSummary { - /** Effective window after the server aligned it to `granularity` (UTC+8). */ - query_range: UsageTimeRange; + /** + * Effective window after the server aligned it to `granularity` (UTC+8). + * The `session` dimension has no caller-supplied window and may omit it. + */ + query_range?: UsageTimeRange; /** Latest known data refresh time; null when no statistics exist. */ data_updated_at: string | null; - usage: { - total: UsageTotal; - models: UsageModelRow[]; - tools: UsageToolRow[]; - }; + usage: UsageBreakdown; } export interface UsageSummaryResponse { @@ -119,6 +147,31 @@ export interface UsageSummaryResponse { data: UsageSummary; } +/** One trend bucket. Buckets without data are omitted, not zero-filled. */ +export interface UsageTrendPoint { + start_time: string; + end_time: string; + usage: UsageBreakdown; +} + +/** One page of trend buckets; `total/models/tools` describe that bucket only. */ +export interface UsageTrend { + /** Effective window after the server aligned it to `granularity` (UTC+8). */ + query_range: UsageTimeRange; + data_updated_at: string | null; + granularity: UsageGranularity; + points: UsageTrendPoint[]; + has_more: boolean; + /** Cursor for the next page; null on the last page or when it expired. */ + next_page_token: string | null; +} + +export interface UsageTrendResponse { + /** Server-side request id, kept for support triage. */ + request_id: string; + data: UsageTrend; +} + export interface UsageQueryOptions { signal?: AbortSignal; } diff --git a/packages/sdk/tests/unit/bailian-usage-trend.test.ts b/packages/sdk/tests/unit/bailian-usage-trend.test.ts new file mode 100644 index 00000000..75ac64e9 --- /dev/null +++ b/packages/sdk/tests/unit/bailian-usage-trend.test.ts @@ -0,0 +1,165 @@ +import { afterEach, expect, test } from "bun:test"; +import { createManagedApiContext, getUsageTrend } from "../../src/index.ts"; +import { type FetchLike, setDefaultFetch } from "../../src/internal/transport.ts"; +import type { UsageTrendRequest } from "../../src/internal/types/usage.ts"; + +afterEach(() => setDefaultFetch(undefined)); + +const baseUrl = "https://bailian.test/api/v1/agentstudio"; +const context = () => createManagedApiContext({ providers: { bailian: { api_key: "test", base_url: baseUrl } } }); + +const timeRange = { start_time: "2026-11-02T10:00:00+08:00", end_time: "2026-11-02T15:00:00+08:00" }; +const metric = (value: number | null, unit = "count") => ({ value, unit }); + +const total = { + input_tokens: metric(100, "tokens"), + output_tokens: metric(20, "tokens"), + total_tokens: metric(120, "tokens"), + cache_read_tokens: metric(0, "tokens"), + cache_creation_tokens: metric(0, "tokens"), + cache_hit_ratio: metric(null, "ratio"), + model_call_count: metric(1), + tool_call_count: metric(1), + builtin_tool_call_count: metric(0), + mcp_tool_call_count: metric(0), + custom_tool_call_count: metric(1), + turns: metric(1), + steps: metric(2), + interrupt_error_count: metric(0), + model_failed_count: metric(0), + tool_failed_count: metric(0), + runtime_ms: metric(3000, "ms"), +}; + +const trend = { + query_range: timeRange, + data_updated_at: "2026-11-02T15:02:00+08:00", + granularity: "hour", + points: [ + { + start_time: "2026-11-02T10:00:00+08:00", + end_time: "2026-11-02T11:00:00+08:00", + usage: { + total, + models: [{ model_name: "qwen-plus", usage: { input_tokens: metric(100, "tokens") } }], + tools: [{ source: "mcp", tool_name: "web_search", usage: { call_count: metric(1), failed_count: metric(0) } }], + }, + }, + ], + has_more: true, + next_page_token: "cursor_2", +}; + +const envelope = { request_id: "req_trend_example", data: trend }; + +function urlOf(input: Parameters[0]) { + return new URL(input instanceof Request ? input.url : input.toString()); +} + +test("workspace trend posts the cursor body and unwraps request_id/data", async () => { + let path = ""; + const bodies: unknown[] = []; + setDefaultFetch(async (input, init) => { + path = urlOf(input).pathname; + bodies.push(JSON.parse(String(init?.body ?? "{}"))); + return Response.json(envelope); + }); + const request: UsageTrendRequest = { + dimension: "workspace", + time_range: timeRange, + granularity: "hour", + page_size: 20, + page_token: "cursor_1", + }; + const result = await getUsageTrend(context(), request); + expect(path).toBe("/api/v1/agentstudio/usage/trend"); + expect(bodies[0]).toEqual(request); + expect(result).toEqual(envelope); + expect(result.data.points).toHaveLength(1); + expect(result.data.next_page_token).toBe("cursor_2"); +}); + +test("agent trend forwards agent_version null without inventing paging fields", async () => { + let body: Record | undefined; + setDefaultFetch(async (_input, init) => { + body = JSON.parse(String(init?.body ?? "{}")); + return Response.json(envelope); + }); + await getUsageTrend(context(), { + dimension: "agent", + agent_id: "agent_one", + agent_version: null, + time_range: timeRange, + }); + expect(body).toEqual({ + dimension: "agent", + agent_id: "agent_one", + agent_version: null, + time_range: timeRange, + }); +}); + +test("trend requests reject contract violations before any HTTP call", async () => { + let requests = 0; + setDefaultFetch(async () => { + requests += 1; + return Response.json(envelope); + }); + const ctx = context(); + const reject = (request: UsageTrendRequest, message: string) => + expect(getUsageTrend(ctx, request)).rejects.toThrow(message); + + await reject({ dimension: "session", time_range: timeRange } as never, "Unknown usage trend dimension"); + await reject({ dimension: "workspace" } as never, "requires time_range"); + await reject({ dimension: "workspace", agent_id: "agent_one", time_range: timeRange }, "forbids agent_id"); + await reject({ dimension: "agent", time_range: timeRange }, "requires agent_id"); + await reject({ dimension: "agent", agent_id: " ", time_range: timeRange }, "requires agent_id"); + await reject( + { dimension: "agent", agent_id: "agent_one", agent_version: " ", time_range: timeRange }, + "agent_version", + ); + await reject( + { dimension: "workspace", time_range: timeRange, granularity: "week" as never }, + "Unknown usage granularity", + ); + await reject( + { dimension: "workspace", time_range: timeRange, granularity: null as never }, + "omitted rather than null", + ); + await reject({ dimension: "workspace", time_range: timeRange, page_size: 0 }, "between 1 and 100"); + await reject({ dimension: "workspace", time_range: timeRange, page_size: 101 }, "between 1 and 100"); + await reject({ dimension: "workspace", time_range: timeRange, page_size: 1.5 }, "between 1 and 100"); + await reject({ dimension: "workspace", time_range: timeRange, page_token: " " }, "non-empty cursor"); + await reject( + { + dimension: "workspace", + time_range: { start_time: "2026-11-02 10:00:00", end_time: timeRange.end_time }, + }, + "RFC 3339", + ); + await reject( + { dimension: "workspace", time_range: { start_time: timeRange.end_time, end_time: timeRange.start_time } }, + "before end_time", + ); + expect(requests).toBe(0); +}); + +test("a trend response without data is rejected instead of yielding empty points", async () => { + setDefaultFetch(async () => Response.json({ request_id: "req_missing" })); + await expect(getUsageTrend(context(), { dimension: "workspace", time_range: timeRange })).rejects.toThrow( + "missing `data`", + ); +}); + +test("unsupported providers reject usage trend before making a request", async () => { + const ctx = createManagedApiContext({ providers: { claude: { api_key: "test" } } }); + let requests = 0; + setDefaultFetch(async () => { + requests += 1; + return Response.json(envelope); + }); + await expect(getUsageTrend(ctx, { dimension: "workspace", time_range: timeRange })).rejects.toThrow( + "does not support usage trend", + ); + expect(requests).toBe(0); +}); diff --git a/packages/sdk/tests/unit/bailian-usage.test.ts b/packages/sdk/tests/unit/bailian-usage.test.ts index 9722b13d..287e6514 100644 --- a/packages/sdk/tests/unit/bailian-usage.test.ts +++ b/packages/sdk/tests/unit/bailian-usage.test.ts @@ -166,6 +166,67 @@ test("a response without data is rejected instead of yielding an empty summary", ); }); +test("session summary may omit query_range and passes it through as absent", async () => { + setDefaultFetch(async () => + Response.json({ + request_id: "req_session_no_range", + data: { + data_updated_at: null, + usage: { total: summary.usage.total, models: [], tools: [] }, + }, + }), + ); + const result = await getUsageSummary(context(), { dimension: "session", session_id: "sesn_one" }); + expect(result.data.query_range).toBeUndefined(); +}); + +test("time_range rejects fractional seconds and offset-less local times", async () => { + let requests = 0; + setDefaultFetch(async () => { + requests += 1; + return Response.json(envelope); + }); + const ctx = context(); + const reject = (request: UsageSummaryRequest, message: string) => + expect(getUsageSummary(ctx, request)).rejects.toThrow(message); + + await reject( + { + dimension: "workspace", + time_range: { start_time: "2026-11-02T10:00:00.500+08:00", end_time: timeRange.end_time }, + }, + "RFC 3339", + ); + await reject( + { dimension: "workspace", time_range: { start_time: "2026-11-02T10:00:00", end_time: timeRange.end_time } }, + "RFC 3339", + ); + expect(requests).toBe(0); +}); + +test("blank identifiers, blank agent_version and explicit-null granularity are rejected", async () => { + let requests = 0; + setDefaultFetch(async () => { + requests += 1; + return Response.json(envelope); + }); + const ctx = context(); + const reject = (request: UsageSummaryRequest, message: string) => + expect(getUsageSummary(ctx, request)).rejects.toThrow(message); + + await reject({ dimension: "agent", agent_id: " ", time_range: timeRange }, "requires agent_id"); + await reject({ dimension: "session", session_id: " " }, "requires session_id"); + await reject( + { dimension: "agent", agent_id: "agent_one", agent_version: " ", time_range: timeRange }, + "agent_version", + ); + await reject( + { dimension: "workspace", time_range: timeRange, granularity: null as never }, + "omitted rather than null", + ); + expect(requests).toBe(0); +}); + test("unsupported providers reject usage summary before making a request", async () => { const ctx = createManagedApiContext({ providers: { claude: { api_key: "test" } } }); let requests = 0; From c26643f6967ddb2f496f22a8cf5183b98110a30a Mon Sep 17 00:00:00 2001 From: kapla73 Date: Tue, 17 Nov 2026 15:09:50 +0800 Subject: [PATCH 3/4] =?UTF-8?q?fix(usage):=20=E7=A4=BA=E4=BE=8B=E6=9C=8D?= =?UTF-8?q?=E5=8A=A1=E8=B7=AF=E7=94=B1=E6=94=B9=E7=94=A8=E5=90=88=E5=B9=B6?= =?UTF-8?q?=E5=90=8E=E7=9A=84=20getUsageSummary=20=E5=90=88=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/server/src/routes/usage.ts | 62 +++----- apps/server/src/schemas/usage.ts | 233 ++++++++++++++++--------------- 2 files changed, 135 insertions(+), 160 deletions(-) diff --git a/apps/server/src/routes/usage.ts b/apps/server/src/routes/usage.ts index 5b3c56ae..b841c638 100644 --- a/apps/server/src/routes/usage.ts +++ b/apps/server/src/routes/usage.ts @@ -1,67 +1,37 @@ import { createRoute, OpenAPIHono } from "@hono/zod-openapi"; -import { listModelUsage, listToolUsage, readProjectRuntime } from "@openagentpack/sdk"; +import { getUsageSummary, readProjectRuntime } from "@openagentpack/sdk"; import { errorResponses } from "@/schemas/common"; -import { - ListModelUsageRequestSchema, - ListToolUsageRequestSchema, - ModelUsagePageSchema, - ToolUsagePageSchema, -} from "@/schemas/usage"; +import { GetUsageSummaryRequestSchema, UsageSummaryResponseSchema } from "@/schemas/usage"; import { projectRuntimeManager } from "@/services/project-manager"; export const usageRoute = new OpenAPIHono(); -// Usage analytics proxy the resolved provider's app-control usage.* endpoints. The -// scope/time_range cross rules are validated by the request schemas (session scope -// forbids time_range; workspace/agent require it). -const listModelUsageRoute = createRoute({ +// Usage analytics proxy the resolved provider's app-control usage.summary endpoint. The +// dimension/time_range cross rules are validated by the request schema (session dimension +// forbids time_range/granularity and requires session_id; workspace/agent require +// time_range, and agent also requires agent_id). +const getUsageSummaryRoute = createRoute({ method: "post", - path: "/usage/models", - operationId: "listModelUsage", + path: "/usage/summary", + operationId: "getUsageSummary", request: { - body: { required: true, content: { "application/json": { schema: ListModelUsageRequestSchema } } }, + body: { required: true, content: { "application/json": { schema: GetUsageSummaryRequestSchema } } }, }, responses: { 200: { - description: "Paged aggregated model usage for the requested scope", - content: { "application/json": { schema: ModelUsagePageSchema } }, + description: "Aggregated usage for the requested dimension: scope totals plus model/tool detail views", + content: { "application/json": { schema: UsageSummaryResponseSchema } }, }, ...errorResponses, }, }); -usageRoute.openapi(listModelUsageRoute, async (c) => { +usageRoute.openapi(getUsageSummaryRoute, async (c) => { const request = c.req.valid("json"); await projectRuntimeManager.ensureStarted(); - const page = await readProjectRuntime(projectRuntimeManager.requireRuntimeInput(), (ctx) => { + const summary = await readProjectRuntime(projectRuntimeManager.requireRuntimeInput(), (ctx) => { const provider = ctx.config.defaults?.provider; - return listModelUsage(ctx, request, { provider }); + return getUsageSummary(ctx, request, { provider }); }); - return c.json(page, 200); -}); - -const listToolUsageRoute = createRoute({ - method: "post", - path: "/usage/tools", - operationId: "listToolUsage", - request: { - body: { required: true, content: { "application/json": { schema: ListToolUsageRequestSchema } } }, - }, - responses: { - 200: { - description: "Paged aggregated tool usage for the requested scope", - content: { "application/json": { schema: ToolUsagePageSchema } }, - }, - ...errorResponses, - }, -}); - -usageRoute.openapi(listToolUsageRoute, async (c) => { - const request = c.req.valid("json"); - await projectRuntimeManager.ensureStarted(); - const page = await readProjectRuntime(projectRuntimeManager.requireRuntimeInput(), (ctx) => { - const provider = ctx.config.defaults?.provider; - return listToolUsage(ctx, request, { provider }); - }); - return c.json(page, 200); + return c.json(summary, 200); }); diff --git a/apps/server/src/schemas/usage.ts b/apps/server/src/schemas/usage.ts index cfad304b..e9a1e5a8 100644 --- a/apps/server/src/schemas/usage.ts +++ b/apps/server/src/schemas/usage.ts @@ -1,145 +1,150 @@ import { z } from "@hono/zod-openapi"; -// Usage analytics over app-control usage.* (model call details / tool call details). -// Wire shapes mirror the SDK's usage types; paging defaults follow the usage contract -// (page 1, size 20, sort call_count desc). +// Usage analytics over app-control usage.summary. Wire shapes mirror the SDK's usage +// types: one call returns scope totals plus the model/tool breakdown views, so no +// per-table paging or sorting parameters exist anymore. + +export const UsageDimensionSchema = z.enum(["workspace", "agent", "session"]).openapi("UsageDimension"); export const UsageTimeRangeSchema = z .object({ - start_time: z.number().int().describe("Window start, Unix epoch milliseconds."), - end_time: z.number().int().describe("Window end, Unix epoch milliseconds."), + start_time: z.string().describe("Window start, RFC 3339 with an explicit offset (UTC+8 aligned)."), + end_time: z.string().describe("Window end, RFC 3339 with an explicit offset (UTC+8 aligned)."), }) .openapi("UsageTimeRange"); -export const UsageScopeSchema = z - .discriminatedUnion("type", [ - z.object({ - type: z.literal("workspace").describe("Aggregated usage across the listed workspaces."), - workspace_ids: z.array(z.string()).min(1).describe("Workspaces to aggregate; at least one is required."), - agent_id: z.string().optional().describe("Narrow the workspace aggregation to one Agent."), - }), - z.object({ - type: z.literal("agent").describe("Usage of one Agent (optionally a pinned version)."), - agent_id: z.string(), - workspace_ids: z - .array(z.string()) - .optional() - .describe("Optional single-workspace pin; omit to use the caller's identity workspace."), - agent_version: z.string().optional(), - }), - z.object({ - type: z.literal("session").describe("Usage within one Session; its own window applies."), - session_id: z.string(), - }), - ]) - .openapi("UsageScope"); - -const usagePagination = { - page_no: z.number().int().min(1).default(1).describe("1-based page number."), - page_size: z.number().int().min(1).max(100).default(20).describe("Page size, 1..100."), - sort_order: z.enum(["asc", "desc"]).default("desc"), -}; +export const UsageGranularitySchema = z.enum(["hour", "day", "month"]).openapi("UsageGranularity"); -function refineUsageTimeRange< - T extends { scope: { type: string }; time_range?: { start_time: number; end_time: number } }, ->(value: T, ctx: z.RefinementCtx): void { - if (value.scope.type === "session") { - if (value.time_range) { +export const GetUsageSummaryRequestSchema = z + .object({ + dimension: UsageDimensionSchema, + agent_id: z.string().optional().describe("Required for the agent dimension; forbidden for session."), + agent_version: z.string().nullish().describe("Only meaningful for the agent dimension; null means every version."), + session_id: z.string().optional().describe("Required for the session dimension; forbidden otherwise."), + time_range: UsageTimeRangeSchema.optional().describe("Required for workspace/agent; forbidden for session."), + granularity: UsageGranularitySchema.optional().describe("Only for workspace/agent; forbidden for session."), + }) + .superRefine((value, ctx) => { + if (value.dimension === "session") { + if (value.agent_id) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ["agent_id"], + message: "agent_id is forbidden for session dimension.", + }); + } + if (value.time_range) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ["time_range"], + message: "time_range is forbidden for session dimension; the Session's own window is used.", + }); + } + if (value.granularity) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ["granularity"], + message: "granularity is forbidden for session dimension.", + }); + } + if (!value.session_id) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ["session_id"], + message: "session_id is required for session dimension.", + }); + } + return; + } + if (value.session_id) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ["session_id"], + message: "session_id is forbidden for workspace/agent dimension.", + }); + } + if (!value.time_range) { ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["time_range"], - message: "time_range is forbidden for session scope; the Session's own window is used.", + message: `time_range is required for ${value.dimension} dimension.`, + }); + } + if (value.dimension === "agent" && !value.agent_id) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + path: ["agent_id"], + message: "agent_id is required for agent dimension.", }); } - return; - } - if (!value.time_range) { - ctx.addIssue({ - code: z.ZodIssueCode.custom, - path: ["time_range"], - message: `time_range is required for ${value.scope.type} scope.`, - }); - } -} - -export const ListModelUsageRequestSchema = z - .object({ - scope: UsageScopeSchema, - time_range: UsageTimeRangeSchema.optional(), - model_name: z.string().nullish().describe("Exact model name; omitted/null means all models."), - ...usagePagination, - sort_by: z.enum(["call_count", "failed_count", "input_tokens", "output_tokens"]).default("call_count"), }) - .superRefine(refineUsageTimeRange) - .openapi("ListModelUsageRequest"); + .openapi("GetUsageSummaryRequest"); -export const ListToolUsageRequestSchema = z - .object({ - scope: UsageScopeSchema, - time_range: UsageTimeRangeSchema.optional(), - source: z - .enum(["builtin", "mcp", "custom"]) - .nullish() - .describe("Exact tool source; omitted/null means all sources."), - tool_name: z.string().nullish().describe("Exact tool name; omitted/null means all tools."), - ...usagePagination, - sort_by: z.enum(["call_count", "failed_count"]).default("call_count"), - }) - .superRefine(refineUsageTimeRange) - .openapi("ListToolUsageRequest"); +/** Every indicator carries its own unit; unknown indicators keep their unit with a null value. */ +export const UsageMetricSchema = z.object({ value: z.number().nullable(), unit: z.string() }).openapi("UsageMetric"); -export const UsageTokenStatsSchema = z +export const UsageTotalSchema = z .object({ - input_tokens: z.number().int(), - output_tokens: z.number().int(), - cache_read_tokens: z.number().int(), - cache_creation_tokens: z.number().int(), - total_tokens: z.number().int(), - cache_hit_ratio: z.number(), + input_tokens: UsageMetricSchema, + output_tokens: UsageMetricSchema, + total_tokens: UsageMetricSchema, + cache_read_tokens: UsageMetricSchema, + cache_creation_tokens: UsageMetricSchema, + cache_hit_ratio: UsageMetricSchema, + model_call_count: UsageMetricSchema, + tool_call_count: UsageMetricSchema, + builtin_tool_call_count: UsageMetricSchema, + mcp_tool_call_count: UsageMetricSchema, + custom_tool_call_count: UsageMetricSchema, + turns: UsageMetricSchema, + steps: UsageMetricSchema, + interrupt_error_count: UsageMetricSchema, + model_failed_count: UsageMetricSchema, + tool_failed_count: UsageMetricSchema, + runtime_ms: UsageMetricSchema, }) - .openapi("UsageTokenStats"); + .openapi("UsageTotal"); -export const ModelUsageItemSchema = z +export const UsageModelRowSchema = z .object({ - workspace_id: z.string(), - model_name: z.string(), - call_count: z.number().int(), - failed_count: z.number().int(), - tokens: UsageTokenStatsSchema, + model_name: z.string().nullable().describe("Null when the provider could not attribute the calls."), + usage: z.object({ + input_tokens: UsageMetricSchema, + output_tokens: UsageMetricSchema, + total_tokens: UsageMetricSchema, + cache_read_tokens: UsageMetricSchema, + cache_creation_tokens: UsageMetricSchema, + cache_hit_ratio: UsageMetricSchema, + call_count: UsageMetricSchema, + failed_count: UsageMetricSchema, + }), }) - .openapi("ModelUsageItem"); + .openapi("UsageModelRow"); -export const ToolUsageItemSchema = z +export const UsageToolRowSchema = z .object({ - workspace_id: z.string(), - tool_name: z.string(), - source: z.string().describe("builtin | mcp | custom; unknown future values are preserved verbatim."), - call_count: z.number().int(), - failed_count: z.number().int(), + source: z.string().nullable().describe("builtin | mcp | custom; unknown future values are preserved verbatim."), + tool_name: z.string().nullable(), + usage: z.object({ call_count: UsageMetricSchema, failed_count: UsageMetricSchema }), }) - .openapi("ToolUsageItem"); + .openapi("UsageToolRow"); -// Header totals ride on the aggregates: token columns sum items[].tokens, the call -// total is total_call_count, and the paging count is total. No matches → empty items -// with zeroed totals. -export const ModelUsagePageSchema = z +// total, models and tools are three views of the same query — never add the total to the detail rows. +export const UsageSummarySchema = z .object({ - items: z.array(ModelUsageItemSchema), - total: z.number().int().describe("Total rows across all pages."), - total_call_count: z.number().int().describe("Total calls across all pages."), - page_no: z.number().int(), - page_size: z.number().int(), - data_updated_at: z.number().int().describe("Data freshness, Unix epoch milliseconds."), + query_range: UsageTimeRangeSchema.optional(), + data_updated_at: z.string().nullable().describe("Data freshness; null when no statistics exist."), + usage: z.object({ + total: UsageTotalSchema, + models: z.array(UsageModelRowSchema), + tools: z.array(UsageToolRowSchema), + }), }) - .openapi("ModelUsagePage"); + .openapi("UsageSummary"); -export const ToolUsagePageSchema = z +export const UsageSummaryResponseSchema = z .object({ - items: z.array(ToolUsageItemSchema), - total: z.number().int().describe("Total rows across all pages."), - total_call_count: z.number().int().describe("Total calls across all pages."), - page_no: z.number().int(), - page_size: z.number().int(), - data_updated_at: z.number().int().describe("Data freshness, Unix epoch milliseconds."), + request_id: z.string().describe("Server-side request id, kept for support triage."), + data: UsageSummarySchema, }) - .openapi("ToolUsagePage"); + .openapi("UsageSummaryResponse"); From f0c9d6075afd0aa32cee1b9615f38e2b8aa5c420 Mon Sep 17 00:00:00 2001 From: kapla73 Date: Tue, 17 Nov 2026 15:21:55 +0800 Subject: [PATCH 4/4] =?UTF-8?q?fix(usage):=20=E7=A4=BA=E4=BE=8B=E6=9C=8D?= =?UTF-8?q?=E5=8A=A1=E6=B5=8B=E8=AF=95=E4=B8=8E=E7=94=9F=E6=88=90=E7=89=A9?= =?UTF-8?q?=E5=AF=B9=E9=BD=90=20getUsageSummary=20=E5=90=88=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/server/openapi.json | 515 +++++++------------ apps/server/tests/usage-route.test.ts | 84 +-- apps/webui/src/lib/api/generated/schema.d.ts | 324 ++++-------- 3 files changed, 339 insertions(+), 584 deletions(-) diff --git a/apps/server/openapi.json b/apps/server/openapi.json index 78022c8b..8ca9fef5 100644 --- a/apps/server/openapi.json +++ b/apps/server/openapi.json @@ -1796,304 +1796,276 @@ }, "required": ["id", "type", "status", "created_at", "updated_at", "events"] }, - "ModelUsagePage": { + "UsageSummaryResponse": { "type": "object", "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ModelUsageItem" - } - }, - "total": { - "type": "integer", - "description": "Total rows across all pages." - }, - "total_call_count": { - "type": "integer", - "description": "Total calls across all pages." - }, - "page_no": { - "type": "integer" - }, - "page_size": { - "type": "integer" + "request_id": { + "type": "string", + "description": "Server-side request id, kept for support triage." }, - "data_updated_at": { - "type": "integer", - "description": "Data freshness, Unix epoch milliseconds." + "data": { + "$ref": "#/components/schemas/UsageSummary" } }, - "required": ["items", "total", "total_call_count", "page_no", "page_size", "data_updated_at"] + "required": ["request_id", "data"] }, - "ModelUsageItem": { + "UsageSummary": { "type": "object", "properties": { - "workspace_id": { - "type": "string" - }, - "model_name": { - "type": "string" + "query_range": { + "$ref": "#/components/schemas/UsageTimeRange" }, - "call_count": { - "type": "integer" + "data_updated_at": { + "type": "string", + "nullable": true, + "description": "Data freshness; null when no statistics exist." }, - "failed_count": { - "type": "integer" + "usage": { + "type": "object", + "properties": { + "total": { + "$ref": "#/components/schemas/UsageTotal" + }, + "models": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UsageModelRow" + } + }, + "tools": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UsageToolRow" + } + } + }, + "required": ["total", "models", "tools"] + } + }, + "required": ["data_updated_at", "usage"] + }, + "UsageTimeRange": { + "type": "object", + "properties": { + "start_time": { + "type": "string", + "description": "Window start, RFC 3339 with an explicit offset (UTC+8 aligned)." }, - "tokens": { - "$ref": "#/components/schemas/UsageTokenStats" + "end_time": { + "type": "string", + "description": "Window end, RFC 3339 with an explicit offset (UTC+8 aligned)." } }, - "required": ["workspace_id", "model_name", "call_count", "failed_count", "tokens"] + "required": ["start_time", "end_time"] }, - "UsageTokenStats": { + "UsageTotal": { "type": "object", "properties": { "input_tokens": { - "type": "integer" + "$ref": "#/components/schemas/UsageMetric" }, "output_tokens": { - "type": "integer" + "$ref": "#/components/schemas/UsageMetric" + }, + "total_tokens": { + "$ref": "#/components/schemas/UsageMetric" }, "cache_read_tokens": { - "type": "integer" + "$ref": "#/components/schemas/UsageMetric" }, "cache_creation_tokens": { - "type": "integer" - }, - "total_tokens": { - "type": "integer" + "$ref": "#/components/schemas/UsageMetric" }, "cache_hit_ratio": { - "type": "number" + "$ref": "#/components/schemas/UsageMetric" + }, + "model_call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "tool_call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "builtin_tool_call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "mcp_tool_call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "custom_tool_call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "turns": { + "$ref": "#/components/schemas/UsageMetric" + }, + "steps": { + "$ref": "#/components/schemas/UsageMetric" + }, + "interrupt_error_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "model_failed_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "tool_failed_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "runtime_ms": { + "$ref": "#/components/schemas/UsageMetric" } }, "required": [ "input_tokens", "output_tokens", + "total_tokens", "cache_read_tokens", "cache_creation_tokens", - "total_tokens", - "cache_hit_ratio" + "cache_hit_ratio", + "model_call_count", + "tool_call_count", + "builtin_tool_call_count", + "mcp_tool_call_count", + "custom_tool_call_count", + "turns", + "steps", + "interrupt_error_count", + "model_failed_count", + "tool_failed_count", + "runtime_ms" ] }, - "ListModelUsageRequest": { + "UsageMetric": { "type": "object", "properties": { - "scope": { - "$ref": "#/components/schemas/UsageScope" - }, - "time_range": { - "$ref": "#/components/schemas/UsageTimeRange" + "value": { + "type": "number", + "nullable": true }, + "unit": { + "type": "string" + } + }, + "required": ["value", "unit"] + }, + "UsageModelRow": { + "type": "object", + "properties": { "model_name": { "type": "string", "nullable": true, - "description": "Exact model name; omitted/null means all models." - }, - "page_no": { - "type": "integer", - "minimum": 1, - "default": 1, - "description": "1-based page number." - }, - "page_size": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 20, - "description": "Page size, 1..100." - }, - "sort_order": { - "type": "string", - "enum": ["asc", "desc"], - "default": "desc" + "description": "Null when the provider could not attribute the calls." }, - "sort_by": { - "type": "string", - "enum": ["call_count", "failed_count", "input_tokens", "output_tokens"], - "default": "call_count" - } - }, - "required": ["scope"] - }, - "UsageScope": { - "oneOf": [ - { + "usage": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": ["workspace"], - "description": "Aggregated usage across the listed workspaces." + "input_tokens": { + "$ref": "#/components/schemas/UsageMetric" }, - "workspace_ids": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "description": "Workspaces to aggregate; at least one is required." + "output_tokens": { + "$ref": "#/components/schemas/UsageMetric" }, - "agent_id": { - "type": "string", - "description": "Narrow the workspace aggregation to one Agent." - } - }, - "required": ["type", "workspace_ids"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["agent"], - "description": "Usage of one Agent (optionally a pinned version)." + "total_tokens": { + "$ref": "#/components/schemas/UsageMetric" }, - "agent_id": { - "type": "string" + "cache_read_tokens": { + "$ref": "#/components/schemas/UsageMetric" }, - "workspace_ids": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Optional single-workspace pin; omit to use the caller's identity workspace." + "cache_creation_tokens": { + "$ref": "#/components/schemas/UsageMetric" }, - "agent_version": { - "type": "string" - } - }, - "required": ["type", "agent_id"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["session"], - "description": "Usage within one Session; its own window applies." + "cache_hit_ratio": { + "$ref": "#/components/schemas/UsageMetric" }, - "session_id": { - "type": "string" + "call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "failed_count": { + "$ref": "#/components/schemas/UsageMetric" } }, - "required": ["type", "session_id"] - } - ] - }, - "UsageTimeRange": { - "type": "object", - "properties": { - "start_time": { - "type": "integer", - "description": "Window start, Unix epoch milliseconds." - }, - "end_time": { - "type": "integer", - "description": "Window end, Unix epoch milliseconds." - } - }, - "required": ["start_time", "end_time"] - }, - "ToolUsagePage": { - "type": "object", - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ToolUsageItem" - } - }, - "total": { - "type": "integer", - "description": "Total rows across all pages." - }, - "total_call_count": { - "type": "integer", - "description": "Total calls across all pages." - }, - "page_no": { - "type": "integer" - }, - "page_size": { - "type": "integer" - }, - "data_updated_at": { - "type": "integer", - "description": "Data freshness, Unix epoch milliseconds." + "required": [ + "input_tokens", + "output_tokens", + "total_tokens", + "cache_read_tokens", + "cache_creation_tokens", + "cache_hit_ratio", + "call_count", + "failed_count" + ] } }, - "required": ["items", "total", "total_call_count", "page_no", "page_size", "data_updated_at"] + "required": ["model_name", "usage"] }, - "ToolUsageItem": { + "UsageToolRow": { "type": "object", "properties": { - "workspace_id": { - "type": "string" - }, - "tool_name": { - "type": "string" - }, "source": { "type": "string", + "nullable": true, "description": "builtin | mcp | custom; unknown future values are preserved verbatim." }, - "call_count": { - "type": "integer" + "tool_name": { + "type": "string", + "nullable": true }, - "failed_count": { - "type": "integer" + "usage": { + "type": "object", + "properties": { + "call_count": { + "$ref": "#/components/schemas/UsageMetric" + }, + "failed_count": { + "$ref": "#/components/schemas/UsageMetric" + } + }, + "required": ["call_count", "failed_count"] } }, - "required": ["workspace_id", "tool_name", "source", "call_count", "failed_count"] + "required": ["source", "tool_name", "usage"] }, - "ListToolUsageRequest": { + "GetUsageSummaryRequest": { "type": "object", "properties": { - "scope": { - "$ref": "#/components/schemas/UsageScope" + "dimension": { + "$ref": "#/components/schemas/UsageDimension" }, - "time_range": { - "$ref": "#/components/schemas/UsageTimeRange" - }, - "source": { + "agent_id": { "type": "string", - "nullable": true, - "enum": ["builtin", "mcp", "custom", null], - "description": "Exact tool source; omitted/null means all sources." + "description": "Required for the agent dimension; forbidden for session." }, - "tool_name": { + "agent_version": { "type": "string", "nullable": true, - "description": "Exact tool name; omitted/null means all tools." - }, - "page_no": { - "type": "integer", - "minimum": 1, - "default": 1, - "description": "1-based page number." - }, - "page_size": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 20, - "description": "Page size, 1..100." - }, - "sort_order": { - "type": "string", - "enum": ["asc", "desc"], - "default": "desc" + "description": "Only meaningful for the agent dimension; null means every version." }, - "sort_by": { + "session_id": { "type": "string", - "enum": ["call_count", "failed_count"], - "default": "call_count" + "description": "Required for the session dimension; forbidden otherwise." + }, + "time_range": { + "allOf": [ + { + "$ref": "#/components/schemas/UsageTimeRange" + }, + { + "description": "Required for workspace/agent; forbidden for session." + } + ] + }, + "granularity": { + "$ref": "#/components/schemas/UsageGranularity" } }, - "required": ["scope"] + "required": ["dimension"] + }, + "UsageDimension": { + "type": "string", + "enum": ["workspace", "agent", "session"] + }, + "UsageGranularity": { + "type": "string", + "enum": ["hour", "day", "month"], + "description": "Only for workspace/agent; forbidden for session." } }, "parameters": {} @@ -5019,113 +4991,26 @@ } } }, - "/api/usage/models": { - "post": { - "operationId": "listModelUsage", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ListModelUsageRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Paged aggregated model usage for the requested scope", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ModelUsagePage" - } - } - } - }, - "400": { - "description": "Bad request", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "500": { - "description": "Server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - } - } - } - }, - "/api/usage/tools": { + "/api/usage/summary": { "post": { - "operationId": "listToolUsage", + "operationId": "getUsageSummary", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ListToolUsageRequest" + "$ref": "#/components/schemas/GetUsageSummaryRequest" } } } }, "responses": { "200": { - "description": "Paged aggregated tool usage for the requested scope", + "description": "Aggregated usage for the requested dimension: scope totals plus model/tool detail views", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ToolUsagePage" + "$ref": "#/components/schemas/UsageSummaryResponse" } } } diff --git a/apps/server/tests/usage-route.test.ts b/apps/server/tests/usage-route.test.ts index 25ba8d21..982ab590 100644 --- a/apps/server/tests/usage-route.test.ts +++ b/apps/server/tests/usage-route.test.ts @@ -19,7 +19,10 @@ let originalEnvironment: Map; let directory: string; let manager: ProjectRuntimeManager; const spies: Array<{ mockRestore(): void }> = []; -const page = { items: [], total: 0, total_call_count: 0, page_no: 1, page_size: 20, data_updated_at: 0 }; +const summaryResponse = { + request_id: "req_test", + data: { data_updated_at: null, usage: { total: {}, models: [], tools: [] } }, +}; beforeEach(async () => { originalEnvironment = new Map(environmentKeys.map((key) => [key, process.env[key]])); @@ -50,46 +53,61 @@ afterEach(async () => { if (directory) await rm(directory, { recursive: true, force: true }); }); -function usageRequest(path: string) { - return app.request(path, { +function usageRequest() { + return app.request("/api/usage/summary", { method: "POST", headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ scope: { type: "session", session_id: "test-session" } }), + body: JSON.stringify({ dimension: "session", session_id: "test-session" }), }); } describe("Workbench usage Provider selection", () => { - for (const [resource, processCredentials] of [ - ["models", false], - ["tools", true], - ] as const) { - test(`${resource} uses project-local credentials when process credentials are ${processCredentials ? "different" : "absent"}`, async () => { - if (processCredentials) { - process.env.DASHSCOPE_API_KEY = "environment-test-key"; - process.env.BAILIAN_BASE_URL = "https://environment-provider.test/api/v1/agentstudio"; - process.env.AGENTS_PROVIDER = "claude"; - } - const calls: Array<{ url: string; authorization: string | null }> = []; - setDefaultFetch(async (input, init) => { - calls.push({ - url: input instanceof Request ? input.url : input.toString(), - authorization: new Headers(init?.headers).get("Authorization"), - }); - return Response.json({ data: page }); + test("uses project-local credentials when process credentials are absent", async () => { + const calls: Array<{ url: string; authorization: string | null }> = []; + setDefaultFetch(async (input, init) => { + calls.push({ + url: input instanceof Request ? input.url : input.toString(), + authorization: new Headers(init?.headers).get("Authorization"), }); + return Response.json(summaryResponse); + }); + + const response = await usageRequest(); - const response = await usageRequest(`/api/usage/${resource}`); + expect(response.status).toBe(200); + expect(await response.json()).toEqual(summaryResponse); + expect(calls).toEqual([ + { + url: "https://project-provider.test/api/v1/agentstudio/usage/summary", + authorization: "Bearer project-test-key", + }, + ]); + }); - expect(response.status).toBe(200); - expect(await response.json()).toEqual(page); - expect(calls).toEqual([ - { - url: `https://project-provider.test/api/v1/agentstudio/usage/${resource}`, - authorization: "Bearer project-test-key", - }, - ]); + test("uses project-local credentials when process credentials are different", async () => { + process.env.DASHSCOPE_API_KEY = "environment-test-key"; + process.env.BAILIAN_BASE_URL = "https://environment-provider.test/api/v1/agentstudio"; + process.env.AGENTS_PROVIDER = "claude"; + const calls: Array<{ url: string; authorization: string | null }> = []; + setDefaultFetch(async (input, init) => { + calls.push({ + url: input instanceof Request ? input.url : input.toString(), + authorization: new Headers(init?.headers).get("Authorization"), + }); + return Response.json(summaryResponse); }); - } + + const response = await usageRequest(); + + expect(response.status).toBe(200); + expect(await response.json()).toEqual(summaryResponse); + expect(calls).toEqual([ + { + url: "https://project-provider.test/api/v1/agentstudio/usage/summary", + authorization: "Bearer project-test-key", + }, + ]); + }); test("rejects a missing project instead of querying with process credentials", async () => { await rm(join(directory, "project.json")); @@ -100,10 +118,10 @@ describe("Workbench usage Provider selection", () => { let requests = 0; setDefaultFetch(async () => { requests += 1; - return Response.json({ data: page }); + return Response.json(summaryResponse); }); - const response = await usageRequest("/api/usage/models"); + const response = await usageRequest(); expect(response.status).toBe(422); expect(await response.json()).toMatchObject({ error: { message: expect.stringContaining("missing") } }); diff --git a/apps/webui/src/lib/api/generated/schema.d.ts b/apps/webui/src/lib/api/generated/schema.d.ts index d1746cab..bed143a7 100644 --- a/apps/webui/src/lib/api/generated/schema.d.ts +++ b/apps/webui/src/lib/api/generated/schema.d.ts @@ -2765,7 +2765,7 @@ export interface paths { patch?: never; trace?: never; }; - "/api/usage/models": { + "/api/usage/summary": { parameters: { query?: never; header?: never; @@ -2774,23 +2774,7 @@ export interface paths { }; get?: never; put?: never; - post: operations["listModelUsage"]; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/usage/tools": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - get?: never; - put?: never; - post: operations["listToolUsage"]; + post: operations["getUsageSummary"]; delete?: never; options?: never; head?: never; @@ -3493,145 +3477,91 @@ export interface components { result?: unknown; error?: string; }; - ModelUsagePage: { - items: components["schemas"]["ModelUsageItem"][]; - /** @description Total rows across all pages. */ - total: number; - /** @description Total calls across all pages. */ - total_call_count: number; - page_no: number; - page_size: number; - /** @description Data freshness, Unix epoch milliseconds. */ - data_updated_at: number; - }; - ModelUsageItem: { - workspace_id: string; - model_name: string; - call_count: number; - failed_count: number; - tokens: components["schemas"]["UsageTokenStats"]; - }; - UsageTokenStats: { - input_tokens: number; - output_tokens: number; - cache_read_tokens: number; - cache_creation_tokens: number; - total_tokens: number; - cache_hit_ratio: number; - }; - ListModelUsageRequest: { - scope: components["schemas"]["UsageScope"]; - time_range?: components["schemas"]["UsageTimeRange"]; - /** @description Exact model name; omitted/null means all models. */ - model_name?: string | null; - /** - * @description 1-based page number. - * @default 1 - */ - page_no: number; - /** - * @description Page size, 1..100. - * @default 20 - */ - page_size: number; - /** - * @default desc - * @enum {string} - */ - sort_order: "asc" | "desc"; - /** - * @default call_count - * @enum {string} - */ - sort_by: "call_count" | "failed_count" | "input_tokens" | "output_tokens"; - }; - UsageScope: - | { - /** - * @description Aggregated usage across the listed workspaces. - * @enum {string} - */ - type: "workspace"; - /** @description Workspaces to aggregate; at least one is required. */ - workspace_ids: string[]; - /** @description Narrow the workspace aggregation to one Agent. */ - agent_id?: string; - } - | { - /** - * @description Usage of one Agent (optionally a pinned version). - * @enum {string} - */ - type: "agent"; - agent_id: string; - /** @description Optional single-workspace pin; omit to use the caller's identity workspace. */ - workspace_ids?: string[]; - agent_version?: string; - } - | { - /** - * @description Usage within one Session; its own window applies. - * @enum {string} - */ - type: "session"; - session_id: string; - }; + UsageSummaryResponse: { + /** @description Server-side request id, kept for support triage. */ + request_id: string; + data: components["schemas"]["UsageSummary"]; + }; + UsageSummary: { + query_range?: components["schemas"]["UsageTimeRange"]; + /** @description Data freshness; null when no statistics exist. */ + data_updated_at: string | null; + usage: { + total: components["schemas"]["UsageTotal"]; + models: components["schemas"]["UsageModelRow"][]; + tools: components["schemas"]["UsageToolRow"][]; + }; + }; UsageTimeRange: { - /** @description Window start, Unix epoch milliseconds. */ - start_time: number; - /** @description Window end, Unix epoch milliseconds. */ - end_time: number; - }; - ToolUsagePage: { - items: components["schemas"]["ToolUsageItem"][]; - /** @description Total rows across all pages. */ - total: number; - /** @description Total calls across all pages. */ - total_call_count: number; - page_no: number; - page_size: number; - /** @description Data freshness, Unix epoch milliseconds. */ - data_updated_at: number; - }; - ToolUsageItem: { - workspace_id: string; - tool_name: string; + /** @description Window start, RFC 3339 with an explicit offset (UTC+8 aligned). */ + start_time: string; + /** @description Window end, RFC 3339 with an explicit offset (UTC+8 aligned). */ + end_time: string; + }; + UsageTotal: { + input_tokens: components["schemas"]["UsageMetric"]; + output_tokens: components["schemas"]["UsageMetric"]; + total_tokens: components["schemas"]["UsageMetric"]; + cache_read_tokens: components["schemas"]["UsageMetric"]; + cache_creation_tokens: components["schemas"]["UsageMetric"]; + cache_hit_ratio: components["schemas"]["UsageMetric"]; + model_call_count: components["schemas"]["UsageMetric"]; + tool_call_count: components["schemas"]["UsageMetric"]; + builtin_tool_call_count: components["schemas"]["UsageMetric"]; + mcp_tool_call_count: components["schemas"]["UsageMetric"]; + custom_tool_call_count: components["schemas"]["UsageMetric"]; + turns: components["schemas"]["UsageMetric"]; + steps: components["schemas"]["UsageMetric"]; + interrupt_error_count: components["schemas"]["UsageMetric"]; + model_failed_count: components["schemas"]["UsageMetric"]; + tool_failed_count: components["schemas"]["UsageMetric"]; + runtime_ms: components["schemas"]["UsageMetric"]; + }; + UsageMetric: { + value: number | null; + unit: string; + }; + UsageModelRow: { + /** @description Null when the provider could not attribute the calls. */ + model_name: string | null; + usage: { + input_tokens: components["schemas"]["UsageMetric"]; + output_tokens: components["schemas"]["UsageMetric"]; + total_tokens: components["schemas"]["UsageMetric"]; + cache_read_tokens: components["schemas"]["UsageMetric"]; + cache_creation_tokens: components["schemas"]["UsageMetric"]; + cache_hit_ratio: components["schemas"]["UsageMetric"]; + call_count: components["schemas"]["UsageMetric"]; + failed_count: components["schemas"]["UsageMetric"]; + }; + }; + UsageToolRow: { /** @description builtin | mcp | custom; unknown future values are preserved verbatim. */ - source: string; - call_count: number; - failed_count: number; - }; - ListToolUsageRequest: { - scope: components["schemas"]["UsageScope"]; - time_range?: components["schemas"]["UsageTimeRange"]; - /** - * @description Exact tool source; omitted/null means all sources. - * @enum {string|null} - */ - source?: "builtin" | "mcp" | "custom" | null; - /** @description Exact tool name; omitted/null means all tools. */ - tool_name?: string | null; - /** - * @description 1-based page number. - * @default 1 - */ - page_no: number; - /** - * @description Page size, 1..100. - * @default 20 - */ - page_size: number; - /** - * @default desc - * @enum {string} - */ - sort_order: "asc" | "desc"; - /** - * @default call_count - * @enum {string} - */ - sort_by: "call_count" | "failed_count"; + source: string | null; + tool_name: string | null; + usage: { + call_count: components["schemas"]["UsageMetric"]; + failed_count: components["schemas"]["UsageMetric"]; + }; }; + GetUsageSummaryRequest: { + dimension: components["schemas"]["UsageDimension"]; + /** @description Required for the agent dimension; forbidden for session. */ + agent_id?: string; + /** @description Only meaningful for the agent dimension; null means every version. */ + agent_version?: string | null; + /** @description Required for the session dimension; forbidden otherwise. */ + session_id?: string; + time_range?: components["schemas"]["UsageTimeRange"] & unknown; + granularity?: components["schemas"]["UsageGranularity"]; + }; + /** @enum {string} */ + UsageDimension: "workspace" | "agent" | "session"; + /** + * @description Only for workspace/agent; forbidden for session. + * @enum {string} + */ + UsageGranularity: "hour" | "day" | "month"; }; responses: never; parameters: never; @@ -3641,85 +3571,7 @@ export interface components { } export type $defs = Record; export interface operations { - listModelUsage: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - requestBody: { - content: { - "application/json": components["schemas"]["ListModelUsageRequest"]; - }; - }; - responses: { - /** @description Paged aggregated model usage for the requested scope */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ModelUsagePage"]; - }; - }; - /** @description Bad request */ - 400: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ErrorResponse"]; - }; - }; - /** @description Forbidden */ - 403: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ErrorResponse"]; - }; - }; - /** @description Not found */ - 404: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ErrorResponse"]; - }; - }; - /** @description Conflict */ - 409: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ErrorResponse"]; - }; - }; - /** @description Unprocessable entity */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ErrorResponse"]; - }; - }; - /** @description Server error */ - 500: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ErrorResponse"]; - }; - }; - }; - }; - listToolUsage: { + getUsageSummary: { parameters: { query?: never; header?: never; @@ -3728,17 +3580,17 @@ export interface operations { }; requestBody: { content: { - "application/json": components["schemas"]["ListToolUsageRequest"]; + "application/json": components["schemas"]["GetUsageSummaryRequest"]; }; }; responses: { - /** @description Paged aggregated tool usage for the requested scope */ + /** @description Aggregated usage for the requested dimension: scope totals plus model/tool detail views */ 200: { headers: { [name: string]: unknown; }; content: { - "application/json": components["schemas"]["ToolUsagePage"]; + "application/json": components["schemas"]["UsageSummaryResponse"]; }; }; /** @description Bad request */