FE-1161: Petrinaut CLI

[kube]

🌟 What is the purpose of this PR?

Add an internal Petrinaut CLI for Python optimization services. The CLI loads and type-checks one model once, then runs repeated simulations with different parameters, initial markings, metrics, and seeds without restarting Node for every trial.

🔍 What does this change?

• Adds the private @hashintel/petrinaut-cli workspace package.
• Adds a reusable compilePetrinautModel facade in Petrinaut Core.
• Supports JSON Lines over stdio by default, with Unix sockets as an alternative.
• Exposes healthz, metadata, and run protocol methods.
• Supports uncolored token counts and explicit colored-token records.
• Adds a reusable Python stdio wrapper and Optuna integration examples.
• Includes example models covering parameters, metrics, and multiple color schemas.

🚀 Quick usage

# Build the CLI once
turbo --filter @hashintel/petrinaut-cli build

# Run the bundled SIR model through the Python stdio wrapper
python3 libs/@hashintel/petrinaut-cli/examples/python_stdio.py --demo

See the Python and Optuna integration guide and the parameter, metric, and colored-token examples.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• affected the execution graph, and the turbo.json's have been updated to reflect this

⚠️ Known issues

• A CLI process executes simulation requests serially.
• Metrics are evaluated on the final frame; full frame histories are not returned.

🛡 What tests cover this?

Core regression tests cover run-limit validation and generated seeds. The CLI is also verified through package type-checking, linting, building, and end-to-end protocol smoke tests.

• yarn workspace @hashintel/petrinaut-core test:unit src/simulation/compiled-model.test.ts
• yarn workspace @hashintel/petrinaut-cli lint:tsc
• yarn workspace @hashintel/petrinaut-cli lint:eslint
• yarn workspace @hashintel/petrinaut-cli build
• Python stdio SIR demo
• Unix-socket metadata and run smoke test
• Colored-token and multi-color model smoke tests

❓ How to test this?

1. Build the CLI:

   turbo --filter @hashintel/petrinaut-cli build

2. Run the Python stdio demo:

   python3 libs/@hashintel/petrinaut-cli/examples/python_stdio.py --demo

3. Confirm the result contains seed 4242, final place token counts, and the Infected Fraction metric.
4. Optionally follow libs/@hashintel/petrinaut-cli/MODEL_EXAMPLES.md to try colored-token models.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jul 15, 2026 12:51pm
petrinaut	Ready	Preview	Jul 15, 2026 12:51pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jul 15, 2026 12:51pm

[cursor]

PR Summary

Medium Risk
New long-lived CLI and protocol surface on top of the simulation engine; mistakes in run parsing or compilation could affect optimization jobs, but there is no HTTP/auth exposure and the package is private with solid unit and transport tests.

Overview
Introduces the private @hashintel/petrinaut-cli package so scripts and Python optimization loops can run one Petrinaut model many times without restarting Node. petrinaut serve --model <path> loads and compiles the model once (via a new @hashintel/petrinaut-core/compiled-model export), then serves healthz, metadata, and run over JSON Lines on stdio (default) or a Unix socket.

run accepts parameters, initial markings (integer counts or colored token objects), metrics, maxSteps / maxTime, dt, and seed, and returns summary results (final-frame metrics, completion reason, root-place token counts). Request parsing validates markings and resolves parameter/place keys by id, variable name, or display name.

Also adds bundled example models, examples/python_stdio.py (stdlib PetrinautClient), and integration docs for Optuna-style workflows.

^{Reviewed by Cursor Bugbot for commit 47a4f11. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1d89519. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 37 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 8 comments.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.