@mgiles/perk 1.0.1

package/extension/substrate/runId.ts

@@ -0,0 +1,49 @@
+// Mint perk run ids in the TS plane (contracts.md §8.2 mint doctrine).
+// Warm sessions with no identity (decideClaim's `none` path) mint their own ULID;
+// cold launches still mint in Python (perk/state/run_id.py) and hand off via PERK_RUN_ID.
+//
+// Hand-rolled spec-conformant ULID (no npm dependency): a 48-bit `Date.now()` timestamp
+// + 80 bits of `randomBytes(10)`, Crockford base32, 26 chars (10 time + 16 randomness).
+// Per-process monotonicity is NOT required — one mint per session.
+
+import { randomBytes } from "node:crypto";
+
+/** Crockford base32 alphabet (no I/L/O/U) — the ULID character set. */
+export const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/** Mint a spec-conformant ULID: 10 time chars (48-bit ms) + 16 randomness chars (80 bits). */
+export function mintRunId(): string {
+  // Time component: most-significant-first base32 of Date.now() (2^48 ms ≈ year 10889).
+  let ms = Date.now();
+  const time = new Array<string>(10);
+  for (let i = 9; i >= 0; i--) {
+    time[i] = CROCKFORD[ms % 32] as string;
+    ms = Math.floor(ms / 32);
+  }
+  // Randomness component: 10 bytes → 16 five-bit chunks, standard bit-walk.
+  const bytes = randomBytes(10);
+  let rand = "";
+  let acc = 0;
+  let bits = 0;
+  for (const byte of bytes) {
+    acc = (acc << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      rand += CROCKFORD[(acc >> bits) & 31];
+      acc &= (1 << bits) - 1;
+    }
+  }
+  return time.join("") + rand;
+}
+
+/** Decode the first 10 chars of a ULID to epoch milliseconds (test aid). */
+export function decodeTime(runId: string): number {
+  let ms = 0;
+  for (const ch of runId.slice(0, 10)) {
+    const value = CROCKFORD.indexOf(ch);
+    if (value < 0) throw new Error(`invalid ULID time character: ${ch}`);
+    ms = ms * 32 + value;
+  }
+  return ms;
+}

package/extension/substrate/sessionData.ts

@@ -0,0 +1,229 @@
+// The session-data accessor seam (contracts.md §8.1).
+//
+// Every run-scoped session artifact lives under `.pi/workflow/scratch/runs/<run_id>/data/`, and
+// ALL session-data paths flow through this module (interior) or `perk/state/cache.py` (exterior) — the
+// guard tests (cacheGuard.test.ts / tests/test_cache_guard.py) forbid manual construction of the
+// `scratch`/`runs` path segments anywhere else.
+//
+// Seam doctrine — degrade gracefully, never invent identity:
+// - The current run_id resolves from the rebuilt `perk:workflow-state` and degrades to `null`
+//   when the session has no identity. CONTRAST with `coldDoor.activeRunId`, which falls back to
+//   a `cold-door-<ts>` stamp for stdin-staging debuggability: a stamp here would orphan data
+//   dirs and break run_id-keyed provenance, so this seam never stamps.
+// - Reads return `null` on absence (normal, branchable) and on I/O errors (with a loud stderr
+//   warning); writes return the written path or `null` on failure (with a warning). Never
+//   throws — a broken disk must not wedge a session.
+//
+// Provenance doctrine (contracts §8.1/§8.3) — the pointer makes it consumable:
+// - A session artifact is *consumable* only via its `session_artifacts` pointer
+//   ({run_id, name, path, digest, at}) in the rebuilt `perk:workflow-state`. A bare file on
+//   disk is never trusted: `writeSessionArtifact` returns a path only once BOTH the file and
+//   the pointer landed; `readSessionArtifact` validates the on-disk bytes against the rebuilt
+//   pointer and fails open to `null` when validation refuses.
+// - Validation always derives the path from `run_id` + `name` through the seam; the recorded
+//   `pointer.path` is informational/debugging only and is never dereferenced (workflow-state
+//   entries are reconstructable from untrusted session history).
+// - The four lifecycle guarantees: REWIND ⇒ the rebuilt branch carries an older pointer while
+//   disk holds newer bytes ⇒ digest mismatch ⇒ refusal. FORK ⇒ the child run_id no longer
+//   matches the inherited pointer's ⇒ silent refusal (no inheritance; fresh dir).
+//   RELOAD/COMPACTION ⇒ same run_id ⇒ pointer + dir persist. CONCURRENT SESSIONS ⇒ run_id
+//   keying isolates dirs and pointers alike — validation never crosses run_ids.
+//
+// Imports only node builtins + cache.ts + workflowState.ts + report.ts so the module stays
+// 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 { join, relative } from "node:path";
+import type { ReportTarget } from "../surfaces/report.ts";
+import { sessionDataDir } from "./cache.ts";
+import {
+  appendWorkflowState,
+  type BranchSource,
+  branchOf,
+  type EntrySink,
+  rebuildWorkflowState,
+  type SessionArtifactPointer,
+} from "./workflowState.ts";
+
+/** Minimal context slice — `ExtensionContext` satisfies it (the `BranchSource` precedent). */
+export interface SessionDataCtx extends BranchSource {
+  cwd: string;
+}
+
+/**
+ * The current session's run_id from the rebuilt workflow-state; `null` when the session has no
+ * identity (no stamp fallback — see the header).
+ */
+export function activeSessionRunId(ctx: SessionDataCtx): string | null {
+  try {
+    const runId = rebuildWorkflowState(branchOf(ctx)).run_id;
+    if (typeof runId === "string" && runId.length > 0) return runId;
+  } catch {
+    // a throwing getBranch means no resolvable identity — degrade to null
+  }
+  return null;
+}
+
+/** The current session's data dir as a pure path (no mkdir); `null` without a run_id. */
+export function activeSessionDataDir(ctx: SessionDataCtx): string | null {
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) return null;
+  return sessionDataDir(ctx.cwd, runId);
+}
+
+/** Ensure (mkdir -p) the current session's data dir; `null` + a warning on failure. */
+export function ensureSessionDataDir(ctx: SessionDataCtx): string | null {
+  const dir = activeSessionDataDir(ctx);
+  if (dir === null) return null;
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (error) {
+    console.error(`perk: warning: could not create session data dir ${dir}: ${error}`);
+    return null;
+  }
+  return dir;
+}
+
+/**
+ * Read a session-data file; `null` on no run_id or an absent file (normal, branchable), and on
+ * read errors (with a stderr warning). Never throws.
+ */
+export function readSessionData(ctx: SessionDataCtx, name: string): string | null {
+  const dir = activeSessionDataDir(ctx);
+  if (dir === null) return null;
+  const path = join(dir, name);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    console.error(`perk: warning: could not read session data ${path}: ${error}`);
+    return null;
+  }
+}
+
+/**
+ * Write a session-data file (creating the data dir lazily); returns the absolute path, or
+ * `null` + a stderr warning on any failure. Never throws.
+ */
+export function writeSessionData(
+  ctx: SessionDataCtx,
+  name: string,
+  content: string,
+): string | null {
+  const dir = ensureSessionDataDir(ctx);
+  if (dir === null) return null;
+  const path = join(dir, name);
+  try {
+    writeFileSync(path, content, "utf8");
+  } catch (error) {
+    console.error(`perk: warning: could not write session data ${path}: ${error}`);
+    return null;
+  }
+  return path;
+}
+
+/** The session-artifact digest convention: `sha256:` + lowercase hex of the UTF-8 bytes. */
+export function digestSessionData(content: string): string {
+  return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+
+/** Per-name pointer identity: same run_id + same digest (the custom-equals comparator). */
+function artifactMapsEqual(
+  rebuilt: Record<string, SessionArtifactPointer> | null | undefined,
+  expected: Record<string, SessionArtifactPointer> | null | undefined,
+): boolean {
+  const a = rebuilt ?? {};
+  const b = expected ?? {};
+  const names = Object.keys(b);
+  if (Object.keys(a).length !== names.length) return false;
+  return names.every(
+    (name) => a[name]?.run_id === b[name]?.run_id && a[name]?.digest === b[name]?.digest,
+  );
+}
+
+/**
+ * Write a session artifact AND record its provenance pointer in `perk:workflow-state`.
+ * Returns the absolute written path only when the artifact is *fully recorded* (file written,
+ * read back, digested, pointer strict-appended); `null` on any failure — the seam/module has
+ * already warned, and an orphan file (pointer-append failure) is gitignored scratch for the
+ * GC to prune. Never throws.
+ */
+export function writeSessionArtifact(
+  sink: EntrySink,
+  ctx: SessionDataCtx & ReportTarget,
+  name: string,
+  content: string,
+): string | null {
+  const written = writeSessionData(ctx, name, content);
+  if (written === null) return null; // already warned; never point at an unwritten file
+
+  // Digest the bytes as read back from disk — catches encoding/disk surprises.
+  const readBack = readSessionData(ctx, name);
+  if (readBack === null) {
+    console.error(`perk: warning: session artifact ${written} unreadable after write`);
+    return null;
+  }
+
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) return null; // unreachable after a successful write; belt-and-braces
+  const pointer: SessionArtifactPointer = {
+    run_id: runId,
+    name,
+    path: relative(ctx.cwd, written),
+    digest: digestSessionData(readBack),
+    at: new Date().toISOString(),
+  };
+
+  // Per-field LWW: each append must carry the WHOLE merged map so sibling artifacts survive.
+  const merged: Record<string, SessionArtifactPointer> = {
+    ...(rebuildWorkflowState(branchOf(ctx)).session_artifacts ?? {}),
+    [name]: pointer,
+  };
+  const ok = appendWorkflowState(sink, ctx, {
+    data: { session_artifacts: merged },
+    field: "session_artifacts",
+    expected: merged,
+    scope: "session-data",
+    failure: `session_artifacts pointer read-back failed for ${name}`,
+    equals: artifactMapsEqual,
+  });
+  return ok ? written : null;
+}
+
+/**
+ * Read a session artifact through its provenance pointer; fail-open `null` when validation
+ * refuses. Tiering: no identity / no pointer / run_id mismatch (the designed fork-isolation
+ * path) → silent `null`; pointer matches but the file is absent, unreadable, or its digest
+ * differs (rewind, tamper) → stderr warning + `null`. The path is always DERIVED from
+ * `run_id` + `name` via the seam — `pointer.path` is never dereferenced. Never throws.
+ */
+export function readSessionArtifact(
+  ctx: SessionDataCtx,
+  name: string,
+): { path: string; content: string } | null {
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) return null;
+  let pointer: SessionArtifactPointer | undefined;
+  try {
+    pointer = rebuildWorkflowState(branchOf(ctx)).session_artifacts?.[name];
+  } catch {
+    return null;
+  }
+  if (pointer === undefined) return null;
+  if (pointer.run_id !== runId) return null; // fork / concurrent isolation — by design, silent
+
+  const path = join(sessionDataDir(ctx.cwd, runId), name);
+  const content = readSessionData(ctx, name);
+  if (content === null) {
+    console.error(`perk: warning: session artifact ${name} has a pointer but no file at ${path}`);
+    return null;
+  }
+  if (digestSessionData(content) !== pointer.digest) {
+    console.error(
+      `perk: warning: session artifact ${path} digest mismatch (rewound or modified) — refusing`,
+    );
+    return null;
+  }
+  return { path, content };
+}

package/extension/substrate/structuredOutput.ts

@@ -0,0 +1,141 @@
+// A small, reusable structured-output substrate over `@earendil-works/pi-ai`.
+//
+// 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.
+// 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 Context,
+  complete,
+  type Model,
+  type Static,
+  type Tool,
+  type ToolCall,
+  type TSchema,
+  validateToolCall,
+} from "@earendil-works/pi-ai";
+
+/** Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth. */
+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 }
+    >;
+  };
+}
+
+/** 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: false; error: string };
+
+/** The generic structured-output outcome — soft success/failure, never a throw. */
+export interface StructuredOutcome<T> {
+  ok: boolean;
+  value?: T;
+  error?: string;
+}
+
+/**
+ * Resolve the session's model and its API key + headers via the sanctioned `ModelRegistry`. Returns
+ * `{ ok:false }` when no model is configured or auth cannot be resolved (offline, no key). Pure
+ * apart from the single `getApiKeyAndHeaders` await, which is wrapped so a throw becomes a soft
+ * failure.
+ */
+export async function resolveModelAuth(ctx: ModelAuthContext): Promise<ResolvedModelAuth> {
+  const model = ctx.model;
+  if (!model) return { ok: false, error: "no model configured for this session" };
+  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 };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export interface CompleteStructuredOptions<S extends TSchema> {
+  model: Model<Api>;
+  /** TypeBox schema describing the structured result (becomes the single tool's parameters). */
+  schema: S;
+  /** The forced tool's name (the model is instructed to call it). */
+  toolName: string;
+  toolDescription: string;
+  /** Optional system prompt. */
+  system?: string;
+  /** Instruction prepended to the input in the single user message. */
+  instruction: string;
+  /** The payload (e.g. the document to summarize/classify). */
+  input: string;
+  apiKey?: string;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+/**
+ * Ask the model for a structured object via a single tool call, validated against `schema`. Never
+ * throws: any model error, missing tool call, or schema-invalid arguments yields `{ ok:false }`.
+ *
+ * Deliberately sets no provider-specific `toolChoice` — the generic `complete` surface has no
+ * portable forced-tool value (providers disagree: `"required"` vs `"any"`), so tool use is requested
+ * via the prompt and the call site keeps a deterministic fallback. No `maxTokens` cap is set, so
+ * reasoning models are not truncated before emitting the tool call.
+ */
+export async function completeStructured<S extends TSchema>(
+  opts: CompleteStructuredOptions<S>,
+): Promise<StructuredOutcome<Static<S>>> {
+  const tool: Tool = {
+    name: opts.toolName,
+    description: opts.toolDescription,
+    parameters: opts.schema,
+  };
+  const context: Context = {
+    systemPrompt: opts.system,
+    messages: [
+      {
+        role: "user",
+        content: `${opts.instruction}\n\n${opts.input}`,
+        timestamp: Date.now(),
+      },
+    ],
+    tools: [tool],
+  };
+
+  let msg: Awaited<ReturnType<typeof complete>>;
+  try {
+    msg = await complete(opts.model, context, {
+      apiKey: opts.apiKey,
+      headers: opts.headers,
+      signal: opts.signal,
+      timeoutMs: opts.timeoutMs,
+    });
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+
+  if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+    return { ok: false, error: msg.errorMessage ?? `model stopped: ${msg.stopReason}` };
+  }
+
+  const toolCalls = msg.content.filter((b): b is ToolCall => b.type === "toolCall");
+  const call = toolCalls.find((c) => c.name === opts.toolName) ?? toolCalls[0];
+  if (!call) return { ok: false, error: "model returned no tool call" };
+
+  try {
+    const value = validateToolCall([tool], call) as Static<S>;
+    return { ok: true, value };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}