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
| Term | Definition | Page |
|---|---|---|
| Agent runtime | Anything 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 implements | Agent core decorators |
| Runtime adapter | An 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 one | Runtimes and CLI |
| Guarded runtime | An 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 to | Agent core decorators |
| Control | One platform rule (kill switch, budget, limits or redaction) packaged as an agent runtime that wraps another | Agent core decorators |
| Run | One execution of an agent runtime for one agent request, ending in exactly one terminal result. "Job" is reserved for factory jobs | Agent core decorators |
| Agent request | A client's ask to run an agent once: prompt, model, profile and optional run limits, identified by a request id | REST API |
| Request id | The 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 |
| Client | A 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 key | The 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 key | REST API |
| Admin client | A client listed in API_ADMIN_CLIENTS; allowed to read GET /v1/usage | Observability and alerts |
| Profile | A 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 container | Agent core decorators |
| Capability | A 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 downgraded | Agent core decorators |
| Workspace | The one directory an agent may read during a run. Paths that resolve outside it are refused. Not the sandbox, and not an Anthropic Console workspace | Sandbox |
| Workspace audit | The check before each run that refuses a workspace containing a symlink that leads outside it, or holding too many entries | Sandbox |
| Tool policy | The 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 env | The fixed, minimal set of environment variables a runtime adapter passes to its agent process; nothing else from the host reaches the agent | Runtimes and CLI |
| Direct path | A 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 |
| SSE | The 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_MS | REST API |
Outcomes and errors
| Term | Definition | Page |
|---|---|---|
| Runtime event | One item in a run's output stream: text, a tool call, a tool result, or the terminal result. Not "message" | Agent core decorators |
| Terminal result | The 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 it | Agent core decorators |
| Usage | The token counts and reported cost of one run. The ledger total is Spend; the table is the Ledger | Data model |
| Run status | How a run ended: success, aborted, or one error code | Error model |
| Error code | The 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_pending | Error model |
| Aborted | A run stopped by its abort signal (caller exit, timeout, shutdown, cancel) rather than finishing on its own. "Cancel" is used for sessions | Error model |
| Factory error code | max_iterations, budget_exhausted, approval_rejected, approval_expired, agent_failed, pr_closed_by_human, repo_too_large, internal_error, disabled | Error model |
Spend control
| Term | Definition | Page |
|---|---|---|
| Ledger | The 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 row | The ledger's entry for one request id: its reservation, its settled cost and tokens, and its ledger status | Data model |
| Ledger status | A ledger row's state: reserved while unsettled, a run status once settled, or rejected_budget or rejected_disabled for a request refused before it ran | Data model |
| Reservation | The 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 settled | Agent core decorators |
| Admission | The 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 lock | Agent core decorators |
| Settle | To close a ledger row with the run's reported cost, tokens and status. A missing or invalid cost settles at the full reservation | Agent core decorators |
| Spend | The total charged for a day: each row's settled cost, or its reservation if it has no cost. Not Usage | Observability and alerts |
| Overrun | A settled row whose actual cost exceeded its reservation | Agent core decorators |
| Stale reservation | A ledger row still reserved longer than STALE_RESERVATION_SEC (default 900, minimum 600). Only reported, and it keeps counting in full | Observability and alerts |
| Abandon | To settle an unsettled ledger row as aborted at its full reservation, so it stops being stale. Used before retrying under a new attempt | Sessions and workflows |
| Day | The UTC calendar date a ledger row belongs to, fixed when the row is created | Data model |
| Daily limit | The 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 USD | Configuration |
| Per-request cap | The largest reservation any single request can get (PER_REQUEST_CAP_USD: 0.5 on the API, 2.00 on the session worker) | Configuration |
| Budget floor | The smallest reservation worth running (BUDGET_FLOOR_USD, default 0.02). Below it the request is refused with budget_exhausted | Configuration |
| Sonnet minimum reservation | SONNET_MIN_RESERVATION_USD (default 0.5): the minimum reservation for models whose id contains sonnet, capped at the per-request cap | Configuration |
| Budget margin | The fraction of a reservation kept back from the runtime budget (BUDGET_MARGIN, default 0.2) | Configuration |
| Runtime budget | The spend limit handed to the agent runtime for one run: the reservation minus the budget margin | Agent core decorators |
| Run limits | The per-run bounds on agent turns, wall-clock timeout and runtime budget; requested values are clamped to platform defaults and maxima | Agent core decorators |
| Kill switch | The 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 read | Observability and alerts |
| Settings | Persisted operator switches read on every request (table settings). Today only the kill switch | Data model |
| Spend alert | A warning, and an optional webhook call, sent when global spend for the day crosses an alert threshold; at most once per threshold per day | Observability and alerts |
| Alert threshold | A fraction of the global daily limit: 50 percent and 80 percent | Observability and alerts |
Secret safety
| Term | Definition | Page |
|---|---|---|
| Redaction | The control that removes secrets from everything a run emits and everything the platform logs | Observability and alerts |
| Scrubbing | The part of redaction that replaces secret-looking values (API keys, bearer tokens, job tokens, key=value secrets) wherever they appear in text | Observability and alerts |
| Swarm secret | A 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 variable | An 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-worker | Secrets flow |
| Secrets manifest | secrets.manifest.yml: the env-sync services and SSM paths; names only, never values | Secrets flow |
| env-sync | The tool that moves fields between 1Password items and SSM parameters (env-sync-ts secret set-many, push, diff) | Secrets flow |
| Payload codec | The 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 auth | Sessions and workflows |
Durable sessions
| Term | Definition | Page |
|---|---|---|
| Session | A 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 |
| Message | One user prompt in a session and, once its turn finishes, the reply. A session holds up to 50 | Sessions and workflows |
| Turn | The 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 |
| Attempt | One try at running a turn, with its own request id and ledger row; at most three per turn | Sessions and workflows |
| Transcript replay | How a session keeps context: each turn's prompt is rebuilt from the session's earlier completed messages, so no provider-side memory is used | Sessions and workflows |
| Turn fence | The database marker that shows which attempt currently owns a turn; an attempt that loses the fence stops | Sessions and workflows |
| Cancel | A client's request to stop a session (DELETE /v1/sessions/:id, answered 202). Its running turn ends aborted and the session closes cancelled | REST API |
| Core worker | The 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 worker | A 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 credential | Worker fleet |
| Worker fleet | The set of exec workers over the tailnet, polling the queue agentforge-sessions-exec | Worker fleet |
| Task queues | agentforge-sessions (core), agentforge-sessions-exec (fleet and by default core), agentforge-sessions-exec-core (core fallback), agentforge-factory, agentforge-quality | Sessions and workflows |
fleet-split | The workflow patch that splits a turn into prepareTurn, executeTurn and finishTurn, replay-safe | Sessions and workflows |
Governance and the gateway
| Term | Definition | Page |
|---|---|---|
| Agent gateway | The 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 proxy | Gateway |
| Data listener | The gateway listener (GATEWAY_DATA_PORT, default 8787) that serves the model proxy and POST /mcp, authenticated by job tokens | Gateway |
| Control listener | The gateway listener (GATEWAY_CONTROL_PORT, default 8788) for registering and revoking jobs and subjects, authenticated by control tokens | Gateway |
| Control token | A 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 rest | Job 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 retry | Job tokens and policies |
| Registration | The gateway's in-memory record of a job: compiled grants, token and TTL. Lost on a gateway restart, which fails closed | Job tokens and policies |
| Policy | Layered 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 one | Job tokens and policies |
| Baked policy | The deny-by-default org policy plus the role policies shipped in the gateway image under /policies (ADR fleet 0003) | Gateway |
| Grant | One 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 allow | Job tokens and policies |
| OBO identity | Acting on behalf of the requesting user by exchanging their token at the gateway for the turn only. The default identity mode; the other is service | Job tokens and policies |
| MCP registry | A directory of *.yaml server definitions (GATEWAY_REGISTRY_DIR, default /registry, empty is valid): https endpoints only, each tool pinned by schemaSha256 | MCP registry |
| Context provider | A source of project knowledge supplied to a job as evidence, never as instructions | MCP registry |
| Allowlists | The 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 authority | The one component whose recorded cost counts for a request: the gateway when it is in the path, otherwise the runtime's settle | Gateway |
| Gateway audit | Table gateway_audit: one evidence row per gateway decision, with no prompts, bodies, tokens or headers | Observability and alerts |
GATEWAY_CONTROL_BIND_ANY | Setting 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 alone | Deployment topology |
GATEWAY_CONTROL_BIND_CIDR | Setting 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_HOSTS | Exact hostnames to which plain http to the gateway is allowed, because the path is an encrypted private overlay | Deploy runbooks |
Software factory
| Term | Definition | Page |
|---|---|---|
| Factory | The capability that turns a task into a pull request through planner, coder, test and review roles | Factory 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, cancelled | Job lifecycle |
| Step | One 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 attempts | Job lifecycle |
| Approval | A 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 h | Gates and approvals |
| Gate | A point where a job waits for an approval, identified by a SHA-256 digest of the exact artifact | Gates and approvals |
| Artifact | A stored output of a step: kinds plan, patch, test-log, review; at most 1 MiB each | Job lifecycle |
| Patch policy | The 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_patch | Patch policy |
| Sandbox | The 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 network | Sandbox |
| Sandbox role | The profile and policy a step runs under: factory-planner, factory-coder, factory-reviewer; test steps run with --network none and no env file | Sandbox roles |
| Capability guard | An in-process object only the worker can create, which the factory-coder profile requires. It prevents mistakes and is explicitly not a security control | Sandbox roles |
| Same-org fork | The 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 Apps | agentforge-read-pr (contents:read, pull_requests:write, metadata:read) on base and forks; agentforge-push (contents:write) on the forks only | Secrets and keys |
runc guard | runc 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 work | Sandbox |
CodeCrucible (quality)
| Term | Definition | Page |
|---|---|---|
| CodeCrucible | The mutation-evidence quality gate: deterministic analysis (CRAP, cognitive complexity, incremental mutation testing) with verification of a pushed change. No model is called. Built locally, dormant | Quality overview |
| quality-core | packages/quality-core: the pure analysis library that runs no tests, Docker, Temporal, database, network or model | Library |
| CRAP | C^2 * (1 - cov)^3 + C with C the cyclomatic complexity and cov in [0, 1] | Library |
| Mutant | One source change from Stryker identified by (file, span, mutator, replacement); status killed, survived, no_coverage, timeout, compile_error, runtime_error, ignored, pending | Library |
| Trusted list | The set of mutant tuples from an empty-test run; reports join on the tuple, never on Stryker ids | Anti-gaming |
| Assessment (quality run) | A measurement of a protected-branch commit or package: baseline rows and a report. Statuses running, completed, partial, inconclusive, error, cancelled | Assessment workflow |
| Verify | The workflow that checks a pushed change: solo check, materialized re-kill, controls, then a verdict | Verify workflow |
| Intent | remediation or feature; a pass carries the intent it was judged under (passed:remediation, passed:feature, otherwise failed) | Verify workflow |
| Re-kill | A check that a survivor killed by a new test is killed again when materialized against the base tests: result confirmed or not_reproduced | Anti-gaming |
| Controls | Rewrites of the mutated code (such as !(a >= b) for a < b) used to detect gaming; they differ for NaN or undefined operands | Anti-gaming |
| Chunk | A slice of a mutation run executed by runChunk in the sandbox; a 20-chunk run has 147 workflow history events against a 150 budget | Exec worker and image |
| Chunk cache | Table quality_chunk_cache: gzip normalised reports, at most 2000 rows and 30 days unused | Data model |
| Quality submission | A row in quality_submissions recorded by the API before admission (cap 4 pending per client, 24 h TTL) | REST and limits |
| Quality policy | QualityPolicy: per-repo mutate and support globs, thresholds, protectedBranch (default main) and chunkTimeoutMs, inside FactoryRepoPolicy | Status and limits |
| Quality image | apps/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 none | Exec worker and image |
| PRE-0 to PRE-3 | Owner preconditions for the quality exec host: Temporal access decision, sandbox host with runsc, Postgres volume (done), read-only GitHub App key | Deploy runbooks |
| Spikes S1 to S5 | Phase 0 prototypes: S1, S2, S4 pass; S5 (offline image) passes; S3 (runsc) not run | Quality overview |
Operations and infrastructure
| Term | Definition | Page |
|---|---|---|
| Core host | The CapRover host that runs Postgres, gateway, core worker and API (called app-03 in the source docs) | Deployment topology |
| Exec host | A sandbox host for exec workers and quality runs; not built (PRE-1) | Deployment topology |
| CapRover | The container platform on top of Docker Swarm used on each application host; apps are of type worker or web | Deployment topology |
agentforge-net | The private encrypted overlay network of the core host | Deployment topology |
| Tailnet | The private WireGuard network (Tailscale) over which clients, laptops and the Temporal host are reached; access is controlled by ACL tags | Deployment topology |
| Catalog | The hostinger repo's services.yml entries that declare each CapRover app; one file per host | Deploy runbooks |
| Drift gate | A read-only check that the live apps match the catalog; fails the fleet's applies while a merged entry has no live app | Deploy runbooks |
| Owner go | The owner's explicit approval, given in the session that performs a live change | Deploy runbooks |
| Immutable tag | An ECR tag that cannot be overwritten; a failed push burns it | Release process |
| Mirror | A single-platform copy of a digest-pinned upstream image (postgres, temporal) pushed to ECR as vX.Y.Z | Release process |
| Smoke test | An authenticated session turn through the whole stack after a deploy | Deploy runbooks |
| Real-key run | A 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 harness | apps/smoke: the private app that composes the guarded runtime over Postgres for real-key runs | Testing and CI |
| Smoke cap | The highest daily limit a real-key run accepts; a fixed hard ceiling in apps/smoke/src/compose.ts bounds it | Testing and CI |
| Conformance suite | The shared behavioural checks every runtime adapter must pass | Testing and CI |
| Fake | An in-memory stand-in for a runtime or store that copies the real semantics, used in keyless tests | Testing and CI |
| Store | The persistence behind a control: ledger store, settings store, alert store. Postgres in production, fakes in tests | Data model |
| Dossier | A session wrap-up folder under docs/sessions/ with a resume pointer | Session dossiers |
| Bead | An issue in the beads tracker (epic id hawkeye-81e; children .NN) | Repository docs map |
| ADR | Architecture decision record under docs/sessions/*/adr | Decisions |
| Plan ids | Acceptance-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.tspackages/agent-core/src/redaction.ts,alerts.ts,kill-switch.tspackages/quality-core/README.mdapps/api/src/config.ts,apps/worker/src/exec-config.tsdocs/deploy-worker-fleet.md,docs/deploy-gateway-coolify.md,docs/deploy-factory.md,docs/deploy-quality.mddocs/design-gateway-fleet-exposure.mddocs/sessions/*/adr/*.mdsecrets.manifest.yml