@bubblebrain-ai/bubble 0.0.1

package/dist/permissions/settings.js

@@ -0,0 +1,202 @@
+/**
+ * Persistent permission settings.
+ *
+ * Three scopes, lowest to highest precedence:
+ *
+ *   user    — ~/.bubble/settings.json            (cross-project preferences)
+ *   project — <cwd>/.bubble/settings.json        (team-shared, check into git)
+ *   local   — <cwd>/.bubble/settings.local.json  (personal, gitignore)
+ *
+ * `defaultMode` uses last-wins precedence (local beats project beats user).
+ * `allow` / `deny` arrays are concatenated across scopes (with the rule text
+ * itself carrying provenance via `PermissionRule.source`).
+ *
+ * Parse errors do not fail the load; they collect into `diagnostics` so callers
+ * can surface them in /permissions or on startup without taking the agent down.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+import { normalizeLspConfig } from "../lsp/config.js";
+import { parseRules } from "./rule.js";
+const KNOWN_MODES = new Set([
+    "default",
+    "acceptEdits",
+    "plan",
+    "bypassPermissions",
+    "dontAsk",
+]);
+export class SettingsManager {
+    cwd;
+    paths;
+    raw = {
+        user: null,
+        project: null,
+        local: null,
+    };
+    fileDiagnostics = [];
+    constructor(cwd, options = {}) {
+        this.cwd = cwd;
+        const bubbleHome = options.bubbleHome ?? getBubbleHome();
+        this.paths = {
+            user: join(bubbleHome, "settings.json"),
+            project: join(cwd, ".bubble", "settings.json"),
+            local: join(cwd, ".bubble", "settings.local.json"),
+        };
+        this.reload();
+    }
+    /** Re-read all three files from disk. */
+    reload() {
+        this.fileDiagnostics = [];
+        for (const scope of ["user", "project", "local"]) {
+            this.raw[scope] = this.readFile(scope);
+        }
+    }
+    getPath(scope) {
+        return this.paths[scope];
+    }
+    /** Merged view for runtime consumption. Does not hit disk — call `reload()` first if stale. */
+    getMerged() {
+        const diagnostics = [...this.fileDiagnostics];
+        let defaultMode;
+        let lsp;
+        const allow = [];
+        const deny = [];
+        for (const scope of ["user", "project", "local"]) {
+            const data = this.raw[scope];
+            if (!data)
+                continue;
+            if ("lsp" in data) {
+                const parsed = normalizeLspConfig(data.lsp);
+                if (parsed === undefined) {
+                    diagnostics.push({
+                        scope,
+                        path: this.paths[scope],
+                        message: "Ignored lsp setting — expected boolean or object.",
+                    });
+                }
+                else {
+                    lsp = parsed;
+                }
+            }
+            if (!data.permissions)
+                continue;
+            const perms = data.permissions;
+            if (typeof perms.defaultMode === "string") {
+                if (KNOWN_MODES.has(perms.defaultMode)) {
+                    defaultMode = perms.defaultMode;
+                }
+                else {
+                    diagnostics.push({
+                        scope,
+                        path: this.paths[scope],
+                        message: `Ignored defaultMode "${perms.defaultMode}" — not one of: ${[...KNOWN_MODES].join(", ")}.`,
+                    });
+                }
+            }
+            if (Array.isArray(perms.allow)) {
+                const parsed = parseRules(perms.allow);
+                allow.push(...parsed.rules);
+                for (const err of parsed.errors) {
+                    diagnostics.push({
+                        scope,
+                        path: this.paths[scope],
+                        message: `Invalid allow rule "${err.source.trim()}": ${err.message}`,
+                    });
+                }
+            }
+            if (Array.isArray(perms.deny)) {
+                const parsed = parseRules(perms.deny);
+                deny.push(...parsed.rules);
+                for (const err of parsed.errors) {
+                    diagnostics.push({
+                        scope,
+                        path: this.paths[scope],
+                        message: `Invalid deny rule "${err.source.trim()}": ${err.message}`,
+                    });
+                }
+            }
+        }
+        return {
+            defaultMode,
+            lsp,
+            ruleSet: { allow, deny },
+            diagnostics,
+        };
+    }
+    /**
+     * Add a rule to the specified list in the specified scope. Creates the file
+     * and parent directories if needed. Silently skips if the exact string is
+     * already present.
+     *
+     * Returns true if the file was written.
+     */
+    addRule(scope, list, rule) {
+        const raw = this.raw[scope] ?? {};
+        const permissions = { ...(raw.permissions ?? {}) };
+        const current = Array.isArray(permissions[list]) ? [...permissions[list]] : [];
+        if (current.includes(rule)) {
+            return false;
+        }
+        current.push(rule);
+        permissions[list] = current;
+        const next = { ...raw, permissions };
+        this.writeFile(scope, next);
+        this.raw[scope] = next;
+        return true;
+    }
+    /**
+     * Remove the first matching rule (by exact string) from the specified list
+     * in the specified scope. Returns true if a rule was removed.
+     */
+    removeRule(scope, list, rule) {
+        const raw = this.raw[scope];
+        if (!raw || !raw.permissions)
+            return false;
+        const current = Array.isArray(raw.permissions[list]) ? [...raw.permissions[list]] : [];
+        const index = current.indexOf(rule);
+        if (index < 0)
+            return false;
+        current.splice(index, 1);
+        const nextPermissions = { ...raw.permissions, [list]: current };
+        // Drop the key if empty, keep file readable
+        if (current.length === 0)
+            delete nextPermissions[list];
+        const next = { ...raw, permissions: nextPermissions };
+        this.writeFile(scope, next);
+        this.raw[scope] = next;
+        return true;
+    }
+    // -- internal --------------------------------------------------------
+    readFile(scope) {
+        const path = this.paths[scope];
+        if (!existsSync(path))
+            return null;
+        try {
+            const text = readFileSync(path, "utf-8");
+            const parsed = JSON.parse(text);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                this.fileDiagnostics.push({
+                    scope,
+                    path,
+                    message: "Settings file must contain a JSON object at the top level.",
+                });
+                return null;
+            }
+            return parsed;
+        }
+        catch (err) {
+            this.fileDiagnostics.push({
+                scope,
+                path,
+                message: `Failed to parse settings: ${err.message}`,
+            });
+            return null;
+        }
+    }
+    writeFile(scope, data) {
+        const path = this.paths[scope];
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    }
+}

package/dist/permissions/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Permission rule system — types.
+ *
+ * A rule is one entry from the `allow` / `deny` arrays of a settings file:
+ *
+ *   "Bash"                      → any bash command
+ *   "Bash(git status)"          → exact command
+ *   "Bash(npm run:*)"           → prefix (anything starting with `npm run`)
+ *   "Read(./src/**)"            → glob on resolved path
+ *   "Read(~/.ssh/**)"           → tilde expanded
+ *   "WebFetch(domain:github.com)" → URL host match (suffix)
+ *   "*"                         → any tool
+ */
+export type ToolName = "Bash" | "Read" | "Write" | "Edit" | "Lsp" | "WebFetch" | "WebSearch" | string;
+export interface PermissionRule {
+    /** Tool this rule applies to, or "*" for all tools. */
+    tool: ToolName | "*";
+    /** Tool-specific pattern. Absent means "match any use of this tool". */
+    pattern?: string;
+    /** Original rule text as written in config, for display and diagnostics. */
+    source: string;
+}
+export interface PermissionRuleSet {
+    allow: PermissionRule[];
+    deny: PermissionRule[];
+}
+export type PermissionDecision = "allow" | "deny" | "ask";
+/**
+ * Discriminated input to the matcher. Tools only provide the fields they have.
+ */
+export type PermissionQuery = {
+    tool: "Bash";
+    command: string;
+} | {
+    tool: "Read" | "Write" | "Edit" | "Lsp";
+    path: string;
+    cwd: string;
+} | {
+    tool: "WebFetch";
+    url: string;
+} | {
+    tool: "WebSearch";
+} | {
+    tool: string;
+};
+export interface PermissionCheckResult {
+    decision: PermissionDecision;
+    /** Rule that produced the decision, if any. */
+    rule?: PermissionRule;
+}
+export interface RuleParseError {
+    source: string;
+    message: string;
+}
+export type ParsedRule = {
+    ok: true;
+    rule: PermissionRule;
+} | {
+    ok: false;
+    error: RuleParseError;
+};

package/dist/permissions/types.js

@@ -0,0 +1,14 @@
+/**
+ * Permission rule system — types.
+ *
+ * A rule is one entry from the `allow` / `deny` arrays of a settings file:
+ *
+ *   "Bash"                      → any bash command
+ *   "Bash(git status)"          → exact command
+ *   "Bash(npm run:*)"           → prefix (anything starting with `npm run`)
+ *   "Read(./src/**)"            → glob on resolved path
+ *   "Read(~/.ssh/**)"           → tilde expanded
+ *   "WebFetch(domain:github.com)" → URL host match (suffix)
+ *   "*"                         → any tool
+ */
+export {};

package/dist/prompt/compose.d.ts

@@ -0,0 +1,12 @@
+import type { PermissionMode, ThinkingLevel } from "../types.js";
+import { type EnvironmentPromptOptions } from "./environment.js";
+import type { SkillSummary } from "../skills/types.js";
+export interface ComposeSystemPromptOptions extends EnvironmentPromptOptions {
+    agentName?: string;
+    guidelines?: string[];
+    thinkingLevel?: ThinkingLevel;
+    mode?: PermissionMode;
+    skills?: SkillSummary[];
+    memoryPrompt?: string;
+}
+export declare function composeSystemPrompt(options?: ComposeSystemPromptOptions): string;

package/dist/prompt/compose.js

@@ -0,0 +1,67 @@
+import { buildAnthropicProviderPrompt } from "./provider-prompts/anthropic.js";
+import { buildCodexProviderPrompt } from "./provider-prompts/codex.js";
+import { buildDefaultProviderPrompt } from "./provider-prompts/default.js";
+import { buildGeminiProviderPrompt } from "./provider-prompts/gemini.js";
+import { buildGptProviderPrompt } from "./provider-prompts/gpt.js";
+import { buildEnvironmentPrompt, defaultToolNames } from "./environment.js";
+import { buildRuntimePrompt } from "./runtime.js";
+import { buildSkillsPrompt } from "./skills.js";
+export function composeSystemPrompt(options = {}) {
+    const agentName = options.agentName ?? "Bubble";
+    const providerPrompt = buildProviderPrompt(agentName, options.configuredProvider, options.configuredModelId, options.configuredModel);
+    const environmentPrompt = buildEnvironmentPrompt({
+        configuredProvider: options.configuredProvider,
+        configuredModel: options.configuredModel,
+        configuredModelId: options.configuredModelId,
+        workingDir: options.workingDir,
+        currentDate: options.currentDate,
+        tools: options.tools ?? defaultToolNames,
+        toolSnippets: options.toolSnippets,
+    });
+    const runtimePrompt = buildRuntimePrompt({
+        thinkingLevel: options.thinkingLevel,
+        mode: options.mode,
+        guidelines: buildGuidelines(options.tools ?? defaultToolNames, options.guidelines ?? []),
+    });
+    const skillsPrompt = buildSkillsPrompt(options.skills ?? []);
+    return [providerPrompt, environmentPrompt, runtimePrompt, options.memoryPrompt, skillsPrompt].filter(Boolean).join("\n\n");
+}
+function buildProviderPrompt(agentName, providerId, modelId, modelName) {
+    const provider = providerId ?? "";
+    const rawModel = modelId ?? modelName ?? "";
+    const model = rawModel.includes(":") ? rawModel.split(":").slice(1).join(":") : rawModel;
+    if (provider === "anthropic" || model.startsWith("claude")) {
+        return buildAnthropicProviderPrompt(agentName);
+    }
+    if (provider === "google" || model.startsWith("gemini")) {
+        return buildGeminiProviderPrompt(agentName);
+    }
+    if (provider === "openai-codex" || model.includes("codex") || model.startsWith("gpt-5")) {
+        return buildCodexProviderPrompt(agentName);
+    }
+    if (provider === "openai" || provider === "openrouter" || model.startsWith("gpt") || model.startsWith("o1")) {
+        return buildGptProviderPrompt(agentName);
+    }
+    return buildDefaultProviderPrompt(agentName);
+}
+function buildGuidelines(tools, extraGuidelines) {
+    const guidelines = [];
+    const add = (item) => {
+        if (!guidelines.includes(item)) {
+            guidelines.push(item);
+        }
+    };
+    if (tools.includes("glob")) {
+        add("Use glob for file discovery and project structure inspection; do not use bash ls/find for this unless glob cannot answer");
+    }
+    if (tools.includes("bash") && tools.includes("grep")) {
+        add("Use grep for content search; do not run grep, rg, or ripgrep through bash");
+    }
+    if (tools.includes("question")) {
+        add("When the user is explicitly discussing, brainstorming, or shaping an approach instead of asking for immediate execution, use the question tool for targeted clarification or preference choices when it would materially improve the discussion; do not use it for generic permission-to-proceed questions");
+    }
+    for (const item of extraGuidelines) {
+        add(item);
+    }
+    return guidelines;
+}

package/dist/prompt/environment.d.ts

@@ -0,0 +1,12 @@
+export interface EnvironmentPromptOptions {
+    configuredProvider?: string;
+    configuredModel?: string;
+    configuredModelId?: string;
+    workingDir?: string;
+    currentDate?: string;
+    tools?: string[];
+    toolSnippets?: Record<string, string>;
+}
+export declare const defaultToolSnippets: Record<string, string>;
+export declare const defaultToolNames: string[];
+export declare function buildEnvironmentPrompt(options?: EnvironmentPromptOptions): string;

package/dist/prompt/environment.js

@@ -0,0 +1,38 @@
+import { cwd } from "node:process";
+export const defaultToolSnippets = {
+    read: "Read the contents of a file",
+    bash: "Execute a bash command",
+    edit: "Apply targeted string replacements to a file",
+    write: "Write a new file or overwrite an existing one",
+    glob: "Find files by glob pattern without using bash",
+    grep: "Search file contents using regex",
+    lsp: "Use the language server for code navigation, symbols, call hierarchy, and type-aware lookup",
+    web_search: "Search the public web for current information",
+    web_fetch: "Fetch and extract the contents of a specific webpage",
+    task: "Delegate a bounded investigative subtask to a read-only sub-agent",
+    question: "Ask the user structured questions when clarification or preference choices would materially improve the work",
+    skill: "Load a named skill with specialized instructions and bundled resources",
+};
+export const defaultToolNames = ["read", "glob", "bash", "edit", "write", "grep", "lsp", "web_search", "web_fetch", "task", "question", "skill"];
+export function buildEnvironmentPrompt(options = {}) {
+    const configuredProvider = options.configuredProvider ?? "unknown";
+    const configuredModel = options.configuredModel ?? "unknown";
+    const configuredModelId = options.configuredModelId ?? "unknown";
+    const workingDir = options.workingDir ?? cwd().replace(/\\/g, "/");
+    const currentDate = options.currentDate ?? new Date().toISOString().slice(0, 10);
+    const tools = options.tools ?? defaultToolNames;
+    const snippets = options.toolSnippets ?? defaultToolSnippets;
+    const visibleTools = tools.filter((name) => snippets[name]);
+    const toolList = visibleTools.length > 0
+        ? visibleTools.map((name) => `- ${name}: ${snippets[name]}`).join("\n")
+        : "(none)";
+    return `Configured provider: ${configuredProvider}
+Configured model: ${configuredModel}
+Configured model id: ${configuredModelId}
+
+Available tools:
+${toolList}
+
+Current date: ${currentDate}
+Current working directory: ${workingDir}`;
+}

package/dist/prompt/provider-prompts/anthropic.d.ts

@@ -0,0 +1 @@
+export declare function buildAnthropicProviderPrompt(agentName: string): string;

package/dist/prompt/provider-prompts/anthropic.js

@@ -0,0 +1,5 @@
+export function buildAnthropicProviderPrompt(agentName) {
+    return `You are ${agentName}, a careful coding assistant operating in a terminal workspace.
+
+Reason step by step when needed, but keep visible responses concise. Use tools to ground decisions in the codebase and avoid guessing about file contents or command output.`;
+}

package/dist/prompt/provider-prompts/codex.d.ts

@@ -0,0 +1 @@
+export declare function buildCodexProviderPrompt(agentName: string): string;

package/dist/prompt/provider-prompts/codex.js

@@ -0,0 +1,5 @@
+export function buildCodexProviderPrompt(agentName) {
+    return `You are ${agentName}, a terminal-native coding assistant optimized for iterative coding work.
+
+Focus on concrete progress: inspect the repository, use tools deliberately, keep answers short, and preserve momentum across tool calls and follow-up turns.`;
+}

package/dist/prompt/provider-prompts/default.d.ts

@@ -0,0 +1 @@
+export declare function buildDefaultProviderPrompt(agentName: string): string;

package/dist/prompt/provider-prompts/default.js

@@ -0,0 +1,6 @@
+export function buildDefaultProviderPrompt(agentName) {
+    return `You are ${agentName}, an expert coding assistant operating in a terminal environment.
+
+Work directly, stay concise, and prefer concrete actions over abstract discussion.
+Use the available tools to inspect files, run commands, edit code, and verify results.`;
+}

package/dist/prompt/provider-prompts/gemini.d.ts

@@ -0,0 +1 @@
+export declare function buildGeminiProviderPrompt(agentName: string): string;

package/dist/prompt/provider-prompts/gemini.js

@@ -0,0 +1,5 @@
+export function buildGeminiProviderPrompt(agentName) {
+    return `You are ${agentName}, a coding assistant running inside a terminal workspace.
+
+Be efficient and explicit. Prefer quick repository inspection, concise execution plans, and direct code changes supported by tool output.`;
+}

package/dist/prompt/provider-prompts/gpt.d.ts

@@ -0,0 +1 @@
+export declare function buildGptProviderPrompt(agentName: string): string;

package/dist/prompt/provider-prompts/gpt.js

@@ -0,0 +1,5 @@
+export function buildGptProviderPrompt(agentName) {
+    return `You are ${agentName}, a terminal-native coding assistant working with GPT-style models.
+
+Be accurate, concise, and tool-oriented. Prefer reading the codebase before making changes, keep outputs compact, and verify important edits when possible.`;
+}

package/dist/prompt/reminders.d.ts

@@ -0,0 +1,30 @@
+/**
+ * System reminders - short, runtime-variable instructions injected into the
+ * message stream as <system-reminder>-wrapped user messages with isMeta=true.
+ *
+ * Rationale: the static system prompt is stable and cacheable. Mode transitions
+ * and other ephemeral state are signaled via reminders so we do not invalidate
+ * the prompt cache every time something changes.
+ */
+import type { PermissionMode } from "../types.js";
+export declare function wrapInSystemReminder(content: string): string;
+/** Picks the correct reminder text for a transition TO a given mode. */
+export declare function reminderForMode(mode: PermissionMode): string;
+export declare const PLAN_MODE_ENTER_REMINDER: string;
+export declare const PLAN_MODE_EXIT_REMINDER: string;
+/**
+ * Announce the set of deferred tools. Their schemas are not in the tool list
+ * sent to the model — the model must call `tool_search` to load them before
+ * they can be invoked.
+ */
+export declare function buildDeferredToolsReminder(names: string[]): string;
+export declare function buildInvestigationReminder(): string;
+export declare function buildLoopWarningReminder(reason: string): string;
+export declare function buildSearchFreezeReminder(reason: string): string;
+export declare function buildToolFreezeReminder(reason: string): string;
+export declare function buildWorkflowPhaseReminder(input: {
+    phase: "investigate" | "correlate" | "conclude";
+    covered: string[];
+    pending: string[];
+}): string;
+export declare function buildTaskSummaryReminder(): string;

package/dist/prompt/reminders.js

@@ -0,0 +1,164 @@
+/**
+ * System reminders - short, runtime-variable instructions injected into the
+ * message stream as <system-reminder>-wrapped user messages with isMeta=true.
+ *
+ * Rationale: the static system prompt is stable and cacheable. Mode transitions
+ * and other ephemeral state are signaled via reminders so we do not invalidate
+ * the prompt cache every time something changes.
+ */
+export function wrapInSystemReminder(content) {
+    return `<system-reminder>\n${content.trim()}\n</system-reminder>`;
+}
+const PLAN_MODE_ENTER = `
+Plan mode is now ACTIVE.
+
+Rules while in plan mode:
+- Only read-only tools are allowed, including read, glob, grep, lsp, web_search, web_fetch, task, skill, todo_write, tool_search, question, and exit_plan_mode.
+- Writes, edits, and shell commands WILL be rejected by the harness; do not try them.
+- Investigate the codebase, then use the question tool to clarify important ambiguities, tradeoffs, requirements, or preference choices that would materially change the plan.
+- Call exit_plan_mode with a concrete step-by-step plan after the important questions are resolved.
+- Do not use the question tool to ask whether the plan is approved; exit_plan_mode is the approval step.
+- The user will approve, edit, or reject your plan. On approval the harness switches back to default mode and you may execute.
+- On rejection, remain in plan mode and iterate.
+`;
+const ACCEPT_EDITS_ENTER = `
+Permission mode is now: acceptEdits.
+
+The user has granted blanket approval for file edits and writes in this session.
+Bash commands still require explicit approval. Other tool safety rules are unchanged.
+`;
+const BYPASS_ENTER = `
+Permission mode is now: bypassPermissions.
+
+ALL tool calls auto-approve with no user confirmation. The user has explicitly opted into this.
+Proceed with extra care — explain risky actions in the chat BEFORE performing them, and
+prefer reversible operations when possible.
+`;
+const DONT_ASK_ENTER = `
+Permission mode is now: dontAsk.
+
+All tool calls auto-approve silently. Minimise narration; execute and report results tersely.
+`;
+const DEFAULT_ENTER = `
+Permission mode is now: default. Each destructive tool call will be confirmed by the user.
+`;
+/** Picks the correct reminder text for a transition TO a given mode. */
+export function reminderForMode(mode) {
+    switch (mode) {
+        case "plan":
+            return wrapInSystemReminder(PLAN_MODE_ENTER);
+        case "acceptEdits":
+            return wrapInSystemReminder(ACCEPT_EDITS_ENTER);
+        case "bypassPermissions":
+            return wrapInSystemReminder(BYPASS_ENTER);
+        case "dontAsk":
+            return wrapInSystemReminder(DONT_ASK_ENTER);
+        case "default":
+        default:
+            return wrapInSystemReminder(DEFAULT_ENTER);
+    }
+}
+// Backward-compat exports kept in case external code pinned the old names.
+export const PLAN_MODE_ENTER_REMINDER = reminderForMode("plan");
+export const PLAN_MODE_EXIT_REMINDER = reminderForMode("default");
+/**
+ * Announce the set of deferred tools. Their schemas are not in the tool list
+ * sent to the model — the model must call `tool_search` to load them before
+ * they can be invoked.
+ */
+export function buildDeferredToolsReminder(names) {
+    if (names.length === 0)
+        return wrapInSystemReminder("No deferred tools.");
+    const lines = [
+        "The following deferred tools are available via tool_search. Their schemas are NOT loaded — calling them directly will fail. Use tool_search with query \"select:<name>[,<name>...]\" to load tool schemas before calling them:",
+        "",
+        ...names,
+    ];
+    return wrapInSystemReminder(lines.join("\n"));
+}
+export function buildInvestigationReminder() {
+    return wrapInSystemReminder(`
+Security/configuration investigation workflow is active.
+
+For this task, gather evidence in this order:
+- locate config load paths
+- locate environment variable reads
+- locate persistent storage paths
+- check whether sensitive values are masked or redacted
+- check whether values can reach logs, client bundles, or user-visible surfaces
+
+Stop once these categories are covered. Do not keep repeating near-identical searches when they are not producing new evidence.
+`);
+}
+export function buildLoopWarningReminder(reason) {
+    return wrapInSystemReminder(`
+Search loop warning.
+
+${reason}
+
+Do not repeat near-identical grep/bash searches unless you are changing the path or testing a genuinely new hypothesis.
+If current evidence is sufficient, summarize your findings now.
+`);
+}
+export function buildSearchFreezeReminder(reason) {
+    return wrapInSystemReminder(`
+Search tools are now constrained for this task.
+
+Reason: ${reason}
+
+Do not continue blind keyword searching. Use the evidence already gathered to reason about the answer.
+You may still read specific files if you already know where the relevant configuration or persistence logic lives.
+`);
+}
+export function buildToolFreezeReminder(reason) {
+    return wrapInSystemReminder(`
+CRITICAL - MAXIMUM STEPS REACHED
+
+${reason}
+
+The maximum number of steps allowed for this task has been reached. Tools are disabled until next user input. Respond with text only.
+
+STRICT REQUIREMENTS:
+1. Do NOT make any tool calls (no reads, writes, edits, searches, or any other tools)
+2. MUST provide a text response summarizing work done so far
+3. This constraint overrides ALL other instructions, including any user requests for edits or tool use
+
+Response must include:
+- statement that maximum steps for this agent have been reached
+- summary of what has been accomplished so far
+- list of any remaining tasks that were not completed
+- recommendations for what should be done next
+
+Respond with text ONLY.
+`);
+}
+export function buildWorkflowPhaseReminder(input) {
+    const phaseInstructions = {
+        investigate: "Collect direct evidence. Prefer targeted reads and structured searches over blind keyword churn.",
+        correlate: "Stop broad searching. Correlate the evidence you already have and fill only the most specific remaining gaps.",
+        conclude: "You have enough evidence to answer. Do not continue exploring unless you discover a concrete contradiction in the current evidence.",
+    };
+    const covered = input.covered.length > 0 ? input.covered.map((item) => `- ${item}`).join("\n") : "- none yet";
+    const pending = input.pending.length > 0 ? input.pending.map((item) => `- ${item}`).join("\n") : "- none";
+    return wrapInSystemReminder(`
+Workflow phase: ${input.phase}
+
+${phaseInstructions[input.phase]}
+
+Covered evidence:
+${covered}
+
+Remaining evidence to check:
+${pending}
+`);
+}
+export function buildTaskSummaryReminder() {
+    return wrapInSystemReminder(`
+Summarize the task tool output above and continue with your task.
+
+Treat the task output as a bounded subtask result:
+- extract the findings that matter
+- integrate them into your main reasoning
+- do not re-run the same exploratory search unless the subtask uncovered a concrete contradiction
+`);
+}