@argszero/cordis-plugin-goal-budget-guard

Deployment budgets for dsh autonomous goal rounds: cap a goal's rounds, the rounds that ran with no human message, and the tokens spent since the guard began watching the goal.

npm install @argszero/cordis-plugin-goal-budget-guard

The gap this closes

A goal (@deepseek-ai/dsh-goal + @deepseek-ai/dsh-goal-round-driver) keeps a session working after the human's turn ends: each time the session goes quiescent the driver queues one more round, for as long as the goal's phase is active and its live activation is armed.

The only bound the harness ships is the goal's own maxGoalRounds, and it is denominated in rounds:

• One round is unbounded in cost. 256 rounds of a cheap lookup and 256 rounds of a full-repository sweep are the same number to the cap. This is the shape behind discussion #7193 — "I left it running overnight and the tokens were gone".
• The cap is fixed when the goal is created, by whoever created it — not by the operator who pays for the deployment.
• "Keep going while I'm watching" and "keep going while I'm asleep" are the same request to this cap, so there is no way to allow long supervised continuation while bounding unattended drift.

This plugin adds those dimensions without touching core. It programs only against documented service shapes (ctx.goals, ctx.sessionProjections, the declared agent/status and session/event events) and imports no @deepseek-ai/dsh-* package at runtime.

Mount

- insert:
    - id: goal-budget-guard
      name: '@argszero/cordis-plugin-goal-budget-guard'
      config:
        maxGoalRounds: 20        # deployment cap, whatever the goal's own cap says
        maxUnattendedRounds: 3   # rounds since the last human message
        maxTokens: 2000000       # tokens since the guard began watching this goal
        dryRun: false            # true logs the stop it would write instead of writing it

Every dimension is optional and unset means unenforced; a guard with none of the three set logs no budget configured … the guard is inert and does nothing. dryRun is the standard agent/config-aware toggle: it logs the decision it would write, which is how you size a budget before trusting it.

What enforcement is

One durable ctx.goals.block(agent, ref, { code, message }) — not a veto per model call:

• the goal's phase becomes blocked and its activation is disarmed, so the driver's next quiescence check stops (drive() only continues an active, armed goal);
• the stop is durable and visible: the reason code is the plugin's own (round-budget, unattended-budget, token-budget), which is what GoalBlockReason.code is for — a stable lower-kebab-case classification chosen by the blocking policy — so the user and the model both see who stopped the goal and why;
• a human can still resume the goal. This is a policy, not a lock.

Dimensions

| Config | Crossed when | Read from | |---|---|---| | maxGoalRounds | roundsStarted >= maxGoalRounds | the durable goal view | | maxUnattendedRounds | autonomous rounds since the last human message >= maxUnattendedRounds | session/event, counting only source.kind === 'user' messages | | maxTokens | tokens spent since the guard first saw this goal >= maxTokens | the tokenUsage session projection |

Dimensions are evaluated in the fixed order rounds → unattended → tokens, so a stop is reported against one stable dimension rather than whichever comparison happened to run first.

Boundaries (all of them)

• Goals, not steps. A round already admitted runs to completion; at most one further round is admitted after a budget is crossed. The guard bounds the run, it does not interrupt work in flight.
• maxTokens counts from when the guard first saw the goal (mount, or the goal's creation). Mounting into a session whose goal has already spent a lot re-seeds the baseline there; it does not retroactively bill that session.
• maxUnattendedRounds arms only after the guard has observed a human message in the session. A session with no observed human message is left alone rather than guessed at — a silent mis-observation would block goals a human is actively supervising. Plugin-injected and goal-round messages do not count as human; only a user message does.
• Unreadable is skipped, never assumed. If the tokenUsage projection is not mounted, or the goal service refuses a read, the dimension stays silent instead of reading as 0 — a guard that guesses is worse than one that abstains, and every abstention is logged.
• It is not a cost meter. Token figures are provider-reported totals for the session; the guard compares them, it does not price them.

Related

• Source discussion: deepseek-ai/deepseek-harness#7193
• Sibling plugins by the same author: @argszero/cordis-plugin-session-model, @argszero/cordis-plugin-subagent-effort, @argszero/cordis-plugin-thinking-loop-guard.

License

MIT