@fitchmultz/pi-subagents 0.52.16 → 0.52.17

package/scripts/intercom-bridge-credentials.mjs

@@ -161,8 +161,7 @@ function issueCertificate(
 }
 
 function readConfig(/** @type {string} */ path) {
-  /** @type {{ ca?: string, clients?: unknown[], cert?: string, key?: string }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  /** @type {unknown} */
   const config = JSON.parse(readFileSync(path, "utf8"));
   if (!isRecord(config) || !Array.isArray(config.clients) || typeof config.ca !== "string") {
     throw new Error("Invalid clients allowlist.");
@@ -178,7 +177,9 @@ function readConfig(/** @type {string} */ path) {
     }
     return { ...client, name: client.name, cwd: client.cwd, fingerprint256: client.fingerprint256 };
   });
-  return { ...config, ca: config.ca, clients };
+  /** @type {Record<string, unknown> & { ca: string, clients: typeof clients }} */
+  const validated = { ...config, ca: config.ca, clients };
+  return validated;
 }
 
 let args;

package/scripts/intercom-remote.mjs

@@ -32,7 +32,6 @@ const actions = {
   send: ["to", "message", "id", "passive", "expects-reply", "reply-to"],
 };
 function messageId(/** @type {string | undefined} */ id) {
-  // oxlint-disable-next-line no-control-regex
   const controls = /[\u0000-\u001f\u007f-\u009f]/;
   if (id !== undefined && (id.trim() === "" || id.length > 512 || controls.test(id))) {
     throw new Error("Invalid message ID.");

package/scripts/native-package-smoke-assertions.mjs

@@ -1,6 +1,22 @@
 // Journal and observation assertions shared with the packed-native smoke script.
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
+import { isRecord, isUnknownArray } from "../src/shared/unknown.ts";
+
+function jsonRecords(/** @type {string} */ file) {
+  return readFileSync(file, "utf8")
+    .trimEnd()
+    .split("\n")
+    .map((line) => {
+      /** @type {unknown} */ const entry = JSON.parse(line);
+      assert.ok(isRecord(entry));
+      return entry;
+    });
+}
+
+function containsText(/** @type {unknown} */ content, /** @type {string} */ text) {
+  return isUnknownArray(content) && content.some((part) => isRecord(part) && part.text === text);
+}
 
 /**
  * Assert the child journal records its native tool result and completion entry.
@@ -9,23 +25,15 @@ import { readFileSync } from "node:fs";
  * @param {string} completionText
  */
 export function assertChildJournal(sessionFile, terminalEntryId, completionText) {
-  const childEntries = readFileSync(sessionFile, "utf8")
-    .trimEnd()
-    .split("\n")
-    .map((line) =>
-      /** @type {{ id?: string, type?: string, message?: { role?: string, toolName?: string, content?: { text?: string }[] } }} */ (
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- journal line shape, guarded below
-        JSON.parse(line)
-      ),
-    );
-  // oxlint-disable typescript/no-unnecessary-condition -- journal fields are optional under tsc
+  const childEntries = jsonRecords(sessionFile);
   assert.ok(
     childEntries.some(
       (entry) =>
         entry.type === "message" &&
-        entry.message?.role === "toolResult" &&
-        entry.message?.toolName === "packed_probe" &&
-        entry.message?.content?.some((part) => part.text === "PACKED_TOOL_RESULT") === true,
+        isRecord(entry.message) &&
+        entry.message.role === "toolResult" &&
+        entry.message.toolName === "packed_probe" &&
+        containsText(entry.message.content, "PACKED_TOOL_RESULT"),
     ),
     "actual child journal contains its native tool result",
   );
@@ -34,12 +42,12 @@ export function assertChildJournal(sessionFile, terminalEntryId, completionText)
       (entry) =>
         entry.id === terminalEntryId &&
         entry.type === "message" &&
-        entry.message?.role === "assistant" &&
-        entry.message?.content?.some((part) => part.text === completionText) === true,
+        isRecord(entry.message) &&
+        entry.message.role === "assistant" &&
+        containsText(entry.message.content, completionText),
     ),
     "completion references an actually published child assistant entry",
   );
-  // oxlint-enable typescript/no-unnecessary-condition
 }
 
 /**
@@ -47,13 +55,7 @@ export function assertChildJournal(sessionFile, terminalEntryId, completionText)
  * @param {string} observations
  */
 export function assertObservations(observations) {
-  /** @type {Record<string, unknown>[]} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const observed = readFileSync(observations, "utf8")
-    .trimEnd()
-    .split("\n")
-    // oxlint-disable-next-line typescript/no-unsafe-return
-    .map((line) => JSON.parse(line));
+  const observed = jsonRecords(observations);
   const matches = (/** @type {(item: Record<string, unknown>) => boolean} */ predicate) =>
     observed.filter(predicate).length;
   assert.equal(

package/scripts/native-package-smoke.mjs

@@ -19,9 +19,10 @@ import { createRequire } from "node:module";
 import { hostCli, hostIndex, hostRoot } from "./compat-host.mjs";
 import { SmokeProcesses } from "./real-pi-processes.mjs";
 import { assertChildJournal, assertObservations } from "./native-package-smoke-assertions.mjs";
+import { isRecord, isUnknownArray } from "../src/shared/unknown.ts";
+import { isContextTarget } from "../src/pi-intercom/types.ts";
 
 /** @type {(file: string, args: readonly string[], options: import("node:child_process").ExecFileOptions) => Promise<{ stdout: string, stderr: string }>} */
-// oxlint-disable-next-line typescript/strict-void-return
 const execFile = promisify(execFileCallback);
 
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
@@ -145,20 +146,9 @@ writeFileSync(
     retry: { enabled: false },
   }),
 );
-/** @type {typeof import("@earendil-works/pi-coding-agent")} */
-// oxlint-disable-next-line typescript/no-unsafe-assignment
-const sdk = await import(pathToFileURL(hostIndex).href);
-/** @type {typeof import("@earendil-works/pi-ai")} */
-// oxlint-disable-next-line typescript/no-unsafe-assignment
-const ai = await import(import.meta.resolve("@earendil-works/pi-ai"));
-/**
- * The intercom context snapshot the consumer fixture answers with.
- * @typedef {object} IntercomContextSnapshot
- * @property {boolean | undefined} connected
- * @property {string | undefined} peerId
- * @property {string | undefined} rootSessionId
- * @property {number | undefined} incarnation
- */
+// compat-host verifies this specifier resolves to the selected native graph.
+const sdk = await import("@earendil-works/pi-coding-agent");
+const ai = await import("@earendil-works/pi-ai");
 const selected = ai.fauxProvider({ provider: "packed-probe", models: [{ id: "native" }] });
 const processes = new SmokeProcesses({
   cwd: root,
@@ -191,7 +181,6 @@ try {
   while (!existsSync(join(runtimeDir, "broker.pid"))) {
     assert.ok(brokerError === undefined && Date.now() < deadline, brokerReadinessMessage());
     // Observe the broker's publication, not a sleep-based startup assumption.
-    // oxlint-disable-next-line no-await-in-loop
     await delay(25);
   }
   const settingsManager = sdk.SettingsManager.create(root, agentDir, { projectTrusted: true });
@@ -249,7 +238,6 @@ try {
     },
   });
   assert.deepEqual(
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
     [...session.getActiveToolNames()].sort(),
     expectedTools,
     "exactly three eager package tools",
@@ -263,9 +251,8 @@ try {
   const status = await execute("intercom", { action: "status" });
   assert.match(JSON.stringify(status.content), /Connected: Yes/);
   const runs = await execute("agent_runs", { action: "list" });
-  /** @type {{ total: number, runs: unknown[] }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const listDetails = runs.details;
+  /** @type {unknown} */ const listDetails = runs.details;
+  assert.ok(isRecord(listDetails));
   assert.equal(listDetails.total, 0);
   assert.equal(session.model?.provider, "packed-probe");
   assert.equal(session.model.id, "native");
@@ -274,9 +261,10 @@ try {
     events.push(event);
   });
   watchdog = setTimeout(() => {
-    // Fire-and-forget by design: the watchdog only interrupts a stuck turn.
-    // oxlint-disable-next-line typescript/no-floating-promises
-    void session?.abort();
+    // Interrupt a stuck turn, retaining abort failures in the smoke's error evidence.
+    session?.abort().catch((/** @type {unknown} */ error) => {
+      errors.push(error);
+    });
   }, 30_000);
   await session.prompt("Exercise the packed native delegate.", { expandPromptTemplates: false });
   const relevantEvents = () =>
@@ -299,7 +287,6 @@ try {
       Date.now() < completionDeadline,
       `native completion notification resumes the parent: ${JSON.stringify(session.messages.slice(-3))}`,
     );
-    // oxlint-disable-next-line no-await-in-loop
     await delay(25);
   }
   await session.waitForIdle();
@@ -313,20 +300,24 @@ try {
     (event) => event.type === "tool_execution_start" && event.toolName === "delegate",
   );
   assert.equal(starts.length, 1, "one real native delegate call, no fabricated wire events");
-  const receipt =
-    /** @type {{ isError?: boolean, result?: { details?: { receipt?: string, id?: string } } } | undefined} */ (
-      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the packed event shape is not exported by the SDK
-      events.find((event) => event.type === "tool_execution_end" && event.toolName === "delegate")
-    );
-  assert.ok(receipt !== undefined && receipt.isError !== true, JSON.stringify(receipt));
-  assert.equal(receipt.result?.details?.receipt, "launch");
-  /** @type {{ status: string, output: { text: string }, sessionFile: string, result?: { terminalEntryId?: string } }} */
-  // oxlint-disable-next-line typescript/no-unnecessary-condition, typescript/no-unsafe-assignment -- cast-type optionality is not modelled by the checker
-  const run = (await execute("agent_runs", { action: "inspect", id: receipt.result?.details?.id }))
+  const receipt = events.find(
+    (event) => event.type === "tool_execution_end" && event.toolName === "delegate",
+  );
+  assert.ok(receipt?.type === "tool_execution_end" && !receipt.isError, JSON.stringify(receipt));
+  /** @type {unknown} */ const launchResult = receipt.result;
+  assert.ok(isRecord(launchResult) && isRecord(launchResult.details));
+  assert.equal(launchResult.details.receipt, "launch");
+  assert.ok(typeof launchResult.details.id === "string");
+  /** @type {unknown} */
+  const run = (await execute("agent_runs", { action: "inspect", id: launchResult.details.id }))
     .details;
+  assert.ok(isRecord(run) && isRecord(run.output) && typeof run.sessionFile === "string");
   assert.equal(run.status, "completed");
   assert.equal(run.output.text, "PACKED_NATIVE_COMPLETE");
-  assertChildJournal(run.sessionFile, run.result?.terminalEntryId, "PACKED_NATIVE_COMPLETE");
+  assert.ok(run.result === undefined || isRecord(run.result));
+  const terminalEntryId = run.result?.terminalEntryId;
+  assert.ok(terminalEntryId === undefined || typeof terminalEntryId === "string");
+  assertChildJournal(run.sessionFile, terminalEntryId, "PACKED_NATIVE_COMPLETE");
   assertObservations(observations);
   assert.equal(networkAttempts, 0);
   assert.deepEqual(errors, []);
@@ -334,35 +325,30 @@ try {
   if (consumerScript !== undefined) {
     assert.ok(intercomEvents !== undefined, "expected the consumer observer extension");
     assert.ok(consumerDir !== undefined, "expected the consumer script directory argument");
-    /** @type {IntercomContextSnapshot | undefined} */ let target;
+    /** @type {unknown} */ let target;
     intercomEvents.emit("pi-intercom:context-query", {
       version: 1,
-      respond: (/** @type {IntercomContextSnapshot} */ snapshot) => {
+      respond: (/** @type {unknown} */ snapshot) => {
         target = snapshot;
       },
     });
-    assert.ok(
-      target?.connected === true &&
-        target.peerId !== undefined &&
-        target.rootSessionId !== undefined &&
-        target.incarnation !== undefined,
-    );
+    assert.ok(isRecord(target) && target.connected === true && isContextTarget(target));
     const guard = {
       rootSessionId: target.rootSessionId,
       peerId: target.peerId,
       incarnation: target.incarnation,
       applicationGuard: "package-consent-1",
     };
-    /** @type {{ applicationGuard?: string } | undefined} */ let consent;
+    /** @type {unknown} */ let consent;
     intercomEvents.emit("pi-intercom:application-guard", {
       version: 1,
       target: guard,
       revision: guard.applicationGuard,
-      respond: (/** @type {{ applicationGuard?: string }} */ result) => {
+      respond: (/** @type {unknown} */ result) => {
         consent = result;
       },
     });
-    assert.ok(consent !== undefined, "the consumer answered the guard query");
+    assert.ok(isRecord(consent), "the consumer answered the guard query");
     assert.equal(consent.applicationGuard, guard.applicationGuard);
     const consumerHome = join(root, "consumer-home");
     mkdirSync(consumerHome);
@@ -376,7 +362,7 @@ try {
         PI_INTERCOM_RUNTIME_DIR: runtimeDir,
         S3_ROOT: guard.rootSessionId,
         S3_PEER: guard.peerId,
-        S3_INCARNATION: String(guard.incarnation),
+        S3_INCARNATION: guard.incarnation,
         S3_GUARD: guard.applicationGuard,
         S3_BROKER_PID: String(brokerPid),
       },
@@ -391,7 +377,7 @@ try {
           "--permission",
           "--allow-fs-read=*",
           "--allow-fs-write=*",
-          "--input-type=module",
+          "--input-type=module-typescript",
           "-e",
           readFileSync(consumerScript, "utf8"),
         ],
@@ -399,7 +385,6 @@ try {
       );
       process.stdout.write(stdout);
       process.stderr.write(stderr);
-      // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
       assert.equal(events.filter((event) => event.type === "turn_start").length, turns);
     } finally {
       // The consumer's failure/timeout must never leave this fixture's broker stopped.
@@ -472,11 +457,10 @@ export default function(pi) {
       "",
     );
     assert.doesNotMatch(output, /Failed to load extension|ERR_INTERNAL_ASSERTION|Extension error/);
-    /** @type {{ tools: string[], sdkReused: boolean }} */
-    // oxlint-disable-next-line typescript/no-unsafe-assignment
-    const cli = JSON.parse(readFileSync(marker, "utf8"));
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
-    assert.deepEqual(cli.tools.sort(), expectedTools);
+    /** @type {unknown} */ const cli = JSON.parse(readFileSync(marker, "utf8"));
+    assert.ok(isRecord(cli) && isUnknownArray(cli.tools));
+    assert.ok(cli.tools.every((tool) => typeof tool === "string"));
+    assert.deepEqual([...cli.tools].sort(), expectedTools);
     if (!existsSync(join(packageRoot, "node_modules/@earendil-works/pi-coding-agent"))) {
       assert.equal(cli.sdkReused, true, "production-only installs reuse Pi's loaded SDK");
     }

package/scripts/package-smoke.mjs

@@ -16,6 +16,9 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { hostRoot } from "./compat-host.mjs";
 import { compilerInvocation } from "./typescript.mjs";
+import { isRecord, isUnknownArray } from "../src/shared/unknown.ts";
+import { Type } from "typebox";
+import { Assert } from "typebox/value";
 
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
   console.log(
@@ -25,9 +28,11 @@ if (process.argv.includes("--help") || process.argv.includes("-h")) {
 }
 assert.ok(process.argv.length <= 3, "Expected at most one package tarball; use --help");
 
-/** @type {{ name: string, version: string, pi: { extensions?: string[], skills?: string[], agents?: unknown, prompts?: unknown } }} */
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+/** @type {unknown} */
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+assert.ok(isRecord(packageJson));
+assert.ok(typeof packageJson.name === "string" && typeof packageJson.version === "string");
+const packageName = packageJson.name;
 const candidate = process.argv[2] !== undefined ? resolve(process.argv[2]) : undefined;
 const root = mkdtempSync(join(tmpdir(), "ps-package-"));
 const packDir = join(root, "pack");
@@ -55,9 +60,8 @@ function run(
   return result.stdout;
 }
 
-function verifyManifest(
-  /** @type {{ name?: string, private?: boolean, publishConfig?: unknown, bin?: unknown, pi: { extensions?: string[], skills?: string[], agents?: unknown, prompts?: unknown } }} */ manifest,
-) {
+function verifyManifest(/** @type {unknown} */ manifest) {
+  assert.ok(isRecord(manifest) && isRecord(manifest.pi));
   assert.equal(manifest.name, "@fitchmultz/pi-subagents");
   assert.notEqual(manifest.private, true);
   assert.deepEqual(manifest.publishConfig, { access: "public" });
@@ -87,7 +91,7 @@ function installProduction(/** @type {{ filename?: string, files?: { path: strin
     ],
     installDir,
   );
-  const installed = join(installDir, "node_modules", packageJson.name);
+  const installed = join(installDir, "node_modules", packageName);
   const standalone = join(root, "standalone");
   cpSync(installed, standalone, { recursive: true });
   run("npm", ["install", "--ignore-scripts", "--omit=dev", "--legacy-peer-deps"], standalone);
@@ -143,16 +147,14 @@ function verifyDeclarations(/** @type {string} */ consumerDir) {
 async function verifyRuntime(
   /** @type {{ packageRoot: string, consumerDir: string }} */ { packageRoot, consumerDir },
 ) {
-  /** @type {{ name?: string, private?: boolean, publishConfig?: unknown, bin?: unknown, pi: { extensions?: string[], skills?: string[], agents?: unknown, prompts?: unknown } }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  /** @type {unknown} */
   const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
   verifyManifest(manifest);
   verifyDeclarations(consumerDir);
-  /** @type {typeof import("@earendil-works/pi-coding-agent")} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const sdk = await import(pathToFileURL(join(hostRoot, "dist/index.js")).href);
+  // compat-host verifies this specifier resolves to the selected native graph.
+  const sdk = await import("@earendil-works/pi-coding-agent");
   /** @type {typeof import("../src/agent/host.ts")} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  // oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: load the selected runtime artifact with its authoritative source contract.
   const nativeHost = await import(pathToFileURL(join(packageRoot, "dist/agent/host.js")).href);
   assert.equal(
     await nativeHost.loadSDK(hostRoot),
@@ -182,11 +184,10 @@ assert.equal(native.Assert, hostValue.Assert, "detached validation uses the sele
     },
   );
   /** @type {typeof import("../src/pi-intercom/broker/spawn.ts")} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  // oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: load the selected runtime artifact with its authoritative source contract.
   const broker = await import(
     pathToFileURL(join(packageRoot, "dist/pi-intercom/broker/spawn.js")).href
   );
-  // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
   assert.equal(realpathSync(broker.getBrokerSpawnOptions().cwd), realpathSync(packageRoot));
   const help = run(
     process.execPath,
@@ -207,7 +208,9 @@ assert.equal(native.Assert, hostValue.Assert, "detached validation uses the sele
         fileURLToPath(new URL("./native-package-smoke.mjs", import.meta.url)),
         packageRoot,
         consumerDir,
-        fileURLToPath(new URL("../test/fixtures/intercom-client-consumer.mjs", import.meta.url)),
+        fileURLToPath(
+          new URL("../test/fixtures/intercom-client-consumer.test-d.mts", import.meta.url),
+        ),
       ],
       root,
       {
@@ -225,25 +228,32 @@ assert.equal(native.Assert, hostValue.Assert, "detached validation uses the sele
 try {
   verifyManifest(packageJson);
   process.env.PI_PACKAGE_DIR = hostRoot;
-  /** @type {{ name: string, version: string, filename: string, files: { path: string }[] }[]} */
-  const packReports = Object.values(
-    // oxlint-disable-next-line typescript/no-unsafe-argument
-    JSON.parse(
-      run("npm", [
-        "pack",
-        "--json",
-        "--pack-destination",
-        packDir,
-        ...(candidate !== undefined ? [candidate] : []),
-      ]),
-    ),
+  const packSchema = Type.Array(
+    Type.Object({
+      name: Type.String(),
+      version: Type.String(),
+      filename: Type.String(),
+      files: Type.Array(Type.Object({ path: Type.String() })),
+    }),
+  );
+  /** @type {unknown} */
+  const report = JSON.parse(
+    run("npm", [
+      "pack",
+      "--json",
+      "--pack-destination",
+      packDir,
+      ...(candidate !== undefined ? [candidate] : []),
+    ]),
   );
+  // npm 12 reports by package name; earlier npm versions report an array.
+  assert.ok(isRecord(report) || isUnknownArray(report));
+  const packReports = Object.values(report);
+  Assert(packSchema, packReports);
   const pack = packReports[0];
   assert.ok(pack !== undefined && Array.isArray(pack.files), "npm pack must report files");
   if (candidate !== undefined) {
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
     assert.equal(pack.name, packageJson.name);
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
     assert.equal(pack.version, packageJson.version, "Candidate version differs from source");
     assert.ok(
       readFileSync(join(packDir, pack.filename)).equals(readFileSync(candidate)),
@@ -287,7 +297,6 @@ try {
   }
   for (const packageRoot of installProduction(pack)) {
     // Qualify both the npm node_modules location and standalone git-style production graph.
-    // oxlint-disable-next-line no-await-in-loop
     await verifyRuntime(packageRoot);
   }
   console.log(

package/scripts/prepare.mjs

@@ -9,6 +9,7 @@
  */
 
 import { execFile as execFileCallback } from "node:child_process";
+import assert from "node:assert/strict";
 import { existsSync } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -17,7 +18,6 @@ import process from "node:process";
 import { promisify } from "node:util";
 
 /** @type {(file: string, args: readonly string[], options: import("node:child_process").ExecFileOptions) => Promise<{ stdout: string, stderr: string }>} */
-// oxlint-disable-next-line typescript/strict-void-return
 const execFile = promisify(execFileCallback);
 const cwd = process.cwd();
 const buildScript = join(cwd, "scripts", "build.mjs");
@@ -57,10 +57,16 @@ async function main() {
   if (npmExecPath === undefined || npmExecPath === "") {
     throw new Error(`npm_execpath is not set; run "npm install" manually in ${cwd} and retry.`);
   }
-  /** @type {{ devDependencies: { typescript: string } }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  /** @type {unknown} */
   const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+  assert.ok(typeof pkg === "object" && pkg !== null && "devDependencies" in pkg);
   const { devDependencies } = pkg;
+  assert.ok(
+    typeof devDependencies === "object" &&
+      devDependencies !== null &&
+      "typescript" in devDependencies &&
+      typeof devDependencies.typescript === "string",
+  );
   const prefix = await mkdtemp(join(tmpdir(), "pi-subagents-tsc-"));
   try {
     await runNode([
@@ -82,13 +88,13 @@ async function main() {
 }
 
 main().catch((/** @type {unknown} */ error) => {
-  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- exec rejections carry partial output
-  const output = /** @type {{ stdout?: string, stderr?: string }} */ (error);
-  if (output.stdout !== undefined && output.stdout !== "") {
-    process.stdout.write(output.stdout);
-  }
-  if (output.stderr !== undefined && output.stderr !== "") {
-    process.stderr.write(output.stderr);
+  if (typeof error === "object" && error !== null) {
+    if ("stdout" in error && typeof error.stdout === "string") {
+      process.stdout.write(error.stdout);
+    }
+    if ("stderr" in error && typeof error.stderr === "string") {
+      process.stderr.write(error.stderr);
+    }
   }
   console.error(error instanceof Error ? error.message : JSON.stringify(error));
   process.exitCode = 1;

package/scripts/real-pi-events.mjs

@@ -0,0 +1,92 @@
+// Decode the RPC evidence used by the standalone live smoke without requiring local Pi peers.
+import assert from "node:assert/strict";
+import { isRecord, isUnknownArray } from "../src/shared/unknown.ts";
+
+/** @typedef {Record<string, unknown>} RpcEvent */
+/**
+ * The fields consumed from a native launch/continuation receipt, plus stream position.
+ * @typedef {{ [K in "id" | "name" | "sessionFile" | "context" | "predecessor"]: import("../src/agent/contracts.ts").Launch[K] | undefined } & { receipt: string, tool: string, index: number }} SessionReceipt
+ */
+/** @typedef {ReturnType<typeof completionNotice>} SessionNotice */
+/**
+ * @typedef {object} SessionView
+ * @property {RpcEvent[]} events
+ * @property {SessionReceipt[]} receipts
+ * @property {Map<string | undefined, SessionNotice>} notices
+ * @property {{ index: number, text: string, stopReason: string | undefined }[]} replies
+ */
+
+/**
+ * @param {Record<string, unknown>} details
+ * @param {unknown} tool
+ * @param {number} index
+ * @returns {SessionReceipt}
+ */
+function sessionReceipt(details, tool, index) {
+  const { id, name, sessionFile, context, predecessor, receipt } = details;
+  assert.ok(id === undefined || typeof id === "string");
+  assert.ok(name === undefined || typeof name === "string");
+  assert.ok(sessionFile === undefined || typeof sessionFile === "string");
+  assert.ok(context === undefined || context === "fresh" || context === "fork");
+  assert.ok(predecessor === undefined || typeof predecessor === "string");
+  assert.ok(typeof receipt === "string" && typeof tool === "string");
+  return { id, name, sessionFile, context, predecessor, receipt, tool, index };
+}
+
+function completionNotice(/** @type {unknown} */ details, /** @type {number} */ index) {
+  assert.ok(isRecord(details));
+  const { id, result, page } = details;
+  assert.ok(id === undefined || typeof id === "string");
+  assert.ok(result === undefined || isRecord(result));
+  assert.ok(page === undefined || isRecord(page));
+  const status = result?.status;
+  const text = page?.text;
+  assert.ok(status === undefined || typeof status === "string");
+  assert.ok(text === undefined || typeof text === "string");
+  return { id, index, result: { status }, page: { text } };
+}
+
+function addMessage(
+  /** @type {SessionView} */ view,
+  /** @type {unknown} */ message,
+  /** @type {number} */ index,
+) {
+  if (!isRecord(message)) {
+    return;
+  }
+  if (message.customType === "agent-completion" && message.details !== undefined) {
+    const notice = completionNotice(message.details, index);
+    view.notices.set(notice.id, notice);
+  } else if (message.role === "assistant") {
+    const content = message.content ?? [];
+    assert.ok(isUnknownArray(content));
+    const text = content
+      .filter(isRecord)
+      .filter((part) => part.type === "text")
+      .map((part) => {
+        assert.ok(part.text === undefined || typeof part.text === "string");
+        return part.text;
+      });
+    assert.ok(message.stopReason === undefined || typeof message.stopReason === "string");
+    view.replies.push({ index, text: text.join("\n"), stopReason: message.stopReason });
+  }
+}
+
+/** @param {RpcEvent[]} events @returns {SessionView} */
+export function sessionView(events) {
+  /** @type {SessionView} */
+  const view = { events, receipts: [], notices: new Map(), replies: [] };
+  for (const [index, event] of events.entries()) {
+    const details = isRecord(event.result) ? event.result.details : undefined;
+    if (event.type === "message_end") {
+      addMessage(view, event.message, index);
+    } else if (
+      event.type === "tool_execution_end" &&
+      isRecord(details) &&
+      (details.receipt === "launch" || details.receipt === "continuation")
+    ) {
+      view.receipts.push(sessionReceipt(details, event.toolName, index));
+    }
+  }
+  return view;
+}