@north-light/cli 0.0.0-stage → 0.3.413

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/frontmatter-rules/index.ts

@@ -0,0 +1,421 @@
+/**
+ * Frontmatter Rules
+ *
+ * Conditional "pi rules" that load only when the agent reads a markdown file
+ * whose YAML frontmatter satisfies a rule's `when:` condition. This is the
+ * inverse of a PATH-glob rule (matched on the document's location, not its
+ * content): here the *content* of the read document (its frontmatter) decides
+ * which rules apply, not the document's path. Path-glob rules live as
+ * substrate docs with read-glob `surfaces` entries (see `crtr sys sync
+ * project-guidance`'s `.claude/rules` migration), not as a sibling pi-extension.
+ *
+ * Rule files live in `.pi/rules/*.md` (walked up the read file's ancestor
+ * chain, so a project-root rules dir governs everything beneath it) plus a
+ * global `~/.pi/rules/`. Each rule declares a `when:` condition in its own
+ * frontmatter; the rule body (markdown after the frontmatter) is what gets
+ * injected ahead of the file contents in the read result.
+ *
+ * Rule file shape:
+ *   ---
+ *   name: Security review rules        # optional, defaults to filename
+ *   description: ...                   # optional, shown in the injection header
+ *   when:
+ *     tags: { contains: security }     # see "Condition language" below
+ *   ---
+ *   <rule guidance in markdown>
+ *
+ * Condition language (evaluated against the READ file's frontmatter object):
+ *   A `when:` block is a map of <field> -> <matcher>, AND-ed across fields.
+ *   `field` may be dotted to reach nested values (e.g. meta.owner).
+ *
+ *   Matcher forms:
+ *     scalar (string/number/bool/null)
+ *         field === value, OR (if the field is an array) the array includes value
+ *     array  [a, b, c]
+ *         membership/intersection: field is one of these, OR the field array
+ *         shares any element with these
+ *     object { <op>: <arg>, ... }   (multiple ops AND together)
+ *         eq          equals (scalar or array-includes)
+ *         ne          not eq
+ *         in          [..] — field (or any of its array elements) is in the list
+ *         nin         not in
+ *         exists      true|false — field is present / absent
+ *         contains    field array includes this value
+ *         containsAll [..] — field array includes all of these
+ *         containsAny [..] — field array includes any of these
+ *         matches     regex string, case-sensitive (tests String(field); arrays: any)
+ *         imatches    regex string, case-insensitive
+ *         gt gte lt lte   numeric comparison
+ *
+ *   Combinators (reserved keys at any condition level):
+ *     all: [ {..}, {..} ]   every sub-condition true (AND)
+ *     any: [ {..}, {..} ]   at least one true (OR)
+ *     not: { .. }           sub-condition false
+ *   Sibling field matchers next to combinators are AND-ed in.
+ *
+ *   A rule with no `when:` is inert (never auto-loads) — keeps reads quiet.
+ *
+ * Notes:
+ *   - Only .md/.mdx/.markdown reads are considered, and only if they have
+ *     frontmatter that parses to a YAML object.
+ *   - Each rule file is injected at most once per session (deduped by realpath),
+ *     so reading many matching documents won't re-spam the same rule.
+ *
+ * Install: directory lives in ~/.pi/agent/extensions/ (global) or a project's
+ * .pi/extensions/. Run `npm install` here once so `yaml` resolves.
+ */
+
+import type { ExtensionAPI, ToolResultEvent } from '@earendil-works/pi-coding-agent';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { mergeAutoLoadedContext } from '../../../../pi-extensions/envelope-merge.js';
+
+const MARKDOWN_EXTS = new Set([".md", ".mdx", ".markdown"]);
+
+const JUNK_DIRS = new Set([
+	"node_modules",
+	".git",
+	".venv",
+	"venv",
+	"dist",
+	"build",
+	".next",
+	".cache",
+	".yalc",
+	".sisyphus",
+	".crouter",
+]);
+
+type Frontmatter = Record<string, unknown>;
+
+interface Rule {
+	name: string;
+	description?: string;
+	when?: unknown;
+	body: string;
+}
+
+function realpathOrSelf(p: string): string {
+	try {
+		return fs.realpathSync(p);
+	} catch {
+		return p;
+	}
+}
+
+function isJunkPath(absDir: string): boolean {
+	return absDir.split(path.sep).some((seg) => JUNK_DIRS.has(seg));
+}
+
+// Nearest enclosing git repo root for a path (walk up looking for `.git`).
+function gitRoot(p: string): string | null {
+	let d = p;
+	const root = path.parse(d).root;
+	while (true) {
+		if (fs.existsSync(path.join(d, ".git"))) return d;
+		if (d === root) return null;
+		const parent = path.dirname(d);
+		if (parent === d) return null;
+		d = parent;
+	}
+}
+
+// Display paths relative to the nearest git repo root, else absolute.
+function disp(p: string): string {
+	const root = gitRoot(p);
+	if (!root) return p;
+	const rel = path.relative(root, p);
+	return rel === "" ? "." : rel;
+}
+
+// Escape a value for use inside an XML-ish attribute in the injected block.
+function attr(s: string): string {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+
+// Pull the leading `--- ... ---` YAML block out of a markdown file.
+function extractFrontmatter(raw: string): Frontmatter | null {
+	const m = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+	if (!m) return null;
+	try {
+		const parsed = parseYaml(m[1]);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Frontmatter;
+		}
+	} catch {
+		/* malformed frontmatter — treat as none */
+	}
+	return null;
+}
+
+function findMarkdown(dir: string): string[] {
+	const out: string[] = [];
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const e of entries) {
+		const fp = path.join(dir, e.name);
+		if (e.isDirectory()) out.push(...findMarkdown(fp));
+		else if (e.isFile() && MARKDOWN_EXTS.has(path.extname(e.name).toLowerCase())) out.push(fp);
+	}
+	return out;
+}
+
+function parseRuleFile(filePath: string): Rule {
+	const fallback = (): Rule => ({ name: path.basename(filePath).replace(/\.[^.]+$/, ""), body: "" });
+	let raw = "";
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return fallback();
+	}
+	const m = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/);
+	if (!m) {
+		// No frontmatter: whole file is body, but inert (no `when`).
+		return { name: path.basename(filePath).replace(/\.[^.]+$/, ""), body: raw.trim() };
+	}
+	let front: Frontmatter = {};
+	try {
+		const parsed = parseYaml(m[1]);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) front = parsed as Frontmatter;
+	} catch {
+		/* malformed rule frontmatter */
+	}
+	const name = typeof front.name === "string" && front.name.trim()
+		? front.name.trim()
+		: path.basename(filePath).replace(/\.[^.]+$/, "");
+	const description = typeof front.description === "string" ? front.description.trim() : undefined;
+	return { name, description, when: front.when, body: (m[2] ?? "").trim() };
+}
+
+// Condition language
+
+function asArray(v: unknown): unknown[] {
+	if (Array.isArray(v)) return v;
+	if (v === undefined) return [];
+	return [v];
+}
+
+// Scalar equality with light, predictable coercion: exact match, or
+// string/number cross-compare so `version: 2` matches frontmatter "2".
+function scalarEq(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (
+		(typeof a === "number" || typeof a === "string") &&
+		(typeof b === "number" || typeof b === "string")
+	) {
+		return String(a) === String(b);
+	}
+	return false;
+}
+
+// Resolve a (possibly dotted) field path against the frontmatter object.
+function getField(fm: unknown, key: string): unknown {
+	if (fm && typeof fm === "object" && key in (fm as Record<string, unknown>)) {
+		return (fm as Record<string, unknown>)[key];
+	}
+	if (!key.includes(".")) return undefined;
+	let cur: unknown = fm;
+	for (const part of key.split(".")) {
+		if (cur == null || typeof cur !== "object") return undefined;
+		cur = (cur as Record<string, unknown>)[part];
+	}
+	return cur;
+}
+
+function toRegExp(arg: unknown, flags: string): RegExp | null {
+	if (typeof arg !== "string") return null;
+	try {
+		return new RegExp(arg, flags);
+	} catch {
+		return null;
+	}
+}
+
+function applyOp(op: string, value: unknown, arg: unknown): boolean {
+	const vals = asArray(value);
+	switch (op) {
+		case "eq":
+			return Array.isArray(value) ? value.some((v) => scalarEq(v, arg)) : scalarEq(value, arg);
+		case "ne":
+			return !applyOp("eq", value, arg);
+		case "in":
+			return asArray(arg).some((a) => vals.some((v) => scalarEq(v, a)));
+		case "nin":
+			return !applyOp("in", value, arg);
+		case "exists":
+			return (value !== undefined) === (arg !== false);
+		case "contains":
+			return vals.some((v) => scalarEq(v, arg));
+		case "containsAll":
+			return asArray(arg).every((a) => vals.some((v) => scalarEq(v, a)));
+		case "containsAny":
+			return asArray(arg).some((a) => vals.some((v) => scalarEq(v, a)));
+		case "matches":
+		case "imatches": {
+			const re = toRegExp(arg, op === "imatches" ? "i" : "");
+			if (!re) return false;
+			return vals.some((v) => typeof v === "string" || typeof v === "number" ? re.test(String(v)) : false);
+		}
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": {
+			const n = Number(value);
+			const t = Number(arg);
+			if (Number.isNaN(n) || Number.isNaN(t)) return false;
+			if (op === "gt") return n > t;
+			if (op === "gte") return n >= t;
+			if (op === "lt") return n < t;
+			return n <= t;
+		}
+		default:
+			return false; // unknown op never matches
+	}
+}
+
+function matchField(value: unknown, matcher: unknown): boolean {
+	if (matcher === null || ["string", "number", "boolean"].includes(typeof matcher)) {
+		if (Array.isArray(value)) return value.some((v) => scalarEq(v, matcher));
+		return scalarEq(value, matcher);
+	}
+	if (Array.isArray(matcher)) {
+		const vals = asArray(value);
+		return matcher.some((m) => vals.some((v) => scalarEq(v, m)));
+	}
+	if (matcher && typeof matcher === "object") {
+		return Object.entries(matcher as Record<string, unknown>).every(([op, arg]) =>
+			applyOp(op, value, arg),
+		);
+	}
+	return false;
+}
+
+function evalCondition(cond: unknown, fm: Frontmatter): boolean {
+	if (cond == null) return false;
+	if (Array.isArray(cond)) return cond.every((sub) => evalCondition(sub, fm));
+	if (typeof cond !== "object") return false;
+	const c = cond as Record<string, unknown>;
+	const hasCombinator = "all" in c || "any" in c || "not" in c;
+	if (hasCombinator) {
+		let ok = true;
+		if ("all" in c) ok = ok && asArray(c.all).every((s) => evalCondition(s, fm));
+		if ("any" in c) ok = ok && asArray(c.any).some((s) => evalCondition(s, fm));
+		if ("not" in c) ok = ok && !evalCondition(c.not, fm);
+		for (const k of Object.keys(c)) {
+			if (k === "all" || k === "any" || k === "not") continue;
+			ok = ok && matchField(getField(fm, k), c[k]);
+		}
+		return ok;
+	}
+	const keys = Object.keys(c);
+	if (keys.length === 0) return false; // empty `when:` is inert, not match-all
+	return keys.every((k) => matchField(getField(fm, k), c[k]));
+}
+
+// Extension
+
+export default function frontmatterRules(pi: ExtensionAPI) {
+	const seen = new Set<string>();
+
+	pi.on("session_start", async () => {
+		seen.clear();
+	});
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "read" || event.isError) return;
+
+		const rawPath =
+			(event.input as { path?: string; file_path?: string })?.path ??
+			(event.input as { file_path?: string })?.file_path;
+		if (!rawPath) return;
+		if (!MARKDOWN_EXTS.has(path.extname(rawPath).toLowerCase())) return;
+
+		const cwd = path.resolve(ctx.cwd);
+		const expanded = rawPath.startsWith("~") ? path.join(os.homedir(), rawPath.slice(1)) : rawPath;
+		const absFile = realpathOrSelf(path.resolve(cwd, expanded));
+
+		// Read from disk (not event.content) so frontmatter is clean and
+		// unaffected by the read tool's formatting/truncation.
+		let raw = "";
+		try {
+			raw = fs.readFileSync(absFile, "utf-8");
+		} catch {
+			return;
+		}
+		const fm = extractFrontmatter(raw);
+		if (!fm) return; // no frontmatter -> nothing to match
+
+		// Collect candidate rule directories: each ancestor's `.pi/rules`, plus
+		// a global `~/.pi/rules`. Dedup directories before scanning.
+		const home = os.homedir();
+		const fsRoot = path.parse(absFile).root;
+		const ruleDirs: { dir: string; order: number }[] = [];
+		const seenDirs = new Set<string>();
+		const pushDir = (d: string, order: number) => {
+			const real = realpathOrSelf(d);
+			if (seenDirs.has(real)) return;
+			seenDirs.add(real);
+			ruleDirs.push({ dir: d, order });
+		};
+
+		let dir = path.dirname(absFile);
+		let depth = 0;
+		while (true) {
+			if (!isJunkPath(dir)) pushDir(path.join(dir, ".pi", "rules"), depth);
+			if (dir === home || dir === fsRoot) break;
+			const parent = path.dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+			depth += 1;
+		}
+		// Global rules rank as the outermost (highest order = farthest).
+		pushDir(path.join(home, ".pi", "rules"), depth + 1);
+
+		type Block = { order: number; text: string };
+		const blocks: Block[] = [];
+
+		for (const { dir: rulesDir, order } of ruleDirs) {
+			for (const rf of findMarkdown(rulesDir)) {
+				const real = realpathOrSelf(rf);
+				if (seen.has(real)) continue;
+				const rule = parseRuleFile(rf);
+				if (rule.when === undefined) continue; // inert without a condition
+				if (!evalCondition(rule.when, fm)) continue; // may match a later read
+				seen.add(real);
+				const descAttr = rule.description ? ` description="${attr(rule.description)}"` : "";
+				blocks.push({
+					order,
+					text:
+						`<rule name="${attr(rule.name)}" src="${attr(disp(rf))}"${descAttr}>\n` +
+						`${rule.body}\n` +
+						`</rule>`,
+				});
+			}
+		}
+
+		if (blocks.length === 0) return;
+
+		// Outermost-first so the most specific (nearest) rule reads last/closest
+		// to the file content that follows.
+		blocks.sort((a, b) => b.order - a.order);
+		const merged = mergeAutoLoadedContext(blocks.map((b) => b.text), event.content);
+		if (merged === event.content) return;
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Loaded ${blocks.length} frontmatter rule(s)`, "info");
+		}
+
+		return { content: merged };
+	});
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts

@@ -0,0 +1,145 @@
+import { envNodeId } from '../../../shared/env.js';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { DeliveryCommandDTO } from '../../../api/dto/delivery.js';
+import { brokerDelivery } from '../../../core/runtime/broker/daemon-ops.js';
+import {
+  expandDeterministicCommand,
+  type DeterministicCommandExpansion,
+} from '../../../core/runtime/command-expansion.js';
+import { expandShellBlocks, hasShellBlocks, DEFAULT_SHELL_TIMEOUT_MS } from '../../../core/runtime/shell-expansion.js';
+import type { ChatCommandMetadata } from '../../../core/runtime/command-surface.js';
+import { piShellRunner } from './pi-shell-runner.js';
+
+// memory-slash-commands: any document with a `slash-command` delivery rule in
+// the node's view becomes an invocable slash command (`/<name>`). This mirrors Hermes Agent's
+// "every skill is automatically a slash command" — /research-alpha injects
+// the doc body (plus the user's free-text args) as a normal turn instead of
+// requiring a separate skill-invocation mechanism.
+//
+// The node's delivery route lists and resolves the commands (the broker is the
+// only host, so there is always a node); shell blocks run only when invoked here.
+
+export interface SlashDoc {
+  /** Canonical name resolved by `crtr canvas read`. */
+  name: string;
+  /** Canonical `/` segments rendered as ordinary `:` command segments. */
+  commandName: string;
+  /** The memory document's short-form description, shown in the slash menu. */
+  description: string;
+}
+
+// Keep each listed command's body for registration-time disclosure classification.
+const resolvedCommands = new Map<string, DeliveryCommandDTO>();
+
+function nodeIdOrThrow(): string {
+  const node = envNodeId();
+  if (!node) throw new Error('slash commands require a canvas node');
+  return node;
+}
+
+async function listSlashCommands(): Promise<DeliveryCommandDTO[]> {
+  const commands = (await brokerDelivery(nodeIdOrThrow(), { activity: 'slash-command' })).commands ?? [];
+  resolvedCommands.clear();
+  for (const command of commands) resolvedCommands.set(command.name, command);
+  return commands;
+}
+
+function readSlashCommand(name: string): { canonicalBody: string; executionBody: string } {
+  const resolved = resolvedCommands.get(name);
+  if (resolved === undefined) throw new Error(`slash command document was not resolved: ${name}`);
+  return { canonicalBody: resolved.canonical_body, executionBody: resolved.execution_body };
+}
+
+async function slashReadAttachments(name: string): Promise<{ blocks: string[]; execution_body: string }> {
+  const res = await brokerDelivery(nodeIdOrThrow(), { activity: 'slash-command', subject: name });
+  if (res.execution_body === undefined) throw new Error(`slash command document has no execution body: ${name}`);
+  return { blocks: (res.blocks ?? []).filter((block) => block !== ''), execution_body: res.execution_body };
+}
+
+function hasNodeRelativeExpansion(body: string): boolean {
+  return body.includes("$CRTR_CONTEXT_DIR") || body.includes("$CRTR_NODE_ID");
+}
+
+/** Canonical name -> the registered slash-command name. */
+export function slashCommandName(docName: string): string {
+  return docName.split("/").join(":");
+}
+
+/** Every document with a `slash-command` rule in the node's view, deduped by name. */
+export async function discoverSlashDocs(): Promise<SlashDoc[]> {
+  if (!envNodeId()) return [];
+  const items = await listSlashCommands();
+  const seen = new Set<string>();
+  const out: SlashDoc[] = [];
+  for (const item of items) {
+    if (seen.has(item.name)) continue;
+    seen.add(item.name);
+    out.push({ name: item.name, commandName: slashCommandName(item.name), description: item.description });
+  }
+  return out;
+}
+
+export default async function (pi: ExtensionAPI) {
+  const docs = await discoverSlashDocs();
+  for (const doc of docs) {
+    let expansion: DeterministicCommandExpansion | undefined;
+    let discloseExpansion = false;
+    try {
+      const body = readSlashCommand(doc.name);
+      expansion = {
+        kind: "memory-slash",
+        commandName: doc.commandName,
+        body: body.executionBody,
+      };
+      discloseExpansion = !hasNodeRelativeExpansion(body.canonicalBody);
+    } catch {
+      // Keep registration for a document that became unreadable; invocation
+      // reports the current read error without executing the cached body.
+    }
+
+    // pi preserves unknown registration fields on the resolved command object.
+    // The broker discloses deterministic expansions through get_commands. A
+    // node-relative body still executes through the private expansion below,
+    // but cannot promise a concrete payload before the future node exists.
+    pi.registerCommand(doc.commandName, {
+      description: doc.description,
+      // Chat-capable: the handler's whole outcome is a conversation turn
+      // carrying the expanded document, which any surface hosting the
+      // conversation receives. Only when the expansion loaded — without it the
+      // sole outcome is a terminal-only error notify, so it stays undisclosed.
+      ...(expansion === undefined
+        ? {}
+        : { gateway: true as const, ...(discloseExpansion ? { expansion } : {}) }),
+      handler: async (args, ctx) => {
+        let current: { blocks: string[]; execution_body: string };
+        try {
+          current = await slashReadAttachments(doc.name);
+        } catch (error) {
+          ctx.ui.notify(`/${doc.commandName}: failed to read memory doc "${doc.name}": ${error instanceof Error ? error.message : String(error)}`, "error");
+          return;
+        }
+        // The daemon resolves the current slash document and attachments in one
+        // request, before the document can execute any shell block.
+        const expanded = expandDeterministicCommand({ kind: 'memory-slash', commandName: doc.commandName, body: current.execution_body }, args ?? "");
+        const content = hasShellBlocks(expanded)
+          ? await expandShellBlocks(
+              expanded,
+              piShellRunner(pi, (ctx as { cwd?: string }).cwd ?? process.cwd(), DEFAULT_SHELL_TIMEOUT_MS),
+            )
+          : expanded;
+        const blocks = current.blocks;
+        pi.sendMessage(
+          {
+            customType: "memory-slash-command",
+            content:
+              blocks.length === 0
+                ? content
+                : `${blocks.join("\n")}\n\n${content}`,
+            display: true,
+          },
+          { triggerTurn: true },
+        );
+      },
+    } as Parameters<ExtensionAPI["registerCommand"]>[1] & { expansion?: DeterministicCommandExpansion } & ChatCommandMetadata);
+  }
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/pi-shell-runner.ts

@@ -0,0 +1,34 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { truncateTail, formatSize, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES } from '@earendil-works/pi-coding-agent';
+
+// The broker-side execution strategy for `core/runtime/shell-expansion`. Every
+// command surface that expands a Markdown body inside a pi engine shares it, so
+// the engine owns the subprocess and truncation uses pi's own limits. The
+// grammar and substitution order live in the shared module; only this strategy
+// is pi-specific, and it stays out of that module so CLI leaves can import the
+// expander without loading the pi runtime.
+
+function truncateForLLM(content: string): string {
+  const t = truncateTail(content, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+  let out = t.content;
+  if (t.truncated) {
+    const limit = t.truncatedBy === "lines" ? `${t.maxLines} lines` : formatSize(t.maxBytes);
+    out += `\n[truncated: hit ${limit}]`;
+  }
+  return out;
+}
+
+export function piShellRunner(pi: ExtensionAPI, cwd: string, timeoutMs: number) {
+  const [sh, flag] = process.platform === "win32" ? ["powershell.exe", "-Command"] : ["sh", "-c"];
+  return async (cmd: string): Promise<string> => {
+    const res: any = await pi.exec(sh, [flag, cmd], { cwd, timeout: timeoutMs });
+    if (res.killed) return `[Shell error: timed out after ${Math.max(1, Math.round(timeoutMs / 1000))}s]`;
+    if (res.code !== 0) return `[Shell error: exit code ${res.code}]\n${truncateForLLM(res.stderr ?? "")}`;
+    let combined = res.stdout ?? "";
+    if (res.stderr) {
+      const sep = combined.length === 0 || combined.endsWith("\n") ? "" : "\n";
+      combined = `${combined}${sep}[stderr]\n${res.stderr}`;
+    }
+    return truncateForLLM(combined);
+  };
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.d.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { type AssistantMessageEventStream, type TranscriptContext, type Model, type SimpleStreamOptions } from '@earendil-works/pi-ai';
+import { type ManagedProviderId, type SubscriptionCredential } from '../../../core/subscription-state.js';
+export interface ProviderRotationOptions {
+    modelIntent?: string;
+    nodeCwd?: string;
+    profileId?: string;
+}
+type ProviderErrorClassification = {
+    kind: "rate_limit" | "transient" | "fatal";
+    status?: number;
+    reason: string;
+    hadRetryAfterHeader: boolean;
+    /** Cooldown this classification imposes regardless of any Retry-After header. */
+    cooldownMs?: number;
+};
+type ProviderClassificationPolicy = {
+    rotateOnAuth: boolean;
+};
+/** Test seam for the policy mapping over the shared recognition signal. */
+export declare function __classifyProviderErrorForTest(error: unknown, observed?: {
+    status?: number;
+    retryAfterMs?: number;
+}, policy?: ProviderClassificationPolicy): ProviderErrorClassification;
+declare function defaultSleep(ms: number): Promise<void>;
+/** Test-only seam: override the sleep implementation used for in-place/wait-out retries. Pass undefined to restore the default. */
+export declare function __setSleepForTest(fn: typeof defaultSleep | undefined): void;
+export declare const POISONED_TRANSPORT_PASS_LIMIT = 2;
+declare function defaultTerminatePoisonedProcess(tried: string): Promise<boolean>;
+/** Test-only seam: override poisoned-process self-termination. Pass undefined to restore the default. */
+export declare function __setTerminatePoisonedProcessForTest(fn: typeof defaultTerminatePoisonedProcess | undefined): void;
+/** Test-only seam for the bounded, non-fatal subscription bookkeeping path. */
+export declare function __recordSubscriptionMutationForTest(description: string, mutate: () => Promise<unknown>): Promise<boolean>;
+type RefreshedCredential = {
+    refresh: string;
+    access: string;
+    expires: number;
+    clientId?: string;
+};
+type LoginCredential = {
+    refresh: string;
+    access: string;
+    expires: number;
+    accountId?: string;
+    clientId?: string;
+};
+type ResolvedCredential = SubscriptionCredential & {
+    access: string;
+};
+type RefreshForProvider = (providerId: ManagedProviderId, refreshToken: string, signal?: AbortSignal, clientId?: string) => Promise<RefreshedCredential>;
+/** Test-only seam: override the per-provider refresh function. Pass undefined to restore the default. */
+export declare function __setRefreshForProviderForTest(fn: RefreshForProvider | undefined): void;
+/** Test-only seam: exercises the real `refreshCredentialIfNeeded` (including its locked refresh
+ * transaction) without duplicating its logic. */
+export declare function __refreshCredentialIfNeededForTest(providerId: ManagedProviderId, credential: SubscriptionCredential, signal?: AbortSignal): Promise<ResolvedCredential>;
+declare function defaultLoginForProvider(providerId: ManagedProviderId, ctx: ExtensionContext): Promise<LoginCredential>;
+/** Test-only seam: override the per-provider login function. Pass undefined to restore the default. */
+export declare function __setLoginForProviderForTest(fn: typeof defaultLoginForProvider | undefined): void;
+declare function defaultStreamForProvider(model: Model<any>, context: TranscriptContext, options: SimpleStreamOptions | undefined): AssistantMessageEventStream;
+/** Test-only seam: override the per-provider stream factory. Pass undefined to restore the default. */
+export declare function __setStreamForProviderForTest(fn: typeof defaultStreamForProvider | undefined): void;
+/**
+ * pi-ai races the manual-code-paste dialog against its loopback callback server. When the
+ * callback supplies a code, the manual-input promise can remain pending, so `run` receives:
+ *  - `readCode`, a `ctx.ui.input` wrapper with an AbortSignal. Aborting it removes the pending
+ *    broker entry and emits an `extension_ui_dismiss` frame for exactly that dialog.
+ *  - `dismissManual`, which aborts the signal at the post-code `onProgress` boundary before
+ *    the token exchange completes. `onProgress` is emitted only after a code is available, so
+ *    dismissing then cannot close a dialog the user still needs; `finally` covers paths without
+ *    progress, and repeated AbortController calls are inert.
+ *
+ * `undefined` from `readCode` means cancellation or timeout. It throws so OAuth ends directly
+ * instead of opening a second paste-only dialog.
+ */
+export declare function loginWithManualInputCleanup<T>(ctx: ExtensionContext, run: (readCode: (title: string, placeholder: string) => Promise<string>, dismissManual: () => void) => Promise<T>): Promise<T>;
+export declare function createProviderRotationExtension(options?: ProviderRotationOptions): (pi: ExtensionAPI) => Promise<void>;
+declare const defaultProviderRotationExtension: (pi: ExtensionAPI) => Promise<void>;
+export default defaultProviderRotationExtension;