🤖 feat: make mux agent routable from Auto in project workspaces by ethanndickson · Pull Request #2768 · coder/mux

ethanndickson · 2026-03-04T06:03:26Z

Summary

Make the mux agent (skills, AGENTS.md, config tools) reachable in any project workspace via Auto routing. In project context, tools operate on project-scoped resources (.mux/skills/, project AGENTS.md); in the system workspace they continue to operate globally. Also eliminates a wasteful throwaway runtime assembly used for sentinel tool-name computation.

Background

The mux agent was previously confined to the singleton "Chat with Mux" system workspace. All its tools derived scope from workspaceSessionDir (navigating up ~/.mux/sessions/<id> to find ~/.mux/), hardcoding them to global scope. This meant project workspaces couldn't manage their own skills or AGENTS.md via mux.

Separately, resolveAgentForStream created a throwaway runtime and instantiated every tool object just to compute tool names for the agent-transition sentinel message. This was slow and caused analytics_query to be missing from the handoff message (the stub config lacked analyticsService).

Implementation

1. MuxToolScope type + wiring (`toolScope.ts`, `aiService.ts`, `tools.ts`)

New discriminated union MuxToolScope:
- { type: "global", muxHome } — system workspace
- { type: "project", muxHome, projectRoot } — project workspace (projectRoot = worktree path)
Added muxScope?: MuxToolScope to ToolConfiguration
Resolved once at tool-construction time in aiService.ts based on workspaceId === MUX_HELP_CHAT_WORKSPACE_ID
Shifted MCP/secrets gates from workspaceId !== MUX_HELP_CHAT_WORKSPACE_ID to effectiveAgentId !== MUX_HELP_CHAT_AGENT_ID so mux running in project scope gets the right capability set

2. Scope-aware skill tools (`agent_skill_{write,delete,list}.ts`, `skillFileUtils.ts`)

All three skill mutation tools derive their skills root from config.muxScope:
- Project scope → <projectRoot>/.mux/skills/
- Global scope → <muxHome>/skills/
validateLocalSkillDirectory generalized: takes a containmentRoot parameter instead of hardcoded muxHomeReal
agent_skill_list scans both project and global roots when in project scope, tagging each entry with its scope. Global-only listing retained for system workspace.
Removed getMuxHomeFromWorkspaceSessionDir from muxHome.ts (file deleted) — all callers use muxScope directly

3. Renamed + scope-aware AGENTS.md tools (`mux_agents_{read,write}.ts`)

mux_global_agents_read/write → mux_agents_read/write via git mv
Tools read config.muxScope to determine target:
- Project scope → <projectRoot>/AGENTS.md
- Global scope → <muxHome>/AGENTS.md
Replaced symlink rejection (lstat + reject-if-symlink) with realpath() + containment validation (isPathInsideRoot). In-root symlinks (e.g., AGENTS.md → docs/AGENTS.md) now work; escaping symlinks are rejected.
Updated all references in toolDefinitions.ts, tools.ts, exec.md, plan.md

4. Simplified config tools (`mux_config_{read,write}.ts`)

Use config.muxScope!.muxHome directly instead of getMuxHomeFromWorkspaceSessionDir
Removed the duplicate getMuxHomeFromWorkspaceSessionDir from configToolUtils.ts

5. Agent prompt updates (`mux.md`, `auto.md`, `exec.md`, `plan.md`)

mux.md: Rewritten for dual-scope behavior with clear context-aware documentation and safety rules
auto.md: Added mux routing criteria for config/skills/AGENTS.md management requests
exec.md / plan.md: Updated tool policy regex mux_global_agents_.* → mux_agents_.*
Regenerated builtInAgentContent.generated.ts

6. Sentinel tool-name computation without throwaway runtime (`agentResolution.ts`, `toolPolicy.ts`, `toolDefinitions.ts`)

New applyToolPolicyToNames(names, policy) — name-only policy filtering that shares matching logic with applyToolPolicy (single source of truth for regex/order semantics)
applyToolPolicy refactored to delegate to applyToolPolicyToNames
getAvailableTools() gained enableAnalyticsQuery?: boolean flag (defaults true)
resolveAgentForStream replaced throwaway block with getAvailableTools(model, flags) → applyToolPolicyToNames(names, policy) — no tool objects instantiated
Removed initStateManager from ResolveAgentOptions, added hasAnalyticsService: boolean
Removed dead imports: os, createRuntime, getToolsForModel, InitStateManager
getToolsForModel allowlist passes enableAnalyticsQuery: Boolean(config.analyticsService) to stay in sync

7. Test coverage

testHelpers.ts: createTestToolConfig accepts optional muxScope (defaults to global scope pointing at tempDir)
Updated all existing tool tests to supply muxScope in configs
New dual-scope test cases for skill write/delete/list, AGENTS.md read/write, and config tools
New applyToolPolicyToNames parity tests (undefined/empty policy, disable, regex, last-wins, require, order preservation)
mux_global_agents.test.ts deleted, replaced by mux_agents.test.ts with expanded scope coverage

Validation

make typecheck ✅
All focused tests pass: toolPolicy.test.ts, agent_skill_list.test.ts, mux_agents.test.ts, aiService.test.ts, agent_skill_write.test.ts, agent_skill_delete.test.ts, mux_config_read.test.ts, mux_config_write.test.ts
Manual E2E testing confirmed three additional fixes (committed as fix commit): projectRoot→worktree for skill visibility, dual-scope skill listing, symlink-safe AGENTS.md

Risks

MCP/secrets gate shift: Changed from workspace-ID check to agent-ID check. If effectiveAgentId doesn't resolve to MUX_HELP_CHAT_AGENT_ID in the system workspace, MCP/secrets would incorrectly activate. Low risk — the resolution path for the system workspace always yields this agent ID.
Symlink containment: The new realpath + isPathInsideRoot approach is more permissive than the old blanket symlink rejection. Escaping symlinks are still rejected, but in-root symlinks are now allowed. This is intentional for repos with committed AGENTS.md symlinks.

Generated with mux • Model: anthropic:claude-opus-4-6 • Thinking: xhigh • Cost: $31.71

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c16c9996c8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/node/services/tools/mux_agents_write.ts

src/node/services/aiService.ts

ethanndickson · 2026-03-04T06:40:37Z

@codex review

ethanndickson · 2026-03-04T06:41:44Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7f14af86e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/node/services/tools/agent_skill_write.ts

ethanndickson · 2026-03-04T07:29:51Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62fb263f9e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/node/services/tools/agent_skill_write.ts

src/node/services/tools/agent_skill_list.ts

ethanndickson · 2026-03-04T08:00:34Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 03cf98f807

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/common/utils/tools/tools.ts

ethanndickson · 2026-03-04T08:16:04Z

Resolved — backward-compat aliases are unnecessary here. Frontend and backend are always in sync (see AGENTS.md IPC/Compatibility section), so breaking tool renames are expected and safe. No persisted policy will reference the old names since this is a net-new feature. @codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 728534d868

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/node/services/aiService.ts

ethanndickson · 2026-03-04T14:37:13Z

@codex review

- Add MuxToolScope discriminated union (global/project) to ToolConfiguration - Scope-aware skill tools: project writes to .mux/skills/, global to ~/.mux/skills/ - agent_skill_list scans both project + global roots in project scope - Rename mux_global_agents_read/write → mux_agents_read/write, scope-aware - Symlink-safe AGENTS.md via realpath + containment (replaces blanket rejection) - Simplify config tools to use muxScope.muxHome directly; delete muxHome.ts - Rewrite mux.md for dual-scope behavior; add mux routing to auto.md - Sentinel tool names via getAvailableTools + applyToolPolicyToNames (no throwaway runtime) - Add enableAnalyticsQuery flag to getAvailableTools; sync in getToolsForModel allowlist - Shift MCP/secrets gates from workspace-ID to agent-ID check

ethanndickson · 2026-03-04T14:42:03Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1fbe8126d9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-04T14:50:57Z

src/node/services/aiService.ts

+  workspacePath: string
+): string {
+  const runtimeType = metadata.runtimeConfig.type;
+  return runtimeType === "ssh" || runtimeType === "docker" ? metadata.projectPath : workspacePath;


Keep project AGENTS writes in the active SSH workspace

For ssh workspaces this maps muxScope.projectRoot to metadata.projectPath (host path), so mux_agents_write edits host AGENTS.md instead of the remote workspace file. The prompt pipeline still reads instructions from workspacePath via runtime-first lookup (readInstructionSources), and SSHRuntime.ensureReady() only checks repo presence (it does not resync host edits each stream), so users can successfully edit AGENTS via mux but those changes won’t actually affect subsequent model requests in that SSH workspace.

Useful? React with 👍 / 👎.

ethanndickson changed the title ~~🤖 refactor: make mux agent scope-aware for project workspaces~~ 🤖 feat: make mux agent routable from Auto in project workspaces Mar 4, 2026

ethanndickson force-pushed the chat-mux-j85r branch from c16c999 to bff3f88 Compare March 4, 2026 06:09

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

src/node/services/tools/mux_agents_write.ts Outdated Show resolved Hide resolved

src/node/services/aiService.ts Outdated Show resolved Hide resolved

ethanndickson force-pushed the chat-mux-j85r branch from 842b79e to 7f14af8 Compare March 4, 2026 06:41

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

src/node/services/tools/agent_skill_write.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

src/node/services/tools/agent_skill_write.ts Outdated Show resolved Hide resolved

src/node/services/tools/agent_skill_list.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

src/common/utils/tools/tools.ts Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

src/node/services/aiService.ts Show resolved Hide resolved

ethanndickson added 13 commits March 5, 2026 01:41

Refactor mux agents read/write path resolution

41f0d90

Use host-local mux project root for remote runtimes

a93e677

🤖 tests: cover dangling AGENTS symlink and mux root resolver

0a6a6b1

Fix lint violations in agent skill list and mux agents tests

7605b2e

Regenerate docs from source

f980c8f

Harden skill path containment for project scope

bdff0fa

test: cover project .mux symlink escapes for skill tools

14fdb27

Fix preflight ordering in agent_skill_write

852aded

Block symlinked project skill directories in listing

e3cc281

Add backward-compat aliases for renamed mux agents tools

1d6701d

Revert backward-compat aliases for renamed mux agents tools

46376c9

Use shared skill storage context for read/discovery

1fbe812

ethanndickson force-pushed the chat-mux-j85r branch from 5f358a1 to 1fbe812 Compare March 4, 2026 14:42

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

Conversation

ethanndickson commented Mar 4, 2026

Summary

Background

Implementation

1. MuxToolScope type + wiring (toolScope.ts, aiService.ts, tools.ts)

2. Scope-aware skill tools (agent_skill_{write,delete,list}.ts, skillFileUtils.ts)

3. Renamed + scope-aware AGENTS.md tools (mux_agents_{read,write}.ts)

4. Simplified config tools (mux_config_{read,write}.ts)

5. Agent prompt updates (mux.md, auto.md, exec.md, plan.md)

6. Sentinel tool-name computation without throwaway runtime (agentResolution.ts, toolPolicy.ts, toolDefinitions.ts)

7. Test coverage

Validation

Risks

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

ethanndickson commented Mar 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

1. MuxToolScope type + wiring (`toolScope.ts`, `aiService.ts`, `tools.ts`)

2. Scope-aware skill tools (`agent_skill_{write,delete,list}.ts`, `skillFileUtils.ts`)

3. Renamed + scope-aware AGENTS.md tools (`mux_agents_{read,write}.ts`)

4. Simplified config tools (`mux_config_{read,write}.ts`)

5. Agent prompt updates (`mux.md`, `auto.md`, `exec.md`, `plan.md`)

6. Sentinel tool-name computation without throwaway runtime (`agentResolution.ts`, `toolPolicy.ts`, `toolDefinitions.ts`)