@baique/pi-web-sky 0.1.55 → 0.1.57

package/lib/subagent-extension.ts

@@ -0,0 +1,309 @@
+import { Type } from "@earendil-works/pi-ai";
+import {
+  defineTool,
+  type ExtensionContext,
+  type InlineExtension,
+  type LoadExtensionsResult,
+} from "@earendil-works/pi-coding-agent";
+import {
+  SUBAGENT_CONTROL_TOOL_NAMES,
+  type SubagentProfile,
+  type SubagentRunInfo,
+} from "./subagents";
+import { MAX_SUBAGENT_INPUT_FILES } from "./subagent-input";
+
+export const HOST_SUBAGENT_EXTENSION_NAME = "pi-web-subagents";
+const HOST_SUBAGENT_EXTENSION_PATH = `<inline:${HOST_SUBAGENT_EXTENSION_NAME}>`;
+const SUBAGENT_TOOL_NAMES = new Set<string>(SUBAGENT_CONTROL_TOOL_NAMES);
+const LEGACY_SUBAGENT_PACKAGE_NAME = "pi-subagents";
+
+export interface SubagentToolDetails {
+  kind: "pi-web-subagent";
+  sessionId: string;
+  profile: string;
+  description: string;
+  status: SubagentRunInfo["status"];
+  runInBackground: boolean;
+  createdAt: string;
+  completedAt?: string;
+  error?: string;
+  worktreePath?: string;
+  worktreeBranch?: string;
+  worktreeCleanupError?: string;
+}
+
+export interface StartSubagentRequest {
+  parentContext: ExtensionContext;
+  parentToolCallId: string;
+  profile: string;
+  task: string;
+  inputFiles?: string[];
+  description: string;
+  runInBackground?: boolean;
+  model?: string;
+  thinking?: string;
+  maxTurns?: number;
+  inheritContext?: boolean;
+  isolation?: "worktree";
+  signal?: AbortSignal;
+  onUpdate?: (run: SubagentRunInfo) => void;
+}
+
+export interface ResumeSubagentRequest {
+  parentContext: ExtensionContext;
+  parentToolCallId: string;
+  sessionId: string;
+  task: string;
+  description: string;
+  runInBackground?: boolean;
+  signal?: AbortSignal;
+  onUpdate?: (run: SubagentRunInfo) => void;
+}
+
+export interface SubagentExecution {
+  run: SubagentRunInfo;
+  completion: Promise<SubagentRunInfo>;
+}
+
+export interface SubagentExtensionRuntime {
+  start(request: StartSubagentRequest): Promise<SubagentExecution>;
+  resume(request: ResumeSubagentRequest): Promise<SubagentExecution>;
+  get(sessionId: string): Promise<SubagentRunInfo | null>;
+  steer(sessionId: string, message: string): Promise<void>;
+  notifyParent(run: SubagentRunInfo): Promise<void>;
+}
+
+export type SubagentProfileProvider = () => readonly SubagentProfile[];
+export type SubagentEnabledProvider = () => boolean;
+
+function agentTypeDescription(profiles: readonly SubagentProfile[]): string {
+  const available = profiles.filter((profile) => profile.enabled);
+  if (available.length === 0) return "No subagent profiles are currently enabled.";
+  return available.map((profile) => {
+    const details = [`Tools: ${profile.tools.length > 0 ? profile.tools.join(", ") : "none"}`];
+    if (profile.model) details.push(`Model: ${profile.model}`);
+    return `- ${profile.name}: ${profile.description} (${details.join("; ")})`;
+  }).join("\n");
+}
+
+export function subagentToolDetails(run: SubagentRunInfo): SubagentToolDetails {
+  return {
+    kind: "pi-web-subagent",
+    sessionId: run.sessionId,
+    profile: run.profile,
+    description: run.description,
+    status: run.status,
+    runInBackground: run.runInBackground,
+    createdAt: run.createdAt,
+    ...(run.completedAt ? { completedAt: run.completedAt } : {}),
+    ...(run.error ? { error: run.error } : {}),
+    ...(run.worktreePath ? { worktreePath: run.worktreePath } : {}),
+    ...(run.worktreeBranch ? { worktreeBranch: run.worktreeBranch } : {}),
+    ...(run.worktreeCleanupError ? { worktreeCleanupError: run.worktreeCleanupError } : {}),
+  };
+}
+
+export function subagentFinalText(run: SubagentRunInfo): string {
+  if (run.status === "starting" || run.status === "running") {
+    return `Subagent ${run.sessionId} is ${run.status}.`;
+  }
+  if (run.status === "completed") return run.result?.trim() || "Subagent completed without text output.";
+  if (run.status === "aborted") return `Subagent ${run.sessionId} was stopped.`;
+  if (run.status === "interrupted") return `Subagent ${run.sessionId} was interrupted before completion.`;
+  return `Subagent ${run.sessionId} failed: ${run.error ?? "Unknown error"}`;
+}
+
+export function createSubagentExtension(
+  runtime: SubagentExtensionRuntime,
+  getProfiles: SubagentProfileProvider,
+  isEnabled: SubagentEnabledProvider = () => true,
+): InlineExtension {
+  return {
+    name: HOST_SUBAGENT_EXTENSION_NAME,
+    hidden: true,
+    factory: (pi) => {
+      if (!isEnabled()) return;
+      const profiles = getProfiles().filter((profile) => profile.enabled);
+      const profileNames = profiles.map((profile) => profile.name);
+      const availableTypes = profileNames.length > 0 ? profileNames.join(", ") : "none";
+      pi.registerTool(defineTool({
+        name: "Agent",
+        label: "Agent",
+        description: `Delegate a focused task to a configured subagent. Each subagent runs as a full, inspectable Pi session. Use background mode for independent work and foreground mode when the result is needed immediately.\n\nAvailable agent types:\n${agentTypeDescription(profiles)}`,
+        promptSnippet: "Delegate a focused task to an inspectable subagent session",
+        promptGuidelines: [
+          "Use Agent for a focused task that benefits from an isolated context.",
+          "Use multiple background Agent calls in the same response for independent parallel work.",
+          "Do not duplicate work already delegated to a running subagent.",
+        ],
+        executionMode: "parallel",
+        parameters: Type.Object({
+          subagent_type: Type.Optional(Type.String({ description: `Configured agent profile. Available types: ${availableTypes}. Default: general-purpose.` })),
+          prompt: Type.String({ description: "The complete task for the subagent." }),
+          resume: Type.Optional(Type.String({ description: "Existing subagent session ID to continue instead of creating a new session." })),
+          input_files: Type.Optional(Type.Array(Type.String(), {
+            description: "UTF-8 text files under the session cwd to include with the task.",
+            maxItems: MAX_SUBAGENT_INPUT_FILES,
+          })),
+          description: Type.String({ description: "Short activity label shown in the UI." }),
+          run_in_background: Type.Optional(Type.Boolean({ description: "Return immediately and notify this session when complete." })),
+          model: Type.Optional(Type.String({ description: "Optional provider/modelId override." })),
+          thinking: Type.Optional(Type.String({ description: "Optional thinking level override." })),
+          max_turns: Type.Optional(Type.Number({ description: "Optional positive agent turn limit." })),
+          inherit_context: Type.Optional(Type.Boolean({ description: "Include the parent session's active conversation context." })),
+          isolation: Type.Optional(Type.String({ description: "Run the subagent in an isolated git worktree." })),
+        }),
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+          try {
+            const resume = params.resume?.trim();
+            const execution = resume
+              ? await runtime.resume({
+                  parentContext: ctx,
+                  parentToolCallId: toolCallId,
+                  sessionId: resume,
+                  task: params.prompt,
+                  description: params.description,
+                  ...(params.run_in_background !== undefined ? { runInBackground: params.run_in_background } : {}),
+                  signal,
+                  onUpdate: (run) => onUpdate?.({
+                    content: [{ type: "text", text: `${run.profile}: ${run.description} (${run.status})` }],
+                    details: subagentToolDetails(run),
+                  }),
+                })
+              : await runtime.start({
+              parentContext: ctx,
+              parentToolCallId: toolCallId,
+              profile: params.subagent_type ?? "general-purpose",
+              task: params.prompt,
+              ...(params.input_files ? { inputFiles: params.input_files } : {}),
+              description: params.description,
+              ...(params.run_in_background !== undefined ? { runInBackground: params.run_in_background } : {}),
+              ...(params.model ? { model: params.model } : {}),
+              ...(params.thinking ? { thinking: params.thinking } : {}),
+              ...(params.max_turns ? { maxTurns: params.max_turns } : {}),
+              ...(params.inherit_context !== undefined ? { inheritContext: params.inherit_context } : {}),
+              ...(params.isolation === "worktree" ? { isolation: "worktree" as const } : {}),
+              signal,
+              onUpdate: (run) => onUpdate?.({
+                content: [{ type: "text", text: `${run.profile}: ${run.description} (${run.status})` }],
+                details: subagentToolDetails(run),
+              }),
+                });
+
+            if (execution.run.runInBackground) {
+              void execution.completion
+                .then((run) => runtime.notifyParent(run))
+                .catch((error) => {
+                  console.error(
+                    "[pi-web] failed to deliver subagent completion:",
+                    error instanceof Error ? error.message : error,
+                  );
+                });
+              return {
+                content: [{ type: "text", text: `Subagent started in background. Session ID: ${execution.run.sessionId}. You will be notified when it completes.` }],
+                details: subagentToolDetails(execution.run),
+              };
+            }
+
+            const run = await execution.completion;
+            return {
+              content: [{ type: "text", text: subagentFinalText(run) }],
+              details: subagentToolDetails(run),
+              ...(run.status === "failed" ? { isError: true } : {}),
+            };
+          } catch (error) {
+            return {
+              content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+              details: undefined,
+              isError: true,
+            };
+          }
+        },
+      }));
+
+      pi.registerTool(defineTool({
+        name: "get_subagent_result",
+        label: "Get agent result",
+        description: "Check an inspectable subagent session and retrieve its latest result.",
+        parameters: Type.Object({
+          agent_id: Type.String({ description: "Subagent session ID." }),
+          wait: Type.Optional(Type.Boolean({ description: "Wait until the subagent finishes." })),
+        }),
+        async execute(_toolCallId, params, signal) {
+          let run = await runtime.get(params.agent_id);
+          if (!run) return { content: [{ type: "text", text: `Subagent not found: ${params.agent_id}` }], details: undefined, isError: true };
+          while (params.wait && (run.status === "starting" || run.status === "running")) {
+            await new Promise<void>((resolve, reject) => {
+              const onAbort = () => {
+                clearTimeout(timer);
+                reject(new Error("Result wait aborted"));
+              };
+              const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+              }, 500);
+              if (signal?.aborted) onAbort();
+              else signal?.addEventListener("abort", onAbort, { once: true });
+            });
+            run = await runtime.get(params.agent_id);
+            if (!run) return { content: [{ type: "text", text: `Subagent not found: ${params.agent_id}` }], details: undefined, isError: true };
+          }
+          return {
+            content: [{ type: "text", text: subagentFinalText(run) }],
+            details: subagentToolDetails(run),
+            ...(run.status === "failed" ? { isError: true } : {}),
+          };
+        },
+      }));
+
+      pi.registerTool(defineTool({
+        name: "steer_subagent",
+        label: "Steer agent",
+        description: "Send a steering message to a currently running subagent session.",
+        parameters: Type.Object({
+          agent_id: Type.String({ description: "Subagent session ID." }),
+          message: Type.String({ description: "Instruction to inject after the current tool execution." }),
+        }),
+        async execute(_toolCallId, params) {
+          try {
+            await runtime.steer(params.agent_id, params.message);
+            return { content: [{ type: "text", text: `Steering message sent to ${params.agent_id}.` }], details: undefined };
+          } catch (error) {
+            return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], details: undefined, isError: true };
+          }
+        },
+      }));
+    },
+  };
+}
+
+/** Keep Pi Web's integrated implementation when the legacy package is loaded. */
+export function preferPiWebSubagentExtension(base: LoadExtensionsResult): LoadExtensionsResult {
+  const host = base.extensions.find((extension) => extension.path === HOST_SUBAGENT_EXTENSION_PATH);
+  if (!host?.tools.has("Agent")) return base;
+  const legacyPaths = new Set(base.extensions
+    .filter((extension) => extension.path !== HOST_SUBAGENT_EXTENSION_PATH)
+    .filter((extension) => {
+      const source = extension.sourceInfo?.source ?? "";
+      const sourcePackage = source.replace(/^npm:/, "").split("@")[0];
+      const pathSegments = extension.path.replaceAll("\\", "/").split("/");
+      return sourcePackage === LEGACY_SUBAGENT_PACKAGE_NAME
+        || pathSegments.some((segment) => segment === LEGACY_SUBAGENT_PACKAGE_NAME);
+    })
+    .filter((extension) => [...SUBAGENT_TOOL_NAMES].some((name) => extension.tools.has(name)))
+    .map((extension) => extension.path));
+  if (legacyPaths.size === 0) return base;
+  return {
+    ...base,
+    extensions: base.extensions.filter((extension) => !legacyPaths.has(extension.path)),
+    errors: base.errors.filter((error) => {
+      if (legacyPaths.has(error.path)) return false;
+      if (error.path !== HOST_SUBAGENT_EXTENSION_PATH) return true;
+      return ![...legacyPaths].some((legacyPath) =>
+        [...SUBAGENT_TOOL_NAMES].some((name) =>
+          error.error === `Tool "${name}" conflicts with ${legacyPath}`
+        )
+      );
+    }),
+  };
+}

package/lib/subagent-input.test.mjs

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const {
+  appendSubagentInputFiles,
+  loadSubagentInputFiles,
+  MAX_SUBAGENT_INPUT_BYTES,
+  MAX_SUBAGENT_INPUT_FILES,
+} = await createJiti(import.meta.url).import("./subagent-input.ts");
+
+test("loads cwd-relative UTF-8 files and formats them as delegated user input", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-web-subagent-input-"));
+  try {
+    await mkdir(join(cwd, "docs"));
+    await writeFile(join(cwd, "docs", "article.md"), "# Article\n\nEvidence.", "utf8");
+
+    const files = loadSubagentInputFiles(cwd, ["docs/article.md"]);
+    assert.deepEqual(files, [{ path: "docs/article.md", content: "# Article\n\nEvidence." }]);
+    assert.equal(
+      appendSubagentInputFiles("Analyze the argument.", files),
+      "Analyze the argument.\n\n<documents>\n<document path=\"docs/article.md\">\n# Article\n\nEvidence.\n</document>\n</documents>",
+    );
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("rejects files outside cwd, including symlink targets", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-web-subagent-input-cwd-"));
+  const outside = await mkdtemp(join(tmpdir(), "pi-web-subagent-input-outside-"));
+  try {
+    const outsideFile = join(outside, "article.md");
+    await writeFile(outsideFile, "Private", "utf8");
+    await symlink(outsideFile, join(cwd, "linked.md"));
+
+    assert.throws(() => loadSubagentInputFiles(cwd, [outsideFile]), /outside the session cwd/);
+    assert.throws(() => loadSubagentInputFiles(cwd, ["linked.md"]), /outside the session cwd/);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("rejects invalid UTF-8 and bounded input sets", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "pi-web-subagent-input-"));
+  try {
+    await writeFile(join(cwd, "binary.txt"), Buffer.from([0xc3, 0x28]));
+    await writeFile(join(cwd, "large.txt"), "x".repeat(MAX_SUBAGENT_INPUT_BYTES + 1), "utf8");
+
+    assert.throws(() => loadSubagentInputFiles(cwd, ["binary.txt"]), /not valid UTF-8/);
+    assert.throws(() => loadSubagentInputFiles(cwd, ["large.txt"]), /total limit/);
+    assert.throws(
+      () => loadSubagentInputFiles(cwd, Array(MAX_SUBAGENT_INPUT_FILES + 1).fill("binary.txt")),
+      /at most/,
+    );
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});

package/lib/subagent-input.ts

@@ -0,0 +1,71 @@
+import { readFileSync, realpathSync, statSync } from "fs";
+import { relative, resolve } from "path";
+import { isPathWithinRoots } from "./path-security";
+import { toSlashPath } from "./paths";
+
+export const MAX_SUBAGENT_INPUT_FILES = 8;
+export const MAX_SUBAGENT_INPUT_BYTES = 512 * 1024;
+
+export interface SubagentInputFile {
+  path: string;
+  content: string;
+}
+
+export function loadSubagentInputFiles(cwd: string, requestedPaths: readonly string[]): SubagentInputFile[] {
+  if (requestedPaths.length > MAX_SUBAGENT_INPUT_FILES) {
+    throw new Error(`Agent input_files accepts at most ${MAX_SUBAGENT_INPUT_FILES} files`);
+  }
+
+  const realCwd = realpathSync(cwd);
+  const allowedRoots = new Set([realCwd]);
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const seen = new Set<string>();
+  const files: SubagentInputFile[] = [];
+  let totalBytes = 0;
+
+  for (const requestedPath of requestedPaths) {
+    if (!requestedPath.trim()) throw new Error("Agent input_files paths must not be empty");
+
+    let filePath: string;
+    try {
+      filePath = realpathSync(resolve(cwd, requestedPath));
+    } catch {
+      throw new Error(`Agent input file does not exist: ${requestedPath}`);
+    }
+    if (!isPathWithinRoots(filePath, allowedRoots)) {
+      throw new Error(`Agent input file is outside the session cwd: ${requestedPath}`);
+    }
+    if (!statSync(filePath).isFile()) {
+      throw new Error(`Agent input path is not a file: ${requestedPath}`);
+    }
+    if (seen.has(filePath)) continue;
+    seen.add(filePath);
+
+    const buffer = readFileSync(filePath);
+    totalBytes += buffer.byteLength;
+    if (totalBytes > MAX_SUBAGENT_INPUT_BYTES) {
+      throw new Error(`Agent input_files exceeds the ${MAX_SUBAGENT_INPUT_BYTES}-byte total limit`);
+    }
+
+    let content: string;
+    try {
+      content = decoder.decode(buffer);
+    } catch {
+      throw new Error(`Agent input file is not valid UTF-8 text: ${requestedPath}`);
+    }
+    files.push({
+      path: toSlashPath(relative(realCwd, filePath)),
+      content,
+    });
+  }
+
+  return files;
+}
+
+export function appendSubagentInputFiles(task: string, files: readonly SubagentInputFile[]): string {
+  if (files.length === 0) return task;
+  const documents = files.map((file) =>
+    `<document path=${JSON.stringify(file.path)}>\n${file.content}\n</document>`
+  ).join("\n\n");
+  return `${task}\n\n<documents>\n${documents}\n</documents>`;
+}

package/lib/subagent-profile-precedence.ts

@@ -0,0 +1,20 @@
+import type { SubagentProfile, SubagentScope } from "./subagents";
+
+const SUBAGENT_SCOPE_PRIORITY: Record<SubagentScope, number> = {
+  builtin: 0,
+  global: 1,
+  workspace: 2,
+  project: 3,
+};
+
+export function isSubagentProfileOverridden(
+  profile: Pick<SubagentProfile, "name" | "scope">,
+  profiles: readonly Pick<SubagentProfile, "name" | "scope">[],
+): boolean {
+  const name = profile.name.toLowerCase();
+  const priority = SUBAGENT_SCOPE_PRIORITY[profile.scope];
+  return profiles.some((candidate) =>
+    candidate.name.toLowerCase() === name
+    && SUBAGENT_SCOPE_PRIORITY[candidate.scope] > priority
+  );
+}

package/lib/subagent-prompt.test.mjs

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const { buildSubagentPromptPlan } = await createJiti(import.meta.url).import("./subagent-prompt.ts");
+
+test("a tool-free subagent uses only its profile as the exact system prompt", () => {
+  const plan = buildSubagentPromptPlan({
+    profileSystemPrompt: "Review carefully.",
+    tools: [],
+    task: "Inspect the parser.",
+    inheritedParentContext: "Parent context",
+  });
+
+  assert.equal(plan.chatOnly, true);
+  assert.equal(plan.exactSystemPrompt, "Review carefully.");
+  assert.deepEqual(plan.appendSystemPrompt, ["Review carefully."]);
+  assert.equal(plan.delegatedTask, "Inspect the parser.\n\nParent context");
+});
+
+test("a tool-enabled subagent retains inherited context in its appended system prompt", () => {
+  const plan = buildSubagentPromptPlan({
+    profileSystemPrompt: "Explore carefully.",
+    tools: ["read"],
+    task: "Inspect the parser.",
+    inheritedParentContext: "Parent context",
+  });
+
+  assert.equal(plan.chatOnly, false);
+  assert.equal(plan.exactSystemPrompt, undefined);
+  assert.deepEqual(plan.appendSystemPrompt, ["Explore carefully.", "Parent context"]);
+  assert.equal(plan.delegatedTask, "Inspect the parser.");
+});
+
+test("a resource-enabled tool-free subagent keeps the normal system prompt pipeline", () => {
+  for (const resources of [
+    { loadSkills: true, loadExtensions: false },
+    { loadSkills: false, loadExtensions: true },
+  ]) {
+    const plan = buildSubagentPromptPlan({
+      profileSystemPrompt: "Use loaded resources.",
+      tools: [],
+      ...resources,
+      task: "Inspect the parser.",
+      inheritedParentContext: "Parent context",
+    });
+
+    assert.equal(plan.chatOnly, false);
+    assert.equal(plan.exactSystemPrompt, undefined);
+    assert.deepEqual(plan.appendSystemPrompt, ["Use loaded resources.", "Parent context"]);
+    assert.equal(plan.delegatedTask, "Inspect the parser.");
+  }
+});
+
+test("replace prompt mode makes the profile body the exact system prompt", () => {
+  const plan = buildSubagentPromptPlan({
+    profileSystemPrompt: "Only these instructions.",
+    tools: ["read"],
+    promptMode: "replace",
+    task: "Inspect the parser.",
+  });
+  assert.equal(plan.exactSystemPrompt, "Only these instructions.");
+  assert.equal(plan.delegatedTask, "Inspect the parser.");
+});

package/lib/subagent-prompt.ts

@@ -0,0 +1,31 @@
+export interface SubagentPromptPlan {
+  chatOnly: boolean;
+  appendSystemPrompt: string[];
+  delegatedTask: string;
+  exactSystemPrompt?: string;
+}
+
+export function buildSubagentPromptPlan(options: {
+  profileSystemPrompt: string;
+  tools: readonly string[];
+  loadSkills?: boolean;
+  loadExtensions?: boolean;
+  promptMode?: "replace" | "append";
+  task: string;
+  inheritedParentContext?: string;
+}): SubagentPromptPlan {
+  const chatOnly = options.tools.length === 0 && !options.loadSkills && !options.loadExtensions;
+  const replacePrompt = options.promptMode === "replace";
+  const appendSystemPrompt = [options.profileSystemPrompt];
+  if (options.inheritedParentContext && !chatOnly) {
+    appendSystemPrompt.push(options.inheritedParentContext);
+  }
+  return {
+    chatOnly,
+    appendSystemPrompt,
+    delegatedTask: options.inheritedParentContext && chatOnly
+      ? `${options.task}\n\n${options.inheritedParentContext}`
+      : options.task,
+    ...(chatOnly || replacePrompt ? { exactSystemPrompt: options.profileSystemPrompt } : {}),
+  };
+}

package/lib/subagent-queue.test.mjs

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const { SubagentQueue } = await createJiti(import.meta.url).import("./subagent-queue.ts");
+
+test("runs FIFO with a per-parent concurrency limit and drains after completion", async () => {
+  const queue = new SubagentQueue();
+  const events = [];
+  let release;
+  const first = queue.enqueue("parent", 1, () => new Promise((resolve) => { release = () => resolve("first"); }), (state) => events.push(["first", state]));
+  const second = queue.enqueue("parent", 1, async () => "second", (state) => events.push(["second", state]));
+  assert.deepEqual(events, [["first", "queued"], ["first", "running"], ["second", "queued"]]);
+  release();
+  assert.equal(await first.promise, "first");
+  assert.equal(await second.promise, "second");
+  assert.deepEqual(events, [
+    ["first", "queued"], ["first", "running"], ["second", "queued"], ["second", "running"],
+  ]);
+});
+
+test("cancels queued work without starting it", async () => {
+  const queue = new SubagentQueue();
+  let release;
+  const first = queue.enqueue("parent", 1, () => new Promise((resolve) => { release = resolve; }), () => {});
+  let started = false;
+  let cancelled = false;
+  const second = queue.enqueue("parent", 1, async () => { started = true; return "bad"; }, () => {}, () => { cancelled = true; });
+  assert.equal(second.cancel(), true);
+  assert.equal(cancelled, true);
+  release();
+  await first.promise;
+  assert.equal(await second.promise, undefined);
+  assert.equal(started, false);
+});

package/lib/subagent-queue.ts

@@ -0,0 +1,74 @@
+export type SubagentQueueState = "queued" | "running";
+
+interface QueueItem<T> {
+  run: () => Promise<T>;
+  onState: (state: SubagentQueueState) => void;
+  onCancel?: () => void | Promise<void>;
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+  state: SubagentQueueState;
+  cancelled: boolean;
+}
+
+type ParentQueue<T> = {
+  limit: number;
+  active: number;
+  items: QueueItem<T>[];
+};
+
+export interface EnqueuedSubagent<T> {
+  promise: Promise<T>;
+  cancel(): boolean;
+}
+
+/** FIFO per parent session; separate parents do not block one another. */
+export class SubagentQueue<T> {
+  private readonly parents = new Map<string, ParentQueue<T>>();
+
+  enqueue(
+    parentId: string,
+    limit: number,
+    run: () => Promise<T>,
+    onState: (state: SubagentQueueState) => void,
+    onCancel?: () => void,
+  ): EnqueuedSubagent<T> {
+    const parent = this.parents.get(parentId) ?? { limit: 1, active: 0, items: [] };
+    parent.limit = Math.max(1, Math.floor(limit) || 1);
+    let item!: QueueItem<T>;
+    const promise = new Promise<T>((resolve, reject) => {
+      item = { run, onState, onCancel, resolve, reject, state: "queued", cancelled: false };
+    });
+    parent.items.push(item);
+    this.parents.set(parentId, parent);
+    onState("queued");
+    this.pump(parentId, parent);
+    return {
+      promise,
+      cancel: () => {
+        if (item.state !== "queued" || item.cancelled) return false;
+        item.cancelled = true;
+        Promise.resolve(item.onCancel?.()).then(
+          () => item.resolve(undefined as T),
+          (error) => item.reject(error),
+        );
+        this.pump(parentId, parent);
+        return true;
+      },
+    };
+  }
+
+  private pump(parentId: string, parent: ParentQueue<T>): void {
+    while (parent.active < parent.limit && parent.items.length > 0) {
+      const item = parent.items.shift()!;
+      if (item.cancelled) continue;
+      item.state = "running";
+      item.onState("running");
+      parent.active += 1;
+      void item.run().then(item.resolve, item.reject).finally(() => {
+        parent.active -= 1;
+        this.pump(parentId, parent);
+        if (parent.active === 0 && parent.items.length === 0) this.parents.delete(parentId);
+      });
+    }
+  }
+}