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

package/lib/tools.js

@@ -12,11 +12,12 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { join } from 'node:path';
 import { appendTeamEvent, captainSessionOf } from "./events.js";
-import { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, removeTeamDir, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, } from "./state.js";
-import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, validateMemberLlmSelections, } from "./members.js";
+import { acknowledgeMailbox, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, removeTeamDir, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, normalizeBlankOptionalTaskFields, taskKindOf, } from "./state.js";
+import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, interruptMember, memberActivity, resolveMemberLlmSelection, spawnMember, steerCaptainReport, validateMemberLlmSelections, } from "./members.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
 import { installTeamScheduler } from "./scheduler.js";
 import { resolveTeamProfile } from "./profiles.js";
+export { steerCaptainReport } from "./members.js";
 /** The caller agent, or a loud failure for non-agent callers. */
 function requireCaptain(exec) {
     if (!exec.agent) {
@@ -275,18 +276,14 @@ export async function haltTeamWork(input) {
         alreadyHalted: halted.alreadyHalted,
     };
 }
-export function steerCaptainReport(captain, from, content) {
-    try {
-        captain.steer(createUserMessage({
-            content: [{ type: 'text', text: `AgentTeams message from member ${from}:\n\n${content}` }],
-            source: { kind: 'plugin', plugin: 'dsh-agent-teams' },
-        }));
-        return true;
-    }
-    catch {
-        // The plugin mailbox was persisted before this best-effort live delivery.
-        return false;
-    }
+/** Web approval has no tool result in the captain's conversation. */
+export function stagedPlanApprovedContext(teamName) {
+    return [
+        `The user approved the staged AgentTeams plan "${teamName}" from the pre-run review UI.`,
+        'Approval has committed; the scheduler owns dispatch of the approved team. Do not approve again, recreate the roster, or send messages merely to start assigned tasks.',
+        'Acknowledge the approval and handle any reports or user work already pending. Yield only when waiting for members is the remaining action. Their reports will wake you automatically; do not busy-poll status or keep a turn running just to wait.',
+        'On a report, inspect the result and coordinate the next necessary action. If work has since been halted, respect that state and resume only on an explicit user request.',
+    ].join('\n');
 }
 /** Context queued after the human rejects a staged plan. */
 export function stagedPlanDiscardContext(teamName) {
@@ -313,8 +310,8 @@ export function stagedPlanFeedbackContext(teamName) {
  */
 export function registerAgentTeamsTools(ctx, config) {
     installRetiredMemberGuard(ctx, config.stateDir);
-    const memberSelections = installMemberSelectionRuntime(ctx, config.stateDir);
     const scheduler = installTeamScheduler(ctx, { stateDir: config.stateDir, executionPrompt: config.executionPrompt });
+    const memberSelections = installMemberSelectionRuntime(ctx, config.stateDir, (workspace, teamId, memberName) => (scheduler.kickMember(workspace, teamId, memberName)));
     const updateStagedPlanBatch = async (captain, teamId, mutations, signal) => {
         if (mutations.length === 0)
             throw new Error('at least one staged plan operation is required');
@@ -536,6 +533,7 @@ export function registerAgentTeamsTools(ctx, config) {
         return { teamId: discarded.teamId };
     };
     const runtime = {
+        isPendingMember: memberSelections.isPendingMember,
         updateStagedPlan,
         updateStagedPlanBatch,
         approveStagedTeam,
@@ -586,15 +584,20 @@ export function registerAgentTeamsTools(ctx, config) {
                 throw new Error('team name must not be empty');
             const teamId = sanitizeKey(teamName);
             const staged = args.approval === 'required';
-            const profileName = args.profile?.trim();
-            if (args.profile !== undefined && profileName === '') {
-                throw new Error('AgentTeams profile name must not be empty');
-            }
+            // Some models materialize optional parameters as "" instead of omitting
+            // them (issue #99). The profile is optional, so treat a blank value
+            // exactly like an omitted one instead of failing every create call.
+            const profileName = args.profile !== undefined && args.profile.trim() !== ''
+                ? args.profile.trim()
+                : undefined;
             const created = await withTeamLock(captainLockKey(stateRoot, captain.id), async () => {
                 const current = await findTeamByParticipant(stateRoot, captain.id);
                 if (current !== undefined) {
                     const relationship = current.captainSessionId === captain.id ? 'lead' : 'belong to';
-                    throw new Error(`you already ${relationship} team "${current.name}" — end or leave it before creating another`);
+                    const guidance = current.captainSessionId === captain.id
+                        ? 'Use agent_teams_status and continue the existing team. Do not delete and recreate it merely to continue work. End it only when the user explicitly wants a separate new team.'
+                        : 'Continue your assigned member work and report to your captain; do not create a separate team.';
+                    throw new Error(`you already ${relationship} team "${current.name}" (id ${current.id}). ${guidance}`);
                 }
                 return withTeamLock(teamLockKey(stateRoot, teamId), async () => {
                     const existing = await readTeam(stateRoot, teamId);
@@ -927,6 +930,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     provider: selection.provider,
                     model: selection.model,
                     reasoningEffort: selection.reasoningEffort,
+                    ...selection.fallback === undefined ? {} : { fallback: selection.fallback },
                     executionPrompt: trimmedOptional(args.executionPrompt),
                     joinedAt: Date.now(),
                     status: 'idle',
@@ -1081,28 +1085,33 @@ export function registerAgentTeamsTools(ctx, config) {
             const workspace = workspaceOf(captain);
             const stateRoot = stateRootOf(workspace, config);
             const team = await requireCaptainTeam(workspace, config, captain);
+            // Some models materialize optional parameters as "" instead of omitting
+            // them (issue #105). Normalize blank optional fields to omitted before
+            // validation so a blank value can neither be rejected spuriously nor be
+            // persisted into team.json, where it would brick the team on reload.
+            const input = normalizeBlankOptionalTaskFields(args);
             const created = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
                 const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
                 const gate = validateCreateTask(fresh, {
-                    subject: args.subject,
-                    description: args.description,
-                    dependencies: args.dependencies,
-                    assignee: args.assignee,
-                    kind: args.kind,
-                    round: args.round,
-                    objective: args.objective,
-                    inScope: args.inScope,
-                    outOfScope: args.outOfScope,
-                    acceptance: args.acceptance,
-                    verify: args.verify,
-                    deliverables: args.deliverables,
-                    nonGoals: args.nonGoals,
-                    reviewedTaskId: args.reviewedTaskId,
-                    sourceTaskId: args.sourceTaskId,
-                    sourceFindingIds: args.sourceFindingIds,
-                    coverageOf: args.coverageOf,
-                    resume: args.resume,
-                    resumeReason: args.resumeReason,
+                    subject: input.subject,
+                    description: input.description,
+                    dependencies: input.dependencies,
+                    assignee: input.assignee,
+                    kind: input.kind,
+                    round: input.round,
+                    objective: input.objective,
+                    inScope: input.inScope,
+                    outOfScope: input.outOfScope,
+                    acceptance: input.acceptance,
+                    verify: input.verify,
+                    deliverables: input.deliverables,
+                    nonGoals: input.nonGoals,
+                    reviewedTaskId: input.reviewedTaskId,
+                    sourceTaskId: input.sourceTaskId,
+                    sourceFindingIds: input.sourceFindingIds,
+                    coverageOf: input.coverageOf,
+                    resume: input.resume,
+                    resumeReason: input.resumeReason,
                 });
                 if (!gate.ok)
                     throw new Error(gate.error ?? 'create_task rejected by quality gates');
@@ -1128,11 +1137,11 @@ export function registerAgentTeamsTools(ctx, config) {
                     requireMember(fresh, args.assignee);
                 const kind = gate.kind ?? 'work';
                 const objective = kind === 'review' || kind === 'requirements'
-                    ? sanitizeReviewObjective(args.objective)
-                    : args.objective;
+                    ? sanitizeReviewObjective(input.objective)
+                    : input.objective;
                 const acceptance = kind === 'review' || kind === 'requirements'
-                    ? sanitizeReviewAcceptance(args.acceptance)
-                    : args.acceptance;
+                    ? sanitizeReviewAcceptance(input.acceptance)
+                    : input.acceptance;
                 const task = {
                     id: `t${fresh.taskSeq + 1}`,
                     subject: args.subject,
@@ -1146,16 +1155,16 @@ export function registerAgentTeamsTools(ctx, config) {
                     kind,
                     ...args.round === undefined ? {} : { round: args.round },
                     ...objective === undefined ? {} : { objective },
-                    ...args.inScope === undefined ? {} : { inScope: args.inScope },
-                    ...args.outOfScope === undefined ? {} : { outOfScope: args.outOfScope },
+                    ...input.inScope === undefined ? {} : { inScope: input.inScope },
+                    ...input.outOfScope === undefined ? {} : { outOfScope: input.outOfScope },
                     ...acceptance === undefined ? {} : { acceptance },
-                    ...args.verify === undefined ? {} : { verify: args.verify },
-                    ...args.deliverables === undefined ? {} : { deliverables: args.deliverables },
-                    ...args.nonGoals === undefined ? {} : { nonGoals: args.nonGoals },
-                    ...args.reviewedTaskId === undefined ? {} : { reviewedTaskId: args.reviewedTaskId },
-                    ...args.sourceTaskId === undefined ? {} : { sourceTaskId: args.sourceTaskId },
-                    ...args.sourceFindingIds === undefined ? {} : { sourceFindingIds: args.sourceFindingIds },
-                    ...args.coverageOf === undefined ? {} : { coverageOf: args.coverageOf },
+                    ...input.verify === undefined ? {} : { verify: input.verify },
+                    ...input.deliverables === undefined ? {} : { deliverables: input.deliverables },
+                    ...input.nonGoals === undefined ? {} : { nonGoals: input.nonGoals },
+                    ...input.reviewedTaskId === undefined ? {} : { reviewedTaskId: input.reviewedTaskId },
+                    ...input.sourceTaskId === undefined ? {} : { sourceTaskId: input.sourceTaskId },
+                    ...input.sourceFindingIds === undefined ? {} : { sourceFindingIds: input.sourceFindingIds },
+                    ...input.coverageOf === undefined ? {} : { coverageOf: input.coverageOf },
                 };
                 fresh.taskSeq += 1;
                 fresh.tasks.push(task);
@@ -1304,10 +1313,10 @@ export function registerAgentTeamsTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_claim_task',
-        description: 'Claim one ready task for a member (or yourself). A member cannot own a second unfinished task. The returned attempt_id is required for that member\'s updates and becomes stale after retry/reassignment.',
+        description: 'Members claim their own ready task or read their existing attempt_id. Captains must use reassign_task to assign and wake a member; claim_task does not dispatch work. A member cannot own a second unfinished task. The returned attempt_id is required for updates and becomes stale after retry/reassignment.',
         parameters: {
             task_id: { type: 'string', required: true, description: 'The task id to claim.' },
-            assignee: { type: 'string', description: 'Member to claim for (captain only; defaults to the task\'s assignee).' },
+            assignee: { type: 'string', description: 'Deprecated: claim_task only supports a member claiming its own task. Captains must use reassign_task.' },
         },
         output: {
             schema: {
@@ -1339,9 +1348,11 @@ export function registerAgentTeamsTools(ctx, config) {
                 }
                 let assignee = task.assignee;
                 if (identity.kind === 'captain') {
-                    if (args.assignee !== undefined) {
-                        requireMember(fresh, args.assignee);
-                        assignee = args.assignee;
+                    // A captain may read the capability of its already-started takeover,
+                    // but must never create a member claim without dispatching it (#125).
+                    if (args.assignee !== undefined || task.assignee !== CAPTAIN_KEY
+                        || (task.status !== 'claimed' && task.status !== 'in_progress')) {
+                        throw new Error('claim_task is for members claiming their own task; captains must use agent_teams_reassign_task to assign and wake a member');
                     }
                 }
                 else {
@@ -1518,6 +1529,10 @@ export function registerAgentTeamsTools(ctx, config) {
                         ...task.output !== undefined ? { output: task.output } : {},
                     };
                 }
+                // Blank optional list entries (e.g. changedPaths:[""]) must not be
+                // persisted: hasValidQualityTaskFields rejects them on reload and
+                // would brick the whole team state (issue #105 class).
+                const input = normalizeBlankOptionalTaskFields(args);
                 const findings = parseFindings(args.findings);
                 const acceptanceResults = parseAcceptanceResults(args.acceptanceResults);
                 const commandsRun = parseCommandResults(args.commandsRun);
@@ -1526,7 +1541,7 @@ export function registerAgentTeamsTools(ctx, config) {
                     output: args.output,
                     verdict: args.verdict,
                     findings,
-                    changedPaths: args.changedPaths,
+                    changedPaths: input.changedPaths,
                     acceptanceResults,
                     commandsRun,
                 });
@@ -1544,8 +1559,8 @@ export function registerAgentTeamsTools(ctx, config) {
                     task.verdict = args.verdict;
                 if (findings !== undefined)
                     task.findings = findings;
-                if (args.changedPaths !== undefined)
-                    task.changedPaths = args.changedPaths;
+                if (input.changedPaths !== undefined)
+                    task.changedPaths = input.changedPaths;
                 if (acceptanceResults !== undefined)
                     task.acceptanceResults = acceptanceResults;
                 if (commandsRun !== undefined)
@@ -1698,7 +1713,7 @@ export function registerAgentTeamsTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_status',
-        description: 'Team snapshot: members with live activity and tasks with status/assignee/dependencies/output. Captains also see every team mailbox; members see only their own inbox. Poll this to watch progress.',
+        description: 'Team snapshot: members with live activity and tasks with status/assignee/dependencies/output. Captains also see every team mailbox; members see only their own inbox. Use after mailbox progress deliveries or for an explicit status request. After dispatch, end your turn while members work; do not repeatedly poll.',
         parameters: {},
         output: {
             schema: { type: 'object', additionalProperties: true, properties: {} },
@@ -1871,7 +1886,7 @@ export function registerAgentTeamsTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_delete',
-        description: 'End your team: interrupts all members (best effort) and deletes the team\'s state directory (team file, tasks, mailboxes). Use when the team\'s work is done or abandoned.',
+        description: 'End and archive your team: interrupts members and moves the current tasks and mailboxes out of active state for later inspection. Use when the work is done or explicitly abandoned. A same-name archive replaces its previous generation.',
         parameters: {},
         output: {
             schema: {
@@ -1884,7 +1899,7 @@ export function registerAgentTeamsTools(ctx, config) {
             },
             render: (args, value) => [{
                     type: 'text',
-                    text: `Team "${value.team_name}" deleted.`,
+                    text: `Team "${value.team_name}" ended and archived.`,
                 }],
         },
         async execute(_args, exec) {
@@ -2065,7 +2080,9 @@ function parseFindings(value) {
             severity: raw['severity'],
             problem: raw['problem'],
             requiredFix: raw['requiredFix'],
-            ...typeof raw['file'] === 'string' ? { file: raw['file'] } : {},
+            // A blank optional file must be omitted, not persisted: durable-state
+            // validation requires non-empty optional strings (issue #105 class).
+            ...typeof raw['file'] === 'string' && raw['file'].trim() !== '' ? { file: raw['file'] } : {},
             ...typeof raw['line'] === 'number' ? { line: raw['line'] } : {},
             ...typeof raw['resolved'] === 'boolean' ? { resolved: raw['resolved'] } : {},
         };

package/lib/types/capabilities.d.ts

@@ -0,0 +1,14 @@
+/** Stable, agent-scoped presentation. Business authority stays in the tools. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+export declare const TEAM_ACTIVATION_PROMPT = "AgentTeams (Agent Teams) provides multi-agent team collaboration. Apply these rules when the user requests it (including /agent-teams) or when continuing an existing team. Mentioning, quoting, discussing, or declining AgentTeams alone is not a request to start work.";
+export declare const TEAM_MEMBER_PROMPT = "You are an AgentTeams member. Follow your assigned member persona and task contract. Use agent_teams_claim_task, agent_teams_update_task, agent_teams_send_message and agent_teams_status for your own work. Include the current attempt_id in updates; report completion or failure to the captain. Do not create, approve, edit or resume a team. If your durable membership is unavailable, report that to the parent instead of creating a replacement.";
+interface CapabilityConfig {
+    stateDir: string;
+    isPendingMember: (agent: Agent) => boolean;
+    captainPrompt: () => string;
+    order?: number;
+}
+/** Call once, after all business definitions have registered. Never per member. */
+export declare function installTeamCapabilities(ctx: Context, config: CapabilityConfig): void;
+export {};

package/lib/types/client/locales.d.ts

@@ -81,7 +81,6 @@ export declare const zh: {
     'dependency.hint.pinned': string;
     'task.runningAria': string;
     'task.model': string;
-    'member.model': string;
     'task.detail.completed': string;
     'task.detail.noPrerequisite': string;
     'task.detail.ready': string;
@@ -275,7 +274,6 @@ export declare const en: {
     'dependency.hint.pinned': string;
     'task.runningAria': string;
     'task.model': string;
-    'member.model': string;
     'task.detail.completed': string;
     'task.detail.noPrerequisite': string;
     'task.detail.ready': string;

package/lib/types/harness-compat.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The audited Harness 0.1.2 subagent boundary. Keep version-specific shapes
+ * here: API presence alone is not a promise of support for future versions.
+ *
+ * Alpha.2 owns followup/registerContinuableSetup; Alpha.5 and rc.1 own a
+ * host-only FIFO queue and synchronous agent/session-start. Their public
+ * sendMessage instead steers a running Agent and must never carry team jobs.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+type Setup = (childCtx: Context) => () => void;
+/** Read child-owned history, excluding any descriptor inherited from a parent. */
+export declare function sessionOwnEvents(session: Session): readonly SessionEvent[];
+/** Install before the first request, including cold resume, with HMR cleanup. */
+export declare function installContinuableMemberSetup(ctx: Context, setup: Setup): void;
+/** Queue a distinct host-authored turn; never substitute model-message steer. */
+export declare function queueMemberPrompt(runtime: Context['subagents'], parent: Agent, childId: SessionId, content: ContentBlock[], signal: AbortSignal): Promise<MessageId>;
+/** Guard all resumable delivery paths, preserving the native service receiver. */
+export declare function guardSubagentDelivery(ctx: Context, isRetired: (sender: Agent, targetId: SessionId) => Promise<boolean>): void;
+export {};

package/lib/types/index.d.ts

@@ -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

package/lib/types/members.d.ts

@@ -4,7 +4,7 @@
  *
  * Members are durable continuable subagents of the captain, so a member keeps
  * its conversation across turns and across harness restarts: the captain
- * wakes it with {@link ctx.subagents.followup}, it works through its turn
+ * queues its next turn through {@link deliverToMember}, it works through its turn
  * (updating team state through the `agent_teams_*` tools), and becomes idle
  * again. Its final assistant message is not readable programmatically, so the
  * member persists its report into the captain's mailbox and the task records,
@@ -13,7 +13,8 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { type Agent } from '@deepseek-ai/dsh-agent';
-import { type TeamMember, type TeamState } from './types.ts';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { type TeamMember, type TeamState, type TeamTask } from './types.ts';
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
 export declare const PERSONA_PROTOCOL_MAX_CHARS = 400;
 /** Runtime knobs for member spawning, resolved from plugin config. */
@@ -62,6 +63,8 @@ export interface MemberLlmSelectionRequest {
 }
 /** Process-local bridge between spawn admission and synchronous child setup. */
 export interface MemberSelectionRuntime {
+    /** Trusted fresh-child admission, before the durable member id is written. */
+    isPendingMember(agent: Agent): boolean;
     /** Make one selection visible while Harness materializes the fresh child. */
     withPending<T>(parentSessionId: string, label: string, selection: MemberLlmSelection, operation: () => Promise<T>): Promise<T>;
 }
@@ -88,6 +91,18 @@ export declare function selectFallbackRoute(current: {
         model: string;
     };
 };
+/** Deliver a durable member report to the live captain at its next model step. */
+export declare function steerCaptainReport(captain: Pick<Agent, 'steer'>, from: string, content: string): boolean;
+interface FailedMemberAttempt {
+    readonly captainSessionId: string;
+    readonly memberId: string;
+    readonly task?: Pick<TeamTask, 'id' | 'attempt' | 'attemptId'>;
+}
+/** Record a final turn failure, never an intermediate request retry. */
+export declare function failMemberOpenAttempt(ctx: Context, stateRoot: string, teamId: string, memberName: string, failure: {
+    readonly code: string;
+    readonly message: string;
+}, fallbackSession: Session, observed: FailedMemberAttempt): Promise<boolean>;
 /**
  * Resolve one member's complete model selection. Ordinary members snapshot the
  * captain's current request route and reasoning effort. When provider or model
@@ -105,7 +120,7 @@ export declare function resolveMemberLlmSelection(ctx: Context, captain: Agent,
  * record. Legacy members without a complete saved route retain Harness's
  * descriptor provider/model behavior.
  */
-export declare function installMemberSelectionRuntime(ctx: Context, stateDir: string): MemberSelectionRuntime;
+export declare function installMemberSelectionRuntime(ctx: Context, stateDir: string, onFailureSettled?: (workspace: string, teamId: string, memberName: string) => Promise<void>): MemberSelectionRuntime;
 /**
  * The member's system prompt (persona), shadowing the deployment persona for
  * that child. Self-contained: it replaces the whole persona section.
@@ -168,12 +183,12 @@ export declare function interruptMember(ctx: Context, captain: Agent, childId: s
  *
  * Upstream `interrupt()` deliberately preserves continuable sessions and the
  * upstream seam exposes no targeted forget/retire method. The durable
- * AgentTeams index therefore rejects `followup()` before it can cold-resume a
+ * AgentTeams index therefore rejects every inbox delivery before it can cold-resume a
  * retired member. Catalog rows deliberately remain discoverable: Harness rc.8
  * uses the direct-child catalog to authorize historical transcript reads and
  * `openSubagent()`, so filtering those rows would make an archived member's
  * persisted conversation inaccessible. Exact ids keep unrelated subagents
- * untouched while the followup boundary still prevents further model turns.
+ * untouched while the delivery boundary still prevents further model turns.
  */
 export declare function installRetiredMemberGuard(ctx: Context, stateDir: string): void;
 /**
@@ -189,3 +204,4 @@ export declare function installRetiredMemberGuard(ctx: Context, stateDir: string
  * @returns child id → live activity.
  */
 export declare function memberActivity(ctx: Context, memberIds: readonly string[]): Map<string, 'running' | 'idle' | 'ready'>;
+export {};

package/lib/types/quality-gates.d.ts

@@ -128,6 +128,14 @@ export declare function resumeTeamState(team: TeamState, reason: string): Resume
 export declare function isReviewFinding(value: unknown): value is ReviewFinding;
 export declare function isAcceptanceResult(value: unknown): value is AcceptanceResult;
 export declare function isCommandResult(value: unknown): value is CommandResult;
+/**
+ * Normalize blank optional task fields to omitted ("blank means absent").
+ * Blank string scalars are deleted; string lists have blank entries filtered
+ * out, and a list that only contained blanks is omitted entirely. Non-blank
+ * values and every other field are passed through untouched, so durable-state
+ * validation stays strict.
+ */
+export declare function normalizeBlankOptionalTaskFields<T extends object>(task: T): T;
 export declare function hasValidQualityTaskFields(value: Record<string, unknown>): boolean;
 export declare function isTaskKind(value: unknown): value is TaskKind;
 export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;

package/lib/types/scheduler.d.ts

@@ -8,7 +8,7 @@
  * the selected durable member. A resident member that becomes idle while it
  * still owns an open attempt is parked: only an explicit captain reassignment
  * may rotate that capability. Automatic retry is reserved for cold recovery,
- * when the durable owner is no longer resident in the live Agent registry.
+ * when this process has not observed the durable owner settle its open attempt.
  * @module dsh-agent-teams/scheduler
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -42,6 +42,12 @@ export interface DispatchTicket {
     readonly attempt: number;
     readonly attemptId: string;
     readonly previousAssignee?: string;
+    /** True when this ticket rotates an unobserved durable open attempt. */
+    readonly recoveredOwned: boolean;
+    /** Original task generation, used to restore a failed automatic recovery. */
+    readonly previousStatus?: 'claimed' | 'in_progress';
+    readonly previousAttempt?: number;
+    readonly previousAttemptId?: string;
     readonly subject: string;
     readonly description?: string;
     readonly teamDescription?: string;

package/lib/types/state.d.ts

@@ -13,7 +13,7 @@
  * @module dsh-agent-teams/state
  */
 import { type TaskStatus, type TeamMessage, type TeamState, type TeamTask } from './types.ts';
-export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
+export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
 /** Mailbox key of the captain. */
 export declare const CAPTAIN_KEY = "captain";
 /**
@@ -23,6 +23,11 @@ export declare const CAPTAIN_KEY = "captain";
  * @returns the mutation's result.
  */
 export declare function withTeamLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Keys with an in-process lock queue (held or waiting), snapshot for
+ * diagnostics and leak checks. The queue promises themselves stay private.
+ */
+export declare function teamLockQueueKeys(): readonly string[];
 /**
  * Fold a free-form name into a safe path/key segment.
  *
@@ -101,7 +106,8 @@ export declare function readTeamSync(stateRoot: string, teamId: string): TeamSta
  * @param state - the record to persist.
  */
 export declare function writeTeam(stateRoot: string, state: TeamState): Promise<void>;
-/** Read the durable set of member session ids retired by remove/delete. */
+/** Synchronous role hydration before the host's first prompt assembly. */
+export declare function readRetiredMemberIdsSync(stateRoot: string): Set<string>;
 export declare function readRetiredMemberIds(stateRoot: string): Promise<Set<string>>;
 /** Atomically add session ids to the durable retired-member deny-list. */
 export declare function recordRetiredMemberIds(stateRoot: string, memberIds: readonly string[]): Promise<void>;

package/lib/types/tool-names.d.ts

@@ -0,0 +1,4 @@
+/** Stable business API names; exposure changes never rename these operations. */
+export declare const TEAM_TOOL_NAMES: readonly ["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"];
+export declare const MEMBER_TOOL_NAMES: readonly string[];
+export declare const CAPTAIN_TOOL_NAMES: ("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")[];

package/lib/types/tools.d.ts

@@ -11,6 +11,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { type TeamState, type TeamTask } from './types.ts';
+export { steerCaptainReport } from './members.ts';
 /** Resolved plugin config consumed by the tools. */
 export interface ToolsConfig {
     /** State directory name under the captain's workspace. */
@@ -61,6 +62,7 @@ export type StagedPlanMutation = {
 };
 /** Runtime bridge shared by model-facing tools and the Web staging surface. */
 export interface AgentTeamsRuntime {
+    isPendingMember(agent: Agent): boolean;
     updateStagedPlan(captain: Agent, teamId: string, mutation: StagedPlanMutation, signal?: AbortSignal): Promise<TeamState>;
     updateStagedPlanBatch(captain: Agent, teamId: string, mutations: readonly StagedPlanMutation[], signal?: AbortSignal): Promise<TeamState>;
     approveStagedTeam(captain: Agent, teamId: string, signal?: AbortSignal): Promise<{
@@ -87,7 +89,8 @@ export declare function haltTeamWork(input: {
     cancelledTasks: number;
     alreadyHalted: boolean;
 }>;
-export declare function steerCaptainReport(captain: Pick<Agent, 'steer'>, from: string, content: string): boolean;
+/** Web approval has no tool result in the captain's conversation. */
+export declare function stagedPlanApprovedContext(teamName: string): string;
 /** Context queued after the human rejects a staged plan. */
 export declare function stagedPlanDiscardContext(teamName: string): string;
 /** Model-facing continuation that turns the review UI back into a conversation. */

package/lib/types/web-routes.d.ts

@@ -9,5 +9,11 @@ export interface WebRouteHost {
     }): () => void;
 }
 export type BrowserRequestGate = Pick<HostConnectionService, 'requestRejection'>;
+export declare class RequestBodyError extends Error {
+    readonly status: 400 | 413;
+    constructor(message: string, status: 400 | 413);
+}
+/** Bound memory while draining oversized requests so the route can return 413. */
+export declare function readJsonRequest(req: IncomingMessage, maxBytes?: number): Promise<Record<string, unknown>>;
 /** Raw WebServer routes do not inherit Connection's authentication fence. */
 export declare function authenticatedWebRoutes(server: WebRouteHost, connection: () => BrowserRequestGate | undefined): WebRouteHost;

package/lib/web-routes.js

@@ -1,3 +1,63 @@
+export class RequestBodyError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Bound memory while draining oversized requests so the route can return 413. */
+export async function readJsonRequest(req, maxBytes = 1_000_000) {
+    const raw = await new Promise((resolve, reject) => {
+        let size = 0;
+        let settled = false;
+        const chunks = [];
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            req.off('data', onData);
+            req.off('end', onEnd);
+            req.off('aborted', onAborted);
+            req.off('error', onError);
+            if (error) {
+                chunks.length = 0;
+                // IncomingMessage may still receive data; discard it without buffering.
+                req.once('error', () => { });
+                req.resume();
+                reject(error);
+            }
+            else {
+                resolve(Buffer.concat(chunks).toString('utf8'));
+            }
+        };
+        const onData = (chunk) => {
+            const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += part.length;
+            if (size > maxBytes)
+                finish(new RequestBodyError('request body is too large', 413));
+            else
+                chunks.push(part);
+        };
+        const onEnd = () => finish();
+        const onAborted = () => finish(new RequestBodyError('request body was aborted', 400));
+        const onError = () => finish(new RequestBodyError('invalid request body', 400));
+        req.on('data', onData);
+        req.once('end', onEnd);
+        req.once('aborted', onAborted);
+        req.once('error', onError);
+    });
+    let value;
+    try {
+        value = raw.trim() === '' ? {} : JSON.parse(raw);
+    }
+    catch {
+        throw new RequestBodyError('invalid JSON', 400);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new RequestBodyError('body must be an object', 400);
+    }
+    return value;
+}
 /** Raw WebServer routes do not inherit Connection's authentication fence. */
 export function authenticatedWebRoutes(server, connection) {
     return {