@akagilnc/pi-workflow-roles 0.1.1751

package/src/public-cli/fixer-run.ts

@@ -0,0 +1,587 @@
+/**
+ * Public Fixer Role run: admit → explicit Internal activate → settle Terminal result.
+ * #110/#177: package-owned diagnosing-bugs and tdd methods (available, not forced),
+ * common Invocation + structural prerequisites, default apply / explicit plan,
+ * shared #106 success interface. Controlled-failure settlement reuses #107.
+ */
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  loadPackagedMethodSkillMaterial,
+  resolvePackagedMethodSkillPath,
+  type PackagedMethodSkillMaterial,
+  type PackagedMethodSkillProvenance,
+} from "../package-resources/method-skill.ts";
+import {
+  runExplicitInternalActivation,
+  type ExplicitInternalKnownFailure,
+  type ExplicitInternalPiRunner,
+  type ExplicitInternalPiResult,
+} from "./explicit-internal.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import {
+  admitFixerInvocation,
+  buildFixerTransportPrompt,
+  type AdmittedFixerInvocation,
+} from "./invocation.ts";
+import {
+  type CredentialProviders,
+  type SeatModelConfig,
+} from "./config.ts";
+import {
+  missingCredentialPreDispatchFailure,
+  postRunMissingCredentialFailure,
+} from "./public-run-credentials.ts";
+import {
+  acquireRunWriterLease,
+  clearTypedProviderHttpObservation,
+  isSessionPrincipalAvailable,
+  isV1ResumableFailure,
+  loadResumableFixerRun,
+  markRunAdmitted,
+  markRunResumable,
+  markRunRunning,
+  markRunTerminal,
+  renderResumeCommand,
+  RESUME_TRANSPORT_ENVELOPE,
+  RunWriterLeaseHeldError,
+  type RunWriterLease,
+  readTypedHttp429Observation,
+} from "./run-lifecycle.ts";
+import {
+  classifyPostAdmissionFailure,
+  exitCodeForTerminalOutcome,
+  formatCliDiagnostic,
+  formatTerminalResult,
+  hasLawfulFixerTerminalResult,
+  inspectJudgeSession,
+  isLawfulTypedTerminalOutcome,
+  presentFailureTerminal,
+  presentStructuralRejection,
+  resolveAuditedRunnerKnownFailure,
+  explicitInternalKnownFailureClassificationInput,
+  settleFailureTerminalResult,
+  trySettleFixerTerminalResult,
+  trySettleComplianceAuditIncompleteTerminalResult,
+} from "./settlement.ts";
+import type { CliIo } from "./cli-io.ts";
+import type {
+  ControlledFailureCause,
+  TerminalResult,
+} from "./terminal.ts";
+
+export type FixerRunEnv = {
+  home: string;
+  agentDir: string;
+  packageRoot: string;
+  cwd: string;
+  correlationId?: string;
+  piRunner?: ExplicitInternalPiRunner;
+  model?: SeatModelConfig;
+  credentials?: CredentialProviders;
+  createRunId?: () => string;
+  extraPiArgs?: readonly string[];
+  timeoutMs?: number;
+};
+
+function buildModelArgs(model: SeatModelConfig | undefined): string[] {
+  if (model === undefined) return [];
+  return [
+    "--provider",
+    model.provider,
+    "--model",
+    model.model,
+    "--thinking",
+    model.thinking,
+  ];
+}
+
+/**
+ * Build Internal activation extra-args for an admitted Fixer run.
+ * Package diagnosing-bugs and tdd Skills are available via --skill on every phase
+ * (not forced into the first prompt). Ambient home skills stay disabled.
+ */
+export function buildFixerActivationExtraArgs(
+  admitted: AdmittedFixerInvocation,
+  options: {
+    packageRoot: string;
+    model?: SeatModelConfig;
+    extraPiArgs?: readonly string[];
+  },
+): string[] {
+  const prompt = buildFixerTransportPrompt(admitted);
+  const diagnosisSkillPath = resolvePackagedMethodSkillPath(
+    options.packageRoot,
+    "diagnosing-bugs",
+  );
+  const tddSkillPath = resolvePackagedMethodSkillPath(options.packageRoot, "tdd");
+  const prerequisiteArgs =
+    admitted.prerequisitesPath === undefined
+      ? []
+      : ["--ak-fixer-prerequisites", admitted.prerequisitesPath];
+  return [
+    "--no-skills",
+    "--skill",
+    diagnosisSkillPath,
+    "--skill",
+    tddSkillPath,
+    "--no-prompt-templates",
+    "--no-themes",
+    "--no-context-files",
+    "--session",
+    admitted.sessionFile,
+    "--session-dir",
+    admitted.sessionDirectory,
+    ...(options.extraPiArgs ?? []),
+    "--ak-role",
+    "fixer",
+    "--ak-fixer-phase",
+    admitted.phase,
+    "--ak-fix-packet",
+    admitted.packetPath,
+    ...prerequisiteArgs,
+    "--mode",
+    "json",
+    ...buildModelArgs(options.model),
+    prompt,
+  ];
+}
+
+/**
+ * Reopen the exact Fixer Pi session for resume. Preserves admitted phase,
+ * prerequisites, and package diagnosis/tdd availability; does not resubmit instruction.
+ */
+export function buildFixerResumeActivationExtraArgs(
+  admitted: AdmittedFixerInvocation,
+  options: {
+    packageRoot: string;
+    model?: SeatModelConfig;
+    extraPiArgs?: readonly string[];
+  },
+): string[] {
+  const diagnosisSkillPath = resolvePackagedMethodSkillPath(
+    options.packageRoot,
+    "diagnosing-bugs",
+  );
+  const tddSkillPath = resolvePackagedMethodSkillPath(options.packageRoot, "tdd");
+  const prerequisiteArgs =
+    admitted.prerequisitesPath === undefined
+      ? []
+      : ["--ak-fixer-prerequisites", admitted.prerequisitesPath];
+  return [
+    "--no-skills",
+    "--skill",
+    diagnosisSkillPath,
+    "--skill",
+    tddSkillPath,
+    "--no-prompt-templates",
+    "--no-themes",
+    "--no-context-files",
+    "--session",
+    admitted.sessionFile,
+    "--session-dir",
+    admitted.sessionDirectory,
+    ...(options.extraPiArgs ?? []),
+    "--ak-role",
+    "fixer",
+    "--ak-fixer-phase",
+    admitted.phase,
+    "--ak-fix-packet",
+    admitted.packetPath,
+    ...prerequisiteArgs,
+    "--mode",
+    "json",
+    ...buildModelArgs(options.model),
+    RESUME_TRANSPORT_ENVELOPE,
+  ];
+}
+
+async function presentControlledFailure(
+  admitted: AdmittedFixerInvocation,
+  failureInput: {
+    timedOut: boolean;
+    code: number | null;
+    stderr: string;
+    thrown?: unknown;
+    knownFailure?: ExplicitInternalKnownFailure;
+  },
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted: AdmittedFixerInvocation;
+  terminal: TerminalResult;
+}> {
+  const hasThrown = Object.hasOwn(failureInput, "thrown");
+  const session =
+    !hasThrown &&
+    !failureInput.timedOut &&
+    failureInput.knownFailure === undefined
+      ? await inspectJudgeSession(admitted.sessionFile)
+      : undefined;
+  const failure = classifyPostAdmissionFailure({
+    timedOut: failureInput.timedOut,
+    code: failureInput.code,
+    stderr: failureInput.stderr,
+    ...(hasThrown ? { thrown: failureInput.thrown } : {}),
+    ...explicitInternalKnownFailureClassificationInput(failureInput.knownFailure),
+    ...(session === undefined ? {} : { session }),
+  });
+
+  const hasLawfulTerminalResult = await hasLawfulFixerTerminalResult(admitted);
+  const typedHttp429 = await readTypedHttp429Observation(admitted.runDirectory);
+  const sessionPrincipalAvailable = await isSessionPrincipalAvailable(
+    admitted.sessionFile,
+  );
+  const resumable =
+    sessionPrincipalAvailable &&
+    isV1ResumableFailure({
+      hasLawfulTerminalResult,
+      ...(typedHttp429 === undefined ? {} : { typedHttp429 }),
+    });
+  if (resumable && typedHttp429 !== undefined) {
+    await markRunResumable(admitted.runDirectory, typedHttp429);
+  } else {
+    await markRunTerminal(admitted.runDirectory).catch(() => undefined);
+  }
+
+  // #107 owns generic controlled-failure settlement — consume, do not re-own.
+  const terminal = await settleFailureTerminalResult(
+    admitted,
+    failure,
+    resumable
+      ? { resume: { command: renderResumeCommand(admitted.runId) } }
+      : {},
+  );
+  presentFailureTerminal(terminal, io);
+  return {
+    exitCode: exitCodeForTerminalOutcome(terminal.roleOutcome),
+    admitted,
+    terminal,
+  };
+}
+
+async function dispatchAdmittedFixer(input: {
+  admitted: AdmittedFixerInvocation;
+  env: FixerRunEnv;
+  io: CliIo;
+  extraArgs: string[];
+  lease: RunWriterLease;
+  methodMaterial: PackagedMethodSkillMaterial;
+}): Promise<{
+  exitCode: number;
+  admitted: AdmittedFixerInvocation;
+  terminal?: TerminalResult;
+}> {
+  const { admitted, env, io, extraArgs, lease, methodMaterial } = input;
+  try {
+    const missingCredential = missingCredentialPreDispatchFailure(
+      env.model,
+      env.credentials,
+    );
+    if (missingCredential !== undefined) {
+      return await presentControlledFailure(
+        admitted,
+        missingCredential,
+        io,
+      );
+    }
+    await markRunRunning(admitted.runDirectory);
+    await clearTypedProviderHttpObservation(admitted.runDirectory);
+
+    const childEnv: NodeJS.ProcessEnv = {
+      ...process.env,
+      HOME: env.home,
+      PI_CODING_AGENT_DIR: env.agentDir,
+      AK_ROLE_RUN_DIR: admitted.runDirectory,
+    };
+    if (env.correlationId !== undefined && env.correlationId.trim() !== "") {
+      childEnv.AK_CORRELATION_ID = env.correlationId;
+    }
+
+    let result: ExplicitInternalPiResult;
+    try {
+      result = await runExplicitInternalActivation({
+        packageRoot: env.packageRoot,
+        extraArgs,
+        cwd: admitted.projectRoot,
+        home: env.home,
+        agentDir: env.agentDir,
+        env: childEnv,
+        timeoutMs: env.timeoutMs,
+        ...(env.piRunner === undefined ? {} : { runner: env.piRunner }),
+      });
+    } catch (error) {
+      return await presentControlledFailure(
+        admitted,
+        {
+          timedOut: false,
+          code: null,
+          stderr: "",
+          thrown: error,
+        },
+        io,
+      );
+    }
+
+    try {
+      await writeFile(
+        join(admitted.runDirectory, "stderr.log"),
+        result.stderr,
+        "utf8",
+      );
+    } catch {
+      // continue to lawful / controlled-failure settlement
+    }
+
+    let lawful: TerminalResult | undefined;
+    try {
+      lawful = await trySettleFixerTerminalResult(admitted, {
+        methodProvenance: methodMaterial.provenance,
+        methodSkillPath: methodMaterial.skillPath,
+        methodSkillConfiguredPath: resolvePackagedMethodSkillPath(
+          env.packageRoot,
+          "diagnosing-bugs",
+        ),
+      });
+    } catch (error) {
+      return await presentControlledFailure(
+        admitted,
+        {
+          timedOut: false,
+          code: result.code,
+          stderr: result.stderr,
+          thrown: error,
+        },
+        io,
+      );
+    }
+    if (lawful !== undefined && isLawfulTypedTerminalOutcome(lawful.roleOutcome)) {
+      await markRunTerminal(admitted.runDirectory).catch(() => undefined);
+      io.stdout(formatTerminalResult(lawful));
+      return {
+        exitCode: exitCodeForTerminalOutcome(lawful.roleOutcome),
+        admitted,
+        terminal: lawful,
+      };
+    }
+
+    const auditIncomplete = await trySettleComplianceAuditIncompleteTerminalResult(admitted);
+    if (auditIncomplete !== undefined) {
+      await markRunTerminal(admitted.runDirectory).catch(() => undefined);
+      if (auditIncomplete.roleOutcome.kind === "failure") {
+        presentFailureTerminal(auditIncomplete, io);
+      } else {
+        io.stdout(formatTerminalResult(auditIncomplete));
+      }
+      return {
+        exitCode: exitCodeForTerminalOutcome(auditIncomplete.roleOutcome),
+        admitted,
+        terminal: auditIncomplete,
+      };
+    }
+
+    const credentialFailure = postRunMissingCredentialFailure(
+      result,
+      env.model,
+      env.credentials,
+    );
+    const knownFailure = await resolveAuditedRunnerKnownFailure({
+      runner: result.knownFailure,
+      sessionFile: admitted.sessionFile,
+      credential: credentialFailure,
+    });
+    return await presentControlledFailure(
+      admitted,
+      {
+        timedOut: result.timedOut,
+        code: result.code,
+        stderr: result.stderr,
+        ...(knownFailure === undefined ? {} : { knownFailure }),
+      },
+      io,
+    );
+  } finally {
+    await lease.release();
+  }
+}
+
+async function loadFixerMethodMaterial(
+  packageRoot: string,
+): Promise<PackagedMethodSkillMaterial> {
+  return await loadPackagedMethodSkillMaterial(packageRoot, "diagnosing-bugs");
+}
+
+export async function runPublicFixer(
+  argv: readonly string[],
+  env: FixerRunEnv,
+  io: CliIo,
+  parseFixerArgv: (args: readonly string[]) => {
+    phase: "plan" | "apply";
+    instruction: string;
+    attachmentPaths: string[];
+    prerequisitesPath?: string;
+    project?: string;
+  },
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedFixerInvocation;
+  terminal?: TerminalResult;
+}> {
+  let admitted: AdmittedFixerInvocation;
+  try {
+    const parsed = parseFixerArgv(argv);
+    admitted = await admitFixerInvocation({
+      home: env.home,
+      cwd: env.cwd,
+      phase: parsed.phase,
+      instruction: parsed.instruction,
+      attachmentPaths: parsed.attachmentPaths,
+      ...(parsed.prerequisitesPath === undefined
+        ? {}
+        : { prerequisitesPath: parsed.prerequisitesPath }),
+      ...(parsed.project === undefined ? {} : { project: parsed.project }),
+      ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+    });
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  await markRunAdmitted(admitted);
+
+  let lease: RunWriterLease;
+  try {
+    lease = await acquireRunWriterLease(admitted.runDirectory);
+  } catch (error) {
+    if (error instanceof RunWriterLeaseHeldError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  let methodMaterial: PackagedMethodSkillMaterial;
+  try {
+    methodMaterial = await loadFixerMethodMaterial(env.packageRoot);
+  } catch (error) {
+    await lease.release();
+    return await presentControlledFailure(
+      admitted,
+      {
+        timedOut: false,
+        code: null,
+        stderr: "",
+        thrown: error,
+      },
+      io,
+    );
+  }
+
+  const extraArgs = buildFixerActivationExtraArgs(admitted, {
+    packageRoot: env.packageRoot,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+  });
+
+  return await dispatchAdmittedFixer({
+    admitted,
+    env,
+    io,
+    extraArgs,
+    lease,
+    methodMaterial,
+  });
+}
+
+/**
+ * Resume a previously admitted Fixer Role run after a typed HTTP 429.
+ * Restores role/phase/packet/prerequisites/session identity; model override is temporary.
+ */
+export async function runPublicFixerResume(
+  argv: readonly string[],
+  env: FixerRunEnv,
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedFixerInvocation;
+  terminal?: TerminalResult;
+}> {
+  const runId = argv[0];
+  if (runId === undefined || runId.trim() === "" || runId.startsWith("-")) {
+    presentStructuralRejection(
+      new CliUsageError("usage: ak-role resume <runId>"),
+      io,
+    );
+    return { exitCode: 2 };
+  }
+  if (argv.length > 1) {
+    presentStructuralRejection(
+      new CliUsageError("resume takes exactly one run id"),
+      io,
+    );
+    return { exitCode: 2 };
+  }
+
+  let loaded;
+  try {
+    loaded = await loadResumableFixerRun(env.home, runId);
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      presentStructuralRejection(error, io);
+      return { exitCode: 2 };
+    }
+    throw error;
+  }
+
+  const { admitted } = loaded;
+
+  let lease: RunWriterLease;
+  try {
+    lease = await acquireRunWriterLease(admitted.runDirectory);
+  } catch (error) {
+    if (error instanceof RunWriterLeaseHeldError) {
+      io.stderr(formatCliDiagnostic(error.message));
+      return { exitCode: 1 };
+    }
+    throw error;
+  }
+
+  let methodMaterial: PackagedMethodSkillMaterial;
+  try {
+    methodMaterial = await loadFixerMethodMaterial(env.packageRoot);
+  } catch (error) {
+    await lease.release();
+    return await presentControlledFailure(
+      admitted,
+      {
+        timedOut: false,
+        code: null,
+        stderr: "",
+        thrown: error,
+      },
+      io,
+    );
+  }
+
+  const extraArgs = buildFixerResumeActivationExtraArgs(admitted, {
+    packageRoot: env.packageRoot,
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+  });
+
+  return await dispatchAdmittedFixer({
+    admitted,
+    env,
+    io,
+    extraArgs,
+    lease,
+    methodMaterial,
+  });
+}
+
+// Re-export for tests that assert typed credential failure channel shape.
+export type { ExplicitInternalKnownFailure, PackagedMethodSkillProvenance };

package/src/public-cli/host-pi-runtime.ts

@@ -0,0 +1,112 @@
+/**
+ * Standalone-invocation runtime resolution. The public CLI runs outside Pi, while
+ * the @earendil-works peers are optional and host-provided (ADR: the machine's Pi
+ * installation is the single runtime authority). When the local install cannot
+ * resolve them, link the host Pi's own modules into this package's node_modules
+ * instead of materializing a second runtime from the registry.
+ *
+ * Package presence is probed by directory (ancestor node_modules walk, the same
+ * package lookup ESM uses) — entry-point resolution is unusable here because the
+ * peers export "." with an `import` condition only, which CJS require cannot see.
+ */
+import { existsSync, lstatSync, mkdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+
+export const HOST_PROVIDED_PACKAGES = [
+  "@earendil-works/pi-ai",
+  "@earendil-works/pi-coding-agent",
+  "typebox",
+] as const;
+
+type HostProvidedPackage = (typeof HOST_PROVIDED_PACKAGES)[number];
+
+/**
+ * Make the host-provided runtime packages resolvable from `packageRoot`.
+ * Local resolution wins untouched; otherwise the host `pi` executable on PATH
+ * anchors the lookup and the packages are symlinked into the package-own
+ * node_modules (highest resolution precedence for the package and its child
+ * processes). Throws when neither source can provide a package.
+ */
+export function ensureHostPiRuntimeResolvable(
+  packageRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  const missing = missingPackages(packageRoot);
+  if (missing.length === 0) {
+    return;
+  }
+  const hostCli = findHostPiCli(env);
+  if (hostCli === undefined) {
+    throw new Error(
+      `ak-role cannot resolve ${missing.join(", ")} next to the installed package and found no host \`pi\` executable on PATH. ` +
+        "Install Pi (@earendil-works/pi-coding-agent) on this machine or provide the peer packages locally.",
+    );
+  }
+  for (const name of missing) {
+    const hostDir = findPackageDirFrom(dirname(hostCli), name);
+    if (hostDir === undefined) {
+      throw new Error(`ak-role found the host pi at ${hostCli} but could not locate ${name} in its tree.`);
+    }
+    linkPackage(packageRoot, name, hostDir);
+  }
+  const unresolved = missingPackages(packageRoot);
+  if (unresolved.length > 0) {
+    throw new Error(
+      `ak-role linked the host Pi runtime from ${hostCli} but ${unresolved.join(", ")} remained unresolvable.`,
+    );
+  }
+}
+
+function missingPackages(packageRoot: string): HostProvidedPackage[] {
+  return HOST_PROVIDED_PACKAGES.filter((name) => findPackageDirFrom(packageRoot, name) === undefined);
+}
+
+/** Ancestor node_modules walk — the package-directory half of bare-specifier lookup. */
+function findPackageDirFrom(startDir: string, name: string): string | undefined {
+  let dir = startDir;
+  while (true) {
+    const candidate = join(dir, "node_modules", ...name.split("/"));
+    if (existsSync(join(candidate, "package.json"))) {
+      return realpathSync(candidate);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}
+
+function findHostPiCli(env: NodeJS.ProcessEnv): string | undefined {
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (dir === "") {
+      continue;
+    }
+    const candidate = join(dir, "pi");
+    if (existsSync(candidate)) {
+      return realpathSync(candidate);
+    }
+  }
+  return undefined;
+}
+
+function linkPackage(packageRoot: string, name: HostProvidedPackage, targetDir: string): void {
+  const linkPath = join(packageRoot, "node_modules", ...name.split("/"));
+  mkdirSync(dirname(linkPath), { recursive: true });
+  const existing = lstatSync(linkPath, { throwIfNoEntry: false });
+  if (existing !== undefined) {
+    if (!existing.isSymbolicLink()) {
+      throw new Error(
+        `ak-role found ${linkPath} present but unresolvable; refusing to replace a non-symlink install.`,
+      );
+    }
+    rmSync(linkPath);
+  }
+  try {
+    symlinkSync(targetDir, linkPath, "dir");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+  }
+}