@mgiles/perk 2.2.0 → 3.0.0

package/extension/worker/worker.ts

@@ -32,19 +32,17 @@ import { env } from "node:process";
 // re-export a thinking-level type (only `ThinkingLevelChangeEntry`).
 import type { Api, Model, ModelThinkingLevel as ThinkingLevel } from "@earendil-works/pi-ai";
 import {
-  AuthStorage,
   type CreateAgentSessionRuntimeFactory,
   createAgentSessionFromServices,
   createAgentSessionRuntime,
   createAgentSessionServices,
-  ModelRegistry,
+  ModelRuntime,
   resolveCliModel,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { planReadInstruction } from "../doors/lifecycleGates.ts";
 import { ensureRunScratch, type PlanRef, readPlanRef, runEventsPath } from "../substrate/cache.ts";
-import { loadPerkConfig } from "../substrate/config.ts";
 import { render } from "../substrate/prompts.ts";
 import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import { rebuildWorkflowState } from "../substrate/workflowState.ts";
@@ -94,10 +92,14 @@ export interface RunOutcome {
  * The structured run-event stream (contracts §8.12). A small, JSON-serializable,
  * **additive-stable** discriminated union keyed on `kind` (distinct from `DriveEvent.type`). Every
  * event carries a monotonic `seq` (0-based) and `t` (elapsed ms, same basis as
- * `RunOutcome.budget.elapsed_ms`). Future nodes may add variants/fields; existing ones keep meaning.
+ * `RunOutcome.budget.elapsed_ms`). Future nodes may add variants/fields; existing ones keep
+ * meaning — including deprecated variants that are no longer emitted (see `step_marker`).
  */
 export type RunEvent =
   | { kind: "run_started"; seq: number; t: number; run_id: string; stage: DriveStage }
+  // DEPRECATED — never emitted: the `[WIP:n]`/`[DONE:n]` marker protocol died with the
+  // checkpoints removal. Kept for additive-stable grammar — historical `events.ndjson` files
+  // may carry the variant (contracts §8.12).
   | { kind: "step_marker"; seq: number; t: number; marker: "wip" | "done"; step: number }
   | {
       kind: "tool_outcome";
@@ -137,8 +139,8 @@ export interface DriveStageOptions {
    * `undefined` ⇒ the SDK's settings-default resolution — unchanged behavior.
    */
   thinkingLevel?: ThinkingLevel;
-  authStorage?: AuthStorage;
-  modelRegistry?: ModelRegistry;
+  /** The canonical model/auth runtime (pi 0.84 `ModelRuntime`); default-created when absent. */
+  modelRuntime?: ModelRuntime;
   budget: DriveBudget;
   /** External cancellation; OR'd with the budget watchdog. */
   signal?: AbortSignal;
@@ -176,8 +178,6 @@ export interface DriveEvent {
      * sum: adding it would double-count.
      */
     usage?: { input?: number; output?: number; reasoning?: number };
-    /** Assistant text/content blocks (where `[WIP:n]`/`[DONE:n]` markers live). */
-    content?: unknown;
   };
 }
 
@@ -207,13 +207,14 @@ export interface DriveRuntimeLike {
 export interface DriveCounters {
   turns: number;
   tokens: number;
+  /** Latest submit-bearing evidence (standalone submit or the nested finalizer submit). */
   submitDetails: Record<string, unknown> | null;
-  resolveDetails: Record<string, unknown> | null;
+  finalizeDetails: Record<string, unknown> | null;
   modelError: { message: string } | null;
 }
 
 export function freshCounters(): DriveCounters {
-  return { turns: 0, tokens: 0, submitDetails: null, resolveDetails: null, modelError: null };
+  return { turns: 0, tokens: 0, submitDetails: null, finalizeDetails: null, modelError: null };
 }
 
 /** The natural-idle terminal classification (before watchdog/abort overrides). */
@@ -239,7 +240,7 @@ function detailsOf(result: unknown): Record<string, unknown> | null {
 /**
  * Fold one agent-session event into the running counters (pure). Counts `turn_end` turns, sums
  * assistant token usage (the `sumAssistantTokens` pattern in objective.ts), captures the `submit`
- * /`resolve_review_threads` terminal tool details, and records a post-acceptance model error
+ * /`finalize_address` terminal tool details, and records a post-acceptance model error
  * (assistant `message_end` with `stopReason:"error"`, surfaced with retry off — audit §B #4).
  *
  * The token sum is `input + output` ONLY: `usage.reasoning` is a subset of `output` on every
@@ -255,8 +256,19 @@ export function applyEvent(counters: DriveCounters, event: DriveEvent): void {
   }
   if (event.type === "tool_execution_end") {
     if (event.toolName === "submit") counters.submitDetails = detailsOf(event.result);
-    else if (event.toolName === "resolve_review_threads") {
-      counters.resolveDetails = detailsOf(event.result);
+    else if (event.toolName === "finalize_address") {
+      const details = detailsOf(event.result);
+      counters.finalizeDetails = details;
+      // A finalizer carries the submit that immediately preceded resolution. Recording it into the
+      // same latest-evidence slot means a later standalone submit naturally supersedes it after a
+      // conflict-resolver re-drive.
+      const nestedSubmit = details?.submit;
+      if (nestedSubmit && typeof nestedSubmit === "object" && !Array.isArray(nestedSubmit)) {
+        // The finalizer only exposes this nested block after submit succeeded; restore the
+        // success marker stripped from its nested public shape so a later failed standalone
+        // submit cannot accidentally satisfy the address completion predicate.
+        counters.submitDetails = { ok: true, ...(nestedSubmit as Record<string, unknown>) };
+      }
     }
     return;
   }
@@ -276,13 +288,14 @@ export function budgetTripped(counters: DriveCounters, budget: DriveBudget): boo
  * Classify a natural-idle terminal from the captured state (pure). `modelError` wins (post-
  * acceptance error, §B #4); else the stage success predicate:
  *  - implement: a successful `submit` carrying a `pr` → completed/submit_tool;
- *  - address: `resolve_review_threads` ok AND `last_review_batch` appended → completed/address_resolved;
+ *  - address: `finalize_address` ok, `last_review_batch` appended, and the latest submit-bearing
+ *    evidence is successful and not definitively unmergeable → completed/address_resolved;
  *  - otherwise the agent went idle without completing the stage → failed/agent_idle_incomplete.
  */
 export function evaluateTerminal(args: {
   stage: DriveStage;
   submitDetails: Record<string, unknown> | null;
-  resolveSucceeded: boolean;
+  finalizeDetails: Record<string, unknown> | null;
   lastReviewBatchPresent: boolean;
   modelError: { message: string } | null;
 }): TerminalVerdict {
@@ -331,8 +344,20 @@ export function evaluateTerminal(args: {
     };
   }
 
-  // address
-  if (args.resolveSucceeded && args.lastReviewBatchPresent) {
+  // address. `applyEvent` keeps submitDetails as the latest submit-bearing evidence: the nested
+  // finalizer submit first, then a later standalone submit from the conflict-resolution re-drive.
+  const nestedSubmit = args.finalizeDetails?.submit;
+  const fallbackSubmit: Record<string, unknown> | null =
+    nestedSubmit && typeof nestedSubmit === "object" && !Array.isArray(nestedSubmit)
+      ? { ok: true, ...(nestedSubmit as Record<string, unknown>) }
+      : null;
+  const effectiveSubmit = args.submitDetails ?? fallbackSubmit;
+  if (
+    args.finalizeDetails?.ok === true &&
+    args.lastReviewBatchPresent &&
+    effectiveSubmit?.ok === true &&
+    effectiveSubmit.mergeable !== false
+  ) {
     return {
       status: "completed",
       terminal_signal: "address_resolved",
@@ -346,18 +371,20 @@ export function evaluateTerminal(args: {
     terminal_signal: "agent_idle_incomplete",
     pr: null,
     errorType: "incomplete",
-    errorMessage: "address drive went idle without resolving feedback (no last_review_batch).",
+    errorMessage:
+      "address drive went idle without fully finalizing feedback " +
+      "(publication, thread resolution, and last_review_batch are required).",
   };
 }
 
 /**
  * The post-bind preflight rule (pure): the stage's terminating perk tool must be registered —
- * `implement` → `submit`, `address` → `resolve_review_threads`. Returns the required tool name
+ * `implement` → `submit`, `address` → `finalize_address`. Returns the required tool name
  * when absent, else `null`. Deliberately does NOT require the `subagent` tool for `address` — the
  * subagent-under-worker live smoke stays the §8.11 carried risk.
  */
 export function missingTerminatingTool(stage: DriveStage, toolNames: string[]): string | null {
-  const required = stage === "implement" ? "submit" : "resolve_review_threads";
+  const required = stage === "implement" ? "submit" : "finalize_address";
   return toolNames.includes(required) ? null : required;
 }
 
@@ -406,39 +433,6 @@ export function assembleOutcome(args: {
 
 // --- run-event helpers (offline-testable) ---------------------------------------------
 
-/**
- * Extract `[WIP:n]`/`[DONE:n]` markers from assistant text in **textual appearance order** (pure).
- * A single combined, case-insensitive regex so interleaved markers (`[WIP:2]` before `[DONE:1]` in
- * the same message) emit in that order — unlike checkpoints.ts's separate `extractWip/DoneSteps`
- * lists, which lose cross-marker order. Returns `[]` when there are no markers.
- */
-export function extractStepMarkers(text: string): { marker: "wip" | "done"; step: number }[] {
-  const out: { marker: "wip" | "done"; step: number }[] = [];
-  for (const m of text.matchAll(/\[(WIP|DONE):(\d+)\]/gi)) {
-    const step = Number(m[2]);
-    if (Number.isFinite(step)) {
-      out.push({ marker: (m[1] ?? "").toLowerCase() === "done" ? "done" : "wip", step });
-    }
-  }
-  return out;
-}
-
-/** Flatten a `DriveEvent`'s assistant `message.content` (string | `{type:'text',text}[]`) to text. */
-export function assistantText(event: DriveEvent): string {
-  const content = event.message?.content;
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content
-      .map((b) => {
-        const block = b as { type?: string; text?: string };
-        return block.type === "text" && typeof block.text === "string" ? block.text : "";
-      })
-      .filter(Boolean)
-      .join("\n");
-  }
-  return "";
-}
-
 /**
  * Compute a `tool_outcome` `{ tool, ok, summary }` from a `tool_execution_end` `DriveEvent` (pure).
  * `ok` = `details.ok === true` when the result carries a `details.ok` boolean, else `!isError`.
@@ -524,14 +518,11 @@ export function defaultEventSink(worktree: string, runId: string): RunEventSink
  *
  * The `address` wording lives in the shared canonical template `prompts/stages/address/action.md`
  * rendered via the cross-plane render seam (contracts.md §8.31); the worker has no preview path
- * (preview is a warm/cold flag only), so it always renders the action body. The classifier
- * present/absent split builds the `model_clause` render var in code.
+ * (preview is a warm/cold flag only), so it always renders the action body. The classify step is
+ * the `classify_review_feedback` tool, which reads the configured classifier model at execute
+ * time — nothing model-shaped rides the prompt.
  */
-export function initialPromptFor(
-  stage: DriveStage,
-  planRef: PlanRef | null,
-  classifierModel?: string,
-): string | null {
+export function initialPromptFor(stage: DriveStage, planRef: PlanRef | null): string | null {
   if (planRef === null) return null;
   const provider = String(planRef.provider ?? "");
   const prId = String(planRef.pr_id ?? "");
@@ -541,15 +532,7 @@ export function initialPromptFor(
     return render("stages/implement.md", { provider, pr_id: prId, url, read_cmd: readCmd });
   }
   // address
-  const modelClause = classifierModel
-    ? `, passing \`model: "${classifierModel}"\` on that call (the configured [models.subagents] review-classifier model)`
-    : "";
-  return render("stages/address/action.md", {
-    provider,
-    pr_id: prId,
-    url,
-    model_clause: modelClause,
-  });
+  return render("stages/address/action.md", { provider, pr_id: prId, url });
 }
 
 // --- bind / subscribe management (Gap 1) --------------------------------------------------------
@@ -619,9 +602,8 @@ async function defaultCreateRuntime(
     const services = await createAgentSessionServices({
       cwd: factoryOpts.cwd,
       agentDir: factoryOpts.agentDir,
-      authStorage: resolved.authStorage,
       settingsManager,
-      modelRegistry: resolved.modelRegistry,
+      modelRuntime: resolved.modelRuntime,
     });
     const result = await createAgentSessionFromServices({
       services,
@@ -660,24 +642,23 @@ async function defaultCreateRuntime(
 // --- model/auth resolution (Gap 5) --------------------------------------------------------------
 
 export interface ResolvedAuth {
-  authStorage: AuthStorage;
-  modelRegistry: ModelRegistry;
+  modelRuntime: ModelRuntime;
   /** The EXPLICIT model only; `undefined` defers the pick to the SDK at session creation. */
   model: Model<Api> | undefined;
 }
 
 /**
- * Resolve auth; returns null (never throws) when no model is available at all. The model is NOT
- * pre-pinned from the registry: an `undefined` model lets `createAgentSession` run its own
- * initial-model resolution (settings `defaultModel` → pi's curated per-provider defaults → first
- * available), which picks a current-generation model instead of the registry's
- * alphabetically-first (= oldest) entry.
+ * Resolve auth; returns null (never throws a domain error) when no model is available at all.
+ * The model is NOT pre-pinned from the runtime: an `undefined` model lets `createAgentSession`
+ * run its own initial-model resolution (settings `defaultModel` → pi's curated per-provider
+ * defaults → first available), which picks a current-generation model instead of the catalogue's
+ * alphabetically-first (= oldest) entry. Async because pi 0.84's `ModelRuntime.create` is async
+ * (the default creation stays offline — `allowModelNetwork` defaults false).
  */
-export function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
-  const authStorage = opts.authStorage ?? AuthStorage.create();
-  const modelRegistry = opts.modelRegistry ?? ModelRegistry.create(authStorage);
-  if (!opts.model && modelRegistry.getAvailable().length === 0) return null;
-  return { authStorage, modelRegistry, model: opts.model };
+export async function resolveAuth(opts: DriveStageOptions): Promise<ResolvedAuth | null> {
+  const modelRuntime = opts.modelRuntime ?? (await ModelRuntime.create());
+  if (!opts.model && modelRuntime.getAvailableSnapshot().length === 0) return null;
+  return { modelRuntime, model: opts.model };
 }
 
 /** What an explicit `--model` flag resolves to (a thin projection of `ResolveCliModelResult`). */
@@ -700,12 +681,12 @@ export interface ResolvedWorkerModel {
  */
 export function resolveWorkerModel(
   raw: string | undefined,
-  modelRegistry: ModelRegistry,
+  modelRuntime: ModelRuntime,
 ): ResolvedWorkerModel {
   if (!raw) {
     return { model: undefined, thinkingLevel: undefined, warning: undefined, error: undefined };
   }
-  const result = resolveCliModel({ cliModel: raw, modelRegistry });
+  const result = resolveCliModel({ cliModel: raw, modelRuntime });
   if (result.model === undefined && result.error === undefined) {
     return {
       model: undefined,
@@ -753,7 +734,9 @@ export async function driveStage(
     return outcome;
   };
 
-  const resolved = resolveAuth(opts);
+  // Auth/model resolution is a production-path concern only: with an injected runtime factory
+  // (tests) the drive never touches the default `ModelRuntime.create` (no host file reads).
+  const resolved = deps.createRuntime ? null : await resolveAuth(opts);
   if (resolved === null && !deps.createRuntime) {
     // A zero-turn run is still observable: emit a `run_started` + `run_finished` pair.
     emitter.emit({ kind: "run_started", run_id: runId, stage: opts.stage });
@@ -772,10 +755,6 @@ export async function driveStage(
   const bindManager = createBindManager(headlessBinding(), (event) => {
     applyEvent(counters, event);
     if (event.type === "turn_end") {
-      // Emit this turn's `[WIP:n]`/`[DONE:n]` markers in textual appearance order (one event each).
-      for (const m of extractStepMarkers(assistantText(event))) {
-        emitter.emit({ kind: "step_marker", marker: m.marker, step: m.step });
-      }
       if (budgetTripped(counters, opts.budget)) trip("budget");
     } else if (event.type === "tool_execution_end") {
       const o = toolOutcomeOf(event);
@@ -908,7 +887,7 @@ function classify(
   return evaluateTerminal({
     stage: opts.stage,
     submitDetails: counters.submitDetails,
-    resolveSucceeded: counters.resolveDetails?.ok === true,
+    finalizeDetails: counters.finalizeDetails,
     lastReviewBatchPresent,
     modelError: counters.modelError,
   });
@@ -916,6 +895,5 @@ function classify(
 
 /** Convenience: re-derive the initial prompt for a prepared worktree (reads its `cache.plan-ref`). */
 export function initialPromptForWorktree(worktree: string, stage: DriveStage): string | null {
-  const classifierModel = loadPerkConfig(worktree).subagents["review-classifier"];
-  return initialPromptFor(stage, readPlanRef(worktree), classifierModel);
+  return initialPromptFor(stage, readPlanRef(worktree));
 }

package/extension/workerMain.ts

@@ -9,7 +9,7 @@
 // stderr), and exits 0 on `completed` else non-zero. Runs as `.ts` under node 22 type-stripping.
 
 import { argv, env, exit, stderr, stdout } from "node:process";
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { runEventsPath, workflowDir } from "./substrate/cache.ts";
 import {
   type DriveBudget,
@@ -99,9 +99,8 @@ async function main(): Promise<number> {
   // pi's CLI semantics (fuzzy matching, `provider/pattern`, a `:thinking` suffix —
   // `resolveWorkerModel`), else the SDK's default resolution at session creation (settings
   // default → pi's per-provider defaults → first available) — the deferral is unchanged.
-  const authStorage = AuthStorage.create();
-  const modelRegistry = ModelRegistry.create(authStorage);
-  const resolved = resolveWorkerModel(parsed.model, modelRegistry);
+  const modelRuntime = await ModelRuntime.create();
+  const resolved = resolveWorkerModel(parsed.model, modelRuntime);
   if (resolved.error) {
     stderr.write(`perk worker: ${resolved.error}\n`);
     return 2;
@@ -121,8 +120,7 @@ async function main(): Promise<number> {
       initialPrompt,
       model: resolved.model,
       thinkingLevel: resolved.thinkingLevel,
-      authStorage,
-      modelRegistry,
+      modelRuntime,
       budget: parsed.budget,
       signal: controller.signal,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgiles/perk",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "perk Pi extension (session interior) for the plan-oriented workflow.",
   "license": "MIT",
   "repository": {
@@ -29,10 +29,18 @@
       "./extension/index.ts"
     ]
   },
+  "workspaces": [
+    "docs/site"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "biome check extension",
-    "format": "biome format --write extension"
+    "lint": "biome check extension docs/site tools",
+    "format": "biome format --write extension docs/site tools",
+    "docs:dev": "npm run dev --workspace docs/site",
+    "docs:build": "npm run build --workspace docs/site",
+    "docs:preview": "npm run preview --workspace docs/site",
+    "docs:typecheck": "npm run typecheck --workspace docs/site",
+    "docs:check": "npm run check --workspace docs/site"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -42,11 +50,18 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@earendil-works/pi-ai": "0.80.5",
-    "@earendil-works/pi-coding-agent": "0.80.5",
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "22.19.19",
     "diff": "8.0.4",
+    "typebox": "1.3.7",
     "typescript": "6.0.3",
     "yaml": "2.9.0"
+  },
+  "allowScripts": {
+    "@google/genai@1.52.0": true,
+    "protobufjs@7.6.4": true,
+    "protobufjs@7.6.2": true
   }
 }

package/prompts/README.md

@@ -18,6 +18,25 @@ Templates are rendered by jinja2 (Python) and a vendored TS subset (the extensio
 are loaded by explicit name through the resolver — never by scanning the directory, so
 this README is a durable doc, not a template.
 
+The workflow-first inventory of these templates alongside skills, agent definitions, tool
+contracts, injected contexts, and code-owned guidance lives in the generated
+[`docs/design/prose-prompt-map.md`](../docs/design/prose-prompt-map.md). Its authored graph is the
+source for capability relationships, session-shape assemblies, concerns, and generated lineage.
+
+## Layering — one statement of contract
+
+A compact, **non-normative** summary of the layering rule for prompt authors — the canonical
+rule is [`shared/contracts.md` §8.57](../shared/contracts.md). Per stage, each contract
+statement has exactly one canonical carrier; every other surface points at it, never restates
+it. The **launch statement** (classified by delivery call site — cold seed, warm guidance turn,
+headless primer — never by template path) states the flow once per session shape; **injected
+contexts** carry live state + pointers, never a restatement; **adapter blocks** carry only the
+provider-surface delta; the **bound skill** is the read-on-demand detail tier. One named
+exception: the `plan` stage launches idle, so its mode context
+(`contexts/plan-authoring.md`) is its designated flow carrier. Per-template byte budgets are
+CI-enforced by `tests/test_prompt_surface_budgets.py` (constants + derivation beside the
+checks; the canonical rule stays §8.57).
+
 ## Frozen template grammar
 
 The templates use a deliberately tiny, **frozen** subset of jinja syntax — the canonical