@loompad/cli 0.1.0 → 1.1.1

package/dist/core/providers.js

@@ -0,0 +1,343 @@
+/**
+ * Where a model agent's turns actually go, and where its key lives.
+ *
+ * Loom's agents have always been CLIs, which bring their own auth. A model
+ * agent (adapters/model.ts) doesn't: it needs a base URL, a key, and whatever
+ * headers that particular service insists on. This is the one place that
+ * knows those things.
+ *
+ * ## Keys are not project config
+ *
+ * `.loom/config.json` is committed in most projects. A key in it is a key in
+ * the repository, and then in the fork, and then in the search index. So the
+ * project config names a PROVIDER — `"provider": "openrouter"` — and the key
+ * lives either in the environment or in `~/.loom/providers.json`, mode 0600,
+ * beside the daemon token that already lives there under the same rule.
+ *
+ * Nothing here returns a key to an HTTP client, logs one, or prints one. What
+ * a person sees is whether a provider is configured and the last four
+ * characters, which is enough to tell two keys apart and not enough to use
+ * one.
+ *
+ * ## Providers differ in ways that matter
+ *
+ * They all speak `/v1/chat/completions`, and then each has a quirk: OpenRouter
+ * wants attribution headers, AgentRouter refuses clients it doesn't recognise,
+ * a local Ollama wants no key at all. Those live in the table rather than in
+ * the adapter, so adding a provider is data.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loomHome } from "./registry.js";
+/**
+ * The ones Loom knows by name. Anything else is a custom provider: give it a
+ * base URL and it works, because the protocol is the protocol.
+ */
+export const BUILTIN_PROVIDERS = [
+    {
+        id: "openrouter",
+        label: "OpenRouter",
+        baseUrl: "https://openrouter.ai/api",
+        envKeys: ["OPENROUTER_API_KEY"],
+        // OpenRouter asks callers to identify the app; it's used for their
+        // leaderboards and rate limits, and it's ours to give honestly.
+        headers: {
+            "HTTP-Referer": "https://github.com/nickthelegend/loom",
+            "X-Title": "Loom",
+        },
+        // Their own convention: a free model's id ends in `:free`.
+        free: (id) => id.endsWith(":free"),
+        docs: "https://openrouter.ai/docs",
+    },
+    {
+        id: "agentrouter",
+        label: "AgentRouter",
+        baseUrl: "https://agentrouter.org",
+        envKeys: ["AGENTROUTER_API_KEY"],
+        // Everything AgentRouter serves is free quota, which is the whole point
+        // of the service.
+        free: () => true,
+        note: "refuses clients it doesn't recognise (401 unauthorized_client_error) — ask them to allow-list Loom, or set a user-agent they accept with `loom providers:set agentrouter --header`",
+        docs: "https://agentrouter.org/docs/",
+    },
+    {
+        id: "openai",
+        label: "OpenAI",
+        baseUrl: "https://api.openai.com",
+        envKeys: ["OPENAI_API_KEY"],
+        docs: "https://platform.openai.com/docs/api-reference",
+    },
+    {
+        id: "groq",
+        label: "Groq",
+        baseUrl: "https://api.groq.com/openai",
+        envKeys: ["GROQ_API_KEY"],
+        docs: "https://console.groq.com/docs",
+    },
+    {
+        id: "ollama",
+        label: "Ollama (local)",
+        baseUrl: "http://127.0.0.1:11434",
+        envKeys: ["OLLAMA_API_KEY"],
+        // A local server wants no key, and demanding one would be theatre.
+        free: () => true,
+        note: "local — no key needed",
+        docs: "https://github.com/ollama/ollama/blob/main/docs/api.md",
+    },
+];
+export function providersFile() {
+    return path.join(loomHome(), "providers.json");
+}
+function readStore() {
+    try {
+        return JSON.parse(fs.readFileSync(providersFile(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeStore(store) {
+    const file = providersFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // 0600 before anything is in it: the window between create and chmod is
+    // exactly when a key would be world-readable.
+    fs.writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+/** The spec for an id, built-in or stored, or null if nobody has heard of it. */
+export function specFor(id) {
+    const builtin = BUILTIN_PROVIDERS.find((p) => p.id === id);
+    if (builtin)
+        return builtin;
+    const stored = readStore()[id];
+    if (!stored?.baseUrl)
+        return null;
+    return {
+        id,
+        label: stored.label ?? id,
+        baseUrl: stored.baseUrl.replace(/\/+$/, ""),
+        envKeys: [`${id.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`],
+    };
+}
+/**
+ * Everything needed to make a call: URL, key, headers.
+ *
+ * The environment wins over the stored file, so a shell that sets a key for
+ * one run doesn't have to undo anything afterwards.
+ */
+export function resolveProvider(id, env = process.env) {
+    const spec = specFor(id);
+    if (!spec)
+        return null;
+    const stored = readStore()[id] ?? {};
+    const key = spec.envKeys.map((k) => env[k]).find((v) => v?.trim()) ?? stored.key ?? null;
+    return {
+        id: spec.id,
+        label: stored.label ?? spec.label,
+        baseUrl: (stored.baseUrl ?? spec.baseUrl).replace(/\/+$/, ""),
+        key: key?.trim() || null,
+        headers: { ...(spec.headers ?? {}), ...(stored.headers ?? {}) },
+        free: spec.free ?? (() => false),
+        ...(spec.note ? { note: spec.note } : {}),
+        ...(spec.docs ? { docs: spec.docs } : {}),
+    };
+}
+/** Save a key, a base URL, headers — any subset. Writes 0600. */
+export function setProvider(id, patch) {
+    const clean = id.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(clean))
+        throw new Error(`"${id}" isn't a usable provider id`);
+    if (!specFor(clean) && !patch.baseUrl) {
+        throw new Error(`"${clean}" isn't a provider Loom knows — give it a base URL and it will be`);
+    }
+    const store = readStore();
+    const next = { ...(store[clean] ?? {}), ...patch };
+    if (next.baseUrl)
+        next.baseUrl = next.baseUrl.replace(/\/+$/, "");
+    store[clean] = next;
+    writeStore(store);
+}
+export function forgetProvider(id) {
+    const store = readStore();
+    if (!(id in store))
+        return false;
+    delete store[id];
+    writeStore(store);
+    return true;
+}
+/** The last four characters, which tells two keys apart and uses neither. */
+export function maskKey(key) {
+    if (!key)
+        return "";
+    return key.length <= 4 ? "…" : `…${key.slice(-4)}`;
+}
+/** Every provider Loom knows or has been told about, and whether it can be used. */
+export function listProviders(env = process.env) {
+    const ids = new Set([...BUILTIN_PROVIDERS.map((p) => p.id), ...Object.keys(readStore())]);
+    const out = [];
+    for (const id of ids) {
+        const p = resolveProvider(id, env);
+        if (!p)
+            continue;
+        const spec = specFor(id);
+        const fromEnv = Boolean(spec?.envKeys.some((k) => env[k]?.trim()));
+        out.push({
+            id: p.id,
+            label: p.label,
+            baseUrl: p.baseUrl,
+            configured: Boolean(p.key) || id === "ollama",
+            hint: maskKey(p.key),
+            source: fromEnv ? "env" : p.key ? "file" : "none",
+            ...(p.note ? { note: p.note } : {}),
+            ...(p.docs ? { docs: p.docs } : {}),
+        });
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+// ---------------------------------------------------------------------------
+// The wire
+// ---------------------------------------------------------------------------
+export function chatUrl(p) {
+    return `${p.baseUrl}/v1/chat/completions`;
+}
+export function modelsUrl(p) {
+    return `${p.baseUrl}/v1/models`;
+}
+/**
+ * Headers for a request. A provider with no key gets none — a local server
+ * doesn't want `Authorization: Bearer null`, which is a 401 that reads like a
+ * bad key rather than like no key.
+ */
+export function requestHeaders(p) {
+    return {
+        "content-type": "application/json",
+        accept: "application/json",
+        ...p.headers,
+        ...(p.key ? { authorization: `Bearer ${p.key}` } : {}),
+    };
+}
+/**
+ * Turn a provider's refusal into something a person can act on.
+ *
+ * These four are the ones worth naming: they're the difference between "your
+ * key is wrong", "your free quota is spent", "that model is gone" and "slow
+ * down", and each has a different next step.
+ */
+export function explainStatus(status, body, p) {
+    const snippet = body.replace(/\s+/g, " ").slice(0, 200);
+    if (status === 401 && /unauthorized_client|client detected/i.test(body)) {
+        return `${p.label} refused Loom as a client, not your key — it only accepts callers it recognises. ${p.note ?? ""}`.trim();
+    }
+    // "only available on agentic harnesses": the provider keeps this model for its
+    // own app list. Nothing is wrong with the key, and a key check would mislead.
+    if ((status === 403 || status === 404) && /only available (?:on|to|in)|not available (?:for|to|via)|restricted to/i.test(body)) {
+        return `${p.label} doesn't serve this model to Loom (${status}) — it keeps it for its own app list. Your key is fine: pick another model, or \`pool:free\` to spread across the free ones. ${snippet}`;
+    }
+    if (status === 401 || status === 403) {
+        return `${p.label} rejected the key (${status}). Check it with \`loom providers\`. ${snippet}`;
+    }
+    if (status === 402) {
+        return `${p.label} has no quota left for this model right now (402). Another model on the same key may still work. ${snippet}`;
+    }
+    if (status === 404 || status === 503) {
+        return `${p.label} has no channel for that model (${status}) — the name may be wrong or the model retired. \`loom models --refresh\`. ${snippet}`;
+    }
+    if (status === 429)
+        return `${p.label} is rate-limiting this key (429). ${snippet}`;
+    return `${p.label} answered ${status}: ${snippet}`;
+}
+/** Is this the kind of failure another model on the same key might survive? */
+export function isExhausted(status) {
+    return status === 402 || status === 429;
+}
+/** How long a model list is believed before asking again. */
+export const MODELS_TTL_MS = 10 * 60_000;
+function cacheFile() {
+    return path.join(loomHome(), "models-cache.json");
+}
+function readCache() {
+    try {
+        return JSON.parse(fs.readFileSync(cacheFile(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The models a provider has right now.
+ *
+ * Cached on disk rather than in memory: the CLI is a new process every time,
+ * and asking a provider for its catalogue once per command is rude to them and
+ * slow for you. `refresh` skips the cache — which is what a model that has
+ * just appeared (or vanished) needs.
+ */
+export async function fetchModels(p, opts = {}) {
+    const cache = readCache();
+    const hit = cache[p.id];
+    if (!opts.refresh && hit && Date.now() - hit.at < MODELS_TTL_MS) {
+        return { models: hit.models, cached: true };
+    }
+    const doFetch = opts.fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(modelsUrl(p), { headers: requestHeaders(p) });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            // A stale list beats no list: the models probably still exist, and the
+            // person asked what they could use, not whether the network is up.
+            return { models: hit?.models ?? [], cached: Boolean(hit), error: explainStatus(res.status, body, p) };
+        }
+        const body = (await res.json());
+        const models = (body.data ?? [])
+            .map((m) => String(m.id ?? ""))
+            .filter(Boolean)
+            .map((id) => {
+            const raw = (body.data ?? []).find((m) => m.id === id);
+            return {
+                id,
+                provider: p.id,
+                free: p.free(id),
+                ...(raw?.supported_endpoint_types ? { endpoints: raw.supported_endpoint_types } : {}),
+            };
+        })
+            .sort((a, b) => a.id.localeCompare(b.id));
+        try {
+            const next = { ...cache, [p.id]: { at: Date.now(), models } };
+            fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
+            fs.writeFileSync(cacheFile(), JSON.stringify(next));
+        }
+        catch {
+            /* a cache that can't be written is still a list that can be returned */
+        }
+        return { models, cached: false };
+    }
+    catch (err) {
+        return {
+            models: hit?.models ?? [],
+            cached: Boolean(hit),
+            error: `couldn't reach ${p.label}: ${String(err.message)}`,
+        };
+    }
+}
+/** Every configured provider's models, for a picker that spans providers. */
+export async function allModels(opts = {}) {
+    const env = opts.env ?? process.env;
+    const models = [];
+    const errors = [];
+    for (const row of listProviders(env)) {
+        if (!row.configured)
+            continue;
+        const p = resolveProvider(row.id, env);
+        if (!p)
+            continue;
+        const got = await fetchModels(p, opts.refresh ? { refresh: true } : {});
+        // A provider with free models offers the free pool first: every turn on the
+        // next free model in a rotation (core/free-pool.ts), so the work spreads.
+        if (got.models.some((m) => m.free))
+            models.push({ id: "pool:free", provider: row.id, free: true });
+        models.push(...got.models);
+        if (got.error)
+            errors.push({ provider: row.id, error: got.error });
+    }
+    return { models, errors };
+}
+//# sourceMappingURL=providers.js.map

package/dist/core/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/core/providers.ts"],"names":[],"mappings":"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"}

package/dist/core/quota.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Quota Relay — recognising "this agent is out of quota", and until when.
+ *
+ * A subscription CLI that hits its 5-hour or weekly cap mid-task either parks
+ * the turn until the reset (Claude Code: no result arrives for hours) or ends
+ * it with an error (Codex: "You've hit your usage limit… try again at 3:04
+ * PM"). Either way the work stops. Loom sees both: Claude and Codex report
+ * their windows as a `usage_limits` status with `reached` set, and every CLI
+ * says it in words. This file turns either into { resetAt }; the runtime
+ * (daemon/runtime/relay.ts) hands the work to the next agent.
+ */
+import type { LoomEvent } from "../types.js";
+export interface QuotaHit {
+    /** When the limit lifts (epoch ms), when the agent said; otherwise a guess an hour out. */
+    resetAt: number;
+    /** Whether resetAt came from the agent rather than the default. */
+    known: boolean;
+    /** Which window: "five_hour", "seven_day", "primary"… or "limit". */
+    window: string;
+    /** The words, for the thread. */
+    reason: string;
+}
+/** The default when the agent doesn't say when: an hour, the shortest common window. */
+export declare const UNKNOWN_RESET_MS: number;
+/**
+ * "try again at 3:04 PM", "resets at 19:00", "resets in 2 hours",
+ * "in 45 minutes", "resets Oct 16, 9:00 AM" → epoch ms (the next such moment).
+ */
+export declare function parseReset(text: string, now?: number): number | null;
+/** Did this event say the agent is out of quota? */
+export declare function quotaHit(event: LoomEvent, now?: number): QuotaHit | null;
+/** "19:00" / "tomorrow 09:00" — when it's back, for a person reading the thread. */
+export declare function backAt(resetAt: number, now?: number): string;

package/dist/core/quota.js

@@ -0,0 +1,74 @@
+/**
+ * Quota Relay — recognising "this agent is out of quota", and until when.
+ *
+ * A subscription CLI that hits its 5-hour or weekly cap mid-task either parks
+ * the turn until the reset (Claude Code: no result arrives for hours) or ends
+ * it with an error (Codex: "You've hit your usage limit… try again at 3:04
+ * PM"). Either way the work stops. Loom sees both: Claude and Codex report
+ * their windows as a `usage_limits` status with `reached` set, and every CLI
+ * says it in words. This file turns either into { resetAt }; the runtime
+ * (daemon/runtime/relay.ts) hands the work to the next agent.
+ */
+const LIMIT_TEXT = /\b(?:usage limit|hit (?:your|the) (?:usage |rate )?limit|rate[- ]limit(?:ed)?|quota (?:exceeded|exhausted|reached)|exceeded (?:your |the )?(?:current )?quota|limit reached|too many requests|out of (?:credits|quota)|credits? (?:exhausted|exceeded)|insufficient (?:quota|credits|balance)|weekly limit|5-hour limit)\b/i;
+/** Words that mean it's *not* a quota: a context window, a file-size or a request-size limit. */
+const NOT_QUOTA = /\b(?:context (?:window|length)|token limit for (?:this|the) (?:request|prompt)|max(?:imum)? (?:tokens|context)|too large|file size|payload)\b/i;
+/** The default when the agent doesn't say when: an hour, the shortest common window. */
+export const UNKNOWN_RESET_MS = 60 * 60_000;
+/**
+ * "try again at 3:04 PM", "resets at 19:00", "resets in 2 hours",
+ * "in 45 minutes", "resets Oct 16, 9:00 AM" → epoch ms (the next such moment).
+ */
+export function parseReset(text, now = Date.now()) {
+    const t = text.replace(/\s+/g, " ");
+    let m = /\b(?:in|after)\s+(\d+(?:\.\d+)?)\s*(minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/i.exec(t);
+    if (m) {
+        const n = Number(m[1]), unit = m[2].toLowerCase();
+        const ms = unit.startsWith("d") ? 86_400_000 : unit.startsWith("h") ? 3_600_000 : 60_000;
+        return now + Math.round(n * ms);
+    }
+    m = /\b(?:at|after|until|resets?(?: at)?|try again at)\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\b/i.exec(t);
+    if (m && (m[2] !== undefined || m[3] !== undefined)) {
+        let h = Number(m[1]);
+        const min = Number(m[2] ?? 0), ap = m[3]?.toLowerCase();
+        if (ap === "pm" && h < 12)
+            h += 12;
+        if (ap === "am" && h === 12)
+            h = 0;
+        if (h > 23 || min > 59)
+            return null;
+        const d = new Date(now);
+        d.setHours(h, min, 0, 0);
+        if (d.getTime() <= now)
+            d.setDate(d.getDate() + 1);
+        return d.getTime();
+    }
+    return null;
+}
+/** Did this event say the agent is out of quota? */
+export function quotaHit(event, now = Date.now()) {
+    const p = event.payload;
+    if (event.kind === "status" && p.state === "usage_limits" && typeof p.reached === "string" && p.reached) {
+        const windows = Array.isArray(p.windows) ? p.windows : [];
+        const hit = windows.find((w) => w.id === p.reached) ?? windows.find((w) => typeof w.resetsAt === "number");
+        const resetAt = typeof hit?.resetsAt === "number" && hit.resetsAt > now ? hit.resetsAt : null;
+        return { resetAt: resetAt ?? now + UNKNOWN_RESET_MS, known: resetAt !== null, window: p.reached,
+            reason: `usage limit reached (${p.reached})` };
+    }
+    const text = event.kind === "error" ? String(p.message ?? "")
+        : event.kind === "run_complete" && typeof p.error === "string" ? p.error
+            : event.kind === "status" && (p.state === "notice" || p.state === "warning") ? String(p.message ?? "") : "";
+    // a CLI retrying a brief rate limit by itself hasn't stopped: no relay for that
+    if (p.retrying === true)
+        return null;
+    if (!text || !LIMIT_TEXT.test(text) || NOT_QUOTA.test(text))
+        return null;
+    const resetAt = parseReset(text, now);
+    return { resetAt: resetAt ?? now + UNKNOWN_RESET_MS, known: resetAt !== null, window: "limit", reason: text.trim().slice(0, 240) };
+}
+/** "19:00" / "tomorrow 09:00" — when it's back, for a person reading the thread. */
+export function backAt(resetAt, now = Date.now()) {
+    const d = new Date(resetAt), today = new Date(now);
+    const time = d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+    return d.toDateString() === today.toDateString() ? time : `${d.toLocaleDateString([], { weekday: "short" })} ${time}`;
+}
+//# sourceMappingURL=quota.js.map

package/dist/core/quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../src/core/quota.ts"],"names":[],"mappings":"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"}

package/dist/core/recipes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A queue worth keeping: the same five steps you run on every project.
+ *
+ * "Update deps, run the tests, fix what broke, update the changelog, open the
+ * PR" is a queue you build by hand every time. A recipe is that queue saved —
+ * an ordered list of prompts, each remembering who it goes to.
+ *
+ * Targets travel by ROLE rather than by agent id, because `claude-code` on one
+ * project is `reviewer` on another and an id from someone else's machine means
+ * nothing here. Running a recipe resolves those roles against the project it
+ * lands in, and anything it can't resolve becomes an Auto prompt rather than a
+ * refusal — the prompts are still editable before they go.
+ *
+ * Stored in ~/.loom/recipes.json. Nothing leaves the machine.
+ */
+import type { QueueTarget } from "./prompt-queue.js";
+export interface RecipeStep {
+    text: string;
+    /** "auto", "orchestra", or a role/kind like "reviewer" or "codex". */
+    to: string;
+    plan?: boolean;
+}
+export interface Recipe {
+    name: string;
+    steps: RecipeStep[];
+    /** Where it came from, for the person reading a list of them later. */
+    fromProject?: string;
+    savedAt: number;
+}
+export declare const MAX_STEPS = 50;
+export declare function listRecipes(): Recipe[];
+export declare function getRecipe(name: string): Recipe | null;
+/** Save (or replace) a recipe. Names are how you call it back, so they're checked. */
+export declare function saveRecipe(recipe: Omit<Recipe, "savedAt">): Recipe;
+export declare function deleteRecipe(name: string): boolean;
+/** What a queued item's target becomes when a recipe is saved. */
+export declare function targetToRole(target: QueueTarget, roleOf: (agentId: string) => string | undefined): string;
+/**
+ * Resolve a saved step's target against a project's agents.
+ *
+ * An exact id wins, then a role, then a kind. Nothing matching means Auto: the
+ * prompt still runs, the router still picks, and the person can still change
+ * it before it goes — better than refusing a recipe because a machine happens
+ * to call its reviewer something else.
+ */
+export declare function roleToTarget(to: string, agents: Array<{
+    id: string;
+    role?: string;
+    kind?: string;
+}>): QueueTarget;

package/dist/core/recipes.js

@@ -0,0 +1,99 @@
+/**
+ * A queue worth keeping: the same five steps you run on every project.
+ *
+ * "Update deps, run the tests, fix what broke, update the changelog, open the
+ * PR" is a queue you build by hand every time. A recipe is that queue saved —
+ * an ordered list of prompts, each remembering who it goes to.
+ *
+ * Targets travel by ROLE rather than by agent id, because `claude-code` on one
+ * project is `reviewer` on another and an id from someone else's machine means
+ * nothing here. Running a recipe resolves those roles against the project it
+ * lands in, and anything it can't resolve becomes an Auto prompt rather than a
+ * refusal — the prompts are still editable before they go.
+ *
+ * Stored in ~/.loom/recipes.json. Nothing leaves the machine.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loomHome } from "./registry.js";
+export const MAX_STEPS = 50;
+function file() {
+    return path.join(loomHome(), "recipes.json");
+}
+export function listRecipes() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file(), "utf8"));
+        return Array.isArray(raw) ? raw.filter((r) => r?.name && Array.isArray(r.steps)) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function getRecipe(name) {
+    return listRecipes().find((r) => r.name === name) ?? null;
+}
+function write(all) {
+    fs.mkdirSync(loomHome(), { recursive: true });
+    fs.writeFileSync(file(), JSON.stringify(all, null, 2));
+}
+/** Save (or replace) a recipe. Names are how you call it back, so they're checked. */
+export function saveRecipe(recipe) {
+    const name = recipe.name.trim();
+    if (!/^[\w][\w .-]{0,48}$/.test(name))
+        throw new Error(`"${name}" isn't a usable recipe name`);
+    if (!recipe.steps.length)
+        throw new Error("a recipe with no steps isn't a recipe");
+    if (recipe.steps.length > MAX_STEPS)
+        throw new Error(`a recipe holds at most ${MAX_STEPS} steps`);
+    const steps = recipe.steps.map((s) => {
+        const text = String(s.text ?? "").trim();
+        if (!text)
+            throw new Error("a recipe step needs something to say");
+        return { text, to: String(s.to ?? "auto").trim() || "auto", ...(s.plan ? { plan: true } : {}) };
+    });
+    const saved = { name, steps, ...(recipe.fromProject ? { fromProject: recipe.fromProject } : {}), savedAt: Date.now() };
+    write([saved, ...listRecipes().filter((r) => r.name !== name)]);
+    return saved;
+}
+export function deleteRecipe(name) {
+    const all = listRecipes();
+    const left = all.filter((r) => r.name !== name);
+    if (left.length === all.length)
+        return false;
+    write(left);
+    return true;
+}
+/** What a queued item's target becomes when a recipe is saved. */
+export function targetToRole(target, roleOf) {
+    if (target.kind === "orchestra")
+        return "orchestra";
+    if (target.kind === "auto")
+        return "auto";
+    return roleOf(target.agentId) ?? target.agentId;
+}
+/**
+ * Resolve a saved step's target against a project's agents.
+ *
+ * An exact id wins, then a role, then a kind. Nothing matching means Auto: the
+ * prompt still runs, the router still picks, and the person can still change
+ * it before it goes — better than refusing a recipe because a machine happens
+ * to call its reviewer something else.
+ */
+export function roleToTarget(to, agents) {
+    const want = to.trim().toLowerCase();
+    if (!want || want === "auto")
+        return { kind: "auto" };
+    if (want === "orchestra" || want === "orchestrate")
+        return { kind: "orchestra" };
+    const byId = agents.find((a) => a.id.toLowerCase() === want);
+    if (byId)
+        return { kind: "agent", agentId: byId.id };
+    const byRole = agents.find((a) => (a.role ?? "").toLowerCase() === want);
+    if (byRole)
+        return { kind: "agent", agentId: byRole.id };
+    const byKind = agents.find((a) => (a.kind ?? "").toLowerCase() === want);
+    if (byKind)
+        return { kind: "agent", agentId: byKind.id };
+    return { kind: "auto" };
+}
+//# sourceMappingURL=recipes.js.map

package/dist/core/recipes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.js","sourceRoot":"","sources":["../../src/core/recipes.ts"],"names":[],"mappings":"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"}