@akagilnc/pi-workflow-roles 0.1.1751

package/src/public-cli/config.ts

@@ -0,0 +1,346 @@
+/**
+ * Persistent and effective per-seat model/thinking configuration for ak-role.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  AUTOMATIC_NAVIGATOR_SEAT,
+  PUBLIC_CALLABLE_ROLES,
+  PUBLIC_CONFIGURABLE_SEATS,
+  type ModelRef,
+  type PublicConfigurableSeat,
+  type PublicThinkingLevel,
+  publicStartupCandidates,
+} from "./registry.ts";
+
+export type CredentialProviders = {
+  "openai-codex": boolean;
+  xai: boolean;
+};
+
+export type SeatModelConfig = ModelRef;
+
+export type PublicCliConfig = {
+  seats: Partial<Record<PublicConfigurableSeat, SeatModelConfig>>;
+};
+
+export type EffectiveSource = "persistent" | "startup" | "invocation" | "unconfigured";
+
+export type EffectiveSeat = {
+  seat: PublicConfigurableSeat;
+  /** True when the seat is automatic Navigator attendance rather than caller-selected. */
+  automatic: boolean;
+  source: EffectiveSource;
+  selection?: SeatModelConfig;
+};
+
+export type InvocationModelOverride = {
+  model?: string;
+  thinking?: PublicThinkingLevel;
+};
+
+const THINKING_LEVELS = new Set<PublicThinkingLevel>([
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]);
+
+export function publicCliConfigPath(home: string = homedir()): string {
+  return join(home, ".ak-roles", "public-cli.json");
+}
+
+export async function loadPublicCliConfig(
+  home: string = homedir(),
+): Promise<PublicCliConfig> {
+  const path = publicCliConfigPath(home);
+  try {
+    const raw = await readFile(path, "utf8");
+    return parsePublicCliConfig(JSON.parse(raw));
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return { seats: {} };
+    }
+    throw error;
+  }
+}
+
+export async function savePublicCliConfig(
+  config: PublicCliConfig,
+  home: string = homedir(),
+): Promise<void> {
+  const path = publicCliConfigPath(home);
+  await mkdir(dirname(path), { recursive: true });
+  const normalized = parsePublicCliConfig(config);
+  await writeFile(path, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+}
+
+export function setPersistentSeatConfig(
+  config: PublicCliConfig,
+  seat: PublicConfigurableSeat,
+  selection: SeatModelConfig,
+): PublicCliConfig {
+  return {
+    seats: {
+      ...config.seats,
+      [seat]: { ...selection },
+    },
+  };
+}
+
+export function parseModelSpec(
+  spec: string,
+  fallbackThinking?: PublicThinkingLevel,
+): SeatModelConfig {
+  const trimmed = spec.trim();
+  if (!trimmed) {
+    throw new Error("model specification must be non-empty");
+  }
+  const thinkingSplit = trimmed.lastIndexOf(":");
+  let modelPart = trimmed;
+  let thinking: PublicThinkingLevel | undefined = fallbackThinking;
+  if (thinkingSplit > 0) {
+    const maybeThinking = trimmed.slice(thinkingSplit + 1);
+    if (THINKING_LEVELS.has(maybeThinking as PublicThinkingLevel)) {
+      thinking = maybeThinking as PublicThinkingLevel;
+      modelPart = trimmed.slice(0, thinkingSplit);
+    }
+  }
+  const slash = modelPart.indexOf("/");
+  if (slash <= 0 || slash === modelPart.length - 1) {
+    throw new Error(
+      `model specification must be provider/model[:thinking], got ${spec}`,
+    );
+  }
+  const provider = modelPart.slice(0, slash);
+  const model = modelPart.slice(slash + 1);
+  if (!thinking) {
+    throw new Error(
+      `model specification requires a thinking level (provider/model:thinking), got ${spec}`,
+    );
+  }
+  return { provider, model, thinking };
+}
+
+export function formatModelSpec(selection: SeatModelConfig): string {
+  return `${selection.provider}/${selection.model}:${selection.thinking}`;
+}
+
+function parsePublicCliConfig(value: unknown): PublicCliConfig {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("public CLI config must be an object");
+  }
+  const record = value as { seats?: unknown };
+  if (record.seats === undefined) {
+    return { seats: {} };
+  }
+  if (
+    record.seats === null ||
+    typeof record.seats !== "object" ||
+    Array.isArray(record.seats)
+  ) {
+    throw new Error("public CLI config.seats must be an object");
+  }
+  const seats: PublicCliConfig["seats"] = {};
+  for (const [key, raw] of Object.entries(
+    record.seats as Record<string, unknown>,
+  )) {
+    if (!(PUBLIC_CONFIGURABLE_SEATS as readonly string[]).includes(key)) {
+      throw new Error(`unknown configurable seat in config: ${key}`);
+    }
+    seats[key as PublicConfigurableSeat] = parseSeatModelConfig(raw, key);
+  }
+  return { seats };
+}
+
+function parseSeatModelConfig(value: unknown, seat: string): SeatModelConfig {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`config seat ${seat} must be an object`);
+  }
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.provider !== "string" || raw.provider.trim() === "") {
+    throw new Error(`config seat ${seat} requires provider`);
+  }
+  if (typeof raw.model !== "string" || raw.model.trim() === "") {
+    throw new Error(`config seat ${seat} requires model`);
+  }
+  if (
+    typeof raw.thinking !== "string" ||
+    !THINKING_LEVELS.has(raw.thinking as PublicThinkingLevel)
+  ) {
+    throw new Error(`config seat ${seat} requires a valid thinking level`);
+  }
+  return {
+    provider: raw.provider,
+    model: raw.model,
+    thinking: raw.thinking as PublicThinkingLevel,
+  };
+}
+
+export function providerConfigured(
+  credentials: CredentialProviders,
+  provider: string,
+): boolean {
+  if (provider === "openai-codex") return credentials["openai-codex"] === true;
+  if (provider === "xai") return credentials.xai === true;
+  return false;
+}
+
+/**
+ * Typed provider-credential absence for the public seat providers ak-role owns.
+ * Presence is read from auth.json shape (CredentialProviders), never from stderr prose.
+ * Returns undefined for unknown/custom providers (not this package's credential map).
+ */
+export function missingPublicProviderCredential(
+  provider: string,
+  credentials: CredentialProviders,
+): provider is "openai-codex" | "xai" {
+  if (provider !== "openai-codex" && provider !== "xai") return false;
+  return !providerConfigured(credentials, provider);
+}
+
+function pickStartupCandidate(
+  seat: PublicConfigurableSeat,
+  credentials: CredentialProviders,
+): SeatModelConfig | undefined {
+  for (const candidate of publicStartupCandidates(seat)) {
+    if (providerConfigured(credentials, candidate.provider)) {
+      return { ...candidate };
+    }
+  }
+  return undefined;
+}
+
+function resolveBaseSeat(
+  config: PublicCliConfig,
+  seat: PublicConfigurableSeat,
+  credentials: CredentialProviders,
+): EffectiveSeat {
+  const automatic = seat === AUTOMATIC_NAVIGATOR_SEAT;
+  const persistent = config.seats[seat];
+  if (persistent !== undefined) {
+    return {
+      seat,
+      automatic,
+      source: "persistent",
+      selection: { ...persistent },
+    };
+  }
+  const startup = pickStartupCandidate(seat, credentials);
+  if (startup !== undefined) {
+    return {
+      seat,
+      automatic,
+      source: "startup",
+      selection: startup,
+    };
+  }
+  return { seat, automatic, source: "unconfigured" };
+}
+
+export function resolveEffectiveSeat(
+  config: PublicCliConfig,
+  seat: PublicConfigurableSeat,
+  credentials: CredentialProviders,
+  invocation?: InvocationModelOverride,
+): EffectiveSeat {
+  const automatic = seat === AUTOMATIC_NAVIGATOR_SEAT;
+  const hasInvocation =
+    invocation !== undefined &&
+    (invocation.model !== undefined || invocation.thinking !== undefined);
+  if (!hasInvocation || invocation === undefined) {
+    return resolveBaseSeat(config, seat, credentials);
+  }
+
+  if (invocation.model !== undefined) {
+    const spec =
+      invocation.model.includes(":") || invocation.thinking === undefined
+        ? invocation.model
+        : `${invocation.model}:${invocation.thinking}`;
+    return {
+      seat,
+      automatic,
+      source: "invocation",
+      selection: parseModelSpec(spec),
+    };
+  }
+
+  const base = resolveBaseSeat(config, seat, credentials);
+  if (base.selection === undefined || invocation.thinking === undefined) {
+    return { seat, automatic, source: "unconfigured" };
+  }
+  return {
+    seat,
+    automatic,
+    source: "invocation",
+    selection: { ...base.selection, thinking: invocation.thinking },
+  };
+}
+
+export function effectiveSeatConfigurations(
+  config: PublicCliConfig,
+  credentials: CredentialProviders,
+  invocation?: InvocationModelOverride,
+): EffectiveSeat[] {
+  return PUBLIC_CONFIGURABLE_SEATS.map((seat) =>
+    resolveEffectiveSeat(config, seat, credentials, invocation),
+  );
+}
+
+/** Callable roles first (package order), then automatic Navigator. */
+export function listRolesForDisplay(
+  config: PublicCliConfig,
+  credentials: CredentialProviders,
+  invocation?: InvocationModelOverride,
+): EffectiveSeat[] {
+  const all = effectiveSeatConfigurations(config, credentials, invocation);
+  const callable = PUBLIC_CALLABLE_ROLES.map(
+    (role) => all.find((entry) => entry.seat === role)!,
+  );
+  const navigator = all.find((entry) => entry.seat === AUTOMATIC_NAVIGATOR_SEAT)!;
+  return [...callable, navigator];
+}
+
+/**
+ * Read configured credential presence from a Pi auth.json document.
+ * Only presence of a provider key matters for startup selection (#11).
+ */
+export function credentialProvidersFromAuthData(
+  data: unknown,
+): CredentialProviders {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return { "openai-codex": false, xai: false };
+  }
+  const record = data as Record<string, unknown>;
+  return {
+    "openai-codex": Object.prototype.hasOwnProperty.call(record, "openai-codex"),
+    xai: Object.prototype.hasOwnProperty.call(record, "xai"),
+  };
+}
+
+export async function loadCredentialProviders(
+  agentDir: string,
+): Promise<CredentialProviders> {
+  try {
+    const raw = await readFile(join(agentDir, "auth.json"), "utf8");
+    return credentialProvidersFromAuthData(JSON.parse(raw));
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return { "openai-codex": false, xai: false };
+    }
+    throw error;
+  }
+}

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

@@ -0,0 +1,355 @@
+/**
+ * Public Doctor Role run: admit Issue → retained case via #78 → explicit
+ * Internal activate → settle Terminal result (#113). One-shot; no resume path.
+ * Failure settlement reuses the #107 shared owner.
+ */
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  runExplicitInternalActivation,
+  type ExplicitInternalKnownFailure,
+  type ExplicitInternalPiRunner,
+  type ExplicitInternalPiResult,
+} from "./explicit-internal.ts";
+import { CliUsageError } from "./cli-errors.ts";
+import {
+  admitDoctorInvocation,
+  buildDoctorTransportPrompt,
+  type AdmittedDoctorInvocation,
+  type ParseDoctorArgvResult,
+} from "./invocation.ts";
+import {
+  type CredentialProviders,
+  type SeatModelConfig,
+} from "./config.ts";
+import {
+  missingCredentialPreDispatchFailure,
+  postRunMissingCredentialFailure,
+} from "./public-run-credentials.ts";
+import {
+  acquireRunWriterLease,
+  clearTypedProviderHttpObservation,
+  markRunAdmitted,
+  markRunRunning,
+  markRunTerminal,
+  RunWriterLeaseHeldError,
+  type RunWriterLease,
+} from "./run-lifecycle.ts";
+import {
+  classifyPostAdmissionFailure,
+  exitCodeForTerminalOutcome,
+  formatTerminalResult,
+  inspectJudgeSession,
+  isLawfulTypedTerminalOutcome,
+  presentFailureTerminal,
+  presentStructuralRejection,
+  resolveAuditedRunnerKnownFailure,
+  explicitInternalKnownFailureClassificationInput,
+  settleFailureTerminalResult,
+  trySettleDoctorTerminalResult,
+  trySettleComplianceAuditIncompleteTerminalResult,
+} from "./settlement.ts";
+import type { CliIo } from "./cli-io.ts";
+import type {
+  ControlledFailureCause,
+  TerminalResult,
+} from "./terminal.ts";
+
+export type DoctorRunEnv = {
+  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 Doctor run.
+ * Always --no-skills (Doctor forbids every Skill). Session under #78 book.
+ * Case path is the retained runs root — never a legacy case packet.
+ */
+export function buildDoctorActivationExtraArgs(
+  admitted: AdmittedDoctorInvocation,
+  options: {
+    model?: SeatModelConfig;
+    extraPiArgs?: readonly string[];
+  } = {},
+): string[] {
+  const prompt = buildDoctorTransportPrompt(admitted);
+  return [
+    "--no-skills",
+    "--no-prompt-templates",
+    "--no-themes",
+    "--no-context-files",
+    "--session",
+    admitted.sessionFile,
+    "--session-dir",
+    admitted.sessionDirectory,
+    ...(options.extraPiArgs ?? []),
+    "--ak-role",
+    "doctor",
+    "--ak-doctor-case",
+    admitted.caseRunsPath,
+    "--mode",
+    "json",
+    ...buildModelArgs(options.model),
+    prompt,
+  ];
+}
+
+async function presentControlledFailure(
+  admitted: AdmittedDoctorInvocation,
+  failureInput: {
+    timedOut: boolean;
+    code: number | null;
+    stderr: string;
+    thrown?: unknown;
+    knownFailure?: ExplicitInternalKnownFailure;
+  },
+  io: CliIo,
+): Promise<{
+  exitCode: number;
+  admitted: AdmittedDoctorInvocation;
+  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 }),
+  });
+
+  // Doctor does not support resume — always terminal.
+  await markRunTerminal(admitted.runDirectory).catch(() => undefined);
+
+  const terminal = await settleFailureTerminalResult(admitted, failure);
+  presentFailureTerminal(terminal, io);
+  return {
+    exitCode: exitCodeForTerminalOutcome(terminal.roleOutcome),
+    admitted,
+    terminal,
+  };
+}
+
+async function dispatchAdmittedDoctor(input: {
+  admitted: AdmittedDoctorInvocation;
+  env: DoctorRunEnv;
+  io: CliIo;
+  extraArgs: string[];
+  lease: RunWriterLease;
+}): Promise<{
+  exitCode: number;
+  admitted: AdmittedDoctorInvocation;
+  terminal?: TerminalResult;
+}> {
+  const { admitted, env, io, extraArgs, lease } = 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 trySettleDoctorTerminalResult(admitted);
+    } 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();
+  }
+}
+
+export async function runPublicDoctor(
+  argv: readonly string[],
+  env: DoctorRunEnv,
+  io: CliIo,
+  parseDoctorArgv: (args: readonly string[]) => ParseDoctorArgvResult,
+): Promise<{
+  exitCode: number;
+  admitted?: AdmittedDoctorInvocation;
+  terminal?: TerminalResult;
+}> {
+  let admitted: AdmittedDoctorInvocation;
+  try {
+    const parsed = parseDoctorArgv(argv);
+    admitted = await admitDoctorInvocation({
+      home: env.home,
+      cwd: env.cwd,
+      issueNumber: parsed.issueNumber,
+      instruction: parsed.instruction,
+      attachmentPaths: parsed.attachmentPaths,
+      ...(parsed.project === undefined ? {} : { project: parsed.project }),
+      ...(parsed.runs === undefined ? {} : { runs: parsed.runs }),
+      ...(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;
+  }
+
+  const extraArgs = buildDoctorActivationExtraArgs(admitted, {
+    ...(env.model === undefined ? {} : { model: env.model }),
+    ...(env.extraPiArgs === undefined ? {} : { extraPiArgs: env.extraPiArgs }),
+  });
+
+  return await dispatchAdmittedDoctor({
+    admitted,
+    env,
+    io,
+    extraArgs,
+    lease,
+  });
+}