@mgiles/perk 2.2.0 → 3.0.0

package/extension/substrate/providers.ts

@@ -2,13 +2,12 @@
 //
 // Twin of perk/substrate/providers.py: both planes parse the SAME bundled file (no codegen). This is the
 // THIRD parsed cross-plane contract (after registry.yaml and bindings.yaml). It is the SUPPORTED
-// SET — the catalog of plan/todo/askuser/footer/web providers perk knows how to wire —
+// SET — the catalog of plan/footer/web providers perk knows how to wire —
 // distinct from the per-repo SELECTION (the flat `[providers]` table in .perk/config.toml).
 //
 // The Python CLI is the authoritative validator (perk/substrate/providers.py); this side does a thin
 // structural parse only — no deep content validation here. `resolveProviders` is CONSUMED by
-// `planMode` (plan-seam registration-time vacating when a foreign plan provider is selected); the
-// todo-seam runtime deferral is likewise live.
+// `planMode` (plan-seam registration-time vacating when a foreign plan provider is selected).
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -24,12 +23,10 @@ export interface Provider {
   packageFilter?: Record<string, unknown>;
 }
 
-export const PROVIDER_SEAMS = ["plan", "todo", "askuser", "footer", "web"] as const;
+export const PROVIDER_SEAMS = ["plan", "footer", "web"] as const;
 
 /** The bundled reference provider ids (the behavior-preserving no-config defaults per seam). */
 export const PERK_PLAN_PROVIDER_ID = "perk-plan";
-export const PERK_CHECKPOINTS_PROVIDER_ID = "perk-checkpoints";
-export const PERK_ASK_USER_PROVIDER_ID = "perk-ask-user";
 export const PERK_FOOTER_PROVIDER_ID = "perk-footer";
 
 /** The foreign `@tombell/pi-plan` plan-provider id. */
@@ -38,12 +35,6 @@ export const TOMBELL_PLAN_PROVIDER_ID = "tombell-plan";
 /** The foreign `@plannotator/pi-extension` plan-provider id (augment-posture adapter selection check). */
 export const PLANNOTATOR_PLAN_PROVIDER_ID = "plannotator-plan";
 
-/** The foreign `@juicesharp/rpiv-todo` todo-provider id. */
-export const JUICESHARP_TODO_PROVIDER_ID = "juicesharp-todo";
-
-/** The foreign `@juicesharp/rpiv-ask-user-question` askuser-provider id (vacate-only interface seam). */
-export const JUICESHARP_ASK_USER_PROVIDER_ID = "juicesharp-ask-user";
-
 /** The foreign `pi-powerline-footer` footer-provider id (vacate-only interface seam). */
 export const POWERLINE_FOOTER_PROVIDER_ID = "powerline-footer";
 
@@ -106,8 +97,6 @@ export function loadProviders(): Provider[] {
  */
 export interface ResolvedProviders {
   plan: Provider;
-  todo: Provider;
-  askuser: Provider;
   footer: Provider;
   web: Provider;
   issues: string[];
@@ -124,20 +113,6 @@ export interface ResolvedProviders {
  */
 const REFERENCE_FALLBACKS: Record<(typeof PROVIDER_SEAMS)[number], Provider> = {
   plan: { id: PERK_PLAN_PROVIDER_ID, seam: "plan", package: null, adapter: null, default: true },
-  todo: {
-    id: PERK_CHECKPOINTS_PROVIDER_ID,
-    seam: "todo",
-    package: null,
-    adapter: null,
-    default: true,
-  },
-  askuser: {
-    id: PERK_ASK_USER_PROVIDER_ID,
-    seam: "askuser",
-    package: null,
-    adapter: null,
-    default: true,
-  },
   footer: {
     id: PERK_FOOTER_PROVIDER_ID,
     seam: "footer",
@@ -183,8 +158,6 @@ function byId(set: Provider[]): Map<string, Provider> {
 export function resolveProviders(
   selection: {
     plan?: string;
-    todo?: string;
-    askuser?: string;
     footer?: string;
     web?: string;
   },
@@ -205,7 +178,7 @@ export function resolveProviders(
     return def;
   };
 
-  const resolveSeam = (seam: "plan" | "todo" | "askuser" | "footer" | "web"): Provider => {
+  const resolveSeam = (seam: "plan" | "footer" | "web"): Provider => {
     const selected = selection[seam];
     if (selected == null) return requireDefault(seam);
     const provider = ids.get(selected);
@@ -222,8 +195,6 @@ export function resolveProviders(
 
   return {
     plan: resolveSeam("plan"),
-    todo: resolveSeam("todo"),
-    askuser: resolveSeam("askuser"),
     footer: resolveSeam("footer"),
     web: resolveSeam("web"),
     issues,

package/extension/substrate/resources.ts

@@ -39,3 +39,14 @@ export function perkVersion(): string {
     return "0.0.0";
   }
 }
+
+/**
+ * The vintage-stamp filter over a perkVersion() value: the version, or undefined for the
+ * "0.0.0" failure sentinel. A `perk_version` stamp claims an EXACT session vintage
+ * (contracts §8.3 — the session-audit read side treats it as the exact basis), so the
+ * self-confessed-unknown sentinel must not masquerade as one; omitting the stamp leaves the
+ * session on the honest timestamp-estimate arm.
+ */
+export function versionStamp(version: string): string | undefined {
+  return version === "0.0.0" ? undefined : version;
+}

package/extension/substrate/result.ts

@@ -55,18 +55,26 @@ export function ok<D extends object>(
  * `failFor(ctx, scope, label)` when the content label differs from the report scope). Each call
  * reports loudly (`report(ctx, scope, "error", message, { alsoLog: true })`) and returns the
  * canonical soft failure: content `"<label> failed: <message>"`, details
- * `{ ok: false, error: message, error_type: errorType }`, no `terminate`.
+ * `{ ok: false, error: message, error_type: errorType }`, no `terminate`. `X` is the
+ * `FailDetails` extras hook: `failFor<X>(…)` lets a call attach module-specific fail details
+ * (spread AFTER `error`/`error_type`) — e.g. the learn wave's attempt receipts. Extras stay
+ * optional, so existing extras-free call sites are unchanged.
  */
-export function failFor(
+export function failFor<X extends object = Record<never, never>>(
   target: ReportTarget,
   scope: string,
   label: string = scope,
-): (message: string, errorType: string) => FailResult {
-  return (message, errorType) => {
+): (message: string, errorType: string, extras?: X) => FailResult<X> {
+  return (message, errorType, extras) => {
     report(target, scope, "error", message, { alsoLog: true });
     return {
       content: [{ type: "text", text: `${label} failed: ${message}` }],
-      details: { ok: false, error: message, error_type: errorType },
+      details: {
+        ok: false,
+        error: message,
+        error_type: errorType,
+        ...(extras ?? {}),
+      } as FailDetails<X>,
     };
   };
 }

package/extension/substrate/sessionData.ts

@@ -33,10 +33,10 @@
 // loadable under `node --test`; accepts a minimal structural ctx (`BranchSource & { cwd }`).
 
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import type { ReportTarget } from "../surfaces/report.ts";
-import { sessionDataDir } from "./cache.ts";
+import { atomicWriteFileSync, sessionDataDir } from "./cache.ts";
 import {
   appendWorkflowState,
   type BranchSource,
@@ -115,7 +115,7 @@ export function writeSessionData(
   if (dir === null) return null;
   const path = join(dir, name);
   try {
-    writeFileSync(path, content, "utf8");
+    atomicWriteFileSync(path, content);
   } catch (error) {
     console.error(`perk: warning: could not write session data ${path}: ${error}`);
     return null;

package/extension/substrate/sessionPointers.ts

@@ -13,9 +13,9 @@
 // wedge the save/launch/drive it rides on. Node builtins + cache.ts + git.ts only (loads under
 // `node --test`).
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { runScratchDir } from "./cache.ts";
+import { atomicWriteFileSync, runScratchDir } from "./cache.ts";
 import { mainCheckoutRoot } from "./git.ts";
 
 export const SESSION_POINTERS_FILE = "session-pointers.json";
@@ -121,7 +121,7 @@ export function recordSessionPointer(
     record[klass][site] = pointer;
     const dir = runScratchDir(root, runId);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(sessionPointersPath(root, runId), serialize(record), "utf8");
+    atomicWriteFileSync(sessionPointersPath(root, runId), serialize(record));
     return true;
   } catch (error) {
     console.error(`perk: warning: could not record session pointer (${klass}.${site}): ${error}`);

package/extension/substrate/structuredOutput.ts

@@ -2,16 +2,19 @@
 //
 // pi-ai has no dedicated JSON-mode; structured output is done via tool calling. This module wraps
 // that idiom into two pure, dependency-light, NEVER-throwing helpers:
-//   - `resolveModelAuth(ctx)` reuses the session's configured + authenticated model (the sanctioned
-//     `ModelRegistry.getApiKeyAndHeaders` path), and
-//   - `completeStructured(opts)` builds a single-tool `Context`, calls `complete`, and validates the
-//     returned tool-call arguments against a TypeBox schema.
+//   - `resolveModelAuth(ctx)` reuses the session's configured + authenticated model (the compat
+//     `ModelRegistry.getApiKeyAndHeaders` path — the fallback for hosts without registry
+//     dispatch), and
+//   - `completeStructured(opts)` builds a single-tool `Context`, completes it (via the injected
+//     registry `dispatch` when the host provides one, else the compat `complete`), and validates
+//     the returned tool-call arguments against a TypeBox schema.
 // Both report failure via a soft `{ ok:false, error }` outcome — no throws ever reach the caller, so
 // every consumer can stay fail-safe with a deterministic fallback. The first consumer is
 // `extension/factories/planTitle.ts` (LLM-generated plan-issue titles).
 
 import {
   type Api,
+  type AssistantMessage,
   type Context,
   type Model,
   type Static,
@@ -24,21 +27,54 @@ import {
 // keeps the types. Pi's extension loader aliases both the root and /compat to the compat entry.
 import { complete } from "@earendil-works/pi-ai/compat";
 
-/** Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth. */
+/**
+ * Registry dispatch (mirrors pi ≥ 0.84's `ModelRegistry.complete`): pi owns final request
+ * assembly — resolved auth, nullable headers, credential-resolved `baseUrl`, provider `env` —
+ * end to end. Feature-detect it (`typeof … === "function"`); absent on older hosts.
+ */
+export type ModelDispatch = (
+  model: Model<Api>,
+  context: Context,
+  options: { signal?: AbortSignal; timeoutMs?: number },
+) => Promise<AssistantMessage>;
+
+/**
+ * Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth.
+ * Header values mirror pi-ai's `ProviderHeaders` (`string | null` — null is a header-deletion
+ * marker); `baseUrl`/`env` mirror pi 0.84's `ResolvedRequestAuth`.
+ */
 export interface ModelAuthContext {
   model: Model<Api> | undefined;
   modelRegistry: {
-    getApiKeyAndHeaders(
-      model: Model<Api>,
-    ): Promise<
-      { ok: true; apiKey?: string; headers?: Record<string, string> } | { ok: false; error: string }
+    getApiKeyAndHeaders(model: Model<Api>): Promise<
+      | {
+          ok: true;
+          apiKey?: string;
+          headers?: Record<string, string | null>;
+          baseUrl?: string;
+          env?: Record<string, string>;
+        }
+      | { ok: false; error: string }
     >;
+    /** pi ≥ 0.84 registry dispatch; absent on older hosts (feature-detected, never assumed). */
+    complete?(
+      model: Model<Api>,
+      context: Context,
+      options?: { signal?: AbortSignal; timeoutMs?: number },
+    ): Promise<AssistantMessage>;
   };
 }
 
 /** Resolved model + auth, or a soft failure (no model / unresolved auth). */
 export type ResolvedModelAuth =
-  | { ok: true; model: Model<Api>; apiKey?: string; headers?: Record<string, string> }
+  | {
+      ok: true;
+      model: Model<Api>;
+      apiKey?: string;
+      headers?: Record<string, string | null>;
+      baseUrl?: string;
+      env?: Record<string, string>;
+    }
   | { ok: false; error: string };
 
 /** The generic structured-output outcome — soft success/failure, never a throw. */
@@ -60,7 +96,14 @@ export async function resolveModelAuth(ctx: ModelAuthContext): Promise<ResolvedM
   try {
     const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
     if (!auth.ok) return { ok: false, error: auth.error };
-    return { ok: true, model, apiKey: auth.apiKey, headers: auth.headers };
+    return {
+      ok: true,
+      model,
+      apiKey: auth.apiKey,
+      headers: auth.headers,
+      baseUrl: auth.baseUrl,
+      env: auth.env,
+    };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }
@@ -79,8 +122,17 @@ export interface CompleteStructuredOptions<S extends TSchema> {
   instruction: string;
   /** The payload (e.g. the document to summarize/classify). */
   input: string;
+  /**
+   * Registry dispatch (pi ≥ 0.84). When present it REPLACES the compat `complete` +
+   * apiKey/headers assembly below — pi owns auth end to end, including the credential-resolved
+   * `baseUrl` the fallback path cannot carry.
+   */
+  dispatch?: ModelDispatch;
   apiKey?: string;
-  headers?: Record<string, string>;
+  /** `string | null` mirrors pi-ai's `ProviderHeaders` — a null value deletes a default header. */
+  headers?: Record<string, string | null>;
+  /** Provider-scoped environment values (pi 0.84 `ResolvedRequestAuth.env`), fallback path only. */
+  env?: Record<string, string>;
   signal?: AbortSignal;
   timeoutMs?: number;
 }
@@ -114,14 +166,21 @@ export async function completeStructured<S extends TSchema>(
     tools: [tool],
   };
 
-  let msg: Awaited<ReturnType<typeof complete>>;
+  // Primary: registry dispatch (pi ≥ 0.84 owns auth/headers/baseUrl/env). Fallback: the compat
+  // `complete` with caller-resolved auth — it forwards apiKey/headers/env but has NO `baseUrl`
+  // option, so a credential-resolved endpoint is silently dropped on old hosts (the fallback's
+  // named, pre-existing limitation; the dispatch path is the fix).
+  let msg: AssistantMessage;
   try {
-    msg = await complete(opts.model, context, {
-      apiKey: opts.apiKey,
-      headers: opts.headers,
-      signal: opts.signal,
-      timeoutMs: opts.timeoutMs,
-    });
+    msg = opts.dispatch
+      ? await opts.dispatch(opts.model, context, { signal: opts.signal, timeoutMs: opts.timeoutMs })
+      : await complete(opts.model, context, {
+          apiKey: opts.apiKey,
+          headers: opts.headers,
+          env: opts.env,
+          signal: opts.signal,
+          timeoutMs: opts.timeoutMs,
+        });
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : String(err) };
   }

package/extension/substrate/terminalLaunch.ts

@@ -51,7 +51,7 @@ function interactiveShellWrap(
   command: string,
 ): string {
   const shell =
-    env.SHELL !== undefined && env.SHELL.startsWith("/")
+    env.SHELL?.startsWith("/") === true
       ? env.SHELL
       : platform === "darwin"
         ? "/bin/zsh"