Skip to main content

Agent core decorators

packages/agent-core wraps any AgentRuntime in a fixed stack of decorators. The stack enforces the platform controls (secret redaction, the kill switch, the spend ledger, turn and time limits) in one place, so the API, the session workers and the factory worker cannot diverge. agent-core never reads the environment; each app maps its env vars into AgentCoreConfig and calls createAgentRuntime.

Composition and ordering​

createAgentRuntime({runtime, stores, cfg}) builds the stack from the inside out:

limited = withLimits(runtime, cfg)
budgeted = withBudget(limited, { ledger, cfg, onSettled: alertListener })
guarded = withKillSwitch(budgeted, { settings, ledger, disabledFlag: cfg.disabled })
result = withRedaction(guarded)

Seen from the caller, the order is redaction, then kill switch, then budget (with the alert listener), then limits, then the inner runtime.

Why this order:

PositionReason
Redaction outermostnothing a decorator yields (including synthesized results) can leave unscrubbed
Kill switch before budgeta disabled request must not reserve spend; it records a rejected_disabled ledger row and ends
Budget before limitsthe reservation is settled in a finally, whatever the limits layer or runtime did, including consumer break
Limits innermostthe timeout aborts the inner runtime directly and the status is rewritten to timeout

The same composition exists in apps/api/src/runtime.ts (composeRuntime) and apps/worker/src/runtime.ts. The factory worker builds its own with factory limits (see Job lifecycle). The session split (prepareTurn and finishTurn) reimplements the kill switch, admit and settle steps by hand because the model call happens on a different host (Sessions and workflows); the exec activity wraps only withRedaction(withLimits(...)).

Shared contract: events and terminal result​

The runtime port is run(req, ctx): AsyncIterable<RuntimeEvent>. A stream is valid when every event matches the union (text_delta, tool_call, tool_result, result) and exactly one result event exists and is last. assertSingleTerminalResult enforces that; collectResult drains a stream and returns the events plus the result, throwing otherwise. The port and statuses are described on Runtimes and CLI.

guard(): generator discipline​

Every decorator runs its inner runtime through guard (packages/agent-core/src/guard.ts). It guarantees one terminal result, last, even when the inner misbehaves:

Inner behaviourWhat guard does
throwslogs, yields synthesized aborted (if the signal was aborted) or agent_failed
ends without a result eventlogs, yields synthesized aborted or agent_failed
ignores an abort for ABORT_GRACE_MSyields synthesized aborted and attaches a late-result promise
yields events after its resultdropped
consumer stops early (break or throw)aborts first, then calls inner.return()

Constants:

ConstantValueMeaning
ABORT_GRACE_MS1000after an abort, how long a raw runtime may take to deliver its own result before one is synthesized
LATE_RESULT_WAIT_MS120000how long a stuck inner may take to deliver its terminal result for the settle; covers the sandbox teardown (revoke 1 s, inspect 5 s, kill and rm 16 s, default workspace-out 60 s)

Only the guard directly around a raw runtime gives up. Decorators mark themselves with markGuarded, and a guard around an already guarded inner does not start the grace timer, because the inner decorator delivers its own result within the grace period and a second give-up would race it and skip its settle.

The give-up result carries a symbol-keyed promise (LATE_RESULT) of the inner runtime's own terminal result. withBudget settles from it, never from the synthesized result. The source comment states that redaction drops it, so it never reaches callers.

withLimits​

Clamps the per-run limits and owns the abort controller.

  • maxTurns and timeoutMs are clamped by clamp(requested, {default, max}): a finite value above 0 becomes min(requested, max), anything else (0, NaN, negative) becomes the default.
  • A timer aborts the child controller with Error('timeout') after the clamped timeoutMs. If the run ended non-successfully after that timer fired, the terminal status is rewritten to timeout.
  • maxBudgetUsd is not touched here; withBudget owns it.
SettingDEFAULT_CONFIG
maxTurnsdefault 5, max 10
timeoutMsdefault 120,000, max 300,000

The factory worker overrides these: maxTurns default FACTORY_MAX_TURNS (30), max 50; timeoutMs default FACTORY_STEP_TIMEOUT_MS (600,000), max 840,000.

withBudget​

Reserve, run with a share of the reservation, settle in finally.

Rules:

  • ledger.admit (PgLedgerStore) takes a global advisory lock (agentforge:budget), computes x = LEAST(cap, clientDailyLimit - clientSpend, globalDailyLimit - globalSpend) over today's UTC usage rows, refuses when x < floor, and inserts a reserved row with ON CONFLICT (request_id) DO NOTHING. The reserved amount is therefore capped by the remaining daily headroom, not only the per-request cap.
  • The runtime sees maxBudgetUsd = amountUsd * (1 - budgetMargin) (margin default 0.2), leaving headroom for overshoot.
  • Cost on settle: no reported cost, or a reported cost that is negative, NaN or infinite, settles at the full reservation. A buggy runtime can never lower spend. Metered rows (gateway-debited) ignore the runtime's cost: the gateway debits are the cost.
  • If the consumer exits early, the stored result stays aborted and the row is still settled in finally.
  • When the guard gave up and no late result arrives within LATE_RESULT_WAIT_MS, the row is not settled and stays reserved, counting in full. The stale reservation check surfaces such rows (Observability and alerts).
  • Ledger write failures on settle are logged; the row stays reserved. They never throw into the stream.

Defaults and per-app values:

Settingagent-core defaultAPISession workerFactory worker
perRequestCapUsd0.500.520.5
floorUsd0.020.020.02FACTORY_STEP_FLOOR_USD, 0.02
sonnetMinReservationUsd0.050.50.50.05
budgetMargin0.20.20.20.2
globalDailyLimitUsd2GLOBAL_DAILY_LIMIT_USD (2)samesame

The ledger's own per-client daily limit (CLIENT_DAILY_LIMIT_USD, default 1) is configured on the store, not in AgentCoreConfig. The Sonnet minimum exists because one Sonnet turn through the gateway can debit at least about 0.122 USD in the worst case (8192 output tokens plus the CLI's roughly 10k-token request), so a smaller reservation is a guaranteed 429. These per-app defaults differ from the agent-core default by design; the API and worker values come from apps/api/src/config.ts and apps/worker/src/config.ts.

withKillSwitch​

The kill switch is the OR of two sources, read on every call:

  1. the config flag (AGENTS_DISABLED, mapped to disabledFlag). Parsing fails closed: any value other than 0 or false disables;
  2. settings.isDisabled(), which reads the settings row with key agents_disabled and treats 1 or true (case-insensitive) as disabled. No row means enabled.

A read error fails closed (treated as disabled). When disabled, the decorator calls ledger.recordRejected({reason: 'rejected_disabled'}) (a failure is logged and ignored) and yields a terminal disabled, which the API maps to 503. The gateway reads the same setting per request and fails closed, so an in-flight sandbox or session turn also stops at the next model call.

withRedaction and logging​

withRedaction passes every event through scrubDeep, which scrubs every string inside plain objects and arrays (event text, tool input and output, result text). On a scrub failure (for example a throwing getter) it fails closed: a non-result event becomes a text_delta with [REDACTED: event could not be scrubbed], and a result becomes a synthesized internal_error terminal.

Secret patterns (scrubSecrets):

PatternReplacement
sk-ant- followed by key characters[REDACTED]
gateway job token: afj_ plus a 43-character base64url-style suffix[REDACTED]
sk-, pk- or rk- followed by 16 or more key characters[REDACTED]
the word Bearer followed by a token (case-insensitive)the word Bearer then [REDACTED]
api_key, api-key, apikey, secret, token, password assignments (: or =, optional quotes)keeps the key and separator, redacts the value

Character classes exclude quotes, so scrubbing a JSON string keeps it valid JSON. scrubDeep is cycle-safe (a value already on the path becomes [Circular]) and bounded by MAX_SCRUB_DEPTH = 64 ([Truncated] beyond).

createLogger returns a pino logger with key-based censoring (redact.paths: apiKey, *.apiKey, ANTHROPIC_API_KEY, *.ANTHROPIC_API_KEY, env, *.env, headers.authorization, *.headers.authorization, censor [REDACTED]) plus a logMethod hook that scrubs every logged value. logError(logger, msg, err) logs only the scrubbed Name: message text, no stack and no raw object. The API's request log line never includes headers, prompts or replies.

Spend alerts​

createAlertListener is the after-settle hook. withBudget runs it detached, so it never delays the stream end and its errors are logged, never thrown.

  • Thresholds ALERT_THRESHOLDS = [0.5, 0.8] of globalDailyLimitUsd.
  • For each threshold at or below today's global spend, alerts.markSent(threshold, at) returns true only for the first call per (UTC day, threshold). The dedup lives in Postgres (alerts_sent), so it survives restarts.
  • When it wins, it logs a warning global daily spend crossed alert threshold and, if ALERT_WEBHOOK_URL is set, POSTs JSON {threshold, spendUsd, limitUsd} with a 5 s timeout. A non-2xx answer logs alert webhook rejected at error level; a thrown error logs alert webhook failed.
  • At-most-once: the threshold is marked sent before the POST, so a failed or timed-out POST is not retried that UTC day. The error-level log line is then the only signal.

Invariants (summary)​

  1. Exactly one terminal result, last, from every layer.
  2. A ledger row reserved by withBudget is settled in finally whenever the runtime's own result is known; otherwise it stays reserved (never silently freed).
  3. Reported cost can raise but never lower the recorded spend.
  4. Fail closed: ledger admit error gives internal_error; kill switch read error gives disabled; scrub error gives a placeholder.
  5. Abort propagates: consumer break, parent signal and timeout all abort the inner runtime first, then close it.

Testing support​

@agentforge/agent-core/testing exports FakeRuntime (behaviors normal, throw, hang, ignore-abort, empty, optional extraResult), FakeLedgerStore and the runtime conformance suite described on Runtimes and CLI.

Sources​

  • packages/agent-core/src/index.ts (createAgentRuntime, collectResult)
  • packages/agent-core/src/guard.ts (guard, markGuarded, terminal, ABORT_GRACE_MS, LATE_RESULT_WAIT_MS)
  • packages/agent-core/src/limits.ts, packages/agent-core/src/budget.ts, packages/agent-core/src/kill-switch.ts
  • packages/agent-core/src/redaction.ts (scrubSecrets, scrubDeep, redact, createLogger, logError, withRedaction)
  • packages/agent-core/src/alerts.ts (ALERT_THRESHOLDS, createAlertListener)
  • packages/agent-core/src/config.ts (AgentCoreConfig, DEFAULT_CONFIG)
  • packages/agent-types/src/index.ts (LedgerStore, SettingsStore, AlertStore, RuntimeStatus)
  • packages/db/src/stores.ts (PgLedgerStore.admit, settle, PgSettingsStore.isDisabled)
  • apps/api/src/runtime.ts, apps/worker/src/runtime.ts, apps/worker/src/factory-main.ts, apps/worker/src/exec-activities.ts