Token Budget Enforcement

Pre-execution budget gating for multi-agent convoy execution. Prevents token overspend by checking budgets BEFORE API calls, not after. Identified by the 12 Primitives analysis (Primitive 5) as the #1 actionable improvement.

Activation

This skill activates when:

• A convoy execution starts (mayor creates a convoy)
• Agents are spawned within a convoy
• Any agent is about to make an API call during convoy execution
• Budget reporting is requested during or after execution

Architecture

Budget Hierarchy

Convoy Budget (hard limit, default 500K tokens)
  |
  +-- Agent A budget (hard limit, default 100K tokens)
  +-- Agent B budget (hard limit, default 100K tokens)
  +-- Agent C budget (hard limit, default 100K tokens)

The convoy budget is the aggregate ceiling. Individual agent budgets prevent any single polecat from consuming a disproportionate share.

Check-Before-Execute Pattern

Every API call in a convoy MUST follow this sequence:

1. Estimate the projected token cost for the call
2. Check

   checkBudget(budget, agentId, projectedCost)

   — returns

   BudgetCheckResult

3. If

   allowed: false

   — stop immediately, do NOT make the API call
4. If

   reason: 'warning_threshold'

   — proceed but log the warning
5. If

   reason: 'ok'

   — proceed normally
6. After execution —

   recordUsage(budget, agentId, actualInput, actualOutput)

7. Persist —

   saveBudget(budget, budgetDir)

   to survive crashes

Structured Stop Reasons

ok

warning_threshold

convoy_budget_exceeded

agent_budget_exceeded

Core API

Types

interface TokenBudget {
  convoyId: string;
  maxTokensPerConvoy: number;      // Hard limit for entire convoy
  maxTokensPerAgent: number;       // Hard limit per polecat
  warningThresholdPercent: number;  // Warn at this % (e.g., 80)
  currentUsage: BudgetUsage;
  createdAt: string;               // ISO 8601
  updatedAt: string;               // ISO 8601
}

interface BudgetCheckResult {
  allowed: boolean;
  reason: 'ok' | 'warning_threshold' | 'convoy_budget_exceeded' | 'agent_budget_exceeded';
  remainingTokens: number;
  usagePercent: number;
}

Functions

createBudget

(convoyId, config?) => TokenBudget

checkBudget

(budget, agentId, projectedCost) => BudgetCheckResult

recordUsage

(budget, agentId, input, output) => void

getBudgetReport

(budget) => BudgetReport

saveBudget

(budget, budgetDir) => Promise<void>

.chipset/state/budgets/

loadBudget

(convoyId, budgetDir) => Promise<TokenBudget | null>

deleteBudget

(convoyId, budgetDir) => Promise<void>

listBudgets

(budgetDir) => Promise<string[]>

Default Values

maxTokensPerConvoy

maxTokensPerAgent

warningThresholdPercent

State Persistence

Path:

.chipset/state/budgets/{convoyId}.json

Follows the same durability contract as beads-state:

• Atomic writes (write temp -> fsync -> rename)
• JSON with sorted keys for git-friendly diffs
• Filesystem-only, no database dependencies
• Crash-recoverable (partial writes leave only temp files)

Integration Points

Mayor Coordinator

When the mayor creates a convoy, it should also create a token budget:

const convoy = await stateManager.createConvoy('Sprint 1', beadIds);
const budget = createBudget(convoy.id, {
  maxTokensPerConvoy: 500_000,
  maxTokensPerAgent: 100_000,
});
await saveBudget(budget, '.chipset/state/budgets');

Polecat Worker

Before each API call in GUPP autonomous mode:

const budget = await loadBudget(convoyId, '.chipset/state/budgets');
const check = checkBudget(budget!, agentId, estimatedTokens);
if (!check.allowed) {
  // Structured stop — include reason in termination message
  return { stopped: true, reason: check.reason, remaining: check.remainingTokens };
}
// ... make API call ...
recordUsage(budget!, agentId, actualInput, actualOutput);
await saveBudget(budget!, '.chipset/state/budgets');

Witness Observer

The witness can periodically check budget health:

const budget = await loadBudget(convoyId, '.chipset/state/budgets');
const report = getBudgetReport(budget!);
if (report.warningActive) {
  // Alert: convoy approaching budget limit
}

Module Location

• Implementation:

  src/chipset/gastown/token-budget.ts

• Tests:

  src/chipset/gastown/token-budget.test.ts

• Barrel export:

  src/chipset/gastown/index.ts