Runtime Controls - Buildfunctions Docs

Runtime Controls wrap your functions with composable guardrails so agents can run unattended without spiraling into infinite loops, duplicate writes, or runaway tool-call volume. No API key required — they work standalone around your own code, or combined with Buildfunctions hardware-isolated sandboxes.

Runtime Controls is in beta. The SDK interface may change between releases.

Install

npm install buildfunctions

Why Runtime Controls

When agents run unattended, things go wrong:

Infinite loops - the agent retries the same failing call forever
Runaway tool-call volume - unchecked tool calls can spike API usage quickly
Duplicate side effects - the same write runs twice
Unsafe actions - an agent executes destructive operations
Cascading failures - one broken dependency can fan out failures

Runtime Controls reduce these failure modes, but you still need to configure the right controls for your workflow. maxToolCalls is a call-count guardrail, not direct provider billing telemetry.

Examples

Wrap Any Async Call (No API Key)

JavaScript

import { RuntimeControls } from 'buildfunctions'

const controls = RuntimeControls.create({
  maxToolCalls: 50,
  timeoutMs: 30_000,
  retry: { maxAttempts: 3, initialDelayMs: 200, backoffFactor: 2 },
  loopBreaker: { warningThreshold: 5, quarantineThreshold: 8, stopThreshold: 12 },
  onEvent: (event) => console.log(`[controls] ${event.type}: ${event.message}`),
})

const guardedFetch = controls.wrap({
  toolName: 'api-call',
  runKey: 'agent-run-1',
  destination: 'https://api.example.com',
  run: async ([payload]) => {
    const res = await fetch('https://api.example.com/data', {
      method: 'POST',
      body: JSON.stringify(payload),
    })
    return res.json()
  },
})

const result = await guardedFetch({ query: 'latest results' })

Use `run()` Directly

JavaScript

import { RuntimeControls } from 'buildfunctions'

const controls = RuntimeControls.create({ retry: { maxAttempts: 2 } })

const result = await controls.run(
  { toolName: 'simple-tool' },
  async () => 'ok'
)

runtime["signal"] is available in handlers but optional. Use it when your tool call supports cancellation.

Control Layers

Every control is opt-in and composable. Enable only what you need.

Retry with Exponential Backoff

Automatically retries transient failures (503, 429, timeouts) with configurable backoff.

JavaScript

const controls = RuntimeControls.create({
  retry: {
    maxAttempts: 4,
    initialDelayMs: 250,
    maxDelayMs: 10_000,
    backoffFactor: 2,
    jitterRatio: 0.2,
  },
})

Custom retry decisions:

JavaScript

const controls = RuntimeControls.create({
  retry: { maxAttempts: 4 },
  retryClassifier: ({ error, statusCode }) => {
    if (statusCode === 409) {
      return { retryable: true, delayMs: 500, reason: 'conflict_backoff' }
    }
    return { retryable: error.code === 'NETWORK_ERROR' }
  },
})

Tool-Call Budget

Per-run cap on the number of tool calls when maxToolCalls is configured. Budgets are scoped by runKey. This is a tool-call-count budget, not a dollar-based cost meter.

JavaScript

const controls = RuntimeControls.create({
  maxToolCalls: 50,
})

await controls.run({ toolName: 'shell', runKey: 'agent-run-1' }, async () => 'ok')

// Reset budget when starting a new run.
await controls.reset('agent-run-1')

Loop Breaker

Detects repeated no-progress patterns and escalates from warning to quarantine to stop.

JavaScript

const controls = RuntimeControls.create({
  loopBreaker: {
    enabled: true,
    warningThreshold: 5,
    quarantineThreshold: 8,
    stopThreshold: 12,
    quarantineMs: 15_000,
    stopCooldownMs: 120_000,
  },
})

Circuit Breaker

Temporarily blocks calls to a failing dependency. Keyed by (tenant, toolName, destination).

JavaScript

const controls = RuntimeControls.create({
  circuitBreaker: {
    enabled: true,
    windowMs: 30_000,
    minRequests: 20,
    failureRateThreshold: 0.6,
    cooldownMs: 60_000,
  },
})

When failure rate exceeds threshold inside the sliding window, the circuit opens for cooldownMs.

Timeout and Cancellation

Per-call timeout with abort signal propagation.

JavaScript

const controls = RuntimeControls.create({ timeoutMs: 30_000 })

const controller = new AbortController()
await controls.run(
  { toolName: 'shell', signal: controller.signal },
  async ({ signal }) => {
    return runCommand('npm test', { signal })
  }
)

Policy Gates

Deterministic allow / deny / require_approval rules with specificity-based precedence.

JavaScript

const controls = RuntimeControls.create({
  policy: {
    mode: 'enforce',
    rules: [
      {
        id: 'deny-destructive',
        action: 'deny',
        tools: ['repo-admin'],
        actionPrefixes: ['delete'],
        reason: 'Destructive repo operations are blocked',
      },
      {
        id: 'approve-external-writes',
        action: 'require_approval',
        tools: ['ticket-write'],
        destinations: ['*.external.example.com'],
        reason: 'External writes require human approval',
      },
    ],
    approvalHandler: async () => false,
  },
})

Policy precedence (highest wins):

Higher tool specificity (exact name > prefix > wildcard)
Higher destination specificity (exact host > wildcard subdomain > *)
Longer action prefix match
Stricter action (deny > require_approval > allow)
Earlier rule index on exact tie (current behavior)

Idempotency

Prevents duplicate side effects by replaying prior results for calls with the same idempotencyKey.

JavaScript

const controls = RuntimeControls.create({
  idempotency: {
    enabled: true,
    ttlMs: 600_000,
    includeErrors: false,
    namespaceByRunKey: true,
  },
})

await controls.run(
  {
    toolName: 'pr-comment',
    runKey: 'pr-4821',
    idempotencyKey: 'comment:pr-4821:summary',
  },
  async () => postComment('LGTM')
)

await controls.run(
  {
    toolName: 'pr-comment',
    runKey: 'pr-4821',
    idempotencyKey: 'comment:pr-4821:summary',
  },
  async () => postComment('LGTM') // replayed, does not execute again
)

Concurrency Locks

Prevents simultaneous conflicting writes to the same resource.

JavaScript

const controls = RuntimeControls.create({
  concurrency: {
    enabled: true,
    waitMode: 'reject', // or 'wait'
    leaseMs: 30_000,
    waitTimeoutMs: 5_000,
  },
})

await controls.run(
  {
    toolName: 'repo-write',
    resourceKey: 'repo:buildfunctions/web-app',
  },
  async () => gitPush('main')
)

Verifier Hooks

Custom correctness gates that run before execution, after success, and after errors.

JavaScript

const controls = RuntimeControls.create({
  verifiers: {
    beforeCall: ({ toolName, action }) => {
      if (toolName === 'repo-admin' && action?.startsWith('delete')) {
        return { allow: false, reason: 'delete blocked' }
      }
      return { allow: true }
    },
    afterSuccess: ({ result }) => {
      if (!result || typeof result !== 'object') {
        return { allow: false, reason: 'unexpected result shape' }
      }
      return { allow: true }
    },
    afterError: ({ error }) => {
      return { allow: true }
    },
  },
})

Per-Tool and Per-Destination Overrides

Apply stricter or looser controls to specific tools or destinations.

JavaScript

const controls = RuntimeControls.create({
  timeoutMs: 60_000,
  retry: { maxAttempts: 4 },
  overrides: {
    tools: {
      shell: { timeoutMs: 10_000, retry: { maxAttempts: 2 } },
    },
    destinations: {
      '*.internal-api.example.com': { timeoutMs: 5_000 },
    },
  },
})

Tool overrides win when both tool and destination set the same field.

Agent Logic Safety

applyAgentLogicSafety adds pre-execution safety checks without changing RuntimeControls internals.

Injection Guard

Scans tool name, action, destination, and args for injection patterns before execution.

JavaScript

import { RuntimeControls, applyAgentLogicSafety } from 'buildfunctions'

const controls = RuntimeControls.create(
  applyAgentLogicSafety(
    { retry: { maxAttempts: 2 } },
    {
      injectionGuard: {
        enabled: true,
        patterns: [
          /ignore\s+previous\s+instructions/i,
          /\brm\s+-rf\b/i,
          /<script\b/i,
        ],
      },
    }
  )
)

Default patterns (when patterns is omitted):

ignore (all|any|previous) instructions
system prompt
developer message
<script
rm -rf

Exit Conditions

Enforces maximum steps per run and can block calls after a terminal action.

JavaScript

const controls = RuntimeControls.create(
  applyAgentLogicSafety(
    {},
    {
      exitCondition: {
        enabled: true,
        maxStepsPerRun: 30,
        terminalActions: [{ toolNamePattern: 'agent-control', actionPrefix: 'finish' }],
        blockAfterTerminal: true,
      },
    }
  )
)

Intent Allowlist

Restricts which tool + action combinations are permitted. Anything not explicitly allowed is denied.

JavaScript

const controls = RuntimeControls.create(
  applyAgentLogicSafety(
    {},
    {
      intentAllowlist: {
        enabled: true,
        rules: [
          { toolNamePattern: 'cpu-sandbox', actionPrefixes: ['run_'] },
          { toolNamePattern: 'repo-write', actionPrefixes: ['push_'] },
          { toolNamePattern: 'pr-comment', actionPrefixes: ['post_'] },
        ],
      },
    }
  )
)

Combining All Three

JavaScript

const controls = RuntimeControls.create(
  applyAgentLogicSafety(
    {
      tenantKey: 'my-team-prod',
      maxToolCalls: 100,
      retry: { maxAttempts: 3 },
      concurrency: { enabled: true, waitMode: 'reject', leaseMs: 30_000 },
    },
    {
      injectionGuard: { enabled: true },
      exitCondition: {
        enabled: true,
        maxStepsPerRun: 50,
        terminalActions: [{ toolNamePattern: 'agent-control', actionPrefix: 'finish' }],
        blockAfterTerminal: true,
      },
      intentAllowlist: {
        enabled: true,
        rules: [
          { toolNamePattern: 'cpu-sandbox', actionPrefixes: ['run_'] },
          { toolNamePattern: 'repo-write', actionPrefixes: ['push_'] },
          { toolNamePattern: 'pr-comment', actionPrefixes: ['post_'] },
        ],
      },
    }
  )
)

Observability

Event Callback

JavaScript

const controls = RuntimeControls.create({
  onEvent: (event) => {
    console.log(`[${event.type}] ${event.message}`, event.details)
  },
})

Event Sinks

JavaScript

const controls = RuntimeControls.create({
  eventSinks: [
    async (event) => await writeToDatabase(event),
    async (event) => await sendToMonitoring(event),
  ],
  onEventSinkFailure: ({ failure, sinkIndex }) => {
    console.error(`Event sink ${sinkIndex} failed:`, failure)
  },
})

Event Types

Event	Meaning
`retry`	A retry attempt was scheduled
`loop_warning`	Repeated no-progress pattern detected
`loop_quarantine`	Pattern quarantined (temporarily blocked)
`loop_stop`	Pattern hard-stopped
`circuit_open`	Dependency circuit breaker opened
`budget_stop`	Run tool-call budget exceeded
`policy_denied`	Policy denied a call
`policy_approval_required`	Approval required by policy
`policy_approved`	Approval granted by handler
`policy_dry_run`	Simulated policy decision (dry-run mode)
`verifier_rejected`	Verifier rejected call, result, or error
`idempotency_replay`	Prior result replayed
`concurrency_wait`	Waiting for resource lock
`concurrency_rejected`	Lock rejected or wait timed out

State Adapters

By default, state is in-memory. To persist guardrail state across processes, provide adapters.

JavaScript

const stateAdapter = {
  get: async (key) => await store.get(key),
  set: async (key, value) => await store.set(key, value),
  delete: async (key) => await store.delete(key),
  keys: async (prefix) => await store.keys(prefix),
}

const controls = RuntimeControls.create({
  state: {
    budget: stateAdapter,
    circuit: stateAdapter,
    loop: stateAdapter,
    lock: stateAdapter,
    idempotency: stateAdapter,
  },
})

State is namespaced by tenantKey, so teams can scope keys when sharing adapter backends. Unit tests cover adapter contracts; validate your backend and lock semantics with integration tests before production use.

API Methods

`RuntimeControls.create(config?)`

Creates a new controls instance. All config is optional.

`controls.run(context, fn)`

Runs fn(runtime) through enabled control layers. Context fields:

toolName (required)
runKey, destination, action
args
idempotencyKey, resourceKey
timeoutMs (per-call override)
signal (caller cancellation)

JavaScript

const result = await controls.run(
  {
    toolName: 'shell',
    runKey: 'agent-run-42',
    destination: 'sandbox.example.com',
    action: 'run_tests',
    args: { command: 'npm test' },
    idempotencyKey: 'test:42:v1',
    resourceKey: 'workspace:/repo',
    signal: controller.signal,
    timeoutMs: 10_000,
  },
  async ({ signal }) => {
    return runShell('npm test', { signal })
  }
)

`controls.wrap(params)`

Creates a reusable guarded function for repeated tool calls.

JavaScript

const guardedShell = controls.wrap({
  toolName: 'shell',
  runKey: 'agent-run-42',
  destination: 'sandbox.example.com',
  run: async ([command], { signal }) => {
    return runShell(command, { signal })
  },
})

await guardedShell('npm test')
await guardedShell('npm run lint')

Dynamic context via resolver functions:

JavaScript

const guardedShell = controls.wrap({
  toolName: 'shell',
  run: async ([command], { signal }) => runShell(command, { signal }),
  resolveRunKey: (command) => `run-${command}`,
  resolveDestination: () => 'sandbox.example.com',
  resolveAction: (command) => (command.startsWith('rm') ? 'delete' : 'execute'),
  resolveIdempotencyKey: (command) => `shell:${command}`,
  resolveResourceKey: () => 'workspace:/repo',
})

`controls.reset(runKey=None)`

Resets budget counters for the selected run key.

JavaScript

await controls.reset('agent-run-42')

Full Configuration Reference

Config	Default	Description
`tenantKey`	`"default"`	Namespace for all state keys
`timeoutMs`	`60000`	Per-call timeout (`0` disables)
`maxToolCalls`	unset	Per-`runKey` call budget
`retry.maxAttempts`	`4`	Total attempts including first
`retry.initialDelayMs`	`250`	Backoff base delay
`retry.maxDelayMs`	`10000`	Backoff cap
`retry.backoffFactor`	`2`	Exponential multiplier
`retry.jitterRatio`	`0.2`	Delay jitter (`0..1`)
`retryClassifier`	unset	Custom retry decision callback
`loopBreaker.enabled`	`true`	Enables repeated-pattern detection
`loopBreaker.warningThreshold`	`5`	Emits `loop_warning`
`loopBreaker.quarantineThreshold`	`8`	Emits `loop_quarantine`, blocks for `quarantineMs`
`loopBreaker.stopThreshold`	`12`	Emits `loop_stop`, blocks for `stopCooldownMs`
`loopBreaker.quarantineMs`	`15000`	Quarantine duration
`loopBreaker.stopCooldownMs`	`120000`	Stop duration
`loopBreaker.maxFingerprints`	`200`	Max fingerprints retained
`circuitBreaker.enabled`	`true`	Enables dependency circuit protection
`circuitBreaker.windowMs`	`30000`	Sliding failure window
`circuitBreaker.minRequests`	`20`	Requests before open decision
`circuitBreaker.failureRateThreshold`	`0.6`	Open when failure rate exceeds this
`circuitBreaker.cooldownMs`	`60000`	Open duration
`policy.enabled`	`true`	Enables rule enforcement
`policy.mode`	`"enforce"`	`"dryRun"` emits simulation events only
`policy.rules`	`[]`	Array of allow/deny/require_approval rules
`policy.approvalHandler`	unset	Required for `require_approval` rules
`verifiers.beforeCall`	unset	Pre-execution verifier
`verifiers.afterSuccess`	unset	Post-success verifier
`verifiers.afterError`	unset	Post-error verifier
`idempotency.enabled`	`true`	Enables replay by `idempotencyKey`
`idempotency.ttlMs`	unset	Replay record expiration
`idempotency.includeErrors`	`false`	Replay final errors when enabled
`idempotency.namespaceByRunKey`	`true`	Scope replay by run key
`concurrency.enabled`	`false`	Enables locking by `resourceKey`
`concurrency.leaseMs`	`30000`	Lock lease duration
`concurrency.waitMode`	`"reject"`	`"reject"` immediately or `"wait"`
`concurrency.waitTimeoutMs`	`5000`	Wait timeout
`concurrency.pollIntervalMs`	`50`	Poll interval in wait mode
`overrides.tools`	unset	Per-tool config overrides
`overrides.destinations`	unset	Per-destination config overrides
`state.*`	in-memory	State adapters (`budget`, `circuit`, `loop`, `lock`, `idempotency`)
`onEvent`	unset	Synchronous event callback
`eventSinks`	`[]`	Async event fan-out sinks
`onEventSinkFailure`	unset	Sink failure callback

FAQ

Do I need a Buildfunctions API token?

No. Runtime Controls works standalone without any API token.

What should I wrap first?

Start with side-effecting calls:

Repository writes (git push, branch operations)
External ticket or issue creation
Sandbox and test execution
PR or issue comments

What should be denied by default?

Start by denying destructive actions (delete*) and requiring approval for external writes.

Can I use this without agents?

Yes. Runtime Controls wrap functions — API calls, database queries, file operations, shell commands. Validate behavior in your own integration paths.

Pages

​Install

​Why Runtime Controls

​Examples

​Wrap Any Async Call (No API Key)

​Use run() Directly

​Control Layers

​Retry with Exponential Backoff

​Tool-Call Budget

​Loop Breaker

​Circuit Breaker

​Timeout and Cancellation

​Policy Gates

​Idempotency

​Concurrency Locks

​Verifier Hooks

​Per-Tool and Per-Destination Overrides

​Agent Logic Safety

​Injection Guard

​Exit Conditions

​Intent Allowlist

​Combining All Three

​Observability

​Event Callback

​Event Sinks

​Event Types

​State Adapters

​API Methods

​RuntimeControls.create(config?)

​controls.run(context, fn)

​controls.wrap(params)

​controls.reset(runKey=None)

​Full Configuration Reference

​FAQ

​Do I need a Buildfunctions API token?

​What should I wrap first?

​What should be denied by default?

​Can I use this without agents?

Install

Why Runtime Controls

Examples

Wrap Any Async Call (No API Key)

Use `run()` Directly

Control Layers

Retry with Exponential Backoff

Tool-Call Budget

Loop Breaker

Circuit Breaker

Timeout and Cancellation

Policy Gates

Idempotency

Concurrency Locks

Verifier Hooks

Per-Tool and Per-Destination Overrides

Agent Logic Safety

Injection Guard

Exit Conditions

Intent Allowlist

Combining All Three

Observability

Event Callback

Event Sinks

Event Types

State Adapters

API Methods

`RuntimeControls.create(config?)`

`controls.run(context, fn)`

`controls.wrap(params)`

`controls.reset(runKey=None)`

Full Configuration Reference

FAQ

Do I need a Buildfunctions API token?

What should I wrap first?

What should be denied by default?

Can I use this without agents?