9e538d2809
二、门禁与唤醒(新插件 dsh-plugin-team-ledger 0.2.0)
宿主 Agent Teams 缺两块能力,补在独立仓
D:/Code/AI/dsh-plugin-team-ledger:
- 状态存放:<工作区>/.dsh/team/gate.jsonl 追加账本,记验收
清单、实测证据、认领历史,跨重启存活;canonical JSON +
fsync,坏尾行截断恢复。
- 唤醒模型:门禁推进后按事件计划唤醒下一责任人,借活体
Lead 作 caller 走宿主 sendMessage;无定时器;30 分钟滑动
窗口限 4 次防复活风暴。
- 验收独立性由机器强制:执行人/历史认领者不能 accept,
checklist 逐项 passed=true 缺一不可。
- team_member_revive(Lead 专用):成员模型路由死亡后的
复活通道——可换 provider/model,再经 subagents.sendMessage
冷恢复唤醒,绕过宿主 roster 的 phase=active 门禁。
二、角色绑定跨重启还原(roles fork 0.5.2)
persona 与工具白名单只有运行中 agent 的内存态,宿主重启后
冷恢复的成员既无 persona 也无白名单——实测出现 doc-writer
成员带全量工具面(qq_*/ImageGen),属静默权限放大。改为
注入成功时持久化 childId -> {roleId, cwd} 到
~/.dsh/role-inject-bindings.json,并在 agent/created 时重放。
追加 team_member_rebind 补绑定,覆盖 0.5.2 之前已存在的成员。
三、配套
- .dsh/roles 八个角色白名单加入门禁工具;AGENTS.md 委派策略
补门禁/复活/重绑三套操作口径。
- docs/环境与部署/子Agent角色自动注入实现说明.md 新增
§5.1,记录绑定机制、存量成员缺口与「成员自省不可全信」的
台架教训。
329 lines
13 KiB
JavaScript
329 lines
13 KiB
JavaScript
/**
|
|
* Tool-call budget: how many tool calls a role's child may make, and what
|
|
* happens when it runs out.
|
|
*
|
|
* Counting is event-sourced. The monitor folds committed `tool/call` events of
|
|
* the Sessions this plugin started — the framework records those, so the guard
|
|
* never parses model output and never trusts the child's self-report. One
|
|
* `tool/call` is one "call": parallel calls inside one step each count, and a
|
|
* call the scheduler appended before a policy denial or a post-cancellation skip
|
|
* counts too, because the model already spent that decision.
|
|
*
|
|
* The enforcement ACTION is deliberately not decided here. A delegation hands in
|
|
* `enforce` / `injectWrapUp` closures, because the three delegation routes need
|
|
* three different mechanisms: a foreground one-shot child is stopped by aborting
|
|
* the signal its run was started with, a background one-shot child by aborting
|
|
* the job's controller, and a continuable child by
|
|
* `SubagentRuntime.interrupt()` — which is documented as an accepted no-op for a
|
|
* one-shot or unknown target, so it cannot be the only mechanism.
|
|
*
|
|
* This module holds no `ctx` dependency: `observe()` is the whole seam, which
|
|
* keeps the counting rules unit-testable without a host.
|
|
*/
|
|
|
|
/** Structured-result discriminator; mirrored by the delegation output schema. */
|
|
export const TOOL_CALL_BUDGET_STATUS = 'tool-call-budget-exceeded'
|
|
/** Machine-readable reason, kept distinct from the core's own `TOOL_TIMEOUT`. */
|
|
export const TOOL_CALL_BUDGET_REASON = 'tool-call-budget'
|
|
/** Default bounded size of the per-child record table. */
|
|
const DEFAULT_MAX_RECORDS = 256
|
|
|
|
/** A count that is a non-negative safe integer, or undefined. */
|
|
function asCount(value) {
|
|
return Number.isSafeInteger(value) && value >= 0 ? value : undefined
|
|
}
|
|
|
|
/**
|
|
* Resolve one delegation's effective budget.
|
|
*
|
|
* Precedence is `role file` over `settings/row-config default`; `0` means
|
|
* unlimited and is a sentinel rather than a count, so `maxToolCallsHardCap`
|
|
* never clamps it — the escape hatch outranks the ceiling by design.
|
|
* @param options - the role, the resolved row/settings defaults, and the hard cap.
|
|
* @returns the effective policy, its provenance, and any clamp warning.
|
|
*/
|
|
export function resolveToolCallBudget(options = {}) {
|
|
const { role, defaults, hardCap } = options
|
|
const declared = asCount(role?.maxToolCalls)
|
|
const fallback = asCount(defaults?.maxToolCalls) ?? 0
|
|
const requested = declared ?? fallback
|
|
const cap = asCount(hardCap) ?? 0
|
|
// Name the actual source of the value being clamped: a clamped row/Settings
|
|
// default is not the role file asking for something.
|
|
const origin = declared === undefined ? 'the row/Settings default' : `role "${role?.id ?? '(unknown)'}"`
|
|
const warnings = []
|
|
let limit = requested
|
|
if (cap > 0 && limit > cap) {
|
|
warnings.push(`${origin} asked for maxToolCalls ${limit}, over the configured maxToolCallsHardCap ${cap}; using ${cap}`)
|
|
limit = cap
|
|
}
|
|
const mode = role?.onToolCallBudget ?? defaults?.onToolCallBudget ?? 'wrap-up'
|
|
return {
|
|
limit,
|
|
scope: role?.maxToolCallsScope ?? 'delegation',
|
|
mode,
|
|
grace: asCount(role?.graceToolCalls) ?? asCount(defaults?.graceToolCalls) ?? 1,
|
|
source: declared === undefined ? (limit > 0 ? 'row-default' : 'unlimited') : (limit > 0 ? 'role' : 'unlimited'),
|
|
warnings,
|
|
}
|
|
}
|
|
|
|
/**
|
|
* The structured, non-error value a budget-stopped delegation returns.
|
|
*
|
|
* Deliberately not thrown: a thrown error reads to the delegating agent as a
|
|
* tool fault worth retrying, which is the opposite of the intended "choose a
|
|
* smaller task, raise the budget, or accept the partial result".
|
|
* @param record - the breached budget record.
|
|
* @param partialOutput - child text preserved before the stop, when there is any.
|
|
* @returns the value the delegation output schema declares.
|
|
*/
|
|
export function toolCallBudgetFailure(record, partialOutput) {
|
|
const { limit, scope, mode } = record.policy
|
|
const used = record.usedAtBreach ?? record.used
|
|
return {
|
|
kind: 'budget-exceeded',
|
|
status: TOOL_CALL_BUDGET_STATUS,
|
|
reason: TOOL_CALL_BUDGET_REASON,
|
|
role: record.roleId,
|
|
used,
|
|
limit,
|
|
scope,
|
|
mode,
|
|
...(typeof partialOutput === 'string' && partialOutput.length > 0 ? { partialOutput } : {}),
|
|
note: `role "${record.roleId}" used ${used} of its ${limit} tool calls (scope ${scope}, mode ${mode}) and was stopped. Re-delegate a narrower task, raise maxToolCalls in the role file, or accept the partial output.`,
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Create the per-row budget monitor.
|
|
*
|
|
* Registers ONE `session/event` observer for every child Session of the host (a
|
|
* child lives in its own context, so the observer must bypass the context filter)
|
|
* plus a `session/disposed` release, and keeps a bounded table of the delegations
|
|
* that armed it.
|
|
* @param options - the plugin `ctx` and a warning sink.
|
|
* @returns the arm/release seam, the raw `observe` fold, and a disposer.
|
|
*/
|
|
export function createToolCallBudgetMonitor(options = {}) {
|
|
const { ctx, log } = options
|
|
const maxRecords = asCount(options.maxRecords) || DEFAULT_MAX_RECORDS
|
|
const records = new Map()
|
|
|
|
const warn = (message) => {
|
|
try {
|
|
log?.(message)
|
|
} catch {
|
|
// A warning sink that throws must not escape into the Session commit path.
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Insert a record, evicting the OLDEST INSERTION when the table is full.
|
|
*
|
|
* Not an LRU: a live record whose delegation keeps running is not re-ordered by
|
|
* use, so an eviction is a real (if remote) loss of enforcement. The table is a
|
|
* backstop against a leak, not the primary lifecycle — `release()` on disposal
|
|
* is.
|
|
*/
|
|
function remember(record) {
|
|
if (!records.has(record.childSessionId) && records.size >= maxRecords) {
|
|
for (const oldest of records.keys()) {
|
|
records.delete(oldest)
|
|
break
|
|
}
|
|
}
|
|
records.set(record.childSessionId, record)
|
|
}
|
|
|
|
/**
|
|
* Deliver the plugin-authored notice, at most once per delegation.
|
|
*
|
|
* The notice is the DURABLE audit record: it carries `used`/`limit`/`scope`/
|
|
* `mode` into the child Session's own log, so a stop can be replayed even when
|
|
* the child never gets another step. It is delivered on every stop, not only
|
|
* under `wrap-up`, because an interrupted child is exactly the case a bare host
|
|
* log line cannot answer "where did it stop, and how much was left".
|
|
*/
|
|
function deliverNotice(record, used) {
|
|
if (record.noticeSent === true) return
|
|
record.noticeSent = true
|
|
let delivered = false
|
|
try {
|
|
delivered = record.injectNotice?.(used) === true
|
|
} catch (error) {
|
|
warn(`[subagent-roles] role=${record.roleId} could not inject the wrap-up notice: ${String(error?.message ?? error)}`)
|
|
}
|
|
if (!delivered) {
|
|
warn(`[subagent-roles] role=${record.roleId} wrap-up notice could not be delivered (no live local child agent); the stop is recorded in this log only`)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Report and enforce one budget stop.
|
|
*
|
|
* A delegation already being torn down is skipped: the core's own deadline and
|
|
* the budget are orthogonal guards, and each must report itself rather than the
|
|
* other's teardown being mislabelled as a budget breach.
|
|
*
|
|
* Enforcement runs at most ONCE PER TURN. A `session` budget stays breached for
|
|
* the child's whole life and is never reset, so a parent that wakes the child
|
|
* again must be able to stop it again — but a single crossing is followed by the
|
|
* calls the scheduler appends for a stopped batch, each of which is a
|
|
* `tool/call` too, and re-enforcing on those would only repeat one stop.
|
|
*/
|
|
function breach(record, used, turn) {
|
|
// The teardown predicate is what keeps the two orthogonal guards apart: when
|
|
// the core's own deadline (or a user cancel) already aborted this delegation,
|
|
// the stop is that guard's to report, not this one's. Contained because a
|
|
// bookkeeping throw in here would disable the cap for the rest of the run.
|
|
try {
|
|
if (typeof record.isTornDown === 'function' && record.isTornDown() === true) return
|
|
} catch (error) {
|
|
warn(`[subagent-roles] role=${record.roleId} could not read the teardown state: ${String(error?.message ?? error)}`)
|
|
return
|
|
}
|
|
if (turn !== undefined && record.enforcedTurn === turn) return
|
|
record.enforcedTurn = turn
|
|
// The FIRST crossing owns the reported facts; a later wake's larger count
|
|
// must not rewrite what the delegation is reported to have stopped at.
|
|
if (record.breached !== true) {
|
|
record.breached = true
|
|
record.usedAtBreach = used
|
|
}
|
|
const { limit, scope, mode } = record.policy
|
|
warn(`[subagent-roles] role=${record.roleId} tool-call budget exceeded: used=${used} limit=${limit} scope=${scope} mode=${mode}`)
|
|
deliverNotice(record, used)
|
|
try {
|
|
record.enforce?.()
|
|
} catch (error) {
|
|
warn(`[subagent-roles] role=${record.roleId} could not enforce the tool-call budget: ${String(error?.message ?? error)}`)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Apply the pinned threshold rules to one already-counted call.
|
|
*
|
|
* `used === limit` is NOT a breach. The call that crosses the limit tells the
|
|
* child to wrap up; `wrap-up` then tolerates `grace` further calls before the
|
|
* stop, while `interrupt` stops on that same call. `grace: 0` therefore IS
|
|
* `interrupt`: the same notice and the same stop, on the same call.
|
|
*/
|
|
function onToolCall(record, used, turn) {
|
|
const { limit, mode, grace } = record.policy
|
|
if (limit <= 0 || used <= limit) return
|
|
if (mode === 'off') {
|
|
// Warn once per crossing, not once per call beyond the limit.
|
|
if (used === limit + 1) {
|
|
warn(`[subagent-roles] role=${record.roleId} tool-call budget exhausted: used=${used} limit=${limit} scope=${record.policy.scope} mode=off`)
|
|
}
|
|
return
|
|
}
|
|
if (mode === 'interrupt') {
|
|
breach(record, used, turn)
|
|
return
|
|
}
|
|
// wrap-up: tell the child first, then tolerate the grace calls.
|
|
deliverNotice(record, used)
|
|
if (used >= limit + 1 + grace) breach(record, used, turn)
|
|
}
|
|
|
|
/**
|
|
* Fold one committed Session event.
|
|
*
|
|
* Synchronous and fully contained on purpose: this runs inside
|
|
* `Session.append()`'s commit path, so an exception escaping here would
|
|
* corrupt the very log the guard reads.
|
|
* @param session - the Session that committed the event.
|
|
* @param event - the committed event (`{ type, data, ... }`).
|
|
*/
|
|
function observe(session, event) {
|
|
try {
|
|
const id = session?.id
|
|
const record = id === undefined ? undefined : records.get(id)
|
|
if (record === undefined) return
|
|
if (event?.type === 'tool/call') {
|
|
record.used += 1
|
|
onToolCall(record, record.used, event.data?.turn)
|
|
return
|
|
}
|
|
// A continuable child's wake opens a new turn, which is the only
|
|
// observable definition of "one count per background wake".
|
|
if (event?.type === 'turn/start' && record.policy.scope === 'delegation') {
|
|
record.used = 0
|
|
record.noticeSent = false
|
|
// The reported latch clears with the count: a new turn IS a new delegation
|
|
// under this scope, and leaving it set would let the guard fire once per
|
|
// child session and leave every later wake unbounded.
|
|
record.breached = false
|
|
record.usedAtBreach = undefined
|
|
record.enforcedTurn = undefined
|
|
}
|
|
} catch (error) {
|
|
warn(`[subagent-roles] tool-call budget monitor failed: ${String(error?.message ?? error)}`)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Track one delegation. Call after `start` resolves, when the child Session id
|
|
* is known — a child cannot have made a tool call before its first model
|
|
* request, which is always after `start` fulfilled.
|
|
* @param spec - child session id, role id, policy, and the enforcement
|
|
* closures: `enforce` (stop the child), `injectNotice(used)` (deliver the
|
|
* durable notice), and `isTornDown` (whether another guard already stopped it).
|
|
* @returns the record the delegation reports from.
|
|
*/
|
|
function arm(spec) {
|
|
const record = {
|
|
childSessionId: spec.childSessionId,
|
|
roleId: spec.roleId,
|
|
policy: spec.policy,
|
|
enforce: spec.enforce,
|
|
injectNotice: spec.injectNotice,
|
|
isTornDown: spec.isTornDown,
|
|
used: 0,
|
|
noticeSent: false,
|
|
breached: false,
|
|
}
|
|
remember(record)
|
|
return record
|
|
}
|
|
|
|
/** Forget one delegation. Safe to call twice. */
|
|
function release(childSessionId) {
|
|
records.delete(childSessionId)
|
|
}
|
|
|
|
const detach = []
|
|
if (typeof ctx?.on === 'function') {
|
|
// `global: true` bypasses context-filter checks; without it a child Session's
|
|
// events would never reach this host-plane row.
|
|
detach.push(ctx.on('session/event', observe, { global: true }))
|
|
// The primary lifecycle, so a dead child's record does not sit in the bounded
|
|
// table until an eviction takes a LIVE one with it.
|
|
detach.push(ctx.on('session/disposed', (session) => {
|
|
if (session?.id !== undefined) release(session.id)
|
|
}, { global: true }))
|
|
}
|
|
|
|
return {
|
|
arm,
|
|
release,
|
|
observe,
|
|
/** Number of tracked delegations (diagnostics and tests). */
|
|
get size() {
|
|
return records.size
|
|
},
|
|
dispose: () => {
|
|
for (const disposer of detach) {
|
|
try {
|
|
if (typeof disposer === 'function') disposer()
|
|
} catch {
|
|
// A disposed fiber already removed the listener.
|
|
}
|
|
}
|
|
records.clear()
|
|
},
|
|
}
|
|
}
|