@bubblebrain-ai/bubble 0.0.58 → 0.0.60

package/dist/approval/controller.js

@@ -1,16 +1,20 @@
 import { checkPermission } from "../permissions/rule.js";
 import { truncateHookText } from "../hooks/index.js";
+import { bashSessionGrant } from "./session-cache.js";
+import { isProtectedWorkspacePath } from "./protected-paths.js";
 /**
  * Default ApprovalController. Decision tree:
  *
  *   deny rule match              → reject (applies even under bypassPermissions)
  *   bypassPermissions            → auto-approve, no prompt
  *   default + edit|write         → auto-approve (workspace paths only; a
- *                                  path outside the workspace falls through
- *                                  to allow rules / the interactive prompt)
+ *                                  path outside the workspace, or a protected
+ *                                  one — .git, agent permission settings —
+ *                                  falls through to the interactive prompt)
  *   plan                         → reject with instructions to use exit_plan_mode
- *   allow rule match             → auto-approve
- *   bash in session allowlist    → auto-approve
+ *   allow rule match             → auto-approve (never for protected paths)
+ *   session grant (bash prefix,
+ *     MCP tool)                  → auto-approve
  *   bash / other                 → delegate to UI; if no UI, reject
  *
  * Deny rules sit at the top as a hard ceiling: bypassPermissions is a trust
@@ -28,7 +32,8 @@ export class PermissionAwareApprovalController {
             return { decision: "ask" };
         return checkPermission(ruleSet, query);
     }
-    async request(req) {
+    async request(original) {
+        const req = this.annotate(original);
         const ruleResult = this.checkRequestRules(req);
         const finalize = async (decision) => {
             await this.runPermissionResultHook(req, decision);
@@ -49,7 +54,9 @@ export class PermissionAwareApprovalController {
             return finalize({ action: "approve" });
         }
         const outsideWorkspace = (req.type === "edit" || req.type === "write") && req.outsideWorkspace === true;
-        if (mode === "default" && !outsideWorkspace && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
+        const protectedPath = (req.type === "edit" || req.type === "write" || req.type === "patch") && req.protectedPath === true;
+        if (mode === "default" && !outsideWorkspace && !protectedPath
+            && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
             return finalize({ action: "approve" });
         }
         // Project profile trust is a user decision, not a destructive action:
@@ -60,13 +67,19 @@ export class PermissionAwareApprovalController {
                 feedback: "Plan mode is active. Do not call destructive tools directly — propose your changes via exit_plan_mode and wait for user approval.",
             });
         }
-        if (ruleResult.decision === "allow") {
+        // A broad allow rule (`Edit`, `Write(**)`) must not silently cover a
+        // protected path; the user confirms those one at a time.
+        if (ruleResult.decision === "allow" && !protectedPath) {
             return finalize({ action: "approve" });
         }
         // Session-scoped allowlist: previously-approved bash prefixes skip the prompt.
         if (req.type === "bash" && this.options.bashAllowlist?.matches(req.command)) {
             return finalize({ action: "approve" });
         }
+        const grantKey = sessionGrantKey(req);
+        if (grantKey && this.options.sessionGrants?.has(grantKey)) {
+            return finalize({ action: "approve" });
+        }
         const handler = this.options.handlerRef.current;
         if (!handler) {
             return finalize({
@@ -74,7 +87,48 @@ export class PermissionAwareApprovalController {
                 feedback: "No interactive UI is available to approve this tool call.",
             });
         }
-        return finalize(await handler(req));
+        const decision = await handler(req);
+        if (decision.action === "approve" && decision.remember === "session") {
+            this.rememberForSession(req);
+        }
+        return finalize(decision);
+    }
+    /**
+     * Facts the host needs to render the prompt correctly: whether a path is
+     * protected (never auto-approve it host-side either) and what scope a
+     * "this session" approval would cover.
+     */
+    annotate(req) {
+        const cwd = this.options.cwd;
+        switch (req.type) {
+            case "edit":
+            case "write":
+                return isProtectedWorkspacePath(cwd, req.path) ? { ...req, protectedPath: true } : req;
+            case "patch": {
+                const paths = [...req.paths, ...req.files.map((file) => file.path)];
+                return paths.some((path) => isProtectedWorkspacePath(cwd, path)) ? { ...req, protectedPath: true } : req;
+            }
+            case "bash": {
+                const grant = this.options.bashAllowlist ? bashSessionGrant(req.command) : undefined;
+                return grant ? { ...req, sessionGrant: grant } : req;
+            }
+            case "external_tool":
+                return req.kind === "mcp" && this.options.sessionGrants && req.title.trim()
+                    ? { ...req, sessionGrant: req.title.trim() }
+                    : req;
+            default:
+                return req;
+        }
+    }
+    rememberForSession(req) {
+        if (req.type === "bash") {
+            if (req.sessionGrant)
+                this.options.bashAllowlist?.add(req.sessionGrant);
+            return;
+        }
+        const key = sessionGrantKey(req);
+        if (key)
+            this.options.sessionGrants?.add(key);
     }
     requestToQuery(req) {
         switch (req.type) {
@@ -219,6 +273,11 @@ function summarizeApprovalRequest(req) {
             };
     }
 }
+function sessionGrantKey(req) {
+    if (req.type === "external_tool" && req.sessionGrant)
+        return `${req.kind}:${req.sessionGrant}`;
+    return undefined;
+}
 function externalCommand(rawInput) {
     if (typeof rawInput !== "object" || rawInput === null || Array.isArray(rawInput))
         return undefined;

package/dist/approval/protected-paths.d.ts

@@ -0,0 +1 @@
+export declare function isProtectedWorkspacePath(cwd: string, filePath: string): boolean;

package/dist/approval/protected-paths.js

@@ -0,0 +1,35 @@
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { resolveThroughLinks } from "../tools/path-utils.js";
+/**
+ * Workspace files whose content grants capabilities beyond the edit itself.
+ * Default mode auto-approves ordinary workspace edits; these always ask,
+ * because writing them is a privilege escalation rather than a code change:
+ *
+ * - anything inside a `.git` directory — hooks and `core.hooksPath` /
+ *   `core.fsmonitor` in `.git/config` run arbitrary commands the next time
+ *   anyone runs git;
+ * - agent permission settings (`.bubble/settings*.json`, and Claude Code's
+ *   `.claude/settings*.json`) — an allow rule written there approves every
+ *   later command without a prompt.
+ */
+const PROTECTED_SETTINGS = [
+    { dir: ".bubble", files: new Set(["settings.json", "settings.local.json"]) },
+    { dir: ".claude", files: new Set(["settings.json", "settings.local.json"]) },
+];
+export function isProtectedWorkspacePath(cwd, filePath) {
+    const absolute = isAbsolute(filePath) ? resolve(filePath) : resolve(cwd, filePath);
+    // Also where the path really leads: `docs/hooks -> ../.git/hooks` must not
+    // turn a hook into an ordinary auto-approved edit.
+    return isProtected(cwd, absolute) || isProtected(resolveThroughLinks(cwd), resolveThroughLinks(absolute));
+}
+function isProtected(cwd, absolute) {
+    // Case-folded: on the default macOS (and Windows) filesystem `.GIT/config`
+    // is `.git/config`. On case-sensitive systems this only asks more often.
+    const rel = relative(resolve(cwd), absolute).toLowerCase();
+    const parts = rel.split(sep).filter(Boolean);
+    if (parts.includes(".git"))
+        return true;
+    const parent = basename(dirname(absolute)).toLowerCase();
+    const name = basename(absolute).toLowerCase();
+    return PROTECTED_SETTINGS.some((entry) => entry.dir === parent && entry.files.has(name));
+}

package/dist/approval/session-cache.d.ts

@@ -1,35 +1,21 @@
 /**
- * Session-scoped allowlist of bash command prefixes. Not persisted to disk.
+ * Session-scoped set of bash commands the user approved "for this session".
+ * Not persisted to disk.
  *
- * Matching rule: a command is allowed if it starts with one of the stored
- * prefixes and the next character is either end-of-string or whitespace.
- * This means the prefix "git status" will match "git status" and
- * "git status -s", but NOT "git statuss" or "git statusbad".
- *
- * For ergonomic parity with Claude Code we also strip a trailing ":*" when
- * storing so that users may type "npm run:*" as a pattern — functionally
- * equivalent to just "npm run" under our simple prefix rule.
+ * Exact match only (after trimming), like Kimi Code's session approvals: a
+ * remembered command never vouches for a different one, so no shell parsing
+ * is involved and a compound line cannot smuggle an extra command past it.
+ * Broader, prefix-style grants belong in allow rules (`Bash(npm test:*)`),
+ * which are matched per simple command.
  */
 export declare class BashAllowlist {
-    private prefixes;
-    add(prefix: string): void;
-    remove(prefix: string): boolean;
+    private commands;
+    add(command: string): void;
+    remove(command: string): boolean;
     clear(): void;
     matches(command: string): boolean;
     list(): string[];
     size(): number;
 }
-/**
- * Infers a reasonable "don't ask again" prefix from a bash command. Uses the
- * first two whitespace-separated tokens when the second token looks like a
- * subcommand (no leading `-` or `/`), otherwise falls back to the first token.
- * Examples:
- *   "git status -s"     → "git status"
- *   "git status"        → "git status"
- *   "git"               → "git"
- *   "npm run test"      → "npm run"
- *   "npm test"          → "npm test"
- *   "rm -rf /tmp/x"     → "rm"
- *   "./scripts/foo.sh"  → "./scripts/foo.sh"
- */
-export declare function inferBashPrefix(command: string): string;
+/** What a "this session" approval of `command` remembers: the command itself. */
+export declare function bashSessionGrant(command: string): string | undefined;

package/dist/approval/session-cache.js

@@ -1,68 +1,38 @@
 /**
- * Session-scoped allowlist of bash command prefixes. Not persisted to disk.
+ * Session-scoped set of bash commands the user approved "for this session".
+ * Not persisted to disk.
  *
- * Matching rule: a command is allowed if it starts with one of the stored
- * prefixes and the next character is either end-of-string or whitespace.
- * This means the prefix "git status" will match "git status" and
- * "git status -s", but NOT "git statuss" or "git statusbad".
- *
- * For ergonomic parity with Claude Code we also strip a trailing ":*" when
- * storing so that users may type "npm run:*" as a pattern — functionally
- * equivalent to just "npm run" under our simple prefix rule.
+ * Exact match only (after trimming), like Kimi Code's session approvals: a
+ * remembered command never vouches for a different one, so no shell parsing
+ * is involved and a compound line cannot smuggle an extra command past it.
+ * Broader, prefix-style grants belong in allow rules (`Bash(npm test:*)`),
+ * which are matched per simple command.
  */
 export class BashAllowlist {
-    prefixes = new Set();
-    add(prefix) {
-        const cleaned = prefix.trim().replace(/:\*$/, "").trim();
+    commands = new Set();
+    add(command) {
+        const cleaned = command.trim();
         if (!cleaned)
             return;
-        this.prefixes.add(cleaned);
+        this.commands.add(cleaned);
     }
-    remove(prefix) {
-        return this.prefixes.delete(prefix.trim());
+    remove(command) {
+        return this.commands.delete(command.trim());
     }
     clear() {
-        this.prefixes.clear();
+        this.commands.clear();
     }
     matches(command) {
-        const trimmed = command.trim();
-        for (const prefix of this.prefixes) {
-            if (trimmed === prefix)
-                return true;
-            if (trimmed.startsWith(prefix) && /\s/.test(trimmed.charAt(prefix.length))) {
-                return true;
-            }
-        }
-        return false;
+        return this.commands.has(command.trim());
     }
     list() {
-        return [...this.prefixes].sort();
+        return [...this.commands].sort();
     }
     size() {
-        return this.prefixes.size;
+        return this.commands.size;
     }
 }
-/**
- * Infers a reasonable "don't ask again" prefix from a bash command. Uses the
- * first two whitespace-separated tokens when the second token looks like a
- * subcommand (no leading `-` or `/`), otherwise falls back to the first token.
- * Examples:
- *   "git status -s"     → "git status"
- *   "git status"        → "git status"
- *   "git"               → "git"
- *   "npm run test"      → "npm run"
- *   "npm test"          → "npm test"
- *   "rm -rf /tmp/x"     → "rm"
- *   "./scripts/foo.sh"  → "./scripts/foo.sh"
- */
-export function inferBashPrefix(command) {
-    const tokens = command.trim().split(/\s+/);
-    if (tokens.length === 0 || !tokens[0])
-        return "";
-    const first = tokens[0];
-    const second = tokens[1];
-    if (second && /^[A-Za-z_]/.test(second)) {
-        return `${first} ${second}`;
-    }
-    return first;
+/** What a "this session" approval of `command` remembers: the command itself. */
+export function bashSessionGrant(command) {
+    return command.trim() || undefined;
 }

package/dist/approval/types.d.ts

@@ -18,6 +18,12 @@ export interface EditApprovalRequest {
      * (bypassPermissions still auto-approves, consistent with bash).
      */
     outsideWorkspace?: boolean;
+    /**
+     * Set by the approval controller: the path is a workspace file that can
+     * grant further capabilities (permission settings, git hooks/config), so
+     * it is never auto-approved in default mode. Hosts must not auto-approve it.
+     */
+    protectedPath?: boolean;
 }
 export interface WriteApprovalRequest {
     type: "write";
@@ -29,6 +35,8 @@ export interface WriteApprovalRequest {
     fileExists: boolean;
     /** See EditApprovalRequest.outsideWorkspace. */
     outsideWorkspace?: boolean;
+    /** See EditApprovalRequest.protectedPath. */
+    protectedPath?: boolean;
 }
 export interface PatchApprovalRequest {
     type: "patch";
@@ -42,6 +50,8 @@ export interface PatchApprovalRequest {
     }>;
     /** Combined unified diff for all file changes. */
     diff: string;
+    /** See EditApprovalRequest.protectedPath. */
+    protectedPath?: boolean;
 }
 export interface BashApprovalRequest {
     type: "bash";
@@ -54,6 +64,12 @@ export interface BashApprovalRequest {
      * session allowlist, and bypass approve it like foreground by design.
      */
     background?: boolean;
+    /**
+     * Set by the approval controller when this request may be approved for the
+     * rest of the session: the exact scope the grant would cover (a bash
+     * command prefix, an MCP tool name). Absent = hosts offer only "once".
+     */
+    sessionGrant?: string;
 }
 export interface LspApprovalRequest {
     type: "lsp";
@@ -77,7 +93,9 @@ export interface AgentProfileApprovalRequest {
     promptPreview: string;
 }
 /**
- * Permission gate for a tool exposed by an external ACP runtime.
+ * Permission gate for a tool Bubble does not implement itself: a tool
+ * exposed by an external ACP runtime (kind = ACP tool category) or an MCP
+ * server tool (kind = "mcp", title = the namespaced mcp__server__tool name).
  *
  * Keep this structural rather than importing ACP SDK types so the approval
  * layer remains provider-agnostic. External runtimes are responsible for
@@ -95,11 +113,19 @@ export interface ExternalToolApprovalRequest {
         path: string;
         line?: number | null;
     }>;
+    /** See BashApprovalRequest.sessionGrant. */
+    sessionGrant?: string;
 }
 export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest | ExternalToolApprovalRequest;
 export type ApprovalDecision = {
     action: "approve";
     feedback?: string;
+    /**
+     * "session": also approve future requests covered by the request's
+     * `sessionGrant` for the rest of the session. Ignored when the request
+     * carried no sessionGrant.
+     */
+    remember?: "session";
 } | {
     action: "reject";
     feedback?: string;

package/dist/cli.d.ts

@@ -30,3 +30,8 @@ export interface CliArgs {
 }
 export declare function parseArgs(argv: string[]): CliArgs;
 export declare function printHelp(): void;
+/**
+ * Make `cwd` the process working directory, so --cwd behaves exactly like
+ * launching Bubble there. Returns an error message instead of throwing.
+ */
+export declare function enterWorkingDirectory(cwd: string): string | undefined;

package/dist/cli.js

@@ -1,6 +1,8 @@
 /**
  * CLI argument parsing.
  */
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
 import { THINKING_LEVELS } from "./types.js";
 import { isThinkingLevel } from "./variant/thinking-level.js";
 export function parseArgs(argv) {
@@ -27,9 +29,13 @@ export function parseArgs(argv) {
             case "-m":
                 args.model = argv[++i];
                 break;
-            case "--cwd":
-                args.cwd = argv[++i];
+            case "--cwd": {
+                // Absolute, so it survives the chdir in main() and matches session metadata.
+                const dir = argv[++i];
+                if (dir)
+                    args.cwd = resolve(dir);
                 break;
+            }
             case "--api-key":
             case "-k":
                 args.apiKey = argv[++i];
@@ -150,3 +156,20 @@ Options (serve --feishu):
   --dry-run                Connect once, then exit (smoke test)
 `);
 }
+/**
+ * Make `cwd` the process working directory, so --cwd behaves exactly like
+ * launching Bubble there. Returns an error message instead of throwing.
+ */
+export function enterWorkingDirectory(cwd) {
+    if (cwd === process.cwd())
+        return undefined;
+    try {
+        if (!statSync(cwd).isDirectory())
+            return `--cwd ${cwd} is not a directory.`;
+        process.chdir(cwd);
+        return undefined;
+    }
+    catch {
+        return `--cwd ${cwd} does not exist or cannot be opened.`;
+    }
+}

package/dist/config.d.ts

@@ -20,6 +20,7 @@ export interface UserConfigData {
     /** Skill names disabled from invocation/search until re-enabled in /skills. */
     skills?: {
         disabled?: string[];
+        catalogChars?: number;
     };
     /**
      * Three shapes are accepted on disk so we can evolve without breaking
@@ -76,6 +77,8 @@ export declare class UserConfig {
     setDefaultProvider(id: string): void;
     getSkillPaths(): string[];
     setSkillPaths(paths: string[]): void;
+    /** Skill catalog budget in characters; undefined uses the default, 0 turns the catalog off. */
+    getSkillCatalogChars(): number | undefined;
     getDisabledSkills(): string[];
     setDisabledSkills(names: string[]): void;
     getTheme(): ThemeConfig;

package/dist/config.js

@@ -202,6 +202,13 @@ export class UserConfig {
         this.data.skillPaths = paths.slice();
         this.save();
     }
+    /** Skill catalog budget in characters; undefined uses the default, 0 turns the catalog off. */
+    getSkillCatalogChars() {
+        const value = this.data.skills?.catalogChars;
+        return typeof value === "number" && Number.isFinite(value) && value >= 0
+            ? Math.min(Math.floor(value), 200_000)
+            : undefined;
+    }
     getDisabledSkills() {
         const disabled = this.data.skills?.disabled;
         if (!Array.isArray(disabled))

package/dist/context/checkpoint.d.ts

@@ -0,0 +1,18 @@
+import type { Message } from "../types.js";
+/** A versioned, exact conversational projection. Never includes the host system prompt. */
+export interface ContextCheckpoint {
+    version: 1;
+    compactionId: string;
+    reason: "auto" | "manual" | "overflow" | "resident";
+    baseRevision?: string;
+    summary?: string;
+    messages: Message[];
+}
+export declare function createContextCheckpoint(messages: Message[], reason: ContextCheckpoint["reason"], summary?: string, baseRevision?: string): ContextCheckpoint;
+/** Live meta reminders may interleave results, but every canonical call needs a real result. */
+export declare function hasCompleteToolGroups(messages: Message[]): boolean;
+export declare function checkpointMessages(checkpoint: ContextCheckpoint): Message[];
+/** Replay-side read: a checkpoint this build cannot validate (a newer format,
+ * a hand-edited record) is not a boundary. Originals are retained, so callers
+ * fall back to an earlier boundary instead of failing the whole session. */
+export declare function tryCheckpointMessages(checkpoint: ContextCheckpoint): Message[] | undefined;

package/dist/context/checkpoint.js

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { isClaudeWithBoundThinking } from "../anthropic-thinking.js";
+import { isInternalBlockOnlyContent, sanitizeInternalReminderBlocks, sanitizeInternalReasoningText, sanitizeAssistantProviderMetadata } from "../agent/internal-reminder-sanitizer.js";
+import { isCompactionSummaryMessage, splitLeadingContext } from "./compact.js";
+export function createContextCheckpoint(messages, reason, summary, baseRevision) {
+    const { body } = splitLeadingContext(messages);
+    // Runtime reminders must be recomputed by the host. Compaction summaries are
+    // first-class context, not ephemeral reminders, and must survive verbatim.
+    const durable = body.filter(message => {
+        if (isCompactionSummaryMessage(message))
+            return true;
+        if (message.role === "meta")
+            return false;
+        // Backstop for older histories containing provider-projected reminders.
+        // Never remove user prose merely because it mentions or quotes a block.
+        return !(message.role === "user" && typeof message.content === "string"
+            && isInternalBlockOnlyContent(message.content)
+            && !sanitizeInternalReminderBlocks(message.content).trim());
+    });
+    const sanitized = durable.map(sanitizeCheckpointMessage);
+    return { version: 1, compactionId: randomUUID(), reason, baseRevision,
+        summary: summary === undefined ? undefined : sanitizeInternalReminderBlocks(summary),
+        messages: structuredClone(sanitized) };
+}
+/** Live meta reminders may interleave results, but every canonical call needs a real result. */
+export function hasCompleteToolGroups(messages) {
+    const pending = new Set();
+    for (const message of messages) {
+        if (message.role === "meta")
+            continue;
+        if (message.role === "tool") {
+            if (!pending.delete(message.toolCallId))
+                return false;
+        }
+        else {
+            if (pending.size)
+                return false;
+            if (message.role === "assistant") {
+                for (const call of message.toolCalls ?? []) {
+                    // Ids only need to be unambiguous within their own group: providers
+                    // may scope them per response (`call_1` in every reply).
+                    if (!call.id || pending.has(call.id))
+                        return false;
+                    pending.add(call.id);
+                }
+            }
+        }
+    }
+    return pending.size === 0;
+}
+export function checkpointMessages(checkpoint) {
+    if (checkpoint?.version !== 1 || typeof checkpoint.compactionId !== "string" || !checkpoint.compactionId
+        || !Array.isArray(checkpoint.messages))
+        throw new Error("Unsupported context checkpoint");
+    const pending = new Set();
+    for (const message of checkpoint.messages) {
+        if (!message || !["user", "assistant", "tool", "system", "meta"].includes(message.role)
+            || !(typeof message.content === "string" || (message.role === "user" && Array.isArray(message.content)))) {
+            throw new Error("Invalid context checkpoint message");
+        }
+        if (message.role === "assistant") {
+            if (pending.size)
+                throw new Error("Incomplete checkpoint tool group");
+            for (const call of message.toolCalls ?? []) {
+                if (!call.id || pending.has(call.id))
+                    throw new Error("Invalid checkpoint tool call id");
+                pending.add(call.id);
+            }
+        }
+        else if (message.role === "tool") {
+            if (!pending.delete(message.toolCallId))
+                throw new Error("Orphan checkpoint tool result");
+        }
+        else if (pending.size)
+            throw new Error("Interrupted checkpoint tool group");
+    }
+    if (pending.size)
+        throw new Error("Incomplete checkpoint tool group");
+    // Also repairs checkpoints written by builds that retained now-invalid
+    // signatures. Messages appended AFTER this boundary are replayed normally.
+    return structuredClone(checkpoint.messages.map(sanitizeCheckpointMessage));
+}
+function sanitizeCheckpointMessage(message) {
+    if (message.role !== "assistant")
+        return message;
+    let metadata = message.providerMetadata;
+    const blocks = metadata?.anthropic?.contentBlocks;
+    if (blocks && isClaudeWithBoundThinking(message.modelId ?? message.model)) {
+        // A checkpoint rewrites the prefix. Remove the entire bound thinking run,
+        // including encrypted blocks, so the model can reason from the new context.
+        // Keep text, tool calls/results, and display reasoning; never mutate originals.
+        metadata = {
+            ...metadata,
+            anthropic: {
+                ...metadata?.anthropic,
+                contentBlocks: blocks.filter(block => block.type !== "thinking" && block.type !== "redacted_thinking"),
+            },
+        };
+    }
+    return {
+        ...message,
+        content: sanitizeInternalReminderBlocks(message.content),
+        ...(message.reasoning !== undefined ? { reasoning: sanitizeInternalReasoningText(message.reasoning) } : {}),
+        ...(metadata ? { providerMetadata: sanitizeAssistantProviderMetadata(metadata) } : {}),
+    };
+}
+/** Replay-side read: a checkpoint this build cannot validate (a newer format,
+ * a hand-edited record) is not a boundary. Originals are retained, so callers
+ * fall back to an earlier boundary instead of failing the whole session. */
+export function tryCheckpointMessages(checkpoint) {
+    try {
+        return checkpointMessages(checkpoint);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/context/compact-llm.js

@@ -132,6 +132,13 @@ async function generateSummary(oldMessages, options) {
 export function serializeTranscript(messages) {
     const lines = [];
     for (const message of messages) {
+        // Manual /compact receives raw history, unlike the automatic path which
+        // first folds summary carriers into user messages. Keep those summaries,
+        // but do not turn ordinary system/meta reminders into durable history.
+        if (isCompactionSummaryMessage(message)) {
+            lines.push(`[Prior compaction summary] ${messageText(message)}`);
+            continue;
+        }
         switch (message.role) {
             case "user":
                 lines.push(`[user] ${contentToText(message.content)}`);

package/dist/context/compact.d.ts

@@ -50,6 +50,14 @@ export interface CompactResult {
     summary?: string;
     entries?: SessionLogEntry[];
     messages?: Message[];
+    /** Original messages the new summary replaces (prior summary carriers
+     * plus the evicted body) — the exact set an external summarizer should
+     * condense. Kept-verbatim messages are excluded so they are not duplicated
+     * into the summary. */
+    evictedMessages?: Message[];
+    /** Index in `messages` of the one summary that stands for `evictedMessages`.
+     * Other summaries in `messages` cover different history and must survive. */
+    summaryIndex?: number;
     droppedEntries?: number;
 }
 /**