@openagentpack/sdk is the Node-compatible TypeScript project/runtime SDK that powers the agents CLI. The same package exports Node-only local snapshots from @openagentpack/sdk/project-versions and directory Build/Publish services from @openagentpack/sdk/project-workspace. These subpaths share the SDK's validation, transport, and error types without adding project services to the default entry. See directory projects, local versions, and the public API contract.
npm install @openagentpack/sdkimport { resolveProjectConfig, planProjectContext } from "@openagentpack/sdk";
const config = await resolveProjectConfig({ configPath: "agents.yaml" });
const plan = await planProjectContext(config);
console.log(plan);The package entry is .. It also exposes three narrow, browser-safe subpath contracts:
./session-events— session event streaming/parsing (browser-safe)../scan-lifecycle— scan lifecycle helpers../file-lifecycle— file lifecycle helpers.
Everything re-exported from these entries is public SDK surface. The engine itself lives under src/internal/ and is deliberately not reachable from outside the package — there is no exports condition that resolves into it.
@openagentpack/sdk/session-events 导出的 sanitizeSessionEvent() 和
sanitizeSessionEvents() 接受同一个 SessionEventSanitizerOptions 配置。
SDK 保持默认脱敏、默认截断;完整 SSE 的调用方可以显式关闭这两种处理:
import {
sanitizeSessionEvent,
sanitizeSessionEvents,
type SessionEventSanitizerOptions,
} from "@openagentpack/sdk/session-events";
sanitizeSessionEvent(event); // 保持默认脱敏和截断
sanitizeSessionEvent(event, { redact: false }); // 仅关闭脱敏
sanitizeSessionEvent(event, { truncate: false }); // 仅关闭截断
const completeContent: SessionEventSanitizerOptions = { redact: false, truncate: false };
sanitizeSessionEvent(event, completeContent); // 完整 SSE 内容的显式策略
sanitizeSessionEvents(events, { ...completeContent, includeRaw: true });redact默认true,控制正文、错误文本、metadata.tool_input和可选metadata.raw中的敏感文本替换;仅影响本次调用,不改变全局配置。truncate默认true,保留原有上限:普通正文 4000 字符、工具正文 8000 字符、 检出的 HTML/SVG/Mermaid 文档 32000 字符、可选 raw 16000 字符。 只有显式传入false才取消这些长度限制。旧legacy投影中的metadata.tool_input保持原有长度;新snapshot模式中的工具参数按工具文本上限处理。- 两个开关互相独立,同时开启时先脱敏再截断。
metadata.redacted和metadata.truncated仅在对应处理实际改变数据时设置为true。 includeRaw默认false,独立控制是否包含 Provider 原始数据;开启后同样遵循 两个策略。关闭脱敏和截断不会自动返回 raw。- 脱敏沿用关键词和 URL 参数匹配规则,Markdown 媒体及下载链接的保留规则不变。
新
snapshot路径还识别结构化对象中的api_key、authorization、secret、token等敏感字段,但不承诺识别任意业务敏感信息。 - 存在
ProviderSessionEvent.snapshot时,sanitizer 优先深拷贝该结构,递归处理文本叶子, 保留对象、数组、身份、状态和内容块索引。截断不会把整个对象变成残缺的 JSON 字符串。 显式content: []不会被旧的正文便利字段重新填充。 身份字段的豁免只适用于协议中的明确位置;工具参数、输出及未知业务数据内同名的code、id、status等字段仍按所选策略脱敏和截断,包括metadata.tool_input与可选 raw。 - 仅关闭内容策略不会开启增量或补齐旧
legacy投影;需要结构化内容时同时选择 下文的snapshot模式。 streamSessionEvents()、listSessionEvents()和listSessionThreadEvents()返回ProviderSessionEvent; 内容策略在转换为契约SessionEvent时传入,不是 Provider 请求参数。
此能力针对百炼 BMA Session 的 /sessions/{session_id}/events/stream 协议。
SSE 是传输方式;event_deltas 决定是否订阅消息生成期间的正文和推理分片。
2026-10-28 的 BMA 实测流使用混合 envelope:生成期间发送 event_start/event_delta,
完成时仍发送完整 object: "message", status: "completed" 事件,最后由独立的
session_status 表示会话状态。SDK 同时兼容既有 object: "content" / msg_id / delta 分片。
这里只覆盖该 BMA 合同,不表示支持任意 CMA envelope 或 Responses API 流式格式。
旧调用不传新选项时仍使用 event_format: "legacy":不请求增量,不新增累计快照,
ProviderSessionEvent 的原有便利字段与 sanitizer 默认策略保持不变。
event_format: "snapshot" 可用于完整事件流或历史查询,不要求同时开启增量。
| 选项 | 适用入口 | 默认与含义 |
|---|---|---|
event_format |
历史、流式 | "legacy";设置 "snapshot" 保留结构化事件 |
event_deltas |
流式 | 不传;非空 ("message" | "reasoning")[] 请求相应内容分片,自动选择 snapshot |
signal |
历史、流式 | 不传;取消请求、流读取及恢复等待 |
onReady |
流式 | 不传;每次 HTTP 连接成功且 reader 建立后调用 |
reconnect |
流式 | false;仅百炼 snapshot 模式支持自动恢复 |
connectTimeoutMs |
流式 | snapshot 默认 30000 毫秒;连接就绪前超时 |
idleTimeoutMs |
流式 | snapshot 默认 180000 毫秒;任何网络数据、注释和心跳均计为活动 |
显式 event_format: "legacy" 与非空 event_deltas 冲突时直接报错。
非百炼 Provider 请求快照、增量或这些流生命周期配置时明确报不支持,不会静默忽略。
超时必须是正的有限数值。event_deltas 才会编码为百炼的 event_deltas[] 查询参数,
其余新选项由 SDK 本地处理。
streamSessionEvents() 的流选项直接放在第三个参数中;
startSessionRun() 和 sendSessionMessageStreaming() 则放在 options.stream 中:
import {
sendSessionMessageStreaming,
streamSessionEvents,
type ProjectRuntimeContext,
type SessionEvent,
} from "@openagentpack/sdk";
import { sanitizeSessionEvent } from "@openagentpack/sdk/session-events";
// ctx 使用调用方已经配置好的百炼 runtime;本函数只订阅,不发送用户消息。
async function watchSession(
ctx: ProjectRuntimeContext,
sessionId: string,
signal: AbortSignal,
onEvent: (event: SessionEvent) => void,
) {
for await (const event of streamSessionEvents(ctx, sessionId, {
provider: "bailian",
event_deltas: ["message", "reasoning"], // 自动选择 snapshot
signal,
reconnect: true, // 默认关闭;此例显式开启
onReady: () => console.info("SSE connection established"),
})) {
onEvent(sanitizeSessionEvent(event, { redact: false, truncate: false }));
}
}
// 高层发送入口负责先建立订阅,再发送一次消息。
async function sendMessage(ctx: ProjectRuntimeContext, sessionId: string, signal: AbortSignal) {
return sendSessionMessageStreaming(ctx, sessionId, "请介绍一下这个项目", {
provider: "bailian",
stream: { event_deltas: ["message", "reasoning"], signal },
});
}高层发送返回的事件迭代器也需要使用 for await 消费,才能驱动订阅和发送。
onReady 表示客户端 HTTP 连接及 reader 已建立,不代表首个业务事件已到达,
也不额外保证服务端已将订阅登记到它的执行系统。
新模式每次输出的 ProviderSessionEvent.snapshot 都使用现有 SessionEvent 契约。
分片累计后的正文可能依次为 你、你好、你好!,它们沿用同一个 event_id。
调用方应按 ID 替换同一条消息的快照,不能把每次快照当作新消息追加,也不能按 ID
只保留第一次结果。无 ID 的状态事件仍应独立处理。
content[]保留正文、推理、工具数据、多模态和未知内容块;delta: true追加到 对应索引,delta: false替换该块。最终消息显式携带的content具有权威性。 空字符串或content: []表示清空,字段缺失表示保留已有值。- BMA
event_start.event提供业务事件的id/type,可选角色、线程与时间字段原样保留; 缺失字段不猜测,待完整事件补齐。event_delta.event_id关联同一事件:reasoning_delta.reasoning累积推理文本,content_delta.content按index累积文本内容。 这些 envelope 不作为独立业务事件输出,也不推进完成游标;先到的分片有界暂存,直到身份到达。 实测结束帧是完整消息,不据此定义event_end行为,更不把消息完成当作会话结束。 metadata.event_status是消息生命周期,如in_progress/completed;metadata.status是会话运行状态,如running/idle,两者不能互相替代。- 工具调用通过
call_id关联,保留参数和输出的字符串或对象形态、错误标记、MCP 信息; 线程路由、结构化停止原因与审批字段保留到内容或元数据中。 SDK 不会自动批准工具调用,也不会把不同审批字段改写成同一种协议。 metadata.artifacts[]是 SDK 派生字段,不是 SSE 原生字段:SDK 仅在工具名或call_id关联确认是mark_artifacts结果后,从output.marked[]提取有效文件。 原始marked/failed结果仍保留在内容里;首个文件同时提供metadata.artifact。 SDK 不从普通文本猜测产物,也不自动获取下载 URL。- 每次快照都是独立对象,后续分片不会修改已交付的快照。
ProviderSessionEvent.raw始终是实际触发该次输出的上游帧,不是伪造的累计帧。 sanitizer 仅在includeRaw: true时将它放进metadata.raw。
历史查询同样显式选择 snapshot,分页继续使用 Provider 返回的不透明 next_page:
import { listSessionEvents } from "@openagentpack/sdk";
import { sanitizeSessionEvents, toBailianSessionEvent } from "@openagentpack/sdk/session-events";
const page = await listSessionEvents(ctx, sessionId, {
provider: "bailian",
event_format: "snapshot",
order: "asc",
limit: 100,
page_token: previousNextPage,
});
const events = sanitizeSessionEvents(page.events, { redact: false, truncate: false });
// 纯映射函数用于完整消息/历史事件;content 分片必须经过订阅内的有状态归并器。
const mapped = toBailianSessionEvent(rawCompleteEvent, { event_format: "snapshot" });其中 ctx、sessionId、上一页的 previousNextPage 和原始完整事件由调用方提供。
./session-events 子路径保持浏览器安全,提供纯映射、累计转换与 sanitizer;
网络订阅和高层 Session 工作流使用 SDK 主入口,不应导入 internal/*。
百炼 Multi-Agent 的子 Agent 执行使用独立的 sthr_* Thread;主 Agent 的 thrd_*
不是线程列表中的子资源。同一 Agent 可以对应多条 Thread,调用方应按 Thread ID 区分执行实例。
两个 SDK 查询入口使用百炼的 Session Threads REST 路径:
| SDK 方法 | 百炼路径 | 结果 |
|---|---|---|
listSessionThreads(ctx, sessionId, options) |
GET /sessions/{session_id}/threads |
SessionThreadPage,即 CursorPage<SessionThread> |
listSessionThreadEvents(ctx, sessionId, threadId, options) |
GET /sessions/{session_id}/threads/{thread_id}/events |
ProviderSessionEventList |
这些路径由百炼 Multi-Agent 教程
说明,尚未纳入正式公开 API 参考;不能据此假设其他 Provider 也支持。当前 SDK 仅百炼实现,
其他 Provider 返回明确的 unsupported 错误。ctx 可用现有 ProjectRuntimeContext,
也可用只包含 Provider 配置的 ManagedApiContext。
import { listSessionThreads, listSessionThreadEvents } from "@openagentpack/sdk";
import { sanitizeSessionEvents } from "@openagentpack/sdk/session-events";
const threads = await listSessionThreads(ctx, sessionId, {
provider: "bailian", limit: 100, page: previousThreadPage, signal,
});
const history = await listSessionThreadEvents(ctx, sessionId, selectedThreadId, {
provider: "bailian", event_format: "snapshot", order: "desc",
limit: 50, page_token: previousEventPage, signal,
});
const events = sanitizeSessionEvents(history.events, { redact: false, truncate: false });SessionThread 保留 id/session_id/parent_thread_id、绑定的 agent.id/version、状态和时间,
Provider 有名称时也保留 agent.name 或 agent_name。列表按 limit/page 分页;历史查询
复用 EventListOptions,page_token 优先于兼容别名 page,请求时均映射为 page。
两者下一页都回传不透明的 next_page。历史 types 在 SDK 内本地过滤,保留原页游标;
过滤后空页不等于查询结束。两者都支持 AbortSignal。
需要补齐线程绑定 Agent 的名称时,可调用
getRemoteAgent(ctx, thread.agent.id, { version: thread.agent.version, signal })。
百炼实现会把 signal 传入实际 GET 请求,取消线程列表时应一并取消这些补充查询。
历史默认仍为 legacy;选择 snapshot 后复用完整事件转换、工具关联和 sanitizer。
子线程历史页不要求包含 session_status。事件的 metadata.thread_id 是实际所属线程,
metadata.session_thread_id、to_session_thread_id/from_session_thread_id 可能是被引用的子线程,
不能直接用引用字段替换实际归属。
此处只提供列表与历史读取,不新增 Thread 创建、归档、发送或独立 SSE。实时事件继续从
Session 的单一事件流获取;子线程状态不表示主会话执行结束。SessionThread、
SessionThreadListOptions 和 SessionThreadPage 也通过 ./session-events 导出类型,
浏览器可复用合同而无需加载 SDK 主入口或 Provider 凭据。
用量对接百炼 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 |
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。
import { getUsageSummary, getUsageTrend } from "@openagentpack/sdk";
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);
}自建后端透传百炼 SSE 时,调用方负责 HTTP、SSE 解帧、订阅就绪、历史分页与重试。
纯转换入口只接受已经解析的百炼业务 JSON,不接受心跳、SSE event/data/id 文本或 Kit 控制帧:
import { createBailianSessionEventNormalizer } from "@openagentpack/sdk/session-events";
const normalizer = createBailianSessionEventNormalizer({
redact: false,
truncate: false,
maxEntries: 1024,
});
// 按顺序输入历史;然后输入已缓冲的实时业务帧。
const historySnapshot = normalizer.seed(rawHistoricalEvent);
const liveSnapshot = normalizer.push(rawLiveFrame);
// 输出可能为 undefined;有输出时按 event_id 替换累计快照。
// 重连重建或更换 Session 前清空,不能沿用未完成正文当新 delta 基线。
normalizer.clear();rawHistoricalEvent 和 rawLiveFrame 均由调用方提供。每个逻辑订阅独立创建实例;
两个方法都直接返回 SessionEvent | undefined,无需再次调用 sanitizer。选项沿用
SessionEventSanitizerOptions:默认脱敏、截断,默认不附加 metadata.raw。
seed区分in_progress和完成历史。未完成快照保留正文、消息身份、线程及运行状态供展示, 但正文不成为后续 delta 的追加基线;后续局部分片及进行中快照被抑制,直到完成消息显式给出 整体content。单个delta: false内容块不足以证明其他块完整。缺少最终正文会报协议错误。- 已完成的历史 message/reasoning 在本次重建中保护同 ID 正文,避免旧缓冲帧覆盖; session_status 和工具事件仍允许同 ID 的完整状态更新。转换器不能推断跨事件的新旧顺序, 调用方必须对历史与缓冲流建立可验证的交接边界。
maxEntries默认 1024,限制保留的事件身份、孤立分片数量及单条消息的内容块数量。已输入的历史身份保留到clear();超过限制明确报错,不静默丢弃历史保护。调用方还应限制输入字节数、历史总量、 建连/空闲时间并在失败或取消后清理实例。不同连接的去重和重试不属于该纯转换接口。- 浏览器只访问业务后端,不需要也不应取得百炼凭据。这个入口不改变 SDK 主入口的
legacy/snapshot默认行为,也不自动打开网络、发送消息或执行审批。
reconnect: true 在意外 EOF、网络故障、429 或 5xx 后最多重试 3 次,等待时间依次为
250、500、1000 毫秒。鉴权、参数和协议错误直接失败。主动取消不会重连。
snapshot 模式将意外 EOF 作为断流错误,不把它合成为业务完成事件;旧模式保留原有行为。
恢复时先建立新订阅并缓冲实时帧,再按升序分页查询历史,归并完成事件后继续处理实时数据。
它只恢复订阅,不会重新发送用户消息或启动新的 Agent 执行。
已交付事件的同 ID 变化快照仍会更新调用方,不因位于恢复标记或其之前而丢弃;
恢复得到的本轮结束状态在历史消息修复完成后交付,避免提前结束而遗漏最终答案。
百炼没有在本 SDK 中确认的原生逐分片续传合同,after_id 在快照模式中作为本地历史核对
标记,不作为原生游标发送给百炼;旧模式的历史轮询回退保持不变。
在旧模式同时传入 after_id 和 signal、onReady 或超时配置会明确报错;需要这些控制时使用快照模式。
恢复目标是最终消息收敛,无法保证断开期间每个 token 都恰好重放一次。SDK 不会盲目把 重连后的分片追加到断开前的半截内容;缺少可靠基线时等待最终快照或历史完成事件。 缺失历史标记、重复分页游标、耗尽重试或缓冲超过 1024 帧/8 MiB 会明确报错,不静默丢内容。
单条消息完成不等于整个 Session 流结束。直接订阅保持持续接收;单轮发送入口根据会话状态
结束本轮消费。调用对应的 AbortController.abort() 会取消读取及恢复工作,退出迭代器也会释放连接。
发送请求尚未返回时取消会停止 SDK 的等待,但不表示 Provider 已取消执行,也不会重新发送消息。
此接口描述不表示已发布到 npm。协议 fixture、字节分块及模拟 HTTP 测试验证 SDK 行为, 不构成真实 Cloud SSE 或已安装下游版本的验证结果。
The public entry exposes domain workflows that return structured domain results (sessions, plans, diagnostics, resources, provider-neutral metadata). It does not return terminal rows, React view models, HTTP envelopes, SSE wrappers, or localized strings.
| Area | Functions |
|---|---|
| Project / resource workflows | resolveProjectConfig, resolveProjectConfigFromObject, planProjectContext, executePlannedProject, decideDestructive, importResource, syncProjectResourcesWithStateBackend |
| Validation and safe source previews | validateProjectConfig, collectConfigReferences, inspectProjectSource |
| Sync & migrate | resolveSyncProvider, syncProviderResourcesFromContext, syncProviderResourcesFromEnv, migrateConfig |
| Destroy | planDestroyProjectContext, destroyPlannedProjectResources |
| Agent | buildAgentDecl, getAgent, listAgentsWithReadiness, listCloudAgents, archiveCloudAgent, syncAgentResourcesWithStateBackend, createCloudEnvironment, deleteCloudEnvironment, listCloudEnvironments, createCloudVault, deleteCloudVault, listCloudVaults |
| Session | createSessionForAgent, startSessionRun, startSessionRunPolling, sendSessionMessageStreaming, sendSessionMessagePolling, streamSessionEvents, getSession, listSessionSummaries, listSessionEvents, listSessionThreads, listSessionThreadEvents, deleteSession, isTerminalSessionStatus, resolveSessionProvider |
| Files & skills | uploadFile, listFiles, getFileInfo, getFileDownloadUrl, deleteFile, createSkillFromFileId, listSkills, getSkillInfo, deleteSkill |
| Deployment | listDeploymentsForContext, getDeploymentDetailsForContext, getDeploymentRuntimeProviderForContext, runDeploymentForContext |
| Models | listProviderModelsForContext, listProviderNames |
| 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 |
| Sandboxing | prependFileHint, preparePromptForProvider, rewriteFileMentions |
Cross-boundary data shapes live in internal/types/dto.ts and are re-exported wholesale as the single source of truth — both the TypeScript types and their Zod schemas (e.g. SessionSchema, PlannedActionSchema, AgentWithReadinessSchema, DiagnosticSchema). Use the schemas to validate provider/HTTP payloads at the boundary.
Notable exported types: ResolvedProjectConfig, ProjectSourceInspection, ResourceState, ExecutionPlan, PlannedAction, Diagnostic, Session, SessionEvent, CloudAgent, CloudEnvironment, CloudVault, ResourceType, ResourceAddress, ActionType.
When adding a CLI or WebUI feature, ask:
- Does an existing SDK service already perform the domain workflow?
- If not, can a provider-neutral SDK service return the missing domain result?
- If the desired result is presentation, transport, or product state, should it stay in the CLI/WebUI instead?
If a workflow seems to need parser outputs, provider adapters, or planner/executor internals, treat that as a missing SDK service rather than reaching into src/internal/.