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 hand-authored sources under priv/preludes/kernel/, PtcRunner.Kernel.LLMFailureCatalog (for generated agent.failure), or Mix.Tasks.Ptc.GenDocs instead.

PtcRunner ships 17 reusable PTC-Lisp components with 60 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`
Rendered agent prompt measurement	`prompt.audit`

Use and compose components

Select a shipped component as a library and declare it as a dependency of every local component that calls it:

"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 installed callable capabilities, fixed built-ins, and the bounded Java surface; dir, export-meta, and source remain attached-prelude views. At Kernel boundaries, an exact doc miss for an indexed shipped public export can identify its unattached owning library. The exact index is diagnostic only and is never searched by apropos. Hiding an export or capability from the prompt does not narrow authority or runtime discovery.

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 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.machine`, `agent.native`, `agent.prompt`, `kernel`, `llm`, `result`, `workflow.event`	`agent.main`
`agent.prompt`	Domain-blind system-prompt policy for agent.core.	`discoverable`	`kernel`	`agent.core`, `agent.machine`
`agent.feedback`	Bounded correction messages for agent workflows.	`prompt`	—	`agent.machine`
`agent.retry`	Small deterministic agent retry policy.	`prompt`	—	`agent.machine`
`agent.native`	Strict run_ptc_lisp model-action protocol.	`prompt`	—	`agent.core`
`agent.failure`	Closed classification of admitted LLM provider, protocol, and whole-request timeout envelopes.	`discoverable`	—	`agent.machine`
`agent.machine`	Pure agent-loop reducer: immutable context/state and closed event-to-command transitions. Visibility is presentation only; exports remain callable and are not an authority boundary.	`discoverable`	`agent.failure`, `agent.feedback`, `agent.prompt`, `agent.retry`, `result`	`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`, `agent.machine`
`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`	—
`prompt.audit`	Size measurement for a rendered agent system prompt. `agent.prompt/render` interleaves authored instruction text with manifest-derived API text, so one byte count for the whole prompt cannot say which of the two an edit moved. These functions take the rendered string — from a recorded run, a committed fixture, or any other source — and answer three questions about it: which segments it is made of, how large each one is, and what changed between two versions. Every function is pure and takes a string. Nothing here reads a run, calls a capability, or assembles a manifest, so the same numbers are available to a REPL session reading recorded evidence and to a test guarding a fixture.	`discoverable`	—	—

Agent entry points

`agent.main`

Generic workflow entry for scripted agents.

Visibility: prompt
Direct dependencies: agent.core
Selecting it also installs: agent.core, agent.failure, agent.feedback, agent.machine, agent.native, agent.prompt, agent.retry, kernel, llm, result, workflow.event
Directly used by: —

{"library": "agent.main"}

Public exports

`agent.main/run`

(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-phase-return-contract-failure, 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.machine, agent.native, agent.prompt, kernel, llm, result, workflow.event
Selecting it also installs: agent.failure, agent.feedback, agent.machine, agent.native, agent.prompt, agent.retry, kernel, llm, result, workflow.event
Directly used by: agent.main

{"library": "agent.core"}

Public exports

`agent.core/run`

(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. The exact value this entry returns is validated against the manifest result contract while a correction turn remains: the envelope by default, or the raw value when result_envelope is false. Use run-value when the caller must continue after the model-authored value returns, and run-result-value when that raw value is itself the contract-shaped application result.

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-phase-return-contract-failure, tool:kernel-result-contract, tool:kernel-result-contract-failure, tool:kernel-runtime-limit-failure, tool:llm-request, tool:workflow-annotate

`agent.core/run-outcome`

(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. The returned outcome is workflow data; this entry does not validate against the manifest result contract. Set return_contract to a name declared under contracts.phase_return_schemas to validate each explicit return inside this standalone loop while correction turns remain.

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?, return_contract :any?, 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-phase-return-contract-failure, 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`

(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?, return_contract :string?}], 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-phase-return-contract-failure, 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`

(agent.core/run-result-value task cfg)

Runs the agent loop and validates the raw model-authored value against the manifest result contract before returning it to the calling workflow. Use this when that raw value is itself the final contract-shaped application result.

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-phase-return-contract-failure, tool:kernel-result-contract, tool:kernel-result-contract-failure, tool:kernel-runtime-limit-failure, tool:llm-request, tool:workflow-annotate

`agent.core/run-value`

(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 and does not validate against the manifest result contract, so an application can validate or score the answer before returning. Set return_contract to a declared named phase-return contract when the value crossing back to the workflow must be checked and corrected inside this standalone loop.

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?, return_contract :any?, 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-phase-return-contract-failure, 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, agent.machine

{"library": "agent.prompt"}

Public exports

`agent.prompt/initial-state`

(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`

(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`

(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.machine

{"library": "agent.feedback"}

Public exports

`agent.feedback/capability-error`

(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`

(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`

(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/phase-result-contract`

(agent.feedback/phase-result-contract validation)

Renders bounded correction guidance for an invalid phase handoff.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: —

`agent.feedback/protocol-error`

(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`

(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`

(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`

(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`

(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.machine

{"library": "agent.retry"}

Public exports

`agent.retry/backoff-ms`

(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?`

(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

{"library": "agent.native"}

Public exports

`agent.native/normalize`

(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`

(agent.native/tool-schema)

Returns the strict provider-neutral run_ptc_lisp tool schema.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: —

`agent.failure`

Closed classification of admitted LLM provider, protocol, and whole-request timeout envelopes.

Visibility: discoverable
Direct dependencies: —
Selecting it also installs: —
Directly used by: agent.machine

{"library": "agent.failure"}

Public exports

`agent.failure/classify`

(agent.failure/classify error)

Returns true when error is an admitted recoverable LLM envelope.

Inspects only kind and reason. Does not add a field to the envelope or consume Kernel evidence.

Kind: function
Visibility: discoverable
Effect: unknown
Contract: (error :any) -> :bool
Backing requirements: —

`agent.machine`

Pure agent-loop reducer: immutable context/state and closed event-to-command transitions. Visibility is presentation only; exports remain callable and are not an authority boundary.

Visibility: discoverable
Direct dependencies: agent.failure, agent.feedback, agent.prompt, agent.retry, result
Selecting it also installs: agent.failure, agent.feedback, agent.prompt, agent.retry, kernel, result
Directly used by: agent.core

{"library": "agent.machine"}

Public exports

`agent.machine/advance`

(agent.machine/advance machine event)

One pure transition. Returns a closed command; never calls LLM, Kernel, tools, or fail.

Kind: function
Visibility: discoverable
Effect: unknown
Contract: (machine :map, event :any) -> :any
Backing requirements: —

`agent.machine/start`

(agent.machine/start task context)

Constructs immutable context and initial loop state. Performs no effects. Returns {:op :ok :machine ...} or a host-failure command.

Kind: function
Visibility: discoverable
Effect: unknown
Contract: (task :string, context :map) -> :any
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

{"library": "kernel"}

Public exports

`kernel/check-source`

(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`

(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`

(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`

(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`

(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`

(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`

(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`

(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/phase-return-contract-presentation`

(kernel/phase-return-contract-presentation name)

Resolve one named phase-return contract and return its model projection.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: tool:kernel-result-contract

`kernel/result-contract-presentation`

(kernel/result-contract-presentation)

Return the bounded renderer-neutral application result contract, or nil.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: tool:kernel-result-contract

`kernel/validate-phase-return`

(kernel/validate-phase-return name value)

Validate an explicit phase or standalone handoff return against its named contract.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: tool:kernel-result-contract

`kernel/validate-result`

(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

{"library": "llm"}

Public exports

`llm/request`

(llm/request request)

Send a provider-neutral request. An optional schema key requests structured output: success is a structured_output object with optional tokens, never encoded content. Tools and schema together are invalid. Tool calls use id, name, and args; token usage may include input, output, cache_creation, cache_read, and fixed-point total_cost as a USD currency and integer microunits object.

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

{"library": "cap"}

Public exports

`cap/describe`

(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`

(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`

(cap/list)

Lists capabilities installed in the current environment.

Kind: function
Visibility: discoverable
Effect: unknown
Backing requirements: tool:cap-list

`cap/unwrap!`

(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: —

{"library": "runtime"}

Public exports

`runtime/remaining`

(runtime/remaining)

Returns the enforced run-resource allowance remaining.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: tool:runtime-remaining

`runtime/usage`

(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, agent.machine

{"library": "result"}

Public exports

`result/error`

(result/error kind reason)

Builds a standard opt-in workflow error envelope.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: —

`result/ok`

(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?`

(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

{"library": "workflow.event"}

Public exports

`workflow.event/annotate`

(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: —

{"library": "analysis"}

Public exports

`analysis/counters`

(analysis/counters filters)

Returns trace counters for a filtered run cohort, including adapter-attested model usage. Filters are the existing counter keys; there is no limit, cursor, view, or run_ids argument. Call once per selected run_id to reduce an explicit cohort.

Kind: function
Visibility: prompt
Effect: unknown
Backing requirements: tool:analysis-counters

`analysis/open`

(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`

(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`

(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: —

{"library": "debug.nav"}

Public exports

`debug.nav/counters`

(debug.nav/counters filters)

Return trace counters for a filtered run cohort, including adapter-attested model usage. Filters are the existing counter keys; call once per selected run_id to reduce an explicit cohort. Example: (debug.nav/counters {"run_id" "run-id"}).

Kind: function
Visibility: prompt
Effect: unknown
Contract: (filters :map) -> :map
Backing requirements: tool:debug.nav.counters

`debug.nav/follow`

(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`

(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`

(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`

(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

`prompt.audit`

Size measurement for a rendered agent system prompt.

agent.prompt/render interleaves authored instruction text with manifest-derived API text, so one byte count for the whole prompt cannot say which of the two an edit moved. These functions take the rendered string — from a recorded run, a committed fixture, or any other source — and answer three questions about it: which segments it is made of, how large each one is, and what changed between two versions.

Every function is pure and takes a string. Nothing here reads a run, calls a capability, or assembles a manifest, so the same numbers are available to a REPL session reading recorded evidence and to a test guarding a fixture.

Visibility: discoverable
Direct dependencies: —
Selecting it also installs: —
Directly used by: —

{"library": "prompt.audit"}

Public exports

`prompt.audit/delta`

(prompt.audit/delta before after)

Compares two rendered prompts and reports the character change per segment.

Returns {"rows" [...]}, one row per label present in either input, in the emission order of after with labels unique to before appended. Each row is {"label" .. "before" .. "after" .. "change" .. "percent" ..}.

All three counts are characters; delta reports no token estimates. A label present on only one side counts 0 on the other. percent is the change against before rounded to one decimal place, and nil when before is 0.

Kind: function
Visibility: discoverable
Effect: unknown
Backing requirements: —

`prompt.audit/measure`

(prompt.audit/measure text)

Measures a rendered agent system prompt, per segment and in total.

Returns {"rows" [...] "recognised?" bool}. rows holds one row per present segment in emission order, then the derived rows authored, dynamic and total. Each row is {"label" .. "characters" .. "lines" .. "tokens_estimated" ..}.

characters is authoritative and counts graphemes, as count does. Bytes are not reported: the string surface exposes no UTF-8 byte size, and characters are tokenizer-independent and sufficient for a budget. tokens_estimated is ceil(characters / 4) — an estimate, named so a caller cannot mistake it for a measurement — and the derived rows compute it from their own aggregated character count rather than by summing per-segment estimates, which would differ.

authored sums the fixed prompt-policy segments. dynamic sums api-notes, api-entries, and the manifest-driven result and phase contract projections; an unrecognised segment counts as authored. So authored + dynamic equals total in both cases. Treat the split as approximate reporting: the dynamic segments carry authored formatter text — headings and the per-entry Call, Type and Docs labels — so it says roughly how much of a rendering a manifest drove, and no more. A budget reads total.

Kind: function
Visibility: discoverable
Effect: unknown
Backing requirements: —

`prompt.audit/segments`

(prompt.audit/segments text)

Splits a rendered agent system prompt into its ordered emission segments.

Returns a vector of {"label" .. "text" ..} in the order render emits them: marker, protocol, language, examples, api-heading, api-notes, api-legend, api-entries, result-contract, phase-return-contract. Each label occurs at most once. api-notes, api-entries, and both optional contract projections are manifest-derived; the remaining segments are authored in agent.prompt. The order is the structure — the rendering interleaves authored and dynamic text, so no unordered value can encode reassembly.

The authored empty-API sentence is an api-empty segment. api-notes is absent when the mission declares no namespace docstrings. Result and phase-return contracts are optional dynamic suffix segments.

Recognition validates the V1 marker, boundary anchors, their ordering and uniqueness, complete entry termination, and the fixed contract prefixes. It is structural rather than a byte-for-byte validation of authored prose. A string that fails those checks returns one unrecognised segment carrying the whole input instead of guessed boundaries.

Joining the segment texts in order reproduces the input exactly, in both the recognised and the unrecognised case. That invariant is what makes the per-segment character counts add up to the whole.

Kind: function
Visibility: discoverable
Effect: unknown
Backing requirements: —

Components and preludes explains local components, contracts, dependency boundaries, and authority.
Building agents applies the agent libraries to workflow and mission design.
Agent library reference defines the complete loop configuration, turn protocol, retry, and failure behavior.
Manifests and capabilities defines selection and environment assembly.