@dieulc/workflow 0.9.1 → 0.10.0

package/provider-retarget.ts

@@ -0,0 +1,258 @@
+/**
+ * Workflow Extension — provider retarget for profiles.json / roles.json.
+ *
+ * The maintained Command Code provider registers as `commandcode`; the
+ * hand-written workaround often registers as `command-code`. Migrating a user
+ * should not mean hand-editing two JSON files and hoping every other key
+ * survives. This module rewrites only `{ provider, id }` model refs, preserves
+ * every other field, and backs up the original before writing.
+ *
+ * Pure parsing/formatting is separated from the filesystem so the tests can
+ * exercise both a dry run and an apply without touching a real profile.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type RetargetFileStatus =
+  "changed" | "would-change" | "unchanged" | "missing" | "invalid" | "blocked";
+
+export interface RetargetFileResult {
+  path: string;
+  status: RetargetFileStatus;
+  changes: number;
+  backup?: string;
+  error?: string;
+}
+
+export interface RetargetFilesResult {
+  oldProvider: string;
+  newProvider: string;
+  dryRun: boolean;
+  profiles: RetargetFileResult;
+  roles: RetargetFileResult;
+}
+
+export interface RetargetFilesInput {
+  profilesPath: string;
+  rolesPath: string;
+  oldProvider: string;
+  newProvider: string;
+  /** When true, compute only; never write. */
+  dryRun?: boolean;
+}
+
+export type RetargetDocumentResult =
+  { ok: true; text: string; changes: number } | { ok: false; error: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Rewrite every `{ provider: oldProvider, id: <string> }` object in a parsed
+ * profile/role document. Unknown keys and their order are preserved because the
+ * input is mutated in place and serialized with the same 2-space layout.
+ */
+function retargetValue(
+  value: unknown,
+  oldProvider: string,
+  newProvider: string,
+  counter: { changes: number },
+  depth: number,
+): void {
+  if (depth > 64) return;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      retargetValue(entry, oldProvider, newProvider, counter, depth + 1);
+    }
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (value.provider === oldProvider && typeof value.id === "string") {
+    value.provider = newProvider;
+    counter.changes += 1;
+  }
+  for (const entry of Object.values(value)) {
+    retargetValue(entry, oldProvider, newProvider, counter, depth + 1);
+  }
+}
+
+/**
+ * Retarget one JSON document. Malformed JSON or a non-object root is an error;
+ * the caller must not write in that case. A same-provider request is a no-op.
+ */
+export function retargetProviderDocument(
+  text: string,
+  oldProvider: string,
+  newProvider: string,
+): RetargetDocumentResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return {
+      ok: false,
+      error: `not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (!isRecord(parsed)) {
+    return { ok: false, error: "the document root is not a JSON object" };
+  }
+  if (oldProvider === newProvider) {
+    return { ok: true, text, changes: 0 };
+  }
+  const counter = { changes: 0 };
+  retargetValue(parsed, oldProvider, newProvider, counter, 0);
+  if (counter.changes === 0) return { ok: true, text, changes: 0 };
+  const trailing = text.endsWith("\n") ? "\n" : "";
+  return {
+    ok: true,
+    text: `${JSON.stringify(parsed, null, 2)}${trailing}`,
+    changes: counter.changes,
+  };
+}
+
+interface FilePlan {
+  result: RetargetFileResult;
+  nextText?: string;
+}
+
+function readPlan(
+  filePath: string,
+  oldProvider: string,
+  newProvider: string,
+): FilePlan {
+  if (!fs.existsSync(filePath)) {
+    return { result: { path: filePath, status: "missing", changes: 0 } };
+  }
+  let text: string;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    return {
+      result: {
+        path: filePath,
+        status: "invalid",
+        changes: 0,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+  const rewritten = retargetProviderDocument(text, oldProvider, newProvider);
+  if (!rewritten.ok) {
+    return {
+      result: {
+        path: filePath,
+        status: "invalid",
+        changes: 0,
+        error: rewritten.error,
+      },
+    };
+  }
+  if (rewritten.changes === 0) {
+    return { result: { path: filePath, status: "unchanged", changes: 0 } };
+  }
+  return {
+    result: {
+      path: filePath,
+      status: "would-change",
+      changes: rewritten.changes,
+    },
+    nextText: rewritten.text,
+  };
+}
+
+function applyPlan(plan: FilePlan): RetargetFileResult {
+  if (plan.result.status !== "would-change" || plan.nextText === undefined) {
+    return plan.result;
+  }
+  const filePath = plan.result.path;
+  const backup = `${filePath}.bak`;
+  const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.copyFileSync(filePath, backup);
+    fs.writeFileSync(temporary, plan.nextText, "utf8");
+    fs.renameSync(temporary, filePath);
+    return { ...plan.result, status: "changed", backup };
+  } catch (error) {
+    try {
+      fs.rmSync(temporary, { force: true });
+    } catch {
+      // Best-effort cleanup must not replace the write error.
+    }
+    return {
+      ...plan.result,
+      status: "invalid",
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Retarget both files. Two-phase: if either document is invalid, neither file
+ * is written. A dry run never writes or creates a backup.
+ */
+export function retargetProviderFiles(
+  input: RetargetFilesInput,
+): RetargetFilesResult {
+  const oldProvider = String(input.oldProvider ?? "").trim();
+  const newProvider = String(input.newProvider ?? "").trim();
+  const dryRun = input.dryRun === true;
+  const profiles = readPlan(input.profilesPath, oldProvider, newProvider);
+  const roles = readPlan(input.rolesPath, oldProvider, newProvider);
+  const invalid =
+    profiles.result.status === "invalid" || roles.result.status === "invalid";
+  const finish = (plan: FilePlan): RetargetFileResult => {
+    if (invalid) {
+      return plan.result.status === "invalid"
+        ? plan.result
+        : plan.result.status === "would-change"
+          ? {
+              ...plan.result,
+              status: "blocked",
+              error: "not written because the other document is invalid",
+            }
+          : plan.result;
+    }
+    if (dryRun) return plan.result;
+    return applyPlan(plan);
+  };
+  return {
+    oldProvider,
+    newProvider,
+    dryRun,
+    profiles: finish(profiles),
+    roles: finish(roles),
+  };
+}
+
+function statusLabel(result: RetargetFileResult): string {
+  switch (result.status) {
+    case "changed":
+      return `changed ${result.changes} model ref(s)${result.backup ? `; backup ${path.basename(result.backup)}` : ""}`;
+    case "would-change":
+      return `would change ${result.changes} model ref(s)`;
+    case "unchanged":
+      return "no model refs to change";
+    case "missing":
+      return "not present";
+    case "invalid":
+      return `not changed — ${result.error ?? "invalid document"}`;
+    case "blocked":
+      return `not written — ${result.error ?? "blocked by another invalid file"}`;
+  }
+}
+
+/** Human-readable command result; safe for `ctx.ui.notify`. */
+export function formatRetargetResult(result: RetargetFilesResult): string {
+  const verb = result.dryRun ? "Dry run" : "Retarget";
+  return [
+    `${verb}: provider ${result.oldProvider} → ${result.newProvider}`,
+    `  profiles.json  ${statusLabel(result.profiles)}`,
+    `  roles.json     ${statusLabel(result.roles)}`,
+    ...(result.dryRun
+      ? ["Add --apply to write; each changed file keeps a .bak."]
+      : []),
+  ].join("\n");
+}

package/review-handoff.ts

@@ -0,0 +1,125 @@
+/**
+ * Review Mode — Plannotator handoff decisions.
+ *
+ * The browser request itself is orchestrated in `index.ts` because it needs the
+ * Pi event bus, the current session context and the plan file. Everything that
+ * can be decided without those live objects lives here:
+ *
+ * - whether an open browser review still belongs to the current plan;
+ * - whether a pending gate must be superseded by a new round;
+ * - whether a settled manual round should hand off at all.
+ *
+ * Keeping these pure is what lets the extension tests cover the stale-gate and
+ * reload-recovery matrix without a host or a real browser.
+ */
+
+import type { ReviewExecutionResult } from "./review.ts";
+
+/** What opened the browser review. */
+export type ReviewHandoffSource = "auto" | "manual";
+
+/** The correlation persisted with `awaitingDecision`. */
+export interface PendingReviewHandoff {
+  reviewId: string;
+  planPath: string;
+  planHash: string;
+  source: ReviewHandoffSource;
+  requestId?: string;
+  reviewUrl?: string;
+  cycleId: number;
+  at: number;
+}
+
+export type ReviewHandoffRecovery =
+  | { action: "keep"; reason: "pending" }
+  | {
+      action: "apply";
+      approved: boolean;
+      feedback?: string;
+      savedPath?: string;
+    }
+  | { action: "clear"; reason: string };
+
+/**
+ * Decide what to do with a pending handoff after a reload.
+ *
+ * Plannotator's `review-status` is authoritative for whether the review is
+ * still open, but not for whether it still describes the current plan. A plan
+ * changed while the app was away makes both a pending tab and a completed
+ * decision stale, so the hash is checked before either is honoured.
+ */
+export function reviewHandoffRecovery(input: {
+  status: "pending" | "completed" | "missing";
+  approved?: boolean;
+  feedback?: string;
+  savedPath?: string;
+  pendingHash?: string;
+  currentHash?: string;
+}): ReviewHandoffRecovery {
+  if (input.status === "missing") {
+    return {
+      action: "clear",
+      reason: "the browser review is no longer available",
+    };
+  }
+  if (
+    input.pendingHash !== undefined &&
+    input.currentHash !== undefined &&
+    input.pendingHash !== input.currentHash
+  ) {
+    return {
+      action: "clear",
+      reason: "the plan changed since the review opened",
+    };
+  }
+  if (input.status === "pending") {
+    return { action: "keep", reason: "pending" };
+  }
+  return {
+    action: "apply",
+    approved: input.approved === true,
+    ...(input.feedback !== undefined ? { feedback: input.feedback } : {}),
+    ...(input.savedPath !== undefined ? { savedPath: input.savedPath } : {}),
+  };
+}
+
+/**
+ * True when a pending browser gate cannot belong to the round about to start.
+ *
+ * `force` is for an automatic round start (a new round must never inherit an
+ * older gate) and for `/review`: both are an explicit supersede even when the
+ * plan hash happens to match.
+ */
+export function pendingHandoffIsStale(input: {
+  awaiting: boolean;
+  force?: boolean;
+  pendingCycleId?: number;
+  currentCycleId?: number;
+  pendingPlanHash?: string;
+  nextPlanHash?: string;
+}): boolean {
+  if (input.awaiting !== true) return false;
+  if (input.force === true) return true;
+  if (
+    input.pendingCycleId !== undefined &&
+    input.currentCycleId !== undefined &&
+    input.pendingCycleId !== input.currentCycleId
+  ) {
+    return true;
+  }
+  return (
+    input.pendingPlanHash !== undefined &&
+    input.nextPlanHash !== undefined &&
+    input.pendingPlanHash !== input.nextPlanHash
+  );
+}
+
+/**
+ * A manual `/review` hands off when the round settled one way or another.
+ * A pause is resumed later; an abort is an explicit exit.
+ */
+export function shouldHandoffManualResult(
+  result: Pick<ReviewExecutionResult, "outcome">,
+): boolean {
+  return result.outcome !== "paused" && result.outcome !== "aborted";
+}

package/review-recovery.ts

@@ -0,0 +1,65 @@
+/**
+ * Review Mode — provider recovery classification.
+ *
+ * The SDK already owns the retryable-provider-error table
+ * (`isRetryableAssistantError`). Reusing it keeps Review Mode aligned with the
+ * agent's own retry policy instead of maintaining a second regex that drifts
+ * when a gateway adds a new transient-error spelling.
+ *
+ * A few failures are explicitly not recoverable by switching models:
+ * user aborts, missing auth, model-not-found, invalid requests and context
+ * overflow (the latter can be a different, larger-context model, but it is not
+ * a stream cut and must not loop through the fallback chain).
+ */
+
+import {
+  isRetryableAssistantError,
+  type AssistantMessage,
+} from "@earendil-works/pi-ai";
+
+const NON_RECOVERABLE_PATTERNS: readonly RegExp[] = [
+  /^request was aborted$/i,
+  /^aborted$/i,
+  /\bno api key\b/i,
+  /\bmodel\b.*\bnot\b.*\bfound\b/i,
+  /\binvalid[_\s-]?request\b/i,
+  /\bcontext\b.*\b(?:overflow|too long|window exceeded)\b/i,
+  /\bprompt\b.*\btoo long\b/i,
+];
+
+function asAssistantError(message: string): AssistantMessage {
+  return {
+    role: "assistant",
+    content: [],
+    api: "openai-completions",
+    provider: "reviewer",
+    model: "reviewer",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "error",
+    errorMessage: message,
+    timestamp: Date.now(),
+  } as unknown as AssistantMessage;
+}
+
+/**
+ * True when the reviewer's failed run is a transient provider/transport failure
+ * worth another model. Delegates the transient table to the SDK; only the
+ * deterministic non-recoverable shapes above short-circuit it.
+ */
+export function isRecoverableProviderFailure(message: string | undefined): boolean {
+  const text = String(message ?? "").trim();
+  if (!text) return false;
+  if (NON_RECOVERABLE_PATTERNS.some((pattern) => pattern.test(text))) return false;
+  try {
+    return isRetryableAssistantError(asAssistantError(text));
+  } catch {
+    return false;
+  }
+}