@nanmicoder/dsh-agent-teams 0.1.15 → 0.1.16-rc.3

package/lib/command.js

@@ -54,11 +54,11 @@ export function invokedAgentTeamsGoal(messages) {
 }
 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.',
+        'The user invoked an AgentTeams slash command. Follow the AgentTeams protocol already in your system instructions. Inspect existing team state with agent_teams_status when needed.',
+        'Respect the current team state. Continue an existing plan or team without recreating it. Only when no current team exists, 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.`);
+        lines.push(`Use profile="${profile}" when creating a new team.`);
         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.');
         }

package/lib/harness-compat.js

@@ -0,0 +1,159 @@
+import { SubagentError } from '@deepseek-ai/dsh-subagent';
+/**
+ * Exact protocol exported by dsh-subagent/internal in Alpha.5 and rc.1.
+ * That subpath does not exist in Alpha.2, so importing it statically prevents
+ * the plugin from loading there. This small adapter uses the same process-
+ * stable symbol and call signature as upstream queueHostSubagentPrompt.
+ * Source: packages/subagent/subagent/src/internal.ts at dsh-v0.1.2-rc.1.
+ */
+const hostPromptQueue = Symbol.for('dsh.subagent.queuePrompt');
+function boundary(runtime) {
+    return runtime;
+}
+function unsupported(detail) {
+    throw new Error(`agent-teams: unsupported Harness subagent contract (${detail}); use an explicitly tested Harness version and a coherent dependency installation`);
+}
+/** Read child-owned history, excluding any descriptor inherited from a parent. */
+export function sessionOwnEvents(session) {
+    const current = session;
+    if (typeof current.ownEvents === 'function')
+        return current.ownEvents.call(session);
+    const legacy = session;
+    if (!Array.isArray(legacy.events))
+        return unsupported('missing ownEvents/legacy session log');
+    return legacy.events.slice(legacy.header.seedLength ?? 0);
+}
+/** Install before the first request, including cold resume, with HMR cleanup. */
+export function installContinuableMemberSetup(ctx, setup) {
+    const runtime = boundary(ctx.subagents);
+    if (typeof runtime.registerContinuableSetup === 'function') {
+        // Upstream owns this registration with this.ctx.effect. Cordis resolves
+        // that ctx to the accessing plugin, so its disposal revokes installations
+        // even while the subagents service and child Agents remain live.
+        runtime.registerContinuableSetup.call(ctx.subagents, setup);
+        return;
+    }
+    if (typeof runtime[hostPromptQueue] !== 'function' || typeof runtime.sendMessage !== 'function') {
+        return unsupported('missing continuable setup and modern host queue');
+    }
+    const installed = new WeakSet();
+    const active = new Set();
+    ctx.effect(() => {
+        const stop = ctx.on('agent/session-start', ({ agent }) => {
+            if (installed.has(agent))
+                return;
+            // Deliberately synchronous: awaiting here loses the first-request race.
+            let teardown;
+            try {
+                teardown = setup(agent.ctx);
+            }
+            catch (error) {
+                // session-start is a notification: Harness logs a thrown listener and
+                // still admits the first prompt. Reject request assembly explicitly so
+                // a malformed saved route cannot silently execute on a default model.
+                const failure = new Error(`agent-teams: member initialization failed: ${String(error)}`, { cause: error });
+                ctx.logger.warn(failure.message);
+                teardown = agent.ctx.on('agent/request', () => { throw failure; });
+            }
+            installed.add(agent);
+            let disposed = false;
+            const dispose = () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                active.delete(dispose);
+                installed.delete(agent);
+                teardown();
+            };
+            active.add(dispose);
+            // Listeners contributed to agent.ctx already follow its lifetime. Also
+            // release our bookkeeping and remove them if this plugin is reloaded.
+            try {
+                agent.ctx.effect(() => dispose, 'agent-teams: child compatibility setup');
+            }
+            catch (error) {
+                dispose();
+                throw error;
+            }
+        });
+        return () => {
+            stop();
+            for (const dispose of [...active])
+                dispose();
+        };
+    }, 'agent-teams: member lifecycle compatibility');
+}
+/** Queue a distinct host-authored turn; never substitute model-message steer. */
+export async function queueMemberPrompt(runtime, parent, childId, content, signal) {
+    const host = boundary(runtime);
+    const source = { kind: 'plugin', plugin: 'dsh-agent-teams' };
+    if (typeof host.followup === 'function') {
+        return host.followup.call(runtime, parent, childId, content, { source, signal });
+    }
+    const queue = host[hostPromptQueue];
+    if (typeof queue !== 'function')
+        return unsupported('missing host FIFO delivery');
+    return queue.call(runtime, parent, childId, content, source, signal);
+}
+/** Guard all resumable delivery paths, preserving the native service receiver. */
+export function guardSubagentDelivery(ctx, isRetired) {
+    const runtime = ctx.subagents;
+    const host = boundary(runtime);
+    const legacy = host.followup;
+    const queue = host[hostPromptQueue];
+    const send = host.sendMessage;
+    if (typeof legacy !== 'function' && (typeof queue !== 'function' || typeof send !== 'function')) {
+        return unsupported('cannot install complete retired-member guard');
+    }
+    ctx.effect(() => {
+        const descriptors = new Map([
+            ['followup', Object.getOwnPropertyDescriptor(host, 'followup')],
+            [hostPromptQueue, Object.getOwnPropertyDescriptor(host, hostPromptQueue)],
+            ['sendMessage', Object.getOwnPropertyDescriptor(host, 'sendMessage')],
+        ]);
+        let active = true;
+        const check = async (sender, targetId) => {
+            if (active && await isRetired(sender, targetId)) {
+                throw new SubagentError(`AgentTeams member "${targetId}" was retired and cannot be resumed`, 'NOT_RESUMABLE');
+            }
+        };
+        const guardedLegacy = async (parent, childId, content, options) => {
+            await check(parent, childId);
+            return legacy.call(runtime, parent, childId, content, options);
+        };
+        const guardedQueue = async (parent, childId, content, source, signal) => {
+            await check(parent, childId);
+            return queue.call(runtime, parent, childId, content, source, signal);
+        };
+        const guardedSend = async (sender, targetId, content, options) => {
+            await check(sender, targetId);
+            return send.call(runtime, sender, targetId, content, options);
+        };
+        if (typeof legacy === 'function')
+            host.followup = guardedLegacy;
+        if (typeof queue === 'function')
+            host[hostPromptQueue] = guardedQueue;
+        if (typeof send === 'function')
+            host.sendMessage = guardedSend;
+        // Cordis wraps method reads in fresh Proxies. Compare the actual own
+        // descriptor to restore only our contribution, including prototype methods.
+        const restore = (key, installed) => {
+            if (Object.getOwnPropertyDescriptor(host, key)?.value !== installed)
+                return;
+            const original = descriptors.get(key);
+            if (original === undefined)
+                Reflect.deleteProperty(host, key);
+            else
+                Object.defineProperty(host, key, original);
+        };
+        return () => {
+            active = false;
+            if (typeof legacy === 'function')
+                restore('followup', guardedLegacy);
+            if (typeof queue === 'function')
+                restore(hostPromptQueue, guardedQueue);
+            if (typeof send === 'function')
+                restore('sendMessage', guardedSend);
+        };
+    }, 'agent-teams: retired member guard');
+}

package/lib/index.js

@@ -2,7 +2,9 @@
  * AgentTeams for DeepSeek Harness.
  *
  * A host-plane plugin that registers the `agent_teams_*` tools and one usage
- * section into the global system prompt. After installation any session can
+ * agent-scoped usage section. Each session keeps a stable tool set and core
+ * instructions. Existing business tools cover the complete team lifecycle.
+ * After installation any session can
  * run multi-agent teamwork through natural language (e.g. "use AgentTeams to research X"):
  * the model creates a team (it becomes the captain), spawns members as
  * durable continuable subagents, breaks the goal into tasks with
@@ -17,7 +19,8 @@
  * @module dsh-agent-teams
  */
 import z from '@deepseek-ai/schemastery';
-import { haltTeamWork, registerAgentTeamsTools, } from "./tools.js";
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { haltTeamWork, stagedPlanApprovedContext, registerAgentTeamsTools, } from "./tools.js";
 import { installAgentTeamsGestureBoundary, registerAgentTeamsCommand } from "./command.js";
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -25,8 +28,9 @@ 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";
-import { authenticatedWebRoutes } from "./web-routes.js";
+import { installTeamCapabilities } from "./capabilities.js";
+import { TEAM_TOOL_NAMES } from "./tool-names.js";
+import { authenticatedWebRoutes, readJsonRequest, RequestBodyError } from "./web-routes.js";
 /** Web-server service key candidates, newest first. */
 const WEB_SERVER_KEYS = ['webServer', 'httpServer'];
 /** Workspace registry service key candidates, newest first. */
@@ -83,18 +87,17 @@ export const Config = z.object({
 });
 /** The model-facing usage policy: when and how to drive AgentTeams. */
 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, 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. 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.
-
+    return `AgentTeams captain protocol:
+1. Inspect current team state when needed, using agent_teams_status. Continue existing work without duplicating its roster/tasks. Create only when no current team exists, with the user's goal as description and approval="required"; automatic approval requires an explicit request to run immediately. Staged plans never spawn or schedule work.
+2. Add each needed role once; members inherit your model route unless another is requested/needed. A requested profile goes to create({profile}); it supplies its roster. Seed profiles also supply tasks; captain-planning profiles require your DAG. Do not duplicate either.
+3. Build the complete smallest useful DAG while staged. Every task needs a subject; dependencies represent prerequisites. Give every required contributor a task or explicit message. Present the plan and end your turn for review; never approve in that planning turn. Approve only after a later explicit user approval or the Web action.
+4. Respect Web approve/return/discard control messages. On return, ask what to change before editing; after the answer, use one atomic agent_teams_edit_plan batch (edit downstream references before removals), summarize and await review again. Never inspect or edit .agent-teams state files or plugin source code to revise plans. Discard does not authorize a replacement.
+5. The scheduler dispatches ready tasks after approval. Delegate; do not duplicate slow work or send messages merely to start a stage. Handle reports/user work, then yield when waiting is all that remains: reports wake you automatically. Use status after a delivery or user request, never busy-poll or wait for unassigned members.
+6. Tasks carry attempt_id capabilities. Use the current attempt_id; stale means ownership changed. Pause members only on explicit request; later guidance via send_message continues that same attempt. Retry, transfer or take over through reassign_task first; it revokes the old attempt and waits for quiescence. Prefer a member. Captain implementation/review takeover requires a user request. Every takeover is one ready task at a time, finished in this turn; never yield with captain-owned work open.
+7. Quality kinds (requirements, implementation, verification, review, repair, integration) require objective + acceptance; implementation/repair also require inScope + verify. Derive paths/commands from the workspace/profile, never assume src/ or pnpm test. Review/requirements complete only with verdict=pass; needs_revision/reject fail with findings. Never approve your own implementation or ask for a deliberate failure.
+8. When full quality mode is requested: requirements → implementation → verification → review → integration. Plan the entire DAG while staged, including implementation before requirements finishes and integration depending on review round 1. Failed review automatically adds repair + next review and rewires pending downstream gates. Do not recreate this loop, omit integration or depend on a failed task. Review acceptance judges the latest implementation. Do not put smoke-test scripts into task instructions.
+9. Halted means the user stopped work (including the captain turn). Resume only on a later explicit user request with a reason, via agent_teams_resume or create_task({resume:true,resumeReason}); creating tasks alone never resumes. Escalated means the review loop hit its limit, not a halt. Deployment requires explicit user confirmation.
+10. Wait for all required tasks to be terminal and members idle/ready, present results, then delete/archive unless the user wants to continue. Never discard unfinished work without authorization.
 Tools: ${toolNames}${profilesText === '' ? '' : `\n\n${profilesText}`}`;
 }
 export function apply(ctx, config) {
@@ -113,28 +116,15 @@ export function apply(ctx, config) {
     // concurrent activation — so capability validation happens at the first
     // member spawn (`spawnMember`), the earliest point the provider list is
     // 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',
-        'agent_teams_reassign_task',
-        'agent_teams_claim_task',
-        '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, formatProfilesForPrompt(config.profiles ?? {})),
-    });
-    // Exported for TDD / docs checks. Not a public runtime API.
     const agentTeamsRuntime = registerAgentTeamsTools(ctx, resolved);
+    installTeamCapabilities(ctx, {
+        stateDir: resolved.stateDir,
+        isPendingMember: agentTeamsRuntime.isPendingMember,
+        order: config.promptSectionOrder,
+        // Keep the bounded profile directory available without extra tool calls.
+        // installTeamCapabilities snapshots this once; no business state rewrites it.
+        captainPrompt: () => usageSectionText(TEAM_TOOL_NAMES.join(', '), formatProfilesForPrompt(config.profiles)),
+    });
     // 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
@@ -199,27 +189,13 @@ export function apply(ctx, config) {
                     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);
+                    payload = await readJsonRequest(req);
                 }
-                catch {
-                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
-                    res.end(JSON.stringify({ error: 'invalid JSON' }));
+                catch (error) {
+                    res.writeHead(error instanceof RequestBodyError ? error.status : 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() : '';
@@ -271,28 +247,10 @@ export function apply(ctx, config) {
                 }
                 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;
+                    payload = await readJsonRequest(req);
                 }
                 catch (error) {
-                    res.writeHead(400, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                    res.writeHead(error instanceof RequestBodyError ? error.status : 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;
                 }
@@ -321,6 +279,20 @@ export function apply(ctx, config) {
                 try {
                     if (action === 'approve') {
                         const approved = await agentTeamsRuntime.approveStagedTeam(captain, teamId);
+                        // The browser receives the HTTP result, so the model needs its own
+                        // control message. steer wakes an idle captain or joins its next
+                        // step; the tool approve path already returns to the model itself.
+                        try {
+                            captain.steer(createUserMessage({
+                                content: [{ type: 'text', text: stagedPlanApprovedContext(team.name) }],
+                                source: { kind: 'plugin', plugin: 'dsh-agent-teams' },
+                            }));
+                        }
+                        catch (error) {
+                            // Approval is already committed. Do not report a failed approval
+                            // and invite a retry that could duplicate the user's action.
+                            ctx.logger.warn(`agent-teams: approval notification failed for ${teamId}: ${String(error)}`);
+                        }
                         res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
                         res.end(JSON.stringify({ ok: true, phase: 'running', ...approved }));
                         return;