Current section
Files
Jump to
Current section
Files
docs/prelude-reference.md
<!-- Auto-generated — do not edit by hand -->
# Shipped prelude reference
> **Warning:** This file is auto-generated by `mix ptc.gen_docs` from the shipped component catalog and compiled PTC-Lisp exports.
> Manual edits will be overwritten. Edit `PtcRunner.Kernel.Library`, the sources under `priv/preludes/kernel/`, or `Mix.Tasks.Ptc.GenDocs` instead.
PtcRunner ships 14 reusable PTC-Lisp **components** with 48 public exports. A component is one named source module with one namespace. A **prelude** is the immutable compiled aggregate of the components selected for a workflow or mission, including their dependency closure.
Private `defn-` helpers are deliberately absent below. Public `defn` functions and `def` constants are derived from the same compiler records used by analysis, evaluation, introspection, and model inventory rendering.
## Choose a component
| Need | Start with |
| --- | --- |
| Generic manifest agent entry with result-contract correction | `agent.main` |
| Composable provider-neutral agent loop | `agent.core` |
| Direct provider-neutral model requests | `llm` |
| Subordinate mission evaluation and validation | `kernel` |
| Capability discovery, envelope handling, or bounded pagination | `cap` |
| Stable run-analysis profile navigation | `analysis` |
| Manifest-installed private snapshot navigation | `debug.nav` |
## Use and compose components
Select a shipped component as a library and declare it as a dependency of every local component that calls it:
```json
"components": [
{"id": "my.workflow", "path": "workflow.clj", "dependencies": ["kernel"]},
{"library": "kernel"}
]
```
Selecting a library expands its transitive shipped dependencies. Dependency declarations control which namespaces may call each other during compilation; they do not grant capabilities. Environment assembly must satisfy every backing requirement of the resolved exports.
## Authority and supported environments
The export sections list compile-time `tool:<name>` backing requirements. How they are satisfied depends on the operation family:
| Requirement family | Supplied by | Supported environment |
| --- | --- | --- |
| `tool:kernel-*`, `tool:workflow-annotate` | Reserved Kernel operations; applications cannot install or replace them as providers | Workflow |
| `tool:runtime-*`, `tool:cap-*` | Reserved Kernel operations | Workflow or mission |
| `tool:llm-request` | A selected live or replay model provider | Workflow |
| `tool:analysis-*` | A host-selected run-analysis profile | Its bounded analysis mission |
| `tool:debug.nav.*` | The correlated inspection snapshot provider selected under alias `debug.nav` | Mission |
Pure exports show no backing requirements. Requirements validate authority; they never create it. A component with reserved workflow requirements cannot be moved into a mission merely by selecting the library there.
Effects below use the same conservative, environment-independent projection as `(doc ...)` and `(export-meta ...)`: an export that reaches a capability is `unknown` unless its chain declares `write`. The authoritative model-visible effect belongs to the assembled mission inventory, where installed capability effects may resolve that value to `read` or `write`.
`:prompt` exports appear in model inventory. `:discoverable` exports stay out of that prompt inventory but remain callable and can be found with `(dir)`, `(dir "namespace")`, `(apropos "term")`, `(doc "namespace/name")`, `(export-meta "namespace/name")`, and `(source namespace/name)`. `apropos` and `doc` additionally cover fixed built-ins and the bounded Java surface; `dir`, `export-meta`, and `source` remain attached-prelude views. Hiding an export from the prompt does not narrow authority.
## Customize or replace a component
Use a new component ID for ordinary application-specific helpers or policies. A local component cannot shadow a selected shipped library ID; such collisions are rejected.
A [component override](guides/evaluating-with-replay.md#evaluate-the-candidate-without-installing-it) can evaluate hash-checked replacement source for one component already selected by the manifest. The override is a run invocation option, not a permanent manifest library installation. For a permanently customized agent prompt in ordinary manifest composition, use custom loop and prompt components under new IDs rather than depending on the shipped `agent.core`, whose dependency remains the shipped `agent.prompt` ID.
The resolved prelude is frozen for the run. Changed component source must be compiled into a new bundle, and traces identify the effective component and aggregate hashes.
## Dependency overview
| Component | Purpose | Visibility | Direct dependencies | Directly used by |
| --- | --- | --- | --- | --- |
| `agent.main` | Generic workflow entry for scripted agents. | `prompt` | `agent.core` | — |
| `agent.core` | Provider-neutral scripted PTC-Lisp agent loop. | `prompt` | `agent.feedback`, `agent.native`, `agent.prompt`, `agent.retry`, `kernel`, `llm`, `result`, `workflow.event` | `agent.main` |
| `agent.prompt` | Domain-blind system-prompt policy for agent.core. | `discoverable` | `kernel` | `agent.core` |
| `agent.feedback` | Bounded correction messages for agent workflows. | `prompt` | — | `agent.core` |
| `agent.retry` | Small deterministic agent retry policy. | `prompt` | — | `agent.core` |
| `agent.native` | Strict run_ptc_lisp model-action protocol. | `prompt` | — | `agent.core` |
| `kernel` | Explicit subordinate evaluation helpers. | `prompt` | — | `agent.core`, `agent.prompt` |
| `llm` | Provider-neutral language-model requests. | `prompt` | — | `agent.core` |
| `cap` | Capability discovery and envelope composition helpers. | `discoverable` | — | `analysis`, `debug.nav` |
| `runtime` | Read-only enforced run-resource snapshots. | `prompt` | — | — |
| `result` | Uniform opt-in workflow result values. | `prompt` | — | `agent.core` |
| `workflow.event` | Bounded workflow-authored semantic annotations. | `prompt` | — | `agent.core` |
| `analysis` | Bounded navigation over one immutable run-evidence capture. | `prompt` | `cap` | — |
| `debug.nav` | Typed navigation over one immutable private run-evidence capture. The mission must select its correlated inspection snapshot provider under the conventional alias debug.nav. | `prompt` | `cap` | — |
## Agent entry points
### `agent.main`
Generic workflow entry for scripted agents.
- **Visibility:** `prompt`
- **Direct dependencies:** `agent.core`
- **Selecting it also installs:** `agent.core`, `agent.feedback`, `agent.native`, `agent.prompt`, `agent.retry`, `kernel`, `llm`, `result`, `workflow.event`
- **Directly used by:** —
```json
{"library": "agent.main"}
```
#### Public exports
##### `agent.main/run`
```clojure
(agent.main/run input)
```
Runs `agent.core` from a manifest input, so a manifest can name this entry
directly instead of every application repeating the same wrapper.
`task` is the workflow's instruction and `agent` its loop configuration. Both
come from input, so this stays domain-blind: it never learns what the task is
about, and adding a new application needs no change here. The application
entry returns the model-authored value directly so a manifest result contract
describes that value rather than agent.core's default success envelope.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(input {task :string, agent {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`
### `agent.core`
Provider-neutral scripted PTC-Lisp agent loop.
- **Visibility:** `prompt`
- **Direct dependencies:** `agent.feedback`, `agent.native`, `agent.prompt`, `agent.retry`, `kernel`, `llm`, `result`, `workflow.event`
- **Selecting it also installs:** `agent.feedback`, `agent.native`, `agent.prompt`, `agent.retry`, `kernel`, `llm`, `result`, `workflow.event`
- **Directly used by:** `agent.main`
```json
{"library": "agent.core"}
```
#### Public exports
##### `agent.core/run`
```clojure
(agent.core/run task cfg)
```
Runs the agent loop as a terminal workflow entry.
The default result is a success envelope. Set `result_envelope` to false for
a raw application value. Use `run-value` when the caller must continue after
the model-authored value returns.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?, result_envelope :bool?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`
##### `agent.core/run-outcome`
```clojure
(agent.core/run-outcome task cfg)
```
Runs the agent loop and distinguishes model-authored completion from a
bounded subject-attributable failure or a bounded provider failure.
Provider failures return `{:status :provider-failure :error error :model alias}`
with the complete bounded LLM envelope. The closed `kind` and `reason` are
facts for workflow policy; this entry does not choose retry, failover, or
abort. Restarting with another alias starts another loop and does not resume
the previous transcript.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`
##### `agent.core/run-phased-result-value`
```clojure
(agent.core/run-phased-result-value task cfg)
```
Runs a sequence of bounded mission phases while retaining the exact
correlated model and evaluation transcript. At each host-controlled phase
boundary, the system prompt is rebuilt from the next mission's authority and
that phase's instruction is appended as a user message. A return closes any
non-final phase and is retained as evidence; only the final phase can complete
the agent with a contract-valid result. A terminal-only phase rejects any
parsed program whose single top-level form is not return or fail before
mission evaluation, and only the final phase may declare terminal_only.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, phases [{mission :string, max_turns :int, instruction :string?, terminal_only :bool?}], max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`
##### `agent.core/run-result-value`
```clojure
(agent.core/run-result-value task cfg)
```
Runs the agent loop and validates model-authored completion against the
manifest result contract before returning it to the calling workflow.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`
##### `agent.core/run-value`
```clojure
(agent.core/run-value task cfg)
```
Runs the agent loop and returns its model-authored value to the calling
PTC-Lisp function. Unlike `run`, this does not terminate the outer program,
so an application can validate or score the answer before returning.
Subject failures and provider failures retain the historical fail behavior.
Evaluators that need to record those attempts use `run-outcome`.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(task :string, cfg {model :string?, mission :string?, max_turns :any?, max_program_chars :any?, max_observation_chars :any?, max_transcript_chars :any?, consolidate_at_turns_remaining :int?}) -> :any`
- **Backing requirements:** `tool:kernel-agent-config-failure`, `tool:kernel-agent-protocol-error`, `tool:kernel-check-source`, `tool:kernel-eval`, `tool:kernel-llm-provider-failure`, `tool:kernel-mission-model-context`, `tool:kernel-result-contract`, `tool:kernel-result-contract-failure`, `tool:kernel-runtime-limit-failure`, `tool:llm-request`, `tool:workflow-annotate`
## Agent loop policy
### `agent.prompt`
Domain-blind system-prompt policy for agent.core.
- **Visibility:** `discoverable`
- **Direct dependencies:** `kernel`
- **Selecting it also installs:** `kernel`
- **Directly used by:** `agent.core`
```json
{"library": "agent.prompt"}
```
#### Public exports
##### `agent.prompt/initial-state`
```clojure
(agent.prompt/initial-state cfg)
```
Creates the initial domain-blind prompt-policy state from agent configuration.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.prompt/render`
```clojure
(agent.prompt/render state)
```
Renders the system prompt, or the capability error envelope that prevented it.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-mission-model-context`
##### `agent.prompt/transition`
```clojure
(agent.prompt/transition state event)
```
Advances prompt-policy state after one agent-loop event.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —
### `agent.feedback`
Bounded correction messages for agent workflows.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`
```json
{"library": "agent.feedback"}
```
#### Public exports
##### `agent.feedback/capability-error`
```clojure
(agent.feedback/capability-error evaluation)
```
Renders correction guidance for a safely retryable capability failure.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/evaluation-error`
```clojure
(agent.feedback/evaluation-error evaluation)
```
Renders bounded correction guidance for a failed evaluation.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/non-retryable`
```clojure
(agent.feedback/non-retryable evaluation)
```
Renders closing guidance after a failure whose external effects may be unsafe to repeat.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/protocol-error`
```clojure
(agent.feedback/protocol-error action)
```
Renders correction guidance for an invalid model action.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/result-contract`
```clojure
(agent.feedback/result-contract validation)
```
Renders bounded correction guidance for an invalid application result.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/success`
```clojure
(agent.feedback/success evaluation max-chars)
```
Renders a bounded, explicitly untrusted observation from a successful evaluation. Value-preview truncation names `*1` only for history-committing ordinary results; omitted println output is reported independently and is never attributed to `*1`.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/terminal-source-required`
```clojure
(agent.feedback/terminal-source-required check)
```
Renders correction guidance for a program rejected by a terminal-only phase.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.feedback/turn-budget`
```clojure
(agent.feedback/turn-budget turns-remaining consolidate-at-turns-remaining)
```
Renders model-visible pacing guidance outside the cached system prompt.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(turns_remaining :int, consolidate_at_turns_remaining :int?) -> :string`
- **Backing requirements:** —
### `agent.retry`
Small deterministic agent retry policy.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`
```json
{"library": "agent.retry"}
```
#### Public exports
##### `agent.retry/backoff-ms`
```clojure
(agent.retry/backoff-ms turn cfg)
```
Returns the bounded deterministic retry delay for a turn.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.retry/retry?`
```clojure
(agent.retry/retry? turn max-turns)
```
Returns whether another agent turn remains within the configured bound.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
### `agent.native`
Strict run_ptc_lisp model-action protocol.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`
```json
{"library": "agent.native"}
```
#### Public exports
##### `agent.native/normalize`
```clojure
(agent.native/normalize response max-program-chars)
```
Normalizes one provider response into a usable tool call or a bounded terminal/recoverable action. A complete run_ptc_lisp call wins even when the provider reports output truncation.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `agent.native/tool-schema`
```clojure
(agent.native/tool-schema)
```
Returns the strict provider-neutral run_ptc_lisp tool schema.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
## Evaluation and models
### `kernel`
Explicit subordinate evaluation helpers.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`, `agent.prompt`
```json
{"library": "kernel"}
```
#### Public exports
##### `kernel/check-source`
```clojure
(kernel/check-source mission source)
```
Check bounded dynamic source against the live mission environment without executing it.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-check-source`
##### `kernel/check-terminal-source`
```clojure
(kernel/check-terminal-source mission source)
```
Check that bounded dynamic source compiles and consists of exactly one top-level return or fail form, without executing it.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-check-source`
##### `kernel/eval`
```clojure
(kernel/eval mission program-value)
```
Evaluate an opaque static Program in the mission environment.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`
##### `kernel/eval-source`
```clojure
(kernel/eval-source mission source)
```
Evaluate bounded dynamic source text in the mission environment.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`
##### `kernel/eval-source-with`
```clojure
(kernel/eval-source-with mission source params)
```
Evaluate bounded dynamic source with JSON parameters at data/params.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`
##### `kernel/eval-with`
```clojure
(kernel/eval-with mission program-value params)
```
Evaluate an opaque static Program with JSON parameters at data/params.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-eval`
##### `kernel/mission-inventory`
```clojure
(kernel/mission-inventory mission)
```
Return the frozen prompt-facing mission inventory JSON, including data grants.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-mission-inventory`
##### `kernel/mission-model-context`
```clojure
(kernel/mission-model-context mission)
```
Return the compact deterministic mission context for the model prompt.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-mission-model-context`
##### `kernel/validate-result`
```clojure
(kernel/validate-result value)
```
Validate one candidate against the manifest's application result contract.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:kernel-result-contract`
### `llm`
Provider-neutral language-model requests.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`
```json
{"library": "llm"}
```
#### Public exports
##### `llm/request`
```clojure
(llm/request request)
```
Send a provider-neutral request. Tool calls use id, name, and args; token
usage may include input, output, cache_creation, cache_read, and total_cost.
On success this returns the model response value. Provider failures,
including a replay miss, are returned as error envelopes with :status
:error rather than failing the evaluation. Branch on :status and fail, or
call cap/unwrap! on the raw tool/llm-request envelope, so an unserved call
cannot look like a result.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:llm-request`
## Workflow helpers
### `cap`
Capability discovery and envelope composition helpers.
- **Visibility:** `discoverable`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `analysis`, `debug.nav`
```json
{"library": "cap"}
```
#### Public exports
##### `cap/describe`
```clojure
(cap/describe name)
```
Returns the installed description for one capability name.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** `tool:cap-describe`
##### `cap/fold-pages`
```clojure
(cap/fold-pages fetch step initial opts)
```
Reduces cursor-paginated items into bounded caller-owned state.
`fetch` receives nil for the first page or the opaque cursor supplied in
`opts`. `step` receives accumulator then item. Every page must contain
`items`, `next_cursor`, and a stable non-empty `snapshot_hash`.
`opts` requires a positive `max_pages`. Resuming with `cursor` also requires
the expected `snapshot_hash`. A page-bound stop returns `complete?` false and
preserves `next_cursor`, so another evaluation can continue without retaining
prior pages. Keep the accumulator bounded; pagination does not make an
unbounded collection safe. Repeated cursors within one invocation fail instead
of looping; a resumed invocation does not retain source-sized cursor history.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `cap/list`
```clojure
(cap/list)
```
Lists capabilities installed in the current environment.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** `tool:cap-list`
##### `cap/unwrap!`
```clojure
(cap/unwrap! response)
```
Returns a capability response's value, failing the program on any error.
Capability calls answer {:status :ok :value ...} or an error envelope. A
wrapper that returns the envelope on failure makes every caller re-check it,
and a caller that forgets treats an error map as ordinary data. This fails
instead, so an unhandled provider error stops the program rather than
flowing onward as a plausible-looking result.
- **Kind:** `function`
- **Visibility:** `discoverable`
- **Effect:** `unknown`
- **Backing requirements:** —
### `runtime`
Read-only enforced run-resource snapshots.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** —
```json
{"library": "runtime"}
```
#### Public exports
##### `runtime/remaining`
```clojure
(runtime/remaining)
```
Returns the enforced run-resource allowance remaining.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:runtime-remaining`
##### `runtime/usage`
```clojure
(runtime/usage)
```
Returns the enforced run-resource usage snapshot.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:runtime-usage`
### `result`
Uniform opt-in workflow result values.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`
```json
{"library": "result"}
```
#### Public exports
##### `result/error`
```clojure
(result/error kind reason)
```
Builds a standard opt-in workflow error envelope.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `result/ok`
```clojure
(result/ok value)
```
Wraps a successful workflow value in the standard opt-in result envelope.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
##### `result/ok?`
```clojure
(result/ok? result)
```
Returns whether a standard result envelope represents success.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** —
### `workflow.event`
Bounded workflow-authored semantic annotations.
- **Visibility:** `prompt`
- **Direct dependencies:** —
- **Selecting it also installs:** —
- **Directly used by:** `agent.core`
```json
{"library": "workflow.event"}
```
#### Public exports
##### `workflow.event/annotate`
```clojure
(workflow.event/annotate annotation-type data)
```
Emits one bounded workflow-authored semantic annotation.
A refused well-formed annotation — a string type or data shape that is
not in the traces vocabulary — returns {:status :error :kind
:invalid_annotation :reason :invalid_workflow_annotation} rather than
failing the evaluation. Accepted types and keys are the finite vocabulary
published by ptc docs traces.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:workflow-annotate`
## Run evidence
### `analysis`
Bounded navigation over one immutable run-evidence capture.
- **Visibility:** `prompt`
- **Direct dependencies:** `cap`
- **Selecting it also installs:** `cap`
- **Directly used by:** —
```json
{"library": "analysis"}
```
#### Public exports
##### `analysis/open`
```clojure
(analysis/open run-id)
```
Opens one captured run and returns its available evidence collections.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-open`
##### `analysis/read`
```clojure
(analysis/read run-id options)
```
Reads one bounded page from a captured run-evidence collection.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-read`
##### `analysis/runs`
```clojure
(analysis/runs options)
```
Lists captured runs using the stable run-analysis profile.
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Backing requirements:** `tool:analysis-runs`
### `debug.nav`
Typed navigation over one immutable private run-evidence capture. The mission must select its correlated inspection snapshot provider under the conventional alias debug.nav.
- **Visibility:** `prompt`
- **Direct dependencies:** `cap`
- **Selecting it also installs:** `cap`
- **Directly used by:** —
```json
{"library": "debug.nav"}
```
#### Public exports
##### `debug.nav/follow`
```clojure
(debug.nav/follow run-id relationship options)
```
Follow one typed relationship returned by an evidence item. The relationship supplies the exact target collection and filters; options may contain only limit and cursor. Check the relationship first: one whose state is "unavailable", or whose filters are null, cannot be followed and calling follow on it fails the program instead of returning a page. Returns the original relationship beside the complete native page envelope. Example: (debug.nav/follow run-id relationship {"limit" 20}).
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(run-id :string, relationship :map, options :map) -> :map`
- **Backing requirements:** `tool:debug.nav.read`
##### `debug.nav/open`
```clojure
(debug.nav/open run-id)
```
Open a run and discover available collections, filters, identifiers, and completeness fields. Example: (debug.nav/open "run-id").
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(run-id :string) -> :map`
- **Backing requirements:** `tool:debug.nav.open`
##### `debug.nav/read`
```clojure
(debug.nav/read run-id options)
```
Read one native evidence page. Put collection and advertised filters directly in options; do not nest them under filters. Example: (debug.nav/read "run-id" {"collection" "turns" "evaluation_id" "mission-evaluation-9"}).
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(run-id :string, options :map) -> :map`
- **Backing requirements:** `tool:debug.nav.read`
##### `debug.nav/runs`
```clojure
(debug.nav/runs options)
```
List captured runs. Example: (debug.nav/runs {"status" "error" "limit" 5}).
- **Kind:** `function`
- **Visibility:** `prompt`
- **Effect:** `unknown`
- **Contract:** `(options :map) -> :map`
- **Backing requirements:** `tool:debug.nav.runs`
## Related guides
- [Components and preludes](guides/components-and-preludes.md) explains local components, contracts, dependency boundaries, and authority.
- [Building agents](guides/building-agents.md) applies the agent libraries to workflow and mission design.
- [Agent library reference](agent-library-reference.md) defines the complete loop configuration, turn protocol, retry, and failure behavior.
- [Manifests and capabilities](guides/manifests-and-capabilities.md) defines selection and environment assembly.