prelude-reference.md

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 45 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:

"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"), and (export-meta "namespace/name"). apropos and doc additionally cover fixed built-ins and the bounded Java surface; dir and export-meta 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 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: —

{"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 :int?, max_program_chars :int?, max_observation_chars :int?, max_transcript_chars :int?, consolidate_at_turns_remaining :int?}}) -> :any
• Backing requirements: 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

{"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. 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 :int?, max_program_chars :int?, max_observation_chars :int?, max_transcript_chars :int?, consolidate_at_turns_remaining :int?, result_envelope :bool?}) -> :any
• Backing requirements: 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

(agent.core/run-outcome task cfg)

Runs the agent loop and distinguishes model-authored completion from a bounded subject-attributable failure.

• Kind: function
• Visibility: prompt
• Effect: unknown
• Contract: (task :string, cfg {model :string?, mission :string?, max_turns :int?, max_program_chars :int?, max_observation_chars :int?, max_transcript_chars :int?, consolidate_at_turns_remaining :int?}) -> :any
• Backing requirements: 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

(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 :int?, max_program_chars :int?, max_observation_chars :int?, max_transcript_chars :int?, consolidate_at_turns_remaining :int?}) -> :any
• Backing requirements: 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

(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 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 :int?, max_program_chars :int?, max_observation_chars :int?, max_transcript_chars :int?, consolidate_at_turns_remaining :int?}) -> :any
• Backing requirements: 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

{"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.core

{"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/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.

• 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.core

{"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 tool call, provider error, or protocol error.

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

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/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 exact frozen model-visible mission inventory JSON.

• 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/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. Tool calls use id, name, and args; token usage may include input, output, cache_creation, cache_read, and total_cost.

• 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

{"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.

• 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/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/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

Related guides

• 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.