@xiangyixie/dsh-superagent 0.11.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.
- package/CHANGELOG.md +85 -10
- package/README.md +322 -28
- package/bin/doctor.js +1 -1
- package/bin/sync.js +187 -0
- package/bin/workbench.js +98 -0
- package/docs/policy.example.json +38 -0
- package/lib/audit.js +555 -0
- package/lib/doctor.js +2 -0
- package/lib/guard.js +841 -0
- package/lib/index.js +493 -9
- package/lib/inject.js +138 -0
- package/lib/orchestrator.js +543 -4
- package/lib/policy.js +739 -0
- package/lib/sync.js +456 -0
- package/lib/workbench.js +1119 -0
- package/package.json +92 -80
- package/public/workbench.html +836 -0
package/lib/orchestrator.js
CHANGED
|
@@ -57,6 +57,10 @@ const ATTENTION_FENCE = /```attention[^\n]*\n([\s\S]*?)```/i
|
|
|
57
57
|
const FOLLOWUP_MAX = 8
|
|
58
58
|
/** Characters kept from one instruction or answer. */
|
|
59
59
|
const FOLLOWUP_MAX_CHARS = 1000
|
|
60
|
+
/** Live injection receipts kept per run; each may target several workers. */
|
|
61
|
+
const INJECTION_MAX = 12
|
|
62
|
+
/** Poll period for the measurement of one step boundary, in milliseconds. */
|
|
63
|
+
const INJECT_POLL_MS = 25
|
|
60
64
|
/** How many expired attention batches stay readable for a late answer. */
|
|
61
65
|
const ATTENTION_HISTORY_MAX = 5
|
|
62
66
|
|
|
@@ -774,6 +778,8 @@ function ensureCounters(run) {
|
|
|
774
778
|
* @param {(childId: string) => Promise<object | null>} deps.readUsage
|
|
775
779
|
* @param {(run: object) => object | void | Promise<object | void>} deps.notify - wake the owning session once.
|
|
776
780
|
* @param {object | null} [deps.memory] - cross-run notebook from `createMemory`; null disables it.
|
|
781
|
+
* @param {object | null} [deps.guard] - worker safety guard from `createGuard`; its
|
|
782
|
+
* snapshot is attached to each run record and its events to the report.
|
|
777
783
|
* @param {(message: string) => void} [deps.log]
|
|
778
784
|
* @param {() => number} [deps.now]
|
|
779
785
|
* @param {(ms: number) => Promise<void>} [deps.sleep]
|
|
@@ -789,6 +795,11 @@ export function createOrchestrator(deps) {
|
|
|
789
795
|
notify,
|
|
790
796
|
memory = null,
|
|
791
797
|
workspace = null,
|
|
798
|
+
guard = null,
|
|
799
|
+
audit = null,
|
|
800
|
+
steerChild = null,
|
|
801
|
+
inspectChild = null,
|
|
802
|
+
watchChild = null,
|
|
792
803
|
log = () => {},
|
|
793
804
|
now = () => Date.now(),
|
|
794
805
|
sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
|
|
@@ -997,6 +1008,10 @@ export function createOrchestrator(deps) {
|
|
|
997
1008
|
|
|
998
1009
|
function save(run) {
|
|
999
1010
|
run.updatedAt = new Date(now()).toISOString()
|
|
1011
|
+
// The guard is process-wide and owned by the caller; copy its counters onto
|
|
1012
|
+
// the record so status and the stored run show what was blocked.
|
|
1013
|
+
const snapshot = guard?.snapshot?.(run.id)
|
|
1014
|
+
if (snapshot) run.guard = snapshot
|
|
1000
1015
|
const previous = saveChains.get(run.id) ?? Promise.resolve()
|
|
1001
1016
|
const next = previous.catch(() => {}).then(() => store.write(run))
|
|
1002
1017
|
saveChains.set(run.id, next)
|
|
@@ -1164,6 +1179,21 @@ export function createOrchestrator(deps) {
|
|
|
1164
1179
|
await pumpQueue().catch(() => {})
|
|
1165
1180
|
}
|
|
1166
1181
|
|
|
1182
|
+
/**
|
|
1183
|
+
* Write one audit event. The trail is an observer: a failure is logged and
|
|
1184
|
+
* dropped, never allowed to change the outcome of the run it describes.
|
|
1185
|
+
* `audit` is optional so a host without the audit layer behaves exactly as
|
|
1186
|
+
* it did before it existed.
|
|
1187
|
+
*
|
|
1188
|
+
* @param {object} event - fields for `audit.record`.
|
|
1189
|
+
*/
|
|
1190
|
+
function auditRecord(event) {
|
|
1191
|
+
if (!audit || typeof audit.record !== 'function') return Promise.resolve()
|
|
1192
|
+
return Promise.resolve()
|
|
1193
|
+
.then(() => audit.record(event))
|
|
1194
|
+
.catch(error => log(`cannot write an audit event for run ${event?.runId ?? 'unknown'}: ${error?.message ?? error}`))
|
|
1195
|
+
}
|
|
1196
|
+
|
|
1167
1197
|
/**
|
|
1168
1198
|
* Record one phase transition on the run. Milestones are observational only:
|
|
1169
1199
|
* they appear in `superagent_status` and never wake the session, which is what
|
|
@@ -1204,6 +1234,16 @@ export function createOrchestrator(deps) {
|
|
|
1204
1234
|
options: attention.options ?? [],
|
|
1205
1235
|
reason: attention.reason ?? null,
|
|
1206
1236
|
})
|
|
1237
|
+
auditRecord({
|
|
1238
|
+
runId: run.id,
|
|
1239
|
+
subtaskId: source,
|
|
1240
|
+
actor: 'agent',
|
|
1241
|
+
kind: 'attention',
|
|
1242
|
+
action: 'attention.request',
|
|
1243
|
+
target: attention.question,
|
|
1244
|
+
result: 'pending',
|
|
1245
|
+
meta: { options: attention.options ?? [], reason: attention.reason ?? null },
|
|
1246
|
+
})
|
|
1207
1247
|
}
|
|
1208
1248
|
|
|
1209
1249
|
/**
|
|
@@ -1274,6 +1314,355 @@ export function createOrchestrator(deps) {
|
|
|
1274
1314
|
return changed
|
|
1275
1315
|
}
|
|
1276
1316
|
|
|
1317
|
+
/**
|
|
1318
|
+
* Record one live injection and its per-worker receipts.
|
|
1319
|
+
*
|
|
1320
|
+
* This is a separate trail from `run.followups` on purpose: a followup is
|
|
1321
|
+
* carried by the next prompt built for the run, while an injection is handed
|
|
1322
|
+
* to an inbox that is already executing. Mixing them would make status
|
|
1323
|
+
* promise a boundary that the message never uses.
|
|
1324
|
+
*
|
|
1325
|
+
* @param {object} run - live run record.
|
|
1326
|
+
* @param {string} text - the instruction.
|
|
1327
|
+
* @returns {object} the stored entry, with an empty `targets` list.
|
|
1328
|
+
*/
|
|
1329
|
+
function pushInjection(run, text) {
|
|
1330
|
+
run.injections = Array.isArray(run.injections) ? run.injections : []
|
|
1331
|
+
const entry = {
|
|
1332
|
+
id: `i${(Number(run.injectionSeq) || 0) + 1}`,
|
|
1333
|
+
text: capChars(text, FOLLOWUP_MAX_CHARS),
|
|
1334
|
+
at: new Date(now()).toISOString(),
|
|
1335
|
+
delivery: 'steer',
|
|
1336
|
+
status: 'pending',
|
|
1337
|
+
followupId: null,
|
|
1338
|
+
targets: [],
|
|
1339
|
+
}
|
|
1340
|
+
run.injectionSeq = (Number(run.injectionSeq) || 0) + 1
|
|
1341
|
+
run.injections.push(entry)
|
|
1342
|
+
if (run.injections.length > INJECTION_MAX) run.injections = run.injections.slice(-INJECTION_MAX)
|
|
1343
|
+
return entry
|
|
1344
|
+
}
|
|
1345
|
+
|
|
1346
|
+
/** Watchers are runtime state, never persisted with the run. */
|
|
1347
|
+
const injectionWatches = new Map()
|
|
1348
|
+
const watchKey = (runId, injectionId, childId) => `${runId}:${injectionId}:${childId}`
|
|
1349
|
+
|
|
1350
|
+
function stopWatch(runId, injectionId, childId) {
|
|
1351
|
+
const key = watchKey(runId, injectionId, childId)
|
|
1352
|
+
const stop = injectionWatches.get(key)
|
|
1353
|
+
if (!stop) return
|
|
1354
|
+
injectionWatches.delete(key)
|
|
1355
|
+
try {
|
|
1356
|
+
stop()
|
|
1357
|
+
} catch (error) {
|
|
1358
|
+
log(`cannot stop the injection watcher for ${childId}: ${error?.message ?? error}`)
|
|
1359
|
+
}
|
|
1360
|
+
}
|
|
1361
|
+
|
|
1362
|
+
function stopRunWatches(runId) {
|
|
1363
|
+
for (const key of [...injectionWatches.keys()]) {
|
|
1364
|
+
if (key.split(':')[0] !== runId) continue
|
|
1365
|
+
stopWatch(...key.split(':'))
|
|
1366
|
+
}
|
|
1367
|
+
}
|
|
1368
|
+
|
|
1369
|
+
/**
|
|
1370
|
+
* Recompute the run totals kept for status and tool replies.
|
|
1371
|
+
* @param {object} run - live run record.
|
|
1372
|
+
*/
|
|
1373
|
+
function refreshInjectionStats(run) {
|
|
1374
|
+
const targets = (run.injections ?? []).flatMap(entry => entry.targets ?? [])
|
|
1375
|
+
const applied = targets.filter(target => target.status === 'applied')
|
|
1376
|
+
const latencies = applied.map(target => target.latencyMs).filter(value => Number.isFinite(value))
|
|
1377
|
+
for (const entry of run.injections ?? []) {
|
|
1378
|
+
if (entry.status === 'degraded') continue
|
|
1379
|
+
const own = entry.targets ?? []
|
|
1380
|
+
if (own.length === 0) entry.status = 'failed'
|
|
1381
|
+
else if (own.some(target => target.status === 'pending')) entry.status = 'pending'
|
|
1382
|
+
else if (own.every(target => target.status === 'applied')) entry.status = 'applied'
|
|
1383
|
+
else if (own.some(target => target.status === 'applied')) entry.status = 'partial'
|
|
1384
|
+
else entry.status = 'missed'
|
|
1385
|
+
}
|
|
1386
|
+
run.injectionStats = {
|
|
1387
|
+
accepted: targets.filter(target => Boolean(target.messageId)).length,
|
|
1388
|
+
applied: applied.length,
|
|
1389
|
+
missed: targets.filter(target => target.status === 'missed').length,
|
|
1390
|
+
failed: targets.filter(target => target.status === 'failed').length,
|
|
1391
|
+
pending: targets.filter(target => target.status === 'pending').length,
|
|
1392
|
+
lastLatencyMs: latencies.length ? latencies[latencies.length - 1] : null,
|
|
1393
|
+
worstLatencyMs: latencies.length ? Math.max(...latencies) : null,
|
|
1394
|
+
samples: latencies.length,
|
|
1395
|
+
}
|
|
1396
|
+
}
|
|
1397
|
+
|
|
1398
|
+
/**
|
|
1399
|
+
* Move one worker receipt out of `pending`, once.
|
|
1400
|
+
*
|
|
1401
|
+
* `applied` is only recorded with the claim time the caller observed; a
|
|
1402
|
+
* dispatch that settles without observing a claim is not upgraded here.
|
|
1403
|
+
*
|
|
1404
|
+
* @param {object} run - live run record.
|
|
1405
|
+
* @param {object} target - one receipt.
|
|
1406
|
+
* @param {'applied'|'missed'} status - observed outcome.
|
|
1407
|
+
* @param {{ at?: number, reason?: string }} [detail] - claim time or miss reason.
|
|
1408
|
+
* @returns {boolean} whether the receipt changed.
|
|
1409
|
+
*/
|
|
1410
|
+
function finishInjectionTarget(run, target, status, detail = {}) {
|
|
1411
|
+
if (!target || target.status !== 'pending') return false
|
|
1412
|
+
target.status = status
|
|
1413
|
+
if (status === 'applied') {
|
|
1414
|
+
const at = Number.isFinite(detail.at) ? detail.at : now()
|
|
1415
|
+
const accepted = Date.parse(target.acceptedAt ?? '')
|
|
1416
|
+
target.appliedAt = new Date(at).toISOString()
|
|
1417
|
+
target.latencyMs = Number.isFinite(accepted) ? Math.max(0, at - accepted) : null
|
|
1418
|
+
} else {
|
|
1419
|
+
target.missedAt = new Date(now()).toISOString()
|
|
1420
|
+
target.missedReason = detail.reason ?? 'the child never reached another step boundary'
|
|
1421
|
+
target.latencyMs = null
|
|
1422
|
+
}
|
|
1423
|
+
return true
|
|
1424
|
+
}
|
|
1425
|
+
|
|
1426
|
+
/**
|
|
1427
|
+
* Persist a receipt change without holding up the caller's serialized action.
|
|
1428
|
+
* @param {object} run - live run record.
|
|
1429
|
+
* @param {object} target - one receipt.
|
|
1430
|
+
* @param {'applied'|'missed'} status - observed outcome.
|
|
1431
|
+
* @param {{ at?: number, reason?: string }} [detail] - claim time or miss reason.
|
|
1432
|
+
*/
|
|
1433
|
+
function recordInjectionTarget(run, target, status, detail) {
|
|
1434
|
+
if (!finishInjectionTarget(run, target, status, detail)) return
|
|
1435
|
+
refreshInjectionStats(run)
|
|
1436
|
+
save(run).catch(error => log(`cannot persist the injection state of run ${run.id}: ${error?.message ?? error}`))
|
|
1437
|
+
}
|
|
1438
|
+
|
|
1439
|
+
/**
|
|
1440
|
+
* Poll one accepted message until the child claims it.
|
|
1441
|
+
*
|
|
1442
|
+
* @param {object} run - live run record.
|
|
1443
|
+
* @param {object} entry - injection receipt.
|
|
1444
|
+
* @param {object} target - one worker receipt.
|
|
1445
|
+
*/
|
|
1446
|
+
function watchInjection(run, entry, target) {
|
|
1447
|
+
if (typeof watchChild !== 'function' || !target.messageId) return
|
|
1448
|
+
const stop = watchChild(target.childId, target.messageId, {
|
|
1449
|
+
onClaimed: at => recordInjectionTarget(run, target, 'applied', { at }),
|
|
1450
|
+
onGone: () => recordInjectionTarget(run, target, 'missed', {
|
|
1451
|
+
reason: 'the child activation was disposed before it reached another step boundary',
|
|
1452
|
+
}),
|
|
1453
|
+
})
|
|
1454
|
+
const key = watchKey(run.id, entry.id, target.childId)
|
|
1455
|
+
const previous = injectionWatches.get(key)
|
|
1456
|
+
if (previous) {
|
|
1457
|
+
try {
|
|
1458
|
+
previous()
|
|
1459
|
+
} catch {
|
|
1460
|
+
// A stale watcher that cannot stop is harmless; the new one owns the receipt.
|
|
1461
|
+
}
|
|
1462
|
+
}
|
|
1463
|
+
injectionWatches.set(key, () => {
|
|
1464
|
+
if (stop && typeof stop.stop === 'function') stop.stop()
|
|
1465
|
+
else if (typeof stop === 'function') stop()
|
|
1466
|
+
})
|
|
1467
|
+
// The message can be claimed before the first poll: one immediate read keeps
|
|
1468
|
+
// a fast delivery from being displayed as pending for a full period.
|
|
1469
|
+
if (typeof stop?.check === 'function') {
|
|
1470
|
+
try {
|
|
1471
|
+
stop.check()
|
|
1472
|
+
} catch {
|
|
1473
|
+
// The poll keeps running; a failed first read is not a delivery failure.
|
|
1474
|
+
}
|
|
1475
|
+
}
|
|
1476
|
+
}
|
|
1477
|
+
|
|
1478
|
+
/**
|
|
1479
|
+
* Close every receipt aimed at one child that is leaving its attempt.
|
|
1480
|
+
*
|
|
1481
|
+
* Runs before disposal, so the inbox is still readable: a message that is
|
|
1482
|
+
* gone was claimed, and one that is still there never reached a prompt.
|
|
1483
|
+
*
|
|
1484
|
+
* @param {object} run - live run record.
|
|
1485
|
+
* @param {string | null | undefined} childId - departing child.
|
|
1486
|
+
* @param {string} reason - why a still-pending message will not be read.
|
|
1487
|
+
* @returns {boolean} whether the run needs a save.
|
|
1488
|
+
*/
|
|
1489
|
+
function settleChildInjections(run, childId, reason) {
|
|
1490
|
+
if (!childId) return false
|
|
1491
|
+
const targets = (run.injections ?? [])
|
|
1492
|
+
.flatMap(entry => (entry.targets ?? []).map(target => ({ entry, target })))
|
|
1493
|
+
.filter(({ target }) => target.childId === childId && target.status === 'pending')
|
|
1494
|
+
if (targets.length === 0) return false
|
|
1495
|
+
let inspected = null
|
|
1496
|
+
try {
|
|
1497
|
+
inspected = typeof inspectChild === 'function' ? inspectChild(childId) : null
|
|
1498
|
+
} catch {
|
|
1499
|
+
inspected = null
|
|
1500
|
+
}
|
|
1501
|
+
let changed = false
|
|
1502
|
+
for (const { entry, target } of targets) {
|
|
1503
|
+
stopWatch(run.id, entry.id, target.childId)
|
|
1504
|
+
const live = Boolean(inspected?.live)
|
|
1505
|
+
const stillPending = live && inspected?.pending?.has?.(String(target.messageId))
|
|
1506
|
+
changed = finishInjectionTarget(run, target, live && !stillPending ? 'applied' : 'missed', {
|
|
1507
|
+
reason: live
|
|
1508
|
+
? reason
|
|
1509
|
+
: 'the child was gone before the message reached another step boundary',
|
|
1510
|
+
}) || changed
|
|
1511
|
+
}
|
|
1512
|
+
if (changed) refreshInjectionStats(run)
|
|
1513
|
+
return changed
|
|
1514
|
+
}
|
|
1515
|
+
|
|
1516
|
+
/**
|
|
1517
|
+
* Deliver one instruction into the workers that are running now.
|
|
1518
|
+
*
|
|
1519
|
+
* Delivery is a steer: `agent-loop` claims it at the next pre-step, so it is
|
|
1520
|
+
* part of the child's next model request instead of interrupting the one in
|
|
1521
|
+
* flight. A child that had already decided to stop runs one more turn when
|
|
1522
|
+
* the inbox is non-empty, which is why a live, uncancelled child consumes it.
|
|
1523
|
+
* The latency is measured from acceptance to that claim and written on the
|
|
1524
|
+
* receipt; the theoretical bound is the remainder of the running step.
|
|
1525
|
+
*
|
|
1526
|
+
* @param {string} runId - run identity.
|
|
1527
|
+
* @param {string} text - the instruction.
|
|
1528
|
+
* @param {object} parent - live agent that owns the run.
|
|
1529
|
+
* @param {{ subtaskIndex?: number | string | null }} [options] - narrow to one worker.
|
|
1530
|
+
* @returns {Promise<{ run: object, injection: object, degraded: object | null, effect: object }>}
|
|
1531
|
+
*/
|
|
1532
|
+
async function inject(runId, text, parent, options = {}) {
|
|
1533
|
+
const id = String(runId ?? '').trim()
|
|
1534
|
+
if (!id) throw new Error('run_id is required')
|
|
1535
|
+
const message = capChars(text, FOLLOWUP_MAX_CHARS)
|
|
1536
|
+
if (!message) throw new Error('message is required; pass the instruction the running workers should read')
|
|
1537
|
+
if (!parent || typeof parent !== 'object') throw new Error('superagent requires a live parent agent')
|
|
1538
|
+
const rawIndex = options.subtaskIndex
|
|
1539
|
+
const wanted = rawIndex === undefined || rawIndex === null || rawIndex === ''
|
|
1540
|
+
? null
|
|
1541
|
+
: Number(rawIndex)
|
|
1542
|
+
if (wanted !== null && !Number.isInteger(wanted)) {
|
|
1543
|
+
throw new Error('subtask_index must be a whole number from superagent_status')
|
|
1544
|
+
}
|
|
1545
|
+
return serialize(async () => {
|
|
1546
|
+
const rt = runtime.get(id)
|
|
1547
|
+
const run = rt?.run ?? await loadRun(id)
|
|
1548
|
+
assertResumeOwner(run, parent)
|
|
1549
|
+
if (!ACTIVE_STATUSES.has(run.status)) {
|
|
1550
|
+
throw new Error(
|
|
1551
|
+
`run ${id} is ${run.status}, so no child is running to receive a live instruction. `
|
|
1552
|
+
+ 'Use superagent_followup to queue it for the next prompt.',
|
|
1553
|
+
)
|
|
1554
|
+
}
|
|
1555
|
+
if (!rt) {
|
|
1556
|
+
throw new Error(
|
|
1557
|
+
`run ${id} is active but owned by another process; a live instruction must come from the process that owns `
|
|
1558
|
+
+ 'its children, because only that process holds their inboxes.',
|
|
1559
|
+
)
|
|
1560
|
+
}
|
|
1561
|
+
const running = (run.subtasks ?? []).filter(subtask => subtask.status === 'running' && subtask.childId)
|
|
1562
|
+
const selected = wanted === null ? running : running.filter(subtask => subtask.index === wanted)
|
|
1563
|
+
// A running subtask can be between attempts, where its old child id no
|
|
1564
|
+
// longer resolves. Steering a dead inbox would look like delivery, so the
|
|
1565
|
+
// live ones are selected here and the reply names the gap otherwise.
|
|
1566
|
+
const live = typeof inspectChild === 'function'
|
|
1567
|
+
? selected.filter(subtask => {
|
|
1568
|
+
try {
|
|
1569
|
+
return Boolean(inspectChild(subtask.childId)?.live)
|
|
1570
|
+
} catch {
|
|
1571
|
+
return false
|
|
1572
|
+
}
|
|
1573
|
+
})
|
|
1574
|
+
: selected
|
|
1575
|
+
const targets = live
|
|
1576
|
+
if (targets.length === 0) {
|
|
1577
|
+
const who = wanted === null ? 'no worker is live' : `worker ${wanted} is not live`
|
|
1578
|
+
const activity = (run.subtasks ?? [])
|
|
1579
|
+
.filter(subtask => subtask.status === 'running')
|
|
1580
|
+
.map(subtask => `#${subtask.index}`)
|
|
1581
|
+
.join(', ')
|
|
1582
|
+
throw new Error(
|
|
1583
|
+
`${who} on run ${id} (status ${run.status}${activity ? `, attempts in progress: ${activity}` : ''}), so `
|
|
1584
|
+
+ 'there is no inbox to steer right now. superagent_followup queues the instruction for the next prompt '
|
|
1585
|
+
+ 'instead.',
|
|
1586
|
+
)
|
|
1587
|
+
}
|
|
1588
|
+
const entry = pushInjection(run, message)
|
|
1589
|
+
let unsupported = null
|
|
1590
|
+
for (const subtask of targets) {
|
|
1591
|
+
const target = {
|
|
1592
|
+
subtaskIndex: subtask.index,
|
|
1593
|
+
childId: subtask.childId,
|
|
1594
|
+
messageId: null,
|
|
1595
|
+
via: null,
|
|
1596
|
+
acceptedAt: new Date(now()).toISOString(),
|
|
1597
|
+
status: 'pending',
|
|
1598
|
+
appliedAt: null,
|
|
1599
|
+
latencyMs: null,
|
|
1600
|
+
missedAt: null,
|
|
1601
|
+
missedReason: null,
|
|
1602
|
+
error: null,
|
|
1603
|
+
}
|
|
1604
|
+
entry.targets.push(target)
|
|
1605
|
+
if (typeof steerChild !== 'function') {
|
|
1606
|
+
target.status = 'failed'
|
|
1607
|
+
target.error = 'this host exposes no live channel into a running child'
|
|
1608
|
+
unsupported = target.error
|
|
1609
|
+
continue
|
|
1610
|
+
}
|
|
1611
|
+
try {
|
|
1612
|
+
const receipt = await steerChild({
|
|
1613
|
+
parent,
|
|
1614
|
+
childId: target.childId,
|
|
1615
|
+
text: message,
|
|
1616
|
+
signal: rt.controller.signal,
|
|
1617
|
+
})
|
|
1618
|
+
target.messageId = String(receipt?.messageId ?? '')
|
|
1619
|
+
target.via = receipt?.via ?? null
|
|
1620
|
+
watchInjection(run, entry, target)
|
|
1621
|
+
} catch (error) {
|
|
1622
|
+
target.status = 'failed'
|
|
1623
|
+
target.error = error?.message ?? String(error)
|
|
1624
|
+
if (error?.code === 'inject-unsupported') unsupported = target.error
|
|
1625
|
+
else if (error?.code === 'inject-child-gone') target.error = `${target.error}; the worker already settled`
|
|
1626
|
+
}
|
|
1627
|
+
}
|
|
1628
|
+
let degraded = null
|
|
1629
|
+
if (unsupported && entry.targets.every(target => target.status === 'failed')) {
|
|
1630
|
+
// No live channel at all. Do not pretend the instruction was delivered:
|
|
1631
|
+
// queue it exactly where superagent_followup would, and label the
|
|
1632
|
+
// receipt as degraded so status cannot read as a live delivery.
|
|
1633
|
+
const followup = pushFollowup(run, { kind: 'followup', text: message })
|
|
1634
|
+
entry.status = 'degraded'
|
|
1635
|
+
entry.followupId = followup.id
|
|
1636
|
+
degraded = { followup, effect: followupEffect(run), reason: unsupported }
|
|
1637
|
+
}
|
|
1638
|
+
refreshInjectionStats(run)
|
|
1639
|
+
await save(run)
|
|
1640
|
+
return { run, injection: entry, degraded, effect: followupEffect(run) }
|
|
1641
|
+
})
|
|
1642
|
+
}
|
|
1643
|
+
|
|
1644
|
+
/**
|
|
1645
|
+
* Wait for the receipts of one injection to leave `pending`.
|
|
1646
|
+
*
|
|
1647
|
+
* The claim is observed by a poll, so the reported latency has that
|
|
1648
|
+
* resolution; waiting does not change delivery, only what the reply can say.
|
|
1649
|
+
*
|
|
1650
|
+
* @param {object} run - live run record.
|
|
1651
|
+
* @param {object} entry - injection receipt.
|
|
1652
|
+
* @param {number} [seconds] - upper bound on the wait.
|
|
1653
|
+
* @returns {Promise<object>} the same entry, updated in place.
|
|
1654
|
+
*/
|
|
1655
|
+
async function waitForInjection(run, entry, seconds) {
|
|
1656
|
+
const limit = Math.max(0, Number(seconds) || 0) * 1000
|
|
1657
|
+
if (limit <= 0) return entry
|
|
1658
|
+
const started = now()
|
|
1659
|
+
while (now() - started < limit) {
|
|
1660
|
+
if (!(entry.targets ?? []).some(target => target.status === 'pending')) break
|
|
1661
|
+
await sleep(Math.min(INJECT_POLL_MS * 2, Math.max(5, limit - (now() - started))))
|
|
1662
|
+
}
|
|
1663
|
+
return entry
|
|
1664
|
+
}
|
|
1665
|
+
|
|
1277
1666
|
/**
|
|
1278
1667
|
* Write the final report next to the run state, so the outcome has an address
|
|
1279
1668
|
* the user can open or attach, not only a paragraph in a tool reply. The
|
|
@@ -1791,7 +2180,8 @@ export function createOrchestrator(deps) {
|
|
|
1791
2180
|
// crash cannot lose the only evidence of a model call.
|
|
1792
2181
|
ensureCounters(run).spawns += 1
|
|
1793
2182
|
await save(run)
|
|
1794
|
-
|
|
2183
|
+
// runId lets the caller bind the child to this run's guard counters.
|
|
2184
|
+
return spawnAbortable({ ...spec, runId: run.id }, rt.controller.signal)
|
|
1795
2185
|
}
|
|
1796
2186
|
|
|
1797
2187
|
/**
|
|
@@ -2077,6 +2467,13 @@ export function createOrchestrator(deps) {
|
|
|
2077
2467
|
if (handle) {
|
|
2078
2468
|
// A failed attempt still spent tokens, so read it before disposing.
|
|
2079
2469
|
await recordUsage(run, handle.childId)
|
|
2470
|
+
// Receipts are resolved while the inbox is still readable: a message
|
|
2471
|
+
// still waiting here never entered a prompt for this attempt.
|
|
2472
|
+
if (settleChildInjections(
|
|
2473
|
+
run,
|
|
2474
|
+
handle.childId,
|
|
2475
|
+
'the child finished its turn before the instruction reached another step boundary',
|
|
2476
|
+
)) await save(run)
|
|
2080
2477
|
rt.activations.delete(handle)
|
|
2081
2478
|
await disposeQuietly(handle)
|
|
2082
2479
|
}
|
|
@@ -2306,6 +2703,21 @@ export function createOrchestrator(deps) {
|
|
|
2306
2703
|
entry.missedReason = 'the run settled before another boundary ran; start a new run to apply it'
|
|
2307
2704
|
}
|
|
2308
2705
|
|
|
2706
|
+
// A live injection has no boundary of its own: once the run is over, an
|
|
2707
|
+
// untouched receipt is a miss, and the queue that carried it is gone.
|
|
2708
|
+
let injectionsChanged = false
|
|
2709
|
+
for (const injection of run.injections ?? []) {
|
|
2710
|
+
for (const target of injection.targets ?? []) {
|
|
2711
|
+
if (target.status !== 'pending') continue
|
|
2712
|
+
stopWatch(run.id, injection.id, target.childId)
|
|
2713
|
+
finishInjectionTarget(run, target, 'missed', {
|
|
2714
|
+
reason: 'the run settled before the child reached another step boundary',
|
|
2715
|
+
})
|
|
2716
|
+
injectionsChanged = true
|
|
2717
|
+
}
|
|
2718
|
+
}
|
|
2719
|
+
if (injectionsChanged) refreshInjectionStats(run)
|
|
2720
|
+
|
|
2309
2721
|
// The aggregator appends a fenced notebook block to its report. Strip it in
|
|
2310
2722
|
// every case so the user never sees plugin syntax, then persist it when the
|
|
2311
2723
|
// notebook is enabled. A write failure is recorded on the run but never
|
|
@@ -2359,6 +2771,12 @@ export function createOrchestrator(deps) {
|
|
|
2359
2771
|
}
|
|
2360
2772
|
}
|
|
2361
2773
|
}
|
|
2774
|
+
// The guard's event list belongs in the user-facing report, not only in the
|
|
2775
|
+
// status line: a blocked command is part of what happened during the run.
|
|
2776
|
+
const guardSection = guard?.reportSection?.(run.id)
|
|
2777
|
+
if (guardSection && typeof run.report === 'string' && run.report) {
|
|
2778
|
+
run.report = `${run.report.trimEnd()}\n\n${guardSection}`
|
|
2779
|
+
}
|
|
2362
2780
|
// The report gets a durable address before the run is announced, so a
|
|
2363
2781
|
// notification or status line can point at a file that already exists.
|
|
2364
2782
|
if (TERMINAL_STATUSES.has(nextStatus)) await writeReportArtifact(run)
|
|
@@ -2416,6 +2834,24 @@ export function createOrchestrator(deps) {
|
|
|
2416
2834
|
if (outcome.delivered !== false) run.notified = true
|
|
2417
2835
|
}
|
|
2418
2836
|
await save(run)
|
|
2837
|
+
// Awaited: the trail must contain the outcome before the run is published
|
|
2838
|
+
// as terminal, or a crash right here would leave a finished run with no
|
|
2839
|
+
// record of how it finished. A failure is still only logged.
|
|
2840
|
+
await auditRecord({
|
|
2841
|
+
runId: run.id,
|
|
2842
|
+
actor: `session:${run.parentSessionId}`,
|
|
2843
|
+
kind: 'run.finish',
|
|
2844
|
+
action: 'settle',
|
|
2845
|
+
target: oneLine(run.goal, 200),
|
|
2846
|
+
result: nextStatus,
|
|
2847
|
+
durationMs: run.activeMs,
|
|
2848
|
+
meta: {
|
|
2849
|
+
subtasks: run.subtasks.length,
|
|
2850
|
+
completed: run.subtasks.filter(subtask => subtask.status === 'completed').length,
|
|
2851
|
+
attention: Boolean(run.attention?.items?.length),
|
|
2852
|
+
error: error ? oneLine(error, 300) : null,
|
|
2853
|
+
},
|
|
2854
|
+
})
|
|
2419
2855
|
// The run is terminal, so a leftover marker would only make the next mount
|
|
2420
2856
|
// rewrite a finished run; drop it now.
|
|
2421
2857
|
await clearCancel(run.id)
|
|
@@ -2702,6 +3138,7 @@ export function createOrchestrator(deps) {
|
|
|
2702
3138
|
.then(() => {
|
|
2703
3139
|
// Finished runs are read from disk from now on; keeping them here would
|
|
2704
3140
|
// grow these maps for the lifetime of the host.
|
|
3141
|
+
stopRunWatches(run.id)
|
|
2705
3142
|
runtime.delete(run.id)
|
|
2706
3143
|
saveChains.delete(run.id)
|
|
2707
3144
|
// The slot this run held may let a waiting run start.
|
|
@@ -2726,6 +3163,7 @@ export function createOrchestrator(deps) {
|
|
|
2726
3163
|
allowDuplicate = false,
|
|
2727
3164
|
queue: wantsQueue = false,
|
|
2728
3165
|
mode: requestedMode,
|
|
3166
|
+
approvePolicy = false,
|
|
2729
3167
|
}) {
|
|
2730
3168
|
const trimmed = typeof goal === 'string' ? goal.trim() : ''
|
|
2731
3169
|
if (!trimmed) throw new Error('goal is required')
|
|
@@ -2768,12 +3206,44 @@ export function createOrchestrator(deps) {
|
|
|
2768
3206
|
)
|
|
2769
3207
|
}
|
|
2770
3208
|
}
|
|
3209
|
+
// A permission policy decides whether this start may exist at all. The
|
|
3210
|
+
// verdict is recorded before the run is written, so a refused start still
|
|
3211
|
+
// leaves evidence of what was asked for and why it was stopped.
|
|
3212
|
+
const runId = newRunId()
|
|
3213
|
+
if (audit && typeof audit.gate === 'function') {
|
|
3214
|
+
const verdict = await audit.gate({
|
|
3215
|
+
runId,
|
|
3216
|
+
kind: 'run.start',
|
|
3217
|
+
action: 'superagent_start',
|
|
3218
|
+
actor: `session:${parentSessionId}`,
|
|
3219
|
+
target: oneLine(trimmed, 200),
|
|
3220
|
+
meta: { goalChars: trimmed.length },
|
|
3221
|
+
})
|
|
3222
|
+
const trail = verdict.eventId ? ` (audit event ${verdict.eventId})` : ''
|
|
3223
|
+
if (verdict.decision === 'deny') {
|
|
3224
|
+
throw new Error(`refused by the permission policy: ${verdict.reason}${trail}`)
|
|
3225
|
+
}
|
|
3226
|
+
if (verdict.decision === 'confirm') {
|
|
3227
|
+
if (!approvePolicy) {
|
|
3228
|
+
throw new Error(
|
|
3229
|
+
`the permission policy holds this start for confirmation: ${verdict.reason}${trail}; `
|
|
3230
|
+
+ 'call superagent_start again with approve_policy: true to release it',
|
|
3231
|
+
)
|
|
3232
|
+
}
|
|
3233
|
+
await audit.approve(verdict.eventId, {
|
|
3234
|
+
actor: `session:${parentSessionId}`,
|
|
3235
|
+
note: 'approve_policy on superagent_start',
|
|
3236
|
+
runId,
|
|
3237
|
+
kind: 'run.start',
|
|
3238
|
+
})
|
|
3239
|
+
}
|
|
3240
|
+
}
|
|
2771
3241
|
// Read once, here: the digest is part of the run record, so a status call
|
|
2772
3242
|
// can show exactly what the planner was told, and a resumed run does not
|
|
2773
3243
|
// silently change the context its plan was based on.
|
|
2774
3244
|
const context = await memoryContext(null, trimmed)
|
|
2775
3245
|
const run = {
|
|
2776
|
-
id:
|
|
3246
|
+
id: runId,
|
|
2777
3247
|
schemaVersion: 1,
|
|
2778
3248
|
goal: trimmed,
|
|
2779
3249
|
dedupeKey,
|
|
@@ -2866,7 +3336,7 @@ export function createOrchestrator(deps) {
|
|
|
2866
3336
|
* `reopen` lets `superagent_answer` continue a `completed` run: its subtasks
|
|
2867
3337
|
* stay done and only the aggregation runs again, now with the answer.
|
|
2868
3338
|
*/
|
|
2869
|
-
async function resumeLocked(runId, parent, clientTimeZone, { reopen = false } = {}) {
|
|
3339
|
+
async function resumeLocked(runId, parent, clientTimeZone, { reopen = false, approvePolicy = false } = {}) {
|
|
2870
3340
|
const id = String(runId ?? '').trim()
|
|
2871
3341
|
if (!parent || typeof parent !== 'object') throw new Error('superagent requires a live parent agent')
|
|
2872
3342
|
{
|
|
@@ -2900,6 +3370,36 @@ export function createOrchestrator(deps) {
|
|
|
2900
3370
|
assertResumeOwner(run, parent)
|
|
2901
3371
|
reopenCompleted = reopen || hasUnappliedAnswer(run)
|
|
2902
3372
|
if (run.status === 'completed' && !reopenCompleted) return run
|
|
3373
|
+
// A resume spends the remaining budget again, so a per-run deny applies
|
|
3374
|
+
// to it as well; otherwise a policy added mid-run could be bypassed by
|
|
3375
|
+
// resuming the run instead of starting a new one.
|
|
3376
|
+
if (audit && typeof audit.gate === 'function') {
|
|
3377
|
+
const verdict = await audit.gate({
|
|
3378
|
+
runId: run.id,
|
|
3379
|
+
kind: 'run.resume',
|
|
3380
|
+
action: 'superagent_resume',
|
|
3381
|
+
actor: `session:${parent.id}`,
|
|
3382
|
+
target: oneLine(run.goal, 200),
|
|
3383
|
+
})
|
|
3384
|
+
const trail = verdict.eventId ? ` (audit event ${verdict.eventId})` : ''
|
|
3385
|
+
if (verdict.decision === 'deny') {
|
|
3386
|
+
throw new Error(`refused by the permission policy: ${verdict.reason}${trail}`)
|
|
3387
|
+
}
|
|
3388
|
+
if (verdict.decision === 'confirm') {
|
|
3389
|
+
if (!approvePolicy) {
|
|
3390
|
+
throw new Error(
|
|
3391
|
+
`the permission policy holds this resume for confirmation: ${verdict.reason}${trail}; `
|
|
3392
|
+
+ 'call superagent_resume again with approve_policy: true to release it',
|
|
3393
|
+
)
|
|
3394
|
+
}
|
|
3395
|
+
await audit.approve(verdict.eventId, {
|
|
3396
|
+
actor: `session:${parent.id}`,
|
|
3397
|
+
note: 'approve_policy on superagent_resume',
|
|
3398
|
+
runId: run.id,
|
|
3399
|
+
kind: 'run.resume',
|
|
3400
|
+
})
|
|
3401
|
+
}
|
|
3402
|
+
}
|
|
2903
3403
|
if (ACTIVE_STATUSES.has(run.status)) {
|
|
2904
3404
|
const verdict = await ownership(run)
|
|
2905
3405
|
if (verdict.live) {
|
|
@@ -2989,6 +3489,15 @@ export function createOrchestrator(deps) {
|
|
|
2989
3489
|
ensureCounters(run)
|
|
2990
3490
|
await save(run)
|
|
2991
3491
|
schedule(run, parent)
|
|
3492
|
+
auditRecord({
|
|
3493
|
+
runId: run.id,
|
|
3494
|
+
actor: `session:${parent.id}`,
|
|
3495
|
+
kind: 'run.resume',
|
|
3496
|
+
action: 'superagent_resume',
|
|
3497
|
+
target: oneLine(run.goal, 200),
|
|
3498
|
+
result: 'queued',
|
|
3499
|
+
meta: { previousStatus: run.recovery?.previousStatus ?? null },
|
|
3500
|
+
})
|
|
2992
3501
|
scheduled = true
|
|
2993
3502
|
return run
|
|
2994
3503
|
} finally {
|
|
@@ -3223,6 +3732,14 @@ export function createOrchestrator(deps) {
|
|
|
3223
3732
|
rt.run.cancelPending = true
|
|
3224
3733
|
await save(rt.run).catch(() => {})
|
|
3225
3734
|
}
|
|
3735
|
+
auditRecord({
|
|
3736
|
+
runId,
|
|
3737
|
+
actor: 'session',
|
|
3738
|
+
kind: 'run.cancel',
|
|
3739
|
+
action: 'superagent_cancel',
|
|
3740
|
+
result: ACTIVE_STATUSES.has(rt.run.status) ? 'requested' : 'cancelled',
|
|
3741
|
+
meta: { ownedHere: true },
|
|
3742
|
+
})
|
|
3226
3743
|
return rt.run
|
|
3227
3744
|
}
|
|
3228
3745
|
|
|
@@ -3234,6 +3751,14 @@ export function createOrchestrator(deps) {
|
|
|
3234
3751
|
// Writing `cancelled` here would be a lie: the owner would overwrite it on
|
|
3235
3752
|
// its next save and keep spending.
|
|
3236
3753
|
await requestCancel(runId)
|
|
3754
|
+
auditRecord({
|
|
3755
|
+
runId,
|
|
3756
|
+
actor: 'session',
|
|
3757
|
+
kind: 'run.cancel',
|
|
3758
|
+
action: 'superagent_cancel',
|
|
3759
|
+
result: 'requested',
|
|
3760
|
+
meta: { ownedHere: false },
|
|
3761
|
+
})
|
|
3237
3762
|
const endsAt = now() + CANCEL_ACK_MS
|
|
3238
3763
|
while (now() < endsAt) {
|
|
3239
3764
|
await sleep(STATUS_POLL_MS)
|
|
@@ -3308,5 +3833,19 @@ export function createOrchestrator(deps) {
|
|
|
3308
3833
|
await Promise.all([...runtime.values()].map(rt => rt.promise?.catch(() => {})))
|
|
3309
3834
|
}
|
|
3310
3835
|
|
|
3311
|
-
return {
|
|
3836
|
+
return {
|
|
3837
|
+
recover,
|
|
3838
|
+
start,
|
|
3839
|
+
resume,
|
|
3840
|
+
cancel,
|
|
3841
|
+
followup,
|
|
3842
|
+
answer,
|
|
3843
|
+
inject,
|
|
3844
|
+
waitForInjection,
|
|
3845
|
+
status,
|
|
3846
|
+
list,
|
|
3847
|
+
idle,
|
|
3848
|
+
activeCount,
|
|
3849
|
+
liveRun,
|
|
3850
|
+
}
|
|
3312
3851
|
}
|