summer-engine 4.0.0 → 4.3.0

package/dist/core/ops/search.js

@@ -1,53 +1,185 @@
+import { stem } from "../registry-search.js";
 /**
- * Plain-words ranking over operations, the same scoring the hosted server
- * uses, so one list can hold local and cloud hits.
+ * Plain-words ranking over operations. cloud.ts ranks the local rows, the
+ * shipped cloud catalog and the server's live rows together here, so a query
+ * ranks the same signed in or out.
+ *
+ * - A query word scores by the best place it meets a row: the action (the
+ *   name after the dot) 7, the area or the title 4, a short tag 3, a 3.x name
+ *   2, the summary or a long use-when line 1. An exact word counts whole, a
+ *   stemmed one 0.9, a prefix half, a plain-English synonym (SYNONYMS) 0.7.
+ * - Rare words weigh more (idf over the rows searched) and everyday verbs
+ *   half: in "publish my game" publish decides, in "add multiplayer"
+ *   multiplayer does.
+ * - A row that meets every word in its name, title or short tags keeps its
+ *   score; one that meets none of them there keeps half. One whose whole
+ *   action the query names gains a quarter: "publish" is store.publish
+ *   before store.cancel_publish.
+ * - A title or tag the query says nearly word for word, articles aside
+ *   ("how is my game doing" for "how did my game do"), adds 2 per word.
  */
-const STOP = new Set(["a", "an", "the", "my", "of", "for", "to", "in", "on", "and", "or", "with", "is", "it", "me", "i", "please", "how", "do", "what"]);
+const STOP = new Set([
+    "a", "an", "the", "my", "of", "for", "to", "in", "on", "and", "or", "with", "is", "it", "me", "i", "please", "how", "do", "what",
+    "did", "does", "doing", "done", "am", "are", "was", "were", "be", "have", "has", "had", "can", "could", "would", "should", "will",
+    "want", "need", "this", "that", "these", "those", "some", "any", "many", "much", "why", "where", "when", "which", "there", "you",
+    "your", "we", "our", "us", "at", "by", "from", "as", "so", "just", "s",
+]);
+/** Verbs that say what to do but rarely which operation: the object does. */
+const EVERYDAY_VERBS = new Set(["add", "make", "create", "set", "get", "change", "update", "edit", "run", "start", "put", "take", "show", "read", "list", "use", "give", "check", "find", "see", "turn", "open"]);
+/** Left out of phrase matching: "put my game on sale" says "Put a game on sale". */
+const ARTICLES = new Set(["a", "an", "the", "my", "your", "our", "their", "its", "this", "that"]);
+/** Irregular forms, so "how did my game do" meets "how is my game doing". */
+const IRREGULAR = { did: "do", does: "do", doing: "do", done: "do", is: "be", are: "be", was: "be", were: "be", am: "be", has: "have", had: "have" };
+/** Plain English to the catalog's words (stemmed keys). */
+const SYNONYMS = {
+    make: ["generate", "create"],
+    create: ["generate", "make"],
+    picture: ["image"],
+    drawing: ["image"],
+    photo: ["image"],
+    model: ["3d"],
+    mesh: ["3d"],
+    sound: ["audio"],
+    music: ["audio"],
+    song: ["audio"],
+    clip: ["video"],
+    movie: ["video"],
+    film: ["video"],
+    animate: ["motion"],
+    animation: ["motion"],
+    run: ["play", "start"],
+    cost: ["price"],
+    teammate: ["member"],
+    character: ["model"],
+    game: ["store"],
+    error: ["diagnostic"],
+    bug: ["error", "diagnostic"],
+};
+const norm = (word) => IRREGULAR[word] ?? stem(word);
+const tokens = (text) => text
+    .toLowerCase()
+    .replace(/\ba\/b\b/g, "ab")
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .map((raw) => ({ raw, normed: norm(raw) }));
 export function words(text) {
-    return text
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((word) => word.length > 1 && !STOP.has(word));
-}
-const stem = (word) => word.length > 3 && word.endsWith("ies") ? `${word.slice(0, -3)}y` : word.length > 3 && word.endsWith("s") && !word.endsWith("ss") ? word.slice(0, -1) : word;
-export function scoreEntry(entry, query) {
-    const terms = words(query);
-    if (!terms.length)
-        return 0;
-    const exact = query.trim().toLowerCase();
-    if (exact === entry.name || entry.legacy?.some((name) => name.split("#")[0] === exact))
-        return 1000;
+    return tokens(text)
+        .filter(({ raw }) => raw.length > 1 && !STOP.has(raw))
+        .map(({ raw }) => raw);
+}
+const indexCache = new WeakMap();
+function indexed(entry) {
+    const cached = indexCache.get(entry);
+    if (cached)
+        return cached;
+    const [area, action] = entry.name.includes(".") ? entry.name.split(".") : ["", entry.name];
+    const kept = (text) => tokens(text).filter(({ raw }) => raw.length > 1 && !STOP.has(raw));
+    const tags = entry.tags ?? [];
+    // A tag of a few words is a keyword; a long one (a use-when line) reads like the summary.
+    const short = (tag) => tokens(tag).length <= 3;
     const fields = [
-        [words(entry.name.replace(/[._]/g, " ")), 6],
-        [words(entry.title), 4],
-        [(entry.tags ?? []).flatMap(words), 3],
-        [(entry.legacy ?? []).flatMap((name) => words(name.replace(/^summer_/, "").replace(/[#_]/g, " "))), 2],
-        [words(entry.summary), 1],
+        { weight: 7, words: kept(action.replace(/_/g, " ")) },
+        { weight: 4, words: kept(area) },
+        { weight: 4, words: kept(entry.title) },
+        { weight: 3, words: [...tags.filter(short), ...(entry.topics ?? [])].flatMap(kept) },
+        { weight: 2, words: (entry.legacy ?? []).flatMap((name) => kept(name.replace(/^summer_/, "").replace(/[#_]/g, " "))) },
+        { weight: 1, words: [entry.summary, ...tags.filter((tag) => !short(tag))].flatMap(kept) },
     ];
-    let total = 0;
-    for (const term of terms.map(stem)) {
-        let best = 0;
-        for (const [fieldWords, weight] of fields) {
-            for (const word of fieldWords) {
-                const candidate = stem(word);
-                if (candidate === term)
-                    best = Math.max(best, weight);
-                else if (term.length >= 4 && candidate.length >= 3 && (candidate.startsWith(term) || term.startsWith(candidate)))
-                    best = Math.max(best, weight / 2);
-            }
+    const phrases = [entry.title, ...tags].map((text) => tokens(text).filter(({ raw }) => !ARTICLES.has(raw))).filter((phrase) => phrase.length >= 2);
+    const result = { fields, phrases, action: kept(action.replace(/_/g, " ")), area: kept(area) };
+    indexCache.set(entry, result);
+    return result;
+}
+/** How well one query word meets one row word: exact 1, same stem 0.9, a prefix 0.5 ("anim" in animation; not "play" in players). */
+function meets(term, word) {
+    if (word.raw === term.raw)
+        return 1;
+    if (word.normed === term.normed)
+        return 0.9;
+    const [a, b] = [term.normed, word.normed];
+    return (a.length >= 4 && b.startsWith(a)) || (b.length >= 5 && a.startsWith(b)) ? 0.5 : 0;
+}
+const alternatesOf = (term) => (SYNONYMS[term.normed] ?? []).map((synonym) => ({ raw: synonym, normed: norm(synonym) }));
+/** A query word's best weight in a row, and whether it met a strong field (weight 3 or more). */
+function best(term, entry, synonyms = true) {
+    const alternates = synonyms ? alternatesOf(term) : [];
+    let score = 0;
+    let strong = false;
+    for (const field of indexed(entry).fields) {
+        for (const word of field.words) {
+            const quality = Math.max(meets(term, word), ...alternates.map((alternate) => 0.7 * meets(alternate, word)));
+            if (quality === 0)
+                continue;
+            score = Math.max(score, field.weight * quality);
+            if (field.weight >= 3)
+                strong = true;
         }
-        total += best;
     }
-    return total;
+    return { score, strong };
+}
+/** The best title or tag the query says nearly word for word: 2 per word met. */
+function phraseBonus(entry, all) {
+    const query = all.filter(({ raw }) => !ARTICLES.has(raw));
+    let bonus = 0;
+    for (const phrase of indexed(entry).phrases) {
+        const met = phrase.map((word) => Math.max(0, ...query.map((term) => (term.raw === word.raw ? 1 : term.normed === word.normed ? 0.9 : alternatesOf(term).some((alternate) => alternate.normed === word.normed) ? 0.7 : 0))));
+        const count = met.filter((quality) => quality > 0).length;
+        const meaningful = phrase.some((word, index) => met[index] > 0 && !STOP.has(word.raw));
+        if (meaningful && count >= 2 && count / phrase.length >= 0.75)
+            bonus = Math.max(bonus, 2 * met.reduce((sum, quality) => sum + quality, 0));
+    }
+    return bonus;
+}
+/**
+ * The query names the row's whole action, and its area too when the action
+ * is only an everyday verb: "list my games" names games.list, "run my game"
+ * does not name engine.is_running.
+ */
+function namesAction(entry, terms) {
+    const { action, area } = indexed(entry);
+    const met = (word) => terms.some((term) => meets(term, word) >= 0.9);
+    return action.length > 0 && action.every(met) && (action.some((word) => !EVERYDAY_VERBS.has(word.normed)) || area.some(met));
+}
+function scoreAll(entries, query) {
+    const exact = query.trim().toLowerCase();
+    const all = tokens(query);
+    const terms = all.filter(({ raw }) => raw.length > 1 && !STOP.has(raw));
+    if (!terms.length)
+        return entries.map(() => 0);
+    // Rarer words weigh more: idf over the rows searched; everyday verbs count half.
+    const weightOf = terms.map((term) => {
+        const df = entries.filter((entry) => best(term, entry, false).score > 0).length;
+        return Math.log(1 + entries.length / (1 + df)) * (EVERYDAY_VERBS.has(term.normed) ? 0.5 : 1);
+    });
+    return entries.map((entry) => {
+        if (exact === entry.name || entry.legacy?.some((name) => name.split("#")[0] === exact))
+            return 1000;
+        let total = 0;
+        let strong = 0;
+        let missed = false;
+        terms.forEach((term, index) => {
+            const hit = best(term, entry);
+            total += weightOf[index] * hit.score;
+            if (hit.strong)
+                strong += 1;
+            if (hit.score === 0)
+                missed = true;
+        });
+        if (total === 0)
+            return 0;
+        return total * (0.5 + (0.5 * strong) / terms.length) * (!missed && namesAction(entry, terms) ? 1.25 : 1) + phraseBonus(entry, all);
+    });
 }
 const STATUS_RANK = { stable: 0, preview: 1, deprecated: 2 };
 export function searchEntries(entries, query, filters) {
     const hasTerms = words(query).length > 0;
-    return entries
+    const kept = entries
         .filter((entry) => entry.status !== "deprecated")
         .filter((entry) => !filters.area || entry.name === filters.area || entry.name.startsWith(`${filters.area}.`))
-        .filter((entry) => !filters.effect || entry.effect === filters.effect)
-        .map((entry) => ({ entry, score: scoreEntry(entry, query) }))
+        .filter((entry) => !filters.effect || entry.effect === filters.effect);
+    const scores = scoreAll(kept, query);
+    return kept
+        .map((entry, index) => ({ entry, score: scores[index] }))
         .filter(({ score }) => score > 0 || !hasTerms)
         .sort((a, b) => b.score - a.score || STATUS_RANK[a.entry.status] - STATUS_RANK[b.entry.status] || Number(b.entry.available) - Number(a.entry.available) || a.entry.name.localeCompare(b.entry.name))
         .slice(0, filters.limit)

package/dist/core/telemetry.d.ts

@@ -36,9 +36,19 @@ export interface LocalToolCall {
     surfaceVersion?: "v3" | "v4";
     /** The MCP profile: full, engine, assets or custom. */
     profile?: string;
+    /** A failed call's error code (toolErrorCode); never sent for a call that worked. */
+    error?: string | null;
 }
+/**
+ * The code a failed tool result names, read from its first text block: the
+ * one answer shape's `error.code`, the 3.x `code`, then an engine
+ * `failure_reason`. Codes only, never the message or anything else.
+ */
+export declare function toolErrorCode(result: unknown, fallback?: string): string | null;
 /** Report one local tool call: tool name, success, duration, host app name. */
 export declare function recordLocalToolCall(call: LocalToolCall): void;
+/** POST one usage line with the account token; resolves when sent or given up. Never throws. */
+export declare function postUsage(body: Record<string, unknown>, timeoutMs?: number): Promise<void>;
 /**
  * Reset the once-per-session guard. Test-only.
  */

package/dist/core/telemetry.js

@@ -36,6 +36,33 @@ export function recordMcpSession() {
     const mcpClient = currentMcpClient()?.name;
     send({ client: "summer-cli", event: "mcp_session_start", ...(mcpClient ? { mcpClient: mcpClient.slice(0, 64) } : {}) });
 }
+const ERROR_CODE = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * The code a failed tool result names, read from its first text block: the
+ * one answer shape's `error.code`, the 3.x `code`, then an engine
+ * `failure_reason`. Codes only, never the message or anything else.
+ */
+export function toolErrorCode(result, fallback) {
+    const content = result?.content;
+    const text = Array.isArray(content) ? content[0]?.text : undefined;
+    let parsed = null;
+    if (typeof text === "string" && text.length < 200_000) {
+        try {
+            const value = JSON.parse(text);
+            if (value && typeof value === "object" && !Array.isArray(value))
+                parsed = value;
+        }
+        catch {
+            // plain text: no code in it
+        }
+    }
+    const nested = parsed?.error && typeof parsed.error === "object" ? parsed.error.code : undefined;
+    for (const candidate of [nested, parsed?.code, parsed?.failure_reason, fallback]) {
+        if (typeof candidate === "string" && ERROR_CODE.test(candidate))
+            return candidate;
+    }
+    return null;
+}
 /** Report one local tool call: tool name, success, duration, host app name. */
 export function recordLocalToolCall(call) {
     if (isTelemetryDisabled() || !TOOL_NAME.test(call.tool))
@@ -49,42 +76,44 @@ export function recordLocalToolCall(call) {
         ...(call.surfaceVersion ? { surfaceVersion: call.surfaceVersion } : {}),
         ...(call.profile ? { profile: call.profile } : {}),
         ok: call.ok,
+        ...(!call.ok && call.error && ERROR_CODE.test(call.error) ? { error: call.error } : {}),
         durationMs: Math.max(0, Math.round(call.durationMs)),
     });
 }
 function send(body) {
-    // Wrap the entire async pipeline in a void-discarded promise so the caller
-    // never accidentally awaits us.
-    void (async () => {
+    // Void-discarded so the caller never accidentally awaits us.
+    void postUsage(body);
+}
+/** POST one usage line with the account token; resolves when sent or given up. Never throws. */
+export async function postUsage(body, timeoutMs = TIMEOUT_MS) {
+    try {
+        const token = await getAuthToken();
+        if (!token)
+            return; // unauthenticated usage is allowed; we just can't attribute it
+        // Resolved per call, not at import: the gateway the token belongs to is
+        // whatever env/config says NOW (see config.resolveGatewayUrl).
+        const gatewayUrl = await resolveGatewayUrl();
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
         try {
-            const token = await getAuthToken();
-            if (!token)
-                return; // unauthenticated MCP usage is allowed; we just can't attribute it
-            // Resolved per call, not at import: the gateway the token belongs to is
-            // whatever env/config says NOW (see config.resolveGatewayUrl).
-            const gatewayUrl = await resolveGatewayUrl();
-            const ctrl = new AbortController();
-            const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
-            try {
-                await fetch(`${gatewayUrl}${TELEMETRY_PATH}`, {
-                    method: "POST",
-                    signal: ctrl.signal,
-                    headers: {
-                        ...summerRequestHeaders(),
-                        Authorization: `Bearer ${token}`,
-                        "Content-Type": "application/json",
-                    },
-                    body: JSON.stringify(body),
-                });
-            }
-            finally {
-                clearTimeout(timer);
-            }
+            await fetch(`${gatewayUrl}${TELEMETRY_PATH}`, {
+                method: "POST",
+                signal: ctrl.signal,
+                headers: {
+                    ...summerRequestHeaders(),
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+            });
         }
-        catch {
-            // never throws — telemetry is best-effort
+        finally {
+            clearTimeout(timer);
         }
-    })();
+    }
+    catch {
+        // never throws — telemetry is best-effort
+    }
 }
 /**
  * Reset the once-per-session guard. Test-only.

package/dist/installer/agent-config.js

@@ -52,6 +52,11 @@ export async function configureAgentMcp(options) {
     const profile = options.profile ?? spec.mcpProfile ?? "full";
     const server = withProfile(createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel), profile);
     const target = resolveConfigTarget(spec, options.scope, cwd, env);
+    // An entry an earlier setup wrote where the agent no longer reads (Devin Desktop moved from ~/.codeium/windsurf).
+    const moved = spec.mcp.movedFrom ? spec.mcp.movedFrom(defaultPathContext(env, cwd)) : null;
+    if (moved && moved !== target.path && (await readTextFileIfExists(moved)).includes(`"${SUMMER_MCP_SERVER_NAME}"`)) {
+        target.warnings.push(`${moved} still lists ${SUMMER_MCP_SERVER_NAME} from an earlier setup. ${spec.label} now reads ${target.path}, so setup writes it there; the old entry stays for older builds.`);
+    }
     const snippet = renderConfigSnippet(options.agent, server);
     const dryRun = Boolean(options.dryRun);
     const print = Boolean(options.print);

package/dist/installer/agent-table.d.ts

@@ -93,6 +93,8 @@ export interface AgentSpec {
         project: ((ctx: PathContext) => string) | null;
         /** Extra warning printed when project scope is requested (also when it is honoured). */
         projectNote?: string;
+        /** The user file the agent read before it moved: setup names an earlier summer-engine entry left there. */
+        movedFrom?: (ctx: PathContext) => string;
     };
     /** What to do after the config is written. */
     restart: string;
@@ -112,6 +114,13 @@ export declare const supportedAgents: readonly SupportedAgent[];
 export declare const skillCapableAgents: readonly SupportedAgent[];
 /** Every spelling → canonical id. Aliases must be unique across the table. */
 export declare function agentAliasMap(): Record<string, SupportedAgent>;
+/**
+ * Why `summer setup <agent> --cli` cannot set this agent up, or null. --cli
+ * installs the skills and no MCP server, so the agent needs a skills folder,
+ * and one that takes SKILL.md files: rule files (Roo Code) and the Gemini
+ * extension assume the MCP tools.
+ */
+export declare function cliSetupRefusal(spec: AgentSpec): string | null;
 export declare function agentLabel(id: SupportedAgent): string;
 export declare function defaultPathContext(env?: NodeJS.ProcessEnv, cwd?: string): PathContext;
 export interface ResolvedMcpPath {

package/dist/installer/agent-table.js

@@ -54,7 +54,8 @@ function appData(ctx) {
     return ctx.env.APPDATA ?? join(ctx.home, "AppData", "Roaming");
 }
 function xdgConfig(ctx) {
-    return ctx.env.XDG_CONFIG_HOME ?? join(ctx.home, ".config");
+    // An empty XDG_CONFIG_HOME counts as unset (XDG Base Directory spec).
+    return ctx.env.XDG_CONFIG_HOME || join(ctx.home, ".config");
 }
 /** ~/.config on Linux, %APPDATA% on Windows, ~/Library/Application Support on macOS. */
 function appConfigRoot(ctx) {
@@ -183,8 +184,10 @@ const SPECS = [
             signIn: (name) => `Devin Desktop opens summer.games in your browser the first time ${name} connects; sign in there.`,
         },
         mcp: {
-            user: home(".codeium", "windsurf", "mcp_config.json"),
+            // docs.devin.ai/desktop/cascade/mcp (2026-10-16): ~/.config/devin (or $XDG_CONFIG_HOME/devin), %APPDATA%\devin on Windows.
+            user: (ctx) => join(xdgOrAppData(ctx), "devin", "mcp_config.json"),
             project: null,
+            movedFrom: home(".codeium", "windsurf", "mcp_config.json"),
         },
         restart: "Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.",
         skills: sharedSkills({ legacyDirs: { user: home(".codeium", "windsurf", "skills"), project: project(".windsurf", "skills") } }),
@@ -685,6 +688,24 @@ export function agentAliasMap() {
     }
     return map;
 }
+/**
+ * Why `summer setup <agent> --cli` cannot set this agent up, or null. --cli
+ * installs the skills and no MCP server, so the agent needs a skills folder,
+ * and one that takes SKILL.md files: rule files (Roo Code) and the Gemini
+ * extension assume the MCP tools.
+ */
+export function cliSetupRefusal(spec) {
+    if (!spec.skills) {
+        return `${spec.label} has no skills folder, so --cli has nothing to install. Run summer setup ${spec.id} without --cli for the MCP server.`;
+    }
+    if (spec.format === "json-gemini") {
+        return `Gemini CLI loads Summer's skills only through its extension, which runs the MCP server. Run summer setup ${spec.id} without --cli, or use antigravity.`;
+    }
+    if (spec.skills.kind !== "skill-dir" && spec.skills.kind !== "opencode-skill-dir") {
+        return `${spec.label} gets Summer's skills as rule files that tell it to use the MCP tools. Run summer setup ${spec.id} without --cli.`;
+    }
+    return null;
+}
 export function agentLabel(id) {
     return agentSpec(id).label;
 }

package/dist/installer/cli-permissions.d.ts

@@ -0,0 +1,65 @@
+import type { PathContext, SupportedAgent } from "./agent-table.js";
+/**
+ * Allow rules for the CLI path, added only with `summer setup <agent> --cli
+ * --allow-rules --yes` (the flag is in the command the person approves), so
+ * the agent's read-only and dry-run summer commands do not each ask:
+ *
+ * - the reads in AUTO_ALLOWED_READS, as they are. The list is reviewed by
+ *   hand: a new read operation in the catalog does not join it, and
+ *   cli-permissions.test.ts fails until someone adds it on purpose;
+ * - every spend (generation and the rest) only as a dry run, `--dry-run`
+ *   right after the action. A call with that flag is a dry run whatever else
+ *   it says (parseCallFlags), so the rule cannot let a real spend through.
+ *
+ * Changes, publishing, prices, deletes and messages keep asking. Claude Code
+ * matches the command text (`Bash(summer jobs wait *)` matches the bare
+ * command and `summer jobs wait --job-id x`, not `summer jobs waitx`); Codex
+ * matches argument lists, in a rules file of Summer's own. Both get the
+ * `summer` and the `npx -y summer-engine@latest` forms.
+ */
+/**
+ * Reads that run without asking. Each one reads Summer data or the open
+ * editor's state; `jobs wait` and `assets get` also save the files a finished
+ * job names (media files only, never over an existing file). Left out on
+ * purpose: `engine capture-gameplay` (it starts Summer Engine on a project, so
+ * the project's own code runs, and writes to any --out folder) and
+ * `studio open` (it opens a page in the browser).
+ */
+export declare const AUTO_ALLOWED_READS: readonly string[];
+export type CliCommand = {
+    words: string[];
+    dryRun: boolean;
+};
+/** The commands allowed without asking: `summer status`, the reviewed reads, and a dry run of every spend in the catalog. */
+export declare function allowedCliCommands(): CliCommand[];
+export declare const LAUNCHERS: ReadonlyArray<readonly string[]>;
+/** Claude Code `permissions.allow` rules, for both launchers. */
+export declare function claudeAllowRules(): string[];
+/** Codex rules: one prefix_rule per launcher, area and kind, the actions as a union. */
+export declare function codexRules(): string;
+export interface AllowRulesResult {
+    agent: SupportedAgent;
+    path: string;
+    /** Every rule Summer wants there (Codex: its patterns); empty for a removal. */
+    rules: string[];
+    /** What this run added, or removed with --remove-allow-rules. */
+    changed: string[];
+    wrote: boolean;
+}
+/** The agents with clean per-command allow rules: Claude Code (settings.json) and Codex (rules files). */
+export declare function supportsAllowRules(agent: SupportedAgent): boolean;
+/**
+ * Where the rules go. Claude Code: the user's settings, or with --scope
+ * project the project's personal settings.local.json (never the shared file).
+ * Codex: always the user's rules folder; a project's .codex/rules is shared
+ * through git, so Summer does not write there.
+ */
+export declare function allowRulesPath(agent: SupportedAgent, scope: "user" | "project", ctx: PathContext): string;
+/**
+ * Add the allow rules. Claude Code: merged into `permissions.allow`, nothing
+ * removed, every other setting kept. Codex: Summer's own rules file,
+ * rewritten. Writes nothing unless `write`.
+ */
+export declare function addAllowRules(agent: SupportedAgent, path: string, write: boolean): Promise<AllowRulesResult>;
+/** Remove exactly the rules Summer adds (Claude Code), or Summer's own rules file (Codex). Writes nothing unless `write`. */
+export declare function removeAllowRules(agent: SupportedAgent, path: string, write: boolean): Promise<AllowRulesResult>;