@nanmicoder/dsh-agent-teams 0.1.13 → 0.1.14

package/lib/command.js

@@ -1,56 +1,40 @@
-/**
- * The `/agent-teams` slash command and its plain-text gesture boundary.
- *
- * Two deterministic activation paths, mirroring the Harness skill pipeline
- * (`dsh-tool-skill` + the `ui-skill` client source):
- *
- * 1. **Host command** — `ctx.commands.register` publishes the closed-namespace
- *    `/agent-teams` command. The web GUI's slash menu (the Harness
- *    `ui-commands` client) lists it from the host catalog with the input
- *    hint; the argued line is claimed client-side and executed through
- *    `command.execute`. The handler replays that exact line as an ordinary
- *    user follow-up (`agent.followup`) so it remains visible in the chat; the
- *    gesture boundary then adds the deterministic activation message.
- * 2. **Gesture boundary** — a `agent/pre-step` listener recognizes a leading
- *    `/agent-teams` token in genuine user messages and injects the same
- *    activation message. This covers surfaces with no command adjudication
- *    (headless CLI, API, pasted text in plain composers) and also handles the
- *    exact user line replayed by the host command. Mid-sentence mentions stay
- *    ordinary prose; only `source.kind === 'user'` messages are scanned, so
- *    injected or external text cannot forge the gesture.
- *
- * @module dsh-agent-teams/command
- */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-/** The slash command name (without the leading slash). */
+import { parseProfileInvocation, resolveProfileTaskPlanning } from "./profiles.js";
 export const AGENT_TEAMS_COMMAND = 'agent-teams';
-/**
- * A leading, whitespace-bounded `/agent-teams` token — the command grammar
- * shape the harness uses (`parseCommand`): `/` inside words, file paths and
- * mid-sentence mentions never match.
- */
+const PROFILE_COMMAND_PREFIX = `${AGENT_TEAMS_COMMAND}-`;
 const GESTURE = /^\/agent-teams(?=$|[\t\n\r ])/u;
 /**
- * The deterministic activation text. The system-prompt usage section owns
- * the full protocol; this message only switches it on for one concrete goal.
- * @param goal - the user-supplied goal, or `''` for a bare invocation.
+ * Convert a configured profile key into a stable, closed-namespace command
+ * suffix. Only lowercase ASCII letters, digits and dashes are representable;
+ * this deliberately prevents accidental command aliases for ambiguous profile
+ * names such as `foo bar`, `foo_bar`, or non-ASCII keys.
  */
-export function buildActivationDirective(goal) {
-    const goalLine = goal === ''
-        ? 'The goal was not given — ask the user what the team should accomplish.'
-        : `Goal: ${goal}`;
-    return [
-        'The user invoked the `/agent-teams` command. Activate the AgentTeams protocol from your instructions now: you are the captain of a multi-agent team.',
-        goalLine,
-    ].join('\n');
+export function profileCommandName(profileName) {
+    const normalized = profileName.trim().toLowerCase();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(normalized))
+        return undefined;
+    return `${PROFILE_COMMAND_PREFIX}${normalized}`;
 }
-/**
- * The goal of the latest start-anchored `/agent-teams` gesture in genuine
- * user messages, or `undefined` when no message carries one. `''` means a
- * bare `/agent-teams` token with no goal.
- * @param messages - the step's claimed batch (user messages only scanned).
- */
-export function invokedAgentTeamsGoal(messages) {
+/** Resolve a profile command only when it maps uniquely to a live profile. */
+function profileForCommand(commandName, profiles) {
+    const matches = Object.keys(profiles).filter((profileName) => profileCommandName(profileName) === commandName);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/** Parse either the generic command or one generated profile alias. */
+function parseCommandText(text, profiles) {
+    const trimmed = text.trimStart();
+    if (GESTURE.test(trimmed))
+        return parseProfileInvocation(trimmed.slice(AGENT_TEAMS_COMMAND.length + 1).trim());
+    if (!trimmed.startsWith(`/${PROFILE_COMMAND_PREFIX}`))
+        return undefined;
+    const tokenEnd = trimmed.search(/[\t\n\r ]/u);
+    const commandName = trimmed.slice(1, tokenEnd === -1 ? undefined : tokenEnd);
+    const profile = profileForCommand(commandName, profiles);
+    if (profile === undefined)
+        return undefined;
+    return { profile, goal: (tokenEnd === -1 ? '' : trimmed.slice(tokenEnd)).trim() };
+}
+export function invokedAgentTeamsInvocation(messages, getProfiles = () => ({})) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
         if (message === undefined || message.source.kind !== 'user')
@@ -58,69 +42,102 @@ export function invokedAgentTeamsGoal(messages) {
         for (const block of message.content) {
             if (block.type !== 'text')
                 continue;
-            const text = block.text.trimStart();
-            if (!GESTURE.test(text))
-                continue;
-            return text.slice(AGENT_TEAMS_COMMAND.length + 1).trim();
+            const invocation = parseCommandText(block.text, getProfiles());
+            if (invocation !== undefined)
+                return invocation;
         }
     }
     return undefined;
 }
-/**
- * Register the closed-namespace `/agent-teams` host command. The handler
- * preserves the exact submitted slash line as an ordinary user follow-up;
- * the pre-step gesture boundary injects the activation directive and wakes
- * the captain deterministically. The registration rides the calling
- * context's fiber, so a disposed scope (HMR, plugin removal) unregisters the
- * command.
- * @param ctx - host context providing the `commands` registry.
- */
-export function registerAgentTeamsCommand(ctx) {
-    ctx.effect(() => ctx.commands.register({
-        name: AGENT_TEAMS_COMMAND,
-        description: 'run a goal with a multi-agent team (you become the captain)',
-        input: { hint: '<goal — what the team should accomplish>' },
-        handler(invocation) {
-            const goal = invocation.rawInput.trim();
-            if (goal === '') {
-                return {
-                    kind: 'error',
-                    text: `Usage: /${AGENT_TEAMS_COMMAND} <goal — what the team should accomplish>`,
-                };
-            }
-            invocation.agent.followup(createUserMessage({
-                content: [{ type: 'text', text: `/${AGENT_TEAMS_COMMAND}${invocation.rawInput}` }],
-                source: { kind: 'user' },
+export function invokedAgentTeamsGoal(messages) {
+    return invokedAgentTeamsInvocation(messages)?.goal;
+}
+export function buildActivationDirective(goal, profile, taskPlanning = 'seed') {
+    const lines = [
+        'The user invoked an AgentTeams slash command. Activate the AgentTeams protocol from your instructions now: you are the captain of a multi-agent team.',
+        'Call agent_teams_create with approval="required". Build the complete staged roster and DAG, then stop and ask the user to review the Web plan. Do not approve or start it in this same turn.',
+    ];
+    if (profile !== undefined) {
+        lines.push(`Use configured AgentTeams profile "${profile}" when calling agent_teams_create.`);
+        if (taskPlanning === 'captain') {
+            lines.push('This profile supplies the roster and guardrails. After create, do not recreate members.', 'Derive the smallest useful task graph from the goal while the team is staged; do not ask the user whether to split, merge, serialize, or parallelize.', 'Independent supplemental work must become separate ready tasks so idle members can run in parallel. Add dependencies only for genuine prerequisites and later synthesis.');
+        }
+        else {
+            lines.push('Do not recreate the same members or seed tasks manually.');
+        }
+    }
+    lines.push(goal === '' ? 'The goal was not given — ask the user what the team should accomplish.' : `Goal: ${goal}`);
+    return lines.join('\n');
+}
+export function registerAgentTeamsCommand(ctx, getProfiles = () => ({})) {
+    ctx.effect(() => {
+        const dispose = [];
+        dispose.push(ctx.commands.register({
+            name: AGENT_TEAMS_COMMAND,
+            description: 'run a goal with a multi-agent team (you become the captain)',
+            input: { hint: '[--profile <name>] <goal>' },
+            handler(invocation) {
+                let parsed;
+                try {
+                    parsed = parseProfileInvocation(invocation.rawInput.trim());
+                }
+                catch (error) {
+                    return { kind: 'error', text: String(error) };
+                }
+                if (parsed.profile !== undefined && !Object.keys(getProfiles()).some(key => key.trim() === parsed.profile))
+                    return { kind: 'error', text: `unknown AgentTeams profile "${parsed.profile}"` };
+                if (parsed.profile === undefined && parsed.goal === '')
+                    return { kind: 'error', text: `Usage: /${AGENT_TEAMS_COMMAND} [--profile <name>] <goal>` };
+                invocation.agent.followup(createUserMessage({ content: [{ type: 'text', text: `/${AGENT_TEAMS_COMMAND}${invocation.rawInput}` }], source: { kind: 'user' } }));
+                return { kind: 'success', text: `AgentTeams activated${parsed.profile === undefined ? '' : ` with profile ${parsed.profile}`} — the captain will assemble the team.` };
+            },
+        }));
+        for (const profileName of Object.keys(getProfiles())) {
+            const commandName = profileCommandName(profileName);
+            if (commandName === undefined)
+                continue;
+            dispose.push(ctx.commands.register({
+                name: commandName,
+                description: `run a goal with the AgentTeams ${profileName} profile`,
+                input: { hint: '<goal>' },
+                handler(invocation) {
+                    const profile = profileForCommand(commandName, getProfiles());
+                    if (profile === undefined)
+                        return { kind: 'error', text: `AgentTeams profile command "/${commandName}" is unavailable` };
+                    invocation.agent.followup(createUserMessage({ content: [{ type: 'text', text: `/${commandName}${invocation.rawInput}` }], source: { kind: 'user' } }));
+                    return { kind: 'success', text: `AgentTeams activated with profile ${profile} — the captain will assemble the team.` };
+                },
             }));
-            return {
-                kind: 'success',
-                text: `AgentTeams activated — the captain will assemble a team for: ${goal}`,
-            };
-        },
-    }), 'agent-teams: slash command');
+        }
+        return () => {
+            for (const unregister of dispose.reverse())
+                unregister();
+        };
+    }, 'agent-teams: slash commands');
 }
-/**
- * Install the `agent/pre-step` gesture boundary: a claimed user message
- * starting with `/agent-teams` gains the deterministic activation message
- * appended after every other injection, closest to the model's answer.
- * @param ctx - host context providing the `agent/pre-step` waterfall.
- */
-export function installAgentTeamsGestureBoundary(ctx) {
+export function installAgentTeamsGestureBoundary(ctx, getProfiles = () => ({})) {
     ctx.on('agent/pre-step', async ({ messages, signal }, next) => {
         const decision = await next();
         if (decision.kind === 'reject')
             return decision;
-        const goal = invokedAgentTeamsGoal(messages);
-        if (goal === undefined)
+        let invocation;
+        try {
+            invocation = invokedAgentTeamsInvocation(messages, getProfiles);
+        }
+        catch (error) {
+            return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text: `AgentTeams profile parsing failed: ${String(error)}` }], source: { kind: 'agent-teams-command' } })] };
+        }
+        if (invocation === undefined)
             return decision;
         signal.throwIfAborted();
-        const activation = createUserMessage({
-            content: [{ type: 'text', text: buildActivationDirective(goal) }],
-            source: {
-                kind: 'agent-teams-command',
-                ...goal === '' ? {} : { goal },
-            },
-        });
-        return { kind: 'enter', messages: [...decision.messages, activation] };
+        const profiles = getProfiles();
+        const matched = invocation.profile === undefined
+            ? undefined
+            : Object.entries(profiles).find(([key]) => key.trim() === invocation.profile);
+        const known = invocation.profile === undefined || matched !== undefined;
+        const text = !known
+            ? `AgentTeams profile "${invocation.profile}" does not exist. Available profiles: ${Object.keys(profiles).join(', ') || '(none)'}. Do not create a team.`
+            : buildActivationDirective(invocation.goal, invocation.profile, resolveProfileTaskPlanning(matched?.[1]));
+        return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'agent-teams-command', ...invocation.goal === '' ? {} : { goal: invocation.goal }, ...invocation.profile === undefined ? {} : { profile: invocation.profile } } })] };
     });
 }

package/lib/index.js

@@ -17,47 +17,95 @@
  * @module dsh-agent-teams
  */
 import z from '@deepseek-ai/schemastery';
-import { registerAgentTeamsTools } from "./tools.js";
+import { haltTeamWork, registerAgentTeamsTools, } from "./tools.js";
 import { installAgentTeamsGestureBoundary, registerAgentTeamsCommand } from "./command.js";
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { collectArchivedTeamsActivity, collectTeamsActivity } from "./snapshot.js";
+import { findTeamByCaptain } from "./state.js";
+import { formatProfilesForPrompt } from "./profiles.js";
+import { qualityPlanningPrompt } from "./quality-gates.js";
 /** Web-server service key candidates, newest first. */
 const WEB_SERVER_KEYS = ['webServer', 'httpServer'];
 /** Workspace registry service key candidates, newest first. */
 const WORKSPACE_KEYS = ['workspaceRegistry', 'workspace'];
 export const name = 'agent-teams';
 export const inject = ['tools', 'llm', 'subagents', 'systemPrompt', 'agents'];
+// `z.object()` has an implicit `{}` default in Schemastery.  Fallback routes
+// are optional, so model absence explicitly; otherwise a missing route is
+// validated as an empty object and fails on the required provider/model keys.
+const fallbackRouteConfig = z.union([
+    z.object({ provider: z.string().required(), model: z.string().required() }),
+    z.const(undefined),
+]);
 export const Config = z.object({
     stateDir: z.string().default('.agent-teams'),
     memberProvider: z.string().default('spawn'),
     memberModel: z.string(),
+    executionPrompt: z.string(),
+    fallback: fallbackRouteConfig,
+    profiles: z.dict(z.object({
+        description: z.string(),
+        protocol: z.string(),
+        executionPrompt: z.string(),
+        fallback: fallbackRouteConfig,
+        members: z.array(z.object({
+            name: z.string().required(),
+            role: z.string(),
+            provider: z.string(),
+            model: z.string(),
+            reasoning_effort: z.string(),
+            executionPrompt: z.string(),
+            fallback: fallbackRouteConfig,
+        })).min(1).required(),
+        taskPlanning: z.union([z.const('captain'), z.const('seed')]),
+        reviewPolicy: z.object({
+            requirementsMinRounds: z.natural().min(1),
+            requirementsMaxRounds: z.natural().min(1),
+            codeMaxRounds: z.natural().min(1),
+            maxRepairAttempts: z.natural().min(1),
+            requiredReviewers: z.array(z.string()),
+        }),
+        tasks: z.array(z.object({
+            id: z.string().required(),
+            subject: z.string().required(),
+            description: z.string(),
+            assignee: z.string(),
+            dependencies: z.array(z.string()),
+        })),
+    })).default({}),
     memberMaxDepth: z.natural().default(1),
     maxMembers: z.natural().min(1).default(8),
     promptSectionOrder: z.natural().default(117),
     slashCommand: z.boolean().default(true),
 });
 /** The model-facing usage policy: when and how to drive AgentTeams. */
-function usageSectionText(toolNames) {
+export function usageSectionText(toolNames, profilesText = '') {
     return `When the user asks to run something with AgentTeams (e.g. "use AgentTeams to do X"), or an activation message from the /agent-teams slash command arrives, you are the captain of a multi-agent team. Follow this protocol:
-1. Call agent_teams_create with a team name and the goal as description. You become the captain and may lead one team at a time.
-2. Call agent_teams_add_member once per role the goal needs (researcher, engineer, reviewer, ...). Members are durable subagents: they wait for your messages, then work a full turn. By default a member on your current provider/model snapshots your current reasoning effort; a member routed to a different provider or model automatically uses that target model's default effort. Never ask the user to choose these per member; only pass provider/model when the user explicitly requests a different route for that role, and reasoning_effort only when the user explicitly requests a particular effort ("default" explicitly selects the target model's default).
-3. Break the goal into tasks with agent_teams_create_task and wire dependencies. Assign role-specific work when useful; unassigned ready work belongs to the shared pool. The scheduler automatically claims one ready task for each truly idle member and wakes it, including across later rounds.
-4. Lead by delegation: monitor with agent_teams_status, send guidance with agent_teams_send_message, and let idle teammates execute ready work. Do not duplicate a teammate's work merely because its turn is slow. If the user requires every member to contribute or report, create one task per required contribution (or message each member directly); never wait for an unassigned member to produce work it was never given.
-5. If the user explicitly asks to pause a running member, its open attempt remains parked after interruption; after answering the user, send that same member guidance with agent_teams_send_message so it continues the same attempt. Do not interrupt members for an ordinary user question that did not request a pause. If work must change owner, restart from scratch, or be taken over, call agent_teams_reassign_task first. Reassign to another idle member, retry with the same member, or use assignee=captain before doing it yourself. Reassignment revokes the old attempt and waits for that member to quiesce, preventing late results from overwriting the new attempt.
+1. Call agent_teams_create with a team name, the goal as description, and approval="required". This creates a staged plan and must not spawn members or schedule work. Use approval="automatic" only when the user explicitly asks to skip review and run immediately.
+2. Call agent_teams_add_member once per role the goal needs (researcher, engineer, reviewer, ...). In staging these are editable roster entries, not running subagents. By default a member snapshots your current provider/model/reasoning route; use a different route only when the goal or user requires it.
+3. Analyze the goal and create the smallest useful task DAG while staged. Every agent_teams_create_task call must include a non-empty subject, including verification and review tasks. Independent work should be parallel; dependencies are only genuine prerequisites. Finish the complete roster and DAG, tell the user the Web plan is ready, then end this turn. Never call agent_teams_approve during the planning turn. The user may click Approve & Run, explicitly approve in a later user turn, return to chat to request changes, or discard the plan. The review UI injects an authoritative control message for return/discard actions: follow it exactly and never infer that a missing or paused team should be recreated. When the user returns to chat, first ask one concise clarification question without editing or recreating; after their answer, call agent_teams_edit_plan once with an ordered atomic batch, update downstream dependencies/assignees before removals, summarize the revision, and wait for review again. Never inspect or edit .agent-teams state files or plugin source code to revise a plan. Only explicit approval may call agent_teams_approve.
+4. After approval, the final member configuration is spawned atomically and the scheduler starts ready work. Lead by delegation: monitor with agent_teams_status, send guidance with agent_teams_send_message, and let idle teammates execute ready work. Do not duplicate a teammate's work merely because its turn is slow. If the user requires every member to contribute or report, create one task per required contribution (or message each member directly); never wait for an unassigned member to produce work it was never given.
+5. If the user explicitly asks to pause a running member, its open attempt remains parked after interruption; after answering the user, send that same member guidance with agent_teams_send_message so it continues the same attempt. Do not interrupt members for an ordinary user question that did not request a pause. If work must change owner, restart from scratch, or be taken over, call agent_teams_reassign_task first. Prefer another idle member or a retry with the same member. Use assignee=captain only for one ready task that you will personally drive to a terminal status in this same turn; never start a second captain takeover while one is unfinished, and never end your turn with captain-owned work open. Reassignment revokes the old attempt and waits for that member to quiesce, preventing late results from overwriting the new attempt.
 6. Tasks carry attempt_id capabilities. Members must use the current attempt_id for updates; stale-attempt errors mean ownership changed. Check status after progress notifications until every required task is terminal and every member is idle/ready; do not busy-poll or require reports from members with no assigned work.
-7. Present the team's results to the user, then agent_teams_delete the team unless the user wants to keep working with it.
+7. If the user names a configured profile / template / fixed roster, pass that name as profile= to agent_teams_create. After a successful profile create, do not recreate the same members. Seed profiles provide their template tasks; captain-planning profiles provide only the roster and guardrails, so you must design their DAG while staged. Add repair or retry tasks when review/test fails, but never make a new task depend on a failed task. Do not send_message to start the next stage; the scheduler assigns ready work after approval. Watch every required task until it is terminal before deleting the team. Never perform a real deployment without explicit user confirmation.
+8. Quality kinds (requirements, implementation, verification, review, repair, integration) need a contract: non-empty objective and acceptance; implementation/repair also need inScope and verify. Review/requirements can complete only with verdict=pass; needs_revision/reject must fail with findings. The system then opens repair + next review that depend on the successful source, never the failed review. Do not approve your own implementation. create_task no longer silently resumes a halted team — call agent_teams_resume with a reason, or create_task({resume:true, resumeReason}).
+9. ${qualityPlanningPrompt()}
+10. Present the team's results to the user, then agent_teams_delete the team unless the user wants to keep working with it. Stopping a team aborts the Captain's current turn as well as member work; only a later explicit user turn may resume it.
 
-Tools: ${toolNames}`;
+Tools: ${toolNames}${profilesText === '' ? '' : `\n\n${profilesText}`}`;
 }
 export function apply(ctx, config) {
     const resolved = {
         stateDir: config.stateDir ?? '.agent-teams',
         memberProvider: config.memberProvider ?? 'spawn',
         memberModel: config.memberModel,
+        executionPrompt: config.executionPrompt,
+        fallback: config.fallback,
         memberMaxDepth: config.memberMaxDepth ?? 1,
         maxMembers: config.maxMembers ?? 8,
+        profiles: config.profiles ?? {},
     };
     // Provider registration is a sibling plugin's effect (`subagent-spawn` /
     // `subagent-fork` rows), which can land after this mount under the Loader's
@@ -66,6 +114,8 @@ export function apply(ctx, config) {
     // settled, rather than here.
     const toolNames = [
         'agent_teams_create',
+        'agent_teams_approve',
+        'agent_teams_edit_plan',
         'agent_teams_add_member',
         'agent_teams_remove_member',
         'agent_teams_create_task',
@@ -74,14 +124,16 @@ export function apply(ctx, config) {
         'agent_teams_update_task',
         'agent_teams_send_message',
         'agent_teams_status',
+        'agent_teams_resume',
         'agent_teams_delete',
     ].join(', ');
     ctx.systemPrompt.section({
         name: 'agent-teams:usage',
         order: config.promptSectionOrder ?? 117,
-        text: usageSectionText(toolNames),
+        text: () => usageSectionText(toolNames, formatProfilesForPrompt(config.profiles ?? {})),
     });
-    registerAgentTeamsTools(ctx, resolved);
+    // Exported for TDD / docs checks. Not a public runtime API.
+    const agentTeamsRuntime = registerAgentTeamsTools(ctx, resolved);
     // Deterministic activation surfaces: the closed-namespace `/agent-teams`
     // host command (surfaces in the Web GUI slash menu via the Harness
     // ui-commands client) and the plain-text gesture boundary for surfaces
@@ -94,9 +146,9 @@ export function apply(ctx, config) {
     // never pends on it and simply never gains the slash command.
     if (config.slashCommand ?? true) {
         ctx.inject(['commands'], (commandCtx) => {
-            registerAgentTeamsCommand(commandCtx);
+            registerAgentTeamsCommand(commandCtx, () => config.profiles ?? {});
         });
-        installAgentTeamsGestureBoundary(ctx);
+        installAgentTeamsGestureBoundary(ctx, () => config.profiles ?? {});
     }
     // The activity panel data/artwork routes need the Web server and the
     // workspace registry, which headless profiles do not mount; under
@@ -136,6 +188,226 @@ export function apply(ctx, config) {
                 res.end(body);
             },
         }), 'agent-teams: activity route');
+        ctx.effect(() => webServer.register({
+            kind: 'exact',
+            path: '/plugins/dsh-agent-teams/halt',
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    res.writeHead(405, { allow: 'POST', 'cache-control': 'no-store' });
+                    res.end();
+                    return;
+                }
+                let raw = '';
+                try {
+                    raw = await new Promise((resolve, reject) => {
+                        const chunks = [];
+                        req.on('data', (chunk) => { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); });
+                        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+                        req.on('error', reject);
+                    });
+                }
+                catch {
+                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'invalid request body' }));
+                    return;
+                }
+                let payload;
+                try {
+                    payload = raw.trim() === '' ? {} : JSON.parse(raw);
+                }
+                catch {
+                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'invalid JSON' }));
+                    return;
+                }
+                const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId.trim() : '';
+                const teamId = typeof payload.teamId === 'string' ? payload.teamId.trim() : '';
+                if (sessionId === '' || teamId === '') {
+                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'sessionId and teamId are required' }));
+                    return;
+                }
+                const captain = ctx.agents.get(sessionId);
+                if (captain === undefined) {
+                    res.writeHead(409, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'captain session is not attached' }));
+                    return;
+                }
+                const workspace = captain.session.header.cwd ?? process.cwd();
+                const stateRoot = join(workspace, resolved.stateDir);
+                const team = await findTeamByCaptain(stateRoot, captain.id);
+                if (team === undefined || team.id !== teamId) {
+                    res.writeHead(404, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'team not found for this captain' }));
+                    return;
+                }
+                try {
+                    const result = await haltTeamWork({
+                        ctx,
+                        stateRoot,
+                        teamId,
+                        captain,
+                    });
+                    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify(result));
+                }
+                catch (error) {
+                    ctx.logger.warn(`agent-teams: halt failed for ${teamId}: ${String(error)}`);
+                    res.writeHead(500, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'failed to stop the team' }));
+                }
+            },
+        }), 'agent-teams: halt route');
+        ctx.effect(() => webServer.register({
+            kind: 'exact',
+            path: '/plugins/dsh-agent-teams/plan',
+            handler: async (req, res) => {
+                if (req.method !== 'POST') {
+                    res.writeHead(405, { allow: 'POST', 'cache-control': 'no-store' });
+                    res.end();
+                    return;
+                }
+                let payload;
+                try {
+                    const chunks = [];
+                    const raw = await new Promise((resolve, reject) => {
+                        let size = 0;
+                        req.on('data', (chunk) => {
+                            const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                            size += part.length;
+                            if (size > 1_000_000) {
+                                reject(new Error('request body is too large'));
+                                return;
+                            }
+                            chunks.push(part);
+                        });
+                        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+                        req.on('error', reject);
+                    });
+                    const parsed = raw.trim() === '' ? {} : JSON.parse(raw);
+                    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+                        throw new Error('body must be an object');
+                    payload = parsed;
+                }
+                catch (error) {
+                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: error instanceof Error ? error.message : 'invalid request body' }));
+                    return;
+                }
+                const sessionId = typeof payload['sessionId'] === 'string' ? payload['sessionId'].trim() : '';
+                const teamId = typeof payload['teamId'] === 'string' ? payload['teamId'].trim() : '';
+                const action = typeof payload['action'] === 'string' ? payload['action'] : '';
+                if (sessionId === '' || teamId === '' || action === '') {
+                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'sessionId, teamId, and action are required' }));
+                    return;
+                }
+                const captain = ctx.agents.get(sessionId);
+                if (captain === undefined) {
+                    res.writeHead(409, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'captain session is not attached' }));
+                    return;
+                }
+                const workspace = captain.session.header.cwd ?? process.cwd();
+                const stateRoot = join(workspace, resolved.stateDir);
+                const team = await findTeamByCaptain(stateRoot, captain.id);
+                if (team === undefined || team.id !== teamId) {
+                    res.writeHead(404, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'team not found for this captain' }));
+                    return;
+                }
+                try {
+                    if (action === 'approve') {
+                        const approved = await agentTeamsRuntime.approveStagedTeam(captain, teamId);
+                        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                        res.end(JSON.stringify({ ok: true, phase: 'running', ...approved }));
+                        return;
+                    }
+                    if (action === 'continue') {
+                        const continued = await agentTeamsRuntime.continueStagedPlanning(captain, teamId);
+                        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                        res.end(JSON.stringify({ ok: true, phase: 'staged', review: 'awaiting_feedback', ...continued }));
+                        return;
+                    }
+                    if (action === 'discard') {
+                        const discarded = await agentTeamsRuntime.discardStagedTeam(captain, teamId);
+                        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                        res.end(JSON.stringify({ ok: true, phase: 'archived', ...discarded }));
+                        return;
+                    }
+                    const dependencies = Array.isArray(payload['dependencies'])
+                        ? payload['dependencies'].filter((item) => typeof item === 'string')
+                        : [];
+                    let mutation;
+                    if (action === 'update_member') {
+                        if (typeof payload['memberName'] !== 'string'
+                            || typeof payload['provider'] !== 'string'
+                            || typeof payload['model'] !== 'string')
+                            throw new Error('memberName, provider, and model are required');
+                        mutation = {
+                            action,
+                            memberName: payload['memberName'],
+                            provider: payload['provider'],
+                            model: payload['model'],
+                            ...typeof payload['role'] === 'string' || payload['role'] === null ? { role: payload['role'] } : {},
+                            ...typeof payload['reasoningEffort'] === 'string' || payload['reasoningEffort'] === null
+                                ? { reasoningEffort: payload['reasoningEffort'] }
+                                : {},
+                            ...typeof payload['executionPrompt'] === 'string' || payload['executionPrompt'] === null
+                                ? { executionPrompt: payload['executionPrompt'] }
+                                : {},
+                        };
+                    }
+                    else if (action === 'update_task') {
+                        if (typeof payload['taskId'] !== 'string' || typeof payload['subject'] !== 'string') {
+                            throw new Error('taskId and subject are required');
+                        }
+                        mutation = {
+                            action,
+                            taskId: payload['taskId'],
+                            subject: payload['subject'],
+                            dependencies,
+                            ...typeof payload['description'] === 'string' || payload['description'] === null
+                                ? { description: payload['description'] }
+                                : {},
+                            ...typeof payload['assignee'] === 'string' || payload['assignee'] === null
+                                ? { assignee: payload['assignee'] }
+                                : {},
+                        };
+                    }
+                    else if (action === 'add_task') {
+                        if (typeof payload['subject'] !== 'string')
+                            throw new Error('subject is required');
+                        mutation = {
+                            action,
+                            subject: payload['subject'],
+                            dependencies,
+                            ...typeof payload['description'] === 'string' || payload['description'] === null
+                                ? { description: payload['description'] }
+                                : {},
+                            ...typeof payload['assignee'] === 'string' || payload['assignee'] === null
+                                ? { assignee: payload['assignee'] }
+                                : {},
+                        };
+                    }
+                    else if (action === 'remove_task') {
+                        if (typeof payload['taskId'] !== 'string')
+                            throw new Error('taskId is required');
+                        mutation = { action, taskId: payload['taskId'] };
+                    }
+                    else {
+                        throw new Error(`unknown plan action "${action}"`);
+                    }
+                    const updated = await agentTeamsRuntime.updateStagedPlan(captain, teamId, mutation);
+                    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ ok: true, phase: updated.phase, members: updated.members.length, tasks: updated.tasks.length }));
+                }
+                catch (error) {
+                    res.writeHead(409, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.end(JSON.stringify({ error: error instanceof Error ? error.message : 'plan operation failed' }));
+                }
+            },
+        }), 'agent-teams: plan route');
         // Whale mascot artwork: serve the packaged V2 role/action images to the
         // activity panel. An explicit allowlist guards the route (no path
         // traversal); the images ship with the bundle (files: assets/).