Skip to main content

Class: SqlActionLimiter

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:149

ActionLimiter over a @framers/sql-storage-adapter store. Counts are rows in the host's database, so they are shared between processes and survive a restart. They are not atomic across two rules: each rule reserves in its own transaction, and a denial gives back the units taken before it, without counting one of the action's attempts.

Someone must run reconcile (or startReconciler in one process): a reservation whose lease ran out counts against its window, and keeps its action a duplicate, until a pass settles it as used.

Implements​

Constructors​

Constructor​

new SqlActionLimiter(options): SqlActionLimiter

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:162

Parameters​

options​

SqlActionLimiterOptions

The store, every rule the host uses, and the tables' prefix.

Returns​

SqlActionLimiter

Throws​

TypeError for a rule id that is not a word of at most 19 characters, a scope that is not room, target or platform, a window or a ceiling that is not a whole number, one id listed twice with different numbers, no rule, a lease not shorter than every window, or a prefix and a window whose table name runs past 38 characters.

Methods​

forgetTarget()​

forgetTarget(accountId): Promise<void>

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:332

Deletes the rows of every target-scoped rule whose key is exactly <rule id>|t:<accountId> (and its dry: twin), in each meter's two tables, for a host's account deletion. An exact comparison per rule, never a pattern: an id may hold _, which a LIKE reads as any character. A reservation still reserved stays, with its key's window row, so the action that holds it settles its own row and the same action cannot be reserved again while it runs; a host calls this again once that action has ended, or one lease and a reconcile pass later for a process that stopped.

Parameters​

accountId​

string

Returns​

Promise<void>


purge()​

purge(before): Promise<void>

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:313

Deletes settled reservations. Each meter deletes only those settled before both before and one of its own windows back, so no unit a window still counts is deleted and an allowance never reopens early. An action whose rows are gone is no longer a duplicate, so before is also how long a repeated action reads as one. A meter deletes a page of rows a pass, and is asked again until a pass deletes less than a page.

Parameters​

before​

number

Returns​

Promise<void>


reconcile()​

reconcile(now?): Promise<void>

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:291

Settles reservations whose lease ran out; each counts as used.

Parameters​

now?​

number

Returns​

Promise<void>


reserve()​

reserve(request): Promise<ActionLimitAnswer>

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:208

Reserves one unit under every rule, in the order given; a rule listed more than once is reserved once. A rule with no room left, an action that already ran or is running, one whose tool failed three times, or a scope with no id in the target refuses the whole action, and the units taken before it are given back without counting an attempt.

Parameters​

request​
dryRun​

boolean

operationId​

string

The action's idempotency key.

rules​

readonly ActionLimitRule[]

target​

{ accountId?: string; roomId?: string; }

target.accountId?​

string

target.roomId?​

string

Returns​

Promise<ActionLimitAnswer>

Throws​

TypeError for a rule this limiter was not built with, or whose numbers differ.

Throws​

SpendMeterUnavailableError when the store does not answer; the units taken are given back where they can be.

Implementation of​

ActionLimiter.reserve


startReconciler()​

startReconciler(intervalMs?, onError?): void

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:296

Runs reconcile every interval (default 15000 ms) until stopReconciler. A failed pass is retried on the next tick.

Parameters​

intervalMs?​

number = 15_000

onError?​

(error) => void

Returns​

void


stopReconciler()​

stopReconciler(): void

Defined in: packages/agentos/src/safety/runtime/ActionLimiter.ts:302

Returns​

void