FE-717: Prepare Petrinaut for AI assistant by CiaranMn · Pull Request #8721 · hashintel/hash

CiaranMn · 2026-05-15T18:34:49Z

🌟 What is the purpose of this PR?

This is preparatory work for adding an AI assistant, which will need access to tools to mutate the Petri net.

The PR:

Moves the net mutation functions from the react context to Petrinaut core
Adds them as methods to the instance. IN NEXT PR: nest these under an actions property on the instance (e.g. instance.actions.addType).
Adds Zod schemas with descriptions for all of them, and generates AI tools from them.
Adds schema validation to the instance methods.
Changes to make the input parameters to the functions compatible with AI tool calling:
- Changes the updateX functions which take a callback to instead take an update object
- Changes all functions to take a single object, instead of positional values (e.g. updateX(id, update) becomes updateX({ id, update }). This has caused changes to core. While I was touching these functions in core I just took their typing from the mutation functions in core rather than having them all repeat the interface, but can revert it if there was a reason for how it was before.
- Adds a few more mutation methods to allow for mutating nested non-primitive values (e.g. arc arrays).

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:

are internal and do not require a docs change

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

The changes in this PR:

do not affect the execution graph

🐾 Next steps

Add the AI assistant UI and demo website server endpoint.

🛡 What tests cover this?

A few unit tests added.

❓ How to test this?

Check that Petrinaut still works.

… prepare actions for AI assistance

vercel · 2026-05-15T18:34:56Z

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	May 15, 2026 6:43pm
petrinaut	Ready	Preview, Comment	May 15, 2026 6:43pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	May 15, 2026 6:43pm

cursor · 2026-05-15T18:34:57Z

PR Summary

Medium Risk
Medium risk because it refactors all SDCPN mutation call sites to new validated, schema-driven action APIs and adds new cascading delete/arc/type-element mutations, which could subtly change editor behavior if any inputs or validation differ from prior logic.

Overview
Moves all SDCPN mutation logic out of the React MutationProvider into core via new createPetrinautActions, and mixes these validated action methods directly into the Petrinaut instance.

Adds a comprehensive set of Zod schemas (with descriptions) for every mutation in action-schemas.ts plus new entity schemas for places/transitions/types/equations/parameters/scenarios/metrics, then builds AI-facing tool metadata in core/ai.ts (including a getLatestNetDefinition tool name and a shared petrinautAiPrompt).

Updates the editor/UI to call mutations with single-object inputs (replacing callback/positional mutation APIs), introduces granular actions like updateArcPlace and type element add/update/move/remove, and expands tests to cover validation, readonly no-ops, cascading deletes, and relaxed import/clipboard defaults.

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

augmentcode · 2026-05-15T18:38:29Z

🤖 Augment PR Summary

Summary: Preparatory refactor to make Petrinaut’s SDCPN mutations callable as validated “actions”, enabling future AI-assistant tool calling.

Changes:

Moved net mutation helpers out of React context into core as createPetrinautActions() and mixed them into the Petrinaut instance.
Introduced Zod v4 schemas for core entities plus action input schemas with rich descriptions.
Added schema-based input validation and updated mutation APIs to accept single-object payloads (AI-tool friendly), replacing callback-based updaters.
Added granular mutation actions for arcs and type elements (endpoint/weight/type updates, element CRUD/reorder, bulk deletes, position commits).
Added AI exports: generated tool metadata from schemas, a callback map backed by the Petrinaut instance, and a Petrinaut-specific prompt bundle.
Updated clipboard/file-format parsers to reuse current schemas while preserving relaxed import defaults; added tests.
Refactored UI/editor call sites to the new action signatures and expanded unit tests for correctness/validation.

Technical Notes: Action inputs use z.strictObject to reject unknown keys; validation is applied both at input boundaries and after in-place draft mutation.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 1 suggestion posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-05-15T18:40:44Z

+        }
+        for (const equation of sdcpn.differentialEquations) {
+          if (equation.colorId === parsedTypeId) {
+            equation.colorId = "";


libs/@hashintel/petrinaut/src/core/actions.ts:~320 — removeType assigns equation.colorId = "", but differentialEquationSchema requires a non-empty idSchema for colorId, so this can leave the document in an invalid state where later equation updates/validations will throw and the equation becomes effectively uneditable.

Severity: high

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode

Review completed. 1 suggestion posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-05-15T18:41:10Z

  });

+  if (typeof window !== "undefined") {
+    window.addEventListener("beforeunload", () => {


libs/@hashintel/petrinaut/src/core/instance.ts:66 — This beforeunload cleanup doesn’t cover instance.dispose() (and the handler itself isn’t removed), so doc subscriptions/listeners can still accumulate in long-lived pages or if multiple Petrinaut instances are created/destroyed.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

+        (item) => item.elementId === input.elementId,
+      );
+      if (element) {
+        Object.assign(element, clone(input.update));


cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

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

cursor · 2026-05-15T18:48:31Z

-  type: z.enum(["real", "integer", "boolean", "ratio"]),
+  ...currentScenarioParameterSchema.shape,
  identifier: z.string(),
-  default: z.number(),


File format rejects equations with cleared colorId

High Severity

The differentialEquationSchema in both file-format and clipboard types now inherits colorId: idSchema (which enforces min(1)) from currentDifferentialEquationSchema.shape, but only overrides id and name to be more permissive. The old schema used plain z.string() for colorId. Since removeType and deleteItemsByIds actively set equation.colorId = "" when a referenced type is removed, any file exported after that operation cannot be re-imported, and clipboard paste of such equations fails.

Additional Locations (1)

libs/@hashintel/petrinaut/src/core/clipboard/types.ts#L60-L65

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

cursor · 2026-05-15T18:48:31Z

-      existingParameter.name = event.target.value;
+    updateParameter({
+      parameterId: parameter.id,
+      update: { name: event.target.value },


Validated mutations throw on intermediate onChange keystrokes

Medium Severity

The onChange handlers for parameter name, type name, and differential equation name call mutation actions directly on every keystroke. The new actions validate through displayNameSchema, which rejects empty strings. When a user clears or selects-all-and-retypes the field, the validation throws an uncaught error, preventing the update and causing an input desync. The old callback-based mutations had no such validation. Other properties (e.g., place name) correctly use local state with onBlur validation.

Additional Locations (2)

libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/differential-equation-properties/subviews/main.tsx#L138-L142

libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/type-properties/subviews/main.tsx#L246-L250

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

CiaranMn added 3 commits May 15, 2026 19:11

move mutation actions from MutationProvider to core. add Zod schemas.…

7b6b600

… prepare actions for AI assistance

core cleanup / type changes

0f5a57d

untrack file

5c94a8d

graphite-app Bot assigned CiaranMn May 15, 2026

github-actions Bot added area/libs Relates to first-party libraries/crates/packages (area) type/eng > frontend Owned by the @frontend team area/apps > hash.design Affects the `hash.design` design site (app) labels May 15, 2026

remove stray change

a2406d2

vercel Bot deployed to Preview – petrinaut May 15, 2026 18:38 View deployment

augmentcode Bot reviewed May 15, 2026

View reviewed changes

github-advanced-security AI found potential problems May 15, 2026

View reviewed changes

Comment thread ...@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/properties-panel.stories.tsx

(item) => item.elementId === input.elementId,

);

if (element) {

Object.assign(element, clone(input.update));

vercel Bot deployed to Preview – hash May 15, 2026 18:43 View deployment

cursor Bot reviewed May 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FE-717: Prepare Petrinaut for AI assistant#8721

FE-717: Prepare Petrinaut for AI assistant#8721
CiaranMn wants to merge 4 commits into
mainfrom
cm/prepare-petrinaut-for-ai-actions

CiaranMn commented May 15, 2026

Uh oh!

vercel Bot commented May 15, 2026 •

edited

Loading

Uh oh!

cursor Bot commented May 15, 2026 •

edited

Loading

Uh oh!

augmentcode Bot commented May 15, 2026 •

edited

Loading

Uh oh!

augmentcode Bot left a comment

Uh oh!

augmentcode Bot May 15, 2026 •

edited

Loading

Uh oh!

augmentcode Bot left a comment

Uh oh!

augmentcode Bot May 15, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot May 15, 2026

Uh oh!

cursor Bot May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Conversation

CiaranMn commented May 15, 2026

🌟 What is the purpose of this PR?

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

📜 Does this require a change to the docs?

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

🐾 Next steps

🛡 What tests cover this?

❓ How to test this?

Uh oh!

vercel Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

augmentcode Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

augmentcode Bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 15, 2026

Choose a reason for hiding this comment

File format rejects equations with cleared colorId

Uh oh!

cursor Bot May 15, 2026

Choose a reason for hiding this comment

Validated mutations throw on intermediate onChange keystrokes

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

vercel Bot commented May 15, 2026 •

edited

Loading

cursor Bot commented May 15, 2026 •

edited

Loading

augmentcode Bot commented May 15, 2026 •

edited

Loading

augmentcode Bot May 15, 2026 •

edited

Loading

augmentcode Bot May 15, 2026 •

edited

Loading