Intent Petri

A Pi coding-agent extension that maintains a human-oriented intent and action map as a dynamically detailed Petri corridor.

Intent Petri is not a tool-call dashboard. It helps a person recover orientation during a long-running coding-agent session:

• STACK — the certain refinement chain from North Star to the current leaf;
• NOW — which committed leaf intent is active;
• WHY — why this action is active now;
• NEXT — committed successors and explicitly provisional future paths;
• WATCH — gates, plan-adjustment triggers, failures, or path tensions needing attention.

Current scope · V2.3 web hub

• one Pi main Agent and one Execution Token per session;
• schema-2, revisioned, atomic GraphPatch updates;
• arbitrarily nested hierarchical refinement with one executable active leaf;
• committed / provisional / directional planning semantics;
• branch-aware state and history reconstruction from verified Pi checkpoints;
• Mermaid TD projections plus atomic current.json / activity.json session exports;
• local multi-session web hub (intent-petri-hub) as the primary visualization;
• no Intent Petri status line, widget, modal, float pane, or Herdr terminal graph plugin inside Pi;
• extension version/source diagnostics and user-npm preference over duplicate project-local instances;
• a private append-only SQLite audit cache that is never branch authority.

Observed execution reconciliation, automatic Observer proposals, multi-Agent split/join, macOS Pet, and a native model Path Head remain out of scope.

Visualization · multi-session web hub

Frontend stack: Vite + React (hub-ui/), built to static assets and served by the local hub. Chosen for clear component boundaries and low ceremony while iterating on graph/list UX. Not TanStack Start / SvelteKit — this is a localhost single-page app, not a full-stack product.

Each Pi window writes its own projection under:

$XDG_STATE_HOME/intent-petri/sessions/<session-id>/active/

A singleton local hub process serves every session at once:

# from this repo (builds UI then ensures hub):
nub run hub

# or after UI is built:
nubx intent-petri-hub ensure --open

UI development (hot reload, proxies /api → hub):

nub run hub:ui:dev
# separate terminal: node bin/intent-petri-hub.mjs ensure

• List: http://127.0.0.1:7731/
• One session: http://127.0.0.1:7731/s/<session-id>
• Bind: 127.0.0.1 only
• Port: INTENT_PETRI_HUB_PORT (default 7731)
• Auto-open browser on session start: set INTENT_PETRI_HUB_OPEN=1

Inside Pi:

/intent-petri status
/intent-petri doctor
/intent-petri viewer   # ensures hub and opens the session URL

The extension starts the hub in the background on session_start (no browser focus steal by default). Terminal intent-petri-viewer remains available for offline ASCII dumps; it is no longer the primary UI. The Herdr graph plugin has been removed.

Development

This project uses nub:

nub install
nub run typecheck
nub run test
nub run package:check
nub run smoke:extension

Try the extension without installing it globally:

INTENT_PETRI_PREFER_LOCAL=1 pi --no-extensions -e .

/intent-petri doctor reports the exact loaded version, source path, and hub status. A repository copy loaded with -e . is suppressed when the user npm package is installed; set INTENT_PETRI_PREFER_LOCAL=1 only for intentional development smoke tests.

The Agent receives the schema-2 update_action_path tool. Current leaves and ancestor shells must be committed; future nodes may remain provisional or directional until evidence selects them.

Documentation

• Intent Petri V2: certain current stack, provisional future
• Why this project exists
• Conversation that started it
• Intent Petri design
• Archived telemetry-first design
• Pi extension API notes
• V2 implementation report
• V2 acceptance record
• Shipping Slice 1 implementation report