@devorch/cli-linux-x64 0.20.0 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/claude-mod/devorch-companion/.claude-plugin/plugin.json +31 -3
- package/bin/claude-mod/devorch-companion/README.md +47 -5
- package/bin/claude-mod/devorch-companion/hooks/core.ts +3 -0
- package/bin/claude-mod/devorch-companion/hooks/register.ts +48 -14
- package/bin/claude-mod/devorch-companion/hooks/supervision.ts +134 -4
- package/bin/claude-mod/devorch-companion/skills/devorch-step/SKILL.md +39 -21
- package/bin/claude-mod/devorch-companion/skills/sdlc-drive/SKILL.md +31 -16
- package/bin/claude-mod/devorch-companion/types/index.d.ts +18 -0
- package/bin/devorch +1 -1
- package/package.json +1 -1
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "devorch-companion",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "DevOrch companion: the sdlc-drive and devorch-step skills, the devorch-step-worker agent and a DevOrch MCP server (the devorch CLI's `companion mcp`), plus a mod that watches DevOrch runs and wakes an idle /devorch-companion:devorch-step session on platform events instead of ScheduleWakeup polling. Status line, /devorch-watch, /devorch-unwatch, /devorch-answer, the devorch_companion tool and a $.devorch event hook for other plugins.",
|
|
5
|
-
"author": {
|
|
3
|
+
"version": "0.21.0",
|
|
4
|
+
"description": "DevOrch companion: the sdlc-drive and devorch-step skills, the devorch-step-worker agent and a DevOrch MCP server (the devorch CLI's `companion mcp`), plus a mod that watches DevOrch runs and wakes an idle /devorch-companion:devorch-step session on platform events instead of ScheduleWakeup polling (wakeMode: auto, push or poll). Status line, /devorch-watch, /devorch-unwatch, /devorch-answer, the devorch_companion tool and a $.devorch event hook for other plugins.",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Dev Orchestrator"
|
|
7
|
+
},
|
|
6
8
|
"license": "UNLICENSED",
|
|
7
9
|
"types": "./types/index.d.ts",
|
|
8
10
|
"userConfig": {
|
|
@@ -19,6 +21,32 @@
|
|
|
19
21
|
"description": "The DevOrch server the MCP server and run watches use. Default: the hosted API, https://api.devorchestrator.com (an empty value means the same). Set http://localhost:8700 to dogfood against a local backend. DEVORCH_API_BASE in the environment wins over this; a single watch can also name its own base URL.",
|
|
20
22
|
"required": false,
|
|
21
23
|
"default": "https://api.devorchestrator.com"
|
|
24
|
+
},
|
|
25
|
+
"wakeMode": {
|
|
26
|
+
"type": "string",
|
|
27
|
+
"title": "Wake mode",
|
|
28
|
+
"description": "Who wakes an interactive run between steps. auto (default): the companion mod wakes the session the moment the run can move while it is healthy, else the step skill polls with /loop + ScheduleWakeup. push: the companion only; if it is unhealthy the skill reports that and stops instead of polling. poll: always /loop + ScheduleWakeup (the mod still shows the status line but never wakes). DEVORCH_WAKE_MODE in the environment wins over this.",
|
|
29
|
+
"required": false,
|
|
30
|
+
"default": "auto",
|
|
31
|
+
"options": [
|
|
32
|
+
"auto",
|
|
33
|
+
"push",
|
|
34
|
+
"poll"
|
|
35
|
+
]
|
|
36
|
+
},
|
|
37
|
+
"fallbackWakeupSeconds": {
|
|
38
|
+
"type": "number",
|
|
39
|
+
"title": "Fallback wakeup (seconds)",
|
|
40
|
+
"description": "Under poll, the safety-net ScheduleWakeup the step skill sets while a worker runs, in case it never hands back. 60 to 3600, default 1800. DEVORCH_FALLBACK_WAKEUP_SECONDS in the environment wins over this.",
|
|
41
|
+
"required": false,
|
|
42
|
+
"default": 1800
|
|
43
|
+
},
|
|
44
|
+
"longPollSeconds": {
|
|
45
|
+
"type": "number",
|
|
46
|
+
"title": "Long-poll seconds",
|
|
47
|
+
"description": "When the mod's live watch keeps failing it falls back to one-shot long-polls (devorch run wait --seconds N). 5 to 25 (the server's limit), default 25. DEVORCH_LONG_POLL_SECONDS in the environment wins over this.",
|
|
48
|
+
"required": false,
|
|
49
|
+
"default": 25
|
|
22
50
|
}
|
|
23
51
|
}
|
|
24
52
|
}
|
|
@@ -5,7 +5,7 @@ A self-contained Claude Code plugin for driving DevOrch runs from any repository
|
|
|
5
5
|
| Piece | Path | What it is |
|
|
6
6
|
|---|---|---|
|
|
7
7
|
| `/devorch-companion:sdlc-drive` | `skills/sdlc-drive/` | Claim an assigned tracker issue, start an SDLC run, drive it (Interactive or `--headless`). |
|
|
8
|
-
| `/devorch-companion:devorch-step` | `skills/devorch-step/` | Process
|
|
8
|
+
| `/devorch-companion:devorch-step` | `skills/devorch-step/` | Process a run's next instruction and keep going; the mod wakes it between instructions (push), or `/loop` does (poll). |
|
|
9
9
|
| `devorch-companion:devorch-step-worker` | `agents/` | The subagent that does one instruction's work in a fresh context. |
|
|
10
10
|
| MCP server `devorch` | `.mcp.json` | `devorch companion mcp`: the CLI's stdio MCP server (full profile, no admin band). Tools read `mcp__plugin_devorch-companion_devorch__<tool>`. |
|
|
11
11
|
| The mod | `hooks/` | Watches a run with `devorch run watch <runId>`, shows its position and open blockers in a status line, and wakes an idle session with `/devorch-companion:devorch-step <runId>` the moment the run can move, so an interactive run no longer polls. |
|
|
@@ -48,6 +48,47 @@ After upgrading the CLI, run `devorch companion install` again, then
|
|
|
48
48
|
`DEVORCH_EXE` (or the plugin's `devorchExe` setting) overrides the executable the mod runs; the MCP server always runs
|
|
49
49
|
the one `companion install` recorded.
|
|
50
50
|
|
|
51
|
+
## Wake modes
|
|
52
|
+
|
|
53
|
+
Between instructions an interactive run needs something to wake the session: a worker is running, or the run is
|
|
54
|
+
waiting on a human. Two mechanisms, and exactly one owns the wake at a time:
|
|
55
|
+
|
|
56
|
+
- **push** (realtime): the mod watches the run and submits `/devorch-companion:devorch-step <runId>` within seconds of
|
|
57
|
+
it becoming actionable. `sdlc-drive` runs the step skill **once, with no `/loop`**, and the step skill schedules no
|
|
58
|
+
wakeups. After a worker hands back, the step skill goes straight on to the next instruction in the same turn.
|
|
59
|
+
- **poll** (timed): `sdlc-drive` runs `/loop /devorch-companion:devorch-step <runId>` and the step skill keeps its own
|
|
60
|
+
`ScheduleWakeup`s: `retryAfterSeconds` on a `WAIT`, and a safety-net wakeup while a worker runs.
|
|
61
|
+
|
|
62
|
+
The `devorch_companion` tool's `status` and `watch` answers carry the resolved policy, which is the one field the skills
|
|
63
|
+
branch on:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
"wake": { "mode": "auto", "effective": "push", "owner": "companion", "fallbackWakeupSeconds": 1800, "reason": "..." }
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`effective` is `push`, `poll`, or `unavailable` (`wakeMode` is `push` but the companion is unhealthy: the skill reports
|
|
70
|
+
`reason` and stops). `status` also returns `config`: each setting's value, its source (`env`, `option` or `default`)
|
|
71
|
+
and any warnings.
|
|
72
|
+
|
|
73
|
+
| Setting (plugin option) | Environment override | Default | Values |
|
|
74
|
+
|---|---|---|---|
|
|
75
|
+
| `wakeMode` | `DEVORCH_WAKE_MODE` | `auto` | `auto`: push while the companion is healthy, else poll. `push`: the companion only; unhealthy means report and stop, never poll. `poll`: always `/loop` + `ScheduleWakeup`; the mod still shows the status line (with `wake: poll`) but submits no wakes and reports `healthy: false`. An unknown value is `auto`, with a warning in `status`. |
|
|
76
|
+
| `fallbackWakeupSeconds` | `DEVORCH_FALLBACK_WAKEUP_SECONDS` | `1800` | The safety-net `ScheduleWakeup` under poll while a worker runs, and after a `WAIT` with no `retryAfterSeconds`. Clamped to 60..3600. |
|
|
77
|
+
| `longPollSeconds` | `DEVORCH_LONG_POLL_SECONDS` | `25` | The mod's rung-3 fallback (`devorch run wait --seconds N`, used only when the live watch keeps failing). Clamped to 5..25, the server's limit. |
|
|
78
|
+
|
|
79
|
+
Each setting resolves **environment variable, then plugin option, then default**; the first one that is set (not
|
|
80
|
+
empty) decides. Set the options with `/plugin configure devorch-companion@devorch-cli` (or the `/config` menu), or with
|
|
81
|
+
`claude plugin configure devorch-companion@devorch-cli --values-stdin`. The environment variables win because a
|
|
82
|
+
project-scope plugin option may not apply while a project's `env` does, so to pin a mode for one repository put it in
|
|
83
|
+
that project's `.claude/settings.json`:
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{ "env": { "DEVORCH_WAKE_MODE": "poll" } }
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
A new setting takes effect when the mod reloads (a changed option reloads it; an environment change needs a new
|
|
90
|
+
session).
|
|
91
|
+
|
|
51
92
|
## Design notes
|
|
52
93
|
|
|
53
94
|
- **Which `devorch` runs.** `devorch companion install` writes the executable it is running as into the plugin folder
|
|
@@ -65,8 +106,9 @@ the one `companion install` recorded.
|
|
|
65
106
|
- **Wake command.** Claude Code names plugin skills `/<plugin>:<skill>`. Before each wake the mod lists the session's
|
|
66
107
|
commands and submits `devorch-companion:devorch-step` whenever it is listed, even beside a project-level
|
|
67
108
|
`devorch-step` (this plugin's copy ships with the mod and the CLI, so they stay in step). It falls back to a listed
|
|
68
|
-
bare `devorch-step` only when the plugin's skill is missing. A rejected wake reads as `healthy: false`,
|
|
69
|
-
keeps its own `ScheduleWakeup
|
|
109
|
+
bare `devorch-step` only when the plugin's skill is missing. A rejected wake reads as `healthy: false`, so under
|
|
110
|
+
`auto` the next firing sees `wake.effective: poll` and the skill keeps its own `ScheduleWakeup` (it starts `/loop`
|
|
111
|
+
when it wasn't under one).
|
|
70
112
|
- **Tool names.** The skills name `mcp__plugin_devorch-companion_devorch__*` in `allowed-tools` and refer to verbs by
|
|
71
113
|
their bare name in the body ("the DevOrch MCP server's `get_next_instruction`"), so any DevOrch MCP server with the
|
|
72
114
|
same tools also works. Keep the server key `devorch`: renaming it renames every tool.
|
|
@@ -106,7 +148,7 @@ Sign in once for that URL: `devorch login --base-url http://localhost:8700` (pas
|
|
|
106
148
|
| Piece | File | Status |
|
|
107
149
|
|---|---|---|
|
|
108
150
|
| Envelope parsing, NDJSON framing, generic event hook, wake decision, source ladder, CLI handshake, band text | `hooks/core.ts` | built, tested |
|
|
109
|
-
| Supervision decisions: exit-code mapping (unknown -> rung 4), rung-3 backoff, heal/retry timers, pending-wake expiry, position dedupe, hand-back wake, terminal rule, watch cap, exe and base-URL resolution, multi-run status, `healthy
|
|
151
|
+
| Supervision decisions: exit-code mapping (unknown -> rung 4), rung-3 backoff, heal/retry timers, pending-wake expiry, position dedupe, hand-back wake, terminal rule, watch cap, exe and base-URL resolution, multi-run status, `healthy`, wake settings (env > option > default) and the wake policy | `hooks/supervision.ts` | built, tested |
|
|
110
152
|
| CLI option contract (R12): `test/cli-options.json`, checked by the mod tests and by `CompanionArgvContractTests` (C#) | `test/` | built, tested |
|
|
111
153
|
| `register.ts`: the adapter over `$` (process spawn, turn tracking, `$.command.run`, status line, `/devorch-watch`, `/devorch-unwatch`, `/devorch-answer`, tool `devorch_companion`, `$.devorch.on` for other plugins) | `hooks/register.ts` | built; **behaviour unverified until the Windows spike** (`sdlc/devorch-companion-mod-platform-events/implement/spike-tq27.md`) and QA |
|
|
112
154
|
| `.claude-plugin/plugin.json`, `hooks/hooks.json`, marketplace manifest | `.claude-plugin/`, `../.claude-plugin/` | built |
|
|
@@ -116,7 +158,7 @@ Sign in once for that URL: `devorch login --base-url http://localhost:8700` (pas
|
|
|
116
158
|
The spike still decides three things the adapter assumes: that `$.process.spawn` of the native `devorch.exe` shows no
|
|
117
159
|
console window on Windows, which event marks the end of a main-loop turn, and that
|
|
118
160
|
`$.command.run({command: "devorch-companion:devorch-step"})` queues until idle and rejects an unknown command. Every host failure
|
|
119
|
-
reads as `healthy: false`, so the skills fall back to `ScheduleWakeup` rather than stalling.
|
|
161
|
+
reads as `healthy: false`, so under `wakeMode: auto` the skills fall back to `ScheduleWakeup` rather than stalling.
|
|
120
162
|
|
|
121
163
|
## Tests
|
|
122
164
|
|
|
@@ -215,6 +215,8 @@ export interface WakeInputs {
|
|
|
215
215
|
wakePending: boolean
|
|
216
216
|
/** The latest run.position envelope for the watched run. */
|
|
217
217
|
latest: PlatformEventEnvelope | null
|
|
218
|
+
/** False under `wakeMode: poll`: the skill owns the wake, so the mod submits none (default true). */
|
|
219
|
+
modWakes?: boolean
|
|
218
220
|
}
|
|
219
221
|
|
|
220
222
|
export type WakeDecision =
|
|
@@ -246,6 +248,7 @@ export function decideWake(i: WakeInputs): WakeDecision {
|
|
|
246
248
|
* or null when the session may be woken and `watchedRunId` and `latest` are set. */
|
|
247
249
|
function sessionHold(i: WakeInputs): WakeDecision | null {
|
|
248
250
|
if (!i.watchedRunId) return { wake: false, reason: 'no run watched' }
|
|
251
|
+
if (i.modWakes === false) return { wake: false, reason: 'wakeMode poll: the skill owns the wake' }
|
|
249
252
|
if (i.stopHookArmed) return { wake: false, reason: 'Stop-hook host armed' }
|
|
250
253
|
if (i.turnRunning) return { wake: false, reason: 'turn running; re-evaluate when idle' }
|
|
251
254
|
if (i.idleForMs !== null && i.idleForMs < SETTLE_MS)
|
|
@@ -6,9 +6,10 @@ import {
|
|
|
6
6
|
} from './core.ts'
|
|
7
7
|
import {
|
|
8
8
|
HEAL_MS, LOG_MAX_BYTES, WAKE_EXPIRY_MS, afterPoll, afterWakeClaimed, afterWakeExpired, afterWatchExit,
|
|
9
|
-
answerStdinArgv, canWatch, dedupe, handBackWake, health, isBaseUrl, logLine,
|
|
10
|
-
|
|
11
|
-
updateHint, versionArgv, waitArgv,
|
|
9
|
+
answerStdinArgv, canWatch, dedupe, handBackWake, health, isBaseUrl, logLine, modWakes, parseUnwatchArgs,
|
|
10
|
+
parseWatchArgs, pollTimeoutMs, resolveBaseUrl, resolveExe, resolveSettings, respawnDelayMs, restoreWatched, runStatus,
|
|
11
|
+
statusLine, terminalAction, tokenOf, updateHint, versionArgv, waitArgv, wakePolicy, watchArgv, type Settings,
|
|
12
|
+
type WakeHealth, type WatchEntry,
|
|
12
13
|
} from './supervision.ts'
|
|
13
14
|
|
|
14
15
|
/**
|
|
@@ -40,8 +41,6 @@ const TOOL = 'mcp__devorch-companion__devorch_companion'
|
|
|
40
41
|
const STOP_HOOK_MARKER = '.claude/hooks/interactive-loop/state/armed.json'
|
|
41
42
|
/** How long tool `watch` waits for the first envelope or child exit before it answers (D16). */
|
|
42
43
|
const FIRST_SIGNAL_MS = 5_000
|
|
43
|
-
/** A rung-3 `run wait` parks 25 s on the server; the process gets 10 s more. */
|
|
44
|
-
const POLL_TIMEOUT_MS = 35_000
|
|
45
44
|
|
|
46
45
|
type Run = {
|
|
47
46
|
entry: WatchEntry
|
|
@@ -82,6 +81,8 @@ export const register: Register = (on, options) => {
|
|
|
82
81
|
let wakeHealth: WakeHealth = { misses: 0, wakeBroken: false }
|
|
83
82
|
let turnRunning = false
|
|
84
83
|
let lastTurnEnd: number | null = null
|
|
84
|
+
/** Wake mode and timing knobs: the plugin options now, refined with the DEVORCH_* environment at session start. */
|
|
85
|
+
let settings: Settings = resolveSettings({}, options)
|
|
85
86
|
/** Diagnostics for the status action: the last wake decision and how far the last submit got. */
|
|
86
87
|
const diag: { decision?: { at: number; wake: boolean; reason?: string }; submit?: { at: number; stage: string } } = {}
|
|
87
88
|
|
|
@@ -91,13 +92,29 @@ export const register: Register = (on, options) => {
|
|
|
91
92
|
// ---- pure views over the state (no host calls) ----------------------------------------------------------------
|
|
92
93
|
|
|
93
94
|
function healthOf(run: Run | null): { healthy: boolean; reason?: string } {
|
|
94
|
-
return health({
|
|
95
|
+
return health({
|
|
96
|
+
pollMode: settings.wakeMode === 'poll', cliOk: cli.ok, cliReason: cli.reason, stopHookArmed,
|
|
97
|
+
wakeBroken: wakeHealth.wakeBroken, rung: run ? run.ladder.rung : null,
|
|
98
|
+
})
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** The effective wake policy the skills branch on (`wake.effective`). */
|
|
102
|
+
function wakeOf(run: Run | null): ReturnType<typeof wakePolicy> {
|
|
103
|
+
return wakePolicy(settings.wakeMode, healthOf(run), settings.fallbackWakeupSeconds)
|
|
95
104
|
}
|
|
96
105
|
|
|
97
106
|
function statusObject(runId?: string): Record<string, unknown> {
|
|
98
107
|
const asked = runId ? runs.get(runId) ?? null : null
|
|
99
108
|
return {
|
|
100
109
|
...healthOf(asked),
|
|
110
|
+
wake: wakeOf(asked),
|
|
111
|
+
config: {
|
|
112
|
+
wakeMode: settings.wakeMode,
|
|
113
|
+
fallbackWakeupSeconds: settings.fallbackWakeupSeconds,
|
|
114
|
+
longPollSeconds: settings.longPollSeconds,
|
|
115
|
+
sources: settings.sources,
|
|
116
|
+
warnings: settings.warnings,
|
|
117
|
+
},
|
|
101
118
|
cli: { ok: cli.ok, version: cli.version, path: cli.exe },
|
|
102
119
|
stopHookArmed,
|
|
103
120
|
wakeBroken: wakeHealth.wakeBroken,
|
|
@@ -161,7 +178,8 @@ export const register: Register = (on, options) => {
|
|
|
161
178
|
|
|
162
179
|
function redraw(): void {
|
|
163
180
|
const views = [...runs.values()].map((r) => ({ runId: r.entry.runId, latest: r.latest, ladder: r.ladder }))
|
|
164
|
-
const
|
|
181
|
+
const hints = [cli.ok && cli.version ? updateHint(modVersion, cli.version) : null, settings.wakeMode === 'poll' ? 'wake: poll' : null]
|
|
182
|
+
const hint = hints.filter((h) => h !== null).join(' | ') || null
|
|
165
183
|
$.ui.status(cli.ok ? statusLine(views, stopHookArmed, hint) : `DevOrch: offline (${cli.reason})`)
|
|
166
184
|
}
|
|
167
185
|
|
|
@@ -171,7 +189,7 @@ export const register: Register = (on, options) => {
|
|
|
171
189
|
run.handedBack = false
|
|
172
190
|
return
|
|
173
191
|
}
|
|
174
|
-
if (handBackWake({ reportedHealthy: run.reportedHealthy, nowHealthy, stopHookArmed, handedBack: run.handedBack })) {
|
|
192
|
+
if (modWakes(settings.wakeMode) && handBackWake({ reportedHealthy: run.reportedHealthy, nowHealthy, stopHookArmed, handedBack: run.handedBack })) {
|
|
175
193
|
run.handedBack = true
|
|
176
194
|
run.reportedHealthy = false
|
|
177
195
|
$.clock.after(0, () => void submit(run.entry.runId, 'hand-back'))
|
|
@@ -204,6 +222,7 @@ export const register: Register = (on, options) => {
|
|
|
204
222
|
stopHookArmed,
|
|
205
223
|
wakePending: run.pendingWake,
|
|
206
224
|
latest: run.latest,
|
|
225
|
+
modWakes: modWakes(settings.wakeMode),
|
|
207
226
|
})
|
|
208
227
|
diag.decision = { at: now(), wake: decision.wake, ...(decision.wake ? {} : { reason: decision.reason }) }
|
|
209
228
|
if (decision.wake) {
|
|
@@ -382,7 +401,8 @@ export const register: Register = (on, options) => {
|
|
|
382
401
|
let exitCode = 75
|
|
383
402
|
let stdout = ''
|
|
384
403
|
try {
|
|
385
|
-
const
|
|
404
|
+
const argv = waitArgv(exe, run.entry.runId, run.entry.baseUrl, run.lastToken, settings.longPollSeconds)
|
|
405
|
+
const r = await $.process.run(argv, { timeoutMs: pollTimeoutMs(settings.longPollSeconds) })
|
|
386
406
|
exitCode = r.exitCode
|
|
387
407
|
stdout = r.stdout
|
|
388
408
|
} catch {
|
|
@@ -555,6 +575,18 @@ export const register: Register = (on, options) => {
|
|
|
555
575
|
ops = { watch, unwatch, firstSignal, evaluateAll, answer, shutdown }
|
|
556
576
|
|
|
557
577
|
void (async () => {
|
|
578
|
+
try {
|
|
579
|
+
// The DEVORCH_* variables win over the plugin options (project-scope options may not apply; project `env` does).
|
|
580
|
+
// Literal names: the host lists the variables a module reads. Keep them equal to supervision's SETTING_ENV.
|
|
581
|
+
settings = resolveSettings({
|
|
582
|
+
wakeMode: (await $.env.get('DEVORCH_WAKE_MODE')) ?? undefined,
|
|
583
|
+
fallbackWakeupSeconds: (await $.env.get('DEVORCH_FALLBACK_WAKEUP_SECONDS')) ?? undefined,
|
|
584
|
+
longPollSeconds: (await $.env.get('DEVORCH_LONG_POLL_SECONDS')) ?? undefined,
|
|
585
|
+
}, options)
|
|
586
|
+
for (const w of settings.warnings) $.ui.toast(`DevOrch: ${w}`)
|
|
587
|
+
} catch {
|
|
588
|
+
// keep the option-only settings
|
|
589
|
+
}
|
|
558
590
|
try {
|
|
559
591
|
const env = await $.process.hookEnv()
|
|
560
592
|
pluginRoot = env.CLAUDE_PLUGIN_ROOT ?? ''
|
|
@@ -568,10 +600,12 @@ export const register: Register = (on, options) => {
|
|
|
568
600
|
await $.tool.register({
|
|
569
601
|
name: 'devorch_companion',
|
|
570
602
|
description:
|
|
571
|
-
'The DevOrch companion mod. status {runId?}:
|
|
572
|
-
'
|
|
573
|
-
'
|
|
574
|
-
'
|
|
603
|
+
'The DevOrch companion mod. status {runId?}: the wake policy for the run in `wake` (effective "push": the ' +
|
|
604
|
+
'companion wakes this session, run the step once and schedule nothing; "poll": the skill drives /loop + ' +
|
|
605
|
+
'ScheduleWakeup with wake.fallbackWakeupSeconds; "unavailable": wakeMode push but the companion is ' +
|
|
606
|
+
'unhealthy, report and stop), plus healthy, config and each watched run\'s rung, control, lease and open ' +
|
|
607
|
+
'blocker refs. watch {runId, baseUrl?}: arm the watch for a run this session drives (answers after the ' +
|
|
608
|
+
'first event, at most 5 s, with the same wake field). unwatch {runId}: stop.',
|
|
575
609
|
inputSchema: {
|
|
576
610
|
type: 'object',
|
|
577
611
|
properties: {
|
|
@@ -657,7 +691,7 @@ export const register: Register = (on, options) => {
|
|
|
657
691
|
await ops.firstSignal(run)
|
|
658
692
|
const h = healthOf(run)
|
|
659
693
|
run.reportedHealthy = h.healthy
|
|
660
|
-
return reply({ watching: runs.has(runId), ...h })
|
|
694
|
+
return reply({ watching: runs.has(runId), ...h, wake: wakePolicy(settings.wakeMode, h, settings.fallbackWakeupSeconds) })
|
|
661
695
|
}
|
|
662
696
|
if (input.action === 'unwatch') {
|
|
663
697
|
await ops.unwatch(String(input.runId ?? ''))
|
|
@@ -32,7 +32,7 @@ export const CLI_OPTIONS = {
|
|
|
32
32
|
|
|
33
33
|
export type CliCommand = keyof typeof CLI_OPTIONS
|
|
34
34
|
|
|
35
|
-
/** Rung-3 long-poll length in seconds
|
|
35
|
+
/** Rung-3 long-poll length in seconds by default: the server's park limit (the CLI accepts 0-25). */
|
|
36
36
|
export const WAIT_SECONDS = 25
|
|
37
37
|
|
|
38
38
|
/** `devorch run watch <runId> --base-url <url> [--since <token>]`: the long-lived child (rungs 1-2, D15). */
|
|
@@ -41,10 +41,17 @@ export function watchArgv(exe: string, runId: string, baseUrl: string, since: st
|
|
|
41
41
|
return [exe, 'run', 'watch', runId, '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
|
|
42
42
|
}
|
|
43
43
|
|
|
44
|
-
/** `devorch run wait <runId> --seconds
|
|
45
|
-
|
|
44
|
+
/** `devorch run wait <runId> --seconds <n> --base-url <url> [--since <token>]`: one rung-3 long-poll (D5). `seconds`
|
|
45
|
+
* is the `longPollSeconds` setting, clamped again here so a bad value can never reach argv. */
|
|
46
|
+
export function waitArgv(exe: string, runId: string, baseUrl: string, since: string | null, seconds: number = WAIT_SECONDS): string[] {
|
|
46
47
|
assertRunId(runId)
|
|
47
|
-
|
|
48
|
+
const s = clampInt(seconds, LONG_POLL_RANGE[0], LONG_POLL_RANGE[1], WAIT_SECONDS)
|
|
49
|
+
return [exe, 'run', 'wait', runId, '--seconds', String(s), '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** How long the mod lets one `run wait` process live: its park time plus 10 s. */
|
|
53
|
+
export function pollTimeoutMs(longPollSeconds: number): number {
|
|
54
|
+
return (clampInt(longPollSeconds, LONG_POLL_RANGE[0], LONG_POLL_RANGE[1], WAIT_SECONDS) + 10) * 1_000
|
|
48
55
|
}
|
|
49
56
|
|
|
50
57
|
/** Append the run's base URL (D14). */
|
|
@@ -302,6 +309,9 @@ export function updateHint(modVersion: string, cliVersion: string): string | nul
|
|
|
302
309
|
// ---- health (D6) ----------------------------------------------------------------------------------------------
|
|
303
310
|
|
|
304
311
|
export interface HealthInputs {
|
|
312
|
+
/** `wakeMode` is `poll`: the skill owns the wake, so the mod never reports itself healthy (an older skill copy that
|
|
313
|
+
* branches on `healthy` then keeps its own wakeup). */
|
|
314
|
+
pollMode?: boolean
|
|
305
315
|
cliOk: boolean
|
|
306
316
|
cliReason: string
|
|
307
317
|
stopHookArmed: boolean
|
|
@@ -317,9 +327,129 @@ export function health(i: HealthInputs): { healthy: boolean; reason?: string } {
|
|
|
317
327
|
if (i.stopHookArmed) return { healthy: false, reason: 'Stop-hook host armed' }
|
|
318
328
|
if (i.wakeBroken) return { healthy: false, reason: 'wake mechanism broken' }
|
|
319
329
|
if (i.rung === 4) return { healthy: false, reason: 'run offline (rung 4)' }
|
|
330
|
+
if (i.pollMode) return { healthy: false, reason: 'wakeMode poll: the skill owns the wake' }
|
|
320
331
|
return { healthy: true }
|
|
321
332
|
}
|
|
322
333
|
|
|
334
|
+
// ---- wake modes: who wakes an interactive run, and the settings behind it --------------------------------------
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* `auto` (default): the companion wakes the session while it is healthy, else the skill polls with `/loop` and
|
|
338
|
+
* `ScheduleWakeup`. `push`: the companion only; when it is unhealthy the skill reports that and stops instead of
|
|
339
|
+
* polling. `poll`: never rely on the companion's wake (the mod submits none; it still shows the status line).
|
|
340
|
+
*/
|
|
341
|
+
export const WAKE_MODES = ['auto', 'push', 'poll'] as const
|
|
342
|
+
export type WakeMode = (typeof WAKE_MODES)[number]
|
|
343
|
+
|
|
344
|
+
export const FALLBACK_WAKEUP_DEFAULT = 1800
|
|
345
|
+
export const FALLBACK_WAKEUP_RANGE = [60, 3600] as const
|
|
346
|
+
export const LONG_POLL_RANGE = [5, WAIT_SECONDS] as const
|
|
347
|
+
|
|
348
|
+
export type SettingSource = 'env' | 'option' | 'default'
|
|
349
|
+
|
|
350
|
+
/** The environment variable that overrides each plugin option. It wins, because project-scope plugin options may not
|
|
351
|
+
* apply while a project's settings `env` does. */
|
|
352
|
+
export const SETTING_ENV = {
|
|
353
|
+
wakeMode: 'DEVORCH_WAKE_MODE',
|
|
354
|
+
fallbackWakeupSeconds: 'DEVORCH_FALLBACK_WAKEUP_SECONDS',
|
|
355
|
+
longPollSeconds: 'DEVORCH_LONG_POLL_SECONDS',
|
|
356
|
+
} as const
|
|
357
|
+
|
|
358
|
+
export type SettingName = keyof typeof SETTING_ENV
|
|
359
|
+
|
|
360
|
+
export interface Settings {
|
|
361
|
+
wakeMode: WakeMode
|
|
362
|
+
/** The skill's safety-net `ScheduleWakeup` under poll, in seconds. */
|
|
363
|
+
fallbackWakeupSeconds: number
|
|
364
|
+
/** Rung-3 `devorch run wait --seconds`. */
|
|
365
|
+
longPollSeconds: number
|
|
366
|
+
/** Where each value came from. */
|
|
367
|
+
sources: Record<SettingName, SettingSource>
|
|
368
|
+
/** Invalid or clamped values, reported in the tool's `status` (never fatal). */
|
|
369
|
+
warnings: string[]
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/**
|
|
373
|
+
* Resolve the wake settings. Per setting, the first non-empty of the `DEVORCH_*` environment variable, the plugin
|
|
374
|
+
* option, then the default. An unknown mode falls back to `auto` and a non-number to its default, each with a
|
|
375
|
+
* warning; a number outside its range is clamped, with a warning.
|
|
376
|
+
*/
|
|
377
|
+
export function resolveSettings(env: Partial<Record<SettingName, string | undefined>>, options: Partial<Record<SettingName, unknown>> | undefined): Settings {
|
|
378
|
+
const warnings: string[] = []
|
|
379
|
+
const pick = (name: SettingName): { value: unknown; source: SettingSource } => {
|
|
380
|
+
if (present(env[name])) return { value: env[name], source: 'env' }
|
|
381
|
+
if (present(options?.[name])) return { value: options?.[name], source: 'option' }
|
|
382
|
+
return { value: undefined, source: 'default' }
|
|
383
|
+
}
|
|
384
|
+
const label = (name: SettingName, source: SettingSource): string => (source === 'env' ? SETTING_ENV[name] : `option ${name}`)
|
|
385
|
+
|
|
386
|
+
const mode = pick('wakeMode')
|
|
387
|
+
let wakeMode: WakeMode = 'auto'
|
|
388
|
+
if (mode.source !== 'default') {
|
|
389
|
+
const v = String(mode.value).trim().toLowerCase()
|
|
390
|
+
if ((WAKE_MODES as readonly string[]).includes(v)) wakeMode = v as WakeMode
|
|
391
|
+
else warnings.push(`${label('wakeMode', mode.source)}: unknown wake mode "${String(mode.value).trim().slice(0, 20)}"; using auto`)
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
const number = (name: SettingName, range: readonly [number, number], fallback: number): { value: number; source: SettingSource } => {
|
|
395
|
+
const p = pick(name)
|
|
396
|
+
if (p.source === 'default') return { value: fallback, source: 'default' }
|
|
397
|
+
const n = typeof p.value === 'number' ? p.value : Number(String(p.value).trim())
|
|
398
|
+
if (!Number.isFinite(n)) {
|
|
399
|
+
warnings.push(`${label(name, p.source)}: not a number; using ${fallback}`)
|
|
400
|
+
return { value: fallback, source: p.source }
|
|
401
|
+
}
|
|
402
|
+
const clamped = clampInt(n, range[0], range[1], fallback)
|
|
403
|
+
if (clamped !== n) warnings.push(`${label(name, p.source)}: ${n} is outside ${range[0]}..${range[1]}; using ${clamped}`)
|
|
404
|
+
return { value: clamped, source: p.source }
|
|
405
|
+
}
|
|
406
|
+
const fallback = number('fallbackWakeupSeconds', FALLBACK_WAKEUP_RANGE, FALLBACK_WAKEUP_DEFAULT)
|
|
407
|
+
const longPoll = number('longPollSeconds', LONG_POLL_RANGE, WAIT_SECONDS)
|
|
408
|
+
|
|
409
|
+
return {
|
|
410
|
+
wakeMode,
|
|
411
|
+
fallbackWakeupSeconds: fallback.value,
|
|
412
|
+
longPollSeconds: longPoll.value,
|
|
413
|
+
sources: { wakeMode: mode.source, fallbackWakeupSeconds: fallback.source, longPollSeconds: longPoll.source },
|
|
414
|
+
warnings,
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
export interface WakePolicy {
|
|
419
|
+
mode: WakeMode
|
|
420
|
+
/** `push`: the companion wakes the session (run the step once, no /loop, schedule nothing). `poll`: the skill wakes
|
|
421
|
+
* itself (/loop + ScheduleWakeup). `unavailable`: `push` was asked for but the companion is unhealthy; the skill
|
|
422
|
+
* reports it and stops. */
|
|
423
|
+
effective: 'push' | 'poll' | 'unavailable'
|
|
424
|
+
owner: 'companion' | 'skill' | 'none'
|
|
425
|
+
fallbackWakeupSeconds: number
|
|
426
|
+
reason: string
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** The one field the skills branch on: the configured mode resolved against the companion's health right now. */
|
|
430
|
+
export function wakePolicy(mode: WakeMode, h: { healthy: boolean; reason?: string }, fallbackWakeupSeconds: number): WakePolicy {
|
|
431
|
+
const base = { mode, fallbackWakeupSeconds }
|
|
432
|
+
if (mode === 'poll') return { ...base, effective: 'poll', owner: 'skill', reason: 'wakeMode poll: /loop + ScheduleWakeup' }
|
|
433
|
+
if (h.healthy) return { ...base, effective: 'push', owner: 'companion', reason: 'the companion is healthy and wakes the session' }
|
|
434
|
+
const why = h.reason ?? 'companion unhealthy'
|
|
435
|
+
if (mode === 'push') return { ...base, effective: 'unavailable', owner: 'none', reason: `wakeMode push, but ${why}` }
|
|
436
|
+
return { ...base, effective: 'poll', owner: 'skill', reason: `companion unhealthy (${why}); the skill polls` }
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
/** Whether the mod itself submits wakes (position-change and hand-back): every mode but `poll`. */
|
|
440
|
+
export function modWakes(mode: WakeMode): boolean {
|
|
441
|
+
return mode !== 'poll'
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
function present(v: unknown): boolean {
|
|
445
|
+
return (typeof v === 'string' && v.trim().length > 0) || (typeof v === 'number' && !Number.isNaN(v))
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
function clampInt(n: number, min: number, max: number, fallback: number): number {
|
|
449
|
+
if (!Number.isFinite(n)) return fallback
|
|
450
|
+
return Math.min(max, Math.max(min, Math.round(n)))
|
|
451
|
+
}
|
|
452
|
+
|
|
323
453
|
// ---- the status line (D7) -------------------------------------------------------------------------------------
|
|
324
454
|
|
|
325
455
|
export interface RunView {
|
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: devorch-step
|
|
3
3
|
argument-hint: "<runId>"
|
|
4
|
-
description: Processes
|
|
4
|
+
description: Processes the next instruction of a DevOrch run by dispatching its work to a devorch-step-worker subagent, keeping the main thread as a thin orchestrator; the companion mod wakes it for the next one (push) or /loop does (poll). TRIGGERS - devorch step, next devorch step, step this run, loop devorch run. USE WHEN - driving a DevOrch SDLC run one instruction at a time with /devorch-companion:devorch-step <runId>, woken by the companion mod or repeated with /loop /devorch-companion:devorch-step <runId>.
|
|
5
5
|
allowed-tools: mcp__plugin_devorch-companion_devorch__get_next_instruction, mcp__plugin_devorch-companion_devorch__apply_instruction_result, mcp__plugin_devorch-companion_devorch__get_run_position, mcp__plugin_devorch-companion_devorch__raise_blocker, mcp__devorch-companion__devorch_companion, Bash(uv run scripts/worktree_manage.py *), Bash(uv run scripts/app_run.py *)
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# DevOrch Step
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
10
|
+
`/devorch-companion:devorch-step <runId>` processes the run's next instruction and, after the worker hands back, goes
|
|
11
|
+
straight on to the one after. Between instructions that can't start yet (a worker running, a `WAIT`), something
|
|
12
|
+
must wake the session again: the companion mod (**push**, realtime) or `/loop` with `ScheduleWakeup` (**poll**, timed).
|
|
13
|
+
The **Wake** check below decides which, on every firing.
|
|
12
14
|
|
|
13
15
|
**The main thread only orchestrates.** Never read stage docs, source files or the context bundle here, and never
|
|
14
16
|
call `get_context_for_instruction`. The worker does all of that. The only output per instruction is one status line.
|
|
@@ -19,6 +21,27 @@ call `get_context_for_instruction`. The worker does all of that. The only output
|
|
|
19
21
|
server this session has (for example `mcp__devorch-local-mcp__<verb>`); never mix two servers within one run, because
|
|
20
22
|
they may point at different backends.
|
|
21
23
|
|
|
24
|
+
## Wake: check it at the start of every firing
|
|
25
|
+
|
|
26
|
+
Exactly one thing wakes this session for a run. Before anything else in a firing (a launch, a wake from the mod, a
|
|
27
|
+
`/loop` tick or a worker's hand-back):
|
|
28
|
+
|
|
29
|
+
1. If the companion tool `mcp__devorch-companion__devorch_companion` exists, call it with `{action: "watch", runId}`.
|
|
30
|
+
Re-watching a watched run is cheap and answers at once. Add `baseUrl` only when this run lives on a different
|
|
31
|
+
server from the plugin's `apiBase` setting (or `DEVORCH_API_BASE`), such as a worktree slot
|
|
32
|
+
`http://localhost:8704`. Read **`wake.effective`** and `wake.fallbackWakeupSeconds` from the answer. Don't
|
|
33
|
+
re-derive the policy from `healthy`.
|
|
34
|
+
2. No companion tool: treat it as `poll` with a 1800-second fallback.
|
|
35
|
+
3. Hold that value for the rest of the firing:
|
|
36
|
+
|
|
37
|
+
| `wake.effective` | Who wakes the session | What this firing does about it |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| `push` | The companion mod: it submits `/devorch-companion:devorch-step <runId>` within seconds of the run becoming actionable (a blocker answered, a lease freed or lapsed, the run finished), and hands the wake back once if it turns unhealthy. | **Schedule no wakeup, anywhere.** If this firing runs under `/loop`, stop the loop once (`ScheduleWakeup(stop: true)`) and say in one line that the companion owns the wake now; then carry on. |
|
|
40
|
+
| `poll` | You: `ScheduleWakeup` under `/loop`. | Schedule the wakeups named below. If this firing is not under `/loop` (no `ScheduleWakeup` to call), start `/loop /devorch-companion:devorch-step <runId>` at the point where a wakeup is due instead, and end the turn; its first firing picks up from there. |
|
|
41
|
+
| `unavailable` | Nobody: `wakeMode` is `push` but the companion is unhealthy. | Finish a worker's hand-back if this firing is one (steps 5 to 7, so no work is lost), then launch nothing: print `wake.reason`, say `/devorch-companion:devorch-step <runId>` resumes the run once the companion is fixed (or `wakeMode` is set to `auto`/`poll`), stop any `/loop` with `ScheduleWakeup(stop: true)`, and end the turn. |
|
|
42
|
+
|
|
43
|
+
"Schedule a wakeup" below always means: under `poll` only, as this table says.
|
|
44
|
+
|
|
22
45
|
## A firing has two halves
|
|
23
46
|
|
|
24
47
|
Subagents run asynchronously, so one instruction spans two turns: **launch** ends the turn, and the worker's
|
|
@@ -27,7 +50,8 @@ hand-back starts **finish**.
|
|
|
27
50
|
### Launch
|
|
28
51
|
|
|
29
52
|
1. **Don't double-dispatch.** If a worker launched in this session for this run hasn't handed back, launch nothing.
|
|
30
|
-
Under
|
|
53
|
+
Under `poll`, schedule another fallback wakeup (`wake.fallbackWakeupSeconds`); under `push`, schedule nothing.
|
|
54
|
+
End the turn.
|
|
31
55
|
2. Call `get_next_instruction(runId, driverId)` and branch on `control`. `driverId` is this session's id
|
|
32
56
|
(`$CLAUDE_CODE_SESSION_ID`); use the same value on `apply_instruction_result`, because the instruction is leased
|
|
33
57
|
to it. Pass the **bare** id: the envelope's `lease.holder` reads `driver:<id>` because the server adds that prefix
|
|
@@ -37,19 +61,10 @@ hand-back starts **finish**.
|
|
|
37
61
|
| `control` | Action |
|
|
38
62
|
|---|---|
|
|
39
63
|
| `DONE` / `ESCALATE` / `ABORT` | PushNotification with the outcome and `reason`. Under `/loop`, `ScheduleWakeup(stop: true)`. Never self-heal. |
|
|
40
|
-
| `WAIT` | Print the `reason` and open blockers from `get_run_position`. Under
|
|
64
|
+
| `WAIT` | Print the `reason` and open blockers from `get_run_position`. Under `push`, end the turn: the mod wakes the session when the run can move. Under `poll`, schedule a wakeup after `retryAfterSeconds` (else `wake.fallbackWakeupSeconds`). |
|
|
41
65
|
| `CONTINUE` | Go to 3. |
|
|
42
66
|
|
|
43
|
-
|
|
44
|
-
`mcp__devorch-companion__devorch_companion` exists, then **only under `/loop`** (a one-off step arms nothing) call
|
|
45
|
-
it with `{action: "watch", runId}` once before the first wait, and then `{action: "status", runId}`. The mod
|
|
46
|
-
watches the server set by the plugin's `apiBase` setting (or `DEVORCH_API_BASE`), the same one the bundled MCP
|
|
47
|
-
server uses; add `baseUrl` only when this run lives somewhere else (a worktree slot such as
|
|
48
|
-
`http://localhost:8704` while the plugin points at another server). When the status reports the run
|
|
49
|
-
`healthy: true`, the companion mod owns the wake: schedule **no** wakeup and end the turn; the mod submits
|
|
50
|
-
`/devorch-companion:devorch-step <runId>` within seconds of the run becoming actionable (a blocker answered, a lease
|
|
51
|
-
freed). When the tool is absent or reports `healthy: false` (watch child down, CLI too old), schedule the wakeup
|
|
52
|
-
yourself. The answer to a blocker can be given from here with `/devorch-answer <slug> <ref> <answer>` (mod) or
|
|
67
|
+
The answer to a blocker can be given from here with `/devorch-answer <slug> <ref> <answer>` (mod) or
|
|
53
68
|
`devorch blocker answer <slug> <ref> --text ...` (CLI); never answer it yourself.
|
|
54
69
|
|
|
55
70
|
Re-fetching an instruction that was dispatched but never applied returns the same `instructionId`, so resuming
|
|
@@ -76,9 +91,9 @@ hand-back starts **finish**.
|
|
|
76
91
|
exact text, and don't blame driverId for an opaque failure.
|
|
77
92
|
```
|
|
78
93
|
|
|
79
|
-
Under
|
|
80
|
-
|
|
81
|
-
|
|
94
|
+
Under `poll`, first schedule a fallback wakeup of `wake.fallbackWakeupSeconds` (1800 by default) in case the
|
|
95
|
+
worker never hands back. Under `push`, schedule nothing: the mod wakes the session if the worker's instruction
|
|
96
|
+
lease lapses without a result.
|
|
82
97
|
|
|
83
98
|
### Finish (on the worker's hand-back)
|
|
84
99
|
|
|
@@ -86,12 +101,15 @@ hand-back starts **finish**.
|
|
|
86
101
|
the error appended. On a second failure, call `raise_blocker` with type `error` and treat the run as `WAIT`.
|
|
87
102
|
6. Call `apply_instruction_result(runId, instructionId, <result JSON>, driverId)`.
|
|
88
103
|
7. Print one line and nothing else about the work, such as `qa/execute DONE (pass 1) - 12/12 passed`.
|
|
89
|
-
8.
|
|
90
|
-
next instruction. A `CONTINUE` launches the next worker
|
|
91
|
-
terminal `control` is handled by the step 2 table
|
|
104
|
+
8. **Don't wait for a wakeup, with or without `/loop`: go straight back to Launch step 2 in this same turn** and fetch
|
|
105
|
+
the next instruction (after the Wake check, unless it said `unavailable`). A `CONTINUE` launches the next worker
|
|
106
|
+
now; a `WAIT` or terminal `control` is handled by the step 2 table. This is what keeps a push-driven run snappy:
|
|
107
|
+
the mod only has to wake the session when the run was waiting on something outside it.
|
|
92
108
|
|
|
93
109
|
## Anti-patterns
|
|
94
110
|
|
|
95
111
|
- Doing a step's work in the main thread.
|
|
96
112
|
- Echoing the worker's result, or a summary longer than the status line.
|
|
113
|
+
- Scheduling a wakeup, or starting `/loop`, while `wake.effective` is `push`: two wake owners fire twice.
|
|
114
|
+
- Polling when `wake.effective` is `unavailable`: the user chose push only.
|
|
97
115
|
- Merging to `main` during a run. That's a human confirmation after `DONE`.
|
|
@@ -14,8 +14,9 @@ terminal state** in one of two run modes.
|
|
|
14
14
|
|
|
15
15
|
This skill **does NOT implement the loop.** Both run modes wrap the **same `step_once` primitive**:
|
|
16
16
|
|
|
17
|
-
- **Interactive** (default, the headline demo) — `/
|
|
18
|
-
session
|
|
17
|
+
- **Interactive** (default, the headline demo) — `/devorch-companion:devorch-step` runs **inside this
|
|
18
|
+
session**, woken by the companion mod the moment the run can move (push), or under `/loop` when the mod can't
|
|
19
|
+
(poll); each step's work happens in a subagent, and you steer between steps.
|
|
19
20
|
- **Headless** (opt-in with `--headless`, the proven spine) — the loop runs **detached** in
|
|
20
21
|
`devorch run supervise` (fresh `claude -p` per step, `ANTHROPIC_API_KEY`-strip → guaranteed
|
|
21
22
|
subscription billing); you watch via the **portal**.
|
|
@@ -92,19 +93,32 @@ be blocked once that gate lands, then proceed. (SuperAdmin/system bypass; don't
|
|
|
92
93
|
|
|
93
94
|
#### Interactive (default — the headline demo)
|
|
94
95
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
`control` notifications (step 6).
|
|
96
|
+
The main thread only orchestrates: each instruction's work runs in a `devorch-step-worker` subagent, and the session
|
|
97
|
+
is idle between firings so the user can steer. `devorch-step` handles the terminal `control` notifications (step 6).
|
|
98
|
+
A project-level `/devorch-step` is the same skill where one exists.
|
|
99
99
|
|
|
100
|
-
**
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
100
|
+
**Pick the wake from the companion (DEV-47, DEV-56).** Exactly one thing wakes the session between firings: the
|
|
101
|
+
companion mod (push, realtime) or `/loop` with `ScheduleWakeup` (poll, timed). Decide once, from the mod:
|
|
102
|
+
|
|
103
|
+
1. If the companion tool `mcp__devorch-companion__devorch_companion` exists, call it with
|
|
104
|
+
`{action: "watch", runId: <runExternalId>}`; add `baseUrl` only when the run lives on a different server from
|
|
105
|
+
`<apiBase>` (for example a worktree slot). Read **`wake.effective`** from the answer and don't re-derive it from
|
|
106
|
+
`healthy`.
|
|
107
|
+
2. Branch on it:
|
|
108
|
+
|
|
109
|
+
| `wake.effective` | Start the run with |
|
|
110
|
+
|---|---|
|
|
111
|
+
| `push` | **`/devorch-companion:devorch-step <runExternalId>` once, with no `/loop`.** The mod submits the next firing itself whenever the run can move (a blocker answered, a lease freed, the run finished) and hands the wake back if it turns unhealthy. |
|
|
112
|
+
| `poll` | **`/loop /devorch-companion:devorch-step <runExternalId>`**, as before: the step skill schedules its own wakeups (`wake.fallbackWakeupSeconds` as the safety net). |
|
|
113
|
+
| `unavailable` | Nothing. `wakeMode` is `push` but the companion is unhealthy: tell the user `wake.reason`, and that `/devorch-companion:devorch-step <runExternalId>` resumes the run once it's fixed (or set `wakeMode` to `auto`/`poll`). Stop. |
|
|
114
|
+
|
|
115
|
+
**No companion tool:** use `poll`. The one exception is a user who set `wakeMode: push` (or `DEVORCH_WAKE_MODE=push`)
|
|
116
|
+
and said so: report that the companion is missing and stop.
|
|
117
|
+
|
|
118
|
+
The mode comes from the plugin's `wakeMode` setting (`auto` by default: push while the companion is healthy, else
|
|
119
|
+
poll), overridden by `DEVORCH_WAKE_MODE`; see the plugin README's "Wake modes". Blockers can be answered from the
|
|
120
|
+
session with `/devorch-answer <slug> <ref> <answer>` (mod) or `devorch blocker answer <slug> <ref> --text ...`;
|
|
121
|
+
headless `devorch run supervise` parks a WAIT on the server and resumes on its own.
|
|
108
122
|
|
|
109
123
|
> **Billing:** Interactive runs on your already-logged-in subscription — **no key-strip** (you launched
|
|
110
124
|
> Claude logged in). **Claude-only** for now.
|
|
@@ -156,8 +170,9 @@ A back-edge loop or quota-burning run must be stoppable from the operator side:
|
|
|
156
170
|
- **Headless:** `<devorch> run abort <runExternalId>` (the same binary as the supervisor, chosen as above) — reaps
|
|
157
171
|
the tracked headless `claude -p` children for the driver process (best-effort operator stop). Also stop the
|
|
158
172
|
backgrounded `supervise` task.
|
|
159
|
-
- **Interactive (in-session control):**
|
|
160
|
-
|
|
173
|
+
- **Interactive (in-session control):** unwatch the run with `/devorch-unwatch <runId>` so the companion submits no
|
|
174
|
+
further firing (push), and under `/loop` (poll) tell the session to stop the loop; it calls
|
|
175
|
+
`ScheduleWakeup(stop: true)`.
|
|
161
176
|
|
|
162
177
|
## Anti-patterns
|
|
163
178
|
|
|
@@ -31,9 +31,27 @@ export type DevorchRunStatus = {
|
|
|
31
31
|
pendingWake: boolean
|
|
32
32
|
}
|
|
33
33
|
|
|
34
|
+
/** Who wakes an interactive run: `push` the companion, `poll` the skill's /loop + ScheduleWakeup, `unavailable`
|
|
35
|
+
* wakeMode push with an unhealthy companion. */
|
|
36
|
+
export type DevorchWakePolicy = {
|
|
37
|
+
mode: 'auto' | 'push' | 'poll'
|
|
38
|
+
effective: 'push' | 'poll' | 'unavailable'
|
|
39
|
+
owner: 'companion' | 'skill' | 'none'
|
|
40
|
+
fallbackWakeupSeconds: number
|
|
41
|
+
reason: string
|
|
42
|
+
}
|
|
43
|
+
|
|
34
44
|
export type DevorchStatus = {
|
|
35
45
|
healthy: boolean
|
|
36
46
|
reason?: string
|
|
47
|
+
wake: DevorchWakePolicy
|
|
48
|
+
config: {
|
|
49
|
+
wakeMode: 'auto' | 'push' | 'poll'
|
|
50
|
+
fallbackWakeupSeconds: number
|
|
51
|
+
longPollSeconds: number
|
|
52
|
+
sources: Record<'wakeMode' | 'fallbackWakeupSeconds' | 'longPollSeconds', 'env' | 'option' | 'default'>
|
|
53
|
+
warnings: string[]
|
|
54
|
+
}
|
|
37
55
|
cli: { ok: boolean; version: string | null; path: string | null }
|
|
38
56
|
stopHookArmed: boolean
|
|
39
57
|
wakeBroken: boolean
|
package/bin/devorch
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@devorch/cli-linux-x64",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.21.0",
|
|
4
4
|
"description": "Dev Orchestrator CLI (devorch) prebuilt binary for linux-x64 (.NET RID linux-x64). Installed automatically by dev-orchestrator-cli; not meant to be installed directly.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"repository": {
|