Skip to main content

Glossary

Precise definitions of AgentForge terms, each with the page that explains it. The base is GLOSSARY.md in the repository, extended with the gateway, factory, CodeCrucible and operations vocabulary that was added after that file was written.

Two corrections to GLOSSARY.md, because the code wins:

  • It marks sessions, the gateway, the factory, the sandbox and the REST API as "planned". All of them are built (P2 to P3, and CodeCrucible locally). This page treats them as implemented. What is not deployed is called out in Operations overview.
  • Its "Flagged ambiguities" list is still the right guide for words with several meanings: say Agent runtime, Runtime adapter or Guarded runtime, never "runtime" alone; say Run limits or Daily limit, never "limits" alone; say Turn for the session concept and "agent turn" for a loop iteration.

How the main terms relate​

Running agents​

TermDefinitionPage
Agent runtimeAnything that can run an agent for one request and report the outcome as a stream of runtime events. The provider-neutral contract (packages/agent-types/src/index.ts) every runtime adapter and every control implementsAgent core decorators
Runtime adapterAn agent runtime backed by one provider's agent SDK; the only place a provider SDK may be used. The Claude adapter (packages/agent-runtime-claude) is the only oneRuntimes and CLI
Guarded runtimeAn agent runtime wrapped in every platform control in the fixed order redaction, kill switch, budget (with alerts), limits. The only runtime an app may hand requests toAgent core decorators
ControlOne platform rule (kill switch, budget, limits or redaction) packaged as an agent runtime that wraps anotherAgent core decorators
RunOne execution of an agent runtime for one agent request, ending in exactly one terminal result. "Job" is reserved for factory jobsAgent core decorators
Agent requestA client's ask to run an agent once: prompt, model, profile and optional run limits, identified by a request idREST API
Request idThe opaque identifier of one agent request; each ledger row has exactly one. A retried caller adds an attempt suffix (#<n>), so each attempt is a new request id. API request ids look like api/<uuid>Error model
ClientA named caller of the platform. Per-client daily limits, rate limits and ledger rows are keyed by it. Client names match ^[a-z0-9-]{1,64}$REST API
Service keyThe secret a client presents to the REST API as a bearer token (API_KEYS, at least 32 characters); each key maps to exactly one client name. Not the model provider keyREST API
Admin clientA client listed in API_ADMIN_CLIENTS; allowed to read GET /v1/usageObservability and alerts
ProfileA named capability set an agent runs under: readonly, sandbox-spike, factory-planner, factory-coder, factory-reviewer. The API runs only readonly; the factory and sandbox profiles run only inside the sandbox containerAgent core decorators
CapabilityA feature an agent runtime declares it supports (today file tools). A run that requires a missing capability, or an unsupported profile, is refused, never silently downgradedAgent core decorators
WorkspaceThe one directory an agent may read during a run. Paths that resolve outside it are refused. Not the sandbox, and not an Anthropic Console workspaceSandbox
Workspace auditThe check before each run that refuses a workspace containing a symlink that leads outside it, or holding too many entriesSandbox
Tool policyThe rule that a readonly run may use only the read, find and search tools, and only on paths inside the workspace; enforced by a PreToolUse hook in the Claude adapter, not by the model (ADR p1 0002)Threat model
Closed envThe fixed, minimal set of environment variables a runtime adapter passes to its agent process; nothing else from the host reaches the agentRuntimes and CLI
Direct pathA single agent request served by the API without sessions or durable orchestration (POST /v1/agent, or a stream from POST /v1/agent/stream)REST API
SSEThe Server-Sent Events stream of POST /v1/agent/stream: zero or more message events, then exactly one done or error; : ping comments every SSE_PING_MSREST API

Outcomes and errors​

TermDefinitionPage
Runtime eventOne item in a run's output stream: text, a tool call, a tool result, or the terminal result. Not "message"Agent core decorators
Terminal resultThe single last runtime event of a run, carrying reply text, usage and run status. If a runtime fails to produce one, a control produces one for itAgent core decorators
UsageThe token counts and reported cost of one run. The ledger total is Spend; the table is the LedgerData model
Run statusHow a run ended: success, aborted, or one error codeError model
Error codeThe single vocabulary for why a request did not succeed: invalid_request, budget_exhausted, disabled, agent_failed, agent_limit, timeout, internal_error, unsupported_capability, plus the HTTP-only unauthorized, rate_limited, busy, payload_too_large, not_found, unavailable, conflict, forbidden, too_many_pendingError model
AbortedA run stopped by its abort signal (caller exit, timeout, shutdown, cancel) rather than finishing on its own. "Cancel" is used for sessionsError model
Factory error codemax_iterations, budget_exhausted, approval_rejected, approval_expired, agent_failed, pr_closed_by_human, repo_too_large, internal_error, disabledError model

Spend control​

TermDefinitionPage
LedgerThe persisted record of spend: exactly one ledger row per agent request on every exit path that reaches admission. The single source of truth for spend; the Postgres table usage (ADR p1 0001)Data model
Ledger rowThe ledger's entry for one request id: its reservation, its settled cost and tokens, and its ledger statusData model
Ledger statusA ledger row's state: reserved while unsettled, a run status once settled, or rejected_budget or rejected_disabled for a request refused before it ranData model
ReservationThe amount set aside for a request before its run starts: the smallest of the per-request cap, the client's remaining daily limit and the global remaining daily limit. Counts in full against spend until the row is settledAgent core decorators
AdmissionThe decision to reserve for a request or refuse it. Refused if the reservation would be below the budget floor, or if the request id was already used. Runs under a Postgres advisory lockAgent core decorators
SettleTo close a ledger row with the run's reported cost, tokens and status. A missing or invalid cost settles at the full reservationAgent core decorators
SpendThe total charged for a day: each row's settled cost, or its reservation if it has no cost. Not UsageObservability and alerts
OverrunA settled row whose actual cost exceeded its reservationAgent core decorators
Stale reservationA ledger row still reserved longer than STALE_RESERVATION_SEC (default 900, minimum 600). Only reported, and it keeps counting in fullObservability and alerts
AbandonTo settle an unsettled ledger row as aborted at its full reservation, so it stops being stale. Used before retrying under a new attemptSessions and workflows
DayThe UTC calendar date a ledger row belongs to, fixed when the row is createdData model
Daily limitThe most a client (CLIENT_DAILY_LIMIT_USD) or all clients together (GLOBAL_DAILY_LIMIT_USD) may spend in one UTC day; persisted through the ledger so it survives restarts. Production values on the core host: 2.00 and 5.00 USDConfiguration
Per-request capThe largest reservation any single request can get (PER_REQUEST_CAP_USD: 0.5 on the API, 2.00 on the session worker)Configuration
Budget floorThe smallest reservation worth running (BUDGET_FLOOR_USD, default 0.02). Below it the request is refused with budget_exhaustedConfiguration
Sonnet minimum reservationSONNET_MIN_RESERVATION_USD (default 0.5): the minimum reservation for models whose id contains sonnet, capped at the per-request capConfiguration
Budget marginThe fraction of a reservation kept back from the runtime budget (BUDGET_MARGIN, default 0.2)Configuration
Runtime budgetThe spend limit handed to the agent runtime for one run: the reservation minus the budget marginAgent core decorators
Run limitsThe per-run bounds on agent turns, wall-clock timeout and runtime budget; requested values are clamped to platform defaults and maximaAgent core decorators
Kill switchThe operator control that refuses every new request with disabled. On when either AGENTS_DISABLED or the persisted setting agents_disabled is on; treated as on when it cannot be readObservability and alerts
SettingsPersisted operator switches read on every request (table settings). Today only the kill switchData model
Spend alertA warning, and an optional webhook call, sent when global spend for the day crosses an alert threshold; at most once per threshold per dayObservability and alerts
Alert thresholdA fraction of the global daily limit: 50 percent and 80 percentObservability and alerts

Secret safety​

TermDefinitionPage
RedactionThe control that removes secrets from everything a run emits and everything the platform logsObservability and alerts
ScrubbingThe part of redaction that replaces secret-looking values (API keys, bearer tokens, job tokens, key=value secrets) wherever they appear in textObservability and alerts
Swarm secretA file /run/secrets/<target> delivered by the hostinger apps role from a sibling SSM path; used for the gateway control tokens; owner uid must match the image (10001)Secrets flow
_FILE variableAn environment variable whose value is the path of a mounted file holding the real secret, for example GATEWAY_CONTROL_TOKEN_WORKER_FILE=/run/secrets/agentforge-ctl-workerSecrets flow
Secrets manifestsecrets.manifest.yml: the env-sync services and SSM paths; names only, never valuesSecrets flow
env-syncThe tool that moves fields between 1Password items and SSM parameters (env-sync-ts secret set-many, push, diff)Secrets flow
Payload codecThe application-level AES-GCM encryption of Temporal payloads, keyed by TEMPORAL_PAYLOAD_KEYS with the active id in TEMPORAL_PAYLOAD_KEY_ID; protects payloads on a cluster that has no TLS or authSessions and workflows

Durable sessions​

TermDefinitionPage
SessionA multi-turn conversation between one client and one model, kept in the app database and driven by a durable workflow. Not the provider SDK's own session state (the adapter turns that off), which is an "SDK session"Sessions and workflows
MessageOne user prompt in a session and, once its turn finishes, the reply. A session holds up to 50Sessions and workflows
TurnThe work of answering one message, from claim to final write. Its spend is one or more attempts, each with its own ledger row. An agent-loop iteration is an "agent turn" (maxTurns, default 5)Sessions and workflows
AttemptOne try at running a turn, with its own request id and ledger row; at most three per turnSessions and workflows
Transcript replayHow a session keeps context: each turn's prompt is rebuilt from the session's earlier completed messages, so no provider-side memory is usedSessions and workflows
Turn fenceThe database marker that shows which attempt currently owns a turn; an attempt that loses the fence stopsSessions and workflows
CancelA client's request to stop a session (DELETE /v1/sessions/:id, answered 202). Its running turn ends aborted and the session closes cancelledREST API
Core workerThe session worker on the core host (apps/worker, default target, dist/main.js); runs prepareTurn and finishTurn and, by default, also polls the exec queue (WORKER_ALSO_EXEC=true)Worker fleet
Exec workerA database-free worker (dist/exec-main.js) that runs executeTurn with a job token on a laptop or VPS; holds no database, control, model or GitHub credentialWorker fleet
Worker fleetThe set of exec workers over the tailnet, polling the queue agentforge-sessions-execWorker fleet
Task queuesagentforge-sessions (core), agentforge-sessions-exec (fleet and by default core), agentforge-sessions-exec-core (core fallback), agentforge-factory, agentforge-qualitySessions and workflows
fleet-splitThe workflow patch that splits a turn into prepareTurn, executeTurn and finishTurn, replay-safeSessions and workflows

Governance and the gateway​

TermDefinitionPage
Agent gatewayThe single trusted service outside any sandbox that relays model calls and MCP tool calls. It holds the only real provider key and enforces grants and spend for every call. Listeners: data 8787, control 8788. Not a proxyGateway
Data listenerThe gateway listener (GATEWAY_DATA_PORT, default 8787) that serves the model proxy and POST /mcp, authenticated by job tokensGateway
Control listenerThe gateway listener (GATEWAY_CONTROL_PORT, default 8788) for registering and revoking jobs and subjects, authenticated by control tokensGateway
Control tokenA secret of at least 32 characters that authorizes the control listener. The api token only registers session-readonly jobs for its own rows and revokes only its own; the worker token does the restJob tokens and policies
Job token (per-job token)The short-lived credential (prefix afj_, 43 characters after it) that a runtime presents to the gateway in place of any real key. Lives for a turn; revoked on retryJob tokens and policies
RegistrationThe gateway's in-memory record of a job: compiled grants, token and TTL. Lost on a gateway restart, which fails closedJob tokens and policies
PolicyLayered rules (organisation, then application or repository, then agent role, then task) that compile into grants, tool allowlists, sandbox spec, credential scope, run limits and approval gates. A lower level never widens a higher oneJob tokens and policies
Baked policyThe deny-by-default org policy plus the role policies shipped in the gateway image under /policies (ADR fleet 0003)Gateway
GrantOne permission a job holds after policy compilation, checked by the gateway on every call. Compiled shape: models, max tokens, tools, hook tools, limits, approvals required, identity mode, egress allowJob tokens and policies
OBO identityActing on behalf of the requesting user by exchanging their token at the gateway for the turn only. The default identity mode; the other is serviceJob tokens and policies
MCP registryA directory of *.yaml server definitions (GATEWAY_REGISTRY_DIR, default /registry, empty is valid): https endpoints only, each tool pinned by schemaSha256MCP registry
Context providerA source of project knowledge supplied to a job as evidence, never as instructionsMCP registry
AllowlistsThe gateway's accepted query strings, body fields and beta headers (GATEWAY_ALLOWED_QUERIES, GATEWAY_ALLOWED_FIELDS, GATEWAY_ALLOWED_BETAS), frozen against the CLI wire capture (FROZEN_FOR_SDK=0.3.322)Gateway
Cost authorityThe one component whose recorded cost counts for a request: the gateway when it is in the path, otherwise the runtime's settleGateway
Gateway auditTable gateway_audit: one evidence row per gateway decision, with no prompts, bodies, tokens or headersObservability and alerts
GATEWAY_CONTROL_BIND_ANYSetting accepted only with the value private-network-only; lets the control listener bind 0.0.0.0 on a gateway attached to the private overlay aloneDeployment topology
GATEWAY_CONTROL_BIND_CIDRSetting that picks the single local IPv4 address inside a CIDR for the control listener; fails closed on none, several, malformed or IPv6; prefixes wider than /8 refused. Coded, not released (ADR cidr 0008)Deployment topology
GATEWAY_HTTP_ALLOWED_HOSTSExact hostnames to which plain http to the gateway is allowed, because the path is an encrypted private overlayDeploy runbooks

Software factory​

TermDefinitionPage
FactoryThe capability that turns a task into a pull request through planner, coder, test and review rolesFactory overview
Job (factory job)One factory task from start to pull request, with its own budget, iteration limit and ledger rows. Statuses: queued, planning, awaiting_plan_approval, coding, validating, testing, reviewing, awaiting_pr_approval, opening_pr, pr_opened, failed, cancelledJob lifecycle
StepOne unit of a job with a key: plan, or code-<i>, test-<i>, review-<i> with i from 1 to 5. Statuses pending, running, succeeded, failed, aborted; at most 3 attemptsJob lifecycle
ApprovalA human sign-off on an exact plan or diff, given outside the agent; the agent can never approve itself. Gates: factory.plan, factory.pr; default TTL 72 hGates and approvals
GateA point where a job waits for an approval, identified by a SHA-256 digest of the exact artifactGates and approvals
ArtifactA stored output of a step: kinds plan, patch, test-log, review; at most 1 MiB eachJob lifecycle
Patch policyThe host-side validation of a coder patch before it is applied, with reject reasons such as empty_patch, too_large, too_many_files, bad_path, forbidden_path, protected_path, symlink, submodule, binary, secret_in_patchPatch policy
SandboxThe per-job container a factory agent runs in, with no real keys, database credentials or source-host token, no network except the gateway on a per-attempt internal networkSandbox
Sandbox roleThe profile and policy a step runs under: factory-planner, factory-coder, factory-reviewer; test steps run with --network none and no env fileSandbox roles
Capability guardAn in-process object only the worker can create, which the factory-coder profile requires. It prevents mistakes and is explicitly not a security controlSandbox roles
Same-org forkThe fork of a base repository created in the base's own organization as <repo>-fork, so one installation covers both sides (ADR fleet 0002)Job lifecycle
GitHub Appsagentforge-read-pr (contents:read, pull_requests:write, metadata:read) on base and forks; agentforge-push (contents:write) on the forks onlySecrets and keys
runc guardrunc is accepted only with FACTORY_ALLOW_RUNC=throwaway-repo-only (factory) or QUALITY_ALLOW_RUNC=own-repo-only (quality); runsc is the default for real workSandbox

CodeCrucible (quality)​

TermDefinitionPage
CodeCrucibleThe mutation-evidence quality gate: deterministic analysis (CRAP, cognitive complexity, incremental mutation testing) with verification of a pushed change. No model is called. Built locally, dormantQuality overview
quality-corepackages/quality-core: the pure analysis library that runs no tests, Docker, Temporal, database, network or modelLibrary
CRAPC^2 * (1 - cov)^3 + C with C the cyclomatic complexity and cov in [0, 1]Library
MutantOne source change from Stryker identified by (file, span, mutator, replacement); status killed, survived, no_coverage, timeout, compile_error, runtime_error, ignored, pendingLibrary
Trusted listThe set of mutant tuples from an empty-test run; reports join on the tuple, never on Stryker idsAnti-gaming
Assessment (quality run)A measurement of a protected-branch commit or package: baseline rows and a report. Statuses running, completed, partial, inconclusive, error, cancelledAssessment workflow
VerifyThe workflow that checks a pushed change: solo check, materialized re-kill, controls, then a verdictVerify workflow
Intentremediation or feature; a pass carries the intent it was judged under (passed:remediation, passed:feature, otherwise failed)Verify workflow
Re-killA check that a survivor killed by a new test is killed again when materialized against the base tests: result confirmed or not_reproducedAnti-gaming
ControlsRewrites of the mutated code (such as !(a >= b) for a < b) used to detect gaming; they differ for NaN or undefined operandsAnti-gaming
ChunkA slice of a mutation run executed by runChunk in the sandbox; a 20-chunk run has 147 workflow history events against a 150 budgetExec worker and image
Chunk cacheTable quality_chunk_cache: gzip normalised reports, at most 2000 rows and 30 days unusedData model
Quality submissionA row in quality_submissions recorded by the API before admission (cap 4 pending per client, 24 h TTL)REST and limits
Quality policyQualityPolicy: per-repo mutate and support globs, thresholds, protectedBranch (default main) and chunkTimeoutMs, inside FactoryRepoPolicyStatus and limits
Quality imageapps/worker/quality-image/Dockerfile: Stryker 10.1.1, Vitest 5.1.0 with v8 coverage, the repository's dependencies; run by digest only with --network noneExec worker and image
PRE-0 to PRE-3Owner preconditions for the quality exec host: Temporal access decision, sandbox host with runsc, Postgres volume (done), read-only GitHub App keyDeploy runbooks
Spikes S1 to S5Phase 0 prototypes: S1, S2, S4 pass; S5 (offline image) passes; S3 (runsc) not runQuality overview

Operations and infrastructure​

TermDefinitionPage
Core hostThe CapRover host that runs Postgres, gateway, core worker and API (called app-03 in the source docs)Deployment topology
Exec hostA sandbox host for exec workers and quality runs; not built (PRE-1)Deployment topology
CapRoverThe container platform on top of Docker Swarm used on each application host; apps are of type worker or webDeployment topology
agentforge-netThe private encrypted overlay network of the core hostDeployment topology
TailnetThe private WireGuard network (Tailscale) over which clients, laptops and the Temporal host are reached; access is controlled by ACL tagsDeployment topology
CatalogThe hostinger repo's services.yml entries that declare each CapRover app; one file per hostDeploy runbooks
Drift gateA read-only check that the live apps match the catalog; fails the fleet's applies while a merged entry has no live appDeploy runbooks
Owner goThe owner's explicit approval, given in the session that performs a live changeDeploy runbooks
Immutable tagAn ECR tag that cannot be overwritten; a failed push burns itRelease process
MirrorA single-platform copy of a digest-pinned upstream image (postgres, temporal) pushed to ECR as vX.Y.ZRelease process
Smoke testAn authenticated session turn through the whole stack after a deployDeploy runbooks
Real-key runA user-run check that spends real money with a real provider key, allowed only after the keyless spend and safety tests pass (docs/p1-realkey-runbook.md)Testing and CI
Smoke harnessapps/smoke: the private app that composes the guarded runtime over Postgres for real-key runsTesting and CI
Smoke capThe highest daily limit a real-key run accepts; a fixed hard ceiling in apps/smoke/src/compose.ts bounds itTesting and CI
Conformance suiteThe shared behavioural checks every runtime adapter must passTesting and CI
FakeAn in-memory stand-in for a runtime or store that copies the real semantics, used in keyless testsTesting and CI
StoreThe persistence behind a control: ledger store, settings store, alert store. Postgres in production, fakes in testsData model
DossierA session wrap-up folder under docs/sessions/ with a resume pointerSession dossiers
BeadAn issue in the beads tracker (epic id hawkeye-81e; children .NN)Repository docs map
ADRArchitecture decision record under docs/sessions/*/adrDecisions
Plan idsAcceptance-criterion ids from .omc/plans/ used in test names and docs (P1-12, G-P2a, RK-B, FL-2, FX-CFG1, CC-2.4)Writing guide

Sources​

  • GLOSSARY.md (terms, relationships, flagged ambiguities)
  • packages/agent-types/src/index.ts (ErrorCode, ProfileName, RuntimeStatus)
  • packages/agent-types/src/factory.ts (FactoryStatus, FactoryErrorCode, FactoryGate, StepKind, StepKey, StepStatus, ArtifactKind, PatchRejectReason, FACTORY_LIMITS)
  • packages/agent-types/src/quality.ts (QualityIntent, QualityStatus, QualityVerdict, QualityMutantStatus, QualityRekill, QUALITY_LIMITS)
  • packages/agent-types/src/grants.ts (CompiledGrants, IdentityMode)
  • packages/agent-types/src/audit.ts, packages/agent-types/src/http.ts
  • packages/agent-core/src/redaction.ts, alerts.ts, kill-switch.ts
  • packages/quality-core/README.md
  • apps/api/src/config.ts, apps/worker/src/exec-config.ts
  • docs/deploy-worker-fleet.md, docs/deploy-gateway-coolify.md, docs/deploy-factory.md, docs/deploy-quality.md
  • docs/design-gateway-fleet-exposure.md
  • docs/sessions/*/adr/*.md
  • secrets.manifest.yml