@aeondave/pi-persona 1.15.2

package/src/core/frontmatter.ts

@@ -0,0 +1,202 @@
+/**
+ * The single Markdown + YAML-frontmatter engine for pi-persona.
+ *
+ * Pure module — no Pi imports. Used by personas, agents, chains, and any other
+ * frontmatter-bearing file. The YAML is a deliberate SUBSET (not a full engine):
+ * top-level `key: value` scalars, inline `[a, b]` and block (`- a`) lists, and one
+ * level of nested maps (for `delegate`/`tools` allow/deny). Coercion helpers turn
+ * raw values into the typed shapes the rest of the system expects.
+ */
+
+import type { Permission } from "./permissions.ts";
+
+// --------------------------------------------------------------------------
+// Frontmatter split
+// --------------------------------------------------------------------------
+
+/** Split `---\nfrontmatter\n---\nbody`. Missing frontmatter → all body. */
+export function splitFrontmatter(content: string): { frontmatter: string; body: string } {
+	const normalized = content.replace(/^/, "");
+	const match = normalized.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?([\s\S]*)$/);
+	if (!match) return { frontmatter: "", body: normalized.trim() };
+	return { frontmatter: match[1] ?? "", body: (match[2] ?? "").trim() };
+}
+
+// --------------------------------------------------------------------------
+// Minimal YAML-subset parser
+// --------------------------------------------------------------------------
+
+/** Strip a trailing `# comment` that is not inside quotes. */
+function stripComment(line: string): string {
+	let inSingle = false;
+	let inDouble = false;
+	for (let i = 0; i < line.length; i++) {
+		const c = line[i];
+		if (c === "'" && !inDouble) inSingle = !inSingle;
+		else if (c === '"' && !inSingle) inDouble = !inDouble;
+		else if (c === "#" && !inSingle && !inDouble && (i === 0 || line[i - 1] === " " || line[i - 1] === "\t")) {
+			return line.slice(0, i);
+		}
+	}
+	return line;
+}
+
+function unquote(value: string): string {
+	const v = value.trim();
+	if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+		return v.slice(1, -1);
+	}
+	return v;
+}
+
+/** Split on top-level commas only — commas inside `[...]`/`{...}` OR inside a quoted
+ *  string (`"a, b"` / `'a, b'`) are left intact. Quote-aware so an inline map value like
+ *  `role: "injection, authz, secrets"` isn't shredded at every comma. */
+function splitTopLevel(s: string): string[] {
+	const out: string[] = [];
+	let depth = 0;
+	let start = 0;
+	let inSingle = false;
+	let inDouble = false;
+	for (let i = 0; i < s.length; i++) {
+		const c = s[i];
+		if (c === "'" && !inDouble) inSingle = !inSingle;
+		else if (c === '"' && !inSingle) inDouble = !inDouble;
+		else if (inSingle || inDouble) continue; // inside a string: ignore brackets/commas
+		else if (c === "[" || c === "{") depth++;
+		else if (c === "]" || c === "}") depth--;
+		else if (c === "," && depth === 0) {
+			out.push(s.slice(start, i));
+			start = i + 1;
+		}
+	}
+	out.push(s.slice(start));
+	return out.map((x) => x.trim()).filter((x) => x.length > 0);
+}
+
+/** Parse a scalar, inline list (`[a, b]`), or inline flow map (`{ k: v }`). */
+function parseValue(raw: string): string | string[] | boolean | number | Record<string, unknown> {
+	const v = raw.trim();
+	if (v.startsWith("[") && v.endsWith("]")) {
+		const inner = v.slice(1, -1).trim();
+		if (inner === "") return [];
+		return splitTopLevel(inner)
+			.map((s) => unquote(s))
+			.filter((s) => s.length > 0);
+	}
+	if (v.startsWith("{") && v.endsWith("}")) {
+		const inner = v.slice(1, -1).trim();
+		const obj: Record<string, unknown> = {};
+		if (inner === "") return obj;
+		for (const pair of splitTopLevel(inner)) {
+			const ci = pair.indexOf(":");
+			if (ci < 0) continue;
+			obj[unquote(pair.slice(0, ci).trim())] = parseValue(pair.slice(ci + 1).trim());
+		}
+		return obj;
+	}
+	if (v === "true") return true;
+	if (v === "false") return false;
+	if (/^-?\d+(?:\.\d+)?$/.test(v)) return Number(v);
+	return unquote(v);
+}
+
+interface Frame {
+	indent: number;
+	container: Record<string, unknown>;
+	/** When this frame was opened by `key:` with no value, the parent + key so a
+	 *  following `- item` line can convert it to an array. */
+	selfKey?: string;
+	parent?: Record<string, unknown>;
+	listArr?: unknown[];
+}
+
+/** Parse the YAML subset (see module doc) into a plain object. */
+export function parseYamlSubset(src: string): Record<string, unknown> {
+	const root: Record<string, unknown> = {};
+	const stack: Frame[] = [{ indent: -1, container: root }];
+
+	for (const rawLine of src.split(/\r?\n/)) {
+		const line = stripComment(rawLine);
+		if (line.trim() === "") continue;
+		const indent = line.length - line.trimStart().length;
+		const content = line.trim();
+
+		// A `- item` may sit at the SAME indent as the `key:` it belongs to, so only a
+		// strictly smaller indent closes that frame; key lines still close on equal indent.
+		const isItem = content.startsWith("- ") || content === "-";
+		while (stack.length > 1) {
+			const frameIndent = stack[stack.length - 1]!.indent;
+			if (isItem ? indent < frameIndent : indent <= frameIndent) stack.pop();
+			else break;
+		}
+		const top = stack[stack.length - 1]!;
+
+		if (isItem) {
+			// Block list item under the current `key:` frame.
+			const itemRaw = content === "-" ? "" : content.slice(2);
+			if (!top.listArr) {
+				top.listArr = [];
+				if (top.parent && top.selfKey) top.parent[top.selfKey] = top.listArr;
+			}
+			top.listArr.push(parseValue(itemRaw));
+			continue;
+		}
+
+		const colon = content.indexOf(":");
+		if (colon < 0) continue; // not a key line — ignore
+		const key = content.slice(0, colon).trim();
+		const rest = content.slice(colon + 1).trim();
+
+		if (rest === "") {
+			// Open a nested container (map by default; becomes a list if `- ` follows).
+			const child: Record<string, unknown> = {};
+			top.container[key] = child;
+			stack.push({ indent, container: child, selfKey: key, parent: top.container });
+		} else {
+			top.container[key] = parseValue(rest);
+		}
+	}
+
+	return root;
+}
+
+// --------------------------------------------------------------------------
+// Coercion helpers
+// --------------------------------------------------------------------------
+
+/** Coerce a value to a string[] (array, or comma-separated scalar). Empty → undefined. */
+export function asStringArray(value: unknown): string[] | undefined {
+	if (Array.isArray(value)) return value.map((v) => String(v)).filter((s) => s.length > 0);
+	if (typeof value === "string" && value.trim().length > 0) {
+		return value
+			.split(",")
+			.map((s) => s.trim())
+			.filter((s) => s.length > 0);
+	}
+	return undefined;
+}
+
+/** Coerce a value to a `Permission`. A bare list/scalar is the `allow` shorthand. */
+export function asPermission(value: unknown): Permission | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		const allow = asStringArray(value);
+		return allow ? { allow } : undefined;
+	}
+	const obj = value as Record<string, unknown>;
+	const allow = asStringArray(obj.allow);
+	const deny = asStringArray(obj.deny);
+	if (allow === undefined && deny === undefined) return undefined;
+	const perm: Permission = {};
+	if (allow !== undefined) perm.allow = allow;
+	if (deny !== undefined) perm.deny = deny;
+	return perm;
+}
+
+/** Coerce a value to a boolean (real booleans or the strings `"true"`/`"false"`). */
+export function asBoolean(value: unknown): boolean | undefined {
+	if (typeof value === "boolean") return value;
+	if (value === "true") return true;
+	if (value === "false") return false;
+	return undefined;
+}

package/src/core/models.ts

@@ -0,0 +1,192 @@
+/**
+ * Model reference resolution — turn a loose model name the supervisor typed into a
+ * canonical `provider/id` from the registry, or fail with the candidates. Stops a
+ * bare name (e.g. "sonnet") from silently resolving to an unauthenticated provider
+ * (which would spawn a child that just errors "no API key").
+ *
+ * The same model name often exists under several providers (anthropic, bedrock×N,
+ * openrouter, copilot…). When a name is ambiguous we prefer the **loader/session
+ * provider** — the supervisor's own provider, which is the one actually authenticated
+ * — so "sonnet" resolves to e.g. `claude-pro-max-native/claude-sonnet-4-6`, not a
+ * Bedrock look-alike. Pure — list + preferred provider injected.
+ */
+
+export interface ModelLite {
+	provider: string;
+	id: string;
+}
+
+/** A model-family routing rule. Rules are data so deployments can extend the paid-provider
+ * boundary without coupling it to a persona or to one concrete model release. Prefix matching is
+ * case-insensitive and applies to the model id after the provider slash. */
+export interface ModelRoutingRule {
+	idPrefixes: readonly string[];
+	allowedProviders: readonly string[];
+}
+
+export interface ModelRoutingPolicy {
+	rules: readonly ModelRoutingRule[];
+}
+
+/**
+ * Safe defaults for paid model families. OpenCode/OpenRouter remain usable for model families
+ * without a rule, but a Claude model may only route through claude-pro-max-native and an OpenAI
+ * family model may only route through the first-party OpenAI providers. Keep this table at the
+ * family/provider boundary: model ids are versioned and must not be allowlisted one by one.
+ */
+export const DEFAULT_MODEL_ROUTING_POLICY: ModelRoutingPolicy = {
+	rules: [
+		{ idPrefixes: ["claude-"], allowedProviders: ["claude-pro-max-native"] },
+		{ idPrefixes: ["gpt-", "chatgpt-", "o1", "o3", "o4"], allowedProviders: ["openai", "openai-codex"] },
+	],
+};
+
+export type ModelResolution =
+	| { ok: true; ref: string }
+	| { ok: false; reason: "unknown" | "ambiguous" | "blocked"; candidates: string[] };
+
+const full = (m: ModelLite): string => `${m.provider}/${m.id}`;
+
+function dedupe(models: ModelLite[]): ModelLite[] {
+	const seen = new Set<string>();
+	const out: ModelLite[] = [];
+	for (const m of models) {
+		const key = full(m);
+		if (!seen.has(key)) {
+			seen.add(key);
+			out.push(m);
+		}
+	}
+	return out;
+}
+
+function routingRule(id: string, policy: ModelRoutingPolicy): ModelRoutingRule | undefined {
+	const lower = id.toLowerCase();
+	return policy.rules.find((rule) => rule.idPrefixes.some((prefix) => lower.startsWith(prefix.toLowerCase())));
+}
+
+function providerAllowed(provider: string, allowedProviders: readonly string[] | undefined): boolean {
+	return allowedProviders === undefined || allowedProviders.some((allowed) => allowed.toLowerCase() === provider.toLowerCase());
+}
+
+/** Providers permitted for a model family, or undefined when the policy leaves that family open. */
+export function allowedModelProviders(id: string, policy?: ModelRoutingPolicy): readonly string[] | undefined {
+	return policy ? routingRule(id, policy)?.allowedProviders : undefined;
+}
+
+export function isModelProviderAllowed(model: ModelLite, policy?: ModelRoutingPolicy): boolean {
+	return providerAllowed(model.provider, allowedModelProviders(model.id, policy));
+}
+
+/** Compare two numeric version tuples ([4,6] vs [4,5]); >0 when `a` is newer. */
+function compareVersion(a: number[], b: number[]): number {
+	const n = Math.max(a.length, b.length);
+	for (let i = 0; i < n; i++) {
+		const d = (a[i] ?? 0) - (b[i] ?? 0);
+		if (d !== 0) return d;
+	}
+	return 0;
+}
+
+/**
+ * When EVERY candidate is the same model line differing only by a trailing numeric version
+ * (`claude-sonnet-4-6` vs `-4-5` vs `-4`), the newest is the natural pick — a loose family
+ * name ("sonnet") shouldn't force a `models` lookup just to choose between versions. Returns
+ * the newest `provider/id`, or `undefined` when the candidates are NOT one clean version line
+ * (different families/prefixes, or a non-versioned id) — those stay genuinely ambiguous.
+ * Provider-agnostic: the caller passes an already single-provider set.
+ */
+function newestOfVersionLine(candidates: ModelLite[]): string | undefined {
+	const parsed: Array<{ ref: string; prefix: string; version: number[] }> = [];
+	for (const m of candidates) {
+		const match = /^(.*?)-(\d+(?:-\d+)*)$/.exec(m.id);
+		if (!match || match[1] === undefined || match[2] === undefined) return undefined; // non-versioned → not a clean line
+		parsed.push({ ref: full(m), prefix: match[1], version: match[2].split("-").map(Number) });
+	}
+	if (parsed.length === 0) return undefined;
+	const prefixes = new Set(parsed.map((p) => p.prefix));
+	if (prefixes.size !== 1) return undefined; // distinct model lines → genuinely ambiguous
+	let best = parsed[0]!;
+	for (const p of parsed.slice(1)) if (compareVersion(p.version, best.version) > 0) best = p;
+	return best.ref;
+}
+
+export function resolveModelRef(
+	ref: string,
+	models: ModelLite[],
+	preferProvider?: string,
+	policy?: ModelRoutingPolicy,
+): ModelResolution {
+	const wanted = ref.trim();
+	const all = models.map(full);
+	const exact = models.find((m) => full(m) === wanted);
+	// An exact provider-qualified pin is an explicit user choice. Never rewrite or reject it
+	// because the current routing policy is intended only for loose automatic selection.
+	if (exact) return { ok: true, ref: wanted };
+
+	// Candidate set: a unique exact id (no provider), else a case-insensitive substring.
+	const byId = models.filter((m) => m.id === wanted);
+	const lower = wanted.toLowerCase();
+	const rawCandidates = dedupe(byId.length > 0 ? byId : models.filter((m) => full(m).toLowerCase().includes(lower)));
+	const candidates = policy ? rawCandidates.filter((m) => isModelProviderAllowed(m, policy)) : rawCandidates;
+	if (policy) {
+		const allCandidatesArePolicyBlocked = rawCandidates.length > 0 && rawCandidates.every((m) => allowedModelProviders(m.id, policy) !== undefined && !isModelProviderAllowed(m, policy));
+		if (allCandidatesArePolicyBlocked) return { ok: false, reason: "blocked", candidates: rawCandidates.map(full) };
+	}
+
+	if (candidates.length === 0) return { ok: false, reason: "unknown", candidates: all };
+	if (candidates.length === 1) return { ok: true, ref: full(candidates[0]!) };
+
+	// Ambiguous → prefer the loader/session provider (the authenticated one).
+	if (preferProvider) {
+		const preferred = candidates.filter((m) => m.provider === preferProvider);
+		if (preferred.length === 1) return { ok: true, ref: full(preferred[0]!) };
+		if (preferred.length > 1) {
+			// All on the authenticated provider: if they're one model line differing only by
+			// version, take the newest instead of stranding the caller with a `models` lookup.
+			const newest = newestOfVersionLine(preferred);
+			if (newest) return { ok: true, ref: newest };
+			return { ok: false, reason: "ambiguous", candidates: preferred.map(full) };
+		}
+	}
+
+	// Still ambiguous — list the preferred provider's matches first (helps the retry).
+	const ordered = preferProvider
+		? [
+				...candidates.filter((m) => m.provider === preferProvider),
+				...candidates.filter((m) => m.provider !== preferProvider),
+			]
+		: candidates;
+	return { ok: false, reason: "ambiguous", candidates: ordered.map(full) };
+}
+
+/**
+ * The provider-fallback chain for a `provider/id` that failed at runtime: the SAME model
+ * id offered by OTHER (authenticated) providers, so an unpinned run can be retried by switching
+ * the route while keeping the model. Preferred provider first (most likely authenticated), the
+ * failed `ref` excluded. An optional routing policy filters automatic alternatives; exact pins
+ * are enforced by the fallback decorator, not this pure helper. Empty when no alternate survives.
+ */
+export function providerFallbacks(
+	ref: string,
+	models: ModelLite[],
+	preferProvider?: string,
+	policy?: ModelRoutingPolicy,
+): string[] {
+	const slash = ref.indexOf("/");
+	const id = slash > 0 ? ref.slice(slash + 1) : ref;
+	const alts = dedupe(models.filter((m) => m.id === id && full(m) !== ref && isModelProviderAllowed(m, policy)));
+	const ordered = preferProvider
+		? [...alts.filter((m) => m.provider === preferProvider), ...alts.filter((m) => m.provider !== preferProvider)]
+		: alts;
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const m of ordered) {
+		const r = full(m);
+		if (!seen.has(r)) {
+			seen.add(r);
+			out.push(r);
+		}
+	}
+	return out;
+}