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:
| Position | Reason |
|---|---|
| Redaction outermost | nothing a decorator yields (including synthesized results) can leave unscrubbed |
| Kill switch before budget | a disabled request must not reserve spend; it records a rejected_disabled ledger row and ends |
| Budget before limits | the reservation is settled in a finally, whatever the limits layer or runtime did, including consumer break |
| Limits innermost | the 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 behaviour | What guard does |
|---|---|
| throws | logs, yields synthesized aborted (if the signal was aborted) or agent_failed |
| ends without a result event | logs, yields synthesized aborted or agent_failed |
ignores an abort for ABORT_GRACE_MS | yields synthesized aborted and attaches a late-result promise |
| yields events after its result | dropped |
| consumer stops early (break or throw) | aborts first, then calls inner.return() |
Constants:
| Constant | Value | Meaning |
|---|---|---|
ABORT_GRACE_MS | 1000 | after an abort, how long a raw runtime may take to deliver its own result before one is synthesized |
LATE_RESULT_WAIT_MS | 120000 | how 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.
maxTurnsandtimeoutMsare clamped byclamp(requested, {default, max}): a finite value above 0 becomesmin(requested, max), anything else (0, NaN, negative) becomes the default.- A timer aborts the child controller with
Error('timeout')after the clampedtimeoutMs. If the run ended non-successfully after that timer fired, the terminal status is rewritten totimeout. maxBudgetUsdis not touched here;withBudgetowns it.
| Setting | DEFAULT_CONFIG |
|---|---|
maxTurns | default 5, max 10 |
timeoutMs | default 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), computesx = LEAST(cap, clientDailyLimit - clientSpend, globalDailyLimit - globalSpend)over today's UTC usage rows, refuses whenx < floor, and inserts areservedrow withON 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,
NaNor 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
abortedand the row is still settled infinally. - 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:
| Setting | agent-core default | API | Session worker | Factory worker |
|---|---|---|---|---|
perRequestCapUsd | 0.50 | 0.5 | 2 | 0.5 |
floorUsd | 0.02 | 0.02 | 0.02 | FACTORY_STEP_FLOOR_USD, 0.02 |
sonnetMinReservationUsd | 0.05 | 0.5 | 0.5 | 0.05 |
budgetMargin | 0.2 | 0.2 | 0.2 | 0.2 |
globalDailyLimitUsd | 2 | GLOBAL_DAILY_LIMIT_USD (2) | same | same |
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:
- the config flag (
AGENTS_DISABLED, mapped todisabledFlag). Parsing fails closed: any value other than0orfalsedisables; settings.isDisabled(), which reads thesettingsrow with keyagents_disabledand treats1ortrue(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):
| Pattern | Replacement |
|---|---|
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]ofglobalDailyLimitUsd. - 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 thresholdand, ifALERT_WEBHOOK_URLis set, POSTs JSON{threshold, spendUsd, limitUsd}with a 5 s timeout. A non-2xx answer logsalert webhook rejectedat error level; a thrown error logsalert 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)
- Exactly one terminal
result, last, from every layer. - A ledger row reserved by
withBudgetis settled infinallywhenever the runtime's own result is known; otherwise it stays reserved (never silently freed). - Reported cost can raise but never lower the recorded spend.
- Fail closed: ledger admit error gives
internal_error; kill switch read error gives disabled; scrub error gives a placeholder. - 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.tspackages/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