@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/inject.js
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Live delivery of one instruction into a running child agent.
|
|
3
|
+
*
|
|
4
|
+
* The host has four input boundaries on an Agent: `send`, `followup`, `steer`,
|
|
5
|
+
* and `inject` (dsh-agent `runtime-types.d.ts`). `steer` is the one this module
|
|
6
|
+
* uses: the running driver claims it at its next pre-step, so the message is
|
|
7
|
+
* part of the child's next model request. When a steer arrives after the child
|
|
8
|
+
* already decided to stop, `agent-loop` sees a non-empty next-step inbox and
|
|
9
|
+
* runs one more turn instead of closing (`index.js`, turn loop) — so a live,
|
|
10
|
+
* uncancelled child always consumes it.
|
|
11
|
+
*
|
|
12
|
+
* Two host faces reach that inbox:
|
|
13
|
+
* 1. `subagents.sendMessage(parent, childId, content, { signal })` — the
|
|
14
|
+
* documented, admission-checked path between adjacent Agents. Preferred.
|
|
15
|
+
* 2. `agent.steer(message)` on the live child — the Agent API itself, used
|
|
16
|
+
* only when the service method is absent (a host built without it).
|
|
17
|
+
*
|
|
18
|
+
* Delivery is async: it lands at a step boundary, never in the middle of a
|
|
19
|
+
* model call. The watcher below measures that boundary by polling the child's
|
|
20
|
+
* inbox projection; `INJECT_POLL_MS` is the resolution of every measured
|
|
21
|
+
* figure, so it is reported with the number instead of hidden.
|
|
22
|
+
*
|
|
23
|
+
* @module dsh-superagent/inject
|
|
24
|
+
*/
|
|
25
|
+
import { randomUUID } from 'node:crypto'
|
|
26
|
+
|
|
27
|
+
/** Default poll period, in milliseconds, for the inbox claim. */
|
|
28
|
+
export const INJECT_POLL_MS = 25
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The ids still waiting at either inbox boundary of one live child.
|
|
32
|
+
* @param {object | null | undefined} agent - live child Agent.
|
|
33
|
+
* @returns {Set<string>} pending message ids.
|
|
34
|
+
*/
|
|
35
|
+
export function pendingIds(agent) {
|
|
36
|
+
const ids = new Set()
|
|
37
|
+
const inbox = agent?.inbox
|
|
38
|
+
for (const list of [inbox?.nextStep, inbox?.nextTurn]) {
|
|
39
|
+
for (const message of list ?? []) {
|
|
40
|
+
if (message?.id !== undefined) ids.add(String(message.id))
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
return ids
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Build the host-facing steer function.
|
|
48
|
+
*
|
|
49
|
+
* `subagents` and `agents` are getters, not services, because the subagent
|
|
50
|
+
* service can register after this plugin and can disappear while the host
|
|
51
|
+
* shuts down; reading it at call time keeps both states observable.
|
|
52
|
+
*
|
|
53
|
+
* @param {object} deps - host accessors.
|
|
54
|
+
* @param {() => object | undefined} deps.getSubagents - current subagent service.
|
|
55
|
+
* @param {() => object | undefined} deps.getAgents - current agent registry.
|
|
56
|
+
* @param {(message: string) => void} [deps.log]
|
|
57
|
+
* @returns {(spec: { parent: object, childId: string, text: string, signal?: AbortSignal }) => Promise<{ messageId: string, via: string }>}
|
|
58
|
+
*/
|
|
59
|
+
export function createChildSteerer({ getSubagents, getAgents, log = () => {} }) {
|
|
60
|
+
return async function steerChild({ parent, childId, text, signal }) {
|
|
61
|
+
const service = typeof getSubagents === 'function' ? getSubagents() : undefined
|
|
62
|
+
const registry = typeof getAgents === 'function' ? getAgents() : undefined
|
|
63
|
+
const live = registry && typeof registry.get === 'function' ? registry.get(childId) : undefined
|
|
64
|
+
if (!live) {
|
|
65
|
+
const error = new Error(
|
|
66
|
+
`child session ${childId} is no longer live in this host, so no inbox exists to carry the instruction`,
|
|
67
|
+
)
|
|
68
|
+
error.code = 'inject-child-gone'
|
|
69
|
+
throw error
|
|
70
|
+
}
|
|
71
|
+
const content = [{ type: 'text', text }]
|
|
72
|
+
const options = { signal: signal ?? new AbortController().signal }
|
|
73
|
+
if (service && typeof service.sendMessage === 'function') {
|
|
74
|
+
const messageId = await service.sendMessage(parent, childId, content, options)
|
|
75
|
+
return { messageId: String(messageId), via: 'subagents.sendMessage' }
|
|
76
|
+
}
|
|
77
|
+
if (typeof live.steer === 'function') {
|
|
78
|
+
const messageId = `inject-${randomUUID()}`
|
|
79
|
+
live.steer({ id: messageId, role: 'user', content, source: { kind: 'user' } })
|
|
80
|
+
return { messageId, via: 'agent.steer' }
|
|
81
|
+
}
|
|
82
|
+
const error = new Error(
|
|
83
|
+
'this host exposes no live channel into a running child: neither subagents.sendMessage nor Agent.steer exists',
|
|
84
|
+
)
|
|
85
|
+
error.code = 'inject-unsupported'
|
|
86
|
+
log(`live injection is unsupported by this host: ${error.message}`)
|
|
87
|
+
throw error
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Watch one accepted message until it leaves the child's inbox or the child
|
|
93
|
+
* disappears.
|
|
94
|
+
*
|
|
95
|
+
* Absence from the inbox is the claim signal: the step boundary removes the
|
|
96
|
+
* message before building its model request. The same absence also appears if
|
|
97
|
+
* the activation is cancelled or disposed, so the caller passes that evidence
|
|
98
|
+
* (`onGone`, or a run-level abort check) rather than assuming delivery.
|
|
99
|
+
*
|
|
100
|
+
* @param {object} deps - watcher dependencies.
|
|
101
|
+
* @param {(childId: string) => object | null | undefined} deps.resolveChild - live child lookup.
|
|
102
|
+
* @param {number} [deps.intervalMs] - poll period, defaults to `INJECT_POLL_MS`.
|
|
103
|
+
* @param {() => number} [deps.now] - clock, injectable for tests.
|
|
104
|
+
* @returns {(childId: string, messageId: string, handlers: { onClaimed?: (at: number) => void, onGone?: () => void }) => { stop: () => void, check: () => void }}
|
|
105
|
+
*/
|
|
106
|
+
export function createChildWatcher({ resolveChild, intervalMs = INJECT_POLL_MS, now = () => Date.now() }) {
|
|
107
|
+
const period = Math.max(5, Number(intervalMs) || INJECT_POLL_MS)
|
|
108
|
+
return function watch(childId, messageId, handlers = {}) {
|
|
109
|
+
let timer = null
|
|
110
|
+
let stopped = false
|
|
111
|
+
const stop = () => {
|
|
112
|
+
if (stopped) return
|
|
113
|
+
stopped = true
|
|
114
|
+
if (timer) clearInterval(timer)
|
|
115
|
+
timer = null
|
|
116
|
+
}
|
|
117
|
+
const check = () => {
|
|
118
|
+
if (stopped) return
|
|
119
|
+
let agent = null
|
|
120
|
+
try {
|
|
121
|
+
agent = resolveChild(childId)
|
|
122
|
+
} catch {
|
|
123
|
+
agent = null
|
|
124
|
+
}
|
|
125
|
+
if (!agent) {
|
|
126
|
+
stop()
|
|
127
|
+
handlers.onGone?.()
|
|
128
|
+
return
|
|
129
|
+
}
|
|
130
|
+
if (pendingIds(agent).has(String(messageId))) return
|
|
131
|
+
stop()
|
|
132
|
+
handlers.onClaimed?.(now())
|
|
133
|
+
}
|
|
134
|
+
timer = setInterval(check, period)
|
|
135
|
+
timer.unref?.()
|
|
136
|
+
return { stop, check }
|
|
137
|
+
}
|
|
138
|
+
}
|