FE-1573: Add partial Inventory net-copy plumbing and provenance

.changeset/brunch-petrinaut-core-contracts.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut-core": patch
+---
+
+Expose stable document revision identities and explicit browser and headless diagnostics for captured definitions, expand the selected mutation batch with supported update and removal operations, and start document observation only when subscribed.

.changeset/brunch-petrinaut-host-integration.md

@@ -0,0 +1,5 @@
+---
+"@hashintel/petrinaut": patch
+---
+
+Expose revision identity, editor commands, current-definition diagnostics, and user-guide content to host-owned assistant tools, while showing unfinished tool progress and refusing unavailable title edits. Keep host transport and store resources current across route changes, with stable React subscriptions and capability-based read-only titles.

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

@@ -6,7 +6,7 @@ index ed4e4a545f30a40b8da8ac7ffd5cdc427f562e6b..3463a097ad3c15c2d2ba4dd6ea120b8a
 
  ### Constrained Sampling for Tools
 
-+Brunch overrides Pi's Anthropic `convertTools` collapse to `{ type, properties, required }`. That collapse is deliberate for typical Pi tools and remains upstream through 0.85, including when `strict` is off. Brunch construction tools publish nested JSON Schema (`$defs`, `additionalProperties`, descriptions, joined `brunch` fields) that native admission and the model must see on the wire; constrained-sampling `strict` cannot be the carriage switch, because unsupported models would silently strip again. This patch is pinned to 0.83.0 and applies only to Anthropic `input_schema` serialization. It does not change validation, other providers, or tool execution. Drop or rewrite it when upgrading `pi-ai` if upstream grows an explicit full-schema carriage option.
++Brunch preserves Anthropic `input_schema` independently of constrained sampling; Pi's deliberate `{ type, properties, required }` collapse would discard construction schema fields. Drop that change when upstream supports full-schema carriage. This 0.83.0 patch also backports upstream 2e95584dab802ae2f7c8d1a4994d6e0e9f67ec09: preserve values already valid in an anyOf/oneOf arm before attempting coercion. Without it a valid first-workpiece baseRevisionId null becomes an empty string. Remove that backport when upgrading to a version containing the fix; retain ordinary validation and coercion of inputs that match no arm.
 +
  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.
 
@@ -36,3 +36,19 @@ index 17ec1ac38f1124cbb520522660b6f0dcab70d64d..692f81e97038bd8f2cab749d5a43fcc8
          return {
              name: isOAuthToken ? toClaudeCodeName(tool.name) : tool.name,
              description: tool.description,
+diff --git a/dist/utils/validation.js b/dist/utils/validation.js
+--- a/dist/utils/validation.js
++++ b/dist/utils/validation.js
+@@ -152,6 +152,12 @@ function applySchemaArrayCoercion(value, schema) {
+ }
+ function coerceWithUnionSchema(value, schemas) {
+     for (const schema of schemas) {
++        const validator = getSubSchemaValidator(schema);
++        if (validator?.Check(value)) {
++            return value;
++        }
++    }
++    for (const schema of schemas) {
+         const candidate = structuredClone(value);
+         const coerced = coerceWithJsonSchema(candidate, schema);
+         const validator = getSubSchemaValidator(schema);

apps/brunch-agent/.pi/extensions/brunch-persona-testing.ts

@@ -1,191 +1,60 @@
-import { readBrowserSessionOptions } from "../../src/evaluations/persona/browser-session.ts";
-/**
- * Pi extension entry for the Brunch persona harness.
- *
- * Load it from `apps/brunch-agent` with
- * `--extension .pi/extensions/brunch-persona-testing.ts`; the persona policy
- * and operating instructions sit in the same-named folder beside this file.
- * This entry owns only Pi registration and flag handling. The tool lives in
- * `src/evaluations/persona/brunch-turn.ts` and the client-tool hosts in
- * `src/evaluations/persona/client-tool-hosts.ts`, where the application's
- * lint, type-check, and unit tests govern them.
- */
+/** Pi registration for the browser-visible persona launcher; no independent SDK transport. */
+import { sendPersonaBrowserTurn } from "../../src/evaluations/persona/browser-bridge.ts";
 import {
   type BrunchTurnExtensionApi,
-  registerBrunchTurn,
-  requireConversationId,
+  createBrunchTurnTool,
 } from "../../src/evaluations/persona/brunch-turn.ts";
-import {
-  type BrunchClientToolHost,
-  createMockClientToolHost,
-  createRealHeadlessClientToolHost,
-  readMockCalls,
-  TOOL_HOST_FLAG,
-} from "../../src/evaluations/persona/client-tool-hosts.ts";
-import { writeProofArtifacts } from "../../src/evaluations/persona/proof-artifacts.ts";
-import {
-  registerPersonaAccounting,
-  type PersonaAccountingContext,
-} from "../../src/evaluations/persona/request-accounting.ts";
 
-import type { Provider } from "@earendil-works/pi-ai";
-
-/** The slice of Pi's extension API this entry needs; Pi itself is not a workspace dependency. */
 interface BrunchPersonaExtensionApi extends BrunchTurnExtensionApi {
-  registerProvider(provider: Provider): void;
   registerFlag(
     name: string,
-    options: {
-      readonly description?: string;
-      readonly type: "string";
-      readonly default?: string;
-    },
+    options: { readonly description: string; readonly type: "string" },
   ): void;
   getFlag(name: string): boolean | string | undefined;
   on(
     event: "session_start" | "session_shutdown",
-    handler: (
-      event: unknown,
-      context: PersonaAccountingContext,
-    ) => void | Promise<void>,
+    handler: () => void | Promise<void>,
   ): void;
 }
 
-const TOOL_MOCKS_FLAG = "brunch-tool-mocks";
-const HEADLESS_TITLE_FLAG = "brunch-headless-title";
-const EVIDENCE_DIRECTORY_FLAG = "brunch-evidence-dir";
-const BROWSER_SESSION_FLAG = "brunch-browser-session";
-
-const stringFlag = (
-  pi: BrunchPersonaExtensionApi,
-  name: string,
-): string | undefined => {
-  const value = pi.getFlag(name);
-  return typeof value === "string" && value.trim().length > 0
-    ? value.trim()
-    : undefined;
-};
-
-const createConfiguredClientToolHost = (
-  pi: BrunchPersonaExtensionApi,
-): BrunchClientToolHost | undefined => {
-  const mode = stringFlag(pi, TOOL_HOST_FLAG) ?? "none";
-  if (mode === "none") return undefined;
-
-  if (mode === "mock") {
-    const fixturePath = stringFlag(pi, TOOL_MOCKS_FLAG);
-    if (fixturePath === undefined) {
-      throw new Error(
-        `--${TOOL_MOCKS_FLAG} is required when --${TOOL_HOST_FLAG}=mock`,
-      );
-    }
-    return createMockClientToolHost(readMockCalls(fixturePath));
-  }
-
-  if (mode === "real-headless") {
-    const title =
-      stringFlag(pi, HEADLESS_TITLE_FLAG) ??
-      `Brunch persona ${requireConversationId(process.env["PI_SUBAGENT_NAME"])}`;
-    return createRealHeadlessClientToolHost(title);
-  }
-
-  throw new Error(
-    `--${TOOL_HOST_FLAG} must be one of none, mock, or real-headless; received ${mode}`,
-  );
-};
+const browserBridgeFlag = "brunch-browser-bridge";
 
 // Pi loads an extension through its default export.
-export default async function brunchPersonaTestingExtension(
+export default function brunchPersonaTestingExtension(
   pi: BrunchPersonaExtensionApi,
-): Promise<void> {
-  registerPersonaAccounting(pi);
-  pi.registerFlag(TOOL_HOST_FLAG, {
-    type: "string",
-    default: "none",
-    description: "Client-tool host: none, mock, or real-headless",
-  });
-  pi.registerFlag(TOOL_MOCKS_FLAG, {
-    type: "string",
-    description: "Ordered JSON fixture used by the mock client-tool host",
-  });
-  pi.registerFlag(HEADLESS_TITLE_FLAG, {
-    type: "string",
-    description: "Document title used by the real-headless Petrinaut host",
-  });
-  pi.registerFlag(EVIDENCE_DIRECTORY_FLAG, {
-    type: "string",
-    description:
-      "Directory for canonical snapshot, transcript, and trace files",
-  });
-
-  pi.registerFlag(BROWSER_SESSION_FLAG, {
+): void {
+  pi.registerFlag(browserBridgeFlag, {
     type: "string",
     description:
-      "Private operator JSON captured from an initialized Petrinaut browser session",
+      "Private launcher socket for turns executed by the real browser panel",
   });
-  let clientToolHost: BrunchClientToolHost | undefined;
   let generation = 0;
-  const dispose = async () => {
+  pi.on("session_shutdown", () => {
+    generation += 1;
+  });
+  pi.on("session_start", () => {
+    // Pi hydrates CLI flags after the factory, and may continue after lifecycle errors.
+    // Invalidate prior closures before validation so failure cannot retain an old route.
     generation += 1;
-    const previousHost = clientToolHost;
-    clientToolHost = undefined;
-    await previousHost?.dispose?.();
-  };
-
-  pi.on("session_shutdown", dispose);
-  pi.on("session_start", async () => {
-    // CLI extension flags are applied only after the factory has finished.
-    // Invalidate old tool closures before any fallible cleanup or validation:
-    // Pi reports lifecycle errors but may continue running the agent.
-    await dispose();
     const currentGeneration = generation;
-    const browserSessionPath = stringFlag(pi, BROWSER_SESSION_FLAG);
-    if (
-      pi.getFlag(BROWSER_SESSION_FLAG) !== undefined &&
-      browserSessionPath === undefined
-    ) {
-      throw new Error("--brunch-browser-session requires a non-empty path");
-    }
-    if (
-      browserSessionPath !== undefined &&
-      (stringFlag(pi, TOOL_HOST_FLAG) ?? "none") !== "none"
-    ) {
+    const value = pi.getFlag(browserBridgeFlag);
+    const socketPath = typeof value === "string" ? value.trim() : "";
+    if (!socketPath)
       throw new Error(
-        "Browser attachment requires --brunch-tool-host=none; browser mutation hosting is not implemented",
+        "Persona requires the browser launcher. Run yarn brunch:persona --case <name-or-directory>; it supplies --brunch-browser-bridge.",
       );
-    }
-    const browserOptions =
-      browserSessionPath === undefined
-        ? undefined
-        : await readBrowserSessionOptions(browserSessionPath);
-
-    clientToolHost = createConfiguredClientToolHost(pi);
-
-    registerBrunchTurn(
-      {
-        registerTool: (tool) =>
-          pi.registerTool({
-            ...tool,
-            execute: async (...args) => {
-              if (generation !== currentGeneration) {
-                throw new Error(
-                  "brunch_turn session is not initialized; attachment unavailable",
-                );
-              }
-              return tool.execute(...args);
-            },
-          }),
-      },
-      {
-        ...browserOptions,
-        resolveClientToolHost: () => clientToolHost,
-        retainSnapshot: async (snapshot) => {
-          const directory = stringFlag(pi, EVIDENCE_DIRECTORY_FLAG);
-          if (directory !== undefined) {
-            await writeProofArtifacts(directory, snapshot);
-          }
-        },
-      },
+    const tool = createBrunchTurnTool((message, signal) =>
+      sendPersonaBrowserTurn(socketPath, message, signal),
     );
+    pi.registerTool({
+      ...tool,
+      execute: async (...args) => {
+        if (generation !== currentGeneration)
+          throw new Error(
+            "brunch_turn session is not initialized; browser bridge unavailable",
+          );
+        return tool.execute(...args);
+      },
+    });
   });
 }