@nanmicoder/dsh-agent-teams 0.1.0

package/lib/snapshot.js

@@ -0,0 +1,155 @@
+/**
+ * Team activity snapshot assembly for the activity panel.
+ *
+ * Server-side assembly mirrors the Claude Code desktop teamWatcher: read the
+ * durable team files (the truth source) and enrich with live subagent
+ * activity, so the panel always reflects the on-disk state even when a model
+ * skipped a tool "ritual" (e.g. not calling update_task on completion).
+ * @module dsh-agent-teams/snapshot
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CAPTAIN_KEY, listArchivedTeamIds, readArchivedTeam, readMailbox, 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) {
+        if (task.status === 'in_progress' && task.assignee === memberName)
+            return task.id;
+    }
+    return '';
+}
+/**
+ * Assemble one team snapshot from its durable files plus live activity.
+ * @param ctx - the plugin context (injects `subagents`, used for activity).
+ * @param stateRoot - resolved absolute state root of the owning workspace.
+ * @param workspace - display name of the owning workspace.
+ * @param state - the durable team record.
+ * @returns the panel snapshot.
+ */
+export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state) {
+    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 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);
+        }
+    }
+    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')) {
+        try {
+            unreadByMember.set(member.name, (await readMailbox(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 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',
+            progress: owned.length === 0 ? 0 : Math.round((done / owned.length) * 100),
+            done,
+            total: owned.length,
+            currentTask: currentTaskOf(member.name, tasks),
+            unread: unreadByMember.get(member.name) ?? 0,
+        };
+    });
+    const captainInbox = await readMailbox(stateRoot, state.id, CAPTAIN_KEY);
+    return {
+        workspace,
+        teamId: state.id,
+        name: state.name,
+        ...state.description !== undefined ? { description: state.description } : {},
+        captainSessionId: state.captainSessionId,
+        members,
+        tasks: tasks.map((task) => ({
+            id: task.id,
+            subject: task.subject,
+            status: task.status,
+            state: taskVisualState(task.status, task.dependencies, tasks),
+            assignee: task.assignee ?? '',
+            dependencies: task.dependencies,
+            depth: depths.get(task.id) ?? 0,
+        })),
+        messageCount: captainInbox.length
+            + members.reduce((count, member) => count + member.unread, 0),
+        captainInbox: captainInbox.slice(-5).map((message) => ({
+            from: message.from,
+            content: message.content,
+        })),
+    };
+}
+/**
+ * Collect every team under the given workspace state roots.
+ * @param ctx - the plugin context.
+ * @param roots - `{ workspace, stateRoot }` pairs (resolved absolute roots).
+ * @returns the snapshots in stable order (workspace, then team id).
+ */
+export async function collectTeamsActivity(ctx, roots) {
+    const snapshots = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await readdir(root.stateRoot, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                continue;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                const state = await readTeam(root.stateRoot, entry.name);
+                if (state === undefined)
+                    continue;
+                snapshots.push(await assembleTeamSnapshot(ctx, root.stateRoot, root.workspace, state));
+            }
+            catch {
+                ctx.logger.warn(`agent-teams: skipped unreadable team state "${entry.name}" in workspace "${root.workspace}"`);
+            }
+        }
+    }
+    return snapshots;
+}
+/**
+ * Collect every archived team under the given workspace state roots (the
+ * `archive/` subdirectory of each state root). Used by the historic panel
+ * path to restore full team detail after deletion.
+ * @param ctx - the plugin context.
+ * @param roots - `{ workspace, stateRoot }` pairs.
+ * @returns the archived snapshots in stable order.
+ */
+export async function collectArchivedTeamsActivity(ctx, roots) {
+    const snapshots = [];
+    for (const root of roots) {
+        for (const teamId of await listArchivedTeamIds(root.stateRoot)) {
+            try {
+                const state = await readArchivedTeam(root.stateRoot, teamId);
+                if (state === undefined)
+                    continue;
+                snapshots.push(await assembleTeamSnapshot(ctx, join(root.stateRoot, 'archive'), root.workspace, state));
+            }
+            catch {
+                ctx.logger.warn(`agent-teams: skipped unreadable archived team "${teamId}" in workspace "${root.workspace}"`);
+            }
+        }
+    }
+    return snapshots;
+}

package/lib/state.js

@@ -0,0 +1,461 @@
+/**
+ * Team state persistence and pure team-logic rules.
+ *
+ * State lives on disk under `<workspace>/<stateDir>/<teamId>/`:
+ * - `team.json` — the durable {@link TeamState} record
+ * - `inbox/<agentKey>.jsonl` — one JSONL mailbox per agent (`captain` or a
+ *   member name), mirroring the Claude Code AgentTeams mailbox layout
+ *
+ * All mutations run through an in-process per-team queue so read-modify-write
+ * stays serial; `fs/promises` is used directly because the plugin owns this
+ * bookkeeping (host-plane state, like session persistence) and the abstract
+ * `fs` service offers no directory deletion.
+ * @module dsh-agent-teams/state
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Mailbox key of the captain. */
+export const CAPTAIN_KEY = 'captain';
+/** In-process per-team mutation queues (promise chains). */
+const locks = new Map();
+/**
+ * Serialize mutations of one team across the whole process.
+ * @param key - the team id (or any mutation scope).
+ * @param fn - the mutation to run exclusively.
+ * @returns the mutation's result.
+ */
+export async function withTeamLock(key, fn) {
+    const previous = locks.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    locks.set(key, previous.then(() => gate));
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Fold a free-form name into a safe path/key segment.
+ * @param name - any user-supplied name.
+ * @returns lowercase `[a-z0-9-]` key, never empty.
+ */
+export function sanitizeKey(name) {
+    const cleaned = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned === '' ? 'team' : cleaned;
+}
+/**
+ * Whether `dependencies` are all satisfied (every named task exists and
+ * completed) for the given task list.
+ * @param tasks - the team's tasks.
+ * @param dependencies - task ids the candidate depends on.
+ * @returns the ids that are still unsatisfied, empty when claimable.
+ */
+export function unsatisfiedDependencies(tasks, dependencies) {
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    return dependencies.filter((id) => byId.get(id)?.status !== 'completed');
+}
+/**
+ * The allowed task status transitions, keyed by current status.
+ * Terminal statuses have no outgoing transitions.
+ */
+export const TASK_TRANSITIONS = {
+    pending: ['claimed', 'cancelled'],
+    claimed: ['in_progress', 'failed', 'cancelled'],
+    in_progress: ['completed', 'failed', 'cancelled'],
+    completed: [],
+    failed: [],
+    cancelled: [],
+};
+/**
+ * Validate one task status transition.
+ * @param current - the task's current status.
+ * @param next - the requested status.
+ * @returns the transition error, or undefined when allowed.
+ */
+export function transitionError(current, next) {
+    if (current === next)
+        return undefined;
+    if (!TASK_TRANSITIONS[current].includes(next)) {
+        return `task status cannot move from "${current}" to "${next}"`;
+    }
+    return undefined;
+}
+/**
+ * Create the team directory structure and the initial team record.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param state - the initial team record.
+ */
+export async function createTeamDir(stateRoot, state) {
+    const dir = join(stateRoot, state.id);
+    await mkdir(join(dir, 'inbox'), { recursive: true });
+    await atomicWriteText(join(dir, 'team.json'), JSON.stringify(state, null, 2));
+}
+/**
+ * Read one team record; `undefined` when absent.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team's sanitized id.
+ */
+export async function readTeam(stateRoot, teamId) {
+    try {
+        const raw = await readFile(join(stateRoot, teamId, 'team.json'), 'utf8');
+        const value = JSON.parse(stripLeadingBom(raw));
+        if (!isTeamState(value, teamId)) {
+            throw new Error(`invalid AgentTeams state in team "${teamId}"`);
+        }
+        return value;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Persist one team record (inside the caller's lock).
+ * @param stateRoot - resolved absolute state root directory.
+ * @param state - the record to persist.
+ */
+export async function writeTeam(stateRoot, state) {
+    await atomicWriteText(join(stateRoot, state.id, 'team.json'), JSON.stringify(state, null, 2));
+}
+/**
+ * Find the team owned by one captain session (at most one per captain).
+ * @param stateRoot - resolved absolute state root directory.
+ * @param captainSessionId - the owning session id.
+ * @returns the team record, or undefined when the captain leads no team.
+ */
+export async function findTeamByCaptain(stateRoot, captainSessionId) {
+    let entries;
+    try {
+        entries = await readdir(stateRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+    let found;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const team = await readTeam(stateRoot, entry.name);
+        if (team?.captainSessionId === captainSessionId) {
+            if (found !== undefined && found.id !== team.id) {
+                throw new Error(`captain session leads multiple active teams ("${found.id}", "${team.id}"); archive one before continuing`);
+            }
+            found = team;
+        }
+    }
+    return found;
+}
+/**
+ * Find the team in which one session is an active participant.
+ * Captains match `captainSessionId`; members match their durable child session
+ * id. Removed members no longer have access to team-scoped tools.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param agentSessionId - calling captain/member session id.
+ * @returns the team record, or undefined when the caller belongs to no team.
+ */
+export async function findTeamByParticipant(stateRoot, agentSessionId) {
+    let entries;
+    try {
+        entries = await readdir(stateRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+    let found;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const team = await readTeam(stateRoot, entry.name);
+        const participates = team?.captainSessionId === agentSessionId
+            || team?.members.some((member) => member.id === agentSessionId && member.status !== 'removed') === true;
+        if (participates && team !== undefined) {
+            if (found !== undefined && found.id !== team.id) {
+                throw new Error(`agent session belongs to multiple active teams ("${found.id}", "${team.id}"); the target team is ambiguous`);
+            }
+            found = team;
+        }
+    }
+    return found;
+}
+/** Build a fresh message record. */
+export function createMessage(from, to, content) {
+    return { id: randomUUID(), from, to, content, ts: Date.now() };
+}
+/**
+ * Append one message to an agent's mailbox (JSONL).
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team id.
+ * @param agentKey - `captain` or a member name.
+ * @param message - the message to append.
+ */
+export async function appendMailbox(stateRoot, teamId, agentKey, message) {
+    const file = join(stateRoot, teamId, 'inbox', `${sanitizeKey(agentKey)}.jsonl`);
+    await mkdir(join(stateRoot, teamId, 'inbox'), { recursive: true });
+    let existing = '';
+    try {
+        existing = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    const separator = existing !== '' && !existing.endsWith('\n') ? '\n' : '';
+    await atomicWriteText(file, `${existing}${separator}${JSON.stringify(message)}\n`);
+}
+/**
+ * Read one agent's whole mailbox, oldest first.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team id.
+ * @param agentKey - `captain` or a member name.
+ * @param onMalformedLine - optional diagnostic hook; malformed records are
+ * skipped so one manually damaged line cannot make the whole team unreadable.
+ * @returns the messages, empty when the mailbox does not exist yet.
+ */
+export async function readMailbox(stateRoot, teamId, agentKey, onMalformedLine) {
+    const file = join(stateRoot, teamId, 'inbox', `${sanitizeKey(agentKey)}.jsonl`);
+    try {
+        const raw = await readFile(file, 'utf8');
+        const messages = [];
+        for (const [index, rawLine] of raw.split('\n').entries()) {
+            const line = stripLeadingBom(rawLine);
+            if (line.trim() === '')
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                onMalformedLine?.(index + 1, new Error('invalid JSON'));
+                continue;
+            }
+            if (!isTeamMessage(value)) {
+                onMalformedLine?.(index + 1, new Error('invalid message shape'));
+                continue;
+            }
+            messages.push(value);
+        }
+        return messages;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/** Remove the optional UTF-8 BOM some editors prepend to JSON text. */
+function stripLeadingBom(value) {
+    return value.charCodeAt(0) === 0xFEFF ? value.slice(1) : value;
+}
+/** Atomically replace one UTF-8 state file from a same-directory temp file. */
+async function atomicWriteText(file, content) {
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** Whether a parsed JSON value is a plain record. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether a value is an optional string. */
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+/** Whether a value is a finite timestamp/counter number. */
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/** Validate one member record at the durable JSON boundary. */
+function isTeamMember(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value['id'] === 'string'
+        && typeof value['name'] === 'string'
+        && value['name'].trim() !== ''
+        && isOptionalString(value['role'])
+        && isOptionalString(value['model'])
+        && isFiniteNumber(value['joinedAt'])
+        && (value['status'] === 'idle' || value['status'] === 'working' || value['status'] === 'removed');
+}
+/** Validate one task record at the durable JSON boundary. */
+function isTeamTask(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value['id'] === 'string'
+        && typeof value['subject'] === 'string'
+        && isOptionalString(value['description'])
+        && (value['status'] === 'pending'
+            || value['status'] === 'claimed'
+            || value['status'] === 'in_progress'
+            || value['status'] === 'completed'
+            || value['status'] === 'failed'
+            || value['status'] === 'cancelled')
+        && isOptionalString(value['assignee'])
+        && Array.isArray(value['dependencies'])
+        && value['dependencies'].every((dependency) => typeof dependency === 'string')
+        && isOptionalString(value['output'])
+        && isFiniteNumber(value['createdAt'])
+        && isFiniteNumber(value['updatedAt']);
+}
+/** Validate the full team record before it can participate in authorization. */
+function isTeamState(value, expectedId) {
+    if (!isRecord(value))
+        return false;
+    const validShape = value['id'] === expectedId
+        && typeof value['name'] === 'string'
+        && value['name'].trim() !== ''
+        && isOptionalString(value['description'])
+        && typeof value['captainSessionId'] === 'string'
+        && value['captainSessionId'] !== ''
+        && isFiniteNumber(value['createdAt'])
+        && Array.isArray(value['members'])
+        && value['members'].every(isTeamMember)
+        && Array.isArray(value['tasks'])
+        && value['tasks'].every(isTeamTask)
+        && Number.isSafeInteger(value['taskSeq'])
+        && value['taskSeq'] >= 0;
+    if (!validShape)
+        return false;
+    const members = value['members'];
+    const tasks = value['tasks'];
+    const memberIds = new Set();
+    const memberKeys = new Set();
+    for (const member of members) {
+        const key = sanitizeKey(member.name);
+        if (member.id === '' || key === CAPTAIN_KEY || memberIds.has(member.id) || memberKeys.has(key))
+            return false;
+        memberIds.add(member.id);
+        memberKeys.add(key);
+    }
+    const taskIds = new Set();
+    for (const task of tasks) {
+        if (task.id === '' || taskIds.has(task.id))
+            return false;
+        taskIds.add(task.id);
+    }
+    return true;
+}
+/** Validate a mailbox record so later rendering cannot crash on `{}`/`null`. */
+function isTeamMessage(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value['id'] === 'string'
+        && typeof value['from'] === 'string'
+        && typeof value['to'] === 'string'
+        && typeof value['content'] === 'string'
+        && isFiniteNumber(value['ts']);
+}
+/**
+ * Remove a team's whole directory (members should be interrupted first).
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team id.
+ */
+export async function removeTeamDir(stateRoot, teamId) {
+    await rm(join(stateRoot, teamId), { recursive: true, force: true });
+}
+/**
+ * Archive a team instead of deleting it: the whole directory (team.json with
+ * tasks and dependency graph, plus the mailboxes) moves under
+ * `<stateRoot>/archive/<teamId>/` so later sessions can review how tasks were
+ * planned and rebuild dependency relationships. The archive directory has no
+ * team.json of its own, so the live activity scan skips it naturally.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team id.
+ */
+export async function archiveTeamDir(stateRoot, teamId) {
+    const archiveRoot = join(stateRoot, 'archive');
+    await mkdir(archiveRoot, { recursive: true });
+    await rename(join(stateRoot, teamId), join(archiveRoot, teamId));
+}
+/**
+ * Read one archived team (already moved under `archive/`), or undefined when
+ * it was never archived.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team id.
+ */
+export async function readArchivedTeam(stateRoot, teamId) {
+    return readTeam(join(stateRoot, 'archive'), teamId);
+}
+/**
+ * List every archived team id under the state root.
+ * @param stateRoot - resolved absolute state root directory.
+ * @returns the archived team ids, empty when the archive does not exist.
+ */
+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);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * The visual state of one task: `running` while in_progress, `completed`
+ * when done, `blocked` while any dependency is unfinished, else `open`.
+ */
+export function taskVisualState(status, dependencies, tasks) {
+    if (status === 'completed')
+        return 'completed';
+    if (status === 'in_progress')
+        return 'running';
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    const openDependency = dependencies.some((dependencyId) => {
+        const dependency = byId.get(dependencyId);
+        return dependency !== undefined && dependency.status !== 'completed';
+    });
+    return openDependency ? 'blocked' : 'open';
+}
+/**
+ * Longest dependency path depth per task id (each depth = one lane column).
+ */
+export function taskDepthsById(tasks) {
+    const byId = new Map(tasks.map((task) => [task.id, task]));
+    const depths = new Map();
+    const visiting = new Set();
+    const depthOf = (taskId) => {
+        const cached = depths.get(taskId);
+        if (cached !== undefined)
+            return cached;
+        if (visiting.has(taskId))
+            return 0;
+        const task = byId.get(taskId);
+        if (task === undefined)
+            return 0;
+        visiting.add(taskId);
+        const dependencies = task.dependencies
+            .filter((dependencyId) => byId.has(dependencyId))
+            .sort();
+        const depth = dependencies.length === 0
+            ? 0
+            : 1 + Math.max(...dependencies.map(depthOf));
+        visiting.delete(taskId);
+        depths.set(taskId, depth);
+        return depth;
+    };
+    for (const task of tasks)
+        depthOf(task.id);
+    return depths;
+}