@nanmicoder/dsh-agent-teams 0.1.5 → 0.1.6

package/lib/scheduler.js

@@ -0,0 +1,212 @@
+/**
+ * Event-driven shared task scheduler.
+ *
+ * Claude Code teammates keep polling the shared task list after a turn. DSH
+ * continuable agents instead expose explicit idle/running edges, so this
+ * scheduler closes the same loop without keeping a polling turn alive: every
+ * idle edge and every task-graph mutation attempts one atomic claim and wakes
+ * the selected durable member.
+ * @module dsh-agent-teams/scheduler
+ */
+import { join } from 'node:path';
+import { deliverToMember } from "./members.js";
+import { acknowledgeMailbox, beginTaskAttempt, claimMailboxDelivery, findTeamByParticipant, readTeam, readUnreadMailbox, releaseMailboxDelivery, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
+function stateRootOf(workspace, config) {
+    return join(workspace, config.stateDir);
+}
+function teamLockKey(stateRoot, teamId) {
+    return `team:${stateRoot}:${teamId}`;
+}
+function liveCaptain(ctx, captainSessionId, supplied) {
+    if (supplied !== undefined && supplied.id === captainSessionId)
+        return supplied;
+    return ctx.agents.get(captainSessionId);
+}
+function isMemberAvailable(ctx, member) {
+    const live = ctx.agents.get(member.id);
+    return live === undefined || live.status === 'idle';
+}
+function ownedOpenTask(tasks, memberName) {
+    return tasks.find(task => task.assignee === memberName
+        && (task.status === 'claimed' || task.status === 'in_progress'));
+}
+function nextReadyTask(tasks, memberName) {
+    const ready = tasks.filter(task => task.status === 'pending'
+        && task.reassigning !== true
+        && unsatisfiedDependencies([...tasks], task.dependencies).length === 0);
+    return ready.find(task => task.assignee === memberName)
+        ?? ready.find(task => task.assignee === undefined);
+}
+function assignmentPrompt(ticket, stateDir, teamId) {
+    const description = ticket.description === undefined ? '' : `\n\n${ticket.description}`;
+    return `AgentTeams automatic task assignment from the shared task list.
+
+Task: ${ticket.taskId} — ${ticket.subject}${description}
+Attempt: ${ticket.attempt}
+Attempt id: ${ticket.attemptId}
+
+Call agent_teams_claim_task for ${ticket.taskId}; it will return this same attempt_id. Include attempt_id=${ticket.attemptId} in every agent_teams_update_task call. If it is rejected as stale, stop work because the task was reassigned. Work only this task in this turn, report the result to the captain, then become idle so the scheduler can select your next ready task.
+
+State policy: ${stateDir}/${teamId}/ is read-only diagnostics; mutate team state only through agent_teams_* tools.`;
+}
+function fallbackMailboxPrompt(messages) {
+    return [
+        'AgentTeams delivered messages that were persisted while live delivery was unavailable:',
+        ...messages.map(message => `\nFrom ${message.from}:\n${message.content}`),
+        '\nHandle these messages in this turn. Task assignments still require agent_teams_claim_task and the current attempt_id.',
+    ].join('\n');
+}
+/** Install one scheduler and its member activity observer. */
+export function installTeamScheduler(ctx, config) {
+    const memberQueues = new Map();
+    const serializeMember = async (key, operation) => {
+        const previous = memberQueues.get(key) ?? Promise.resolve();
+        let release;
+        const gate = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => gate);
+        memberQueues.set(key, tail);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (memberQueues.get(key) === tail)
+                memberQueues.delete(key);
+        }
+    };
+    const runtime = {
+        async kickTeam(workspace, teamId, suppliedCaptain) {
+            const stateRoot = stateRootOf(workspace, config);
+            const team = await readTeam(stateRoot, teamId);
+            if (team === undefined)
+                return;
+            const captain = liveCaptain(ctx, team.captainSessionId, suppliedCaptain);
+            if (captain === undefined)
+                return;
+            for (const member of team.members) {
+                if (member.status === 'removed')
+                    continue;
+                await runtime.kickMember(workspace, teamId, member.name, captain);
+            }
+        },
+        async kickMember(workspace, teamId, memberName, suppliedCaptain) {
+            const stateRoot = stateRootOf(workspace, config);
+            const queueKey = `${stateRoot}\u0000${teamId}\u0000${memberName}`;
+            await serializeMember(queueKey, async () => {
+                let team = await readTeam(stateRoot, teamId);
+                if (team === undefined)
+                    return;
+                const captain = liveCaptain(ctx, team.captainSessionId, suppliedCaptain);
+                if (captain === undefined)
+                    return;
+                let member = team.members.find(candidate => candidate.name === memberName && candidate.status !== 'removed');
+                if (member === undefined || member.id === '' || !isMemberAvailable(ctx, member))
+                    return;
+                // A mailbox-only fallback is real pending work. Deliver it before a
+                // fresh task and acknowledge only after Harness accepts the follow-up.
+                const unread = await readUnreadMailbox(stateRoot, team.id, member.name);
+                if (unread.length > 0) {
+                    await withTeamLock(teamLockKey(stateRoot, team.id), () => (claimMailboxDelivery(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                    const accepted = await deliverToMember(ctx, captain, member.id, fallbackMailboxPrompt(unread), new AbortController().signal);
+                    if (accepted) {
+                        await withTeamLock(teamLockKey(stateRoot, team.id), () => (acknowledgeMailbox(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                    }
+                    else {
+                        await withTeamLock(teamLockKey(stateRoot, team.id), () => (releaseMailboxDelivery(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                    }
+                    return;
+                }
+                const ticket = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                    const fresh = await readTeam(stateRoot, team.id);
+                    if (fresh === undefined)
+                        return undefined;
+                    const currentMember = fresh.members.find(candidate => candidate.name === memberName && candidate.status !== 'removed');
+                    if (currentMember === undefined || currentMember.id === '' || !isMemberAvailable(ctx, currentMember))
+                        return undefined;
+                    // An idle/ready member that still owns an open task lost the turn
+                    // that was executing it (model stopped early, interrupt settlement,
+                    // or process restart). Retry that task with a fresh capability
+                    // instead of permanently treating the durable claim as "busy".
+                    const task = ownedOpenTask(fresh.tasks, currentMember.name)
+                        ?? nextReadyTask(fresh.tasks, currentMember.name);
+                    if (task === undefined) {
+                        if (currentMember.status !== 'idle') {
+                            currentMember.status = 'idle';
+                            await writeTeam(stateRoot, fresh);
+                        }
+                        return undefined;
+                    }
+                    const previousAssignee = task.assignee;
+                    const attemptId = beginTaskAttempt(task, currentMember.name);
+                    currentMember.status = 'working';
+                    await writeTeam(stateRoot, fresh);
+                    return {
+                        taskId: task.id,
+                        memberName: currentMember.name,
+                        memberId: currentMember.id,
+                        attempt: task.attempt ?? 1,
+                        attemptId,
+                        previousAssignee,
+                        subject: task.subject,
+                        description: task.description,
+                    };
+                });
+                if (ticket === undefined)
+                    return;
+                const accepted = await deliverToMember(ctx, captain, ticket.memberId, assignmentPrompt(ticket, config.stateDir, team.id), new AbortController().signal);
+                if (accepted)
+                    return;
+                // Roll back only our exact failed dispatch. A concurrent captain
+                // handoff has already changed the capability and wins.
+                await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                    const fresh = await readTeam(stateRoot, team.id);
+                    if (fresh === undefined)
+                        return;
+                    const task = fresh.tasks.find(candidate => candidate.id === ticket.taskId);
+                    if (task?.attemptId !== ticket.attemptId)
+                        return;
+                    task.status = 'pending';
+                    task.assignee = ticket.previousAssignee;
+                    task.attemptId = undefined;
+                    task.handoffId = undefined;
+                    task.reassigning = false;
+                    task.updatedAt = Date.now();
+                    const currentMember = fresh.members.find(candidate => candidate.name === ticket.memberName);
+                    if (currentMember !== undefined && currentMember.status !== 'removed')
+                        currentMember.status = 'idle';
+                    await writeTeam(stateRoot, fresh);
+                });
+            });
+        },
+    };
+    const syncMemberStatus = async (agent, status) => {
+        const workspace = agent.session.header.cwd ?? process.cwd();
+        const stateRoot = stateRootOf(workspace, config);
+        const located = await findTeamByParticipant(stateRoot, agent.id);
+        if (located === undefined || located.captainSessionId === agent.id)
+            return;
+        const member = located.members.find(candidate => candidate.id === agent.id && candidate.status !== 'removed');
+        if (member === undefined)
+            return;
+        await withTeamLock(teamLockKey(stateRoot, located.id), async () => {
+            const fresh = await readTeam(stateRoot, located.id);
+            const current = fresh?.members.find(candidate => candidate.id === agent.id && candidate.status !== 'removed');
+            if (fresh === undefined || current === undefined)
+                return;
+            const next = status === 'running' ? 'working' : 'idle';
+            if (current.status === next)
+                return;
+            current.status = next;
+            await writeTeam(stateRoot, fresh);
+        });
+        if (status === 'idle')
+            await runtime.kickMember(workspace, located.id, member.name);
+    };
+    ctx.on('agent/status', ({ agent, status }) => {
+        void syncMemberStatus(agent, status).catch((error) => {
+            ctx.logger.warn(`agent-teams: member status scheduling failed for ${agent.id}: ${String(error)}`);
+        });
+    });
+    return runtime;
+}

package/lib/snapshot.js

@@ -9,7 +9,7 @@
  */
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { CAPTAIN_KEY, listArchivedTeamIds, readArchivedTeam, readMailbox, readTeam, taskDepthsById, taskVisualState, } from "./state.js";
+import { CAPTAIN_KEY, listArchivedTeamIds, readArchivedTeam, readUnreadMailbox, readTeam, taskDepthsById, taskVisualState, } from "./state.js";
 /** The current task of a member: its first unfinished owned task. */
 function currentTaskOf(memberName, tasks) {
     for (const task of tasks) {
@@ -26,41 +26,54 @@ function currentTaskOf(memberName, tasks) {
  * @param state - the durable team record.
  * @returns the panel snapshot.
  */
-export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state) {
+export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state, options = {}) {
     const tasks = state.tasks;
     const depths = taskDepthsById(tasks);
-    const byName = new Map(state.members.filter((m) => m.status !== 'removed').map((m) => [m.name, m]));
+    const roster = options.includeRemoved === true
+        ? state.members
+        : state.members.filter((member) => member.status !== 'removed');
     const activity = new Map();
-    try {
-        const children = await ctx.subagents.listChildren(state.captainSessionId);
-        for (const entry of children) {
-            if (entry.kind === 'child')
-                activity.set(entry.id, entry.activity);
+    if (options.historic !== true) {
+        try {
+            const children = await ctx.subagents.listChildren(state.captainSessionId);
+            for (const entry of children) {
+                if (entry.kind === 'child') {
+                    const live = ctx.agents.get(entry.id);
+                    activity.set(entry.id, live === undefined ? 'ready' : live.status);
+                }
+            }
+        }
+        catch (error) {
+            ctx.logger.warn(`agent-teams: activity listing failed for ${state.name}: ${String(error)}`);
         }
-    }
-    catch (error) {
-        ctx.logger.warn(`agent-teams: activity listing failed for ${state.name}: ${String(error)}`);
     }
     const unreadByMember = new Map();
-    for (const member of state.members.filter((candidate) => candidate.status !== 'removed')) {
+    for (const member of roster) {
         try {
-            unreadByMember.set(member.name, (await readMailbox(stateRoot, state.id, member.name)).length);
+            unreadByMember.set(member.name, (await readUnreadMailbox(stateRoot, state.id, member.name)).length);
         }
         catch (error) {
             ctx.logger.warn(`agent-teams: mailbox read failed for ${member.name}: ${String(error)}`);
             unreadByMember.set(member.name, 0);
         }
     }
-    const members = state.members
-        .filter((member) => member.status !== 'removed')
-        .map((member) => {
+    const members = roster.map((member) => {
         const owned = tasks.filter((task) => task.assignee === member.name);
         const done = owned.filter((task) => task.status === 'completed').length;
         return {
             id: member.id,
             name: member.name,
             role: member.role ?? '',
-            activity: member.id !== '' ? (activity.get(member.id) === 'running' ? 'working' : activity.get(member.id) === 'inactive' ? 'idle' : 'unknown') : 'unknown',
+            status: member.status,
+            activity: options.historic === true
+                ? 'idle'
+                : member.id !== ''
+                    ? (activity.get(member.id) === 'running'
+                        ? 'working'
+                        : activity.get(member.id) === 'idle' || activity.get(member.id) === 'ready'
+                            ? 'idle'
+                            : 'unknown')
+                    : 'unknown',
             progress: owned.length === 0 ? 0 : Math.round((done / owned.length) * 100),
             done,
             total: owned.length,
@@ -68,7 +81,7 @@ export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state) {
             unread: unreadByMember.get(member.name) ?? 0,
         };
     });
-    const captainInbox = await readMailbox(stateRoot, state.id, CAPTAIN_KEY);
+    const captainInbox = await readUnreadMailbox(stateRoot, state.id, CAPTAIN_KEY);
     return {
         workspace,
         teamId: state.id,
@@ -144,7 +157,7 @@ export async function collectArchivedTeamsActivity(ctx, roots) {
                 const state = await readArchivedTeam(root.stateRoot, teamId);
                 if (state === undefined)
                     continue;
-                snapshots.push(await assembleTeamSnapshot(ctx, join(root.stateRoot, 'archive'), root.workspace, state));
+                snapshots.push(await assembleTeamSnapshot(ctx, join(root.stateRoot, 'archive'), root.workspace, state, { includeRemoved: true, historic: true }));
             }
             catch {
                 ctx.logger.warn(`agent-teams: skipped unreadable archived team "${teamId}" in workspace "${root.workspace}"`);

package/lib/state.js

@@ -18,6 +18,10 @@ import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promise
 import { join } from 'node:path';
 /** Mailbox key of the captain. */
 export const CAPTAIN_KEY = 'captain';
+/** A crashed live-delivery attempt becomes retryable after this interval. */
+const MAILBOX_DELIVERY_LEASE_MS = 60_000;
+/** Durable deny-list for AgentTeams members that must never be resumed. */
+const RETIRED_MEMBERS_FILE = 'retired-members.json';
 /** In-process per-team mutation queues (promise chains). */
 const locks = new Map();
 /**
@@ -112,6 +116,36 @@ export function transitionError(current, next) {
     }
     return undefined;
 }
+/** Activate the task's current generation for one owner and return its capability id. */
+export function activateTaskAttempt(task, assignee) {
+    const attemptId = randomUUID();
+    task.status = 'claimed';
+    task.assignee = assignee;
+    task.attemptId = attemptId;
+    task.handoffId = undefined;
+    task.reassigning = false;
+    task.output = undefined;
+    task.updatedAt = Date.now();
+    return attemptId;
+}
+/** Start a fresh task generation for one owner. */
+export function beginTaskAttempt(task, assignee) {
+    task.attempt = (task.attempt ?? 0) + 1;
+    return activateTaskAttempt(task, assignee);
+}
+/**
+ * Revoke the current worker immediately. Clearing its capability makes old
+ * updates stale; a separate handoff generation serializes async quiescence.
+ */
+export function invalidateTaskAttempt(task, nextAssignee, reassigning = false) {
+    task.attemptId = undefined;
+    task.handoffId = randomUUID();
+    task.status = 'pending';
+    task.assignee = nextAssignee;
+    task.reassigning = reassigning;
+    task.output = undefined;
+    task.updatedAt = Date.now();
+}
 /**
  * Create the team directory structure and the initial team record.
  * @param stateRoot - resolved absolute state root directory.
@@ -176,6 +210,35 @@ export function readTeamSync(stateRoot, teamId) {
 export async function writeTeam(stateRoot, state) {
     await atomicWriteText(join(stateRoot, state.id, 'team.json'), JSON.stringify(state, null, 2));
 }
+/** Read the durable set of member session ids retired by remove/delete. */
+export async function readRetiredMemberIds(stateRoot) {
+    try {
+        const parsed = JSON.parse(stripLeadingBom(await readFile(join(stateRoot, RETIRED_MEMBERS_FILE), 'utf8')));
+        if (!Array.isArray(parsed) || parsed.some(value => typeof value !== 'string' || value === '')) {
+            throw new Error('invalid AgentTeams retired member index');
+        }
+        return new Set(parsed);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return new Set();
+        }
+        throw error;
+    }
+}
+/** Atomically add session ids to the durable retired-member deny-list. */
+export async function recordRetiredMemberIds(stateRoot, memberIds) {
+    const additions = memberIds.filter(id => id !== '');
+    if (additions.length === 0)
+        return;
+    await withTeamLock(`retired-members:${stateRoot}`, async () => {
+        const retired = await readRetiredMemberIds(stateRoot);
+        for (const id of additions)
+            retired.add(id);
+        await mkdir(stateRoot, { recursive: true });
+        await atomicWriteText(join(stateRoot, RETIRED_MEMBERS_FILE), `${JSON.stringify([...retired].sort(), null, 2)}\n`);
+    });
+}
 /**
  * Find the team owned by one captain session (at most one per captain).
  * @param stateRoot - resolved absolute state root directory.
@@ -309,6 +372,74 @@ export async function readMailbox(stateRoot, teamId, agentKey, onMalformedLine)
         throw error;
     }
 }
+/** Read only messages that have not been acknowledged by their recipient. */
+export async function readUnreadMailbox(stateRoot, teamId, agentKey, onMalformedLine) {
+    const now = Date.now();
+    return (await readMailbox(stateRoot, teamId, agentKey, onMalformedLine))
+        .filter(message => message.readAt === undefined
+        && (message.deliveryClaimedAt === undefined
+            || now - message.deliveryClaimedAt >= MAILBOX_DELIVERY_LEASE_MS));
+}
+async function mutateMailbox(stateRoot, teamId, agentKey, messageIds, mutate) {
+    if (messageIds.length === 0)
+        return;
+    const file = join(stateRoot, teamId, 'inbox', `${sanitizeKey(agentKey)}.jsonl`);
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const selected = new Set(messageIds);
+    const lines = raw.split('\n').map((rawLine) => {
+        const line = stripLeadingBom(rawLine);
+        if (line.trim() === '')
+            return rawLine;
+        try {
+            const value = JSON.parse(line);
+            if (!isTeamMessage(value) || !selected.has(value.id))
+                return rawLine;
+            return JSON.stringify(mutate(value));
+        }
+        catch {
+            return rawLine;
+        }
+    });
+    await atomicWriteText(file, lines.join('\n'));
+}
+/** Lease selected fallback messages to one delivery path. */
+export async function claimMailboxDelivery(stateRoot, teamId, agentKey, messageIds) {
+    const now = Date.now();
+    await mutateMailbox(stateRoot, teamId, agentKey, messageIds, message => ({
+        ...message,
+        deliveryClaimedAt: now,
+    }));
+}
+/** Release a failed delivery lease so the scheduler can retry it later. */
+export async function releaseMailboxDelivery(stateRoot, teamId, agentKey, messageIds) {
+    await mutateMailbox(stateRoot, teamId, agentKey, messageIds, (message) => {
+        const { deliveryClaimedAt: _claimed, ...released } = message;
+        return released;
+    });
+}
+/**
+ * Mark selected durable mailbox records delivered/read while preserving
+ * malformed lines for diagnostics. Callers serialize this with the team lock.
+ */
+export async function acknowledgeMailbox(stateRoot, teamId, agentKey, messageIds) {
+    const now = Date.now();
+    await mutateMailbox(stateRoot, teamId, agentKey, messageIds, (message) => {
+        const { deliveryClaimedAt: _claimed, ...rest } = message;
+        return {
+            ...rest,
+            deliveredAt: message.deliveredAt ?? now,
+            readAt: message.readAt ?? now,
+        };
+    });
+}
 /** Remove the optional UTF-8 BOM some editors prepend to JSON text. */
 function stripLeadingBom(value) {
     return value.charCodeAt(0) === 0xFEFF ? value.slice(1) : value;
@@ -368,6 +499,11 @@ function isTeamTask(value) {
         && Array.isArray(value['dependencies'])
         && value['dependencies'].every((dependency) => typeof dependency === 'string')
         && isOptionalString(value['output'])
+        && (value['attempt'] === undefined
+            || (Number.isSafeInteger(value['attempt']) && value['attempt'] >= 0))
+        && isOptionalString(value['attemptId'])
+        && isOptionalString(value['handoffId'])
+        && (value['reassigning'] === undefined || typeof value['reassigning'] === 'boolean')
         && isFiniteNumber(value['createdAt'])
         && isFiniteNumber(value['updatedAt']);
 }
@@ -417,7 +553,10 @@ function isTeamMessage(value) {
         && typeof value['from'] === 'string'
         && typeof value['to'] === 'string'
         && typeof value['content'] === 'string'
-        && isFiniteNumber(value['ts']);
+        && isFiniteNumber(value['ts'])
+        && (value['deliveryClaimedAt'] === undefined || isFiniteNumber(value['deliveryClaimedAt']))
+        && (value['deliveredAt'] === undefined || isFiniteNumber(value['deliveredAt']))
+        && (value['readAt'] === undefined || isFiniteNumber(value['readAt']));
 }
 /**
  * Remove a team's whole directory (members should be interrupted first).
@@ -439,7 +578,37 @@ export async function removeTeamDir(stateRoot, teamId) {
 export async function archiveTeamDir(stateRoot, teamId) {
     const archiveRoot = join(stateRoot, 'archive');
     await mkdir(archiveRoot, { recursive: true });
-    await rename(join(stateRoot, teamId), join(archiveRoot, teamId));
+    const source = join(stateRoot, teamId);
+    const target = join(archiveRoot, teamId);
+    const previous = join(archiveRoot, `.${teamId}.previous-${randomUUID()}`);
+    let displaced = false;
+    try {
+        await rename(target, previous);
+        displaced = true;
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    try {
+        await rename(source, target);
+    }
+    catch (error) {
+        if (displaced) {
+            try {
+                await rename(previous, target);
+            }
+            catch (restoreError) {
+                throw new AggregateError([error, restoreError], `failed to archive team "${teamId}" and restore its previous archive`);
+            }
+        }
+        throw error;
+    }
+    // The new generation is authoritative. A failed cleanup only leaves a
+    // hidden recovery directory, which archive discovery deliberately ignores.
+    if (displaced)
+        await rm(previous, { recursive: true, force: true }).catch(() => undefined);
 }
 /**
  * Read one archived team (already moved under `archive/`), or undefined when
@@ -458,7 +627,9 @@ export async function readArchivedTeam(stateRoot, teamId) {
 export async function listArchivedTeamIds(stateRoot) {
     try {
         const entries = await readdir(join(stateRoot, 'archive'), { withFileTypes: true });
-        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+        return entries
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map((entry) => entry.name);
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {