Support per-conversation external Agent launch overrides
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 146
- Forks
- 20
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 43
Description
Summary
Support generic per-conversation launch overrides for external Agents, beginning with the working directory. Agent Nodes and standalone Chats should be able to customize launch settings without requiring one Profile per repository while preserving the server-owned lifecycle introduced by #178.
This issue owns how an existing Profile is consumed by a conversation. Agentlet discovery and automatic Profile provisioning remain in #174.
Requirements
Generic launch configuration
- Represent conversation-specific launch settings as a generic launch-override contract rather than BYOA discovery state.
- Use the existing Agent Node draft and binding ownership boundaries from #178; launch overrides must not introduce a parallel lifecycle or client-owned binding state.
- Keep Profile selection and launch overrides independent. Changing an override must not create, replace, or mutate a Profile.
- Design the contract so future environment, sandbox, model, or permission overrides can be added without redefining Agent Node lifecycle.
Working-directory override
- Let users set a working-directory override near the Agent selector for an unrealized Agent Node or standalone Chat.
- Persist the override in the canonical conversation launch configuration.
- Resolve the effective directory deterministically: conversation override -> selected Profile default, when configured -> documented target-machine default.
- Offer a native folder picker only when it addresses the actual execution machine; otherwise accept a typed target-native path.
- Show the effective path and inheritance source with accessible full-path presentation.
- Allow resetting to inherited behavior before realization.
Target-machine validation
- Resolve and validate the final path on the Agent execution machine, not the desktop client or Huabu Server when those are different machines.
- Preserve POSIX, Windows, and UNC path semantics.
- Reject an invalid explicit path with an actionable error; never silently fall back to another directory.
- Revalidate at the immutable workload-creation boundary to account for filesystem changes and races.
- Classify daemon connection, unsupported validation protocol, invalid path, and launch failures separately.
Realization and lifecycle
- Opening a panel or editing launch settings must not realize a workload.
- First control or first message must use the same canonical launch configuration.
- Before realization, the owner may edit the Profile binding and launch overrides according to #178's draft policy.
- After realization, display the immutable Profile, placement, and effective directory from the workload snapshot.
- Existing workloads must retain their realized identity and directory across refresh, resume, daemon reconnection, process restart, and later Profile edits or deletion.
- Changing immutable launch settings after realization requires a new conversation unless a separately designed replacement operation creates a new workload.
- Hydration, undo/redo, switching panels, and concurrent edits must preserve the canonical server-owned state.
Acceptance criteria
- An unrealized Agent Node and standalone Chat can persist, reset, and hydrate a working-directory override independently of the selected Profile.
- Effective-directory precedence is conversation override -> Profile default -> target-machine default.
- Explicit paths are validated on the execution machine and fail visibly without fallback.
- First-control and first-message realization use the same launch settings.
- Realized placement and cwd remain immutable across reload, recovery, and Profile changes.
- The implementation preserves #178 binding, admission, projection, invocation-token, and title behavior without adding BYOA-specific lifecycle branches.
- Regression coverage includes path-platform semantics, validation races, control-only realization, hydration, owner transitions, unavailable machines, and concurrent draft updates.
Out of scope
- Agentlet harness discovery and Profile provisioning, tracked by #174.
- Automatic installation of Agent software or ACP adapters.
- Credential provisioning.
- New daemon pairing or authentication protocols.
- Moving or mutating an already-realized workload.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No implementation files or tests are named. Start by reading #178 for Agent Node draft, binding, admission, and realization boundaries, then compare #174 to preserve the discovery and provisioning split. Trace canonical launch configuration for unrealized Agent Nodes and standalone Chats; done means the listed acceptance criteria pass, including target-machine validation, immutable realized identity, hydration, recovery, and concurrent updates.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, full-stack
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100