@agent-link/agent 0.1.79 → 0.1.80

package/dist/team.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Agent Team module — manages team state, output stream parsing,
+ * and team lifecycle for multi-agent team mode.
+ *
+ * team.ts is an observer, not an orchestrator: it intercepts the Lead's
+ * output stream to extract UI state (agent list, task board, activity feed)
+ * while the Lead Claude process drives all planning/execution autonomously.
+ */
+export interface TeamConfig {
+    instruction: string;
+    template?: string;
+}
+export interface AgentRole {
+    id: string;
+    name: string;
+    color: string;
+}
+export interface TaskItem {
+    id: string;
+    title: string;
+    description: string;
+    status: 'pending' | 'active' | 'done' | 'failed';
+    assignee: string | null;
+    toolUseId: string | null;
+    agentTaskId: string | null;
+    dependencies: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+export interface TeamState {
+    teamId: string;
+    title: string;
+    config: TeamConfig;
+    conversationId: string;
+    claudeSessionId: string | null;
+    agents: Map<string, AgentTeammate>;
+    tasks: TaskItem[];
+    feed: TeamFeedEntry[];
+    status: 'planning' | 'running' | 'summarizing' | 'completed' | 'failed';
+    leadStatus: string;
+    summary: string | null;
+    totalCost: number;
+    durationMs: number;
+    createdAt: number;
+}
+export interface AgentTeammate {
+    role: AgentRole;
+    toolUseId: string | null;
+    agentTaskId: string | null;
+    status: 'starting' | 'working' | 'done' | 'error';
+    currentTaskId: string | null;
+    messages: TeamAgentMessage[];
+}
+export interface TeamAgentMessage {
+    id: number;
+    role: 'assistant' | 'tool' | 'user';
+    content?: string;
+    toolName?: string;
+    toolInput?: string;
+    toolOutput?: string;
+    hasResult?: boolean;
+    timestamp: number;
+}
+export interface TeamFeedEntry {
+    timestamp: number;
+    agentId: string;
+    type: 'task_started' | 'task_completed' | 'task_failed' | 'tool_call' | 'status_change' | 'lead_activity';
+    content: string;
+}
+export interface TeamStateSerialized {
+    teamId: string;
+    title: string;
+    config: TeamConfig;
+    conversationId: string;
+    claudeSessionId: string | null;
+    agents: Array<{
+        id: string;
+        name: string;
+        color: string;
+        toolUseId: string | null;
+        agentTaskId: string | null;
+        status: string;
+        currentTaskId: string | null;
+        messages?: TeamAgentMessage[];
+    }>;
+    tasks: TaskItem[];
+    feed: TeamFeedEntry[];
+    status: string;
+    leadStatus: string;
+    summary: string | null;
+    totalCost: number;
+    durationMs: number;
+    createdAt: number;
+}
+type SendFn = (msg: Record<string, unknown>) => void;
+type HandleChatFn = (conversationId: string | undefined, prompt: string, workDir: string, options?: {
+    resumeSessionId?: string;
+    extraArgs?: string[];
+}) => void;
+type CancelExecutionFn = (conversationId?: string) => void;
+type SetOutputObserverFn = (fn: (conversationId: string, msg: Record<string, unknown>) => boolean | void) => void;
+type ClearOutputObserverFn = () => void;
+type SetCloseObserverFn = (fn: (conversationId: string, exitCode: number | null, resultReceived: boolean) => void) => void;
+type ClearCloseObserverFn = () => void;
+export declare function setTeamSendFn(fn: SendFn): void;
+/**
+ * Inject claude.ts dependencies to avoid circular imports.
+ * Called once during agent startup from connection.ts.
+ */
+export declare function setTeamClaudeFns(fns: {
+    handleChat: HandleChatFn;
+    cancelExecution: CancelExecutionFn;
+    setOutputObserver: SetOutputObserverFn;
+    clearOutputObserver: ClearOutputObserverFn;
+    setCloseObserver: SetCloseObserverFn;
+    clearCloseObserver: ClearCloseObserverFn;
+}): void;
+export declare function getActiveTeam(): TeamState | null;
+export declare function getLastCompletedTeamId(): string | null;
+/**
+ * Create a new team. Returns the TeamState.
+ * Does NOT start the Lead process — the caller (team lifecycle functions) does that.
+ */
+export declare function createTeamState(config: TeamConfig, conversationId: string): TeamState;
+/**
+ * Clear the active team (used on dissolve/complete).
+ */
+export declare function clearActiveTeam(): void;
+/**
+ * Get the next color for an agent (based on current count).
+ */
+export declare function getNextAgentColor(team: TeamState): string;
+/**
+ * Register a subagent when Lead calls the Agent tool.
+ */
+export declare function registerSubagent(team: TeamState, toolUseId: string, input: {
+    name?: string;
+    description?: string;
+    prompt?: string;
+}): AgentTeammate;
+/**
+ * Link a subagent's task_started system message to its tool_use_id.
+ */
+export declare function linkSubagentTaskId(team: TeamState, toolUseId: string, taskId: string): AgentTeammate | null;
+/**
+ * Find agent by toolUseId (parent_tool_use_id).
+ */
+export declare function findAgentByToolUseId(team: TeamState, toolUseId: string): AgentTeammate | null;
+/**
+ * Find agent by agentTaskId (task_id from system.task_started).
+ */
+export declare function findAgentByTaskId(team: TeamState, agentTaskId: string): AgentTeammate | null;
+/**
+ * Add a message to an agent's message list.
+ */
+export declare function addAgentMessage(agent: AgentTeammate, role: 'assistant' | 'tool' | 'user', fields: Partial<Omit<TeamAgentMessage, 'id' | 'role' | 'timestamp'>>): TeamAgentMessage;
+/**
+ * Add an entry to the team's activity feed.
+ */
+export declare function addFeedEntry(team: TeamState, agentId: string, type: TeamFeedEntry['type'], content: string): TeamFeedEntry;
+/**
+ * Mark a task as done/failed.
+ */
+export declare function updateTaskStatus(team: TeamState, taskId: string, status: 'done' | 'failed'): TaskItem | null;
+/**
+ * Check if all subagent tasks are completed.
+ */
+export declare function allSubagentsDone(team: TeamState): boolean;
+/**
+ * Serialize TeamState for persistence/transmission (Map → array).
+ */
+export declare function serializeTeam(team: TeamState, includeMessages?: boolean): TeamStateSerialized;
+/**
+ * Persist team state to disk (atomic write: tmp → rename).
+ */
+export declare function persistTeam(team: TeamState): void;
+/**
+ * Debounced persist — coalesces rapid state changes into a single write.
+ * Flushes after 500ms of quiet.
+ */
+export declare function persistTeamDebounced(team: TeamState): void;
+/**
+ * Flush all pending debounced persists immediately.
+ */
+export declare function flushPendingPersists(): void;
+/**
+ * Load a team from disk by teamId.
+ */
+export declare function loadTeam(teamId: string): TeamState | null;
+/**
+ * Summary info for listing teams.
+ */
+export interface TeamSummaryInfo {
+    teamId: string;
+    title: string;
+    status: string;
+    template: string | undefined;
+    agentCount: number;
+    taskCount: number;
+    totalCost: number;
+    createdAt: number;
+}
+/**
+ * List all persisted teams, sorted by createdAt descending (newest first).
+ */
+export declare function listTeams(): TeamSummaryInfo[];
+/**
+ * Delete a persisted team file.
+ */
+export declare function deleteTeam(teamId: string): boolean;
+interface AgentDef {
+    description: string;
+    prompt: string;
+    tools: string[];
+}
+type AgentsDefMap = Record<string, AgentDef>;
+/**
+ * Build the agents definition JSON for the --agents CLI flag.
+ */
+export declare function buildAgentsDef(template?: string): AgentsDefMap;
+/**
+ * Build the lead prompt that instructs the Lead to use Agent tool.
+ */
+export declare function buildLeadPrompt(config: TeamConfig, agentsDef: AgentsDefMap): string;
+/**
+ * Output observer callback for the Lead's stdout stream.
+ * Registered via setOutputObserver() when a team is active.
+ * Returns true to suppress the message from normal web client forwarding.
+ */
+export declare function onLeadOutput(conversationId: string, msg: Record<string, unknown>): boolean;
+/**
+ * Close observer callback for the Lead's process exit.
+ * Detects Lead crash (process exited without a result message) and dissolves the team.
+ */
+export declare function onLeadClose(conversationId: string, _exitCode: number | null, resultReceived: boolean): void;
+/**
+ * Create and launch a team. Returns the TeamState.
+ * Spawns the Lead Claude process with --agents flag and attaches the output observer.
+ */
+export declare function createTeam(config: TeamConfig, workDir: string): TeamState;
+/**
+ * Dissolve (cancel) the active team.
+ */
+export declare function dissolveTeam(): void;
+/**
+ * Called when the Lead's result message arrives (from onLeadOutput).
+ * Marks the team as completed, persists state, and notifies clients.
+ */
+export declare function completeTeam(summary?: string): void;
+export {};