TODO Next: subagent parallelism (task tasks batch)
task now accepts { description, prompt, kind } or
{ tasks: TaskSpec[], kind? } (up to 8) and fans out with
Promise.all. Each subagent keeps its own context window and
the progress panel receives start/step/result/end per id, so
independent searches overlap in wall time instead of queueing.
- src/subagent.ts: runOne extracted, createTaskTool uses union
schema (single | batch), batch validates worker channel once
then Promise.all, results joined as headings.
- docs/agents.md: delegation section notes tasks batch.
- 800 pass (added subagent-parallel.test.ts).
This commit is contained in:
asepharyana
@@ -14,7 +14,7 @@ TODO.md status 2026-09-08:
|
||||
1. **Now flip + tests** — patch TODO.md [x], test: hot-reload skill mid-session callable, pruned decision recoverable. Verifikasi: bun test.
|
||||
2. **Derive tool-name lists** — tandai mutating di definisi tool (tools.ts/tools-extra.ts/tools-git.ts/tools-net.ts), TOOL_SETS & MUTATING_TOOLS derive + test coverage. Risiko: silently ungated write jika lupa.
|
||||
3. **MCP tanpa schema tax** — DONE: phi 3 meta-tools mcp_list/mcp_inspect/mcp_call (mcpExpose=phi/direct/auto), prompt hanya nama server, permission+guard lewat built-in, keep direct registration untuk server 2-tool. Test: server 20-tool 0 schema sampai mcp_call (mcp.test.ts).
|
||||
4. **Subagent parallelism** — task terima beberapa investigations, run Promise.all dengan panel fan-out, test overlap waktu.
|
||||
4. **Subagent parallelism** — DONE: task `tasks` union + Promise.all fan-out (8 cap), panel per-subagent, test overlap waktu (subagent-parallel.test.ts).
|
||||
5. **Undo a turn** — snapshot file-tool edits pre-prompt (cap 100), /undo restores files+conversation atau keduanya, /redo, bash tidak ter-snapshot (docs), test edit reverted + record hilang.
|
||||
6. **Maintenance polish** — pricing source+date, estimateTokens label everywhere /cost, listPaths notice staleness / refresh, MUTATING derive dari #2.
|
||||
|
||||
|
||||
@@ -61,8 +61,8 @@ have.
|
||||
Two independent searches run sequentially. The panel already renders several agents; the loop
|
||||
does not fan out.
|
||||
|
||||
- [ ] `task` accepts several investigations and runs them together
|
||||
- [ ] Test: two delegated searches overlap in time rather than queueing
|
||||
- [x] `task` accepts several investigations and runs them together (`src/subagent.ts`: `tasks: TaskSpec[]` union, `runOne` + `Promise.all` fan-out up to 8, panel emits start/step/result/end per subagent)
|
||||
- [x] Test: two delegated searches overlap in time rather than queueing (`test/subagent-parallel.test.ts`: delayed greps overlap < 2*delay, both headings in one tool result)
|
||||
|
||||
### Undo a turn
|
||||
|
||||
|
||||
+1
-1
@@ -175,7 +175,7 @@ around it. The tool descriptions say the same thing, so the rule survives compac
|
||||
accident. The read-only kinds work everywhere. No subagent holds `web_fetch`; network access
|
||||
stays with the main agent, where the approval prompt says what it is for.
|
||||
|
||||
When not to delegate: a single grep, or anything you must supervise step by step — keep that in
|
||||
For independent pieces of work, pass `tasks: [{description, prompt}, …]` to run them in parallel instead of calling `task` several times — each subagent keeps its own window and the panel fans out. When not to delegate: a single grep, or anything you must supervise step by step — keep that in
|
||||
your own turn, where every call is on screen. A worker wins when the intermediate steps are
|
||||
noise: a mechanical rename across twenty files, a test scaffold written to match an existing
|
||||
suite, a cleanup whose shape you already know.
|
||||
|
||||
+110
-45
@@ -139,68 +139,39 @@ let counter = 0;
|
||||
* asked for a worker and got an explorer would be told the task failed for the
|
||||
* wrong reason.
|
||||
*/
|
||||
export function createTaskTool(opts: {
|
||||
export type TaskSpec = { description: string; prompt: string; kind?: SubagentKind };
|
||||
|
||||
async function runOne(
|
||||
spec: TaskSpec,
|
||||
id: string,
|
||||
opts: {
|
||||
model: LanguageModel;
|
||||
/** Cheaper model for `explore`, which is search rather than reasoning. Defaults to `model`. */
|
||||
subagentModel?: LanguageModel;
|
||||
/** Its id, so the parent can price the subagent's spend separately. */
|
||||
subagentModelId?: string;
|
||||
cwd?: string;
|
||||
maxSteps?: number;
|
||||
report?: SubagentReporter;
|
||||
/** Parent-owned approval for a worker's gated calls. Omit to disable `worker`. */
|
||||
approve?: SubagentApproval;
|
||||
/** Records a finished run's token use, so /cost can split subagent from parent spend. */
|
||||
onUsage?: (usage: { kind: SubagentKind; inputTokens: number; outputTokens: number }) => void;
|
||||
}) {
|
||||
const canWrite = opts.approve !== undefined;
|
||||
|
||||
return tool({
|
||||
description:
|
||||
'Delegate work to a subagent with its own context window. It sees none of this conversation, so its ' +
|
||||
'prompt must be self-contained, and it returns one text report.\n' +
|
||||
'explore: find and report, read-only. review: critique code for defects, read-only.' +
|
||||
(canWrite
|
||||
? '\nworker: read, edit, and run commands to carry out a change. Its writes and commands are approved by ' +
|
||||
'the user exactly as yours are. Use it for a self-contained task whose intermediate steps you do not ' +
|
||||
'need to see; keep work you must supervise step by step in your own turn.'
|
||||
: '') +
|
||||
'\nDo not delegate something you can answer with a single grep.',
|
||||
inputSchema: z.object({
|
||||
description: z.string().describe('Short label shown to the user, 3-6 words'),
|
||||
prompt: z.string().describe('Self-contained instructions: what to do, where, and what to report'),
|
||||
kind: z
|
||||
.enum(canWrite ? ['explore', 'review', 'worker'] : ['explore', 'review'])
|
||||
.optional()
|
||||
.describe(
|
||||
canWrite
|
||||
? 'explore: read-only research. review: read-only critique. worker: makes changes. Default explore.'
|
||||
: 'explore: find and report. review: critique code for defects. Default explore.',
|
||||
),
|
||||
}),
|
||||
execute: async ({ description, prompt, kind }, { abortSignal }) => {
|
||||
const flavour: SubagentKind = kind ?? 'explore';
|
||||
},
|
||||
abortSignal?: AbortSignal,
|
||||
): Promise<string> {
|
||||
const flavour: SubagentKind = spec.kind ?? 'explore';
|
||||
if (flavour === 'worker' && !opts.approve) {
|
||||
throw new Error('The worker kind needs an approval channel, which this session has not provided.');
|
||||
}
|
||||
|
||||
const id = `sub${++counter}`;
|
||||
const report = opts.report;
|
||||
report?.({ type: 'start', id, kind: flavour, description });
|
||||
report?.({ type: 'start', id, kind: flavour, description: spec.description });
|
||||
|
||||
let steps = 0;
|
||||
let text = '';
|
||||
let usedTokens: { inputTokens: number; outputTokens: number } | undefined;
|
||||
|
||||
try {
|
||||
// `explore` is search, not reasoning, so it runs on the cheaper model when
|
||||
// one is configured. `review` and `worker` keep the parent's: they judge
|
||||
// and they change, both of which want the full model.
|
||||
const model = flavour === 'explore' ? (opts.subagentModel ?? opts.model) : opts.model;
|
||||
const result = streamText({
|
||||
model,
|
||||
system: PROMPTS[flavour](opts.cwd ?? process.cwd()),
|
||||
messages: [{ role: 'user', content: prompt }],
|
||||
messages: [{ role: 'user', content: spec.prompt }],
|
||||
tools: TOOLS[flavour],
|
||||
stopWhen: isStepCount(opts.maxSteps ?? 20),
|
||||
...(opts.approve
|
||||
@@ -235,8 +206,6 @@ export function createTaskTool(opts: {
|
||||
} else if (part.type === 'text-delta') {
|
||||
text += part.text;
|
||||
} else if (part.type === 'error') {
|
||||
// A provider failure arrives as a stream part, not a throw, so it has to
|
||||
// be rethrown here or the subagent silently returns nothing.
|
||||
const message = part.error instanceof Error ? part.error.message : String(part.error);
|
||||
throw part.error instanceof Error ? part.error : new Error(message);
|
||||
}
|
||||
@@ -256,10 +225,106 @@ export function createTaskTool(opts: {
|
||||
|
||||
const trimmed = text.trim();
|
||||
report?.({ type: 'end', id, ok: trimmed.length > 0, steps });
|
||||
// Settled after the stream closes; a failed run reports nothing rather than
|
||||
// a half count. The parent prices these against the subagent's own model id.
|
||||
if (usedTokens) opts.onUsage?.({ kind: flavour, ...usedTokens });
|
||||
return trimmed || 'Subagent returned no findings.';
|
||||
}
|
||||
|
||||
export function createTaskTool(opts: {
|
||||
model: LanguageModel;
|
||||
/** Cheaper model for `explore`, which is search rather than reasoning. Defaults to `model`. */
|
||||
subagentModel?: LanguageModel;
|
||||
/** Its id, so the parent can price the subagent's spend separately. */
|
||||
subagentModelId?: string;
|
||||
cwd?: string;
|
||||
maxSteps?: number;
|
||||
report?: SubagentReporter;
|
||||
/** Parent-owned approval for a worker's gated calls. Omit to disable `worker`. */
|
||||
approve?: SubagentApproval;
|
||||
/** Records a finished run's token use, so /cost can split subagent from parent spend. */
|
||||
onUsage?: (usage: { kind: SubagentKind; inputTokens: number; outputTokens: number }) => void;
|
||||
}) {
|
||||
const canWrite = opts.approve !== undefined;
|
||||
const kindEnum = canWrite ? (['explore', 'review', 'worker'] as const) : (['explore', 'review'] as const);
|
||||
const singleSchema = z.object({
|
||||
description: z.string().describe('Short label shown to the user, 3-6 words'),
|
||||
prompt: z.string().describe('Self-contained instructions: what to do, where, and what to report'),
|
||||
kind: z.enum(kindEnum as unknown as [string, ...string[]]).optional().describe(
|
||||
canWrite
|
||||
? 'explore: read-only research. review: read-only critique. worker: makes changes. Default explore.'
|
||||
: 'explore: find and report. review: critique code for defects. Default explore.',
|
||||
),
|
||||
});
|
||||
const batchSchema = z.object({
|
||||
tasks: z
|
||||
.array(
|
||||
z.object({
|
||||
description: z.string().describe('Short label shown to the user, 3-6 words'),
|
||||
prompt: z.string().describe('Self-contained instructions: what to do, where, and what to report'),
|
||||
kind: z.enum(kindEnum as unknown as [string, ...string[]]).optional().describe(
|
||||
canWrite
|
||||
? 'explore: read-only research. review: read-only critique. worker: makes changes. Default explore.'
|
||||
: 'explore: find and report. review: critique code for defects. Default explore.',
|
||||
),
|
||||
}),
|
||||
)
|
||||
.min(1)
|
||||
.max(8)
|
||||
.describe('Several independent investigations to run in parallel. Use this instead of calling task multiple times.'),
|
||||
kind: z.enum(kindEnum as unknown as [string, ...string[]]).optional().describe('Default kind for tasks that omit it'),
|
||||
});
|
||||
|
||||
return tool({
|
||||
description:
|
||||
'Delegate work to a subagent with its own context window. It sees none of this conversation, so its ' +
|
||||
'prompt must be self-contained, and it returns one text report.\n' +
|
||||
'explore: find and report, read-only. review: critique code for defects, read-only.' +
|
||||
(canWrite
|
||||
? '\nworker: read, edit, and run commands to carry out a change. Its writes and commands are approved by ' +
|
||||
'the user exactly as yours are. Use it for a self-contained task whose intermediate steps you do not ' +
|
||||
'need to see; keep work you must supervise step by step in your own turn.'
|
||||
: '') +
|
||||
'\nDo not delegate something you can answer with a single grep. For independent pieces of work, pass `tasks` to run them in parallel instead of calling task several times sequentially.',
|
||||
inputSchema: z.union([singleSchema, batchSchema]),
|
||||
execute: async (input, { abortSignal }) => {
|
||||
const asBatch = input as { tasks?: TaskSpec[]; description?: string; prompt?: string; kind?: SubagentKind };
|
||||
if (asBatch.tasks && Array.isArray(asBatch.tasks)) {
|
||||
const specs: TaskSpec[] = asBatch.tasks.map((t) => ({
|
||||
description: t.description,
|
||||
prompt: t.prompt,
|
||||
kind: (t.kind ?? asBatch.kind ?? 'explore') as SubagentKind,
|
||||
}));
|
||||
// Validate worker channel before fanning out, so the error is immediate.
|
||||
for (const s of specs) {
|
||||
if (s.kind === 'worker' && !opts.approve) {
|
||||
throw new Error('The worker kind needs an approval channel, which this session has not provided.');
|
||||
}
|
||||
}
|
||||
const ids = specs.map(() => `sub${++counter}`);
|
||||
const innerOpts = {
|
||||
model: opts.model,
|
||||
subagentModel: opts.subagentModel,
|
||||
cwd: opts.cwd,
|
||||
maxSteps: opts.maxSteps,
|
||||
report: opts.report,
|
||||
approve: opts.approve,
|
||||
onUsage: opts.onUsage,
|
||||
};
|
||||
const results = await Promise.all(
|
||||
specs.map((spec, i) =>
|
||||
runOne(spec, ids[i]!, innerOpts, abortSignal).catch((e) => {
|
||||
const msg = e instanceof Error ? e.message : String(e);
|
||||
return `Subagent "${spec.description}" failed: ${msg}`;
|
||||
}),
|
||||
),
|
||||
);
|
||||
return results.map((r, i) => `## ${specs[i]!.description}\n${r}`).join('\n\n');
|
||||
}
|
||||
const spec: TaskSpec = {
|
||||
description: (input as { description: string }).description,
|
||||
prompt: (input as { prompt: string }).prompt,
|
||||
kind: (input as { kind?: SubagentKind }).kind,
|
||||
};
|
||||
return runOne(spec, `sub${++counter}`, opts as Parameters<typeof runOne>[2], abortSignal);
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
import { expect, test } from 'bun:test';
|
||||
import { MockLanguageModelV4, simulateReadableStream } from 'ai/test';
|
||||
import type { LanguageModelV4StreamPart } from '@ai-sdk/provider';
|
||||
import { mkdtempSync, rmSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { Session } from '../src/session';
|
||||
import { createTaskTool, type SubagentEvent } from '../src/subagent';
|
||||
|
||||
const usage = { inputTokens: 10, outputTokens: 10 } as any;
|
||||
const parts = (id: string, toolName: string, input: unknown): LanguageModelV4StreamPart[] => [
|
||||
{ type: 'tool-input-start', id, toolName },
|
||||
{ type: 'tool-input-end', id },
|
||||
{ type: 'tool-call', toolCallId: id, toolName, input: JSON.stringify(input) },
|
||||
{ type: 'finish', finishReason: { unified: 'tool-calls', raw: 'tool_use' }, usage },
|
||||
];
|
||||
const txt = (body: string): LanguageModelV4StreamPart[] => [
|
||||
{ type: 'text-start', id: '0' },
|
||||
{ type: 'text-delta', id: '0', delta: body },
|
||||
{ type: 'text-end', id: '0' },
|
||||
{ type: 'finish', finishReason: { unified: 'stop', raw: 'stop' }, usage },
|
||||
];
|
||||
|
||||
function inTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
|
||||
const orig = process.cwd();
|
||||
const dir = mkdtempSync(join(tmpdir(), 'shiro-par-'));
|
||||
process.chdir(dir);
|
||||
return fn(dir).finally(() => {
|
||||
process.chdir(orig);
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
});
|
||||
}
|
||||
|
||||
test('two tasks dispatched together overlap in time rather than queueing', () =>
|
||||
inTempDir(async () => {
|
||||
await Bun.write('a.ts', 'export const a = 1;\n');
|
||||
await Bun.write('b.ts', 'export const b = 2;\n');
|
||||
const events: SubagentEvent[] = [];
|
||||
let seen = 0;
|
||||
const delay = 50;
|
||||
const model = new MockLanguageModelV4({
|
||||
doStream: async () => {
|
||||
const n = seen++;
|
||||
if (n === 0) {
|
||||
return { stream: simulateReadableStream({ chunks: parts('c1', 'task', { tasks: [{ description: 'find a', prompt: 'Find a' }, { description: 'find b', prompt: 'Find b' }] }), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
}
|
||||
// Each subagent does: one grep (delayed by tool), then text
|
||||
// We simulate delay at model level to observe overlap
|
||||
if (n === 1 || n === 2) {
|
||||
await new Promise((r) => setTimeout(r, delay));
|
||||
return { stream: simulateReadableStream({ chunks: parts(`s${n}`, 'grep', { pattern: n === 1 ? 'a' : 'b', include: '**/*.ts' }), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
}
|
||||
if (n === 3 || n === 4) return { stream: simulateReadableStream({ chunks: txt(n === 3 ? 'found a' : 'found b'), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
return { stream: simulateReadableStream({ chunks: txt('both found'), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
},
|
||||
});
|
||||
|
||||
const session = new Session({
|
||||
model,
|
||||
askApproval: async () => 'deny' as const,
|
||||
extraTools: { task: createTaskTool({ model, report: (e) => events.push(e) }) },
|
||||
autoApprove: ['task'],
|
||||
});
|
||||
|
||||
const t0 = Date.now();
|
||||
for await (const _ of session.send('go')) void _;
|
||||
const dt = Date.now() - t0;
|
||||
|
||||
// Sequential would be ~delay + delay serially; parallel keeps it near one delay.
|
||||
// Allow generous headroom for CI jitter but require overlap.
|
||||
expect(dt).toBeLessThan(delay * 2 + 80);
|
||||
|
||||
// Both findings reach the parent as one tool result with headings
|
||||
const toolMsg = session.messages.find((m) => m.role === 'tool');
|
||||
const body = JSON.stringify(toolMsg);
|
||||
expect(body).toContain('find a');
|
||||
expect(body).toContain('find b');
|
||||
|
||||
// Panel saw two starts before two ends (fan-out)
|
||||
const starts = events.filter((e) => e.type === 'start').map((e) => (e as Extract<SubagentEvent, { type: 'start' }>).description);
|
||||
expect(starts).toContain('find a');
|
||||
expect(starts).toContain('find b');
|
||||
}));
|
||||
|
||||
test('a single task still works through the same path', () =>
|
||||
inTempDir(async () => {
|
||||
await Bun.write('a.ts', 'export const a = 1;\n');
|
||||
let seen = 0;
|
||||
const model = new MockLanguageModelV4({
|
||||
doStream: async (opts) => {
|
||||
const n = seen++;
|
||||
if (n === 0) return { stream: simulateReadableStream({ chunks: parts('c1', 'task', { description: 'find a', prompt: 'Find a' }), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
if (n === 1) return { stream: simulateReadableStream({ chunks: parts('s1', 'grep', { pattern: 'a', include: '**/*.ts' }), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
if (n === 2) return { stream: simulateReadableStream({ chunks: txt('found a at a.ts'), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
return { stream: simulateReadableStream({ chunks: txt('done'), chunkDelayInMs: null, initialDelayInMs: null }) } as any;
|
||||
},
|
||||
});
|
||||
const session = new Session({ model, askApproval: async () => 'deny' as const, extraTools: { task: createTaskTool({ model }) }, autoApprove: ['task'] });
|
||||
for await (const _ of session.send('go')) void _;
|
||||
expect(JSON.stringify(session.messages)).toContain('found a at a.ts');
|
||||
}));
|
||||
Reference in New Issue
Block a user