Metadata-Version: 2.4
Name: car-runtime
Version: 0.63.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: pytest>=7.0 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Common Agent Runtime — Python bindings for deterministic AI agent execution
Keywords: ai,agent,runtime,llm,inference
Author-email: Parslee AI <hello@parslee.ai>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Parslee-ai/car-releases
Project-URL: Issues, https://github.com/Parslee-ai/car-releases/issues
Project-URL: Repository, https://github.com/Parslee-ai/car-releases

# car-runtime (Python)

Python bindings for **Common Agent Runtime** (CAR) — a deterministic execution
layer for AI agents. Models propose; the runtime validates and executes.

As of v0.8, this package is a **thin daemon client**: every method
proxies to a singleton `car-server` daemon over WebSocket. Inference,
the per-session memory graph, and tool dispatch all live on the
daemon side. Start `car-server` once per host before using the
bindings (`car-server` ships in the same wheel; see "Start the
daemon" below).

Pre-built wheels (abi3, Python 3.9+) for:
- `macosx_15_0_arm64` — macOS 15+ on Apple Silicon (Intel Macs dropped — see CHANGELOG)
- `manylinux_2_17_x86_64`, `manylinux_2_28_aarch64`

Building from source on macOS: set `MACOSX_DEPLOYMENT_TARGET=15.0` when
invoking `maturin build`. MLX's bundled Metal shaders don't compile against
the default 11.0 target, and our release wheels target 15.0 because the
compiled extension pulls in libc++ symbols (notably
`std::exception_ptr::__from_native_exception_pointer`) that only exist on
macOS 15+. A lower target produces a wheel whose tag doesn't match what the
binary actually requires at `dlopen` time.

## Install

From a release wheel (substitute the current version for `X.Y.Z`):

```bash
pip install https://github.com/Parslee-ai/car-releases/releases/download/vX.Y.Z/car_runtime-X.Y.Z-cp39-abi3-macosx_15_0_arm64.whl
```

Or build from source:

```bash
pip install maturin
cd car-rs/crates/car-ffi-pyo3
maturin develop --release
```

The import name is `car_runtime` (matching the PyPI package name).

## Call the daemon

The same five-line Node example appears in every package landing page and in the
Node scaffold so it cannot drift from the agent-facing skill:

```javascript
async function daemonCallExample() {
// BEGIN CALL_DAEMON_FIVE_LINES
  const { CarRuntime } = (await import('car-runtime')).default;
  const car = new CarRuntime();
  car.registerDaemonHandler('tools.execute', async () => JSON.stringify({ ok: true }));
  const methods = JSON.parse(await car.daemonCall('capabilities.list', '{}'));
  return { car, methods, agents: JSON.parse(await car.agentsList('{}')) };
// END CALL_DAEMON_FIVE_LINES
}
```

Python uses the equivalent `daemon_call`, `agents_list`, and
`register_daemon_handler` names; the complete runnable Python block is in the
`car-capabilities` skill.

## Start the daemon

```bash
# The wheel does not contain car-server, and `python -m car_runtime.server`
# never existed. Use the one from the npm package, the platform tarball, or
# CAR Host.app. Default port 9100; auth on by default. Foreground (Ctrl-C to
# stop); needs Node.js 18+ and works from any directory:
npx --package=car-runtime car-server --port 9100

# Or background:
npx --package=car-runtime car-server --port 9100 &

# Override the URL the bindings use:
export CAR_DAEMON_URL=ws://127.0.0.1:9100
```

On macOS the SwiftUI menubar host (`CAR Host.app`) launches the
daemon for you. Install it once from the `.pkg` installer on the
latest GitHub release; from then on it supervises `car-server` and
keeps itself up to date via Sparkle.

## Quickstart

```python
import json
from car_runtime import CarRuntime, verify

rt = CarRuntime()   # lazy-connects to ws://127.0.0.1:9100/

# Tools + policies — proxied to the daemon's per-session runtime
# and persist for the lifetime of this CarRuntime's WS connection.
rt.register_tool("shell")
rt.register_policy(
    "no_rm",
    "deny_tool_param",
    target="shell",
    key="command",
    pattern="rm -rf",
)

# Ground with facts (proxied to the daemon's per-session memgine).
rt.add_fact("project_language", "Python", "pattern")

# Static verification — runs on the daemon side, no model needed.
proposal = json.dumps({
    "actions": [{
        "id": "a1",
        "type": "tool_call",
        "tool": "shell",
        "parameters": {"command": "ls"},
        "dependencies": [],
    }],
})

check = json.loads(rt.verify_proposal(proposal))
if not check["valid"]:
    raise RuntimeError(f"invalid proposal: {check['issues']}")

rt.close()  # disconnect() is an alias; a later call reconnects lazily

# For a complete agent cycle, use the packaged helper shown below. It wires
# register_tool_handler + submit_proposal for you.
```

## Packaged agent loop

Do not copy a harness into each agent. Import the versioned loop and keep the
project entry file declarative:

```python
from car_runtime.agent_loop import main

main({
    "agent_name": "Lookup Agent",
    "identity": "Use lookup before answering; never guess.",
    "tool_schemas": [{
        "name": "lookup", "description": "Look up one key",
        "parameters": {"type": "object", "properties": {"key": {"type": "string"}},
                       "required": ["key"]},
    }],
    "tools": {"lookup": lambda p: {"key": p["key"], "value": lookup(p["key"])}},
    "policies": [],
    "max_turns": 8,
})
```

`run_agent(config, goal)` is also exported for embedding and tests. Put one
long-lived runtime in `config["runtime"]` to reuse its daemon connection across
runs; otherwise the loop creates and closes a runtime for each call. The loop
registers its tools and policies once per daemon session: when that runtime is
closed and reused, or reconnects after a daemon restart (`connection_epoch()`
changes), the next run or `serve_chat` chat turn registers them again on the
new session.
`serve_chat(config)` uses the same option and returns the runtime it serves on.
Its `AgentOutcome["run_id"]` is the durable key accepted by `runs_get_trace`; it is
`None` when an older daemon has no `runs.*` surface or did not acknowledge the
start. `run_chat_turn` keeps returning bare text by default; pass
`include_run_id=True` to receive `{"text": str, "run_id": str | None}`. It
registers its tool schemas and `config["policies"]` on the runtime, so
tool-using turns need no earlier `register_tool_handler` or `serve_chat` call.
The helpers pass their own tool handler to each `execute_proposal` call, so a
handler you registered with `register_tool_handler` stays in place.
`main(config)` provides `--task`, `--json`, and `--serve`. The loop adds
`finish`, statically verifies every proposal before `submit_proposal`, preserves
tool-call/result IDs, honors per-schema `timeoutMs`, traces task and chat runs,
and uses request-shaped inference with prompt-cache breakpoints. Each inference
is recorded before its requested actions with assistant text, normalized
call IDs, model id, token usage, and duration; `runs_get_trace` returns those
model turns interleaved with action turns. Recording is best-effort, so an older
daemon without the method still runs the agent. Importing
`car_runtime.agent_loop` has no daemon side effect; running it requires
`car-server`. The wheel includes `car_runtime/agent_loop.pyi`, while the
top-level `car_runtime.pyi` advertises the submodule.

## Streaming inference

Streaming is WebSocket-only. Connect to `car-server`, call the
`infer_stream` JSON-RPC method, and consume `inference.stream.event`
notifications. `CarRuntime.infer_stream` remains only as an ABI-compatibility
stub; it always raises `RuntimeError` and never invokes its callback. See
[the streaming cookbook](../../../docs/cookbook/09-streaming-inference.md).

## Multi-agent coordination

```python
import json
from car_runtime import register_agent_runner, run_swarm

def agent_fn(spec_json: str, task: str) -> str:
    spec = json.loads(spec_json)
    # Call your LLM of choice, returning an AgentOutput JSON.
    return json.dumps({"name": spec["name"], "response": "...", "tool_calls": []})

# Option A: register once, then call run_* without passing agent_fn each time.
register_agent_runner(agent_fn)
result = run_swarm(
    "parallel",
    json.dumps([
        {"name": "researcher", "role": "gather facts", "model": "gpt-5"},
        {"name": "writer",     "role": "compose summary", "model": "claude-opus-4-7"},
    ]),
    "summarize the CAR paper",
)

# Option B: pass agent_fn per call.
result = run_swarm("parallel", agents_json, task, agent_fn=agent_fn)
```

## API surface

The runtime (`CarRuntime`) exposes:

- **State:** `state_set`, `state_get`, `state_exists`, `state_snapshot`, `state_keys`
- **Memory:** `add_fact`, `query_facts`, `fact_count`, `build_context`,
  `build_context_fast`, `persist_memory`, `load_memory`, `consolidate`
- **Skills:** `ingest_skill`, `find_skill`, `report_outcome`, `distill_skills`,
  `ingest_distilled_skills`, `list_skills`, `domains_needing_evolution`,
  `repair_skill`, `evolve_skills`
- **Tools + policies:** `register_tool`, `register_agent_basics`,
  `register_policy`, `set_replan_config`
- **Inference:** `infer`, `infer_tracked`, `infer_tracked_with_request`
  (request-shaped `GenerateRequest`, including `params.strict_model`),
  `infer_with_context`, `infer_with_context_tracked`, `embed`, `rerank`, `classify`,
  `prepare_speech_runtime`, `transcribe`, `synthesize`
- **Models:** `list_models`, `pull_model`, `remove_model`,
  `list_models_unified`, `register_model`, `route_model`, `model_stats`
- **Execution:** `event_count`, `verify_proposal`, `execute_proposal`

Module-level standalone functions:

- **Verification:** `verify`, `simulate`, `optimize`, `equivalent`
- **Stateless execute:** `execute` (creates a fresh Runtime; for long-lived
  use, prefer `CarRuntime.execute_proposal`)
- **Multi-agent:** `register_agent_runner`, `run_swarm`, `run_pipeline`,
  `run_supervisor`, `run_map_reduce`, `run_vote`
- **Scheduler:** `create_task`, `run_task`, `run_task_loop`, `ensure_dream_task`
- **Planner:** `rank_proposals`

Compatibility-only method: `infer_stream` (always raises; use WebSocket).

Structured returns are JSON-encoded strings — `json.loads` them on the Python
side. This keeps the FFI surface stable across binding and protocol changes.

## Type stubs

The wheel ships the canonical [`car_runtime.pyi`](./car_runtime.pyi) plus a
byte-identical package mirror (`car_runtime/__init__.pyi`) and package-local
`py.typed` marker (PEP 561). `mypy`, `pyright`, Pylance, and similar tools pick
up the full native method signatures and the typed `agent_loop` submodule — no
extra install needed.

If you're editing the source tree, update `crates/car-ffi-pyo3/car_runtime.pyi`
and copy it to `car_runtime/__init__.pyi`. `scripts/check-ffi-parity.sh` rejects
drift between them and continues to check the canonical stub against
`src/lib.rs`. See `CLAUDE.md` for the FFI-bindings parity rule.

## Offline reference docs

The wheel also ships a `car_runtime_docs/` directory alongside the compiled
extension (find it with `python3 -c "import car_runtime, pathlib;
print(pathlib.Path(car_runtime.__file__).parent / 'car_runtime_docs')"` if
your install layout differs) — `SPEC.md`, `GUIDE.md`, `CLI.md`, `ASSISTANT.md`,
`MCP.md`, `agent-ir-spec.md`. So an agent with `pip install car-runtime` and no
network access can still read how the `car` CLI, the flagship assistant's
tools, and `car-mcp` actually work, not just the typed surface above.
`car_runtime_docs/websocket-protocol.md` is a short pointer, not the full
reference (~510KB, deliberately not bundled) — read the real thing at
https://car.parslee.ai/websocket-protocol.md.

## Development

```bash
# Install dev deps.
pip install maturin pytest

# Build and install in editable mode.
cd car-rs/crates/car-ffi-pyo3
maturin develop

# Run the smoke tests.
pytest tests/ -v
```

## Architecture

This package is a thin PyO3 client to the singleton `car-server`
daemon over WebSocket — `CarRuntime()` lazy-connects, every method
proxies through the JSON-RPC dispatcher, and the daemon owns
inference / memory / tool dispatch / per-session state.

Pre-v0.8 (the `RuntimeMode::Embedded` path) the wheel hosted an
in-process `car-engine` + `car-memgine` and ran inference under
`py.allow_threads(...)`. That path was retired to close the
multi-tenant overcommit hazard CAR-issue #139 was opened for —
two FFI consumers in different processes each spawned a fresh
admission semaphore + model cache, and concurrent runs could
overwhelm the host. v0.8 takes the harder path: one daemon per
host, every client attaches.

See the [car-releases README](https://github.com/Parslee-ai/car-releases) for
the broader CAR architecture.

## Long-running packaged task loops

`openai-codex/gpt-6.1-sol:high` and `openai-codex/gpt-6.1-sol:medium`
run on CAR's ChatGPT subscription sign-in (`car auth login --provider openai-codex`),
without an OpenAI API key. Both catalog rows have a 500,000-token context window;
the suffix selects high or medium reasoning effort.

`runAgent` (Node) / `run_agent` (Python) supports these task-only settings:

| Node | Python | Meaning |
| --- | --- | --- |
| `terminalTools` | `terminal_tools` | Array of tool schemas (`name`, `description`, `parameters`) plus a host `validate(arguments)` function. Exactly `true`/`True` accepts; all other results refuse. Nonempty strings give the reason; empty strings/other values use a default. Async validators are awaited; exceptions use their message, or the default if empty. |
| `requireTerminal` | `require_terminal` | Require a terminal call even with the default `finish` tool. Defaults off; declared terminal tools imply it. One text-only turn receives a reminder; a second ends as `no_terminal`. |
| `noProgressGuard` | `no_progress_guard` | Defaults on. Set false for intentional polling. Cumulative repeated signatures earn one nudge at repeat 3 and stop at repeat 6 as `stalled`; eight turns without mutation earn the same single nudge. A new successful mutating signature resets the guard. |
| `priorMessages` | `prior_messages` | Resume a JSON transcript. Prior system messages are removed in favor of the current identity. Unanswered calls are closed with an explanatory tool result without executing them. The new goal follows the prior messages. The guard starts fresh. |
| `maxTurns` | `max_turns` | Task default 8. Node: **0** or `Infinity` removes the cap. Python: **0** or `float('inf')` removes the cap. A positive finite cap ends as `timeout` when reached. |
| `maxTokens` | `max_tokens` | Defaults to **4096**, also for chat turns. |

Declared terminal tools replace `finish` in both the offered schemas and the
system instruction. A refusal becomes a tool result for the model to repair.
Two terminal calls in one turn are both refused. Ordinary tools execute first;
a terminal call alongside them is accepted only when all succeeded. In runs with terminal tools, independent ordinary tools continue after a sibling fails so terminal eligibility can be evaluated. Without terminal tools, the runtime's normal abort behavior stops the rest of the turn. A successful ending returns
`status: "success"` and `terminal_tool: {name, arguments}`.

Every returned task outcome includes `transcript`, an ordered JSON message array
with assistant tool calls and their results. Store it and pass it as prior
messages on the next invocation, including across Node and Python. Transcript
and `run_id` are return metadata added after `runs.complete`; the daemon run
record does not contain the transcript. Terminal identity is also in outcome
evidence. `stalled` and `no_terminal` are real daemon outcome statuses and both
cause the task CLI's `main` to exit with code **1**, like `failure`. Other endings remain
`done`, `timeout`, `success`, `partial_success`, and `give_up`.

A successful tool whose schema declares `mutating: true`, or whose name is
`write_file` or `edit_file`, resets the guard only for a new signature. Failed
mutations and identical writes do not reset it. Distinct read calls never hit
the repeat stop. With no custom terminal tools, the legacy `finish` and `done`
paths remain. Chat retains its existing finish behavior and has no guard.

### Terminal tools: complete runnable configurations

Use the released package entry shown here (Node: save as an `.mjs` file; Python: save as `.py`). A daemon must be available.

```javascript
import { runAgent } from 'car-runtime/agent-loop';
const validate = args => args.reason.trim() ? true : 'Give a concrete reason.';
const terminalTools = ['retry_commit', 'request_recut', 'hand_off'].map(name => ({
  name, description: 'End this investigation.',
  parameters: { type: 'object', properties: { reason: { type: 'string' } }, required: ['reason'] },
  validate,
}));
const outcome = await runAgent({ agentName: 'incident-owner', identity: 'Investigate; end with a terminal tool.',
  terminalTools, maxTokens: 4096, maxTurns: 0, noProgressGuard: true }, 'Investigate the failing check.');
console.log(JSON.stringify(outcome));
```

```python
from car_runtime.agent_loop import run_agent

def validate(args):
    return True if args['reason'].strip() else 'Give a concrete reason.'

terminal_tools = [dict(name=name, description='End this investigation.',
    parameters={'type': 'object', 'properties': {'reason': {'type': 'string'}}, 'required': ['reason']},
    validate=validate) for name in ['retry_commit', 'request_recut', 'hand_off']]
outcome = run_agent(dict(agent_name='incident-owner', identity='Investigate; end with a terminal tool.',
    terminal_tools=terminal_tools, max_tokens=4096, max_turns=0, no_progress_guard=True),
    'Investigate the failing check.')
print(outcome)
```

The runtime checks the declared argument schema before invoking the host validator.
The validator receives only the decoded argument object. Exactly `true` (`True` in Python)
accepts; every other result refuses. A string supplies the refusal reason; an empty string
or other value uses a default reason. Async validators are awaited. A thrown error's
message is the refusal reason (the default if empty). A validator which never returns hangs the run, just as
a hung tool does; supply your own bounded validator when it performs I/O.

Terminal tools replace `finish`; declaring `finish` beside them, duplicate names, malformed
prior messages, or a negative/NaN cap is an error before `runs.start`. With no terminal
tools, `requireTerminal` (`require_terminal`) makes the built-in `finish` the required
terminal. Without that option, a text answer still ends as `done`.

`terminal_tool: {name, arguments}` appears only on `success`. `main` exits with code **1** for `failure`, `stalled`, and `no_terminal`, and **0** for other returned statuses (`success`, `partial_success`, `give_up`, `timeout`, `done`).
The no-progress guard counts a repeat whenever a whole turn's sorted tool-name/argument
signature has occurred earlier since the last reset, not only on consecutive turns.
The third repeat nudges and the sixth stops; eight turns without a new successful
state-changing signature only nudges. Python schemas support `mutating: True`, matching
Node's `mutating: true`; `write_file` and `edit_file` are also state-changing. Failed
calls do not reset the guard. `noProgressGuard: false` / `no_progress_guard=False`
disables it for one run.

For task runs, the per-call `maxTurns` option / Python `max_turns` argument overrides the
config value when non-null. Null or omission uses the config; a null/omitted config
uses 8. Zero or positive infinity lifts the task cap. Chat retains its existing cap
semantics. `maxTokens` / `max_tokens` defaults to 4096.

Resume with `priorMessages` / `prior_messages`, a JSON list of messages shaped as:
`{role: "user" | "assistant" | "system", content: "text"}`; assistant messages may carry
`tool_calls: [{id: "call-id", name: "tool-name", arguments: {...}}]`. A tool result is
`{role: "tool_result", tool_use_id: "call-id", content: "JSON text"}`. `tool_calls` cannot
be null, and each call needs its id and an `arguments` JSON object. Absent
`arguments`, null, arrays, and strings are refused before `runs.start`. Node validates
the JSON round trip, so values that serialize to strings are also refused. Old system
messages are replaced by the current one. Do not trim a transcript ending on a terminal call: answered calls are retained;
unanswered calls are closed with an explanatory tool result without rerunning handlers.
Every ending returns `transcript`; it is never sent to `runs.complete`.



Task cap lifting (`0` or positive infinity) applies to `runAgent` / `run_agent`.
In chat, `maxTurns: 0` / `max_turns=0` performs zero model turns; it does not
remove the chat budget. Python chat rejects infinity before `runs.start`.
A refused task configuration throws an Error in Node or raises ValueError in
Python, rather than returning an outcome. A terminal name cannot collide with
an ordinary tool name. Node keeps main's missing-identity and numeric-string
cap behavior.

Python async validators are awaited with `asyncio.run` when no event loop is
running on the callback thread. If that thread already has an event loop, a
separate thread runs and awaits the coroutine; the synchronous caller waits
for its result. A validator that never returns therefore still hangs its run.
The validator receives a deep copy: mutations cannot rewrite the transcript or
the arguments checked and recorded by CAR. The daemon's full parameter check
runs before dispatch to that validator, including enum, nested, array and
additional-property constraints. Schema refusals count as failed tool calls.
Each task run restores its declared terminal schemas, including A/B/A reuse.

The initial occurrence is not a repeat: for one identical signature, the third
repeat is its fourth occurrence and the sixth repeat is its seventh occurrence.
Repeats of any previously seen whole-turn signature accumulate between resets;
for example A, B, A, B, A reaches the third repeat on turn five.
A typed success also includes an evidence entry shaped as
`{kind: "tool_result", description: "terminal_name", data: { /* original arguments */ }}`.

## License

Free for any use including commercial; free to redistribute unmodified.
Modification, reverse engineering, and derivative works are not permitted.
See [`LICENSE`](./LICENSE) for the full text. Copyright © 2026 Parslee AI.

