@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/src/pi-intercom/bridge-rpc-process.ts

@@ -1,330 +0,0 @@
-import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
-import { StringDecoder } from "node:string_decoder";
-import type { RpcCommand, RpcExtensionUIResponse } from "@earendil-works/pi-coding-agent";
-import { trySignalChildTree } from "../shared/post-exit-stdio-guard.ts";
-import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
-import { Fault, cancelled, log, wait } from "./bridge-protocol.ts";
-import type { LaunchPolicy } from "./bridge-launch-policy.ts";
-
-const FRAME_LIMIT = 4 * 1024 * 1024;
-function launchEnvironment(packageRoot: string): NodeJS.ProcessEnv {
-  const environment = Object.fromEntries(
-    Object.entries(process.env).filter(([key]) => !key.startsWith("PI_SUBAGENT_")),
-  );
-  return { ...environment, PI_PACKAGE_DIR: packageRoot };
-}
-
-// Native RpcClient lacks public EOF/exit/UI control and retains/reprints unbounded stderr.
-// This owner implements state, owned-run cancellation and dialog dismissal, never a raw RPC proxy.
-export class RpcProcess {
-  private readonly child: ChildProcessWithoutNullStreams;
-  readonly exited: Promise<void>;
-  status: "starting" | "idle" | "running" | "stopping" | "exited" = "starting";
-  failure?: Fault;
-  private readonly decoder = new StringDecoder("utf8");
-  private buffer = "";
-  private discarding = false;
-  private sequence = 0;
-  private pending?: {
-    readonly id: string;
-    readonly command: "get_state" | "abort";
-    readonly resolve: (data: UnknownRecord) => void;
-    readonly reject: (error: Readonly<Error>) => void;
-  };
-  private stopping?: Promise<void>;
-  private stderrBytes = 0;
-  private exitObserved = false;
-  private cancelling = false;
-
-  constructor(policy: LaunchPolicy, cwd: string, sessionFile: string, resuming = false) {
-    this.child = spawn(process.execPath, this.arguments(policy, sessionFile, resuming), {
-      cwd,
-      detached: true,
-      env: launchEnvironment(policy.packageRoot),
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    this.exited = new Promise((resolveExit) => {
-      this.child.once("close", (code, signal) => {
-        this.exitObserved = true;
-        this.buffer = "";
-        this.discarding = false;
-        this.status = "exited";
-        this.fail(new Fault(503, "session_exited", "Launched Pi process exited."));
-        log("launch_exit", { pid: this.child.pid, code, signal, stderrBytes: this.stderrBytes });
-        resolveExit();
-      });
-    });
-    this.child.once("error", () =>
-      this.fail(new Fault(503, "launch_failed", "Pi process could not start.")),
-    );
-    this.child.stdin.on("error", () => {
-      this.fail(new Fault(503, "rpc_closed", "Pi RPC input closed."));
-      this.cleanup();
-    });
-    this.child.stdout.once("end", () => {
-      this.fail(new Fault(503, "rpc_closed", "Pi RPC output closed."));
-      this.cleanup();
-    });
-    for (const stream of [this.child.stdout, this.child.stderr]) {
-      stream.on("error", () => {
-        this.fail(new Fault(503, "rpc_closed", "Pi RPC output failed."));
-        this.cleanup();
-      });
-    }
-    this.child.stdout.on("data", (chunk: Buffer) => this.read(this.decoder.write(chunk)));
-    this.child.stderr.on("data", (chunk: Buffer) => {
-      // Drain without retaining or exposing diagnostics, including credential-bearing extension errors.
-      this.stderrBytes = Math.min(Number.MAX_SAFE_INTEGER, this.stderrBytes + chunk.length);
-    });
-  }
-  get pid(): number | undefined {
-    return this.child.pid;
-  }
-  private arguments(policy: LaunchPolicy, sessionFile: string, resuming: boolean): string[] {
-    const args = [
-      policy.cli,
-      "--mode",
-      "rpc",
-      "--session",
-      sessionFile,
-      policy.trustProject ? "--approve" : "--no-approve",
-    ];
-    // Resume leaves native model/thinking restoration authoritative; never force the launch default.
-    if (!resuming && policy.provider !== undefined && policy.model !== undefined) {
-      args.push("--provider", policy.provider, "--model", policy.model);
-    }
-    if (!policy.discoverResources) {
-      args.push(
-        "--no-extensions",
-        "--no-skills",
-        "--no-prompt-templates",
-        "--no-themes",
-        "--no-context-files",
-      );
-    }
-    if (policy.offline) {
-      args.push("--offline");
-    }
-    for (const extension of policy.extensions) {
-      args.push("--extension", extension);
-    }
-    return args;
-  }
-  private fail(error: Readonly<Fault>): void {
-    this.failure ??= error;
-    this.pending?.reject(this.failure);
-    this.pending = undefined;
-  }
-  private retainedChunk(chunk: string): string {
-    if (!this.discarding) {
-      return chunk;
-    }
-    const end = chunk.indexOf("\n");
-    if (end < 0) {
-      return "";
-    }
-    this.discarding = false;
-    return chunk.slice(end + 1);
-  }
-  private read(chunk: string): void {
-    this.buffer += this.retainedChunk(chunk);
-    let newline = this.buffer.indexOf("\n");
-    while (newline >= 0) {
-      const line = this.buffer.slice(0, newline);
-      this.buffer = this.buffer.slice(newline + 1);
-      if (Buffer.byteLength(line) > FRAME_LIMIT) {
-        this.oversize(line);
-      } else {
-        this.record(line);
-      }
-      newline = this.buffer.indexOf("\n");
-    }
-    if (Buffer.byteLength(this.buffer) > FRAME_LIMIT) {
-      this.discarding = this.oversize(this.buffer);
-      this.buffer = "";
-    }
-  }
-  private oversize(prefix: string): boolean {
-    // Native event serializers put the discriminant first; responses may put their request ID first.
-    // ponytail: drain large native data events through LF; use token streaming if producer headers change.
-    const header = /^\{"type":"([a-z_]+)"[,}]/.exec(prefix.slice(0, 256));
-    const event = header?.[1];
-    if (
-      event !== undefined &&
-      !["response", "extension_ui_request", "agent_start", "agent_settled"].includes(event)
-    ) {
-      log("rpc_event_discarded", { pid: this.pid, result: "oversized" });
-      return true;
-    }
-    this.protocolFailure();
-    return false;
-  }
-  private protocolFailure(): void {
-    this.fail(new Fault(503, "rpc_invalid", "Pi RPC output violated its bounded JSONL contract."));
-    this.cleanup();
-  }
-  private record(line: string): void {
-    let data: unknown;
-    try {
-      data = JSON.parse(line);
-    } catch {
-      this.protocolFailure();
-      return;
-    }
-    if (!isRecord(data)) {
-      this.protocolFailure();
-      return;
-    }
-    if (data.type === "response" && data.id === this.pending?.id) {
-      this.response(data);
-    } else if (data.type === "extension_ui_request") {
-      this.dialog(data);
-    } else if (!this.failure) {
-      this.event(data.type);
-    }
-  }
-  private event(type: unknown): void {
-    if (type === "agent_start") {
-      this.status = "running";
-    } else if (type === "agent_settled") {
-      this.status = "idle";
-    }
-  }
-  private response(data: UnknownRecord): void {
-    const pending = this.pending;
-    this.pending = undefined;
-    if (
-      data.success === true &&
-      data.command === pending?.command &&
-      (pending?.command !== "get_state" || isRecord(data.data))
-    ) {
-      pending?.resolve(isRecord(data.data) ? data.data : {});
-    } else {
-      pending?.reject(new Fault(503, "rpc_failed", "Pi RPC state request failed."));
-    }
-  }
-  private dialog(data: UnknownRecord): void {
-    if (
-      typeof data.method !== "string" ||
-      !["confirm", "select", "input", "editor"].includes(data.method)
-    ) {
-      return;
-    }
-    if (typeof data.id === "string") {
-      this.write({ type: "extension_ui_response", id: data.id, cancelled: true });
-    }
-    this.fail(
-      new Fault(
-        409,
-        "interaction_required",
-        "Pi requested unsupported interactive input; dialog cancelled and session stopped.",
-      ),
-    );
-    this.cleanup();
-  }
-  private write(
-    command: Readonly<
-      | Extract<RpcCommand, { type: "get_state" | "abort" }>
-      | Extract<RpcExtensionUIResponse, { cancelled: true }>
-    >,
-  ): void {
-    // Only one bounded state request can be in flight; no arbitrary input or growing write queue.
-    if (!this.child.stdin.write(`${JSON.stringify(command)}\n`)) {
-      this.fail(new Fault(503, "rpc_backpressure", "Pi RPC input is not being consumed."));
-      this.cleanup();
-    }
-  }
-  private async command(
-    command: "get_state" | "abort",
-    signal: AbortSignal,
-  ): Promise<UnknownRecord> {
-    cancelled(signal);
-    if (this.failure) {
-      throw this.failure;
-    }
-    if (this.pending) {
-      throw new Fault(
-        409,
-        "control_in_progress",
-        "A native control operation is already in flight.",
-      );
-    }
-    const id = `control-${++this.sequence}`;
-    const result = new Promise<UnknownRecord>((resolve, reject) => {
-      this.pending = { id, command, resolve, reject };
-      this.write({ type: command, id });
-    });
-    try {
-      return await wait(result, signal);
-    } finally {
-      this.pending = undefined;
-    }
-  }
-  async state(signal: AbortSignal): Promise<UnknownRecord> {
-    return this.command("get_state", signal);
-  }
-  async cancel(signal: AbortSignal): Promise<UnknownRecord> {
-    if (this.cancelling) {
-      throw new Fault(409, "control_in_progress", "Native cancellation is already in flight.");
-    }
-    this.cancelling = true;
-    try {
-      await this.command("abort", signal);
-      const state = await this.state(signal);
-      if (state.isStreaming !== false) {
-        throw new Fault(409, "cancel_unconfirmed", "Native Pi has not reached idle after abort.");
-      }
-      this.status = "idle";
-      return { isStreaming: false, pendingMessageCount: state.pendingMessageCount };
-    } finally {
-      this.cancelling = false;
-    }
-  }
-  ready(): void {
-    if (this.failure || this.exitObserved) {
-      throw this.failure ?? new Fault(503, "session_exited", "Pi exited during startup.");
-    }
-    if (this.status === "starting") {
-      this.status = "idle";
-    }
-  }
-  private cleanup(): void {
-    this.stop().catch(() => log("launch_cleanup", { pid: this.child.pid, result: "failed" }));
-  }
-  stop(): Promise<void> {
-    if (this.exitObserved) {
-      return this.exited;
-    }
-    this.stopping ??= this.shutdown().finally(() => {
-      this.stopping = undefined;
-    });
-    return this.stopping;
-  }
-  private async shutdown(): Promise<void> {
-    if (this.exitObserved) {
-      return;
-    }
-    this.status = "stopping";
-    this.fail(new Fault(410, "session_stopped", "Launched session is stopping."));
-    this.child.stdin.end();
-    const terminate = setTimeout(() => {
-      trySignalChildTree(this.child, "SIGTERM");
-    }, 1000);
-    const kill = setTimeout(() => {
-      trySignalChildTree(this.child, "SIGKILL");
-    }, 3000);
-    const deadline = AbortSignal.timeout(8000);
-    try {
-      await wait(this.exited, deadline);
-    } catch {
-      throw new Fault(
-        503,
-        "stop_timeout",
-        "Launched Pi did not close within the cleanup deadline; inspect sessions before retrying.",
-      );
-    } finally {
-      clearTimeout(terminate);
-      clearTimeout(kill);
-    }
-  }
-}

package/src/pi-intercom/interview.ts

@@ -1,295 +0,0 @@
-import { errorMessage, isRecord, isUnknownArray } from "./validation.ts";
-
-export type InterviewType = "single" | "multi" | "text" | "image" | "info";
-export type InterviewOption =
-  | string
-  | (Readonly<Record<string, unknown>> & { readonly label: string });
-export interface SupervisorInterviewQuestion extends Readonly<Record<string, unknown>> {
-  readonly id: string;
-  readonly type: InterviewType;
-  readonly question: string;
-  readonly options?: readonly InterviewOption[];
-}
-export interface SupervisorInterviewRequest extends Readonly<Record<string, unknown>> {
-  readonly title?: string;
-  readonly description?: string;
-  readonly questions: readonly SupervisorInterviewQuestion[];
-}
-export interface SupervisorInterviewReply {
-  readonly responses: readonly { readonly id: string; readonly value: unknown }[];
-}
-function interviewType(value: unknown): value is InterviewType {
-  return (
-    value === "single" ||
-    value === "multi" ||
-    value === "text" ||
-    value === "image" ||
-    value === "info"
-  );
-}
-function nonempty(value: unknown, field: string): string {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`${field} must be a non-empty string`);
-  }
-  return value.trim();
-}
-function optionValue(value: unknown, field: string): InterviewOption {
-  if (typeof value === "string") {
-    const label = value.trim();
-    if (label === "") {
-      throw new Error(`${field} must not be empty`);
-    }
-    return label;
-  }
-  if (!isRecord(value) || typeof value.label !== "string" || value.label.trim() === "") {
-    throw new Error(`${field} must be a non-empty string or an object with a non-empty label`);
-  }
-  return { ...value, label: value.label.trim() };
-}
-function parseOptions(
-  raw: Readonly<Record<string, unknown>>,
-  field: string,
-  type: InterviewType,
-): readonly InterviewOption[] | undefined {
-  if (raw.options === undefined) {
-    if (type === "single" || type === "multi") {
-      throw new Error(`${field}.options must be a non-empty array for ${type} questions`);
-    }
-    return;
-  }
-  if (!isUnknownArray(raw.options)) {
-    throw new Error(`${field}.options must be an array when provided`);
-  }
-  const options = raw.options.map((option, index) =>
-    optionValue(option, `${field}.options[${index}]`),
-  );
-  if (type !== "single" && type !== "multi") {
-    throw new Error(`${field}.options is only valid for single and multi questions`);
-  }
-  if (options.length === 0) {
-    throw new Error(`${field}.options must be a non-empty array for ${type} questions`);
-  }
-  return options;
-}
-function parseQuestion(value: unknown, index: number): SupervisorInterviewQuestion {
-  const field = `interview.questions[${index}]`;
-  if (!isRecord(value)) {
-    throw new Error(`${field} must be an object`);
-  }
-  const id = nonempty(value.id, `${field}.id`);
-  if (!interviewType(value.type)) {
-    throw new Error(`${field}.type must be one of: single, multi, text, image, info`);
-  }
-  const question = nonempty(value.question, `${field}.question`);
-  if (value.context !== undefined && typeof value.context !== "string") {
-    throw new Error(`${field}.context must be a string when provided`);
-  }
-  const options = parseOptions(value, field, value.type);
-  return { ...value, id, type: value.type, question, ...(options ? { options } : {}) };
-}
-function optionalText(value: unknown, field: string): string | undefined {
-  if (value === undefined) {
-    return;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${field} must be a string when provided`);
-  }
-  return value.trim();
-}
-function parseInterview(input: unknown): SupervisorInterviewRequest {
-  if (!isRecord(input)) {
-    throw new Error("interview must be an object with a questions array");
-  }
-  const title = optionalText(input.title, "interview.title");
-  const description = optionalText(input.description, "interview.description");
-  if (!isUnknownArray(input.questions) || input.questions.length === 0) {
-    throw new Error("interview.questions must be a non-empty array");
-  }
-  const ids = new Set<string>();
-  const questions = input.questions.map((value, index) => {
-    const question = parseQuestion(value, index);
-    if (ids.has(question.id)) {
-      throw new Error(`interview question id must be unique: ${question.id}`);
-    }
-    ids.add(question.id);
-    return question;
-  });
-  return {
-    ...input,
-    ...(title !== undefined ? { title } : {}),
-    ...(description !== undefined ? { description } : {}),
-    questions,
-  };
-}
-export function validateSupervisorInterviewRequest(
-  input: unknown,
-):
-  | { readonly ok: true; readonly interview: SupervisorInterviewRequest }
-  | { readonly ok: false; readonly error: string } {
-  try {
-    return { ok: true, interview: parseInterview(input) };
-  } catch (error) {
-    return { ok: false, error: errorMessage(error) };
-  }
-}
-function optionLabel(option: InterviewOption): string {
-  return typeof option === "string" ? option : option.label;
-}
-function exampleValue(question: SupervisorInterviewQuestion): unknown {
-  switch (question.type) {
-    case "multi":
-      return question.options?.slice(0, 2).map(optionLabel) ?? [];
-    case "single": {
-      const first = question.options?.[0];
-      return first === undefined ? "option label" : optionLabel(first);
-    }
-    case "image":
-      return "image/file reference or description";
-    case "info":
-    case "text":
-      return "answer text";
-  }
-}
-function interviewPreamble(
-  interview: SupervisorInterviewRequest,
-  message: string | undefined,
-): string[] {
-  const lines = [
-    ["Interview", interview.title],
-    ["", interview.description],
-    ["Child note", message],
-  ].flatMap(([label, value]) => {
-    const text = value?.trim() ?? "";
-    if (text === "") {
-      return [];
-    }
-    return [label === "" ? text : `${label ?? ""}: ${text}`];
-  });
-  if (lines.length > 0) {
-    lines.push("");
-  }
-  return lines;
-}
-export function formatSupervisorInterviewRequest(
-  interview: SupervisorInterviewRequest,
-  message?: string,
-): string {
-  const lines = interviewPreamble(interview, message);
-  lines.push("Questions:");
-  interview.questions.forEach((question, index) => {
-    lines.push(`${index + 1}. [${question.id}] (${question.type}) ${question.question}`);
-    if (typeof question.context === "string" && question.context.trim() !== "") {
-      lines.push(`   Context: ${question.context.trim()}`);
-    }
-    if (question.options !== undefined && question.options.length > 0) {
-      lines.push("   Options:");
-      for (const option of question.options) {
-        lines.push(`   - ${optionLabel(option)}`);
-      }
-    }
-  });
-  const responseExample = {
-    responses: interview.questions
-      .filter((question) => question.type !== "info")
-      .map((question) => ({ id: question.id, value: exampleValue(question) })),
-  };
-  lines.push(
-    "",
-    "Supervisor reply instructions:",
-    "Reply with plain JSON or a fenced ```json block using this stable shape. Use the question ids exactly. Info questions are context-only and do not need responses. For single questions, value is one option label. For multi questions, value is an array of option labels. For text/image questions, value is a string unless the question asks otherwise.",
-    "",
-    "```json",
-    JSON.stringify(responseExample, null, 2),
-    "```",
-  );
-  return lines.join("\n");
-}
-function multiResponse(
-  value: unknown,
-  question: SupervisorInterviewQuestion,
-  field: string,
-): readonly string[] {
-  if (!isUnknownArray(value) || !value.every((item): item is string => typeof item === "string")) {
-    throw new Error(`${field} must be an array of strings for multi questions`);
-  }
-  const labels = new Set(question.options?.map(optionLabel));
-  const selected = value.map((item) => item.trim());
-  const invalid = selected.find((item) => !labels.has(item));
-  if (invalid !== undefined && invalid !== "") {
-    throw new Error(`${field} contains an option that is not in the question options: ${invalid}`);
-  }
-  return selected;
-}
-function responseValue(
-  value: unknown,
-  question: SupervisorInterviewQuestion,
-  index: number,
-): unknown {
-  const field = `responses[${index}].value`;
-  if (question.type === "multi") {
-    return multiResponse(value, question, field);
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${field} must be a string for ${question.type} questions`);
-  }
-  if (question.type !== "single") {
-    return value;
-  }
-  const labels = new Set(question.options?.map(optionLabel));
-  if (!labels.has(value.trim())) {
-    throw new Error(`${field} must match one of the question options`);
-  }
-  return value.trim();
-}
-function validateReply(
-  value: unknown,
-  interview: SupervisorInterviewRequest,
-): SupervisorInterviewReply {
-  if (!isRecord(value)) {
-    throw new Error("reply JSON must be an object with a responses array");
-  }
-  if (!isUnknownArray(value.responses)) {
-    throw new Error("reply JSON must include a responses array");
-  }
-  const byId = new Map(
-    interview.questions
-      .filter((question) => question.type !== "info")
-      .map((question) => [question.id, question]),
-  );
-  const seen = new Set<string>();
-  const responses = value.responses.map((response, index) => {
-    if (!isRecord(response)) {
-      throw new Error(`responses[${index}] must be an object`);
-    }
-    const id = nonempty(response.id, `responses[${index}].id`);
-    const question = byId.get(id);
-    if (!question) {
-      throw new Error(`responses[${index}].id must match a non-info interview question id`);
-    }
-    if (seen.has(id)) {
-      throw new Error(`responses[${index}].id is duplicated: ${id}`);
-    }
-    seen.add(id);
-    if (!Object.hasOwn(response, "value")) {
-      throw new Error(`responses[${index}].value is required`);
-    }
-    return { id, value: responseValue(response.value, question, index) };
-  });
-  return { responses };
-}
-export function parseStructuredSupervisorReply(
-  text: string,
-  interview: SupervisorInterviewRequest,
-): { readonly value?: SupervisorInterviewReply; readonly error?: string } | undefined {
-  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
-  const candidate = (fenced?.[1] ?? text).trim();
-  if (!candidate.startsWith("{") && !candidate.startsWith("[")) {
-    return;
-  }
-  try {
-    const value: unknown = JSON.parse(candidate);
-    return { value: validateReply(value, interview) };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
-}