You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/configuration.md
+17-6Lines changed: 17 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -93,6 +93,7 @@ sessions.
93
93
| --- | --- |
94
94
|`DEVSPACE_SKILLS`| Set to `0` to hide skills. Enabled by default. |
95
95
|`DEVSPACE_SUBAGENTS`| Set to `1` to expose configured agent profiles as Subagents. Experimental and disabled by default. |
96
+
|`DEVSPACE_WORKFLOWS`| Experimental Dynamic Workflows gate. When unset, it follows the effective Subagents setting, including persisted config and any environment override. |
96
97
|`DEVSPACE_AGENT_DIR`| Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
|`process-sessions` yield bounds | MCP status yield caps |
311
311
312
312
---
@@ -356,7 +356,7 @@ Do not open MCP before CLI smoke — debug path must work headless without a hos
356
356
357
357
## Resolved questions (see also [primitives-spec.md](./primitives-spec.md))
358
358
359
-
1.**Default provider:**`opts.provider` → `meta.defaultProvider` → first of **onboarding-configured**`agentProviders.enabled` ∩ live available. Full config schema in primitives-spec §3.
359
+
1.**Default provider:**`opts.provider` → `meta.defaultProvider` → first live provider in stable product order. Final provider defaults and enablement are deferred to onboarding finalization.
360
360
2.**writeMode:****not in v1 API**; skill teaches prompt-based RO/write.
361
361
3.**Isolation:****`isolation?: 'worktree'` is v1 must-have** on `agent()`; default shared; no auto-merge.
| 1 | Default provider | Runtime: `opts.provider` → `meta.defaultProvider` → first currently available provider in stable product order. Final provider policy is deferred. |
28
28
| 2 | Access / writeMode |**Not in v1 API.** No `writeMode`. Skill teaches **prompt-based** RO vs write. Isolation handles *where* writes land (see isolation). |
29
29
| 3 | List runs |**No MCP list tool v1.****CLI**`devspace workflow ls` yes. |
providers at runtime, keeps availability details in memory, and orders usable
70
+
providers by `LOCAL_AGENT_PROVIDERS`:
68
71
69
-
```ts
70
-
// src/user-config.ts — today
71
-
interfaceDevspaceUserConfig {
72
-
host?:string
73
-
port?:number
74
-
allowedRoots?:string[]
75
-
publicBaseUrl?:string|null
76
-
allowedHosts?:string[]
77
-
stateDir?:string
78
-
worktreeRoot?:string
79
-
agentDir?:string
80
-
subagents?:boolean// master switch only
81
-
}
72
+
```text
73
+
codex → claude → opencode → pi → cursor → copilot
74
+
```
75
+
76
+
`devspace init` does not configure providers. `devspace doctor` may report live
77
+
availability but remains read-only. Probe timestamps and unavailable-provider
78
+
reasons are diagnostics, not durable user intent.
79
+
80
+
Default resolution is:
81
+
82
+
```text
83
+
explicit agent() provider
84
+
→ workflow meta.defaultProvider
85
+
→ first currently available provider
82
86
```
83
87
84
-
There is **no** persisted enable-list. Runtime exposes every implemented provider that is **currently on PATH** (`getLocalAgentProviderAvailabilitySnapshot`). Order is code order of `LOCAL_AGENT_PROVIDERS`, not user preference. No onboarding write-back.
88
+
An explicit provider or profile whose harness is unavailable fails with a clear
89
+
typed error. Direct `devspace agents` calls and workflow `agent()` calls use the
90
+
same target resolver.
85
91
86
-
### Add: `agentProviders` on user config
92
+
### Deferred final provider policy
93
+
94
+
When Subagents and Dynamic Workflows are finalized and incorporated into
95
+
onboarding, the intended durable shape is an ordered array of user choices:
87
96
88
97
```ts
89
-
/** Known built-in ids — keep in sync with LocalAgentProvider */
90
-
typeAgentProviderId=
91
-
|"codex"
92
-
|"claude"
93
-
|"opencode"
94
-
|"pi"
95
-
|"cursor"
96
-
|"copilot"
97
-
98
-
interfaceAgentProvidersConfig {
99
-
/**
100
-
* Ordered enable-list. Order = preference.
101
-
* index 0 = default fallback for agent() when provider omitted.
102
-
* Only ids in this list may be used by workflows/subagents (if present).
103
-
* Missing/empty → fall back to "all currently available" (compat) OR
104
-
* require init (prefer: treat missing as "auto = all available in code order").
105
-
*/
106
-
enabled:AgentProviderId[]
107
-
108
-
/** ISO time of last successful probe (init/doctor). Optional. */
109
-
detectedAt?:string
110
-
111
-
/**
112
-
* Optional last probe snapshot for doctor UI (not required at runtime).
113
-
* Do not use as source of truth for enablement — `enabled` is.
Array order can define fallback preference. Resolution will then be:
153
112
154
-
| Concern | Spec |
155
-
|---|---|
156
-
|**Master switch**|`subagents: true` still required for workflow tools + agent CLI + skills. |
157
-
|**Enable-list**|`agentProviders.enabled` is the only user-facing allowlist. |
158
-
|**Order**| First entry = default `agent()` provider after availability filter. |
159
-
|**Live ∩ config**|`candidates = enabled.filter(id => currentlyAvailable(id))`. Stale enable of uninstalled CLI → skipped with doctor warning, not hard-fail until no candidates. |
160
-
|**Unknown ids**| Reject on write/init; ignore-with-warn at read if config hand-edited. |
161
-
|**Missing `agentProviders`**| Compat: `enabled` effective = all available in built-in order (today’s behavior). Init should still write the block. |
162
-
|**Empty `enabled: []`**| Error at first `agent()` / `agents run`: “no providers enabled”. |
163
-
|**Env override (optional)**|`DEVSPACE_AGENT_PROVIDERS=codex,claude` replaces `enabled` for process (ops/debug). |
164
-
|**ServerConfig**| Load into `ServerConfig.agentProviders: { enabled: AgentProviderId[] }` resolved at boot. |
165
-
166
-
### Onboarding (`devspace init` / `doctor`)
167
-
168
-
1. Probe all six providers (reuse `local-agent-availability`).
169
-
2. Set `enabled` = available ids in **stable product order**:
170
-
`codex → claude → opencode → pi → cursor → copilot` (only those available).
171
-
3. Write `detectedAt` + optional `lastProbe`.
172
-
4.`doctor` re-probes; offers to refresh `enabled` (add newly installed; optionally keep user-disabled by not auto-re-adding removed ids — v1: refresh = rewrite available set, document that).
173
-
174
-
### Default provider algorithm
175
-
176
-
```
177
-
resolveProvider(opts, meta, config):
178
-
enabled = config.agentProviders?.enabled
179
-
?? ALL_IMPLEMENTED_IN_CODE_ORDER
180
-
candidates = enabled ∩ liveAvailable(PATH)
181
-
if opts.provider:
182
-
if opts.provider ∉ enabled → throw (disabled in config)
183
-
if opts.provider ∉ liveAvailable → throw (not installed)
184
-
return opts.provider
185
-
if meta.defaultProvider:
186
-
same checks against candidates
187
-
return meta.defaultProvider
188
-
if candidates[0] → return candidates[0]
189
-
throw NoProviderError
113
+
```text
114
+
call model/effort override
115
+
→ profile model/effort
116
+
→ provider defaultModel/defaultEffort
117
+
→ provider-native defaults
190
118
```
191
119
192
-
Skill: “Pass `provider` when you care; else first enabled+available provider.”
120
+
Availability snapshots still must not be persisted inside this policy. The
121
+
onboarding, config commands, documentation, and provider-management UI should
122
+
land together rather than exposing another intermediate configuration shape.
0 commit comments