@xiangyixie/dsh-superagent 0.12.0 → 0.12.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/inject.js CHANGED
@@ -1,138 +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
- }
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
+ }