feat(agents): parameterized agent selection via agentName by dimakis · Pull Request #349 · dimakis/mitzo

dimakis · 2026-05-21T10:07:21Z

Summary

Add full protocol support for entry-point-specific agent selection, plus UI integration for Telos and Calendar entry points.

Flow:

Client passes agentName in send message options
Server sets MITZO_AGENT_NAME env var
Harness hook reads env var and requests agent-specific boot context
ContexGin compiles context per agent definition

Changes

Protocol:

packages/protocol/src/ws-schemas-v2.ts — add agentName to V2SendMessage

Server:

server/ws-handler-v2.ts — pass agentName to startChat()
server/chat.ts — set MITZO_AGENT_NAME env var, use in recipe lookup
packages/harness/src/session-registry.ts — add agentName to ManagedSession

Client:

packages/client/src/store.ts — add agentName to SendMessageOptions and PendingSession
frontend/src/pages/ChatView.tsx — forward agentName from pending session

UI Integration:

frontend/src/pages/TodoView.tsx — Telos tasks use mitzo-telos agent ✅
frontend/src/components/EventCard.tsx — "Prep for this meeting" button ✅
frontend/src/lib/calendar-utils.ts — meeting prep prompt and context builders ✅
frontend/src/styles/calendar.css — action button styles ✅

Behavior

Defaults to 'mitzo-conversational' when not specified
Telos-initiated sessions automatically use mitzo-telos agent
Calendar meetings have "Prep for this meeting" button → mitzo-calendar agent
All existing sessions continue to use default agent

Next Steps

✅ Wire Telos entry point → Done
✅ Wire Calendar entry point → Done
⏳ Create additional agent definitions as needed (e.g., mitzo-pr-review, mitzo-email)

Companion PR: dimakis/mgmt#127

Test Plan

Protocol compiles
Types are correct
Defaults to mitzo-conversational
Telos sessions pass agentName: 'mitzo-telos'
Calendar events show prep button
Prep button navigates to chat with agentName: 'mitzo-calendar'
CI passes
Manual test: Telos task → verify boot context shows Telos-specific content
Manual test: Calendar prep → verify boot context shows calendar-specific content

🤖 Generated with Claude Code

Add full protocol support for entry-point-specific agent selection. **Flow:** 1. Client passes agentName in send message options 2. Server sets MITZO_AGENT_NAME env var 3. Harness hook reads env var and requests agent-specific boot context 4. ContexGin compiles context per agent definition **Changes:** - packages/protocol/src/ws-schemas-v2.ts — add agentName to V2SendMessage - server/ws-handler-v2.ts — pass agentName to startChat() - server/chat.ts — set MITZO_AGENT_NAME env var, use in recipe lookup - packages/harness/src/session-registry.ts — add agentName to ManagedSession - packages/client/src/store.ts — add agentName to SendMessageOptions/PendingSession - frontend/src/pages/ChatView.tsx — forward agentName from pending session Defaults to 'mitzo-conversational' when not specified. Enables future UI entry points (Telos, calendar) to request specialized agents. Companion PR: mgmt#<number> Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Wire TodoView to pass agentName: 'mitzo-telos' when starting a session from a Telos task. This triggers the specialized Telos agent with task-specific context blocks and governance. Calendar integration not yet implemented (CalendarView is read-only). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

dimakis

Centaur Review

Found 5 issue(s) (1 critical) (3 warning).

`server/chat.ts`

The core plumbing is clean and follows the established telosTaskId pattern, but the user-controlled agentName is used in file path construction (join(cwd, '.agents', agentName + '.yaml')) without any validation — this is a path traversal vulnerability that needs a format constraint at the protocol schema level.

🔴 unsafe_assumptions (L781): Path traversal vulnerability: agentName originates from unauthenticated WebSocket input (z.string().optional() — no format constraint) and is interpolated directly into a file path: join(cwd, '.agents', \${agentName}.yaml`). A malicious client can send agentName: '../../etc/passwd'to read arbitrary YAML-parseable files. The try-catch silences failures butloadAgentDefinitionmay still parse and return data from out-of-bounds paths. Add a Zod regex constraint (e.g.,z.string().regex(/^[a-zA-Z0-9_-]+$/)) in ws-schemas-v2.tsor validate withpath.basename()before constructingrecipePath. [fixable]`
🟡 unsafe_assumptions (L729): agentName is also injected into the process environment as MITZO_AGENT_NAME without sanitization. While less dangerous than the path traversal, an attacker-controlled env var value containing special characters could affect downstream shell commands or child processes that read this variable. [fixable]
🟡 missing_tests (L781): No test coverage for the agentName parameter. The existing ws-handler-v2.test.ts (2745 lines) has no agentName tests. At minimum: (1) verify agentName is forwarded from WS message to startChat, (2) verify the default fallback to mitzo-conversational, (3) verify path traversal attempts are rejected. [fixable]
🔵 style (L728): The default agent name 'mitzo-conversational' is a magic string. Consider extracting it to constants.ts (where other server-wide defaults live) since it appears in an env var assignment and a file path construction — a single source of truth prevents drift. [fixable]

`packages/harness/src/session-registry.ts`

The core plumbing is clean and follows the established telosTaskId pattern, but the user-controlled agentName is used in file path construction (join(cwd, '.agents', agentName + '.yaml')) without any validation — this is a path traversal vulnerability that needs a format constraint at the protocol schema level.

🟡 regressions (L50): agentName is added to the ManagedSession interface and stored at registration (chat.ts:682), but is never read back anywhere in the codebase (session.agentName has zero grep hits). This is dead metadata — either it should be consumed (e.g., for session restore, reattach, or auditing) or removed from the interface to avoid confusion. [fixable]

dimakis · 2026-05-21T10:09:49Z

    try {
      if (compileModule.loadAgentDefinition) {
-        const recipePath = join(cwd, '.agents', 'mitzo-conversational.yaml');
+        const recipePath = join(cwd, '.agents', `${agentName}.yaml`);


🔴 unsafe_assumptions: Path traversal vulnerability: agentName originates from unauthenticated WebSocket input (z.string().optional() — no format constraint) and is interpolated directly into a file path: join(cwd, '.agents', \${agentName}.yaml`). A malicious client can send agentName: '../../etc/passwd'to read arbitrary YAML-parseable files. The try-catch silences failures butloadAgentDefinitionmay still parse and return data from out-of-bounds paths. Add a Zod regex constraint (e.g.,z.string().regex(/^[a-zA-Z0-9_-]+$/)) in ws-schemas-v2.tsor validate withpath.basename()before constructingrecipePath. [fixable]`

dimakis · 2026-05-21T10:09:49Z

  const sessionEnv = sdkEnv();
  sessionEnv.MITZO_SESSION_ID = wtId;
+  const agentName = options.agentName || 'mitzo-conversational';
+  sessionEnv.MITZO_AGENT_NAME = agentName;


🟡 unsafe_assumptions: agentName is also injected into the process environment as MITZO_AGENT_NAME without sanitization. While less dangerous than the path traversal, an attacker-controlled env var value containing special characters could affect downstream shell commands or child processes that read this variable. [fixable]

dimakis · 2026-05-21T10:09:49Z

    try {
      if (compileModule.loadAgentDefinition) {
-        const recipePath = join(cwd, '.agents', 'mitzo-conversational.yaml');
+        const recipePath = join(cwd, '.agents', `${agentName}.yaml`);


🟡 missing_tests: No test coverage for the agentName parameter. The existing ws-handler-v2.test.ts (2745 lines) has no agentName tests. At minimum: (1) verify agentName is forwarded from WS message to startChat, (2) verify the default fallback to mitzo-conversational, (3) verify path traversal attempts are rejected. [fixable]

dimakis · 2026-05-21T10:09:49Z

  // Build session env with worktree paths for the agent (all repos including primary)
  const sessionEnv = sdkEnv();
  sessionEnv.MITZO_SESSION_ID = wtId;
+  const agentName = options.agentName || 'mitzo-conversational';


🔵 style: The default agent name 'mitzo-conversational' is a magic string. Consider extracting it to constants.ts (where other server-wide defaults live) since it appears in an env var assignment and a file path construction — a single source of truth prevents drift. [fixable]

dimakis · 2026-05-21T10:09:49Z

  /** Active subagent task IDs — task_id → tool_use_id (parent_tool_use_id). */
  activeTaskIds: Map<string, string>;
+  /** Agent definition name for ContexGin boot context (e.g., mitzo-conversational, mitzo-telos). */
+  agentName?: string;


🟡 regressions: agentName is added to the ManagedSession interface and stored at registration (chat.ts:682), but is never read back anywhere in the codebase (session.agentName has zero grep hits). This is dead metadata — either it should be consumed (e.g., for session restore, reattach, or auditing) or removed from the interface to avoid confusion. [fixable]

Add "Prep for this meeting" button to calendar event cards. Clicking initiates a session with the mitzo-calendar agent and pre-populated meeting context. **Changes:** - EventCard.tsx — add prep button + navigation handler - calendar-utils.ts — prompt and context builders for meeting prep - calendar.css — styles for action button **Flow:** 1. User taps event to expand 2. Clicks "Prep for this meeting" 3. Session starts with mitzo-calendar agent 4. Context includes attendees, time, doc links Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

**Security fixes:** - Add regex validation to agentName (/^[a-zA-Z0-9_-]+$/) - prevents path traversal - Extract DEFAULT_AGENT_NAME constant to avoid magic strings **Changes:** - packages/protocol/src/ws-schemas-v2.ts - add regex constraint to agentName - server/constants.ts - add DEFAULT_AGENT_NAME constant - server/chat.ts - use constant instead of magic string Addresses Centaur review findings (critical + style issues). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Remove unused session.agentName field from ManagedSession interface - Add comprehensive test coverage for agentName parameter (4 tests) - Test forwarding to startChat - Test default behavior when omitted - Test path traversal rejection via schema validation - Test valid agent name patterns - Replace require() with ES6 import for @mitzo/protocol in tests All tests passing (109/109). Addresses all red/yellow/style issues from Centaur review on PR #349. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

dimakis · 2026-05-22T11:24:30Z

centaur review

dimakis · 2026-05-22T13:14:33Z

/centaur review

dimakis

Centaur Review

Found 5 issue(s) (1 critical) (1 warning).

`vitest.setup.ts`

Core agentName plumbing is solid with proper Zod regex validation preventing path traversal. Main issues: vitest.setup.ts is dead code (not wired into config), and the new calendar-utils module lacks the TDD-mandated test file.

🔴 bugs (L1): vitest.setup.ts is created but never wired into vitest.config.ts. Without setupFiles: ['./vitest.setup.ts'] in the test config, the EventSource mock is dead code and any test relying on it will fail with a ReferenceError. [fixable]

`frontend/src/lib/calendar-utils.ts`

Core agentName plumbing is solid with proper Zod regex validation preventing path traversal. Main issues: vitest.setup.ts is dead code (not wired into config), and the new calendar-utils module lacks the TDD-mandated test file.

🟡 missing_tests: New pure utility file with three functions (buildMeetingPrepPrompt, buildMeetingContext, formatEventTime) has no test file. These are easily unit-testable and the project mandates TDD — tests should be the first artifact. [fixable]
🔵 style (L6): Multi-line JSDoc comments on buildMeetingPrepPrompt and buildMeetingContext restate what the function name already says. CLAUDE.md says 'default to writing no comments' and 'don't explain WHAT the code does'. Remove the doc blocks. [fixable]

`server/chat.ts`

Core agentName plumbing is solid with proper Zod regex validation preventing path traversal. Main issues: vitest.setup.ts is dead code (not wired into config), and the new calendar-utils module lacks the TDD-mandated test file.

🔵 unsafe_assumptions (L728): options.agentName || DEFAULT_AGENT_NAME treats empty string as falsy and falls back to the default. This is fine behavior-wise, but ?? would be more intentional since Zod's regex already rejects empty strings — using || obscures whether empty-string fallback is deliberate. [fixable]

`frontend/src/pages/TodoView.tsx`

Core agentName plumbing is solid with proper Zod regex validation preventing path traversal. Main issues: vitest.setup.ts is dead code (not wired into config), and the new calendar-utils module lacks the TDD-mandated test file.

🔵 regressions (L191): Adding telosTaskId: item.id is a behavioral change unrelated to the agentName feature — previously TodoView did not set telosTaskId on the pending session. If this was already handled elsewhere (e.g. by ChatView or the store), this could cause duplicate assignment. Confirm this is intentional and not already set by another path.

dimakis · 2026-05-22T13:19:00Z

@@ -0,0 +1,23 @@
+/**


🔴 bugs: vitest.setup.ts is created but never wired into vitest.config.ts. Without setupFiles: ['./vitest.setup.ts'] in the test config, the EventSource mock is dead code and any test relying on it will fail with a ReferenceError. [fixable]

dimakis · 2026-05-22T13:19:00Z

+/**
+ * Build a meeting prep prompt for calendar events.
+ */
+export function buildMeetingPrepPrompt(event: CalendarEvent): string {


🔵 style: Multi-line JSDoc comments on buildMeetingPrepPrompt and buildMeetingContext restate what the function name already says. CLAUDE.md says 'default to writing no comments' and 'don't explain WHAT the code does'. Remove the doc blocks. [fixable]

dimakis · 2026-05-22T13:19:00Z

  // Build session env with worktree paths for the agent (all repos including primary)
  const sessionEnv = sdkEnv();
  sessionEnv.MITZO_SESSION_ID = wtId;
+  const agentName = options.agentName || DEFAULT_AGENT_NAME;


🔵 unsafe_assumptions: options.agentName || DEFAULT_AGENT_NAME treats empty string as falsy and falls back to the default. This is fine behavior-wise, but ?? would be more intentional since Zod's regex already rejects empty strings — using || obscures whether empty-string fallback is deliberate. [fixable]

dimakis · 2026-05-22T13:19:00Z

@@ -190,6 +190,8 @@ export function TodoView() {
    setPendingSession({
      prompt: buildPrompt(item),


🔵 regressions: Adding telosTaskId: item.id is a behavioral change unrelated to the agentName feature — previously TodoView did not set telosTaskId on the pending session. If this was already handled elsewhere (e.g. by ChatView or the store), this could cause duplicate assignment. Confirm this is intentional and not already set by another path.

- Remove dead vitest.setup.ts (not wired into vitest.config.ts) - Add calendar-utils unit tests (10 tests for all 3 functions) - Remove redundant JSDoc comments from calendar-utils - Use ?? instead of || for agentName fallback (intentional nullish check) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

dimakis and others added 2 commits May 21, 2026 11:06

dimakis commented May 21, 2026

View reviewed changes

dimakis and others added 3 commits May 21, 2026 11:13

dimakis commented May 22, 2026

View reviewed changes

dimakis merged commit c971a67 into main May 22, 2026
1 check passed

dimakis deleted the feat/parameterized-agent-selection branch May 22, 2026 17:15

		@@ -190,6 +190,8 @@ export function TodoView() {
		setPendingSession({
		prompt: buildPrompt(item),

Conversation

dimakis commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Behavior

Next Steps

Test Plan

Uh oh!

dimakis left a comment

Choose a reason for hiding this comment

Centaur Review

server/chat.ts

packages/harness/src/session-registry.ts

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dimakis commented May 22, 2026

Uh oh!

dimakis commented May 22, 2026

Uh oh!

dimakis left a comment

Choose a reason for hiding this comment

Centaur Review

vitest.setup.ts

frontend/src/lib/calendar-utils.ts

server/chat.ts

frontend/src/pages/TodoView.tsx

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dimakis commented May 21, 2026 •

edited

Loading

`server/chat.ts`

`packages/harness/src/session-registry.ts`

`vitest.setup.ts`

`frontend/src/lib/calendar-utils.ts`

`server/chat.ts`

`frontend/src/pages/TodoView.tsx`