@nanmicoder/dsh-agent-teams 0.1.0

package/lib/types/state.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 type { TaskStatus, TeamMessage, TeamState, TeamTask } from './types.ts';
+/** Mailbox key of the captain. */
+export declare const CAPTAIN_KEY = "captain";
+/**
+ * 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 declare function withTeamLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function sanitizeKey(name: string): string;
+/**
+ * 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 declare function unsatisfiedDependencies(tasks: TeamTask[], dependencies: string[]): string[];
+/**
+ * The allowed task status transitions, keyed by current status.
+ * Terminal statuses have no outgoing transitions.
+ */
+export declare const TASK_TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>>;
+/**
+ * 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 declare function transitionError(current: TaskStatus, next: TaskStatus): string | 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 declare function createTeamDir(stateRoot: string, state: TeamState): Promise<void>;
+/**
+ * Read one team record; `undefined` when absent.
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team's sanitized id.
+ */
+export declare function readTeam(stateRoot: string, teamId: string): Promise<TeamState | undefined>;
+/**
+ * Persist one team record (inside the caller's lock).
+ * @param stateRoot - resolved absolute state root directory.
+ * @param state - the record to persist.
+ */
+export declare function writeTeam(stateRoot: string, state: TeamState): Promise<void>;
+/**
+ * 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 declare function findTeamByCaptain(stateRoot: string, captainSessionId: string): Promise<TeamState | undefined>;
+/**
+ * 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 declare function findTeamByParticipant(stateRoot: string, agentSessionId: string): Promise<TeamState | undefined>;
+/** Build a fresh message record. */
+export declare function createMessage(from: string, to: string, content: string): TeamMessage;
+/**
+ * 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 declare function appendMailbox(stateRoot: string, teamId: string, agentKey: string, message: TeamMessage): Promise<void>;
+/**
+ * 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 declare function readMailbox(stateRoot: string, teamId: string, agentKey: string, onMalformedLine?: (lineNumber: number, error: unknown) => void): Promise<TeamMessage[]>;
+/**
+ * Remove a team's whole directory (members should be interrupted first).
+ * @param stateRoot - resolved absolute state root directory.
+ * @param teamId - the team id.
+ */
+export declare function removeTeamDir(stateRoot: string, teamId: string): Promise<void>;
+/**
+ * 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 declare function archiveTeamDir(stateRoot: string, teamId: string): Promise<void>;
+/**
+ * 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 declare function readArchivedTeam(stateRoot: string, teamId: string): Promise<TeamState | undefined>;
+/**
+ * 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 declare function listArchivedTeamIds(stateRoot: string): Promise<string[]>;
+/** Visual task state for the activity panel. */
+export type VisualTaskState = 'blocked' | 'open' | 'running' | 'completed';
+/**
+ * The visual state of one task: `running` while in_progress, `completed`
+ * when done, `blocked` while any dependency is unfinished, else `open`.
+ */
+export declare function taskVisualState(status: string, dependencies: readonly string[], tasks: readonly TeamTask[]): VisualTaskState;
+/**
+ * Longest dependency path depth per task id (each depth = one lane column).
+ */
+export declare function taskDepthsById(tasks: readonly TeamTask[]): Map<string, number>;

package/lib/types/tools.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `agent_teams_*` model-facing tools.
+ *
+ * The captain (the agent that created the team) orchestrates: members are
+ * continuable subagents it spawns and wakes. Members share the same tools and
+ * drive their own task state, mirroring the Claude Code AgentTeams flow:
+ * create team → add members → create tasks with dependencies → claim/assign →
+ * work → report → status → delete.
+ * @module dsh-agent-teams/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/** Resolved plugin config consumed by the tools. */
+export interface ToolsConfig {
+    /** State directory name under the captain's workspace. */
+    stateDir: string;
+    /** Member subagent provider name. */
+    memberProvider: string;
+    /** Optional member model override. */
+    memberModel?: string;
+    /** Member delegation depth cap. */
+    memberMaxDepth?: number;
+    /** Team size cap (members). */
+    maxMembers: number;
+}
+/**
+ * Deliver a durable member report at the captain's nearest model boundary.
+ *
+ * `Agent.steer()` targets the next step while the captain is running, wakes a
+ * new turn when it is idle, and lets the Agent runtime reclassify an aborted
+ * activity to `next-turn`. This prevents reports from waiting behind the
+ * captain's entire orchestration turn.
+ */
+export declare function steerCaptainReport(captain: Pick<Agent, 'steer'>, from: string, content: string): boolean;
+/**
+ * Register every `agent_teams_*` tool into the shared tools registry.
+ * @param ctx - the plugin context (injects `tools`).
+ * @param config - resolved tool config.
+ */
+export declare function registerAgentTeamsTools(ctx: Context, config: ToolsConfig): void;

package/lib/types/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Durable AgentTeams state types.
+ *
+ * A team is one directory under the state root holding `team.json` plus an
+ * `inbox/` of per-agent JSONL mailboxes. Members are continuable subagents
+ * whose durable child session ids are recorded in the team file, so a team
+ * survives harness restarts.
+ * @module dsh-agent-teams/types
+ */
+/** Task lifecycle statuses in progression order. */
+export type TaskStatus = 'pending' | 'claimed' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+/** Statuses after which a task can no longer be claimed or worked on. */
+export declare const TERMINAL_TASK_STATUSES: readonly TaskStatus[];
+/** One task of a team's task list. */
+export interface TeamTask {
+    /** Stable task id within the team (`t1`, `t2`, …). */
+    id: string;
+    /** Brief title for the task. */
+    subject: string;
+    /** What needs to be done. */
+    description?: string;
+    status: TaskStatus;
+    /** Member name the task is assigned to; unassigned tasks await a claim. */
+    assignee?: string;
+    /** Task ids that must reach `completed` before this task can be claimed. */
+    dependencies: string[];
+    /** The worker's written result, set when the task completes or fails. */
+    output?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Member lifecycle status. */
+export type MemberStatus = 'idle' | 'working' | 'removed';
+/** One team member: a continuable subagent plus its team-side record. */
+export interface TeamMember {
+    /** Durable continuable subagent session id (empty until spawned). */
+    id: string;
+    /** Unique display name inside the team. */
+    name: string;
+    /** Role description, e.g. `researcher`, `engineer`, `reviewer`. */
+    role?: string;
+    /** Optional model override for this member. */
+    model?: string;
+    joinedAt: number;
+    status: MemberStatus;
+}
+/** One mailbox message. */
+export interface TeamMessage {
+    id: string;
+    /** `captain` or a member name. */
+    from: string;
+    /** `captain` or a member name. */
+    to: string;
+    content: string;
+    ts: number;
+}
+/** The full durable team record. */
+export interface TeamState {
+    /** Original team name. */
+    name: string;
+    /** Sanitized directory id; the team's stable identity. */
+    id: string;
+    /** Team purpose/goal. */
+    description?: string;
+    /** Session id of the captain agent that owns this team. */
+    captainSessionId: string;
+    createdAt: number;
+    /** Teammates only; the captain is implicit (the owning session). */
+    members: TeamMember[];
+    tasks: TeamTask[];
+    /** Monotonic task id counter. */
+    taskSeq: number;
+}

package/lib/types.js

@@ -0,0 +1,11 @@
+/**
+ * Durable AgentTeams state types.
+ *
+ * A team is one directory under the state root holding `team.json` plus an
+ * `inbox/` of per-agent JSONL mailboxes. Members are continuable subagents
+ * whose durable child session ids are recorded in the team file, so a team
+ * survives harness restarts.
+ * @module dsh-agent-teams/types
+ */
+/** Statuses after which a task can no longer be claimed or worked on. */
+export const TERMINAL_TASK_STATUSES = ['completed', 'failed', 'cancelled'];

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@nanmicoder/dsh-agent-teams",
+  "version": "0.1.0",
+  "description": "AgentTeams for DeepSeek Harness: multi-agent team collaboration (captain, members, tasks with dependencies, messaging) driven by natural language, with a tree monitor in the web GUI",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "assets/agent-teams",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "程序员阿江(Relakkes) <relakkes@gmail.com>",
+  "homepage": "https://github.com/NanmiCoder/dsh-agent-teams#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NanmiCoder/dsh-agent-teams.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NanmiCoder/dsh-agent-teams/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "agent-teams",
+    "multi-agent",
+    "subagent",
+    "ai-agent",
+    "llm"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-client-locale",
+      "@deepseek-ai/dsh-client-runtime",
+      "@deepseek-ai/dsh-client-ui-conversation"
+    ],
+    "platform": "web"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "sync:skill": "node scripts/sync-skill.mjs",
+    "verify:skill": "node scripts/sync-skill.mjs --check",
+    "verify": "node scripts/verify.mjs && pnpm verify:skill",
+    "prepublishOnly": "pnpm build && pnpm verify"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "react": "^18.2.0",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^19.2.4",
+    "lightningcss": "^1.33.0",
+    "tsdown": "0.22.2",
+    "typescript": "^5.9.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}