Files
STM32F4-Base/.dsh/plugins/dsh-plugin-subagent-roles/lib/budget.js
T
wandering1 9e538d2809
CI / 静态门禁 (pre-commit) (push) Failing after 43s
CI / 主机侧单测 (MSVC) (push) Failing after 24s
feat(dsh): 门禁账本插件接入 + 角色绑定跨重启还原
二、门禁与唤醒(新插件 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,记录绑定机制、存量成员缺口与「成员自省不可全信」的
  台架教训。
2026-11-16 00:42:51 +08:00

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()
},
}
}