Metadata-Version: 2.4
Name: b3-prosaic-runtime
Version: 0.8.1
Summary: Bounded execution of neutral Prosaic agents on OpenAI-compatible and native Anthropic endpoints
Author: B3 Cognition
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-MIT
License-File: NOTICE.md
Requires-Dist: b3-prosaic<0.5,>=0.4
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.23
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: setuptools>=77; extra == "test"
Requires-Dist: wheel; extra == "test"
Requires-Dist: packaging>=24; extra == "test"
Dynamic: license-file

# Prosaic Runtime

The **0.8.1** candidate is distributed as `b3-prosaic-runtime` and requires
`b3-prosaic>=0.4,<0.5` from the package index. Python imports (`prosaic_runtime`)
and the `prosaic-runtime` CLI remain unchanged. The separately installed recorder
is `b3-prosaic-runtime-postgres` **0.2.1**, selecting Runtime 0.8.x.
Candidates are not public index releases until the release qualification gate passes.

Runtime exports pure execution-artifact and native registry validation for host
workflow admission and reuses Core's canonical in-memory artifact validation.

Version **0.7.0** adds bounded native Anthropic text, streaming and tools, alongside
OpenAI-compatible execution. The separate `prosaic-runtime-postgres` **0.1.1**
recorder validates real schema and runtime grants without DDL. Release assets include both packages;
install the Runtime wheel before the adapter wheel. Accounting stays opt-in.

Optional customer usage metering is described in [Accounting](docs/accounting.md).
Existing callers need no IDs or database; durable tracking uses a separately installed
PostgreSQL recorder and does not enable customer charges.

Runtime also offers optional [bounded observation](docs/telemetry.md) through
`run(observer=..., operation_context=InvocationScope(...))` and the `observer_v1`
capability. Ordinary observer exceptions leave execution results unchanged.
The existing `on_event` callback remains a critical evidence hook. Operation
scope supplies opaque host correlation without enabling accounting.

Installation and CI do not require Node.js or npm.

Version 0.5.3 retains trusted macOS framework Python startup probes using their
declared sandbox working directory and pins the updated permission documentation.

See the [prompt-injection audit and remaining isolation gaps](docs/security.md)
before granting tools access to sensitive workspaces.

Version 0.5.0 adds [custom CLI tools, discovery and offline preflight](docs/cli-tools.md),
with a complete runnable CLI and an optional Understanding adapter.

Version 0.5.0 also adds [host-registered custom tools](examples/README.md#host-registered-custom-tools):
validated Python callbacks with native function calling. Both APIs are opt-in;
Python callbacks execute trusted host code and are not sandboxed. CLI subprocesses
are also unsandboxed by default; the opt-in below isolates them.

## Tool permissions and CLI isolation

Runtime **0.5.2** includes `cli_sandbox_v1` and opt-in CLI isolation.
Versions 0.5.1 and earlier do not include it; upgrading Prosaic alone does not
enable isolation. Start with the
[sandboxed CLI walkthrough](examples/README.md#sandboxed-cli-tools-runtime-052)
and its [complete configuration](examples/cli-tools-sandboxed.yml).

Markdown requests capabilities; it does not grant host authority:

| Layer | Example | Who owns it? |
| --- | --- | --- |
| Agent Markdown | `tools: [analyze_spec]` | Agent author declares what is needed |
| Runtime YAML | `allowed_tools: [analyze_spec]` | Operator allows the tool |
| Invocation | `--allow-tool analyze_spec --read-root evidence` | Host grants this call's tool and readable inputs |
| CLI OS boundary | `cli_sandbox: {mode: required}` in Runtime YAML | Operator requires isolation; prose cannot disable it |

All three tool declarations/grants must intersect. Merely installing a CLI or
adding it to frontmatter grants nothing. For custom CLIs, the operator also
reviews the executable and explicitly trusts its YAML manifest directory via
`tool_directories`; never automatically trust model-generated manifests.

Required mode confines CLI tools and their version probes to read-only evidence,
trusted dependencies and private writable HOME/scratch. Host IP network access
(including loopback) is blocked; model inference/auth stays in the parent.
Linux requires `/usr/bin/bwrap` >= 0.12.0 and working user namespaces; macOS
requires `/usr/bin/sandbox-exec`. Unavailable enforcement fails closed before
inference. There is no automatic unrestricted fallback.

This setting does **not** isolate builtin file tools, trusted Python callbacks,
validators, or native Codex/Claude providers. Builtin file tools still enforce
their own path grants. CLI workspace writes and external-service access are not
supported in required mode, even if builtin write paths are granted. Do not
grant HOME, `/`, or directories containing host Unix sockets as dependency/input
roots. See [the full setup and limitations](docs/cli-tools.md).

## Overview

Version 0.3.0 harness support: `tool_completed` events for successful `read_file`
now include `read_receipts` with path, SHA-256 of the bytes actually read, offset,
lines_read and line_count. Events contain no file text or raw tool arguments.
`RunPolicy(initial_tool="read_file", ...)` requests that granted function on the
first turn only; prose, runtime and host grants must all allow it. This cannot
elevate permissions or guarantee an endpoint honors tool choice. Consumers must
still validate the observed events. Defaults remain unchanged.

Execute neutral Prosaic commands and agents on OpenAI-compatible Chat Completions
or native Anthropic Messages endpoints. A Python library and CLI for small,
bounded tasks with streaming, tool calls, explicit filesystem permissions, and
structured results.

Version 0.4.0 hardening: explicit `initial_tool` selections now reject omitted,
substituted or additional first-turn tool calls before executing any of them.
Failure is `tool_choice_not_honored`, with reported token usage retained and no
automatic retry. This does not prove successful tool execution or correct tool
arguments; consumers must still validate receipts. Stream deltas are provisional
until the final result succeeds. Version 0.4.0 also adds opt-in acquisition prose
and the bounded execution fixes described below.

## First run: from installation to an answer

Follow these steps in order in one terminal. Commands below target macOS, Linux,
or Windows through WSL, using Bash or Zsh. You need an existing OpenAI-compatible
Chat Completions endpoint or an Anthropic API account: this runtime does **not**
install or host a model. The walkthrough below uses OpenAI-compatible endpoints;
see [native Anthropic setup](#native-anthropic-messages) for Claude.
Local and hosted endpoints both work; hosted calls may incur provider charges.

### 1. Check prerequisites

Install Git and Python 3.11 or newer (with pip and venv), then check:

```sh
git --version
python3 --version
```

Use a Python executable that reports 3.11+ throughout. Prosaic 0.3.0 and the
runtime are Python packages; Node.js and npm are not required.

### 2. Install

Start in a directory where you keep projects. This creates a fresh checkout and
an isolated Python environment; no sudo or global Python installation is needed:

```sh
git clone https://github.com/B3Cognition/prosaic-runtime.git
cd prosaic-runtime
git checkout v0.8.1
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
```

The package installs compatible `b3-prosaic` 0.4.x into the same environment.
Use the release tag after publication; older release tags retain historical docs.

For index installation after publication, create a fresh virtual environment or
container image and run `python -m pip install 'b3-prosaic-runtime==0.8.1'`.
Install the optional recorder with
`python -m pip install 'b3-prosaic-runtime-postgres==0.2.1'`. Never add renamed
packages to an environment containing legacy `prosaic`, `prosaic-runtime` or
`prosaic-runtime-postgres`: they share import paths. Preserve old environments
for historical reconstruction. PyPI's unrelated `prosaic` is not a dependency.
Before publication, install only the explicit candidate wheels from an audited
wheelhouse with `--no-index --find-links /path/to/qualified-wheelhouse`.

Confirm both commands are available:

```sh
prosaic --help
prosaic-runtime --help
```

For future terminals, enter the checkout and run `source .venv/bin/activate`
again. The Python package installs Prosaic, PyYAML and jsonschema automatically.

### 3. Open the ready-made examples

```sh
cd examples
```

Stay in this directory for the remaining commands. The checkout already contains:

```text
examples/
  .prosaic/subagents/summarizer.md   # prose without tools
  .prosaic/subagents/reviewer.md     # prose requesting read tools
  evidence/pilot.md                 # sample input for the reviewer
  prosaic-runtime.yaml              # no-tool endpoint configuration
  with-tools.yml                   # read-tool endpoint configuration
```

There are no files to create before the first run. The neutral Markdown prose
uses YAML frontmatter; runtime configuration uses YAML too.

### 4. Configure your endpoint and credentials

Open `prosaic-runtime.yaml` and `with-tools.yml` in your editor. In **both** files,
replace `base_url` and `model` with values supplied by your endpoint operator.
Keep the different `allowed_tools` values: `[]` for the first example and
`[read_file]` for the second.

The no-tool file looks like this:

```yaml
default_profile: small
allowed_tools: []
limits:
  timeout_s: 180
  max_tool_rounds: 8

routes:
  fast: small

profiles:
  small:
    base_url: http://127.0.0.1:8000/v1
    model: your-model
    api_key_env: LOCAL_LLM_API_KEY
    max_tokens: 2048
    features:
      streaming: true
      stream_options: true
```

The localhost URL and `your-model` are placeholders. Start your local model server
separately, or use your hosted endpoint's URL. Supply the API base (often ending
in `/v1`), **not** the full `/chat/completions` URL: the runtime appends that path.
Use the endpoint's exact model identifier. The tool example additionally needs
function-calling support.

If your endpoint requires a Bearer API key, enter it without putting it in shell
history or a configuration file:

```sh
export LOCAL_LLM_API_KEY="$(python -c 'import getpass; print(getpass.getpass("Endpoint API key: "))')"
```

For an unauthenticated local endpoint, leave that variable unset:

```sh
unset LOCAL_LLM_API_KEY
```

Run only the credential command appropriate for your endpoint. Do not commit
credentials. If the endpoint rejects usage streaming, set `stream_options: false`;
if it does not stream, set `streaming: false`. If it rejects `reasoning_effort`,
remove `effort: low` from `.prosaic/subagents/summarizer.md`.

Check setup before making a model request:

```sh
prosaic-runtime doctor --output text
```

This checks configuration, the Prosaic CLI, configured credentials and authenticated
model discovery. It does **not** run inference. A server without a `/models` route
produces a warning; authentication and connectivity failures produce a failed check.
Model discovery alone does not prove completion or tool support.

### 5. Run prose without tools

```sh
prosaic-runtime subagents/summarizer.md \
  --arguments 'S1: The pilot processed 120 requests. S2: Three requests timed out. S3: The cause has not been established.' \
  > summary.json
```

Check the result and print the answer:

```sh
python -c 'import json; r=json.load(open("summary.json")); print(r["stdout"]); print("exit_code:", r["exit_code"]); assert r["exit_code"] == 0, r["stderr"]'
```

An illustrative answer is:

```text
The pilot processed 120 requests (S1). Three requests timed out (S2).
The cause has not been established (S3).
exit_code: 0
```

Wording varies by model. `summary.json` contains a result object with
`event: "result"`, `exit_code`, `stdout`, `stderr`, usage, and metadata. No tool is offered
to this agent. Execution success does not establish factual correctness—compare
the answer against the supplied input.

### 6. Run prose with a read-only tool

```sh
prosaic-runtime subagents/reviewer.md \
  --config with-tools.yml \
  --arguments 'Review evidence/pilot.md. What do we know, and what remains unknown?' \
  --allow-tool read_file \
  --read-root ./evidence \
  > review.json
python -c 'import json; r=json.load(open("review.json")); print(r["stdout"]); print("exit_code:", r["exit_code"]); assert r["exit_code"] == 0, r["stderr"]'
```

Expect a read of `evidence/pilot.md`, followed by **Observed**, **Unknown**, and
**Next check** sections. Findings should cite that path and source IDs: 120 requests,
three timeouts, correctness not evaluated, timeout cause unknown, and no comparison
against another endpoint. A suggested next check is collecting server logs, not
claiming a diagnosis.

The tool must be requested by prose, allowed in configuration, **and** granted by
the invocation. Reads are limited to `evidence/`; this example cannot write files,
execute shell commands, or spawn agents.

### 7. Watch streaming events

```sh
prosaic-runtime subagents/reviewer.md \
  --config with-tools.yml \
  --arguments 'Review evidence/pilot.md.' \
  --allow-tool read_file \
  --read-root ./evidence \
  --events
```

This prints one JSON object per line: events followed by a final `result` object.
It is JSONL, not a single JSON document. Look for `text_delta` events when the
endpoint streams text, tool progress, and the final result's `exit_code: 0`.
Intermediate events are diagnostic; the final result is authoritative.

Without `--events`, status and a five-second elapsed-time heartbeat go to **stderr**,
including while the model is reasoning silently. They do not contaminate JSON or
text on stdout. Use `--quiet` to suppress progress; errors remain visible.

### 8. Run the repeatable live smoke test

```sh
prosaic-runtime smoke --live --config with-tools.yml
```

`--live` is required: this deliberately makes model requests and may incur charges.
The installed package includes the same neutral summarizer/reviewer prose and sample
evidence, so this works without the repository's examples directory when you supply
a configuration path. It uses `default_profile`, or the profile selected with
`--profile NAME`, for both probes.

The test creates a temporary directory with synthetic evidence and grants only
`read_file` within that directory for the reviewer. It never reads your project
files. This fixed test grant is independent of your configuration's `allowed_tools`;
`--live` opts into these two narrowly scoped probes, not general agent permissions.
Timeout and round limits still apply to each probe separately.

The JSON report separates `completion`, observed `streaming`, and `tool_execution`
for each example. Exit 0 requires both completions and an actual successful file read;
a model merely claiming it read the file is not enough. Streaming is reported separately
and is not required for success, because non-streaming endpoints are supported.
This is a capability smoke test, not a model-quality benchmark.

For a larger demonstration, see the [four-tier launch dossier example](examples/README.md#four-tier-launch-dossier-demo):
four neutral Markdown subagents, a synthetic 5,100-word dossier, YAML model-tier
routing, scoped read-only tools, and a runnable program with text or JSONL output.
Its documented live results distinguish successful execution from answer quality.

For a single no-tool inference check instead:

```sh
prosaic-runtime doctor --inference --timeout 180
```

Inference is never a fallback for a failed default doctor check: only the explicit
`--inference` flag enables that request.

For a canonical capability report, run
`prosaic-runtime conformance --config runtime.yml --profile small`. Its default
produces explicit unexecuted evidence with no Runtime construction or probes.
`--live` opts into a finite shared allowance for seven synthetic provider/tool
checks. Fixture results remain `fixture_passed` and cannot qualify a live model.
See [deterministic conformance](docs/conformance.md) for replay, profile/origin
binding, measured assertions, canonical serialization, and execution bounds.

### Troubleshooting

| Symptom | Check or fix |
| --- | --- |
| `python3` missing | Install the prerequisites from step 1; on some Linux systems, Python venv is a separate OS package. |
| `prosaic-runtime` not found | Activate `.venv` from the checkout root and rerun `python -m pip install .`. |
| `prosaic` not found | Activate `.venv` and repeat the pinned Python Prosaic installation in step 2. |
| No configuration or artifact found | Run from `examples/`; otherwise pass `--config` and `--source` explicitly. |
| YAML error | Use spaces for indentation and preserve the nested structure shown above. |
| Connection refused or timeout | Start the local endpoint or check its host, port, connectivity, and availability. |
| HTTP 401/403 | Check the API key, its permissions, and `api_key_env`; do not print the key in logs. |
| HTTP 404 or model error | Check the API base path and exact model ID; do not include `/chat/completions` in `base_url`. |
| Unsupported request field | Disable `stream_options` or `streaming`, or remove prose `effort`, as described in step 4. |
| Tool unavailable or read denied | Check all three grants and `--read-root`; use a function-calling model and a path inside `evidence/`. |
| Nonzero exit or incomplete output | Read the result's `stderr` and `metadata`; check token/round limits before retrying. Setup errors are printed to terminal stderr instead. |

The runtime exits nonzero on failure. Files such as `summary.json` can be empty
when configuration fails before execution; inspect the terminal error first.
There are no automatic retries or paid-model quality guarantees.

## Configuration and further examples

Configuration discovery checks `prosaic-runtime.yaml`, then `prosaic-runtime.yml`,
in the current directory. Use `--config path/to/config.yml` or pass a path to
`ProsaicRuntime.from_config()` to select another file. Only YAML/YML is supported.

See the [examples walkthrough](examples/README.md) for the neutral prose files,
permission details, and Python equivalents. To create your own agent, add a
Markdown file under `.prosaic/subagents/` with neutral YAML frontmatter and a body
using `{{args}}`, following the checked-in summarizer or reviewer.

## Plain-text output

For just the answer in the terminal, use `--output text`:

```sh
prosaic-runtime subagents/summarizer.md --arguments 'Text to summarize' --output text
```

JSON remains the default. `--events` emits JSONL and cannot be combined with
`--output`. On failures, text mode prints any partial answer to stdout, a diagnostic
to stderr, and exits nonzero. Do not treat a partial answer as a successful result.

## Python

The complete runnable program is [examples/run_examples.py](examples/run_examples.py).
From the checkout root, run `python examples/run_examples.py` after configuring the
example YAML files and setting your API-key environment variable. See its
[usage instructions](examples/README.md#runnable-python-sample) for endpoint/model
overrides and streaming events.

```python
from prosaic_runtime import ProsaicRuntime, RunPolicy

runtime = ProsaicRuntime.from_config("prosaic-runtime.yaml")
result = runtime.run(
    "subagents/summarizer.md",
    arguments="Text to summarize",
    policy=RunPolicy(timeout_s=60),
)
if result.exit_code:
    raise RuntimeError(result.stderr)
print(result.stdout)
```

An orchestrator can pass `ProsaicArtifact.from_inspection(inspect_json)` to avoid spawning Prosaic on every invocation. The snapshot includes artifact identity, neutral frontmatter, body, and bundled resources. Results identify the artifact by a SHA-256 digest. Bundle contents are appended as named context; external prose references are the caller's responsibility.

## Tools and authority

### Opt-in acquisition (v0.4.0+)

Pass `acquisition="subagents/acquire-pilot.md"` to `runtime.run()` to send a
short neutral Prosaic artifact first. The final artifact body, resources and
arguments are withheld until the explicitly selected native tool succeeds.
Both artifacts use one model, conversation, deadline and tool-round budget.
The acquisition declaration cannot broaden final prose/host/config grants;
it must declare `policy.initial_tool`. Its tier/effort must match the final
artifact or be omitted. Acquisition receives **no final arguments**; put the
needed path in its own prose. First-turn JSON response formatting is withheld
too, then restored for analysis. Subsequent tool selection is automatic.

A missing/substituted/extra first call blocks with `tool_choice_not_honored`;
a failed required tool blocks with `acquisition_failed`. Neither failure retries
nor switches to preloading. `acquisition_v1` advertises support. Existing calls
without this option retain their behavior. Acquisition requires Runtime v0.4.0+.

Run the complete staged and no-tool examples from this checkout:

```sh
python examples/run_acquisition.py --config examples/tokenproxy.yml --profile qwen
```

Set `TOKENPROXY_KEY` first. Use `--mode staged` or `--mode preloaded` to choose
explicitly, `--no-stream` for non-streaming, or another configured profile.
The preloaded mode reads a fixed example file on the host and supplies its text
to tool-free Markdown prose; it does not fabricate native tool receipts.
See [examples/README.md](examples/README.md#staged-acquisition-and-explicit-preloading).
This program demonstrates execution, not factual validation; the Harness
companion supplies schema and source/quote admission checks.

Tools are enabled only by the intersection of the artifact's declaration, configuration `allowed_tools`, and invocation `RunPolicy.allowed_tools`. Filesystem tools also require explicit roots or exact output paths. Missing and empty grants deny access. Prose and provider responses cannot expand the grant.

Supported declarations are omitted/empty/`none`, `read`, `write`, or a list of supported tool names in an inspection snapshot. `write` requests both read and write tools. `full` is rejected because this runtime does not implement arbitrary shell execution or delegation.

Read tools: `read_file`, `read_many_files`, `sha256_file`, `list_files`, `list_tree_with_sizes`, `grep_files`, `grep_context`. Write tools: `write_file`, `edit_file`.

For a read agent, set `tools: read` in its Prosaic frontmatter, `allowed_tools: [read_file]` in configuration, and invoke:

```sh
prosaic-runtime subagents/reviewer.md --allow-tool read_file --read-root ./evidence
```

Paths are relative to `--cwd` (the current directory by default) and must resolve inside it. `--write-path` grants one exact path; `--forbid-root` excludes a path and its descendants. An edit grant allows reading the target as part of replacing its contents. Resolved symlink escapes are rejected. These guards are for the provided file tools; they are not an OS sandbox against concurrent hostile filesystem changes.

The CLI provides no general-purpose shell, web browsing, recursive agents,
workflow scheduler, or application state writer. Explicitly trusted CLI manifests
can execute fixed application commands. They are unsandboxed in the default
`off` mode; `required` mode adds the CLI OS boundary described above.
Hosts retain their output validation, workflow decisions and publication rules.

## Limits and events

Default invocation limits: 120 seconds, 8 tool rounds, 256 KiB input. Endpoint defaults: 4,096 output tokens per turn and 8 MiB captured response per turn. Conversation requests are checked against the input limit before tool-loop turns; oversized responses fail. Old tool results can be compacted. Repeated identical tool rounds disable tools for a final answer.

YAML can override time and round defaults:

```yaml
limits:
  timeout_s: 180
  max_tool_rounds: 4
```

CLI `--timeout` and `--max-tool-rounds` override these values independently.
The Python API uses YAML limits when `policy` is omitted; an explicit `RunPolicy`
replaces them. The checked-in examples use 180 seconds to accommodate slower models.

`on_event` receives `started`, `text_delta`, `progress`, `text`, `tool_started`,
`tool_completed`, and `completed` dictionaries. Tool events contain `name`, `call_id`,
and `turn`; completion also contains `status` and `duration_ms`. They include denied
calls and omit arguments and file contents. The older diagnostic `progress` events
can contain paths or model text, so do not treat the entire event stream as redacted.
The final `Result` is authoritative. Event handlers execute synchronously; keep them
fast. The `cancelled` callback is checked between streaming reads, tool-loop operations,
and requests. In-flight blocking I/O is bounded by the HTTP timeout; cancellation is cooperative.
Staged invocations additionally emit `acquisition_completed` after the required
tool succeeds. If a later turn is cancelled, times out or exceeds an input/
response limit, already reported completed-turn usage is retained and marked
`usage_scope: reported_completed_turns`; it is not an estimate of an unfinished
request's usage.

Usage is reported when supplied by the endpoint. Cost estimation is unavailable in v0.2; `cost_usd = 0` is a legacy compatibility field, not a claim that inference was free. Check `metadata.cost_status`. No retries or model escalation occur automatically. An incomplete or truncated final response is unsuccessful.

## Native Anthropic Messages

Endpoint profiles accept `provider: anthropic` for native Messages requests.
Omitting `provider` retains `openai-compatible`; both can coexist in the same
configuration and use the existing `routes` by model tier. Configure an API base
such as `https://api.anthropic.com/v1`, without `/messages`, and a model available
to your account. Runtime appends `/messages` and sends `x-api-key` plus the
Anthropic API version header. Model discovery uses the same native credentials.

Start with [examples/anthropic.yml](examples/anthropic.yml). Replace
`your-anthropic-model`, set `ANTHROPIC_API_KEY` in your shell, and run from
`examples/`:

```sh
prosaic-runtime subagents/native-summarizer.md --config anthropic.yml \
  --arguments "Summarize this text." --output text
prosaic-runtime subagents/reviewer.md --config anthropic.yml \
  --arguments "Review evidence/pilot.md" --allow-tool read_file --read-root evidence
```

Use `temperature: null` to omit sampling parameters for models that do not
accept them. Native requests require a positive `max_tokens`. The historic
`summarizer.md` declares `effort: low`; use `native-summarizer.md` for a summary
without that control. This version explicitly rejects effort controls, JSON
mode, extended thinking, image inputs, and provider-hosted tools. It supports
text and Runtime-managed builtin, host-registered, and trusted CLI tools.
Runtime continues to enforce all existing grants, read receipts, first-tool
requirements, acquisition boundaries, cancellation, deadlines, and size limits.
Partial text events remain provisional, and incomplete streamed tool arguments
cannot execute. Provider failures are not automatically retried.

For SDK accounting, set the recorder's `provider_id='anthropic'`; a mismatch
with the routed endpoint fails before inference. For durable CLI accounting,
add `--accounting-provider anthropic` alongside the existing accounting options.
Each recorder serves its matching provider; use separate recorders for mixed
provider invocations. Ledger contracts remain unchanged.

Anthropic token totals include ordinary input, cache reads, cache creation, and
output. Cumulative stream usage snapshots are replaced rather than summed.
Missing details stay unknown; partial and conflicting evidence is retained.
The existing rate-card schema cannot represent cache-write pricing, nonstandard
service tiers, or regional pricing. Those categories and unfamiliar nonzero
usage categories remain unavailable for cost estimates. Raw native usage stays
in result metadata. See the official [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming)
and [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
documentation for native response semantics.

To explicitly request a live capability check, run
`prosaic-runtime smoke --live --config anthropic.yml` from `examples/`.
This makes paid API calls using bundled synthetic prose; automated tests use
local fixtures and require no Anthropic key.

## Echelon integration

The shared transport, stream parser, tool loop, compaction and filtering originated in Echelon. Echelon consumes the runtime through a compatibility adapter, retaining its own prompt policy, RE tools, `echelon_result` handling, journals, and delivery capabilities. The low-level `openai_compatible` module is an integration seam for that adapter, not the public agent-definition API. General consumers should use `ProsaicRuntime`.

## Development

Version 0.4.0 hardening: HTTP inference rejects redirects to protect endpoint
credentials. No-tool and tool-loop requests both obey the serialized byte bound.
Prosaic inspection timeouts return a failed `Result`. Public usage totals remain
unknown (`None`) when any completed turn lacks complete, nonnegative integer
usage. `token_usage_status` distinguishes unknown from reported totals; real
reported zero remains zero. Known partial sums are diagnostic
`reported_token_usage`, not a complete total for a consumer token budget.

For finite invocation allowances, set `RunPolicy(max_provider_requests=4,
max_tool_calls=2, max_reported_tokens=8192)`. Each field accepts a nonnegative
integer or `None` (legacy behavior); zero prevents dispatch in that unit.
Provider attempts are reserved before HTTP and accounting preparation. Tool
attempts include denied and malformed calls, with each call in a batch counted
once. Acquisition and follow-up turns share the same allowances.

With a reported-token cap, missing, invalid or partial totals and duplicate JSON
keys fail with `usage_unknown`; a terminal response above the cap fails with
`token_limit`.
A complete final response exactly at the cap succeeds, while further provider or
tool dispatch stops at equality. Returned text and already reported usage remain
available, including unknown totals and known partial sums. A failed provider
attempt keeps invocation usage unknown even after earlier turns reported complete
totals; its provider error remains available alongside the budget failure.
Accounting capture persists a completed response before budget admission. Token reports arrive
after a request, so one response can exceed the allowance; these controls do not
estimate an invoice ceiling or preempt a running callback. Endpoint `max_tokens`
keeps its provider meaning. Harness `max_calls` still counts workflow invocations.

The capability `invocation_budgets_v1` advertises support. When any allowance is
configured, `Result.metadata.invocation_budgets_v1` includes `provider_requests`,
`tool_calls`, `reported_tokens` and `usage_complete`. Exhausted request/tool
allowances return `provider_request_limit` or `tool_call_limit` in
`metadata.failure_reason`. Disabled allowances add no count metadata and retain
existing low-level consumer defaults.

```sh
python -m pip install -e '.[test]'
pytest
```

Tests cover extracted transport edge cases, tool denial, path containment, artifact loading, routing, cancellation, and local HTTP/SSE integration. The end-to-end Prosaic test requires the CLI on PATH; CI installs an explicit immutable Core candidate while index publication is pending. Tests do not require paid LLM access. Successful conformance tests do not establish model quality; evaluate each agent/model pair against its own acceptance criteria.

`tests/test_distribution_metadata.py` builds both distributions from `git archive`
(override the source with `PROSAIC_RUNTIME_RELEASE_REF`). The optional test extra
includes the backend required for no-isolation source-artifact verification.
Run `python -I scripts/wheel_smoke.py` with a fresh environment containing the
explicit Core, Runtime and recorder candidate wheels to check installed ownership,
CLI help, pure admission and documented recorder construction without model or DB calls.

Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE.md](NOTICE.md)
for extraction provenance and [LICENSE-MIT](LICENSE-MIT) for the retained notice
covering historically MIT-licensed code. Third-party components retain their own licenses.

## Structured JSON tool transport

For endpoints where the host deliberately chooses JSON tool requests, use the
shared [`StructuredToolLoop`](docs/structured-tools.md). It reuses registered
`CustomTool` contracts and bounded execution, with application-owned final-result
admission. Harness can drive each turn without embedding product rules in Runtime.
