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

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:

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

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

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

(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

(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

(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

(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

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

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

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

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