@humain/terminal 0.1.0 → 0.2.1

package/dist/core/tools/subagent.js

@@ -23,19 +23,13 @@ import { getMarkdownTheme } from "../../modes/interactive/theme/theme.js";
 import { parseFrontmatter } from "../../utils/frontmatter.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { shortenPath } from "./render-utils.js";
+import { currentSubagentDepth, currentTaskId, maxParallelTasks, maxSubagentConcurrency, maxSubagentDepth, PARENT_TASK_ID_ENV, SUBAGENT_DEPTH_ENV, TASK_BASE_REVISION_ENV, TASK_ID_ENV, } from "./subagent-env.js";
+import { runDag, validateTaskGraph } from "./subagent-scheduler.js";
+export { SUBAGENT_DEPTH_ENV } from "./subagent-env.js";
 import { createSubagentWorktree, isGitWorkTree, } from "./subagent-worktree.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
-const MAX_PARALLEL_TASKS = 8;
-const MAX_CONCURRENCY = 4;
 const COLLAPSED_ITEM_COUNT = 10;
 const PER_TASK_OUTPUT_CAP = 50 * 1024;
-/** Children must not delegate further: depth 0 = top-level agent, depth >= 1 = subagent. */
-export const SUBAGENT_DEPTH_ENV = "HUMAIN_TERMINAL_SUBAGENT_DEPTH";
-const MAX_SUBAGENT_DEPTH = 1;
-function currentSubagentDepth() {
-    const raw = Number(process.env[SUBAGENT_DEPTH_ENV] ?? "0");
-    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 0;
-}
 function loadAgentsFromDir(dir, source) {
     const agents = [];
     if (!fs.existsSync(dir)) {
@@ -211,6 +205,16 @@ function formatToolCall(toolName, args, themeFg) {
         }
     }
 }
+export function renderTaskWithContext(task, context) {
+    const parts = [`Task: ${task}`];
+    if (context?.files?.length)
+        parts.push(`Context files:\n${context.files.map((f) => `- ${f}`).join("\n")}`);
+    if (context?.acceptance?.length)
+        parts.push(`Acceptance criteria:\n${context.acceptance.map((a) => `- ${a}`).join("\n")}`);
+    if (context?.baseRevision)
+        parts.push(`Base revision: ${context.baseRevision}`);
+    return parts.join("\n\n");
+}
 function getFinalOutput(messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
         const msg = messages[i];
@@ -259,28 +263,6 @@ function getDisplayItems(messages) {
     }
     return items;
 }
-async function mapWithConcurrencyLimit(items, concurrency, fn, signal, onAbort) {
-    if (items.length === 0)
-        return [];
-    const limit = Math.max(1, Math.min(concurrency, items.length));
-    const results = new Array(items.length);
-    let nextIndex = 0;
-    const workers = new Array(limit).fill(null).map(async () => {
-        while (true) {
-            const current = nextIndex++;
-            if (current >= items.length)
-                return;
-            if (signal?.aborted) {
-                if (onAbort)
-                    results[current] = await onAbort(items[current], current);
-                continue;
-            }
-            results[current] = await fn(items[current], current);
-        }
-    });
-    await Promise.all(workers);
-    return results;
-}
 async function writePromptToTempFile(agentName, prompt) {
     const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "humain-subagent-"));
     const safeName = agentName.replace(/[^\w.-]+/g, "_");
@@ -303,7 +285,9 @@ function getCliInvocation(args) {
     }
     return { command: "humain-terminal", args };
 }
-async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolation, step, model, parentModel, signal, onUpdate, makeDetails, toolCallId, childIndex) {
+async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolation, step, model, parentModel, signal, onUpdate, makeDetails, toolCallId, childIndex, options) {
+    const childDepth = currentSubagentDepth() + 1;
+    const parentTaskId = currentTaskId() ?? toolCallId;
     const agent = agents.find((a) => a.name === agentName);
     if (!agent) {
         const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
@@ -311,12 +295,18 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolatio
             agent: agentName,
             agentSource: "unknown",
             task,
+            taskId: options.taskId,
+            parentTaskId,
+            depth: childDepth,
             exitCode: 1,
             messages: [],
             stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
             usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
             step,
             isolation: "shared",
+            thinking: options.thinking,
+            attempt: options.attempt,
+            baseRevision: options.context?.baseRevision,
         };
     }
     let worktree = null;
@@ -342,12 +332,19 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolatio
     }
     if (agent.tools && agent.tools.length > 0)
         args.push("--tools", agent.tools.join(","));
+    if (options.thinking)
+        args.push("--thinking", options.thinking);
     let tmpPromptDir = null;
     let tmpPromptPath = null;
     const currentResult = {
         agent: agentName,
         agentSource: agent.source,
         task,
+        taskId: options.taskId,
+        parentTaskId,
+        depth: childDepth,
+        thinking: options.thinking,
+        attempt: options.attempt,
         exitCode: 0,
         messages: [],
         stderr: "",
@@ -355,6 +352,7 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolatio
         model: model ?? `${parentModel.provider}/${parentModel.id}`,
         step,
         isolation: "shared",
+        baseRevision: options.context?.baseRevision,
     };
     const emitUpdate = () => {
         if (onUpdate) {
@@ -386,14 +384,24 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolatio
             tmpPromptPath = tmp.filePath;
             args.push("--append-system-prompt", tmpPromptPath);
         }
-        args.push(`Task: ${task}`);
+        args.push(renderTaskWithContext(task, options.context));
         const exitCode = await new Promise((resolve) => {
             const invocation = getCliInvocation(args);
+            const env = {
+                ...process.env,
+                [SUBAGENT_DEPTH_ENV]: String(childDepth),
+                [TASK_ID_ENV]: options.taskId,
+                [PARENT_TASK_ID_ENV]: parentTaskId,
+            };
+            if (options.context?.baseRevision)
+                env[TASK_BASE_REVISION_ENV] = options.context.baseRevision;
+            else
+                delete env[TASK_BASE_REVISION_ENV];
             const proc = spawn(invocation.command, invocation.args, {
                 cwd: childCwd,
                 shell: false,
                 stdio: ["ignore", "pipe", "pipe"],
-                env: { ...process.env, [SUBAGENT_DEPTH_ENV]: String(currentSubagentDepth() + 1) },
+                env,
             });
             let buffer = "";
             let settled = false;
@@ -549,9 +557,14 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, isolatio
     }
     return currentResult;
 }
+const ThinkingLevelSchema = StringEnum(["off", "minimal", "low", "medium", "high", "xhigh", "max"], {
+    description: "Reasoning effort for this child. Maps to the CLI --thinking level. Defaults to the child's own default.",
+});
 const TaskItem = Type.Object({
     agent: Type.String({ description: "Name of the agent to invoke" }),
     task: Type.String({ description: "Task to delegate to the agent" }),
+    id: Type.Optional(Type.String({ description: "Stable task id. Defaults to <toolCallId>-<index>. Referenced by dependsOn." })),
+    thinking: Type.Optional(ThinkingLevelSchema),
     model: Type.Optional(Type.String({
         description: "Optional canonical provider/model for this child. Defaults to the parent provider/model.",
     })),
@@ -559,6 +572,26 @@ const TaskItem = Type.Object({
     isolation: Type.Optional(StringEnum(["shared", "worktree"], {
         description: "Filesystem isolation for this child. 'worktree' runs it in a disposable git worktree and merges its changes back; the caller's policy sets this, not the model.",
     })),
+    dependsOn: Type.Optional(Type.Array(Type.String(), {
+        description: "Ids of sibling tasks that must complete successfully before this one starts.",
+    })),
+    ownerPaths: Type.Optional(Type.Array(Type.String(), {
+        description: "Repo-relative paths this task owns. Siblings whose ownerPaths overlap run one after another instead of in parallel.",
+    })),
+    onFailure: Type.Optional(Type.Object({
+        retryWith: Type.Optional(Type.Object({
+            model: Type.Optional(Type.String({ description: "Canonical provider/model for the retry." })),
+            thinking: Type.Optional(ThinkingLevelSchema),
+        })),
+        maxAttempts: Type.Optional(Type.Integer({ minimum: 1, maximum: 3, description: "Total attempts including the first. Default 1." })),
+    }, {
+        description: "Retry only this task on failure with a different model or thinking level. The caller's policy sets this.",
+    })),
+    context: Type.Optional(Type.Object({
+        files: Type.Optional(Type.Array(Type.String(), { description: "Files the child should read first." })),
+        acceptance: Type.Optional(Type.Array(Type.String(), { description: "Acceptance criteria the child must satisfy." })),
+        baseRevision: Type.Optional(Type.String({ description: "Git revision the packet was assembled against." })),
+    }, { description: "Bounded context packet for this child." })),
 });
 const ChainItem = Type.Object({
     agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -566,6 +599,7 @@ const ChainItem = Type.Object({
     model: Type.Optional(Type.String({
         description: "Optional canonical provider/model for this child. Defaults to the parent provider/model.",
     })),
+    thinking: Type.Optional(ThinkingLevelSchema),
     cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 });
 const AgentScopeSchema = StringEnum(["user", "project", "both"], {
@@ -578,6 +612,7 @@ const SubagentParams = Type.Object({
     model: Type.Optional(Type.String({
         description: "Optional canonical provider/model for this child. Defaults to the parent provider/model.",
     })),
+    thinking: Type.Optional(ThinkingLevelSchema),
     tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
     chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
     agentScope: Type.Optional(AgentScopeSchema),
@@ -594,13 +629,14 @@ export function createSubagentToolDefinition(cwd) {
         description: [
             "Delegate tasks to specialized subagents with isolated context.",
             "Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
-            "The optional isolation field is policy-set for each child.",
+            "Parallel tasks may declare id, dependsOn (start after those ids succeed), ownerPaths (overlapping siblings run one at a time), thinking (reasoning level), context (files, acceptance criteria, base revision) and onFailure (retry this task with another model or thinking level).",
+            "The optional isolation, thinking and onFailure fields are policy-set for each child.",
             `Default agent scope is "user" (from ${path.join(getAgentDir(), "agents")}).`,
             `To enable project-local agents in ${CONFIG_DIR_NAME}/agents, set agentScope: "both" (or "project").`,
         ].join(" "),
         promptSnippet: "subagent: delegate work to isolated subagents — single task, parallel batch (tasks array), or sequential chain with {previous} placeholder",
         promptGuidelines: [
-            "Use subagent to fan out independent work in parallel (tasks array) or run multi-step pipelines (chain). Subagents run with isolated context and cannot delegate further.",
+            "Use subagent to fan out independent work in parallel (tasks array) or run multi-step pipelines (chain). Subagents run with isolated context. Nested delegation is allowed only up to the configured depth; a child at the limit must complete its task directly.",
         ],
         parameters: SubagentParams,
         async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -615,17 +651,29 @@ export function createSubagentToolDefinition(cwd) {
             // the tool args and reconcile it against results by index.
             const requestedChildren = () => {
                 if (params.tasks && params.tasks.length > 0)
-                    return params.tasks.map((t) => ({ agent: t.agent, task: t.task }));
+                    return params.tasks.map((t, i) => ({
+                        agent: t.agent,
+                        task: t.task,
+                        taskId: t.id ?? `${toolCallId}-${i}`,
+                    }));
                 if (params.chain && params.chain.length > 0)
-                    return params.chain.map((s, i) => ({ agent: s.agent, task: s.task, step: i + 1 }));
+                    return params.chain.map((s, i) => ({
+                        agent: s.agent,
+                        task: s.task,
+                        step: i + 1,
+                        taskId: `${toolCallId}-${i}`,
+                    }));
                 if (params.agent)
-                    return [{ agent: params.agent, task: params.task }];
+                    return [{ agent: params.agent, task: params.task, taskId: `${toolCallId}-0` }];
                 return [];
             };
             const stubResult = (child, errorMessage) => ({
                 agent: child.agent,
                 agentSource: "unknown",
                 task: child.task ?? "",
+                taskId: child.taskId ?? `${toolCallId}-${child.step !== undefined ? child.step - 1 : 0}`,
+                parentTaskId: currentTaskId() ?? toolCallId,
+                depth: currentSubagentDepth() + 1,
                 exitCode: 1,
                 messages: [],
                 stderr: "",
@@ -641,12 +689,12 @@ export function createSubagentToolDefinition(cwd) {
                 projectAgentsDir: discovery.projectAgentsDir,
                 results,
             });
-            if (currentSubagentDepth() >= MAX_SUBAGENT_DEPTH) {
+            if (currentSubagentDepth() >= maxSubagentDepth()) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "Nested delegation is not allowed: this process is already a subagent. Complete the task directly.",
+                            text: `Nested delegation limit reached (depth ${currentSubagentDepth()} of ${maxSubagentDepth()}). Complete the task directly.`,
                         },
                     ],
                     details: makeDetails("single")([]),
@@ -725,7 +773,7 @@ export function createSubagentToolDefinition(cwd) {
                             }
                         }
                         : undefined;
-                    const result = await runSingleAgent(defaultCwd, agents, step.agent, taskWithContext, step.cwd, undefined, i + 1, step.model, parentModel, signal, chainUpdate, makeDetails("chain"), toolCallId, i);
+                    const result = await runSingleAgent(defaultCwd, agents, step.agent, taskWithContext, step.cwd, undefined, i + 1, step.model, parentModel, signal, chainUpdate, makeDetails("chain"), toolCallId, i, { taskId: `${toolCallId}-${i}`, thinking: step.thinking });
                     results.push(result);
                     const isError = isFailedResult(result);
                     if (isError) {
@@ -747,32 +795,61 @@ export function createSubagentToolDefinition(cwd) {
                 };
             }
             if (params.tasks && params.tasks.length > 0) {
-                if (params.tasks.length > MAX_PARALLEL_TASKS)
+                const taskCap = maxParallelTasks();
+                if (params.tasks.length > taskCap)
                     return {
                         content: [
-                            {
-                                type: "text",
-                                text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
-                            },
+                            { type: "text", text: `Too many parallel tasks (${params.tasks.length}). Max is ${taskCap}.` },
                         ],
-                        details: makeDetails("parallel")(stubAllChildren(`not run: too many parallel tasks (max ${MAX_PARALLEL_TASKS})`)),
+                        details: makeDetails("parallel")(stubAllChildren(`not run: too many parallel tasks (max ${taskCap})`)),
                         isError: true,
                     };
-                // Track all results for streaming updates
-                const allResults = new Array(params.tasks.length);
-                // Initialize placeholder results
-                for (let i = 0; i < params.tasks.length; i++) {
-                    allResults[i] = {
-                        agent: params.tasks[i].agent,
-                        agentSource: "unknown",
-                        task: params.tasks[i].task,
-                        exitCode: -1, // -1 = still running
-                        messages: [],
-                        stderr: "",
-                        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-                        isolation: "shared",
+                const childDepth = currentSubagentDepth() + 1;
+                const graph = params.tasks.map((t, i) => ({
+                    ...t,
+                    id: t.id ?? `${toolCallId}-${i}`,
+                    dependsOn: t.dependsOn ?? [],
+                    ownerPaths: t.ownerPaths ?? [],
+                }));
+                const graphError = validateTaskGraph(graph);
+                if (graphError) {
+                    return {
+                        content: [{ type: "text", text: `Invalid task graph: ${graphError}.` }],
+                        details: makeDetails("parallel")(stubAllChildren(`not run: invalid task graph (${graphError})`)),
+                        isError: true,
                     };
                 }
+                const taskEvents = [];
+                const emitTaskEvent = (event) => {
+                    taskEvents.push(event);
+                };
+                const now = () => Date.now();
+                for (const g of graph)
+                    emitTaskEvent({
+                        type: "schedule",
+                        taskId: g.id,
+                        dependsOn: g.dependsOn,
+                        ownerPaths: g.ownerPaths,
+                        baseRevision: g.context?.baseRevision,
+                        at: now(),
+                    });
+                const allResults = graph.map((g) => ({
+                    agent: g.agent,
+                    agentSource: "unknown",
+                    task: g.task,
+                    taskId: g.id,
+                    parentTaskId: currentTaskId() ?? toolCallId,
+                    depth: childDepth,
+                    exitCode: -1, // -1 = still running
+                    messages: [],
+                    stderr: "",
+                    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+                    isolation: "shared",
+                }));
+                const detailsWithEvents = (results) => ({
+                    ...makeDetails("parallel")(results),
+                    taskEvents: [...taskEvents],
+                });
                 const emitParallelUpdate = () => {
                     if (onUpdate) {
                         const running = allResults.filter((r) => r.exitCode === -1).length;
@@ -781,23 +858,84 @@ export function createSubagentToolDefinition(cwd) {
                             content: [
                                 { type: "text", text: `Parallel: ${done}/${allResults.length} done, ${running} running...` },
                             ],
-                            details: makeDetails("parallel")([...allResults]),
+                            details: detailsWithEvents([...allResults]),
                         });
                     }
                 };
-                const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
-                    const result = await runSingleAgent(defaultCwd, agents, t.agent, t.task, t.cwd, t.isolation, undefined, t.model, parentModel, signal, 
-                    // Per-task update callback
-                    (partial) => {
-                        if (partial.details?.results[0]) {
-                            allResults[index] = partial.details.results[0];
-                            emitParallelUpdate();
+                let results;
+                try {
+                    results = await runDag(graph, maxSubagentConcurrency(), async (g, index) => {
+                        const maxAttempts = Math.min(3, Math.max(1, g.onFailure?.maxAttempts ?? 1));
+                        let attempt = 1;
+                        let model = g.model;
+                        let thinking = g.thinking;
+                        let result;
+                        for (;;) {
+                            emitTaskEvent({ type: "start", taskId: g.id, attempt, at: now() });
+                            result = await runSingleAgent(defaultCwd, agents, g.agent, g.task, g.cwd, g.isolation, undefined, model, parentModel, signal, (partial) => {
+                                if (partial.details?.results[0]) {
+                                    allResults[index] = partial.details.results[0];
+                                    emitParallelUpdate();
+                                }
+                            }, detailsWithEvents, toolCallId, index, { taskId: g.id, thinking, attempt, context: g.context });
+                            if (!isFailedResult(result)) {
+                                emitTaskEvent({ type: "complete", taskId: g.id, attempt, at: now() });
+                                break;
+                            }
+                            emitTaskEvent({
+                                type: "fail",
+                                taskId: g.id,
+                                attempt,
+                                reason: getResultOutput(result).slice(0, 200),
+                                at: now(),
+                            });
+                            if (attempt >= maxAttempts || signal?.aborted)
+                                break;
+                            const next = attempt + 1;
+                            model = g.onFailure?.retryWith?.model ?? model;
+                            thinking = g.onFailure?.retryWith?.thinking ?? thinking;
+                            emitTaskEvent({
+                                type: "escalate",
+                                taskId: g.id,
+                                fromAttempt: attempt,
+                                toAttempt: next,
+                                model: model ?? `${parentModel.provider}/${parentModel.id}`,
+                                thinking,
+                                at: now(),
+                            });
+                            attempt = next;
                         }
-                    }, makeDetails("parallel"), toolCallId, index);
-                    allResults[index] = result;
-                    emitParallelUpdate();
-                    return result;
-                }, signal, (t) => stubResult({ agent: t.agent, task: t.task }, "not run: subagent was aborted"));
+                        allResults[index] = result;
+                        emitParallelUpdate();
+                        return result;
+                    }, isFailedResult, (g, index, failedDependency) => {
+                        const stub = stubResult({ agent: g.agent, task: g.task, taskId: g.id }, `not run: dependency "${failedDependency}" failed`);
+                        allResults[index] = stub;
+                        emitParallelUpdate();
+                        return stub;
+                    }, (event) => {
+                        if (event.type === "wait")
+                            emitTaskEvent({ type: "wait", taskId: event.id, reason: "concurrency", at: now() });
+                        else if (event.type === "serialize")
+                            emitTaskEvent({ type: "serialize", taskId: event.id, after: event.after, at: now() });
+                        else if (event.type === "skip")
+                            emitTaskEvent({
+                                type: "skip",
+                                taskId: event.id,
+                                failedDependency: event.failedDependency,
+                                at: now(),
+                            });
+                        // "start" is emitted inside run() together with the attempt number.
+                    }, signal, (g) => stubResult({ agent: g.agent, task: g.task, taskId: g.id }, "not run: subagent was aborted"));
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: "text", text: `Parallel scheduling failed: ${message}` }],
+                        details: detailsWithEvents(stubAllChildren(`not run: scheduling failed (${message})`)),
+                        isError: true,
+                    };
+                }
                 const successCount = results.filter((r) => !isFailedResult(r)).length;
                 const summaries = results.map((r) => {
                     const output = truncateParallelOutput(getResultOutput(r));
@@ -813,12 +951,12 @@ export function createSubagentToolDefinition(cwd) {
                             text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`,
                         },
                     ],
-                    details: makeDetails("parallel")(results),
+                    details: detailsWithEvents(results),
                     isError: successCount !== results.length,
                 };
             }
             if (params.agent && params.task) {
-                const result = await runSingleAgent(defaultCwd, agents, params.agent, params.task, params.cwd, params.isolation, undefined, params.model, parentModel, signal, onUpdate, makeDetails("single"), toolCallId, 0);
+                const result = await runSingleAgent(defaultCwd, agents, params.agent, params.task, params.cwd, params.isolation, undefined, params.model, parentModel, signal, onUpdate, makeDetails("single"), toolCallId, 0, { taskId: `${toolCallId}-0`, thinking: params.thinking });
                 const isError = isFailedResult(result);
                 if (isError) {
                     const errorMsg = getResultOutput(result);