Kernel limits reference
Warning: This file is auto-generated by
mix ptc.gen_docsfrom the Kernel limit catalog. Manual edits will be overwritten. Editlib/ptc_runner/kernel/limit_catalog.exinstead.
Ordinary limits are positive enforced ceilings. Optional limits are disabled when omitted by the host. Two documents decide an enabled number: the host document installs the outer ceiling and the application manifest may narrow it.
To raise a limit, edit limits in the manifest. Raising the installed ceiling alone moves the enforced value only while that ceiling is the binding one, and with the installed defaults listed below it is not: a host-only edit leaves the run at the effective default. A run that needs longer than the 30,000 ms run_duration_ms default therefore asks for it in the manifest — ptc.json — and nowhere else:
{ "limits": { "run_duration_ms": 120000, "workflow_timeout_ms": 120000 } }Only when the application needs a value above the installed ceiling — here, above the 1,800,000 ms run_duration_ms ceiling — does the host document, ptc-host.json, need a matching edit, alongside the same request in the manifest:
{ "install": {}, "limits": { "run_duration_ms": 3600000 } }The four heap and concurrency rows, and llm_request_timeout_ms, are the
exceptions whose installed default equals their effective default. Heap
rows stay there because live memory is live_provider_tasks multiplied by
a heap ceiling. The LLM whole-call deadline stays there because
applications may only narrow it; a host document owns any widening. Raising
either exception requires both a host ceiling above the compiled default
and a matching manifest request. A limits-only host document —
{"install": {}, "limits": {...}} — is enough for heap and concurrency
rows; it does not need a fabricated provider. A live LLM deadline also
requires the selected installation's ceilings.request_timeout_ms to be
raised to the requested value.
Normal trace limits also have structural rules. event_payload_bytes is at least 8,211: the largest run-stopped payload an application-free manifest can emit. An application that declares capabilities or missions needs more, and because that requirement is only known once providers are assembled it is refused when the run starts, as application/limit_capacity_invalid, naming the effective limit and the bytes it must reach. normal_event_count is at least 3: one ordinary run-started event plus the two-event terminal reserve. After host/application resolution, normal_event_bytes must be at least EventSink.terminal_reserve(:normal, effective_limits).bytes + EventBudget.maximum_event_bytes("run-started", event_payload_bytes), preserving one complete maximum-size run-started envelope in addition to the complete events-dropped and run-stopped envelopes. Invalid combinations are refused before execution as application/limit_configuration_invalid. Private trace policy keeps its zero terminal reserve and does not use this normal-trace byte relationship.
A breached ceiling names itself, its configured value, and the manifest key that raises it, so the error at the point of failure carries this rule too. A request above the ceiling is refused by name, with both numbers.
An agent loop spends two budgets at once, and only one of them is a clock. max_turns bounds the agent protocol: it limits how many model-and-program turns the loop may attempt, and reserves no elapsed time to finish them. The complete run, including active preflight and every provider wait, must fit inside run_duration_ms; the workflow evaluation that owns the loop must also fit inside workflow_timeout_ms. Raising only run_duration_ms leaves the workflow clock as a separate boundary, so a live agent requests explicit values for both from its expected turn count and model latency.
Time values are milliseconds. Heap values are BEAM process heap words, not bytes. The catalog range is the accepted structural range; practical installations should choose ceilings appropriate to their resources and trust boundary.
Application-narrowable limits
| Name | Meaning | Unit | Effective default | Installed default | Inclusive range |
|---|---|---|---|---|---|
capability_argument_bytes | Encoded arguments crossing a capability boundary. | bytes | 262,144 | 4,000,000 | 1–2,592,000,000 |
capability_result_bytes | Encoded result crossing a capability boundary. | bytes | 1,000,000 | 16,000,000 | 1–2,592,000,000 |
entry_source_bytes | Workflow entry source accepted at the application boundary. | bytes | 262,144 | 4,000,000 | 1–2,592,000,000 |
evaluation_admission_timeout_ms | Wait for the single subordinate-evaluation lease before execution begins. | milliseconds | 10,000 | 600,000 | 1–2,592,000,000 |
evaluation_heap_words | Heap of each subordinate evaluator process. | BEAM heap words | 1,250,000 | 1,250,000 | 1–2,592,000,000 |
evaluation_history_bytes | Each value and the aggregate exact three-value continuation history. | bytes | 1,000,000 | 16,000,000 | 1–2,592,000,000 |
evaluation_memory_bytes | Retained mission definitions across successful turns. | bytes | 2,000,000 | 32,000,000 | 1–2,592,000,000 |
evaluation_timeout_ms | One subordinate mission evaluation, and one interactive REPL form. | milliseconds | 30,000 | 600,000 | 1–2,592,000,000 |
event_payload_bytes | One trace event payload. | bytes | 262,144 | 4,000,000 | 8,211–2,592,000,000 |
live_provider_tasks | Concurrent provider callback processes and Kernel-owned parallel Lisp workers. | count | 8 | 8 | 1–2,592,000,000 |
llm_request_output_tokens | Authorized output tokens for one live language-model call, supplied as that call's max_tokens. | count | 4,096 | 65,536 | 1–1,000,000 |
llm_request_timeout_ms | Whole-call deadline for one live language-model request, including adapter work, retries, and structured output validation. | milliseconds | 120,000 | 120,000 | 100–1,800,000 |
mission_capability_calls | Total mission capability calls in one run. | count | 256 | 4,096 | 1–2,592,000,000 |
mission_capability_calls_per_name | Mission capability calls to any one public name in one run. | count | 128 | 2,048 | 1–2,592,000,000 |
normal_event_bytes | Aggregate encoded trace events retained under the normal policy. | bytes | 4,000,000 | 64,000,000 | 1–2,592,000,000 |
normal_event_count | Trace events retained under the normal policy. | count | 256 | 4,096 | 3–2,592,000,000 |
parallel_timeout_ms | One pmap or pcalls operation, clamped by the run deadline. | milliseconds | 60,000 | 600,000 | 1–2,592,000,000 |
protocol_errors | Recoverable agent protocol errors in one run. | count | 64 | 512 | 1–2,592,000,000 |
provider_heap_words | Heap of each provider callback process. | BEAM heap words | 5,000,000 | 5,000,000 | 1–2,592,000,000 |
run_duration_ms | Complete ordinary run after optional provider application admission, including active preflight and Kernel execution. | milliseconds | 30,000 | 1,800,000 | 1–2,592,000,000 |
subordinate_evaluations | Subordinate mission evaluations in one run. | count | 128 | 2,048 | 1–2,592,000,000 |
subordinate_source_bytes | Source accepted by one subordinate check or evaluation. | bytes | 131,072 | 2,000,000 | 1–2,592,000,000 |
subordinate_source_checks | Advisory subordinate source checks in one run. | count | 128 | 2,048 | 1–2,592,000,000 |
terminal_result_bytes | Encoded terminal workflow or mission-session result. | bytes | 1,000,000 | 16,000,000 | 1–2,592,000,000 |
workflow_capability_calls | Total workflow capability calls in one run. | count | 256 | 4,096 | 1–2,592,000,000 |
workflow_capability_calls_per_name | Workflow capability calls to any one public name in one run. | count | 128 | 2,048 | 1–2,592,000,000 |
workflow_heap_words | Heap of the workflow evaluator process. | BEAM heap words | 8,000,000 | 8,000,000 | 1–2,592,000,000 |
workflow_timeout_ms | One workflow evaluation. | milliseconds | 30,000 | 1,800,000 | 1–2,592,000,000 |
Optional application-narrowable limits
These limits are disabled by an omitted host value. A positive host value enables the limit, becomes its inherited manifest default and installed ceiling, and may be narrowed by the manifest. A manifest cannot enable a host-disabled limit. Prerequisites, when listed, apply to every live LLM installation while that host limit is enabled.
| Name | Meaning | Unit | Disabled default | Inclusive range |
|---|---|---|---|---|
evaluation_loop_iterations | Optional per-activation loop/tail-recur bound for one subordinate mission evaluation and one interactive REPL form. | count | null | 1–2,592,000,000 |
llm_cost_microusd | Pre-dispatch USD reservation ceiling, in microunits, across live language-model calls in one run. Requires usage_guarantees.tokens: true, usage_guarantees.cost_currency: "USD", and an explicit USD reservation_tariff on every live LLM installation. | count | null | 1–9,007,199,254,740,991 |
llm_total_tokens | Aggregate provider-counted input and output tokens authorized across live language-model calls in one run. Requires usage_guarantees.tokens: true on every live LLM installation. | count | null | 1–9,007,199,254,740,991 |
workflow_loop_iterations | Optional per-activation loop/tail-recur bound for one workflow evaluation. | count | null | 1–2,592,000,000 |
Size an LLM cost budget
llm_cost_microusd is a pre-dispatch reservation ceiling, not a pre-run
price quote or a direct measurement of realized spend. Before each live
call, PtcRunner computes a conservative, request-specific reservation from
the request and accumulated conversation, the full authorized output-token
allowance, and the model's pricing. Later calls can therefore require more
headroom than earlier ones, and a ceiling set near expected final spend can
refuse before any call is dispatched.
For example, after 62 microUSD has settled, a 2,400 microUSD ceiling has 2,338 remaining. If the next call requires a 2,419 microUSD reservation, it is refused with the exact diagnostic:
llm_cost_microusd limit 2400 microUSD would be exceeded: the next call requires a 2419 microUSD reservation with 2338 remaining; raise limits.llm_cost_microusd in the manifest, and the installed host ceiling if it is lowerThose numbers describe one request; their ratio to its eventual cost is not
a sizing multiplier. ptc models, ptc validate, and ptc doctor do not
provide a pre-run price quote. The optional cost budget is the fail-closed
admission control, and a refusal reports the next call's exact required
reservation.
Valid priced usage releases the unused reservation and charges actual cost.
A dispatched call without trustworthy priced usage conservatively charges
the full reservation and marks llm_budget.cost.state as incomplete; that
charge is an accounting upper bound, not measured spend. When its state is
available, llm_spend aggregates trustworthy priced usage from successful
and failed calls. A possibly dispatched failure without trustworthy usage
makes spend incomplete, because it can still incur unmeasured provider charges.
To reduce the output portion of future reservations, an application may
narrow limits.llm_request_output_tokens, or a model installation may set a
lower params.max_tokens. Lower either only when the smaller output allowance
is valid for the workload; request and conversation size still contribute to
each reservation.
Installed-only limits
These operational timeouts belong only to the host document. A manifest cannot declare them.
| Name | Meaning | Unit | Installed default | Inclusive range | Effective identity |
|---|---|---|---|---|---|
doctor_connectivity_timeout_ms | One doctor --connect provider health check. | milliseconds | 10,000 | 100–30,000 | no |
local_preflight_timeout_ms | Whole audited local-preflight phase across selected providers. | milliseconds | 5,000 | 100–30,000 | yes |
provider_cleanup_timeout_ms | Kernel-owned provider cleanup after execution. | milliseconds | 5,000 | 100–30,000 | yes |
selection_validation_timeout_ms | Active validation of selected provider declarations. | milliseconds | 5,000 | 100–30,000 | yes |
Related documentation
- Application-manifest reference explains application narrowing.
- Host-configuration reference explains outer installed policy.
- Building agents distinguishes agent-loop options from Kernel limits.