@xiangyixie/dsh-superagent 0.12.1 → 0.14.1

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/lib/goal.js ADDED
@@ -0,0 +1,649 @@
1
+ /**
2
+ * Goal mode: keep a run going until its acceptance conditions are met, or until
3
+ * a hard stop means a human has to decide.
4
+ *
5
+ * This module owns everything goal-specific: validating the acceptance spec,
6
+ * running the machine-checkable part so the verdict rests on a real exit code
7
+ * instead of a model's claim, judging only the conditions no machine can check,
8
+ * deciding whether a round made progress, and writing the stop report.
9
+ *
10
+ * The orchestrator owns scheduling, budget, and notification; nothing here
11
+ * wakes a session. That separation is what makes "one notification at the end,
12
+ * none between rounds" a property of the wiring rather than a promise.
13
+ *
14
+ * @module dsh-superagent/goal
15
+ */
16
+ import { exec, execFile } from 'node:child_process'
17
+ import { createHash } from 'node:crypto'
18
+ import fsp from 'node:fs/promises'
19
+ import path from 'node:path'
20
+
21
+ /** Rounds a goal run may take when the caller names no cap. */
22
+ export const DEFAULT_MAX_ROUNDS = 5
23
+ /** Wall-clock cap when the caller names none, in minutes. */
24
+ export const DEFAULT_MAX_WALL_CLOCK_MINUTES = 60
25
+ /** Identical failing rounds tolerated before the loop calls it a stall. */
26
+ export const DEFAULT_NO_PROGRESS_ROUNDS = 2
27
+ /** Acceptance conditions are few by design; a long list is a badly framed goal. */
28
+ export const MAX_ACCEPTANCE_ITEMS = 12
29
+ /** Upper bound on one machine check, in seconds. */
30
+ const MAX_CHECK_TIMEOUT_S = 900
31
+ const DEFAULT_CHECK_TIMEOUT_S = 120
32
+ /** Output kept from one check; the tail is where the failure is. */
33
+ const CHECK_OUTPUT_CHARS = 3000
34
+ /** Untracked files hashed for the change fingerprint; a bound, not a promise. */
35
+ const UNTRACKED_MAX = 50
36
+
37
+ /** Collapse arbitrary text into one bounded line, like the orchestrator does. */
38
+ function oneLine(value, maxChars = 400) {
39
+ const text = String(value ?? '').replace(/\s+/g, ' ').trim()
40
+ if (!text) return ''
41
+ return [...text].slice(0, maxChars).join('')
42
+ }
43
+
44
+ /** Keep the end of a command's output: that is where the error is. */
45
+ function tail(value, maxChars = CHECK_OUTPUT_CHARS) {
46
+ const text = String(value ?? '').trim()
47
+ if (text.length <= maxChars) return text
48
+ return `…${text.slice(-maxChars)}`
49
+ }
50
+
51
+ function numberIn(value, fallback, min, max, label) {
52
+ if (value === undefined || value === null || value === '') return fallback
53
+ const number = Number(value)
54
+ if (!Number.isFinite(number)) throw new Error(`${label} must be a number, got ${JSON.stringify(value)}`)
55
+ return Math.min(max, Math.max(min, Math.trunc(number)))
56
+ }
57
+
58
+ function requiredText(value, label) {
59
+ const text = typeof value === 'string' ? value.trim() : ''
60
+ if (!text) throw new Error(`${label} is required`)
61
+ return text
62
+ }
63
+
64
+ /**
65
+ * Validate one machine check.
66
+ *
67
+ * A bare string is accepted as a command because that is how people write an
68
+ * acceptance condition ("run npm test"); everything else is an explicit object
69
+ * so a condition cannot silently become a different kind of check later.
70
+ *
71
+ * @param {unknown} raw - check from the caller.
72
+ * @param {number} index - position, used in error messages.
73
+ * @returns {object | null} normalized check, or null for a model-judged item.
74
+ */
75
+ function normalizeCheck(raw, index) {
76
+ if (raw === undefined || raw === null || raw === '') return null
77
+ if (typeof raw === 'string') {
78
+ return { type: 'command', command: raw.trim(), cwd: null, timeoutSeconds: DEFAULT_CHECK_TIMEOUT_S }
79
+ }
80
+ if (typeof raw !== 'object' || Array.isArray(raw)) {
81
+ throw new Error(`acceptance[${index}].check must be a command string or an object`)
82
+ }
83
+ const type = String(raw.type ?? '').trim().toLowerCase()
84
+ if (type === 'command') {
85
+ return {
86
+ type: 'command',
87
+ command: requiredText(raw.command, `acceptance[${index}].check.command`),
88
+ cwd: typeof raw.cwd === 'string' && raw.cwd.trim() ? raw.cwd.trim() : null,
89
+ timeoutSeconds: numberIn(
90
+ raw.timeoutSeconds,
91
+ DEFAULT_CHECK_TIMEOUT_S,
92
+ 1,
93
+ MAX_CHECK_TIMEOUT_S,
94
+ `acceptance[${index}].check.timeoutSeconds`,
95
+ ),
96
+ }
97
+ }
98
+ if (type === 'file') {
99
+ return {
100
+ type: 'file',
101
+ path: requiredText(raw.path, `acceptance[${index}].check.path`),
102
+ mustExist: raw.mustExist !== false,
103
+ }
104
+ }
105
+ throw new Error(
106
+ `acceptance[${index}].check.type ${JSON.stringify(raw.type)} is unknown; use "command" or "file", `
107
+ + 'or omit check to have the acceptance model judge the condition',
108
+ )
109
+ }
110
+
111
+ /** One acceptance condition: an id, the text a person reads, and an optional check. */
112
+ function normalizeAcceptanceEntry(raw, index, seen) {
113
+ const source = typeof raw === 'string' ? { text: raw } : raw
114
+ if (!source || typeof source !== 'object' || Array.isArray(source)) {
115
+ throw new Error(`acceptance[${index}] must be a string or an object with "text"`)
116
+ }
117
+ const text = requiredText(source.text ?? source.description ?? source.condition, `acceptance[${index}].text`)
118
+ const id = oneLine(source.id, 40) || `a${index + 1}`
119
+ if (seen.has(id)) throw new Error(`acceptance ids must be unique; "${id}" appears twice`)
120
+ seen.add(id)
121
+ return { id, text: oneLine(text, 600), check: normalizeCheck(source.check, index) }
122
+ }
123
+
124
+ /**
125
+ * Canonical goal spec.
126
+ *
127
+ * Limits can only narrow what the operator allows: a caller naming a round
128
+ * count below 1 gets 1 rather than an unbounded loop. `cwd` is resolved once
129
+ * here so every round checks and fingerprints the same workspace.
130
+ *
131
+ * @param {unknown} value - requested goal mode.
132
+ * @returns {object} normalized spec.
133
+ */
134
+ export function normalizeGoalSpec(value) {
135
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
136
+ throw new Error('goal_mode requires an object with acceptance conditions and optional limits')
137
+ }
138
+ const entries = Array.isArray(value.acceptance) ? value.acceptance : []
139
+ if (entries.length === 0) {
140
+ throw new Error('goal_mode requires at least one acceptance condition; without one, the run cannot know it is done')
141
+ }
142
+ if (entries.length > MAX_ACCEPTANCE_ITEMS) {
143
+ throw new Error(`goal_mode accepts at most ${MAX_ACCEPTANCE_ITEMS} acceptance conditions`)
144
+ }
145
+ const seen = new Set()
146
+ const acceptance = entries.map((entry, index) => normalizeAcceptanceEntry(entry, index, seen))
147
+ const budget = value.budget && typeof value.budget === 'object'
148
+ ? {
149
+ maxModelCalls: value.budget.maxModelCalls === undefined || value.budget.maxModelCalls === null
150
+ ? null
151
+ : numberIn(value.budget.maxModelCalls, null, 0, 10000, 'budget.maxModelCalls'),
152
+ maxTokens: value.budget.maxTokens === undefined || value.budget.maxTokens === null
153
+ ? null
154
+ : numberIn(value.budget.maxTokens, null, 0, 1e12, 'budget.maxTokens'),
155
+ }
156
+ : null
157
+ return {
158
+ acceptance,
159
+ maxRounds: numberIn(value.maxRounds, DEFAULT_MAX_ROUNDS, 1, 20, 'maxRounds'),
160
+ maxWallClockMinutes: numberIn(
161
+ value.maxWallClockMinutes,
162
+ DEFAULT_MAX_WALL_CLOCK_MINUTES,
163
+ 1,
164
+ 720,
165
+ 'maxWallClockMinutes',
166
+ ),
167
+ noProgressRounds: numberIn(value.noProgressRounds, DEFAULT_NO_PROGRESS_ROUNDS, 1, 10, 'noProgressRounds'),
168
+ budget: budget && (budget.maxModelCalls !== null || budget.maxTokens !== null) ? budget : null,
169
+ cwd: typeof value.cwd === 'string' && value.cwd.trim() ? path.resolve(value.cwd.trim()) : null,
170
+ }
171
+ }
172
+
173
+ /** Run one command and resolve with the outcome instead of throwing. */
174
+ function execCommand(command, options) {
175
+ return new Promise(resolve => {
176
+ const started = Date.now()
177
+ exec(command, { ...options, maxBuffer: 4 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
178
+ resolve({ error, stdout, stderr, durationMs: Date.now() - started })
179
+ })
180
+ })
181
+ }
182
+
183
+ /** Machine check: a command whose exit code is the verdict. */
184
+ async function checkCommand(item, base, signal) {
185
+ const check = item.check
186
+ const cwd = check.cwd ? path.resolve(base, check.cwd) : base
187
+ const started = Date.now()
188
+ if (signal?.aborted) {
189
+ return {
190
+ id: item.id,
191
+ text: item.text,
192
+ source: 'command',
193
+ ok: false,
194
+ exitCode: null,
195
+ durationMs: 0,
196
+ detail: 'not run: the run was stopping when this check was due',
197
+ }
198
+ }
199
+ const outcome = await execCommand(check.command, {
200
+ cwd,
201
+ timeout: check.timeoutSeconds * 1000,
202
+ signal: signal ?? undefined,
203
+ })
204
+ const timedOut = Boolean(outcome.error?.killed)
205
+ const exitCode = outcome.error
206
+ ? (typeof outcome.error.code === 'number' ? outcome.error.code : null)
207
+ : 0
208
+ const ok = !outcome.error
209
+ const output = tail(outcome.stderr || '') || tail(outcome.stdout || '')
210
+ let detail
211
+ if (ok) detail = `exit 0 in ${outcome.durationMs} ms`
212
+ else if (timedOut) detail = `timed out after ${check.timeoutSeconds}s`
213
+ else if (exitCode === null) detail = oneLine(outcome.error?.message ?? 'the command could not be started', 500)
214
+ else detail = `exit ${exitCode}${output ? `: ${oneLine(output, 600)}` : ''}`
215
+ return {
216
+ id: item.id,
217
+ text: item.text,
218
+ source: 'command',
219
+ command: check.command,
220
+ ok,
221
+ exitCode,
222
+ durationMs: outcome.durationMs ?? (Date.now() - started),
223
+ detail,
224
+ }
225
+ }
226
+
227
+ /** Machine check: does a path exist (or, with mustExist false, is it gone). */
228
+ async function checkFile(item, base) {
229
+ const target = path.resolve(base, item.check.path)
230
+ let exists = true
231
+ try {
232
+ await fsp.access(target)
233
+ } catch {
234
+ exists = false
235
+ }
236
+ const ok = item.check.mustExist ? exists : !exists
237
+ return {
238
+ id: item.id,
239
+ text: item.text,
240
+ source: 'file',
241
+ path: target,
242
+ ok,
243
+ exitCode: null,
244
+ durationMs: 0,
245
+ detail: exists ? 'the file exists' : 'the file is missing',
246
+ }
247
+ }
248
+
249
+ /**
250
+ * Run every machine-checkable acceptance condition in order.
251
+ *
252
+ * Conditions without a check are returned with `ok: null` and `source: "model"`
253
+ * — they are not silently treated as passed. The command's real exit code and a
254
+ * bounded tail of its output are recorded on each item, so the report can say
255
+ * what was actually run and what it printed.
256
+ *
257
+ * @param {object} goalSpec - normalized goal spec.
258
+ * @param {{ signal?: AbortSignal | null }} [options] - abort signal of the run.
259
+ * @returns {Promise<object[]>} one result per acceptance condition, in order.
260
+ */
261
+ export async function runChecks(goalSpec, { signal = null } = {}) {
262
+ const base = goalSpec.cwd ?? process.cwd()
263
+ const results = []
264
+ for (const item of goalSpec.acceptance) {
265
+ if (!item.check) {
266
+ results.push({ id: item.id, text: item.text, source: 'model', ok: null, exitCode: null, durationMs: 0, detail: null })
267
+ continue
268
+ }
269
+ results.push(item.check.type === 'file'
270
+ ? await checkFile(item, base)
271
+ : await checkCommand(item, base, signal))
272
+ }
273
+ return results
274
+ }
275
+
276
+ /** Run one read-only git command in a workspace. */
277
+ function git(cwd, args) {
278
+ return new Promise((resolve, reject) => {
279
+ execFile('git', ['-C', cwd, ...args], { maxBuffer: 8 * 1024 * 1024, windowsHide: true }, (error, stdout) => {
280
+ if (error) reject(error)
281
+ else resolve(stdout)
282
+ })
283
+ })
284
+ }
285
+
286
+ /**
287
+ * Fingerprint the workspace so two rounds can be compared.
288
+ *
289
+ * Status and diffs alone miss an edit that rewrites an untracked file, which is
290
+ * exactly the shape of a first attempt. Untracked file contents are therefore
291
+ * hashed as well, up to a bound. A directory that is not a git repository gives
292
+ * `null`: "cannot tell" must never be reported as "nothing changed".
293
+ *
294
+ * @param {string | null} cwd - workspace to fingerprint.
295
+ * @returns {Promise<string | null>} hex digest, or null outside a repository.
296
+ */
297
+ export async function fingerprintWorkspace(cwd) {
298
+ if (!cwd) return null
299
+ try {
300
+ const [status, diff, staged, untrackedRaw] = await Promise.all([
301
+ git(cwd, ['status', '--porcelain=v1', '-uall']),
302
+ git(cwd, ['diff']),
303
+ git(cwd, ['diff', '--cached']),
304
+ git(cwd, ['ls-files', '--others', '--exclude-standard', '-z']),
305
+ ])
306
+ const hash = createHash('sha256')
307
+ hash.update(status).update('\0').update(diff).update('\0').update(staged)
308
+ const untracked = untrackedRaw.split('\0').filter(Boolean).sort().slice(0, UNTRACKED_MAX)
309
+ for (const file of untracked) {
310
+ hash.update('\0').update(file).update('\0')
311
+ try {
312
+ const data = await fsp.readFile(path.join(cwd, file))
313
+ hash.update(createHash('sha256').update(data).digest('hex'))
314
+ } catch {
315
+ hash.update('unreadable')
316
+ }
317
+ }
318
+ return hash.digest('hex')
319
+ } catch {
320
+ return null
321
+ }
322
+ }
323
+
324
+ /** True when at least one condition is checked by the runtime itself. */
325
+ export function hasMachineChecks(goalSpec) {
326
+ return (goalSpec?.acceptance ?? []).some(item => Boolean(item.check))
327
+ }
328
+
329
+ /**
330
+ * The goal text every prompt in a round sees.
331
+ *
332
+ * Round one gets the acceptance conditions too, not only the failure feedback:
333
+ * a worker that does not know what will be checked cannot aim at it. The
334
+ * original `run.goal` stays untouched on the record, so dedupe, status, and the
335
+ * report keep showing what the user asked for.
336
+ *
337
+ * @param {object} run - run record.
338
+ * @returns {string} goal plus acceptance conditions plus, after a failed round, the feedback.
339
+ */
340
+ export function roundGoal(run) {
341
+ const goalMode = run?.goalMode
342
+ if (!goalMode) return String(run?.goal ?? '')
343
+ const conditions = (goalMode.acceptance ?? []).map(item => {
344
+ const how = item.check
345
+ ? `checked by the runtime (${item.check.type === 'command' ? `\`${item.check.command}\`` : `file ${item.check.path}`})`
346
+ : 'judged by an independent acceptance model from your report'
347
+ return `- [${item.id}] ${item.text} (${how})`
348
+ })
349
+ const parts = [
350
+ String(run.goal ?? ''),
351
+ '',
352
+ 'Acceptance conditions for this goal. The run is only finished when every one holds:',
353
+ ...conditions,
354
+ ]
355
+ const feedback = goalMode.nextInstruction
356
+ if (feedback) parts.push('', feedback)
357
+ return parts.join('\n')
358
+ }
359
+
360
+ /**
361
+ * Prompt for the independent acceptance judge.
362
+ *
363
+ * The judge sees the machine results but is not asked to re-run them: an exit
364
+ * code is not an opinion. It judges only the listed model-only conditions, and
365
+ * its `next` is the concrete change the following round must make.
366
+ *
367
+ * @param {object} run - run record.
368
+ * @param {object} round - round record being judged.
369
+ * @param {object[]} checks - machine and model check results.
370
+ * @returns {string} prompt for the child.
371
+ */
372
+ export function verifierPrompt(run, round, checks) {
373
+ const judged = checks.filter(check => check.source === 'model')
374
+ const machine = checks.filter(check => check.source !== 'model')
375
+ return [
376
+ 'You are the independent acceptance judge of a long-horizon autonomous run.',
377
+ 'You did not do the work, so judge the evidence instead of trusting a claim that it is done.',
378
+ '',
379
+ 'Goal:',
380
+ roundGoal({ ...run, goalMode: { ...run.goalMode, nextInstruction: null } }),
381
+ '',
382
+ `Round ${round.round} report:`,
383
+ capText(round.report ?? '(the round produced no report)', 8000),
384
+ '',
385
+ ...(machine.length > 0
386
+ ? [
387
+ 'Conditions the runtime already checked by machine (do not re-judge these; the exit codes are final):',
388
+ ...machine.map(check => `- ${check.ok ? 'PASS' : 'FAIL'} [${check.id}] ${check.text}: ${check.detail ?? ''}`),
389
+ '',
390
+ ]
391
+ : []),
392
+ 'Conditions only you can judge:',
393
+ ...judged.map(check => `- [${check.id}] ${check.text}`),
394
+ '',
395
+ 'Rules:',
396
+ '- Mark a condition met only when the report contains concrete evidence for it (a path, a command result, a number).',
397
+ '- "achieved" is true only when every condition listed above is met.',
398
+ '- "next" must say what to change in the next round: the file, the approach, or the missing evidence. Never write',
399
+ ' "try again" or "improve it"; that is what the next round must not hear.',
400
+ '',
401
+ 'Return ONLY this JSON object, with no prose and no code fences:',
402
+ '{"achieved":false,"failed":[{"id":"a1","why":"one concrete reason"}],"next":"the concrete change for the next round"}',
403
+ ].join('\n')
404
+ }
405
+
406
+ function capText(value, maxChars) {
407
+ const text = String(value ?? '')
408
+ return text.length <= maxChars ? text : `${text.slice(0, maxChars)}\n…`
409
+ }
410
+
411
+ /** Pull a JSON object out of a fenced block, or out of the reply itself. */
412
+ function jsonCandidates(text) {
413
+ const candidates = []
414
+ for (const match of String(text ?? '').matchAll(/```[^\n]*\n([\s\S]*?)```/g)) candidates.push(match[1])
415
+ const first = text.indexOf('{')
416
+ const last = text.lastIndexOf('}')
417
+ if (first >= 0 && last > first) candidates.push(text.slice(first, last + 1))
418
+ return candidates
419
+ }
420
+
421
+ /**
422
+ * Parse the acceptance judge's verdict.
423
+ *
424
+ * An unusable reply is reported as an error instead of being read as "not
425
+ * achieved": the difference between "the work failed" and "the judge failed"
426
+ * decides whether another round is worth spending.
427
+ *
428
+ * @param {string} text - child reply.
429
+ * @returns {{ verdict: { achieved: boolean, failed: object[], next: string | null } | null, error: string | null }}
430
+ */
431
+ export function parseVerdict(text) {
432
+ let lastError = 'the acceptance judge returned no JSON object'
433
+ for (const candidate of jsonCandidates(text)) {
434
+ let parsed
435
+ try {
436
+ parsed = JSON.parse(candidate)
437
+ } catch (error) {
438
+ lastError = `the acceptance judge returned invalid JSON: ${error?.message ?? error}`
439
+ continue
440
+ }
441
+ if (!parsed || typeof parsed !== 'object' || typeof parsed.achieved !== 'boolean') {
442
+ lastError = 'the acceptance judge JSON has no boolean "achieved" field'
443
+ continue
444
+ }
445
+ const failed = Array.isArray(parsed.failed)
446
+ ? parsed.failed
447
+ .filter(entry => entry && typeof entry === 'object')
448
+ .map(entry => ({ id: oneLine(entry.id, 40), why: oneLine(entry.why ?? entry.reason, 600) }))
449
+ .filter(entry => entry.id)
450
+ : []
451
+ return {
452
+ verdict: {
453
+ achieved: parsed.achieved,
454
+ failed,
455
+ next: oneLine(parsed.next, 700) || null,
456
+ },
457
+ error: null,
458
+ }
459
+ }
460
+ return { verdict: null, error: lastError }
461
+ }
462
+
463
+ /**
464
+ * Decide whether a failed round shows progress.
465
+ *
466
+ * Two different failures are possible and they deserve different answers:
467
+ * a round that changed no file cannot be repeated into a different outcome, so
468
+ * it is a stall immediately; a round that changed something but failed the same
469
+ * condition gets `noProgressRounds` attempts before the loop stops.
470
+ *
471
+ * @param {object} input - round evidence.
472
+ * @param {object | null} input.previous - previous round record, or null.
473
+ * @param {object[]} input.failed - failed conditions of this round.
474
+ * @param {boolean | null} input.changed - whether the workspace fingerprint moved.
475
+ * @param {boolean} input.machineChecked - whether the spec has machine checks.
476
+ * @param {number} input.noProgressRounds - identical failing rounds tolerated.
477
+ * @returns {{ signature: string, streak: number, stalled: string | null }}
478
+ */
479
+ export function assessRound({ previous = null, failed = [], changed = null, machineChecked = false, noProgressRounds = 1 }) {
480
+ const signature = failed.map(item => item.id).sort().join('|')
481
+ if (failed.length === 0) return { signature, streak: 0, stalled: null }
482
+ if (machineChecked && changed === false) {
483
+ return { signature, streak: 1, stalled: 'no-changes' }
484
+ }
485
+ const same = Boolean(previous) && previous.failedSignature === signature
486
+ const streak = same ? Math.max(1, Number(previous.streak) || 1) + 1 : 1
487
+ return {
488
+ signature,
489
+ streak,
490
+ stalled: same && streak >= noProgressRounds ? 'no-progress' : null,
491
+ }
492
+ }
493
+
494
+ /**
495
+ * The instruction the next round is built from.
496
+ *
497
+ * This is what makes round two different from round one: the exact conditions
498
+ * that failed, what the check said, and the change the judge asked for. A
499
+ * generic "try again" is deliberately not produced.
500
+ *
501
+ * @param {number} roundNumber - round that just failed.
502
+ * @param {object[]} failed - failed conditions.
503
+ * @param {string | null} next - concrete change from the judge, when there is one.
504
+ * @returns {string} instruction appended to the next round's goal.
505
+ */
506
+ export function buildRoundInstruction(roundNumber, failed, next = null) {
507
+ return [
508
+ `Previous round (round ${roundNumber}) did not meet the acceptance conditions.`,
509
+ 'Still failing:',
510
+ ...failed.map(item => `- [${item.id}] ${item.text} — ${item.why}`),
511
+ '',
512
+ next
513
+ ? `Do this differently in this round: ${next}`
514
+ : 'Do this differently in this round: change the approach or the files that produced the failure above; '
515
+ + 'repeating the same work will produce the same result.',
516
+ 'Do not repeat the previous attempt. The acceptance step will check the same conditions again.',
517
+ ].join('\n')
518
+ }
519
+
520
+ const STOP_LABELS = {
521
+ rounds: 'max rounds reached',
522
+ 'wall-clock': 'wall-clock limit reached',
523
+ budget: 'budget reached',
524
+ 'no-changes': 'no progress: the round changed nothing',
525
+ 'no-progress': 'no progress: the same acceptance condition failed again',
526
+ 'needs-decision': 'a decision from you is required',
527
+ aborted: 'the run was stopped before the goal was reached',
528
+ }
529
+
530
+ /** One line naming a stop reason. */
531
+ export function stopLabel(stop) {
532
+ if (!stop) return 'none'
533
+ return `${STOP_LABELS[stop.reason] ?? stop.reason}${stop.detail ? ` (${stop.detail})` : ''}`
534
+ }
535
+
536
+ /** What a human should do next, when a round could not get there alone. */
537
+ function nextStep(run) {
538
+ const goalMode = run.goalMode
539
+ const stop = goalMode.stop
540
+ const failed = goalMode.rounds.at(-1)?.failed ?? []
541
+ if (stop?.reason === 'needs-decision') {
542
+ return 'answer the pending question with superagent_answer, then resume the run'
543
+ }
544
+ if (stop?.reason === 'budget') {
545
+ return `the budget is fixed for this run (${stop.detail ?? 'model calls or tokens'}); start a new run with a `
546
+ + 'higher goal budget, or raise the configured cap and start again'
547
+ }
548
+ if (stop?.reason === 'no-changes') {
549
+ const id = failed[0]?.id
550
+ return `the last round changed no file${id ? `, so ${id} cannot pass by re-running` : ''}; say what to change with `
551
+ + 'superagent_followup, or fix the acceptance condition if it is not achievable by editing this workspace'
552
+ }
553
+ if (stop?.reason === 'no-progress') {
554
+ const id = failed[0]?.id
555
+ return `${id ? `${id} failed again with changes in between` : 'the same condition failed again'}; inspect the `
556
+ + 'check output, decide whether the condition or the approach is wrong, then resume with a concrete instruction'
557
+ }
558
+ if (stop?.reason === 'rounds' || stop?.reason === 'wall-clock') {
559
+ return 'call superagent_resume for another max_rounds allowance, or start a new run with a wider limit'
560
+ }
561
+ return goalMode.rounds.at(-1)?.next ?? 'inspect the last round and resume with a concrete instruction'
562
+ }
563
+
564
+ /**
565
+ * Compose the user-facing report of a goal run.
566
+ *
567
+ * The report answers the three things a person needs after an unattended run:
568
+ * why it stopped, what was already tried, and what they should do next. The last
569
+ * round's own report is kept at the end, so the evidence is still readable.
570
+ *
571
+ * @param {object} run - run record with `goalMode`.
572
+ * @returns {string} Markdown report.
573
+ */
574
+ export function composeGoalReport(run) {
575
+ const goalMode = run.goalMode
576
+ const rounds = goalMode.rounds ?? []
577
+ const last = rounds.at(-1)
578
+ const checks = last?.checks ?? []
579
+ const passed = checks.filter(check => check.ok === true).length
580
+ const achieved = goalMode.achieved === true
581
+ const lines = []
582
+ if (achieved) {
583
+ lines.push('# Goal achieved', '')
584
+ } else {
585
+ lines.push(`# Goal not reached — stopped: ${stopLabel(goalMode.stop)}`, '')
586
+ }
587
+ lines.push(`Goal: ${oneLine(run.goal, 500)}`, '')
588
+ lines.push(
589
+ `Rounds: ${rounds.length} of ${goalMode.maxRounds}; `
590
+ + `${checks.length > 0 ? `acceptance ${passed} of ${checks.length} met` : 'acceptance not evaluated'}; `
591
+ + `wall-clock limit ${goalMode.maxWallClockMinutes} min`,
592
+ )
593
+ lines.push('')
594
+ if (checks.length > 0) {
595
+ lines.push('Acceptance conditions:')
596
+ for (const check of checks) {
597
+ const source = check.source === 'model' ? 'judged by the acceptance model' : 'machine-checked by the plugin'
598
+ lines.push(`- ${check.ok ? 'PASS' : 'FAIL'} [${check.id}] ${check.text} (${source})`)
599
+ if (check.command) lines.push(` ran \`${check.command}\`: ${check.detail ?? ''}`)
600
+ else if (check.detail) lines.push(` ${check.detail}`)
601
+ }
602
+ lines.push('')
603
+ }
604
+ if (rounds.length > 0) {
605
+ lines.push('Tried:')
606
+ for (const round of rounds) {
607
+ const subtasks = round.subtasks ?? {}
608
+ const changed = round.changed === null || round.changed === undefined
609
+ ? 'change unknown'
610
+ : round.changed ? 'workspace changed' : 'workspace unchanged'
611
+ const failed = round.failed?.length > 0 ? round.failed.map(item => item.id).join(', ') : 'nothing'
612
+ lines.push(
613
+ `- round ${round.round}: ${subtasks.completed ?? 0}/${subtasks.total ?? 0} subtask(s) completed; ${changed}; `
614
+ + `failed: ${failed}`,
615
+ )
616
+ if (round.next) lines.push(` next: ${round.next}`)
617
+ }
618
+ lines.push('')
619
+ }
620
+ if (!achieved) {
621
+ lines.push('Next step for a human:', `- ${nextStep(run)}`, '')
622
+ }
623
+ if (last?.report) {
624
+ lines.push('Last round report:', '', capText(last.report, 4000))
625
+ }
626
+ return lines.join('\n').trim()
627
+ }
628
+
629
+ /**
630
+ * Status lines for a goal run, used by the tool reply and `superagent_status`.
631
+ *
632
+ * @param {object | null} goalMode - run's goal mode record.
633
+ * @returns {string[]} zero or more lines.
634
+ */
635
+ export function describeGoal(goalMode) {
636
+ if (!goalMode || !Array.isArray(goalMode.acceptance)) return []
637
+ const rounds = goalMode.rounds ?? []
638
+ const last = rounds.at(-1)
639
+ const state = goalMode.achieved ? 'achieved' : goalMode.stop ? `stopped (${goalMode.stop.reason})` : 'in progress'
640
+ const lines = [
641
+ `goal mode: round ${rounds.length}/${goalMode.maxRounds} — ${state}; `
642
+ + `${goalMode.acceptance.length} acceptance condition(s)`,
643
+ ]
644
+ if (goalMode.stop) lines.push(`goal stop: ${stopLabel(goalMode.stop)}`)
645
+ if (last?.failed?.length > 0) {
646
+ lines.push(`goal failing: ${last.failed.map(item => `[${item.id}] ${oneLine(item.text, 90)}`).join('; ')}`)
647
+ }
648
+ return lines
649
+ }
package/lib/guard.js CHANGED
@@ -490,6 +490,11 @@ function resolvePolicy({ config, cwd, homedir, platform, env, tmpdir, warn }) {
490
490
  allowCommands: (Array.isArray(raw.allowCommands) ? raw.allowCommands : [])
491
491
  .map((entry, index) => compilePattern(entry, index, 'allow', warn))
492
492
  .filter(Boolean),
493
+ // Browser and desktop tools registered by the runtime-control layer belong
494
+ // to the parent session. A worker that calls them would be driving the
495
+ // user's screen behind the parent's back, so they are refused unless the
496
+ // profile says otherwise.
497
+ allowRuntimeTools: raw.allowRuntimeTools === true,
493
498
  maxEvents: Math.min(200, Math.max(1, Number.isFinite(Number(raw.maxEvents)) ? Math.trunc(Number(raw.maxEvents)) : 50)),
494
499
  }
495
500
  }
@@ -702,6 +707,16 @@ export function createGuard(options = {}) {
702
707
  }
703
708
  const context = contextFor(exec)
704
709
 
710
+ if (/^(browser|desktop)_/.test(name) && !policy.allowRuntimeTools) {
711
+ return {
712
+ blocked: true,
713
+ rule: 'guard/runtime-tool',
714
+ reason: 'worker agents may not drive the browser or the desktop; runtime control belongs to the parent session '
715
+ + '(set guard.allowRuntimeTools to change this)',
716
+ detail: truncate(name),
717
+ }
718
+ }
719
+
705
720
  let denial = null
706
721
  if (name === 'bash' || name === 'pwsh' || name === 'terminal_send') {
707
722
  const command = typeof args.command === 'string'