@devorch/cli-linux-x64 0.10.0 → 0.12.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.
@@ -0,0 +1,407 @@
1
+ /**
2
+ * DevOrch companion mod: pure supervision logic for the `$` adapter (DEV-56, design-L0 D3-D8, D14-D18).
3
+ *
4
+ * Like `core.ts`, this file has no dependency on the Claude Code mod API: it is plain functions over plain data, so
5
+ * `node --test` covers every decision `register.ts` makes. `register.ts` only performs host calls (spawn, timers,
6
+ * `$.command.run`, the status line) and asks these functions what to do. Any branch on data that `register.ts` would
7
+ * need belongs here, with a test.
8
+ *
9
+ * Erasable TypeScript only (no enums, no parameter properties) so Node runs it without a build step.
10
+ */
11
+
12
+ import {
13
+ EXIT, MAX_RESTARTS, SETTLE_MS, afterChildExit, answerArgv, bandText, compareVersions, positionOf,
14
+ type LadderState, type PlatformEventEnvelope, type Rung,
15
+ } from './core.ts'
16
+
17
+ // ---- the CLI's argv language (R12: the one knowledge coupling between mod and CLI) --------------------------
18
+
19
+ /**
20
+ * Every option the mod passes to each CLI command it runs. Frozen: the same list is asserted by
21
+ * `CompanionArgvContractTests` in DevOrchestrator.Cli.Tests against the Cocona command definitions, so a renamed or
22
+ * removed option fails a test on either side instead of turning every spawn into a usage error.
23
+ */
24
+ export const CLI_OPTIONS = {
25
+ 'run watch': ['--since', '--base-url'],
26
+ 'run wait': ['--since', '--seconds', '--base-url'],
27
+ 'blocker answer': ['--stdin', '--json', '--base-url'],
28
+ version: ['--json'],
29
+ } as const satisfies Record<string, readonly string[]>
30
+
31
+ export type CliCommand = keyof typeof CLI_OPTIONS
32
+
33
+ /** Rung-3 long-poll length in seconds (the server's park limit). */
34
+ export const WAIT_SECONDS = 25
35
+
36
+ /** `devorch run watch <runId> --base-url <url> [--since <token>]`: the long-lived child (rungs 1-2, D15). */
37
+ export function watchArgv(exe: string, runId: string, baseUrl: string, since: string | null): string[] {
38
+ assertRunId(runId)
39
+ return [exe, 'run', 'watch', runId, '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
40
+ }
41
+
42
+ /** `devorch run wait <runId> --seconds 25 --base-url <url> [--since <token>]`: one rung-3 long-poll (D5). */
43
+ export function waitArgv(exe: string, runId: string, baseUrl: string, since: string | null): string[] {
44
+ assertRunId(runId)
45
+ return [exe, 'run', 'wait', runId, '--seconds', String(WAIT_SECONDS), '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
46
+ }
47
+
48
+ /** Append the run's base URL (D14). */
49
+ export function withBaseUrl(argv: readonly string[], baseUrl: string): string[] {
50
+ return [...argv, '--base-url', baseUrl]
51
+ }
52
+
53
+ /**
54
+ * `devorch blocker answer <slug> <ref> --stdin --json --base-url <url>`: the answer goes on the child's stdin, never in
55
+ * argv. Replaces design-L0's temp file: `$.fs` has no delete, so a temp file would leave the answer on disk. The
56
+ * slug and ref are validated by `core.answerArgv` (no leading '-', so neither can be read as an option).
57
+ */
58
+ export function answerStdinArgv(exe: string, slug: string, blockerRef: string, baseUrl: string): string[] {
59
+ if (!isBaseUrl(baseUrl)) throw new Error('invalid base URL')
60
+ const validated = answerArgv(exe, slug, blockerRef, 'stdin')
61
+ return [...validated.slice(0, 5), '--stdin', '--json', '--base-url', baseUrl]
62
+ }
63
+
64
+ export function versionArgv(exe: string): string[] {
65
+ return [exe, 'version', '--json']
66
+ }
67
+
68
+ /** The command (`run watch`, `version`, ...) and the options an argv uses, for the contract test. */
69
+ export function optionsOf(argv: readonly string[]): { command: string; options: string[] } {
70
+ const words = argv.slice(1)
71
+ const command = words[0] === 'run' || words[0] === 'blocker' ? `${words[0]} ${words[1]}` : (words[0] ?? '')
72
+ return { command, options: words.filter((w) => w.startsWith('--')) }
73
+ }
74
+
75
+ function assertRunId(runId: string): void {
76
+ if (!RUN_ID.test(runId)) throw new Error('not a run id')
77
+ }
78
+
79
+ const RUN_ID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
80
+
81
+ export function isRunId(value: unknown): value is string {
82
+ return typeof value === 'string' && RUN_ID.test(value)
83
+ }
84
+
85
+ // ---- exit codes (D5, R12) ------------------------------------------------------------------------------------
86
+
87
+ /** The exit codes the CLI documents for `run watch` / `run wait` (`core.EXIT` plus 1 for an unexpected failure). */
88
+ export const KNOWN_EXITS: readonly number[] = [EXIT.done, 1, EXIT.notFound, EXIT.transport, EXIT.auth]
89
+
90
+ /**
91
+ * The next rung after the watch child ended (rungs 1-2). Wraps `core.afterChildExit` with the one rule core lacks:
92
+ * an exit code outside the documented set (a Cocona usage error such as 64 or 129) is a bad argv, so it goes
93
+ * straight to rung 4 and never cycles through rungs 2 and 3. A kill (null) counts as an ordinary death.
94
+ */
95
+ export function afterWatchExit(state: LadderState, exitCode: number | null): LadderState {
96
+ if (exitCode !== null && !KNOWN_EXITS.includes(exitCode)) return { rung: 4, restarts: state.restarts, reason: `CLI usage error (exit ${exitCode})` }
97
+ return afterChildExit(state, exitCode)
98
+ }
99
+
100
+ /** Delay before respawning the watch child on rung 2: 1 s, 2 s, 4 s. */
101
+ export function respawnDelayMs(restarts: number): number {
102
+ return 1_000 * 2 ** Math.max(0, Math.min(restarts, MAX_RESTARTS) - 1)
103
+ }
104
+
105
+ /** Rung-3 backoff after a failed poll (exit 75 or 1): 5 s, 10 s, then 30 s. */
106
+ export const POLL_BACKOFF_MS = [5_000, 10_000, 30_000] as const
107
+
108
+ export type PollOutcome =
109
+ | { kind: 'line'; delayMs: 0; failures: 0 }
110
+ | { kind: 'retry'; delayMs: number; failures: number }
111
+ | { kind: 'offline'; reason: string }
112
+ | { kind: 'done' }
113
+
114
+ /**
115
+ * What a rung-3 poller does after one `run wait` returned. Exit 0 prints a line (handled by the caller; poll again at
116
+ * once, the CLI itself parks 25 s); 75 or 1 backs off; 77 or 66 go to rung 4; anything else is a usage error -> rung 4.
117
+ * Polls are strictly sequential: the next starts only after this one returned (no hot loop).
118
+ */
119
+ export function afterPoll(exitCode: number, failures: number): PollOutcome {
120
+ if (exitCode === EXIT.done) return { kind: 'line', delayMs: 0, failures: 0 }
121
+ if (exitCode === EXIT.transport || exitCode === 1) {
122
+ const delayMs = POLL_BACKOFF_MS[Math.min(failures, POLL_BACKOFF_MS.length - 1)] as number
123
+ return { kind: 'retry', delayMs, failures: failures + 1 }
124
+ }
125
+ if (exitCode === EXIT.auth) return { kind: 'offline', reason: 'devorch is not signed in (exit 77)' }
126
+ if (exitCode === EXIT.notFound) return { kind: 'offline', reason: 'run not found or server too old (exit 66)' }
127
+ return { kind: 'offline', reason: `CLI usage error (exit ${exitCode})` }
128
+ }
129
+
130
+ // ---- time heal and retry (D4) ---------------------------------------------------------------------------------
131
+
132
+ /** A watch child that stays up this long heals the ladder (`core.afterHealthyChild`); rungs 3 and 4 retry this often. */
133
+ export const HEAL_MS = 10 * 60_000
134
+
135
+ export type LadderTimer = { kind: 'heal'; afterMs: number } | { kind: 'retry-watch'; afterMs: number } | { kind: 'retry-handshake'; afterMs: number } | null
136
+
137
+ /** The timer the supervisor arms on entering a rung. */
138
+ export function ladderTimer(rung: Rung): LadderTimer {
139
+ if (rung === 1 || rung === 2) return { kind: 'heal', afterMs: HEAL_MS }
140
+ if (rung === 3) return { kind: 'retry-watch', afterMs: HEAL_MS }
141
+ return { kind: 'retry-handshake', afterMs: HEAL_MS }
142
+ }
143
+
144
+ // ---- pending wake expiry (D3) ---------------------------------------------------------------------------------
145
+
146
+ /** A submitted wake not claimed within this window is treated as lost. */
147
+ export const WAKE_EXPIRY_MS = 120_000
148
+
149
+ export interface WakeHealth {
150
+ /** Unclaimed wakes in a row for this run. */
151
+ misses: number
152
+ /** The wake mechanism is broken: `healthy` is false until a wake is claimed again. */
153
+ wakeBroken: boolean
154
+ }
155
+
156
+ /**
157
+ * A pending wake expired with no claim. The first miss clears the flag and asks for one re-evaluation; the second
158
+ * in a row marks the wake mechanism broken (`healthy: false`), so the skill's own `ScheduleWakeup` takes over.
159
+ */
160
+ export function afterWakeExpired(h: WakeHealth): WakeHealth & { reevaluate: boolean; toast: string } {
161
+ const misses = h.misses + 1
162
+ if (misses >= 2) return { misses, wakeBroken: true, reevaluate: false, toast: 'DevOrch: wake not claimed twice; the skill keeps its own wakeup' }
163
+ return { misses, wakeBroken: h.wakeBroken, reevaluate: true, toast: 'DevOrch: wake not claimed; re-checking the run' }
164
+ }
165
+
166
+ /** A claim (the lease turned held or the run moved on) resets the miss count and heals the wake mechanism. */
167
+ export function afterWakeClaimed(_h: WakeHealth): WakeHealth {
168
+ return { misses: 0, wakeBroken: false }
169
+ }
170
+
171
+ // ---- position-token dedupe (D15) ------------------------------------------------------------------------------
172
+
173
+ /** The envelope's position token, or null when it is not a run.position. */
174
+ export function tokenOf(envelope: PlatformEventEnvelope): string | null {
175
+ return positionOf(envelope)?.position ?? null
176
+ }
177
+
178
+ /**
179
+ * Whether to dispatch an envelope: a `run.position` whose token equals the last one dispatched is a repeat (a respawn
180
+ * prints the current position first; `run wait` prints the current one at timeout) and is dropped. Other envelope
181
+ * types pass (the dispatcher dedupes them by id).
182
+ */
183
+ export function dedupe(lastToken: string | null, envelope: PlatformEventEnvelope): { dispatch: boolean; lastToken: string | null } {
184
+ const token = tokenOf(envelope)
185
+ if (token === null) return { dispatch: true, lastToken }
186
+ if (token === lastToken) return { dispatch: false, lastToken }
187
+ return { dispatch: true, lastToken: token }
188
+ }
189
+
190
+ // ---- terminals the session already saw (D17) ------------------------------------------------------------------
191
+
192
+ const TERMINAL = new Set(['DONE', 'ESCALATE', 'ABORT'])
193
+
194
+ export function isTerminal(envelope: PlatformEventEnvelope | null): boolean {
195
+ const p = envelope ? positionOf(envelope) : null
196
+ return p !== null && TERMINAL.has(p.control)
197
+ }
198
+
199
+ /**
200
+ * A terminal envelope that arrives while a main-loop turn runs, or within `SETTLE_MS` after one ended, was read by the
201
+ * session in its own turn: unwatch, toast, no wake. Only a terminal arriving on an idle session wakes.
202
+ * `ESCALATE` never wakes (core's `decideWake` does not wake on it either); it only unwatches.
203
+ */
204
+ export function terminalAction(envelope: PlatformEventEnvelope, turnRunning: boolean, idleForMs: number | null): 'none' | 'seen' | 'wake' {
205
+ if (!isTerminal(envelope)) return 'none'
206
+ if (turnRunning || (idleForMs !== null && idleForMs < SETTLE_MS)) return 'seen'
207
+ return positionOf(envelope)?.control === 'ESCALATE' ? 'seen' : 'wake'
208
+ }
209
+
210
+ // ---- watch cap (D18) ------------------------------------------------------------------------------------------
211
+
212
+ export const MAX_WATCHED = 8
213
+
214
+ export function canWatch(watched: readonly string[], runId: string): { ok: true } | { ok: false; reason: string } {
215
+ if (!isRunId(runId)) return { ok: false, reason: 'not a run id' }
216
+ if (watched.some((w) => w.toLowerCase() === runId.toLowerCase())) return { ok: true }
217
+ if (watched.length >= MAX_WATCHED) return { ok: false, reason: 'watch limit' }
218
+ return { ok: true }
219
+ }
220
+
221
+ // ---- hand-back wake on health loss (D16) ----------------------------------------------------------------------
222
+
223
+ /**
224
+ * When a run turns unhealthy after the tool told the skill `healthy: true`, the skill ended its turn without a
225
+ * `ScheduleWakeup` and nothing would wake it. Submit one `/devorch-step <runId>` so the skill re-reads `status`, sees
226
+ * `healthy: false` and schedules its own wakeup. Not when the Stop-hook host is armed (that host owns the wake), and
227
+ * only once per loss.
228
+ */
229
+ export function handBackWake(i: { reportedHealthy: boolean; nowHealthy: boolean; stopHookArmed: boolean; handedBack: boolean }): boolean {
230
+ return i.reportedHealthy && !i.nowHealthy && !i.stopHookArmed && !i.handedBack
231
+ }
232
+
233
+ // ---- exe resolution (D8) --------------------------------------------------------------------------------------
234
+
235
+ export interface ExeSources {
236
+ /** `DEVORCH_EXE` from the host environment. */
237
+ env: string | undefined
238
+ /** Plugin `userConfig.devorchExe`. */
239
+ userConfig: unknown
240
+ /** The text of `${CLAUDE_PLUGIN_ROOT}/cli.json`, written by `devorch companion install` (null: absent). */
241
+ cliJson: string | null
242
+ }
243
+
244
+ /** `DEVORCH_EXE` -> `userConfig.devorchExe` -> `cli.json` -> not found. No PATH lookup (spike TQ-11 decides). */
245
+ export function resolveExe(s: ExeSources): { exe: string; source: 'env' | 'userConfig' | 'cli.json' } | { exe: null; reason: string } {
246
+ if (nonEmpty(s.env)) return { exe: s.env.trim(), source: 'env' }
247
+ if (nonEmpty(s.userConfig)) return { exe: s.userConfig.trim(), source: 'userConfig' }
248
+ if (s.cliJson) {
249
+ try {
250
+ const v = JSON.parse(s.cliJson) as { exe?: unknown }
251
+ if (nonEmpty(v.exe)) return { exe: v.exe.trim(), source: 'cli.json' }
252
+ } catch {
253
+ // fall through: a damaged cli.json reads as absent
254
+ }
255
+ }
256
+ return { exe: null, reason: 'devorch CLI not found: run `devorch companion install`, or set DEVORCH_EXE / userConfig.devorchExe' }
257
+ }
258
+
259
+ // ---- base URL (D14) -------------------------------------------------------------------------------------------
260
+
261
+ /** Explicit argument -> `userConfig.apiBase` -> `DEVORCH_API_BASE` -> the CLI default. Trailing slashes trimmed. */
262
+ export function resolveBaseUrl(explicit: unknown, userConfig: unknown, env: string | undefined): string {
263
+ const pick = [explicit, userConfig, env].find(nonEmpty)
264
+ return (pick ?? 'http://localhost:8700').trim().replace(/\/+$/, '')
265
+ }
266
+
267
+ /** Only an absolute http(s) URL may reach argv as `--base-url`. */
268
+ export function isBaseUrl(value: unknown): value is string {
269
+ if (!nonEmpty(value) || value.startsWith('-')) return false
270
+ try {
271
+ const u = new URL(value)
272
+ return u.protocol === 'http:' || u.protocol === 'https:'
273
+ } catch {
274
+ return false
275
+ }
276
+ }
277
+
278
+ function nonEmpty(v: unknown): v is string {
279
+ return typeof v === 'string' && v.trim().length > 0
280
+ }
281
+
282
+ // ---- version drift (D13) --------------------------------------------------------------------------------------
283
+
284
+ /** The band suffix when the cached plugin is older than the CLI it runs (still healthy). `0.0.0-dev` never nags. */
285
+ export function updateHint(modVersion: string, cliVersion: string): string | null {
286
+ if (modVersion.startsWith('0.0.0')) return null
287
+ return compareVersions(modVersion, cliVersion) < 0 ? 'update: claude plugin update devorch-companion@devorch-cli' : null
288
+ }
289
+
290
+ // ---- health (D6) ----------------------------------------------------------------------------------------------
291
+
292
+ export interface HealthInputs {
293
+ cliOk: boolean
294
+ cliReason: string
295
+ stopHookArmed: boolean
296
+ wakeBroken: boolean
297
+ /** The asked run's rung, or null for the overall answer. */
298
+ rung: Rung | null
299
+ }
300
+
301
+ /** healthy = handshake ok AND no Stop-hook host AND wake not broken AND (for a run) rung < 4. Any false hands the
302
+ * wake to the skill's `ScheduleWakeup`. */
303
+ export function health(i: HealthInputs): { healthy: boolean; reason?: string } {
304
+ if (!i.cliOk) return { healthy: false, reason: i.cliReason }
305
+ if (i.stopHookArmed) return { healthy: false, reason: 'Stop-hook host armed' }
306
+ if (i.wakeBroken) return { healthy: false, reason: 'wake mechanism broken' }
307
+ if (i.rung === 4) return { healthy: false, reason: 'run offline (rung 4)' }
308
+ return { healthy: true }
309
+ }
310
+
311
+ // ---- the status line (D7) -------------------------------------------------------------------------------------
312
+
313
+ export interface RunView {
314
+ runId: string
315
+ latest: PlatformEventEnvelope | null
316
+ ladder: LadderState
317
+ }
318
+
319
+ const RUNG_LABELS: Record<Rung, string> = { 1: 'live', 2: 'reconnecting', 3: 'polling', 4: 'offline' }
320
+
321
+ /**
322
+ * One status line for the session: no runs and one run use core's `bandText`; N runs collapse to counts
323
+ * (`DevOrch: N watched | <worst rung> | blockers: <n>`). Enums, refs and counts only, never blocker text (CC-4).
324
+ */
325
+ export function statusLine(runs: readonly RunView[], stopHookArmed: boolean, hint: string | null = null): string {
326
+ const suffix = hint ? ` | ${hint}` : ''
327
+ if (runs.length === 0) return bandText(null, null, { rung: 1, restarts: 0, reason: '' }, stopHookArmed) + suffix
328
+ if (runs.length === 1) {
329
+ const r = runs[0] as RunView
330
+ return bandText(r.runId, r.latest, r.ladder, stopHookArmed) + suffix
331
+ }
332
+ if (stopHookArmed) return 'DevOrch: Stop-hook host armed' + suffix
333
+ const worst = Math.max(...runs.map((r) => r.ladder.rung)) as Rung
334
+ const blockers = runs.reduce((n, r) => n + (r.latest ? (positionOf(r.latest)?.openBlockers.length ?? 0) : 0), 0)
335
+ return `DevOrch: ${runs.length} watched | ${RUNG_LABELS[worst]} | blockers: ${blockers}${suffix}`
336
+ }
337
+
338
+ /** The per-run row of the tool's `status` (enums and refs only). */
339
+ export function runStatus(r: RunView & { baseUrl: string; pendingWake: boolean }): Record<string, unknown> {
340
+ const p = r.latest ? positionOf(r.latest) : null
341
+ return {
342
+ runId: r.runId,
343
+ baseUrl: r.baseUrl,
344
+ rung: r.ladder.rung,
345
+ ladderReason: r.ladder.reason,
346
+ control: p?.control ?? null,
347
+ reasonCode: p?.reasonCode ?? null,
348
+ leaseHeld: p?.leaseHeld ?? false,
349
+ openBlockers: (p?.openBlockers ?? []).map((b) => ({ ref: b.ref, kind: b.kind })),
350
+ pendingWake: r.pendingWake,
351
+ }
352
+ }
353
+
354
+ // ---- the watched set kept in $.state (D10) ------------------------------------------------------------------
355
+
356
+ export interface WatchEntry {
357
+ runId: string
358
+ baseUrl: string
359
+ lastToken?: string
360
+ addedAt: number
361
+ }
362
+
363
+ /** Validate a watched set read back from `$.state`: drop malformed entries, keep the first of any duplicate, cap. */
364
+ export function restoreWatched(value: unknown): WatchEntry[] {
365
+ const runs = (value as { runs?: unknown } | null | undefined)?.runs
366
+ if (!Array.isArray(runs)) return []
367
+ const out: WatchEntry[] = []
368
+ for (const r of runs as Partial<WatchEntry>[]) {
369
+ if (!r || !isRunId(r.runId) || !isBaseUrl(r.baseUrl) || out.some((o) => o.runId === (r.runId as string).toLowerCase())) continue
370
+ out.push({ runId: r.runId.toLowerCase(), baseUrl: r.baseUrl, addedAt: typeof r.addedAt === 'number' ? r.addedAt : 0, ...(typeof r.lastToken === 'string' ? { lastToken: r.lastToken } : {}) })
371
+ if (out.length >= MAX_WATCHED) break
372
+ }
373
+ return out
374
+ }
375
+
376
+ // ---- the measurement log (D19) --------------------------------------------------------------------------------
377
+
378
+ export const LOG_MAX_BYTES = 1024 * 1024
379
+
380
+ /** One log line: ids and timings only, never envelope data or answer text. */
381
+ export function logLine(t: number, runId: string, event: string, extra: { token?: string | null; rung?: Rung; exitCode?: number | null } = {}): string {
382
+ const row: Record<string, unknown> = { t, runId, event }
383
+ if (extra.token) row.token = extra.token
384
+ if (extra.rung !== undefined) row.rung = extra.rung
385
+ if (extra.exitCode !== undefined) row.exitCode = extra.exitCode
386
+ return JSON.stringify(row)
387
+ }
388
+
389
+ // ---- slash-command arguments ----------------------------------------------------------------------------------
390
+
391
+ /** `/devorch-watch [runId] [baseUrl]`. */
392
+ export function parseWatchArgs(args: string): { list: true } | { list: false; runId: string; baseUrl: string | null } | { error: string } {
393
+ const words = args.trim().split(/\s+/).filter((w) => w.length > 0)
394
+ if (words.length === 0) return { list: true }
395
+ const [runId, baseUrl] = words
396
+ if (!isRunId(runId)) return { error: 'usage: /devorch-watch [runId] [baseUrl]' }
397
+ if (baseUrl !== undefined && !isBaseUrl(baseUrl)) return { error: 'baseUrl must be an http(s) URL' }
398
+ return { list: false, runId: runId.toLowerCase(), baseUrl: baseUrl ?? null }
399
+ }
400
+
401
+ /** `/devorch-unwatch <runId|all>`. */
402
+ export function parseUnwatchArgs(args: string): { all: true } | { all: false; runId: string } | { error: string } {
403
+ const word = args.trim()
404
+ if (word === 'all') return { all: true }
405
+ if (isRunId(word)) return { all: false, runId: word.toLowerCase() }
406
+ return { error: 'usage: /devorch-unwatch <runId|all>' }
407
+ }
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The `$.devorch` noun the DevOrch companion mod adds in its `engine.create` step (design-L0 D9), and the session
3
+ * state it keeps (D10). Another plugin that lists `devorch-companion` under "dependencies" reads these types.
4
+ *
5
+ * The noun is subscribe and read only: a plugin can observe the platform event envelopes of the runs this session
6
+ * watches, but cannot watch, wake or answer through it (only the companion mod submits a wake, CC-4).
7
+ */
8
+
9
+ /** One platform event envelope (v1) as `devorch run watch` prints it: ids, refs and enums only. */
10
+ export type DevorchEnvelope = {
11
+ id: string
12
+ type: string
13
+ version: number
14
+ occurredAt: string
15
+ org: string
16
+ actor: { kind: string; externalId: string } | null
17
+ subject: { kind: string; externalId: string }
18
+ run: { externalId: string } | null
19
+ data: Record<string, unknown>
20
+ }
21
+
22
+ export type DevorchRunStatus = {
23
+ runId: string
24
+ baseUrl: string
25
+ rung: 1 | 2 | 3 | 4
26
+ ladderReason: string
27
+ control: string | null
28
+ reasonCode: string | null
29
+ leaseHeld: boolean
30
+ openBlockers: { ref: string; kind: string }[]
31
+ pendingWake: boolean
32
+ }
33
+
34
+ export type DevorchStatus = {
35
+ healthy: boolean
36
+ reason?: string
37
+ cli: { ok: boolean; version: string | null; path: string | null }
38
+ stopHookArmed: boolean
39
+ wakeBroken: boolean
40
+ runs: DevorchRunStatus[]
41
+ }
42
+
43
+ export type Devorch = {
44
+ /**
45
+ * Calls `handler` for every envelope of a watched run whose type matches `pattern`: an exact type
46
+ * (`run.position`), a prefix wildcard (`blocker.*`) or `*`. A throwing handler never stops the others.
47
+ * @returns a function that removes the handler
48
+ */
49
+ on: (pattern: string, handler: (envelope: DevorchEnvelope) => void | Promise<void>) => () => void
50
+ /** The latest `run.position` envelope of a watched run, or null. */
51
+ latest: (runId: string) => DevorchEnvelope | null
52
+ /** The same answer as the `devorch_companion` tool's `status` action. */
53
+ status: () => DevorchStatus
54
+ }
55
+
56
+ export type DevorchWatchEntry = { runId: string; baseUrl: string; lastToken?: string; addedAt: number }
57
+
58
+ declare module 'claude-code' {
59
+ interface EngineInterface {
60
+ devorch: Devorch
61
+ }
62
+ interface PluginState {
63
+ 'devorch-companion': { watched: { runs: DevorchWatchEntry[] } }
64
+ }
65
+ }
package/bin/devorch CHANGED
@@ -1,4 +1,4 @@
1
1
  [diffend] Oversized file quarantined before diffing.
2
2
  name: package/bin/devorch
3
- size: 106850033 bytes
4
- sha256: e9edfa80bab57226cc600d8db873aa77a28870669e7fbcb1fac7f663b1042685
3
+ size: 106918641 bytes
4
+ sha256: 8664b0c4716fa5e2ea873fb5012f7482f20d97124d7677172108a785006f138d
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devorch/cli-linux-x64",
3
- "version": "0.10.0",
3
+ "version": "0.12.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": {