@cr1ms0n/pi-subagent 0.8.8 → 0.9.0

package/src/backends/pi.ts

@@ -1,94 +1,164 @@
-/**
- * Pi backend — the original and default. Spawns `pi --mode rpc` and speaks
- * Pi's documented JSON event stream over stdio.
- *
- * This is a straight extraction of the logic that lived inline in
- * `ChildRunner.run()`; behavior is unchanged. It is the only backend that
- * supports every capability, because the protocol was designed for it.
- */
-
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { BackendAdapter, BackendCapabilities, BackendInvocation, BackendLaunchContext, BackendParser } from "../backend.js";
-import { ProtocolParser } from "../protocol.js";
-import { schemaContract } from "../structured.js";
-import type { TaskSpec } from "../types.js";
-
-const PI_CAPABILITIES: BackendCapabilities = {
-  steer: true,
-  gracefulWrapUp: true,
-  costReporting: true,
-  resume: true,
-  fork: true,
-  toolRestriction: true,
-  thinking: true,
-  outputSchema: true,
-};
-
-export class PiBackend implements BackendAdapter {
-  readonly name = "pi" as const;
-  readonly capabilities = PI_CAPABILITIES;
-
-  async buildInvocation(spec: TaskSpec, context: BackendLaunchContext): Promise<BackendInvocation> {
-    // RPC mode keeps a live stdin command channel so steering messages can be
-    // injected mid-run. The event stream on stdout is a superset of json mode.
-    const args = ["--mode", "rpc", "--session-dir", context.sessionDir];
-    if (spec.forkResume && spec.resume) args.push("--fork", spec.resume);
-    else if (spec.resume) args.push("--session", spec.resume);
-    else if (spec.contextFork) {
-      // Context fork: the child starts from a real branched copy of the
-      // parent conversation, then receives the task as its next prompt.
-      // Fail fast rather than silently degrading to a fresh session.
-      if (!spec.parentSessionFile) {
-        throw new Error("context:'fork' requires a persisted parent session (none available). Save the session or use context:'fresh'.");
-      }
-      await fs.access(spec.parentSessionFile).catch(() => {
-        throw new Error(`context:'fork' failed: parent session file ${spec.parentSessionFile} is not readable.`);
-      });
-      args.push("--fork", spec.parentSessionFile);
-    }
-    if (spec.model) args.push("--model", spec.model);
-    if (spec.thinking) args.push("--thinking", spec.thinking);
-    if (spec.tools !== undefined) {
-      const tools = spec.tools.filter((tool) => tool !== "subagent");
-      if (tools.length === 0) args.push("--no-tools");
-      else args.push("--tools", tools.join(","));
-    }
-    // Persona/system prompt first, structured-output contract last (highest salience).
-    const appendPrompt = [spec.systemPrompt?.trim(), spec.outputSchema ? schemaContract(spec.outputSchema) : undefined]
-      .filter(Boolean)
-      .join("\n\n");
-    const cleanupDirs: string[] = [];
-    if (appendPrompt) {
-      const tempPromptDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-subagent-prompt-"));
-      cleanupDirs.push(tempPromptDir);
-      const promptPath = path.join(tempPromptDir, "system-prompt.md");
-      await fs.writeFile(promptPath, appendPrompt, { encoding: "utf8", mode: 0o600 });
-      args.push("--append-system-prompt", promptPath);
-    }
-
-    const invocation = context.getPiCommand(args);
-    return { command: invocation.command, args: invocation.args, cleanupDirs };
-  }
-
-  createParser(): BackendParser {
-    return new ProtocolParser();
-  }
-
-  steerCommand(message: string): unknown {
-    return { type: "steer", message };
-  }
-
-  promptCommand(message: string): unknown {
-    return { type: "prompt", message };
-  }
-
-  uiCancelCommand(id: string): unknown {
-    return { type: "extension_ui_response", id, cancelled: true };
-  }
-
-  stateCommand(): unknown {
-    return { type: "get_state" };
-  }
-}
+/**
+ * Pi backend — the original and default. Spawns `pi --mode rpc` and speaks
+ * Pi's documented JSON event stream over stdio.
+ *
+ * This is a straight extraction of the logic that lived inline in
+ * `ChildRunner.run()`; behavior is unchanged. It is the only backend that
+ * supports every capability, because the protocol was designed for it.
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { BackendAdapter, BackendCapabilities, BackendInvocation, BackendLaunchContext, BackendParser } from "../backend.js";
+import { ProtocolParser } from "../protocol.js";
+import { schemaContract } from "../structured.js";
+import type { TaskSpec } from "../types.js";
+import {
+  PREFLIGHT_MANIFEST_ENV,
+  PREFLIGHT_MANIFEST_SCHEMA,
+  createPreflightNonce,
+  startupFailure,
+  type PreflightManifest,
+} from "../startup-check.js";
+
+/** Nested dispatch tools whose loaded source the startup check must verify. */
+const NESTED_DISPATCH_TOOLS = ["subagent", "subagent_wait"] as const;
+
+const PI_CAPABILITIES: BackendCapabilities = {
+  steer: true,
+  gracefulWrapUp: true,
+  costReporting: true,
+  resume: true,
+  fork: true,
+  toolRestriction: true,
+  thinking: true,
+  outputSchema: true,
+};
+
+export class PiBackend implements BackendAdapter {
+  readonly name = "pi" as const;
+  readonly capabilities = PI_CAPABILITIES;
+
+  async buildInvocation(spec: TaskSpec, context: BackendLaunchContext): Promise<BackendInvocation> {
+    // A Jev-routed spec requires the provider-free startup check before the real task
+    // prompt: Pi silently drops unknown `--tools` names, so parent catalog knowledge is
+    // not proof of what the child actually loaded.
+    const routed = spec.routing !== undefined;
+    if (routed) {
+      if (!spec.model?.trim()) {
+        throw startupFailure(
+          "model_missing",
+          "A routed subagent task must carry the Jev-selected execution model.",
+        );
+      }
+      if (!Array.isArray(spec.tools)) {
+        throw startupFailure(
+          "tools_missing",
+          "A routed subagent task must carry the finalized tool allowlist so the child's active set can be verified.",
+        );
+      }
+    }
+
+    // RPC mode keeps a live stdin command channel so steering messages can be
+    // injected mid-run. The event stream on stdout is a superset of json mode.
+    const args = ["--mode", "rpc", "--session-dir", context.sessionDir];
+    if (spec.forkResume && spec.resume) args.push("--fork", spec.resume);
+    else if (spec.resume) args.push("--session", spec.resume);
+    else if (spec.contextFork) {
+      // Context fork: the child starts from a real branched copy of the
+      // parent conversation, then receives the task as its next prompt.
+      // Fail fast rather than silently degrading to a fresh session.
+      if (!spec.parentSessionFile) {
+        throw new Error("context:'fork' requires a persisted parent session (none available). Save the session or use context:'fresh'.");
+      }
+      await fs.access(spec.parentSessionFile).catch(() => {
+        throw new Error(`context:'fork' failed: parent session file ${spec.parentSessionFile} is not readable.`);
+      });
+      args.push("--fork", spec.parentSessionFile);
+    }
+    if (spec.model) args.push("--model", spec.model);
+    if (spec.thinking) args.push("--thinking", spec.thinking);
+    // A routed task's finalized tools are already profile-filtered and include the
+    // mandatory Pi control-plane tools; the parent applies depth/spawn/profile gating
+    // before `subagent`/`subagent_wait` become candidates, so they are no longer
+    // stripped here. Unrouted (trusted SDK) callers keep the historical behaviour.
+    let toolList: string[] | undefined;
+    if (spec.tools !== undefined) {
+      toolList = routed ? [...new Set(spec.tools)] : spec.tools.filter((tool) => tool !== "subagent");
+      if (toolList.length === 0) args.push("--no-tools");
+      else args.push("--tools", toolList.join(","));
+    }
+    // Persona/system prompt first, structured-output contract last (highest salience).
+    const appendPrompt = [spec.systemPrompt?.trim(), spec.outputSchema ? schemaContract(spec.outputSchema) : undefined]
+      .filter(Boolean)
+      .join("\n\n");
+    const cleanupDirs: string[] = [];
+    try {
+    if (appendPrompt) {
+      const tempPromptDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-subagent-prompt-"));
+      cleanupDirs.push(tempPromptDir);
+      const promptPath = path.join(tempPromptDir, "system-prompt.md");
+      await fs.writeFile(promptPath, appendPrompt, { encoding: "utf8", mode: 0o600 });
+      args.push("--append-system-prompt", promptPath);
+    }
+
+    let env: Record<string, string> | undefined;
+    if (routed) {
+      env = {};
+      const preflightExtension = fileURLToPath(new URL("../child-preflight.ts", import.meta.url));
+      await fs.access(preflightExtension).catch(() => {
+        throw startupFailure(
+          "preflight_extension_missing",
+          "The packaged child-preflight extension is missing, so the routed child's model and tools cannot be verified.",
+        );
+      });
+      const nestedTools = (toolList ?? []).filter((tool) => (NESTED_DISPATCH_TOOLS as readonly string[]).includes(tool));
+      const manifest: PreflightManifest = {
+        schema: PREFLIGHT_MANIFEST_SCHEMA,
+        nonce: createPreflightNonce(),
+        model: spec.model!,
+        tools: toolList ?? [],
+        ...(nestedTools.length > 0 ? { nestedTools } : {}),
+      };
+      const tempPreflightDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-subagent-preflight-"));
+      cleanupDirs.push(tempPreflightDir);
+      const manifestPath = path.join(tempPreflightDir, "preflight.json");
+      await fs.writeFile(manifestPath, JSON.stringify(manifest), { encoding: "utf8", mode: 0o600 });
+      // Bounded, non-secret expectation only: nonce, model ID, tool names, manifest path.
+      env[PREFLIGHT_MANIFEST_ENV] = manifestPath;
+      // Explicit `-e` pins the package-local extension. `--no-extensions` is deliberately
+      // NOT used: the child must still load the extensions that provide Jev-selected tools.
+      args.push("-e", preflightExtension);
+    }
+
+    const invocation = context.getPiCommand(args);
+    return { command: invocation.command, args: invocation.args, env, cleanupDirs };
+    } catch (error) {
+      // The runner cannot own cleanupDirs until an invocation is returned.
+      for (const dir of cleanupDirs) await fs.rm(dir, { recursive: true, force: true }).catch(() => { /* best-effort cleanup */ });
+      throw error;
+    }
+  }
+
+  createParser(): BackendParser {
+    return new ProtocolParser();
+  }
+
+  steerCommand(message: string): unknown {
+    return { type: "steer", message };
+  }
+
+  promptCommand(message: string): unknown {
+    return { type: "prompt", message };
+  }
+
+  uiCancelCommand(id: string): unknown {
+    return { type: "extension_ui_response", id, cancelled: true };
+  }
+
+  stateCommand(): unknown {
+    return { type: "get_state" };
+  }
+}

package/src/child-preflight.ts

@@ -0,0 +1,166 @@
+/**
+ * Private, package-local Pi extension that answers the routed startup handshake.
+ *
+ * Loaded explicitly by the Pi backend (`pi -e <this file>`) for Jev-routed child tasks
+ * only. It registers one nonce-specific command and, when invoked, reports the child's
+ * *actual* active model and tool set plus nested-tool provenance. The control side
+ * (`src/runner.ts`, via `src/startup-check.ts`) is what decides pass/fail — this file
+ * never grants anything and never trusts itself.
+ *
+ * Deliberate properties:
+ *
+ *  - Registers the command unconditionally: nesting/depth/spawn registration rules must
+ *    never disable the check.
+ *  - Reads only the temporary manifest path from the environment; the manifest carries
+ *    the nonce, the expected model ID and tool names — no task text, credentials or
+ *    paths from the parent conversation.
+ *  - Sends a bounded custom message with `triggerTurn: false` so no model turn starts.
+ *  - Uses no imports beyond this package's own handshake module and Node builtins.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  PREFLIGHT_ACK_SCHEMA,
+  PREFLIGHT_ACK_TYPE,
+  PREFLIGHT_MANIFEST_ENV,
+  parsePreflightManifest,
+  preflightCommandBase,
+} from "./startup-check.js";
+
+/** Minimal structural view of the child ExtensionContext we rely on. */
+interface PreflightCommandContext {
+  model?: { provider?: unknown; id?: unknown } | null;
+}
+
+interface PreflightToolMetadata {
+  name?: unknown;
+  sourceInfo?: { path?: unknown; source?: unknown } | null;
+}
+
+/** Minimal structural view of the Pi extension API we rely on. */
+interface PreflightApi {
+  registerCommand(
+    name: string,
+    options: { description?: string; handler: (args: string, ctx: PreflightCommandContext) => unknown },
+  ): void;
+  getActiveTools(): unknown;
+  getAllTools(): unknown;
+  sendMessage(
+    message: { customType: string; content: string; display?: boolean },
+    options?: { triggerTurn?: boolean },
+  ): unknown;
+}
+
+const HOST_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
+const HOST_SEARCH_DEPTH = 6;
+
+function safeActiveTools(pi: PreflightApi): string[] | null {
+  try {
+    const active = pi.getActiveTools();
+    return Array.isArray(active) && active.every((name) => typeof name === "string") ? active : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeNestedProvenance(pi: PreflightApi, wanted: ReadonlySet<string>): Array<{
+  name: string;
+  path: string | null;
+  source: string | null;
+}> {
+  if (wanted.size === 0) return [];
+  try {
+    const all = pi.getAllTools();
+    if (!Array.isArray(all)) return [];
+    return (all as PreflightToolMetadata[])
+      .filter((tool) => typeof tool?.name === "string" && wanted.has(tool.name))
+      .map((tool) => ({
+        name: tool.name as string,
+        path: typeof tool.sourceInfo?.path === "string" ? tool.sourceInfo.path : null,
+        source: typeof tool.sourceInfo?.source === "string" ? tool.sourceInfo.source : null,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Best-effort host identification for the version gate. `PI_PACKAGE_DIR` is documented,
+ * and `process.argv[1]` is the CLI entry for Node-launched Pi. Anything unresolvable
+ * stays `null`; the behavioural handshake, not a guessed version, is the real gate.
+ */
+function readHostInfo(): { version: string | null; packageDir: string | null } {
+  const candidates: string[] = [];
+  try {
+    const override = process.env.PI_PACKAGE_DIR;
+    if (typeof override === "string" && override.trim()) candidates.push(override.trim());
+    const argv1 = process.argv[1];
+    if (typeof argv1 === "string" && argv1) {
+      let dir = path.dirname(path.resolve(argv1));
+      for (let depth = 0; depth < HOST_SEARCH_DEPTH; depth += 1) {
+        candidates.push(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    }
+  } catch {
+    /* fall through to unknown */
+  }
+  for (const dir of candidates) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.name === HOST_PACKAGE_NAME && typeof parsed.version === "string") {
+        return { version: parsed.version, packageDir: dir };
+      }
+    } catch {
+      /* not a package dir; keep looking */
+    }
+  }
+  return { version: null, packageDir: null };
+}
+
+export default function childPreflight(pi: PreflightApi): void {
+  const manifestPath = process.env[PREFLIGHT_MANIFEST_ENV];
+  if (typeof manifestPath !== "string" || manifestPath.length === 0) return;
+
+  let manifest;
+  try {
+    manifest = parsePreflightManifest(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return;
+  }
+  if (!manifest.ok) return;
+  const expectation = manifest.manifest;
+  const nestedWanted = new Set(expectation.nestedTools ?? []);
+
+  pi.registerCommand(preflightCommandBase(expectation.nonce), {
+    description: "private pi-subagent startup check",
+    handler: async (_args: string, ctx: PreflightCommandContext) => {
+      const model = ctx?.model
+        ? {
+            provider: typeof ctx.model.provider === "string" ? ctx.model.provider : undefined,
+            id: typeof ctx.model.id === "string" ? ctx.model.id : undefined,
+          }
+        : null;
+      const payload = {
+        schema: PREFLIGHT_ACK_SCHEMA,
+        nonce: expectation.nonce,
+        model,
+        tools: safeActiveTools(pi),
+        nestedToolsWithSource: safeNestedProvenance(pi, nestedWanted),
+        host: readHostInfo(),
+      };
+      pi.sendMessage(
+        {
+          customType: PREFLIGHT_ACK_TYPE,
+          content: JSON.stringify(payload),
+          display: false,
+        },
+        { triggerTurn: false },
+      );
+    },
+  });
+}