Skip to content

Commit 2aff4ac

Browse files
JeremyDev87JeremyDev87
committed
feat(mcp): expose nested execution metadata in parse_mode (#1312)
Add executionPlan and teamsCapability fields to ParseModeResult. ModeHandler now injects TeamsCapabilityService, builds an ExecutionPlan from dispatchReady agents, and includes Teams runtime capability status in the parse_mode response. Nested plan (subagent+teams) is built when Teams coordination is enabled. All new fields are optional for backward compatibility.
1 parent 4177533 commit 2aff4ac

9 files changed

Lines changed: 441 additions & 152 deletions

File tree

‎apps/mcp-server/src/agent/agent.types.ts‎

Lines changed: 29 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
1-
import type { Mode } from '../keyword/keyword.types';
1+
// Mode is defined in keyword.types but importing it directly creates a circular dependency
2+
// (agent.types → keyword.types → execution-plan.types ← agent.types via re-export).
3+
// Local alias breaks the cycle while preserving type safety.
4+
type Mode = 'PLAN' | 'ACT' | 'EVAL' | 'AUTO';
5+
6+
import type {
7+
DispatchedAgent,
8+
TaskmaestroDispatch,
9+
TeamsDispatch,
10+
VisibilityConfig,
11+
ExecutionPlan,
12+
} from './execution-plan.types';
213

314
/**
415
* Agent Stack - a pre-configured team of agents for common workflows
@@ -69,156 +80,23 @@ export interface ParallelAgentSet {
6980
failedAgents?: FailedAgent[];
7081
}
7182

72-
/**
73-
* Dispatch parameters for a single agent, ready to use with Claude Code Task tool
74-
*/
75-
export interface DispatchParams {
76-
subagent_type: 'general-purpose';
77-
prompt: string;
78-
description: string;
79-
run_in_background?: true;
80-
}
81-
82-
/**
83-
* A dispatched agent with metadata and Task-tool-ready parameters
84-
*/
85-
export interface DispatchedAgent {
86-
name: string;
87-
displayName: string;
88-
description: string;
89-
dispatchParams: DispatchParams;
90-
}
91-
92-
/**
93-
* Inner Teams coordination metadata embedded in a TaskMaestro pane assignment.
94-
* Present only when the composable `taskmaestro+teams` strategy is active
95-
* and the Teams capability gate is enabled.
96-
*/
97-
export interface InnerTeamsSpec {
98-
type: 'teams';
99-
teamSpec: {
100-
team_name: string;
101-
description: string;
102-
};
103-
teammates: Array<{
104-
name: string;
105-
subagent_type: 'general-purpose';
106-
}>;
107-
}
108-
109-
/**
110-
* A single TaskMaestro pane assignment with agent name and prompt.
111-
* When the composable `taskmaestro+teams` strategy is active,
112-
* `innerCoordination` carries the metadata a pane worker needs
113-
* to bootstrap its inner Teams workflow.
114-
*/
115-
export interface TaskmaestroAssignment {
116-
name: string;
117-
displayName: string;
118-
prompt: string;
119-
/** Inner coordination metadata for composable taskmaestro+teams execution */
120-
innerCoordination?: InnerTeamsSpec;
121-
}
122-
123-
/**
124-
* TaskMaestro dispatch configuration for parallel tmux pane execution
125-
*/
126-
export interface TaskmaestroDispatch {
127-
sessionName: string;
128-
paneCount: number;
129-
assignments: TaskmaestroAssignment[];
130-
}
131-
132-
/**
133-
* A single teammate in a Teams dispatch configuration
134-
*/
135-
export interface TeamsTeammate {
136-
name: string;
137-
subagent_type: 'general-purpose';
138-
team_name: string;
139-
prompt: string;
140-
}
141-
142-
/**
143-
* Teams dispatch configuration for Claude Code native team coordination
144-
*/
145-
export interface TeamsDispatch {
146-
team_name: string;
147-
description: string;
148-
teammates: TeamsTeammate[];
149-
}
150-
151-
/**
152-
* SendMessage-based progress reporting instructions for specialist visibility
153-
*/
154-
export interface VisibilityMessages {
155-
onStart: string;
156-
onFinding: string;
157-
onComplete: string;
158-
}
159-
160-
/**
161-
* Configuration for real-time specialist execution visibility via Teams messaging
162-
*/
163-
export interface VisibilityConfig {
164-
reportTo: string;
165-
format: string;
166-
includeProgress: boolean;
167-
messages?: VisibilityMessages;
168-
}
169-
170-
/**
171-
* Execution layer: subagent strategy
172-
*/
173-
export interface SubagentLayer {
174-
type: 'subagent';
175-
agents: DispatchedAgent[];
176-
}
177-
178-
/**
179-
* Execution layer: TaskMaestro tmux-based transport
180-
*/
181-
export interface TaskmaestroLayer {
182-
type: 'taskmaestro';
183-
config: TaskmaestroDispatch;
184-
}
185-
186-
/**
187-
* Execution layer: Claude Code native Teams coordination
188-
*/
189-
export interface TeamsLayer {
190-
type: 'teams';
191-
config: TeamsDispatch;
192-
visibility?: VisibilityConfig;
193-
}
194-
195-
/**
196-
* Discriminated union of all execution layer types.
197-
* Each layer represents a single execution strategy.
198-
*/
199-
export type ExecutionLayer = SubagentLayer | TaskmaestroLayer | TeamsLayer;
200-
201-
/**
202-
* Composable execution plan with outer transport and optional inner coordination.
203-
*
204-
* Simple plan: outerExecution only (e.g. subagent, taskmaestro, or teams)
205-
* Nested plan: outerExecution + innerCoordination (e.g. taskmaestro + teams)
206-
*
207-
* @example
208-
* // Simple subagent plan
209-
* { outerExecution: { type: 'subagent', agents: [...] } }
210-
*
211-
* @example
212-
* // Nested: TaskMaestro as transport, Teams as coordination
213-
* {
214-
* outerExecution: { type: 'taskmaestro', config: {...} },
215-
* innerCoordination: { type: 'teams', config: {...} }
216-
* }
217-
*/
218-
export interface ExecutionPlan {
219-
outerExecution: ExecutionLayer;
220-
innerCoordination?: ExecutionLayer;
221-
}
83+
// Re-export execution plan types from dedicated file (avoids circular dep with keyword.types)
84+
export type {
85+
DispatchParams,
86+
DispatchedAgent,
87+
InnerTeamsSpec,
88+
TaskmaestroAssignment,
89+
TaskmaestroDispatch,
90+
TeamsTeammate,
91+
TeamsDispatch,
92+
VisibilityMessages,
93+
VisibilityConfig,
94+
SubagentLayer,
95+
TaskmaestroLayer,
96+
TeamsLayer,
97+
ExecutionLayer,
98+
ExecutionPlan,
99+
} from './execution-plan.types';
222100

223101
/**
224102
* Result of dispatching agents for execution

‎apps/mcp-server/src/agent/execution-plan.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import type {
55
TaskmaestroDispatch,
66
TeamsDispatch,
77
VisibilityConfig,
8-
} from './agent.types';
8+
} from './execution-plan.types';
99

1010
/**
1111
* Build a single-layer execution plan.

‎apps/mcp-server/src/agent/execution-plan.types.ts‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
/**
2+
* Execution plan types extracted from agent.types.ts to break the
3+
* circular dependency: agent.types → keyword.types → agent.types.
4+
*
5+
* These types are consumed by keyword.types.ts (ParseModeResult) and
6+
* re-exported from agent.types.ts for backward compatibility.
7+
*/
8+
9+
/**
10+
* Dispatch parameters for a single agent, ready to use with Claude Code Task tool
11+
*/
12+
export interface DispatchParams {
13+
subagent_type: 'general-purpose';
14+
prompt: string;
15+
description: string;
16+
run_in_background?: true;
17+
}
18+
19+
/**
20+
* A dispatched agent with metadata and Task-tool-ready parameters
21+
*/
22+
export interface DispatchedAgent {
23+
name: string;
24+
displayName: string;
25+
description: string;
26+
dispatchParams: DispatchParams;
27+
}
28+
29+
/**
30+
* Inner Teams coordination metadata embedded in a TaskMaestro pane assignment.
31+
* Present only when the composable `taskmaestro+teams` strategy is active
32+
* and the Teams capability gate is enabled.
33+
*/
34+
export interface InnerTeamsSpec {
35+
type: 'teams';
36+
teamSpec: {
37+
team_name: string;
38+
description: string;
39+
};
40+
teammates: Array<{
41+
name: string;
42+
subagent_type: 'general-purpose';
43+
}>;
44+
}
45+
46+
/**
47+
* A single TaskMaestro pane assignment with agent name and prompt.
48+
* When the composable `taskmaestro+teams` strategy is active,
49+
* `innerCoordination` carries the metadata a pane worker needs
50+
* to bootstrap its inner Teams workflow.
51+
*/
52+
export interface TaskmaestroAssignment {
53+
name: string;
54+
displayName: string;
55+
prompt: string;
56+
/** Inner coordination metadata for composable taskmaestro+teams execution */
57+
innerCoordination?: InnerTeamsSpec;
58+
}
59+
60+
/**
61+
* TaskMaestro dispatch configuration for parallel tmux pane execution
62+
*/
63+
export interface TaskmaestroDispatch {
64+
sessionName: string;
65+
paneCount: number;
66+
assignments: TaskmaestroAssignment[];
67+
}
68+
69+
/**
70+
* A single teammate in a Teams dispatch configuration
71+
*/
72+
export interface TeamsTeammate {
73+
name: string;
74+
subagent_type: 'general-purpose';
75+
team_name: string;
76+
prompt: string;
77+
}
78+
79+
/**
80+
* Teams dispatch configuration for Claude Code native team coordination
81+
*/
82+
export interface TeamsDispatch {
83+
team_name: string;
84+
description: string;
85+
teammates: TeamsTeammate[];
86+
}
87+
88+
/**
89+
* SendMessage-based progress reporting instructions for specialist visibility
90+
*/
91+
export interface VisibilityMessages {
92+
onStart: string;
93+
onFinding: string;
94+
onComplete: string;
95+
}
96+
97+
/**
98+
* Configuration for real-time specialist execution visibility via Teams messaging
99+
*/
100+
export interface VisibilityConfig {
101+
reportTo: string;
102+
format: string;
103+
includeProgress: boolean;
104+
messages?: VisibilityMessages;
105+
}
106+
107+
/**
108+
* Execution layer: subagent strategy
109+
*/
110+
export interface SubagentLayer {
111+
type: 'subagent';
112+
agents: DispatchedAgent[];
113+
}
114+
115+
/**
116+
* Execution layer: TaskMaestro tmux-based transport
117+
*/
118+
export interface TaskmaestroLayer {
119+
type: 'taskmaestro';
120+
config: TaskmaestroDispatch;
121+
}
122+
123+
/**
124+
* Execution layer: Claude Code native Teams coordination
125+
*/
126+
export interface TeamsLayer {
127+
type: 'teams';
128+
config: TeamsDispatch;
129+
visibility?: VisibilityConfig;
130+
}
131+
132+
/**
133+
* Discriminated union of all execution layer types.
134+
* Each layer represents a single execution strategy.
135+
*/
136+
export type ExecutionLayer = SubagentLayer | TaskmaestroLayer | TeamsLayer;
137+
138+
/**
139+
* Composable execution plan with outer transport and optional inner coordination.
140+
*
141+
* Simple plan: outerExecution only (e.g. subagent, taskmaestro, or teams)
142+
* Nested plan: outerExecution + innerCoordination (e.g. taskmaestro + teams)
143+
*
144+
* @example
145+
* // Simple subagent plan
146+
* { outerExecution: { type: 'subagent', agents: [...] } }
147+
*
148+
* @example
149+
* // Nested: TaskMaestro as transport, Teams as coordination
150+
* {
151+
* outerExecution: { type: 'taskmaestro', config: {...} },
152+
* innerCoordination: { type: 'teams', config: {...} }
153+
* }
154+
*/
155+
export interface ExecutionPlan {
156+
outerExecution: ExecutionLayer;
157+
innerCoordination?: ExecutionLayer;
158+
}

‎apps/mcp-server/src/agent/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ export * from './agent-prompt.builder';
99
export * from './agent-stack.schema';
1010
export * from './agent-stack.loader';
1111
export * from './execution-plan';
12+
export * from './execution-plan.types';

‎apps/mcp-server/src/keyword/keyword.types.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import type { DiffAnalysisResult } from './diff-analyzer';
22
import type { CouncilPreset } from '../agent/council-preset.types';
33
import type { CouncilSummary } from '../collaboration/council-summary.types';
4+
import type { ExecutionPlan } from '../agent/execution-plan.types';
5+
import type { TeamsCapabilityStatus } from '../agent/teams-capability.types';
46

57
export const KEYWORDS = ['PLAN', 'ACT', 'EVAL', 'AUTO'] as const;
68

@@ -523,6 +525,18 @@ export interface ParseModeResult {
523525
* Clients should treat this as read-only diagnostic data.
524526
*/
525527
councilSummary?: CouncilSummary;
528+
/**
529+
* @apiProperty External API - do not rename.
530+
* Describes the outer execution transport and optional inner coordination layer.
531+
* Built from the composable execution model (#1309). Present when dispatch is active.
532+
*/
533+
executionPlan?: ExecutionPlan;
534+
/**
535+
* @apiProperty External API - do not rename.
536+
* Runtime capability status for Teams coordination.
537+
* Reflects environment, config, or default gating from TeamsCapabilityService (#1311).
538+
*/
539+
teamsCapability?: TeamsCapabilityStatus;
526540
}
527541

528542
/**

0 commit comments

Comments
 (0)