FE-1573: Construct and explain one real net region from a genuine conversation

.changeset/brunch-a3-browser-observation.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut": patch
+---
+
+Add an optional synchronous `aiAssistant.executeMutation` boundary so embedding applications can inspect their live document around a canonical mutation or refuse execution, while the panel retains control of tool results and continuation. Show explicitly unapplied assistant operations with their reason instead of a successful mutation summary, and label grouped tool calls as operations rather than changes.

.changeset/preserve-place-capacity.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut-core": patch
+---
+
+Preserve place capacities when normalizing documents or reopening a JSON document handle, including zero limits and explicitly unbounded places.

.github/workflows/deploy.yml

@@ -210,9 +210,13 @@ jobs:
 
             # Infra images — turbo is blind to them; a changed file under their
             # context dir is a complete signal (the dir IS the build context).
-            CHANGED=$(git diff --name-only HEAD^ HEAD | jq -Rsc 'split("\n") | map(select(length > 0))')
+            # Write the path list to a file: on large PR merge checkouts
+            # `git diff HEAD^` is the whole PR, and `--argjson` hits ARG_MAX.
+            CHANGED_JSON="${RUNNER_TEMP:-$(mktemp -d)}/deploy-changed.json"
+            git diff --name-only HEAD^ HEAD | jq -Rsc 'split("\n") | map(select(length > 0))' > "$CHANGED_JSON"
 
-            AFFECTED_CATALOG=$(jq -c --argjson pkgs "$AFFECTED_PKGS" --argjson changed "$CHANGED" '
+            AFFECTED_CATALOG=$(jq -c --argjson pkgs "$AFFECTED_PKGS" --slurpfile changed "$CHANGED_JSON" '
+              ($changed[0]) as $changed |
               [.[] | select(
                 (.package != null and (.package as $p | $pkgs | index($p) != null))
                 or

.yarn/patches/@earendil-works-pi-agent-core-npm-0.83.0-6cd8fe314f.patch

@@ -0,0 +1,77 @@
+diff --git a/README.md b/README.md
+index a4d5fdd9f68a9c158bf7a4e840b06447d2b45071..573f4f1226b950e3e63c0ba5e6d79e8ba620cb6f 100644
+--- a/README.md
++++ b/README.md
+@@ -396,6 +396,8 @@ const agent = new Agent({
+
+ ## Tools
+
++A tool may supply `validateArguments(args, { toolCallId, signal })` as its authoritative validator. This replaces generic JSON Schema validation/coercion for that tool only. It receives cloned input after an optional `prepareArguments` normalizer and returns parsed data (or throws/rejects). The original tool call/history is not rewritten. `beforeToolCall`, `afterToolCall` and `execute` receive that parsed data; a validation failure or cancellation prevents execution. Validators must honor the abort signal. Tools without this callback retain the existing generic validation path. The third `AgentTool` type parameter describes parsed arguments when they differ from the parameter schema's static input type. The JSON Schema in `parameters` remains the provider-facing input projection; it need not represent executable refinements or normalized output defaults.
++
+ Define tools using `AgentTool`:
+
+ ```typescript
+diff --git a/dist/agent-loop.js b/dist/agent-loop.js
+index 5b5da787a637df62dfd944f92a45fc9cb945eac3..48b4fcb827cb359715f0dddd37fc5ce8b16a6cca 100644
+--- a/dist/agent-loop.js
++++ b/dist/agent-loop.js
+@@ -400,8 +400,11 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
+         };
+     }
+     try {
+-        const preparedToolCall = prepareToolCallArguments(tool, toolCall);
+-        const validatedArgs = validateToolArguments(tool, preparedToolCall);
++        const preparedToolCall = prepareToolCallArguments(tool, tool.validateArguments ? { ...toolCall, arguments: structuredClone(toolCall.arguments) } : toolCall);
++        const validatedArgs = tool.validateArguments
++            ? await tool.validateArguments(structuredClone(preparedToolCall.arguments), { toolCallId: toolCall.id, signal })
++            : validateToolArguments(tool, preparedToolCall);
++        if (signal?.aborted) return { kind: "immediate", result: createErrorToolResult("Operation aborted"), isError: true };
+         if (config.beforeToolCall) {
+             const beforeResult = await config.beforeToolCall({
+                 assistantMessage,
+diff --git a/dist/types.d.ts b/dist/types.d.ts
+index 38009ade487645493c0738dbce9d53fc74f589c6..8a434f490ff55dad40e9ae2ccfde3708f175df25 100644
+--- a/dist/types.d.ts
++++ b/dist/types.d.ts
+@@ -72,7 +72,7 @@ export interface BeforeToolCallContext {
+     assistantMessage: AssistantMessage;
+     /** The raw tool call block from `assistantMessage.content`. */
+     toolCall: AgentToolCall;
+-    /** Validated tool arguments for the target tool schema. */
++    /** Parsed arguments from the tool's authoritative validator (custom validateArguments or generic schema validation). */
+     args: unknown;
+     /** Current agent context at the time the tool call is prepared. */
+     context: AgentContext;
+@@ -83,7 +83,7 @@ export interface AfterToolCallContext {
+     assistantMessage: AssistantMessage;
+     /** The raw tool call block from `assistantMessage.content`. */
+     toolCall: AgentToolCall;
+-    /** Validated tool arguments for the target tool schema. */
++    /** Parsed arguments from the tool's authoritative validator (custom validateArguments or generic schema validation). */
+     args: unknown;
+     /** The executed tool result before any `afterToolCall` overrides are applied. */
+     result: AgentToolResult<any>;
+@@ -330,7 +330,7 @@ export interface AgentToolResult<T> {
+  */
+ export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+ /** Tool definition used by the agent runtime. */
+-export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
++export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any, TArguments = Static<TParameters>> extends Tool<TParameters> {
+     /** Human-readable label for UI display. */
+     label: string;
+     /**
+@@ -338,8 +338,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
+      * Must return an object that matches `TParameters`.
+      */
+     prepareArguments?: (args: unknown) => Static<TParameters>;
++    /** Authoritative per-tool validation. Replaces generic JSON Schema validation/coercion.
++     * Receives a clone of prepared raw input; returns parsed data for beforeToolCall
++     * and execute, or throws. Implementations must honor the supplied abort signal.
++     * The provider JSON Schema remains the representable input projection. */
++    validateArguments?: (args: unknown, context: { toolCallId: string; signal?: AbortSignal }) => TArguments | Promise<TArguments>;
+     /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
+-    execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
++    execute: (toolCallId: string, params: TArguments, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+     /**
+      * Per-tool execution mode override.
+      * - "sequential": this tool must execute one at a time with other tool calls.

.yarn/patches/@earendil-works-pi-ai-npm-0.83.0-c607801251.patch

@@ -0,0 +1,38 @@
+diff --git a/README.md b/README.md
+index ed4e4a545f30a40b8da8ac7ffd5cdc427f562e6b..3463a097ad3c15c2d2ba4dd6ea120b8a2990077f 100644
+--- a/README.md
++++ b/README.md
+@@ -480,6 +480,8 @@ const bookMeetingTool: Tool = {
+
+ ### Constrained Sampling for Tools
+
++Anthropic tool preparation preserves the supplied parameter schema independently of constrained sampling, including root descriptions, additional-properties constraints, definitions and references. The adapter does not rewrite missing `required` lists or remove the declared dialect. This is schema carriage, not a promise that the remote provider accepts every JSON Schema keyword or that arbitrary runtime refinements can be exported.
++
+ Tools can opt in to provider-side constrained sampling. For JSON-schema tools, `strict: 'prefer'` uses provider-side strict schema enforcement when supported and otherwise falls back to normal tool calling. `strict: 'require'` fails the request when the active provider/model cannot honor it. Set `constrainedSampling: false` to explicitly opt out; it behaves the same as omitting the field.
+
+ ```typescript
+diff --git a/dist/api/anthropic-messages.js b/dist/api/anthropic-messages.js
+index 17ec1ac38f1124cbb520522660b6f0dcab70d64d..692f81e97038bd8f2cab749d5a43fcc8e7f0d8af 100644
+--- a/dist/api/anthropic-messages.js
++++ b/dist/api/anthropic-messages.js
+@@ -997,18 +997,8 @@ function convertTools(tools, isOAuthToken, supportsEagerToolInputStreaming, supp
+         return [];
+     return tools.map((tool, index) => {
+         const strict = resolveJsonSchemaStrictSampling(tool, supportsStrictTools);
+-        const schema = tool.parameters;
+-        const legacyInputSchema = {
+-            type: "object",
+-            properties: schema.properties ?? {},
+-            required: schema.required ?? [],
+-        };
+-        const inputSchema = strict === true
+-            ? {
+-                ...tool.parameters,
+-                ...legacyInputSchema,
+-            }
+-            : legacyInputSchema;
++        // Schema carriage is independent of constrained generation policy.
++        const inputSchema = tool.parameters;
+         return {
+             name: isOAuthToken ? toClaudeCodeName(tool.name) : tool.name,
+             description: tool.description,