@njuptlzf/agent-chat-protocol 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +172 -0
  2. package/package.json +2 -2
  3. package/src/index.ts +1032 -870
package/dist/index.d.ts CHANGED
@@ -170,6 +170,56 @@ export type ChatEvent = {
170
170
  message: string;
171
171
  level: "info" | "warning" | "error";
172
172
  }
173
+ /**
174
+ * 编排层成员维度的事件(W4 / R-010)。**只在多 phase 的 Run 下发**;
175
+ * 单 phase(档 1)一个都不发,字节流与接入编排层之前完全一致(I8)。
176
+ *
177
+ * 为什么不给既有事件加 `memberId` 可选字段:那会让**每一次**单 phase 下发都
178
+ * 多一个 `memberId: undefined` 被 `JSON.stringify` 丢掉、语义上却存在,
179
+ * 前端还得判「有 memberId 才是成员流」。独立事件类型把两档彻底分开,
180
+ * 旧前端不认识就跳过(降级契约),新前端按需接管。
181
+ *
182
+ * `state` 用内联字面量而不是导出新类型:公开导出符号清单(54 项)不动(I8)。
183
+ */
184
+ | {
185
+ type: "member_started";
186
+ runId: string;
187
+ phaseId: string;
188
+ /** 成员 id:产品 manifest 里声明的人格 id,与 `JobSpec.persona` 同源。 */
189
+ memberId: string;
190
+ /** 交给这个成员的任务文本(前端可据此显示「在干什么」)。 */
191
+ task: string;
192
+ }
193
+ /** 成员的流式输出增量。前端按 `memberId` 归到各自的卡片。 */
194
+ | {
195
+ type: "member_delta";
196
+ runId: string;
197
+ phaseId: string;
198
+ memberId: string;
199
+ delta: string;
200
+ }
201
+ /** 成员收口:状态 + 它自己消耗的 usage(Run 级总量由 `run_done` 给)。 */
202
+ | {
203
+ type: "member_done";
204
+ runId: string;
205
+ phaseId: string;
206
+ memberId: string;
207
+ state: "completed" | "failed" | "stopped" | "blocked";
208
+ usage: TokenUsage;
209
+ }
210
+ /**
211
+ * 整个 Run 的汇总(多 phase 才有):全部成员加总后的 usage、最终输出、耗时。
212
+ * 与 `done` 的分工——`done` 是**流结束**的传输语义(恒发,单 phase 的字节流靠它),
213
+ * `run_done` 是**编排结果**的业务语义(多 phase 才有)。两者不互替。
214
+ */
215
+ | {
216
+ type: "run_done";
217
+ runId: string;
218
+ state: "completed" | "failed" | "stopped" | "blocked";
219
+ usage: TokenUsage;
220
+ output: string;
221
+ durationMs: number;
222
+ }
173
223
  /** The run is fully finished (agent will not continue on its own). Always the last event on success. */
174
224
  | {
175
225
  type: "done";
@@ -212,6 +262,74 @@ export interface ChatAttachment {
212
262
  * core 只回答「这个 id 产品声明了没有」——加人格、换产品都是改 manifest。
213
263
  */
214
264
  export type Persona = string;
265
+ /**
266
+ * 产品声明的一个**多 agent 流程**(M-14 / R-010 W4)。
267
+ *
268
+ * 这是「一次请求要跑哪几段」的声明:平台把它翻成 `RunSpec`,交给编排层执行。
269
+ * **产品不会看到 `RunSpec`**——那是平台内部类型;产品只填这份声明。
270
+ *
271
+ * ```
272
+ * flows:
273
+ * review:
274
+ * label: 双人评审
275
+ * phases:
276
+ * - { id: draft, member: writer, task: "写一段" }
277
+ * - { id: reviewA, member: reviewer-a, task: "审 {steps.draft.output}", dependsOn: [draft] }
278
+ * - { id: reviewB, member: reviewer-b, task: "审 {steps.draft.output}", dependsOn: [draft] }
279
+ * - { id: merge, kind: reduce, member: writer, from: [reviewA, reviewB],
280
+ * task: "汇总:{previous.output}", final: true }
281
+ * concurrency: 2
282
+ * ```
283
+ *
284
+ * `task` 里可用两种占位符(由编排引擎替换):
285
+ * - `{steps.<phaseId>.output}` —— 引用某个已完成 phase 的产物;
286
+ * - `{previous.output}` —— 仅 `kind: reduce` 用,指 `from` 聚合后的输入。
287
+ */
288
+ export interface ProductFlow {
289
+ /** 面向用户的名称(前端选流程时显示)。 */
290
+ label?: string;
291
+ /** 说明文案。 */
292
+ description?: string;
293
+ /** 这些节点连成 DAG。顺序不重要,`dependsOn` 才是关系。 */
294
+ phases: ProductFlowPhase[];
295
+ /**
296
+ * 同时在跑的成员上限。**缺省 = 引擎默认**(不在这里写死数字)。
297
+ * 见 `RunSpec.concurrency`:它与 pi 自己的 worker 队列必须同口径(待办 T1)。
298
+ */
299
+ concurrency?: number;
300
+ }
301
+ /**
302
+ * 流程里的一个节点。
303
+ *
304
+ * `kind` 三选一(缺省 `agent`):
305
+ * - `agent`:一个成员跑一件事(最常见);
306
+ * - `parallel`:`members` 各跑一件事,全部完成后节点收口;
307
+ * - `reduce`:把 `from` 的产物聚合后交给 `member` 汇总。
308
+ *
309
+ * **没有 `gate`**:gate 要的是「这个节点算通过吗」的判定规则,那是产品业务语义
310
+ * (及格线、必含项),平台不猜。真需要时再加,现在加就是编一个没人验证的规则形状。
311
+ */
312
+ export interface ProductFlowPhase {
313
+ /** 节点 id,flow 内唯一。 */
314
+ id: string;
315
+ /** 缺省 `agent`。 */
316
+ kind?: "agent" | "parallel" | "reduce";
317
+ /**
318
+ * 执行这个节点的**成员 id**:必须是产品已声明的人格
319
+ * (`agent.defaultPersona` ∪ `agent.personas.*`)。`kind: parallel` 时用 `members`。
320
+ */
321
+ member?: Persona;
322
+ /** `kind: parallel` 的分支成员列表(各自的 persona)。 */
323
+ members?: Persona[];
324
+ /** 交给成员的指令。支持 `{steps.<id>.output}` / `{previous.output}` 占位符。 */
325
+ task?: string;
326
+ /** 依赖的节点 id。空/缺省 = 入口。 */
327
+ dependsOn?: string[];
328
+ /** `kind: reduce` 的输入来源(节点 id 列表)。 */
329
+ from?: string[];
330
+ /** 是否作为整个 Run 的最终输出来源。 */
331
+ final?: boolean;
332
+ }
215
333
  /**
216
334
  * 产品**没有**声明 `agent.defaultPersona` 时用的兜底 id。
217
335
  * core 只发明这一个 id(其余全部来自产品 manifest);它同时是配额/流水里
@@ -239,6 +357,31 @@ export interface ChatRequest {
239
357
  * `agent.personas.*`); core knows none of them by name.
240
358
  */
241
359
  persona?: Persona;
360
+ /**
361
+ * Which multi-agent flow (`agent.flows.<id>`) this request runs.
362
+ *
363
+ * **Omit for a normal single-agent turn** — that path is byte-for-byte what it
364
+ * was before flows existed (`wire-baseline.test.ts` pins it). With `flow` set,
365
+ * the request becomes a multi-phase Run: the declared DAG runs member by member
366
+ * and the client receives `member_*` / `run_done` events on top of the usual
367
+ * stream, so one UI can render "who is working on what".
368
+ *
369
+ * Legal ids come from the product manifest; an unknown id is a 400. The flow is
370
+ * **not** bound to the session (unlike `persona`): running a different flow in
371
+ * the same conversation is a legitimate action (e.g. "re-review this with the
372
+ * other team"), and each request carries its own DAG.
373
+ */
374
+ flow?: string;
375
+ /**
376
+ * Resume a previously interrupted multi-phase flow run by its run id.
377
+ *
378
+ * The server only accepts a run id belonging to the authenticated user's
379
+ * current session (`<sessionId>:<timestamp>`); a foreign id is a 400. Only
380
+ * meaningful together with `flow` — a plain single-agent turn has no
381
+ * phase checkpoints to resume. Completed phases are replayed from the stored
382
+ * checkpoint without re-spending tokens (I7).
383
+ */
384
+ resumeRunId?: string;
242
385
  /**
243
386
  * Which scope (qualification) this conversation belongs to. The scope is bound
244
387
  * to the session when it is created and is immutable afterwards: resuming an
@@ -600,6 +743,17 @@ export interface BrandingResponse extends Branding {
600
743
  * 只是一个 id,不带任何能力信息,所以可以公开。
601
744
  */
602
745
  defaultPersona?: string;
746
+ /**
747
+ * Multi-agent flows this product declares (`agent.flows.<id>`), display
748
+ * fields only. A client can render a flow picker from this list; it never
749
+ * sees phase internals (member tasks / DAG) — those stay server-side. Absent
750
+ * when the product declares no flows, so existing clients are unaffected.
751
+ */
752
+ flows?: Array<{
753
+ id: string;
754
+ label?: string;
755
+ description?: string;
756
+ }>;
603
757
  }
604
758
  /**
605
759
  * 管理端模型配置。物理模型名只到这一层:
@@ -862,6 +1016,24 @@ export interface ProductManifest {
862
1016
  act: string;
863
1017
  }>;
864
1018
  };
1019
+ /**
1020
+ * **多 agent 流程**(M-14 / R-010 W4):产品声明「有哪些流程、谁是成员、
1021
+ * 谁依赖谁、汇总成什么」;平台给的是机制(DAG 调度、并发闸门、账本归集、
1022
+ * 事件协议)。
1023
+ *
1024
+ * 与 `personas` 完全同构的分层:
1025
+ * - 平台不认识任何具体流程,只认 id 与结构;
1026
+ * - **成员必须是已声明的人格**(`defaultPersona` ∪ `personas.*`)——
1027
+ * 流程不能凭空造出一个没有 prompt / 没有工具白名单的 agent;
1028
+ * - 请求侧只传 `flow: "<id>"`,不带就还是今天那个单 agent 对话。
1029
+ *
1030
+ * 声明即启动期校验(fail-closed):phase id 重复、`dependsOn` 悬空、环、
1031
+ * 成员未声明、`from` 指向不存在的 phase——全部启动失败,不进运行期。
1032
+ * 这与 `personas` 里写坏 prompt 路径就起不来的口径一致。
1033
+ *
1034
+ * **不声明 = 没有多 agent 能力**,产品完全不受影响。
1035
+ */
1036
+ flows?: Record<string, ProductFlow>;
865
1037
  };
866
1038
  tools?: {
867
1039
  /** Module whose default export is `(ctx) => ToolDefinition[]`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@njuptlzf/agent-chat-protocol",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Wire protocol between the agentChat server and any chat UI: event, request/response and config types. Shapes only — no business semantics.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -34,7 +34,7 @@
34
34
  "sse"
35
35
  ],
36
36
  "engines": {
37
- "node": ">=22.13"
37
+ "node": ">=22.15"
38
38
  },
39
39
  "publishConfig": {
40
40
  "access": "public"