feat(agents): parameterized agent selection via agentName

[dimakis]

Summary

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

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

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

1. ✅ Wire Telos entry point → Done
2. ✅ Wire Calendar entry point → Done
3. ⏳ 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

[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]

🔴 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]

🟡 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]

🟡 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]

🔵 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]

🟡 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]