feat: configurable utility agent for auxiliary tasks#836
Conversation
… context grooming) Closes #835 Adds utilityAgentId and utilityModelId settings so users can route lightweight auxiliary tasks to a cheaper/faster agent instead of burning primary session tokens on housekeeping work.
📝 WalkthroughWalkthroughThis PR implements a "Utility Agent" feature that lets users configure a separate agent and optional model for lightweight auxiliary tasks like tab naming and context summarization. Changes span settings metadata, defaults, both renderer and main process stores, IPC handler logic, UI components, and test mocks. Changes
Sequence DiagramsequenceDiagram
participant User as User
participant UI as GeneralTab UI
participant Store as Renderer Store
participant IPC as IPC Handler
participant MainStore as Main Settings Store
participant AgentConfig as Agent Config Store
participant Spawn as Agent Spawn
User->>UI: Select Utility Agent + Model
UI->>Store: Call setUtilityAgentId/setUtilityModelId
Store->>Store: Update state + persist to window.maestro.settings
Note over IPC,Spawn: Tab Naming / Context Grooming Flow
IPC->>MainStore: Read utilityAgentId/utilityModelId
MainStore-->>IPC: Return settings (or null)
alt Utility Agent Set
IPC->>IPC: effectiveAgentType = utilityAgentId
IPC->>AgentConfig: Resolve agent via effectiveAgentType
else Utility Agent Not Set
IPC->>IPC: effectiveAgentType = sessionAgentType
IPC->>AgentConfig: Resolve agent via effectiveAgentType
end
AgentConfig-->>IPC: Agent config + defaults
IPC->>IPC: Pass utilityModelId as modelId (if set)
IPC->>Spawn: buildAgentArgs(effectiveAgentType, modelId)
Spawn-->>IPC: Ready to spawn auxiliary task agent
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThis PR adds Confidence Score: 4/5Safe to merge after fixing the session-level custom config forwarding bug in context.ts. One P1 logic defect: when a utility agent is configured and the session has custom path/args/env-vars set for a different agent type, the context groomer invokes the wrong binary. Tab naming is unaffected. Everything else — settings plumbing, UI, store, defaults, and tests — is correct and well-structured. src/main/ipc/handlers/context.ts — lines 174–178, session overrides forwarded to utility agent. Important Files Changed
Sequence DiagramsequenceDiagram
participant R as Renderer
participant TN as tabNaming.ts (IPC)
participant CTX as context.ts (IPC)
participant SS as settingsStore
participant CG as context-groomer.ts
participant AD as AgentDetector
participant PM as ProcessManager
R->>TN: tabNaming:generateTabName(userMessage, agentType, cwd)
TN->>SS: get('utilityAgentId')
TN->>SS: get('utilityModelId')
Note over TN: effectiveAgentType = utilityAgentId || agentType
TN->>AD: getAgent(effectiveAgentType)
TN->>PM: spawn(effectiveAgentType, args with modelId)
R->>CTX: context:groomContext(projectRoot, agentType, prompt, options)
CTX->>SS: get('utilityAgentId')
CTX->>SS: get('utilityModelId')
Note over CTX: effectiveAgentType = utilityAgentId || agentType
CTX->>CG: groomContext({agentType: effectiveAgentType, modelId, sessionCustomPath, ...})
CG->>AD: getAgent(effectiveAgentType)
CG->>PM: spawn(resolvedCommand, resolvedArgs)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/releases.md`:
- Line 153: Fix the grammar in the release note sentence that currently reads
"You will received (configurable) warnings at 60% and 80% context consumption
with a hint to compact" by changing "received" to "receive" so the sentence
reads "...You will receive (configurable) warnings at 60% and 80% context
consumption with a hint to compact"; update the same sentence text in
docs/releases.md (the context-management release note line) accordingly.
- Line 74: In the "Document Graphs" sentence that currently reads "Launch from
file preview or from the FIle tree panel," fix the typo by changing "FIle tree
panel" to "File tree panel" so the phrase reads "Launch from file preview or
from the File tree panel."
- Line 20: The heading "Major 0.15.x Additions" is using an H1 marker ("#")
inside the "## v0.15.x" section which breaks hierarchy; change the line
containing "Major 0.15.x Additions" from "# Major 0.15.x Additions" to a nested
heading such as "### Major 0.15.x Additions" (or "### Major 0.15.x Additions")
to restore proper section nesting under "## v0.15.x".
- Line 80: Update the heading text "# Smaller Changes in 014.x" to the correct
level and version by replacing the leading "#" with the appropriate heading
level (e.g., "## Smaller Changes in 0.14.x") and fix the typo "014.x" to
"0.14.x" so the heading reads "## Smaller Changes in 0.14.x".
In `@src/renderer/components/Settings/tabs/GeneralTab.tsx`:
- Around line 180-182: Replace the empty .catch handler in the agent detection
promise inside GeneralTab (the anonymous .catch block currently swallowing
errors) with logic that calls the Sentry utility (import captureException or
captureMessage from src/utils/sentry.ts) to report the error with context (e.g.,
"Agent detection failed in GeneralTab") and then re-throw the error for
unexpected failures; ensure the catch still handles known/expected cases (e.g.,
ignore a specific benign error) but otherwise reports via
captureException(caughtError) before throwing so Sentry can observe the failure.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: ce8186b9-3e2d-409b-b5d6-d1a6a3fe2077
📒 Files selected for processing (12)
docs/releases.mdsrc/__tests__/main/ipc/handlers/tabNaming.test.tssrc/main/index.tssrc/main/ipc/handlers/context.tssrc/main/ipc/handlers/index.tssrc/main/ipc/handlers/tabNaming.tssrc/main/stores/defaults.tssrc/main/utils/context-groomer.tssrc/renderer/components/Settings/tabs/GeneralTab.tsxsrc/renderer/hooks/settings/useSettings.tssrc/renderer/stores/settingsStore.tssrc/shared/settingsMetadata.ts
| - **Group chat participant management:** Remove button on participant cards lets you remove stale or unwanted participants from a group chat | ||
| - **Batch resume/abort:** New controls in the right panel for resuming or aborting batch operations | ||
| - **Default worktree directory:** Worktree configuration now defaults to the parent of the agent's working directory instead of blank | ||
| # Major 0.15.x Additions |
There was a problem hiding this comment.
Use a nested heading level here (not H1).
Line 20 resets to # inside a ## v0.15.x section, which breaks document hierarchy/navigation. Use ### (or ### Major 0.15.x Additions) instead.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/releases.md` at line 20, The heading "Major 0.15.x Additions" is using
an H1 marker ("#") inside the "## v0.15.x" section which breaks hierarchy;
change the line containing "Major 0.15.x Additions" from "# Major 0.15.x
Additions" to a nested heading such as "### Major 0.15.x Additions" (or "###
Major 0.15.x Additions") to restore proper section nesting under "## v0.15.x".
|
|
||
| The major contributions to 0.14.x remain: | ||
|
|
||
| 🗄️ Document Graphs. Launch from file preview or from the FIle tree panel. Explore relationships between Markdown documents that contain links between documents and to URLs. |
There was a problem hiding this comment.
Fix typo in “FIle tree panel”.
Line 74 should be “File tree panel”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/releases.md` at line 74, In the "Document Graphs" sentence that
currently reads "Launch from file preview or from the FIle tree panel," fix the
typo by changing "FIle tree panel" to "File tree panel" so the phrase reads
"Launch from file preview or from the File tree panel."
|
|
||
| 🧙♂️ Added an in-tab wizard for generating Auto Run Playbooks via `/wizard` or a new button in the Auto Run panel. | ||
|
|
||
| # Smaller Changes in 014.x |
There was a problem hiding this comment.
Correct heading level and version typo.
Line 80 should not be #, and “014.x” appears to be a typo for “0.14.x”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/releases.md` at line 80, Update the heading text "# Smaller Changes in
014.x" to the correct level and version by replacing the leading "#" with the
appropriate heading level (e.g., "## Smaller Changes in 0.14.x") and fix the
typo "014.x" to "0.14.x" so the heading reads "## Smaller Changes in 0.14.x".
|
|
||
| ## Context Management Tools | ||
|
|
||
| 📖 Added context management options from tab right-click menu. You can now compress, merge, and transfer contexts between agents. You will received (configurable) warnings at 60% and 80% context consumption with a hint to compact. |
There was a problem hiding this comment.
Fix grammar in context-management description.
Line 153 says “You will received”; this should be “You will receive”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/releases.md` at line 153, Fix the grammar in the release note sentence
that currently reads "You will received (configurable) warnings at 60% and 80%
context consumption with a hint to compact" by changing "received" to "receive"
so the sentence reads "...You will receive (configurable) warnings at 60% and
80% context consumption with a hint to compact"; update the same sentence text
in docs/releases.md (the context-management release note line) accordingly.
| .catch(() => { | ||
| // Silently fail - dropdown will just be empty | ||
| }); |
There was a problem hiding this comment.
Do not silently swallow agent detection failures.
The empty .catch() hides unexpected failures and drops observability for this settings flow.
Suggested fix
+import { captureException } from '../../../../utils/sentry';
...
- .catch(() => {
- // Silently fail - dropdown will just be empty
- });
+ .catch((error) => {
+ if (cancelled) return;
+ captureException(error instanceof Error ? error : new Error(String(error)));
+ });As per coding guidelines: "Do not silently swallow errors... For unexpected errors, re-throw them to allow Sentry to capture them. Use Sentry utilities (captureException, captureMessage) from src/utils/sentry.ts for explicit error reporting with context."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/renderer/components/Settings/tabs/GeneralTab.tsx` around lines 180 - 182,
Replace the empty .catch handler in the agent detection promise inside
GeneralTab (the anonymous .catch block currently swallowing errors) with logic
that calls the Sentry utility (import captureException or captureMessage from
src/utils/sentry.ts) to report the error with context (e.g., "Agent detection
failed in GeneralTab") and then re-throw the error for unexpected failures;
ensure the catch still handles known/expected cases (e.g., ignore a specific
benign error) but otherwise reports via captureException(caughtError) before
throwing so Sentry can observe the failure.
|
Looks great! |
chr1syy
left a comment
chr1syy
left a comment
There was a problem hiding this comment.
Took a fresh look at this in the context of where main is now. The concept and core wiring are solid — clean effectiveAgentType indirection through tabNaming.ts and context.ts, modelId only flowing when utilityAgentId is set, defaults of null preserving existing behavior, SSH/custom-config passthrough intact. The new UI section in GeneralTab.tsx matches the surrounding pattern.
That said, I think there are four things to address before this can merge cleanly:
Blockers
-
docs/releases.mdis hand-edited. The branch's second commit (3f52a562e — chore: fix pre-existing prettier formatting in releases.md) reformats the file (+254/-240).CLAUDE.mdexplicitly says "docs/releases.mdis generated/updated automatically during release pressing. Never modify it manually — even when shipping user-facing changes that would seem to warrant a release note entry. The release tooling handles it." Worth reverting that commit so the diff stays scoped to the utility-agent feature. -
No
settingsMetadata.tsentries for the new settings.src/shared/settingsMetadata.tshas landed onmainsince this PR branched (it's the source of truth used bymaestro-cli settings list/get/set).utilityAgentIdandutilityModelIdget added todefaults.tsand the Zustand store but not to the metadata registry, so they'll be invisible to the CLI and to LLM context that reads the registry. Each needs an entry withdescription,type,default, and acategory(integrationsfeels right). -
Stale base — ~32 release-merges behind
main. Merge base is at94ccdf843(v0.16.9-RC). The conflict surface goes well past the utility-agent feature;settingsStore.ts,useSettings.ts,main/index.ts, andGeneralTab.tsxhave all moved on substantially. Rebase is going to be material. -
Probably wants
rcas the base, notmain. Per the standing branching policy (also called out on #1072), features bake onrcfirst. If retargeted torc, this also needs:- An entry in
src/renderer/components/Settings/searchableSettings.ts(only exists onrc) data-setting-id="utilityAgentId"/data-setting-id="utilityModelId"markers on the rendered controls inGeneralTab.tsxso settings search can find them
- An entry in
Non-blocking
-
No test for the utility-agent code path. The change to
tabNaming.test.tsis a mock fix-up that returnsnulldefaults — i.e. it asserts the baseline behavior didn't break. Worth adding at least one case that setsutilityAgentId(and optionallyutilityModelId) and asserts the alternate agent is detected/spawned andmodelIdflows through tobuildAgentArgs. Same forcontext.tsgroom. -
SSH + utility-agent interaction is unspecified. When a session is on SSH and the user picks a local utility agent (or vice versa), the session's
sshRemoteConfigis still passed through. Probably fine as a first cut, but worth a comment in the handler pinning down the chosen semantics so this doesn't drift later.
Concept-approved — happy to re-review once the four blockers are cleared.
3 participants
Summary
Closes #835
utilityAgentIdandutilityModelIdsettings so users can route lightweight auxiliary tasks (tab naming, context grooming) to a cheaper/faster agent instead of burning primary session tokens on housekeepingFiles changed
src/shared/settingsMetadata.ts— new setting definitionssrc/main/stores/defaults.ts— defaults (bothnull)src/renderer/stores/settingsStore.ts— Zustand state, setters, and load logicsrc/renderer/hooks/settings/useSettings.ts— hook interfacesrc/main/ipc/handlers/tabNaming.ts— resolves utility agent before spawningsrc/main/ipc/handlers/context.ts— resolves utility agent for groomContext; addedsettingsStoredependencysrc/main/utils/context-groomer.ts— accepts optionalmodelIdand passes tobuildAgentArgssrc/main/index.ts,src/main/ipc/handlers/index.ts— wiresettingsStoreto context handlerssrc/renderer/components/Settings/tabs/GeneralTab.tsx— Utility Agent UI sectionsrc/__tests__/main/ipc/handlers/tabNaming.test.ts— fix mock to return proper defaultsTest plan
Summary by CodeRabbit
Release Notes
New Features
Documentation