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):
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:
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:
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
# 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
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:
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.
Multi-agent coordination
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-shapedGenerateRequest, includingparams.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, preferCarRuntime.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 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
# 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 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.
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));
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 for the full text. Copyright © 2026 Parslee AI.
Metadata
Release files for car-runtime 0.61.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| car_runtime-0.61.2-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for car_runtime-0.61.2-cp39-abi3-win_amd64.whl |
| car_runtime-0.61.2-cp39-abi3-manylinux_2_28_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ x86-64 | Details for car_runtime-0.61.2-cp39-abi3-manylinux_2_28_x86_64.whl |
| car_runtime-0.61.2-cp39-abi3-macosx_15_0_arm64.whl | CPython 3.9 | abi3 | macOS 15.0+ ARM64 | Details for car_runtime-0.61.2-cp39-abi3-macosx_15_0_arm64.whl |
Total release size: 126.2 MB
Release files / car_runtime-0.61.2-cp39-abi3-win_amd64.whl
| Download URL | car_runtime-0.61.2-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 39.8 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
2b1a29f2ca70c48fbc093356890358c1df181bca5e8d7f65820bab79ad7276ef
|
|
BLAKE2b-256 checksum How to use checksums |
38ff50a87a9a57b6dd6367e3947a6eb271bf94796af90b97d44e532a8080c6f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / car_runtime-0.61.2-cp39-abi3-manylinux_2_28_x86_64.whl
| Download URL | car_runtime-0.61.2-cp39-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 49.7 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
88fc905bd6ebcebff7cc16d36f4bfde24f2ea296277d383f874e697d8666b629
|
|
BLAKE2b-256 checksum How to use checksums |
0f58a209db775d6d55fee5984c07e6bd14cd185afcd802b74a4e576cddcdbd8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / car_runtime-0.61.2-cp39-abi3-macosx_15_0_arm64.whl
| Download URL | car_runtime-0.61.2-cp39-abi3-macosx_15_0_arm64.whl |
|---|---|
| Size | 36.7 MB |
| Tags | CPython 3.9 abi3 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
95740c44c40793e2e91d7ae22bfcacc85d0f0e11256ec4cd0402054f56b6fc05
|
|
BLAKE2b-256 checksum How to use checksums |
9c824ff15aed07b7c673e845248b748fc975395192e7c448b17c3d3bdc71b161
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for car-runtime 0.61.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 3 files in this release have been uploaded with provenance metadata.
Attestation for car_runtime-0.61.2-cp39-abi3-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.