@nanmicoder/dsh-agent-teams 0.1.0

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

@@ -0,0 +1,64 @@
+/**
+ * AgentTeams activity panel: the top-right floater monitoring every team.
+ *
+ * Modeled on the Claude Code desktop SessionActivityPanel: a fixed glass
+ * panel at the top-right corner. On wide viewports it cooperatively makes the
+ * conversation column yield space; narrow viewports keep overlay mode. It
+ * polls the host `/plugins/dsh-agent-teams/state` route for
+ * server-side snapshots (durable files + live subagent activity), with a
+ * collapsed badge that auto-expands once when activity appears. Archived
+ * teams stay available for the owning conversation after live work ends.
+ *
+ * The floater mounts through a body portal (no top-right slot exists in the
+ * web shell); it is not a conversation node — the in-conversation panel was
+ * removed in favor of this always-available monitor.
+ * @module dsh-agent-teams/client/activity
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { ObservableSnapshot, SessionListState } from '@deepseek-ai/dsh-client-runtime/client';
+/** One member row of a host snapshot. */
+export interface ActivityMember {
+    readonly id: string;
+    readonly name: string;
+    readonly role: string;
+    readonly activity: 'working' | 'idle' | 'unknown';
+    readonly progress: number;
+    readonly done: number;
+    readonly total: number;
+    readonly currentTask: string;
+    readonly unread: number;
+}
+/** One task row of a host snapshot. */
+export interface ActivityTask {
+    readonly id: string;
+    readonly subject: string;
+    readonly status: string;
+    readonly state: 'blocked' | 'open' | 'running' | 'completed';
+    readonly assignee: string;
+    readonly dependencies: readonly string[];
+    readonly depth: number;
+}
+/** One captain-inbox preview row. */
+export interface ActivityMessage {
+    readonly from: string;
+    readonly content: string;
+}
+/** One team snapshot (mirrors the host TeamActivitySnapshot). */
+export interface ActivityTeam {
+    readonly workspace: string;
+    readonly teamId: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly captainSessionId: string;
+    readonly members: readonly ActivityMember[];
+    readonly tasks: readonly ActivityTask[];
+    readonly messageCount: number;
+    readonly captainInbox: readonly ActivityMessage[];
+}
+/** The top-right activity floater. Teams follow the current session: live
+ * snapshots and historic card summaries are only shown while their captain
+ * session is the one currently open. */
+export declare function ActivityPanel({ sessionsList, openSession }: {
+    readonly sessionsList: ObservableSnapshot<SessionListState>;
+    readonly openSession: (id: SessionId) => void;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,24 @@
+/**
+ * AgentTeams conversation card: the lightweight in-conversation summary for
+ * one team — the captain's whale avatar and name, the member roster as
+ * clickable whale avatars (opening the member's subagent transcript), and
+ * an "activity panel" button that re-activates the top-right floater.
+ *
+ * The floater and this card share the `agent-teams:open-panel` window event
+ * so the card can summon the panel even after it was closed (or when an old
+ * session is re-opened for review).
+ * @module dsh-agent-teams/client/card
+ */
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/** Window event name the floater listens for to open itself. */
+export declare const OPEN_PANEL_EVENT = "agent-teams:open-panel";
+/** Navigation action injected from the plugin's own SessionsService access. */
+export interface AgentTeamsCardInjected {
+    readonly openSession: (id: SessionId) => void;
+    readonly currentSessionId: () => SessionId | undefined;
+}
+/** Complete keyed Chat renderer props. */
+export type AgentTeamsCardProps = PropsRuntime<'conversation.chat.node', 'agent-teams'> & PropsLocale<'agentTeams'> & AgentTeamsCardInjected;
+/** Render one durable team as a compact conversation card. */
+export declare function AgentTeamsCard({ node, openSession, currentSessionId }: AgentTeamsCardProps): import("react").JSX.Element;

package/lib/types/client/activity-model.d.ts

@@ -0,0 +1,31 @@
+/** Pure relationship projections used by the AgentTeams activity panel. */
+/** Minimum task shape needed to derive dependency relationships. */
+export interface RelationshipTask {
+    readonly id: string;
+    readonly dependencies: readonly string[];
+    readonly depth: number;
+}
+/** One dependency-depth stage in stable display order. */
+export interface RelationshipStage<T extends RelationshipTask> {
+    readonly depth: number;
+    readonly tasks: readonly T[];
+}
+/**
+ * Whether an expanded activity panel still belongs to the current session.
+ *
+ * The panel is mounted through a body portal, so React does not remount it
+ * when the conversation route changes. Ownership keeps an expanded panel
+ * from leaking onto the new-session screen (or another conversation) while
+ * its local open state is being reset.
+ */
+export declare function activityPanelExpandedForSession(open: boolean, owner: string | undefined, current: string | undefined): boolean;
+/** Group tasks by their precomputed dependency depth. */
+export declare function taskStages<T extends RelationshipTask>(tasks: readonly T[]): readonly RelationshipStage<T>[];
+/**
+ * Return the complete upstream/downstream chain around one task.
+ *
+ * Traversal uses both dependency directions and remains cycle-safe, so the UI
+ * can highlight every handoff related to the focused task even if malformed
+ * durable data contains a cycle.
+ */
+export declare function relatedTaskIds(taskId: string, tasks: readonly RelationshipTask[]): ReadonlySet<string>;

package/lib/types/client/agent-teams-card-definition.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AgentTeams conversation card: a lightweight in-conversation summary shown
+ * when a team is created — the captain's name, the member roster with whale
+ * avatars, and an entry point that re-activates the top-right activity
+ * panel (useful after the floater was closed, or when re-opening an old
+ * session for review).
+ *
+ * The fold anchors to the Harness's durable `tool/call` + `tool/result`
+ * records for `agent_teams_create`. Those are first-party session events, so
+ * the card survives restarts without writing an out-of-repo event type.
+ * @module dsh-agent-teams/client/card
+ */
+import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-runtime/client';
+/** Final keyed Chat payload for the team summary card. */
+export interface AgentTeamsCardData {
+    readonly teamId: string;
+    /** The captain session that owns this team (panel follows it). */
+    readonly captainSessionId: string;
+    readonly teamName: string;
+    readonly members: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly role: string;
+    }[];
+}
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+    interface ChatNodeDataMap {
+        /** Lightweight team summary card anchoring the conversation. */
+        'agent-teams': AgentTeamsCardData;
+    }
+}
+/** Folded team record (the node's business state). */
+export interface AgentTeamsNodeState {
+    readonly teamId: string;
+    readonly name: string;
+    readonly accepted: boolean;
+}
+/** Parse the only create-call fields the historic card owns. */
+export declare function parseAgentTeamsCreateArgs(value: string): {
+    teamId: string;
+    name: string;
+} | undefined;
+/** Durable first-party tool events folded into one keyed Chat node. */
+export declare const agentTeamsCardDefinition: ConversationNodeDefinition<AgentTeamsNodeState>;

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

@@ -0,0 +1,19 @@
+/**
+ * Shared whale artwork lookup for the activity panel and the conversation
+ * card: role keywords map to the packaged role images; the captain always
+ * uses the lead whale.
+ * @module dsh-agent-teams/client/artwork
+ */
+/** Artwork route prefix served by the plugin host half. */
+export declare const ART_BASE = "/plugins/dsh-agent-teams/assets/";
+/** Captain artwork (always the lead whale). */
+export declare const LEAD_ART = "/plugins/dsh-agent-teams/assets/team-lead.png";
+/** Status action artwork per member activity. */
+export declare const ACTION_ART: Record<'working' | 'idle' | 'unknown', string>;
+/**
+ * Member artwork URL, or null when no role matches (initial-letter fallback).
+ * @param name - the member's display name.
+ * @param role - the member's role text.
+ * @returns the artwork URL, or null when unmatched.
+ */
+export declare function memberArtUrl(name: string, role: string): string | null;

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

@@ -0,0 +1,11 @@
+/** Browser plugin for the AgentTeams activity floater and conversation card. */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** Required services: conversation nodes, slots, and sessions navigation. */
+export declare const inject: string[];
+/**
+ * Mount the floater through a body portal (the web shell has no top-right
+ * slot) and register the in-conversation team card, whose "activity panel"
+ * button re-activates the floater via a window event — the recovery path
+ * for a closed floater or a re-opened session.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/event-types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * AgentTeams session event types — pure types only, zero imports.
+ *
+ * This file intentionally imports nothing: both the host program (the
+ * emitter in `events.ts`) and the browser program (the Conversation Node
+ * definition) must be able to load these types and the `SessionEventMap`
+ * declaration merge without pulling in host-side `Context` augmentations
+ * (dsh-session's index declares `Context.sessions: SessionStore`, which
+ * collides with the browser runtime's `ISessions` under the same name).
+ * @module dsh-agent-teams/event-types
+ */
+/** Opens one team record: the captain created the team. */
+export interface AgentTeamsTeamCreatedData {
+    readonly teamId: string;
+    /** The captain session that owns this team (UI follows it). */
+    readonly captainSessionId: string;
+    readonly name: string;
+    readonly description?: string;
+}
+/** Records one member after its continuable subagent is spawned. */
+export interface AgentTeamsMemberAddedData {
+    readonly teamId: string;
+    readonly memberId: string;
+    readonly name: string;
+    readonly role?: string;
+}
+/** Marks one member removed. */
+export interface AgentTeamsMemberRemovedData {
+    readonly teamId: string;
+    readonly memberId: string;
+}
+/** Records one task in the team's task list. */
+export interface AgentTeamsTaskCreatedData {
+    readonly teamId: string;
+    readonly taskId: string;
+    readonly subject: string;
+    readonly dependencies: readonly string[];
+    readonly assignee?: string;
+}
+/** Records one task status/assignee/output transition. */
+export interface AgentTeamsTaskUpdatedData {
+    readonly teamId: string;
+    readonly taskId: string;
+    readonly status: string;
+    readonly assignee?: string;
+    readonly output?: string;
+}
+/** Closes one team record: the team was deleted. */
+export interface AgentTeamsTeamDeletedData {
+    readonly teamId: string;
+}
+/** Records one mailbox message sent between team agents. */
+export interface AgentTeamsMessageSentData {
+    readonly teamId: string;
+    readonly messageId: string;
+    /** `captain` or a member name. */
+    readonly from: string;
+    /** `captain` or a member name. */
+    readonly to: string;
+    readonly content: string;
+    readonly ts: number;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Opens one team record.
+         * @param data - stable team identity and display name.
+         */
+        'agent-teams/team-created': AgentTeamsTeamCreatedData;
+        /**
+         * Records one team member.
+         * @param data - team identity, member child session, and display identity.
+         */
+        'agent-teams/member-added': AgentTeamsMemberAddedData;
+        /**
+         * Records one member removal.
+         * @param data - team identity and the member's child session id.
+         */
+        'agent-teams/member-removed': AgentTeamsMemberRemovedData;
+        /**
+         * Records one task creation.
+         * @param data - team identity, task id, subject, dependencies, assignee.
+         */
+        'agent-teams/task-created': AgentTeamsTaskCreatedData;
+        /**
+         * Records one task transition.
+         * @param data - team identity, task id, and the new status/assignee/output.
+         */
+        'agent-teams/task-updated': AgentTeamsTaskUpdatedData;
+        /**
+         * Records one mailbox message.
+         * @param data - team identity, sender, recipient, and content.
+         */
+        'agent-teams/message-sent': AgentTeamsMessageSentData;
+        /**
+         * Closes one team record after deletion.
+         * @param data - stable team identity.
+         */
+        'agent-teams/team-deleted': AgentTeamsTeamDeletedData;
+    }
+}
+/** The full set of `agent-teams/*` event names. */
+export type AgentTeamsEventType = 'agent-teams/team-created' | 'agent-teams/member-added' | 'agent-teams/member-removed' | 'agent-teams/task-created' | 'agent-teams/task-updated' | 'agent-teams/message-sent' | 'agent-teams/team-deleted';

package/lib/types/events.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Durable AgentTeams session events and their emitter.
+ *
+ * Every team-state mutation appends one event to the captain's Session, so
+ * the web client's Conversation Node mechanism can fold the tree view from
+ * the session log deterministically (same mechanism as `tool-workflow`'s
+ * `tool-workflow/*` record events). Events append to the captain's session
+ * even when a member agent performed the mutation, so the captain's
+ * conversation stream stays the single authoritative monitor surface.
+ *
+ * Types and the `SessionEventMap` merge live in `event-types.ts` (zero
+ * imports) so the browser program can load them without host augmentations.
+ * @module dsh-agent-teams/events
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionEventMap } from '@deepseek-ai/dsh-session/types';
+import type { AgentTeamsEventType } from './event-types.ts';
+/**
+ * Append one AgentTeams event to a Session, containing failures (a broken
+ * durable record must never break team tool execution).
+ * @param ctx - the plugin context (for logging).
+ * @param session - the session to record into (the captain's, normally).
+ * @param type - the event type.
+ * @param data - the event payload.
+ */
+export declare function appendTeamEvent(ctx: Context, session: Session, type: AgentTeamsEventType, data: SessionEventMap[AgentTeamsEventType]): void;
+/**
+ * Resolve the captain's live Session for event recording. The captain agent
+ * may be offline (its team outlives the session), in which case the caller's
+ * own session is used as the fallback record target.
+ * @param ctx - the plugin context (injects `agents`).
+ * @param captainSessionId - the captain's durable session id.
+ * @param fallback - the calling agent's session, used when the captain is not live.
+ * @returns the session to record into.
+ */
+export declare function captainSessionOf(ctx: Context, captainSessionId: string, fallback: Session): Session;

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ * 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
+ * dependencies, wakes members with messages, relays reports, and collects
+ * results.
+ *
+ * Installation (bundle): `dsh plugin --profile <name> add @nanmicoder/dsh-agent-teams`
+ * (or a local path). The bundle patch mounts this plugin row into the host
+ * composition; the tools register into the shared `tools` registry and the
+ * usage section into the global system prompt, so the plugin needs no realm.
+ *
+ * @module dsh-agent-teams
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "agent-teams";
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * State directory name under the captain's workspace; team state lives at
+     * `<workspace>/<stateDir>/<teamId>/` (default `.agent-teams`).
+     */
+    stateDir?: string;
+    /** `ctx.subagents` provider used to spawn members; must support continuable children and personas (default `spawn`). */
+    memberProvider?: string;
+    /** Optional model override applied to every member. */
+    memberModel?: string;
+    /** Member delegation depth cap (default `1`; `0` forbids delegation entirely). */
+    memberMaxDepth?: number;
+    /** Team size cap in members (default `8`). */
+    maxMembers?: number;
+    /** Prompt-section order for the usage policy (default `117`, after delegation policy). */
+    promptSectionOrder?: number;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/members.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Member subagent lifecycle: spawn a continuable child per member, deliver
+ * messages into its FIFO inbox, and observe its activity.
+ *
+ * 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
+ * (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,
+ * which the captain reads through `agent_teams_status`.
+ * @module dsh-agent-teams/members
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { TeamMember, TeamState } from './types.ts';
+/** Runtime knobs for member spawning, resolved from plugin config. */
+export interface MemberRuntimeConfig {
+    /** Registered `ctx.subagents` provider name (must support continuable + persona). */
+    provider: string;
+    /** Optional model override applied to every member. */
+    model?: string;
+    /** Child delegation depth cap (0 forbids delegation entirely). */
+    maxDepth?: number;
+}
+/**
+ * The member's system prompt (persona), shadowing the deployment persona for
+ * that child. Self-contained: it replaces the whole persona section.
+ * @param team - the team the member joined.
+ * @param member - the member record (name/role are read before spawning).
+ * @param stateDir - configured state directory, so the member can locate the
+ *   team files with its own file tools.
+ */
+export declare function memberPersona(team: TeamState, member: TeamMember, stateDir: string): string;
+/**
+ * The initial user message delivered when the member is created.
+ * @param team - the team the member joined.
+ */
+export declare function memberWelcome(team: TeamState): string;
+/**
+ * Spawn one member as a durable continuable subagent of the captain and fill
+ * `member.id` with its child session id. On failure nothing is persisted.
+ * @param ctx - the plugin context (injects `subagents`).
+ * @param config - member runtime knobs.
+ * @param captain - the exact live captain agent (the calling agent).
+ * @param team - the team record (read-only here).
+ * @param member - the member draft whose `id` is filled on success.
+ * @param stateDir - configured state directory (for the persona).
+ * @param signal - caller cancellation, forwarded to the start.
+ */
+export declare function spawnMember(ctx: Context, config: MemberRuntimeConfig, captain: Agent, team: TeamState, member: TeamMember, stateDir: string, signal: AbortSignal): Promise<void>;
+/**
+ * Deliver one message to a member as its next FIFO turn. Best effort: a
+ * failure (member gone or not continuable) is logged and reported as `false`
+ * so the caller can decide (mailbox delivery still happened).
+ *
+ * Any team sender can route through this helper: the captain is the direct
+ * parent of every member, and the caller passes the captain's live Agent
+ * (its own when the captain calls, the registry-resolved one when a member
+ * sends) — mirroring the Claude Code mailbox model where the writer writes
+ * the target's inbox and the target picks it up on its own.
+ * @param ctx - the plugin context (injects `subagents`).
+ * @param captain - the exact live captain agent (the member's direct parent).
+ * @param childId - the member's durable child session id.
+ * @param text - the message content.
+ * @param signal - caller cancellation, forwarded to the delivery.
+ * @returns whether the member inbox accepted the message.
+ */
+export declare function deliverToMember(ctx: Context, captain: Agent, childId: string, text: string, signal: AbortSignal): Promise<boolean>;
+/**
+ * Request cancellation of one live member's current turn. Best effort, fire
+ * and return; the target may keep running until it observes the signal.
+ * @param ctx - the plugin context (injects `subagents`).
+ * @param captain - the exact live captain agent (the member's parent).
+ * @param childId - the member's durable child session id.
+ */
+export declare function interruptMember(ctx: Context, captain: Agent, childId: string): void;
+/**
+ * Snapshot each direct continuable child's activity under the captain's
+ * session, keyed by child session id. A member that is currently running its
+ * turn reports `running`; an idle member reports `inactive`.
+ * @param ctx - the plugin context (injects `subagents`).
+ * @param captainSessionId - the captain's session id.
+ * @returns child id → activity, missing entries are unknown children.
+ */
+export declare function memberActivity(ctx: Context, captainSessionId: string): Promise<Map<string, 'running' | 'inactive'>>;

package/lib/types/snapshot.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 type { Context } from '@deepseek-ai/cordis';
+import type { TeamState } from './types.ts';
+/** Visual task state for the activity panel. */
+export type VisualTaskState = 'blocked' | 'open' | 'running' | 'completed';
+/** One member row of the activity snapshot. */
+export interface TeamActivityMember {
+    readonly id: string;
+    readonly name: string;
+    readonly role: string;
+    readonly activity: 'working' | 'idle' | 'unknown';
+    readonly progress: number;
+    readonly done: number;
+    readonly total: number;
+    readonly currentTask: string;
+    readonly unread: number;
+}
+/** One task row of the activity snapshot. */
+export interface TeamActivityTask {
+    readonly id: string;
+    readonly subject: string;
+    readonly status: string;
+    readonly state: VisualTaskState;
+    readonly assignee: string;
+    readonly dependencies: readonly string[];
+    readonly depth: number;
+}
+/** One captain-inbox preview row. */
+export interface TeamActivityMessage {
+    readonly from: string;
+    readonly content: string;
+}
+/** The full panel payload for one team. */
+export interface TeamActivitySnapshot {
+    readonly workspace: string;
+    readonly teamId: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly captainSessionId: string;
+    readonly members: readonly TeamActivityMember[];
+    readonly tasks: readonly TeamActivityTask[];
+    readonly messageCount: number;
+    readonly captainInbox: readonly TeamActivityMessage[];
+}
+/**
+ * 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 declare function assembleTeamSnapshot(ctx: Context, stateRoot: string, workspace: string, state: TeamState): Promise<TeamActivitySnapshot>;
+/**
+ * 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 declare function collectTeamsActivity(ctx: Context, roots: readonly {
+    workspace: string;
+    stateRoot: string;
+}[]): Promise<TeamActivitySnapshot[]>;
+/**
+ * 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 declare function collectArchivedTeamsActivity(ctx: Context, roots: readonly {
+    workspace: string;
+    stateRoot: string;
+}[]): Promise<TeamActivitySnapshot[]>;