feat(runtime): star orchestrator→worker expert teams by jackwener · Pull Request #971 · apache/maka

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx

jackwener · 2026-07-14T08:39:20Z

What

Implements expert teams — a lead persona fans a task out to tool-scoped member experts (child agents) and synthesizes their results. This is the star orchestrator→worker topology reverse-engineered from WorkBuddy's team experts and QoderWork's sub-agent pipelines (see docs/expert-team-implementation.md), rebuilt entirely on Maka's existing child-agent machinery — no new orchestration engine, no mesh mailbox, no shared task board.

Model

Capability archetype — a built-in agent profile (local_read / web_research / implementation) fixing tool scope + permission mode + category policy.
Expert — a persona that runs under an archetype and may narrow (never widen) its tools. An expert can never exceed its archetype's policy → stricter than either competitor, preserves Maka's permission-safety invariant.
Expert team — a lead (runs as the main session) + N dispatchable members. Members never talk to each other; the lead coordinates.

Members materialize into ordinary AgentDefinitions with a deterministic id expert:<teamId>:<memberId>, so the child-turn machinery (tool scoping, permission gating, worktree fail-closed) runs them unchanged and a spawn resolves statelessly from the id.

Changes

@maka/runtime

expert-catalog.ts — types, materialization, static registry, combined resolver, and the built-in Code Review Team (read-only correctness / simplification / test-coverage reviewers).
expert-tools.ts — the team-bound expert_dispatch tool (member enum + roster). Parallel fan-out reuses the existing per-turn subagent concurrency; fan-in is the child summary + artifactIds pointers.
Pluggable resolver: spawnChildAgent / startChildTurn now resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving built-in error messages.

@maka/core

expert-team.ts — the mode:expert-team:<teamId> session-label vocabulary.

Desktop

Lead system-prompt fragment + expert_dispatch tool, gated on the label (main session only — members never get nested teams).
expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session.

How to use

const{ teams }=awaitwindow.maka.expertTeam.list();constr=awaitwindow.maka.expertTeam.start({teamId: 'code-review',prompt: 'Review the current diff.'});

Any session labeled mode:expert-team:<teamId> is a fully functional team lead — the label is the only special state.

Tests

New unit tests across core / runtime / desktop-main. Verified locally:

@maka/core 824/824 · @maka/runtime 1383 (0 fail) · @maka/headless 807/807 · desktop-main handler + quick-chat 28/28.
Full ordered npm run build passes (incl. desktop main + preload + renderer); desktop typecheck clean.

Note: ~193 desktop "source-grep / Storybook / real-window" contract tests fail only in a nested git-worktree checkout (they resolve the repo root to .claude/packages/... and ENOENT); they are unrelated to this change and pass in a normal checkout / CI.

Deliberately deferred (documented, not built)

Renderer team-picker panel; mesh "Agent Teams" (member↔member messaging, shared task board); worktree-isolated writing members (fail-closed today); remote expert marketplace; digital-colleague / IM / cloud layer. Design + rationale in docs/expert-team-{plan,implementation,runtime}.md.

Expert teams let a lead persona fan a task out to tool-scoped member experts (child agents), then synthesize their results — the star topology reverse-engineered from WorkBuddy's `team` experts and QoderWork's sub-agent pipelines, rebuilt entirely on Maka's existing child-agent machinery (no new orchestration engine, no mesh mailbox). Runtime (@maka/runtime): - expert-catalog.ts: ExpertDefinition / ExpertTeamDefinition, data-driven members that inherit a capability archetype (tool scope + permission mode) and may only narrow its tools — never widen. Members materialize into ordinary AgentDefinitions with a deterministic id (expert:<teamId>:<memberId>) so the child-turn machinery runs them unchanged and a spawn resolves statelessly from the id. - expert-tools.ts: the team-bound `expert_dispatch` tool (member enum + roster), a thin wrapper over spawnChildAgent; parallel fan-out reuses the existing per-turn concurrency; fan-in is the child summary + artifact-id pointers. - Pluggable definition resolver: spawnChildAgent / startChildTurn resolve a spec id via requireResolvedAgentDefinition (builtin ?? expert), preserving builtin error messages. - Ships a read-only Code Review Team (correctness / simplification / test-coverage reviewers) that runs within current capabilities. Core (@maka/core): - expert-team.ts: the `mode:expert-team:<teamId>` session-label vocabulary. Desktop: - Lead system-prompt fragment + `expert_dispatch` tool gated on the label (main session only — members never get nested teams). - expertTeam:list / expertTeam:start IPC + preload bridge + window typings to start a read-only team session. Tests across core / runtime / desktop-main. Docs in docs/expert-team-*.md.

The composer "+" button attached files directly. Turn it into a small menu (reusing the existing Menu primitive, same as the workspace/branch pickers): - 添加文件或目录 → the existing attachment picker. - 专家团 → a submenu listing the built-in expert teams; picking one starts a new `mode:expert-team:<teamId>` session (read-only), mirroring the quick-chat start+navigate flow. Wiring: Composer gains `expertTeams` + `onStartExpertTeam` props; app-shell loads window.maka.expertTeam.list() once and routes selection through a new handleExpertTeamStart action. The "+" trigger renders whenever attachments or teams are available. Storybook chat-surface exercises the menu.

End-to-end integration test: startChildTurn with an `expert:<team>:<member>` spec id resolves through requireResolvedAgentDefinition into the materialized member definition — asserting the child backend receives the archetype-scoped tools (Read/Glob/Grep), the composed persona system prompt, explore permission mode, and the expert id/name on the child run. Closes the one integration seam the unit tests could not cover.

…ad code - Correctness: the lead persona fragment was injected into every dispatched member (child turns inherit the session's expert-team label). Gate the lead fragment on `forChildTurn` so members no longer get "you are the lead, use expert_dispatch" for a tool they don't have. (The tool itself was already withheld from children.) - getExpertAgentDefinition now honors its `| undefined` contract: a member that would throw on materialization (tool-widening) resolves to undefined instead of throwing through resolveAgentDefinition. - Remove dead exports flagged for knip: buildExpertToolGroup / EXPERT_TOOL_GROUP_ID (expert_dispatch is added directly, not via a deferred group), getExpertTeamMember (no callers), and un-export the internal composeExpertSystemPrompt.

…4febe7 # Conflicts: # apps/desktop/src/main/main.ts # packages/ui/src/composer.tsx