@mgiles/perk 1.0.1

package/extension/doors/address.ts

@@ -0,0 +1,360 @@
+// The warm `/address` door (the review loop). Classify-then-act: a spawned read-only child
+// (the borrowed `pi-subagents` engine running perk's `perk.review-classifier` agent) fetches +
+// classifies the PR feedback in ISOLATION, so the verbose GitHub JSON never enters this session;
+// the PARENT applies fixes (judgment + edits stay here) and resolves the threads through this
+// deterministic batched op.
+//
+// `resolve_review_threads` is the mechanical half: it DELEGATES the GitHub mutation to the Python
+// cold door (`perk pr resolve-threads` — mutations canonical in Python) via the shared cold-door
+// client (`runColdDoor` — the batch rides the run-scratch stdin channel), then
+// appends `last_review_batch` to `perk:workflow-state`. Never throws (soft `details.ok`, mirrors
+// submitPr).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import { type PlanRef, readPlanRef } from "../substrate/cache.ts";
+import {
+  booleanField,
+  type ColdJson,
+  nullableStringField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { loadPerkConfig } from "../substrate/config.ts";
+import { render } from "../substrate/prompts.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import {
+  arrayParam,
+  numberParam,
+  objectParam,
+  paramsOf,
+  stringParam,
+  type ToolParams,
+} from "../substrate/toolParams.ts";
+import { appendWorkflowState, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report } from "../surfaces/report.ts";
+
+interface ThreadInput {
+  thread_id: string;
+  comment?: string;
+}
+
+interface ResolveCounts {
+  actionable?: number;
+  informational?: number;
+  praise?: number;
+  question?: number;
+}
+
+interface ResolveParams {
+  threads: ThreadInput[];
+  pr?: number;
+  counts?: ResolveCounts;
+}
+
+/** The four known `counts` keys (recorded into workflow-state — strict-decoded). */
+const COUNT_KEYS = ["actionable", "informational", "praise", "question"] as const;
+
+/** Decode the optional `counts` object; null = present-but-mistyped (a key or the object). */
+function decodeCounts(p: ToolParams): ResolveCounts | undefined | null {
+  const raw = objectParam(p, "counts");
+  if (raw === undefined) return undefined;
+  if (raw === null) return null;
+  const counts: ResolveCounts = {};
+  for (const key of COUNT_KEYS) {
+    const value = numberParam(raw, key);
+    if (value === null) return null;
+    if (value !== undefined) counts[key] = value;
+  }
+  return counts;
+}
+
+/**
+ * Decode unknown tool-call params into `ResolveParams` (the tool-boundary seam).
+ * `threads` absent or non-array decodes to `[]` (so the existing empty-batch `bad_input` arm
+ * fires); any malformed ROW → null — whole-batch refusal, since resolving a guessed subset of
+ * threads is a durable GitHub mutation. `pr`/`counts` mistyped → null (recorded state).
+ */
+export function decodeResolveParams(params: unknown): ResolveParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const rawThreads = arrayParam(p, "threads");
+  const threads: ThreadInput[] = [];
+  if (Array.isArray(rawThreads)) {
+    for (const item of rawThreads) {
+      const row = paramsOf(item);
+      if (row === null) return null;
+      const threadId = stringParam(row, "thread_id");
+      const comment = stringParam(row, "comment");
+      if (typeof threadId !== "string" || comment === null) return null;
+      threads.push({ thread_id: threadId, comment });
+    }
+  }
+  const pr = numberParam(p, "pr");
+  if (pr === null) return null;
+  const counts = decodeCounts(p);
+  if (counts === null) return null;
+  return { threads, pr, counts };
+}
+
+/** One per-thread outcome row from the cold door's batch result. */
+export interface ThreadResultRow {
+  thread_id: string;
+  success: boolean;
+  comment_added: boolean;
+  error?: string | null;
+}
+
+/** The ok-arm fields. */
+export interface ResolveOk {
+  results: ThreadResultRow[];
+  resolved_thread_ids: string[];
+}
+
+/** The partial-failure branch carries the per-thread detail on the fail arm too. */
+export interface ResolveFailExtras {
+  results?: ThreadResultRow[];
+  resolved_thread_ids?: string[];
+}
+
+export type ResolveResult = Result<ResolveOk, ResolveFailExtras>;
+
+/**
+ * Narrow the cold door's `results` array to per-thread rows. Strict per row on `thread_id`,
+ * `success`, `comment_added`; lenient on the report-only `error` (wrong-typed coerces to null).
+ * Any malformed row → null (uncertainty ⇒ no half-rendered partial table).
+ */
+function decodeRows(payload: ColdJson): ThreadResultRow[] | null {
+  const raw = payload.results;
+  if (!Array.isArray(raw)) return null;
+  const rows: ThreadResultRow[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) return null;
+    const row = item as ColdJson;
+    const threadId = stringField(row, "thread_id");
+    const success = booleanField(row, "success");
+    const commentAdded = booleanField(row, "comment_added");
+    if (threadId === undefined || success === undefined || commentAdded === undefined) return null;
+    rows.push({
+      thread_id: threadId,
+      success,
+      comment_added: commentAdded,
+      error: nullableStringField(row, "error") ?? null,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Resolve a batch of review threads (the parent's mechanical resolve step). Delegates to the Python
+ * cold door; returns a soft result (never throws). On success, records `last_review_batch`.
+ */
+export async function resolveReviewThreads(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  params: ResolveParams,
+): Promise<ResolveResult> {
+  const fail = failFor(ctx, "address", "resolve_review_threads");
+
+  const threads = Array.isArray(params?.threads) ? params.threads : [];
+  if (threads.length === 0) {
+    return fail("no threads to resolve (pass { threads: [{thread_id, comment?}] })", "bad_input");
+  }
+  const batch = threads.map((t) => ({ thread_id: t.thread_id, comment: t.comment ?? null }));
+
+  const r = await runColdDoor<ThreadResultRow[]>(pi, ctx, ["pr", "resolve-threads", "--json"], {
+    label: "perk pr resolve-threads",
+    decode: decodeRows,
+    stdin: {
+      flag: "--batch",
+      content: `${JSON.stringify(batch, null, 2)}\n`,
+      filename: `resolve-batch-${Date.now()}.json`,
+    },
+  });
+
+  if (!r.ok) {
+    // A partial/failed batch is loud-but-soft: surface the per-thread detail, do not throw. The
+    // detail rides the failure envelope's payload; absent/malformed rows ⇒ plain fail (advisory
+    // drop — never a half-rendered partial table).
+    const rows = r.payload !== undefined ? decodeRows(r.payload) : null;
+    if (r.payload === undefined || rows === null) return fail(r.message, r.errorType);
+    const resolvedIds = rows.filter((row) => row.success).map((row) => row.thread_id);
+    const failed = rows.filter((row) => !row.success).length;
+    const error = stringField(r.payload, "message") ?? `${failed} thread(s) did not resolve`;
+    report(ctx, "address", "error", error, { alsoLog: true });
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Resolved ${resolvedIds.length}/${rows.length} thread(s); ${failed} failed.`,
+        },
+      ],
+      details: {
+        ok: false,
+        error,
+        error_type: stringField(r.payload, "error_type") ?? "partial_failure",
+        results: rows,
+        resolved_thread_ids: resolvedIds,
+      },
+    };
+  }
+
+  const results = r.data;
+  const resolvedIds = results.filter((row) => row.success).map((row) => row.thread_id);
+
+  // Record the batch (tier-3, best-effort-with-logging, idempotent, headless-safe). Strict
+  // read-back via rebuild — loud-but-non-fatal, the resolve already succeeded.
+  const recordedBatch = {
+    pr: params.pr ?? null,
+    counts: params.counts ?? null,
+    resolved_thread_ids: resolvedIds,
+    at: new Date().toISOString(),
+  };
+  appendWorkflowState(pi, ctx, {
+    data: { last_review_batch: recordedBatch },
+    field: "last_review_batch",
+    expected: recordedBatch,
+    scope: "address",
+    failure: "last_review_batch read-back failed",
+  });
+
+  return ok(`Resolved ${resolvedIds.length} review thread(s).`, {
+    results,
+    resolved_thread_ids: resolvedIds,
+  });
+}
+
+const TOOL_GUIDELINES = [
+  "Call resolve_review_threads only AFTER you have applied (and committed) fixes for the actionable items — it replies-then-resolves the threads you pass.",
+  "Pass threads as [{thread_id, comment?}] using the thread_id values from the perk.review-classifier child's structured output; the optional comment is posted as a reply before resolving.",
+  "Judgment and edits stay with you (the parent) — never delegate the fix; the spawned classifier is read-only and classification-only.",
+];
+
+/** Resolve the active plan-ref (worktree first, then the rebuilt workflow-state). The converged
+ * address body carries the PR identity, so the warm door must resolve a ref — and `/address`
+ * cannot function without one regardless (the classifier child's `perk pr feedback` hard-errors
+ * `no_plan_ref`). Mirrors `doors/learn.ts`'s helper. */
+function activePlanRef(ctx: ExtensionContext): PlanRef | null {
+  const fromWorktree = readPlanRef(ctx.cwd);
+  if (fromWorktree) return fromWorktree;
+  try {
+    const branch = branchOf(ctx);
+    return (rebuildWorkflowState(branch).active_plan_ref as PlanRef | null) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Inject the address-workflow guidance the model follows (the perk-address skill pointer is
+ * delivered by the skill-binding suffix — not hardcoded here). When `model` is set, the
+ * `perk.review-classifier` spawn carries an inline `model` override ([subagents] review-classifier);
+ * otherwise the agent's frontmatter default is used.
+ *
+ * The wording lives in the shared canonical templates `prompts/stages/address/*` rendered via the
+ * cross-plane render seam (contracts.md §8.31) — the warm door converges onto the SAME two
+ * templates as the cold `_address_prompt` and the worker `initialPromptFor("address")`. Branching
+ * stays in code: preview/action selects the template; classifier present/absent builds the
+ * `model_clause` render var. */
+export function addressGuidance(ref: PlanRef, preview: boolean, model?: string): string {
+  const modelClause = model
+    ? `, passing \`model: "${model}"\` on that call (the configured [subagents] review-classifier model)`
+    : "";
+  const variables = {
+    provider: ref.provider,
+    pr_id: String(ref.pr_id),
+    url: ref.url,
+    model_clause: modelClause,
+  };
+  return render(preview ? "stages/address/preview.md" : "stages/address/action.md", variables);
+}
+
+/** Register the warm door: the `resolve_review_threads` tool + the `/address` command. */
+export function registerAddress(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "resolve_review_threads",
+    label: "Resolve review threads",
+    description:
+      "Reply-then-resolve a batch of PR review threads after the actionable feedback is fixed. " +
+      "Delegates the GitHub mutation to the perk cold door; records the batch in workflow-state.",
+    promptSnippet: "Batch-resolve the addressed PR review threads",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["threads"],
+      properties: {
+        threads: {
+          type: "array",
+          description: "The threads to resolve.",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            required: ["thread_id"],
+            properties: {
+              thread_id: { type: "string", description: "The GraphQL node id of the thread." },
+              comment: { type: "string", description: "Optional reply posted before resolving." },
+            },
+          },
+        },
+        pr: { type: "number", description: "Optional PR number, recorded in last_review_batch." },
+        counts: {
+          type: "object",
+          description: "Optional classification counts, recorded in last_review_batch.",
+          additionalProperties: false,
+          properties: {
+            actionable: { type: "number" },
+            informational: { type: "number" },
+            praise: { type: "number" },
+            question: { type: "number" },
+          },
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodeResolveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "address",
+          "resolve_review_threads",
+        )("resolve_review_threads needs { threads: [{thread_id, comment?}] }", "bad_input");
+      }
+      return resolveReviewThreads(pi, ctx, decoded);
+    },
+  });
+
+  pi.registerCommand("address", {
+    description:
+      "Classify PR review feedback (isolated child) and resolve threads (submit → address). " +
+      "Pass --preview to classify only (take no action).",
+    handler: async (args, ctx) => {
+      const preview = /(^|\s)--preview(\s|$)/.test(args ?? "");
+      // `/address` needs an active plan-ref (the converged body carries the PR identity, and the
+      // classifier child's `perk pr feedback` hard-errors `no_plan_ref` without one). Mirror the
+      // /implement guard: warn and send no guidance rather than dead-end downstream.
+      const ref = activePlanRef(ctx);
+      if (ref == null) {
+        report(
+          ctx,
+          "address",
+          "warning",
+          "/address needs an active plan-ref — run `perk pr address` / after `/submit`.",
+        );
+        return;
+      }
+      const model = loadPerkConfig(ctx.cwd).subagents["review-classifier"];
+      const guidance = addressGuidance(ref, preview, model);
+      report(
+        ctx,
+        "address",
+        "info",
+        preview ? "--preview (classify only)" : "classify → fix → resolve",
+      );
+      // Inject the address-workflow guidance as a user message so the model starts the loop.
+      // `pi.sendUserMessage` always triggers a turn (the warm entry to the review loop). The
+      // perk-address pointer rides the skill-binding suffix.
+      pi.sendUserMessage(guidance + bindingSuffix(ctx.cwd, "stage:address"));
+    },
+  });
+}

package/extension/doors/askUser.ts

@@ -0,0 +1,194 @@
+// The universal, first-party `ask_user_question` tool. Lets a model interactively ask the
+// human a clarifying question during a turn (free-text, or a multiple-choice selection with an
+// always-present "type a custom answer" escape) and continues its turn with the answer. It is
+// NON-terminating and headless-fail-safe: with no interactive UI it returns a graceful no-user
+// sentinel instead of blocking (the AGENTS.md headless-fail-safe convention).
+//
+// To be callable *during planning* the tool name is added to `READ_ONLY_TOOLS` in toolGating.ts —
+// read-only mode otherwise hides every custom tool (the documented read-only gating trap). The
+// stricter SDK_READ_ONLY_TOOLS (headless child sessions) is intentionally NOT touched.
+//
+// REGISTRATION-TIME VACATING (askuser interface seam). `ask_user_question` is a pluggable provider
+// seam: a repo may select the foreign `@juicesharp/rpiv-ask-user-question` extension via
+// `[providers] askuser = "juicesharp-ask-user"`. That package registers a tool with the IDENTICAL
+// name `ask_user_question`. Tools (unlike commands) do NOT get `:N` suffixes — a same-named tool
+// replaces/warns by extension load order, which is non-deterministic. So under a foreign askuser
+// selection `registerAskUser` registers NOTHING (resolves the provider id once at factory time and
+// early-returns before `pi.registerTool`), leaving exactly one `ask_user_question` standing — the
+// same registration-time vacating proven on the plan seam (`registerPlanMode`). This is an
+// INTERFACE seam: there is no durable artifact to bridge (no `cache.plan-ref`/`perk:checkpoint`
+// analogue), so the adapter is vacate-only (`adapter: null`, no shim, no injected context); the
+// foreign tool self-documents via its own `promptGuidelines`. The foreign package is two-
+// directionally wired by `_converge_provider_packages` (installed only when selected, removed on
+// deselect), so under the default (`perk-ask-user`) the foreign package is never loaded and perk's
+// tool is the sole registrant — the default/fail-safe path is the hard guarantee (zero behavior
+// change).
+//
+// Structure: a pure, injectable core (`runAskUserQuestion`) over a minimal `AskUserUI` surface, plus
+// a thin `registerAskUser` wrapper — mirrors ciExecutor.ts's pure-core + injected-fakes testability.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadPerkConfig } from "../substrate/config.ts";
+import {
+  loadProviders,
+  PERK_ASK_USER_PROVIDER_ID,
+  resolveProviders,
+} from "../substrate/providers.ts";
+import { paramsOf, stringArrayParam, stringParam } from "../substrate/toolParams.ts";
+
+/** The always-appended escape entry on the select path so preset options never trap the user. */
+export const OTHER_CHOICE = "✏️ Other (type a custom answer)…";
+
+/** The minimal structural UI surface the core needs (a subset of `ctx.ui`). */
+export interface AskUserUI {
+  select(
+    title: string,
+    options: string[],
+    opts?: { signal?: AbortSignal },
+  ): Promise<string | undefined>;
+  input(
+    title: string,
+    placeholder?: string,
+    opts?: { signal?: AbortSignal },
+  ): Promise<string | undefined>;
+}
+
+/** The structured `details` surface for the tool result (failure/dismissal are non-throwing). */
+export interface AskDetails {
+  ok: boolean;
+  /** Whether a real user answer was captured (false for headless / dismissed / empty). */
+  answered: boolean;
+}
+
+/** A non-terminating tool result: the model continues its turn with the answer text. */
+export type AskResult = { content: { type: "text"; text: string }[]; details: AskDetails };
+
+const DISMISSED_TEXT = "(no answer — the user dismissed the prompt.)";
+const NO_UI_TEXT =
+  "(no interactive user available — proceed using your best judgment and state the assumption you made.)";
+const NO_QUESTION_TEXT = "ask_user_question: no question provided.";
+
+function answer(text: string, answered: boolean): AskResult {
+  return { content: [{ type: "text", text }], details: { ok: true, answered } };
+}
+
+/**
+ * The pure core: ask the user `question` (optionally with preset `options`) and resolve to a
+ * non-terminating tool result carrying the answer text. Fully offline-testable with a fake UI.
+ */
+export async function runAskUserQuestion(args: {
+  hasUI: boolean;
+  ui: AskUserUI;
+  question: string;
+  options?: string[];
+  signal?: AbortSignal;
+}): Promise<AskResult> {
+  const { hasUI, ui, options, signal } = args;
+  const question = (args.question ?? "").trim();
+  if (!question) return answer(NO_QUESTION_TEXT, false);
+  if (!hasUI) return answer(NO_UI_TEXT, false);
+
+  if (options && options.length > 0) {
+    const choice = await ui.select(question, [...options, OTHER_CHOICE], { signal });
+    if (choice === undefined) return answer(DISMISSED_TEXT, false);
+    if (choice === OTHER_CHOICE) {
+      const typed = await ui.input(question, undefined, { signal });
+      return typed === undefined ? answer(DISMISSED_TEXT, false) : answer(typed, true);
+    }
+    return answer(choice, true);
+  }
+
+  const typed = await ui.input(question, undefined, { signal });
+  return typed === undefined ? answer(DISMISSED_TEXT, false) : answer(typed, true);
+}
+
+/**
+ * Decode unknown `ask_user_question` tool-call params (the tool-boundary seam), in
+ * this tool's native graceful vocabulary: `question` absent OR mistyped → "" (routed into
+ * `runAskUserQuestion`'s NO_QUESTION_TEXT arm — answered: false, never throws/blocks); `options`
+ * mistyped → advisory-dropped to undefined (the free-text path) — a UI affordance, not a durable
+ * write (the decided exception to strict-fail).
+ */
+export function decodeAskUserParams(params: unknown): { question: string; options?: string[] } {
+  const p = paramsOf(params);
+  if (p === null) return { question: "" };
+  return {
+    question: stringParam(p, "question") ?? "",
+    // Advisory drop: a mistyped `options` falls back to the free-text path.
+    options: stringArrayParam(p, "options") ?? undefined,
+  };
+}
+
+const TOOL_GUIDELINES = [
+  "Prefer this during planning to resolve genuine ambiguity rather than guessing.",
+  "Ask ONE focused question at a time, and wait for the answer before the next.",
+  "Provide `options` when the answer is a choice — a free-text escape is always added.",
+  "Explore the codebase first: if a question is answerable from the code, read it instead of asking.",
+];
+
+/**
+ * The resolved `[providers] askuser` selection id for `cwd`. Fail-safe to the perk-ask-user
+ * reference: any load/resolution failure (corrupt bundled set, etc.) returns the reference id so
+ * perk's own tool keeps registering — the default path is the hard guarantee. Mirror of
+ * `resolvedPlanProviderId`.
+ */
+export function resolvedAskUserProviderId(cwd: string): string {
+  try {
+    return resolveProviders(loadPerkConfig(cwd).providers, loadProviders()).askuser.id;
+  } catch {
+    return PERK_ASK_USER_PROVIDER_ID;
+  }
+}
+
+/**
+ * Whether perk's own `ask_user_question` reference is the selected askuser provider for `cwd`. When
+ * a foreign askuser provider is selected via `[providers] askuser`, perk's tool vacates (registers
+ * nothing) so the foreign same-named tool is the sole registrant.
+ */
+export function isPerkAskUserReferenceSelected(cwd: string): boolean {
+  return resolvedAskUserProviderId(cwd) === PERK_ASK_USER_PROVIDER_ID;
+}
+
+/** Register the universal warm tool: `ask_user_question`. */
+export function registerAskUser(pi: ExtensionAPI): void {
+  // Registration-time vacating: under a foreign askuser selection register NOTHING (the foreign
+  // package's same-named tool is the sole registrant). Factory-time `process.cwd()` resolution
+  // mirrors `registerPlanMode`. The default/fail-safe path registers exactly as today.
+  if (resolvedAskUserProviderId(process.cwd()) !== PERK_ASK_USER_PROVIDER_ID) return;
+  pi.registerTool({
+    name: "ask_user_question",
+    label: "Ask user",
+    description:
+      "Ask the human user a clarifying question and return their answer. Supports a free-text " +
+      "prompt or a multiple-choice selection (a 'type a custom answer' escape is always added). " +
+      "NON-terminating: the turn continues with the answer. With no interactive UI it returns a " +
+      "no-user sentinel instead of blocking.",
+    promptSnippet: "Ask the user a clarifying question and get their answer",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["question"],
+      properties: {
+        question: { type: "string", description: "The question to ask the user." },
+        options: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional preset choices rendered as a selector; a free-text escape is always appended.",
+        },
+      },
+    },
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const { question, options } = decodeAskUserParams(params);
+      return runAskUserQuestion({
+        hasUI: ctx.hasUI,
+        ui: ctx.ui,
+        question,
+        options,
+        signal,
+      });
+    },
+  });
+}