@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/src/execution/__tests__/tool-action.test.ts

@@ -23,6 +23,7 @@ function makeDetails(over: Partial<SubagentToolDetails> = {}): SubagentToolDetai
     agent: "worker",
     model: "test/model",
     thinkingLevel: undefined,
+    slug: "test-slug",
     turns: 1,
     totalTokens: 10,
     elapsedSeconds: 1,
@@ -40,6 +41,7 @@ function makeSnapshot(over: Partial<RecordSnapshot> = {}): RecordSnapshot {
     thinkingLevel: undefined,
     mode: "background",
     task: "t",
+    slug: "test-slug",
     status: "done",
     eventLog: [],
     turns: 1,
@@ -74,7 +76,24 @@ describe("startHandler", () => {
 
   it("task 空白 → throw", async () => {
     const svc = makeService();
-    await expect(startHandler(svc, { task: "   " }, undefined)).rejects.toThrow(/task is required/);
+    await expect(startHandler(svc, { task: "   ", slug: "x" }, undefined)).rejects.toThrow(/task is required/);
+  });
+
+  it("slug 缺失 → throw", async () => {
+    const svc = makeService();
+    await expect(startHandler(svc, { task: "ok" }, undefined)).rejects.toThrow(/slug is required/);
+  });
+
+  it("slug 空白 → throw", async () => {
+    const svc = makeService();
+    await expect(startHandler(svc, { task: "ok", slug: "   " }, undefined)).rejects.toThrow(/slug is required/);
+  });
+
+  it("slug 超 20 字符 → throw", async () => {
+    const svc = makeService();
+    await expect(
+      startHandler(svc, { task: "ok", slug: "a".repeat(21) }, undefined),
+    ).rejects.toThrow(/≤20 chars/);
   });
 
   it("background 启动 → kind=bg + bgResponse.message 含 detached", async () => {
@@ -86,7 +105,7 @@ describe("startHandler", () => {
         details: makeDetails({ status: "running", mode: "background" }),
       })),
     });
-    const r = await startHandler(svc, { task: "long" }, undefined);
+    const r = await startHandler(svc, { task: "long", slug: "long-running" }, undefined);
     expect(r.kind).toBe("bg");
     if (r.kind !== "bg") return;
     expect(r.subagentId).toBe("bg-1-123");
@@ -297,11 +316,11 @@ describe("cancelHandler", () => {
 // adapter
 // ============================================================
 describe("adapter", () => {
-  it("start bg → SubagentToolResult.bgResponse + content 合法 JSON（C3 回归）", () => {
+  it("start bg → SubagentToolResult.bgResponse + slug 透传 + content 合法 JSON（C3 回归）", () => {
     const r = adapter({
       action: "start",
       domain: {
-        kind: "bg", subagentId: "bg-1", sessionFile: undefined,
+        kind: "bg", subagentId: "bg-1", sessionFile: undefined, slug: "extract-urls",
         response: { status: "running", mode: "background", message: "detached, will notify on completion" },
       },
     });
@@ -309,9 +328,12 @@ describe("adapter", () => {
     expect(r.details.subagentId).toBe("bg-1");
     expect(r.details.bgResponse).toBeDefined();
     expect(r.details.sessionFile).toBeNull();
+    // slug 透传到 result（renderResult 的 background 行展示用）
+    expect(r.details.slug).toBe("extract-urls");
     // content JSON round-trip（bg 序列化回归）
     const parsed = JSON.parse(r.content[0]!.text);
     expect(parsed.bgResponse.message).toMatch(/detached/);
+    expect(parsed.slug).toBe("extract-urls");
   });
 
   it("list → 最外层 subagentId/sessionFile 为 null", () => {

package/src/execution/agent-result-mapper.ts

@@ -17,6 +17,8 @@ import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } f
  *   text                              → content
  *   parsedOutput                      → parsedOutput（structured-output 契约，BC-8）
  *   !success && error                 → error（失败时填，成功时 undefined）
+ *   !success && !error                → error fallback（abort 路径：session-runner 设 success=false,error=undefined，
+ *                                      若直接透传 undefined 则 executeAgentCall 的 `error===undefined` 误判 completed。H4 修复：synthesize fallback）
  *   durationMs                        → durationMs
  *   sessionId                         → sessionId
  *   usage (AgentUsageTotal)           → usage (AgentUsage: input/output/cacheRead/cacheWrite/cost/contextTokens/turns)
@@ -31,9 +33,10 @@ export function mapToWorkflowAgentResult(
   return {
     content: r.text,
     parsedOutput: r.parsedOutput,
-    error: r.success ? undefined : r.error,
+    error: r.success ? undefined : (r.error || "Agent call failed (aborted or unknown error)"),
     durationMs: r.durationMs,
     sessionId: r.sessionId,
+    sessionFile: r.sessionFile,
     usage: r.usage ? mapUsage(r.usage, r.turns) : undefined,
     toolCalls: r.toolCalls ? mapToolCalls(r.toolCalls) : undefined,
   };

package/src/execution/concurrency-pool.ts

@@ -2,17 +2,22 @@
 //
 // 并发控制 + 优先级排队。background=1000（单一优先级，保留 priority 机制供未来扩展）。
 
-/** 队列条目：优先级 + resolver + 入队序号（同优先级 FIFO）。 */
+/** 队列条目：优先级 + resolver + rejecter + 入队序号（同优先级 FIFO）。 */
 interface QueueEntry {
   priority: number;
   resolve: () => void;
+  reject: (err: Error) => void;
   seq: number;
+  /** abort listener（用于 resolve/abort 时清理）。 */
+  onAbort?: () => void;
+  /** 关联的 signal（用于 resolve 时 removeEventListener）。 */
+  signal?: AbortSignal;
 }
 
 /** 并发池接口（可注入，便于测试 mock）。 */
 export interface ConcurrencyPool {
-  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。 */
-  acquire(priority: number, effectiveMaxConcurrent?: number): Promise<void>;
+  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。可选 AbortSignal 在 abort 时 reject 排队条目。 */
+  acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void>;
   /** 归还槽位。必须无条件执行（finally）。 */
   release(): void;
   /** 当前已占用槽位数（诊断/widget 用）。 */
@@ -45,7 +50,7 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
     this.maxConcurrent = Math.max(1, maxConcurrent);
   }
 
-  acquire(priority: number, effectiveMaxConcurrent?: number): Promise<void> {
+  acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void> {
     // effectiveMaxConcurrent 覆盖实例级默认配额（分层配额：调用方传 max(1, maxConcurrent - depth)）。
     // 不修改实例级 maxConcurrent——实例配额是全局共享上限，分层配额是本次 acquire 的局部上限。
     const effective = effectiveMaxConcurrent ?? this.maxConcurrent;
@@ -53,8 +58,31 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
       this._active += 1;
       return Promise.resolve();
     }
-    return new Promise<void>((resolve) => {
-      this.queue.push({ priority, resolve, seq: this.seqCounter++ });
+    return new Promise<void>((resolve, reject) => {
+      const entry: QueueEntry = { priority, resolve, reject, seq: this.seqCounter++ };
+      // H2: abort 时 reject 排队条目并从 queue 移除，防止永久挂起
+      if (signal) {
+        if (signal.aborted) {
+          // S1: abort reject 需带 name="AbortError"，对齐 concurrency-gate.ts 的 AbortError 语义
+          const err = new Error("acquire aborted");
+          err.name = "AbortError";
+          reject(err);
+          return;
+        }
+        entry.signal = signal;
+        entry.onAbort = (): void => {
+          const idx = this.queue.indexOf(entry);
+          if (idx >= 0) {
+            this.queue.splice(idx, 1);
+            // S1: abort reject 需带 name="AbortError"，与 pre-aborted 分支一致
+            const err = new Error("acquire aborted");
+            err.name = "AbortError";
+            reject(err);
+          }
+        };
+        signal.addEventListener("abort", entry.onAbort, { once: true });
+      }
+      this.queue.push(entry);
     });
   }
 
@@ -70,6 +98,10 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
         }
       }
       const next = this.queue.splice(bestIdx, 1)[0];
+      // H2: 条目已获槽位——移除 abort listener（防 listener 泄漏到长生命周期 signal）
+      if (next.onAbort && next.signal) {
+        next.signal.removeEventListener("abort", next.onAbort);
+      }
       next.resolve();
       // active 不变（一个离开队列立即进入活跃）
     } else if (this._active > 0) {

package/src/execution/execute-options-mapper.ts

@@ -9,6 +9,12 @@ import type { AgentCallOpts } from "../orchestration/models/types.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import type { ExecuteOptions } from "./types.ts";
 
+/**
+ * slug 最大长度（字符）。subagent/workflow 创建时 slug 超过此值会被截断。
+ * 与 subagent tool schema 的 maxLength: 20 保持一致。
+ */
+export const SLUG_MAX_LENGTH = 20;
+
 /**
  * D-A2: AgentCallOpts → ExecuteOptions 映射。
  *
@@ -17,30 +23,41 @@ import type { ExecuteOptions } from "./types.ts";
  *
  * 映射规则：
  *   prompt          → task
+ *   description     → slug（≤20 字符，超长截断。缺失时回落 agent 名）
  *   agent           → agent
  *   schema          → schema
  *   schemaEnv       → schemaEnv（D-A6 bridge）
  *   cwd             → cwd
- *   model           → model ?? ctxModel（D-008 填底）
+ *   model           → model（显式 override 透传，ctxModel 不再压扁为 id 填底）
+ *   ctxModel        → ctxModel（完整 ModelInfo 对象透传，让 resolveModel 走第 3 层透明传递）
  *   skillPath       → skillPath
+ *   thinkingLevel   → thinkingLevel（M1: 否则下游 subagent-service 读到 undefined）
+ *   systemPromptFiles → appendSystemPrompt（M2: resolveAgentOpts 写盘的临时文件需被 session-runner 消费）
  *
  * 忽略字段（委托后由 executeAndAwait 内部机制替代）：
- *   systemPromptFiles —— resolveIdentity 从 agentConfig.systemPrompt 读
  *   timeoutMs         —— mergeTimeoutSignal 单独处理
- *   scene/description —— subagents 不消费
+ *   scene             —— subagents 不消费
+ *
+ * description 原先被忽略，现作为 slug 透传（ExecuteOptions.slug 必填）。
  */
 export function mapToExecuteOptions(
   opts: AgentCallOpts,
   ctxModel?: ModelInfo,
 ): ExecuteOptions {
+  // slug：优先 description，缺失回落 agent 名（保证非空）。超长截断。
+  const rawSlug = opts.description ?? opts.agent ?? "workflow-agent";
   return {
     task: opts.prompt,
+    slug: rawSlug.length > SLUG_MAX_LENGTH ? rawSlug.slice(0, SLUG_MAX_LENGTH) : rawSlug,
     agent: opts.agent,
     schema: opts.schema,
     schemaEnv: opts.schemaEnv,
     cwd: opts.cwd,
-    model: opts.model ?? ctxModel?.id,
+    model: opts.model,
+    ctxModel,
     skillPath: opts.skillPath,
+    thinkingLevel: opts.thinkingLevel,
+    appendSystemPrompt: opts.systemPromptFiles,
   };
 }
 

package/src/execution/execution-record.ts

@@ -147,6 +147,8 @@ export function createRecord(
     thinkingLevel?: string;
     mode: ExecutionMode;
     task: string;
+    /** 短标签（≤20 字符），必填。持久化兜底空串。 */
+    slug: string;
     startedAt: number;
     /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层同值。 */
     rootSessionId?: string;
@@ -164,6 +166,7 @@ export function createRecord(
     thinkingLevel: identity.thinkingLevel,
     mode: identity.mode,
     task: identity.task,
+    slug: identity.slug,
     startedAt: identity.startedAt,
     rootSessionId: identity.rootSessionId,
     parentRecordId: identity.parentRecordId,
@@ -607,6 +610,7 @@ export function project(record: ExecutionRecord): SubagentToolDetails {
     agent: record.agent,
     model: record.model,
     thinkingLevel: record.thinkingLevel,
+    slug: record.slug,
     turns: record.turnCount,
     totalTokens: record.totalTokens,
     elapsedSeconds: computeElapsedSeconds(record),
@@ -657,6 +661,7 @@ export function snapshot(record: ExecutionRecord): RecordSnapshot {
     thinkingLevel: record.thinkingLevel,
     mode: record.mode,
     task: record.task,
+    slug: record.slug,
     status: record.status,
     turns: record.turnCount,
     totalTokens: record.totalTokens,

package/src/execution/record-store.ts

@@ -250,6 +250,7 @@ export class RecordStore {
       const rec: SubagentRecord = {
         id: recon.id,
         agent: recon.agent,
+        slug: recon.slug,
         status: recon.status, // 临时值，各分支覆盖
         mode: recon.mode,
         startedAt: recon.startedAt,
@@ -329,6 +330,7 @@ export class RecordStore {
       agent: r.agent,
       status: r.status,
       mode: r.mode,
+      slug: r.slug,
       startedAt: r.startedAt,
       rootSessionId: r.rootSessionId,
       parentRecordId: r.parentRecordId,

package/src/execution/session-reconstructor.ts

@@ -84,6 +84,11 @@ export interface SubagentIdentityData {
   agent: string;
   mode: ExecutionMode;
   task: string;
+  /**
+   * 短标签（≤20 字符）。旧文件缺失→读取兜底空串（见 reconstructFromFile）。
+   * 写入时（session-runner）必填；读取时可选以兼容旧文件。
+   */
+  slug?: string;
   startedAt: number;
   /** 根 Pi session ID（session 隔离过滤用）。旧文件可能缺失。 */
   rootSessionId?: string;
@@ -126,6 +131,8 @@ export interface ReconstructedRecord {
   agent: string;
   mode: ExecutionMode;
   task: string;
+  /** 短标签（≤20 字符）。旧文件缺失→兜底空串。 */
+  slug: string;
   startedAt: number;
   /** 根 Pi session ID（session 隔离过滤用）。旧文件可能缺失。 */
   rootSessionId: string | undefined;
@@ -353,6 +360,7 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
       const turn = emptyTurn();
       turns.push(turn);
 
+      if (!Array.isArray(msg.content)) continue;
       for (const block of msg.content) {
         if (block.type === "text") {
           turn.text += block.text;
@@ -428,8 +436,11 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
 
   // rootSessionId 归一化：新文件读 rootSessionId，旧文件 fallback parentSessionId。
   const rootSessionId = identity.rootSessionId ?? identity.parentSessionId;
+  // slug 兜底：旧 identity entry 无 slug 字段 → 空串（与 SubagentRecord.slug: string 契约一致）。
+  const slug = identity.slug ?? "";
   return {
     ...identity,
+    slug,
     rootSessionId,
     parentRecordId: identity.parentRecordId,
     depth: identity.depth ?? 0,

package/src/execution/session-runner.ts

@@ -33,6 +33,7 @@ import {
   parseSpawnLine,
   type SpawnSessionHeader,
 } from "./spawn-event-adapter.ts";
+import type { SubagentStream } from "./stream-sink.ts";
 import {
   cleanupTempPrompt,
   writePromptToTempFile,
@@ -181,6 +182,12 @@ export interface RunOptions {
   signal: AbortSignal | undefined;
   /** event 回流——SessionRunner 内部 updateFromEvent 后，再回调调用方（widget/notify）。 */
   onEvent: ((event: AgentEvent) => void) | undefined;
+  /** text_delta streaming 生命周期对象——在 text_delta 到达 onEvent 之前分流。
+   *  background 模式下 onEvent=undefined，但 text_delta 仍可通过此对象被消费。
+   *  由调用方（subagent-service）创建，内部做时间窗合并后转发到 setWidget。
+   *  workflow 路径（executeAndAwait）不传此字段——其 onEvent 是开的，
+   *  text_delta 经 onEvent 到 workflow liveRecord，不走 streaming 通道。 */
+  stream?: SubagentStream;
   /** D-A6 bridge: workflow schema JSON 字符串，存在时注入 childEnv.PI_WORKFLOW_SCHEMA。
    *  workflow 编排层通过 ExecuteOptions.schemaEnv 透传此处，
    *  runSpawn 将其注入子进程环境变量，激活 structured-output 扩展注册 tool。
@@ -474,6 +481,10 @@ export async function runSpawn(
   const agentEvent = (event: AgentEvent): void => {
     updateFromEvent(record, event);
     if (event.type === "turn_end") limiter.onTurnEnd(record.turnCount);
+    // text_delta 分流到 stream 通道（在 onEvent 之前）。
+    // 双通道互斥设计：background 路径 stream 有值、onEvent=undefined；
+    // workflow 路径 onEvent 有值、stream=undefined。详见 W3 注释。
+    if (event.type === "text_delta") opts.stream?.onDelta(event.delta);
     opts.onEvent?.(event);
   };
 
@@ -667,6 +678,7 @@ export async function runSpawn(
           agent: record.agent,
           mode: record.mode,
           task: record.task,
+          slug: record.slug,
           startedAt: record.startedAt,
           rootSessionId: record.rootSessionId,
           parentRecordId: record.parentRecordId,

package/src/execution/stream-sink.ts

@@ -0,0 +1,83 @@
+/**
+ * subagent text_delta streaming sink。
+ *
+ * background subagent 执行期间，session-runner 的 agentEvent 出口把每个 text_delta
+ * 传到 SubagentStream.onDelta。本模块做 100ms 时间窗合并后，通过 StreamSink.setWidget
+ * 转发到 RPC stdout（经 ctx.ui.setWidget → extension_ui_request 通道）。
+ *
+ * SubagentStream 是一个生命周期对象——内聚 buffer/timer 状态 + onDelta/dispose 方法。
+ * 调用方（subagent-service）创建后只需在 text_delta 时调 onDelta、终态时调 dispose，
+ * 不需要拆散 push/clear 两个函数跨层透传。
+ *
+ * 设计要点：
+ * - leading edge：第一个 delta 立即 flush（前端尽快看到开始）
+ * - trailing edge：后续 delta 追加 buffer，timer 到期后 flush
+ * - 每次 flush 把 buffer 的累积全文 split("\n") 传给 setWidget
+ * - dispose 清除 widget + 清 timer
+ */
+
+/** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
+ *
+ * 当前只有一个 adapter（index.ts session_start 包装 ctx.ui.setWidget）。
+ * 保留接口而非裸函数类型，因为 StreamSink 的语义是「UI sink 契约」——
+ * 测试 mock 和未来可能的第二 sink（如写文件）都走此契约。 */
+export interface StreamSink {
+  setWidget(key: string, lines: string[] | undefined): void;
+}
+
+/** delta 合并窗口时间（ms）。与 onEventThrottled 的节流间隔对齐。 */
+const STREAM_FLUSH_MS = 100;
+
+/**
+ * subagent text_delta streaming 生命周期对象。
+ *
+ * 创建后：
+ * - `onDelta(delta)`：session-runner 每次 text_delta 调
+ * - `dispose()`：subagent 终态时调，清除 widget + 清 timer
+ *
+ * buffer/timer 状态全部内聚在此对象，调用方不需要关心合并逻辑。
+ */
+export class SubagentStream {
+  private readonly widgetKey: string;
+  private readonly sink: StreamSink;
+  private buffer = "";
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private hasFlushed = false;
+  private disposed = false;
+
+  constructor(recordId: string, sink: StreamSink) {
+    this.widgetKey = `subagent-stream-${recordId}`;
+    this.sink = sink;
+  }
+
+  /** 接收一个 text_delta 增量。空串静默丢弃（不消耗 leading edge）。 */
+  onDelta(delta: string): void {
+    if (this.disposed || delta.length === 0) return;
+    this.buffer += delta;
+    if (!this.hasFlushed) {
+      // leading edge：第一个 delta 立即 flush
+      this.hasFlushed = true;
+      this.flush();
+    } else if (this.timer === undefined) {
+      // trailing edge：后续 delta 经 timer 合并
+      this.timer = setTimeout(() => this.flush(), STREAM_FLUSH_MS);
+    }
+  }
+
+  /** 终态清理：清除 widget + 清 timer（幂等）。 */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    this.sink.setWidget(this.widgetKey, undefined);
+  }
+
+  private flush(): void {
+    this.timer = undefined;
+    if (this.buffer.length === 0 || this.disposed) return;
+    this.sink.setWidget(this.widgetKey, this.buffer.split("\n"));
+  }
+}