@bubblebrain-ai/bubble 0.0.59 → 0.0.61

package/dist/provider-ai-sdk.js

@@ -137,17 +137,23 @@ function buildCallOptions(messages, chatOptions, providerOptions) {
     };
 }
 /**
- * Gemini 3 models take a graded thinking_level; 2.5-era models take a token
+ * Gemini 3+ models take a graded thinking_level; 2.5-era models take a token
  * budget. "off" (budget 0) is only offered in the catalog for models that
  * accept it (2.5 Flash); xhigh/max/ultra clamp to high.
  */
 function buildGoogleThinkingOptions(modelId, level) {
     if (!level)
         return undefined;
+    const version = geminiVersion(modelId);
+    // Gemini 4 accepts only low/medium/high: MINIMAL is a 400 and thinkingBudget
+    // is undocumented. Side calls (titles, compaction) request "off" by default,
+    // so floor those at low rather than sending a value the API rejects.
+    if (version >= 4 && (level === "off" || level === "minimal"))
+        level = "low";
     if (level === "off")
         return { thinkingConfig: { thinkingBudget: 0 } };
     const clamped = level === "xhigh" || level === "max" || level === "ultra" ? "high" : level;
-    if (modelId.includes("gemini-3")) {
+    if (version >= 3) {
         return { thinkingConfig: { thinkingLevel: clamped, includeThoughts: true } };
     }
     const budgets = { minimal: 512, low: 2048, medium: 8192, high: 24576 };
@@ -459,10 +465,13 @@ export async function fetchGeminiModels(options) {
 }
 /**
  * Ranking: one entry per (version, tier) family — GA ids beat dated previews —
- * then newest version first, pro before flash before flash-lite, top N.
+ * then newest version first, flagship (pro/argon) before flash before
+ * flash-lite, top N.
  */
 export function selectLatestGeminiModels(entries, limit = 5) {
-    const TIER_RANK = { pro: 0, flash: 1, "flash-lite": 2 };
+    // Gemini 4 introduced named flagship tiers (gemini-4-argon). Unknown names
+    // stay excluded rather than guessing whether they are text models.
+    const TIER_RANK = { argon: 0, pro: 0, flash: 1, "flash-lite": 2 };
     const candidates = [];
     for (const entry of entries) {
         const id = (entry.name ?? "").replace(/^models\//, "");
@@ -472,21 +481,23 @@ export function selectLatestGeminiModels(entries, limit = 5) {
             continue;
         if (entry.supportedGenerationMethods && !entry.supportedGenerationMethods.includes("generateContent"))
             continue;
-        const match = /^gemini-(\d+(?:\.\d+)?)-(pro|flash)(-lite)?/.exec(id);
+        const match = /^gemini-(\d+(?:\.\d+)?)-(argon|pro|flash)(-lite)?/.exec(id);
         if (!match)
             continue;
+        const tier = `${match[2]}${match[3] ?? ""}`;
         candidates.push({
             id,
             entry,
             version: Number.parseFloat(match[1]),
-            tierRank: TIER_RANK[`${match[2]}${match[3] ?? ""}`] ?? 3,
+            tier,
+            tierRank: TIER_RANK[tier] ?? 3,
             isPreview: id.includes("preview") || id.includes("exp"),
         });
     }
     // One winner per family: GA over preview, then the shortest (least-suffixed) id.
     const families = new Map();
     for (const candidate of candidates) {
-        const key = `${candidate.version}-${candidate.tierRank}`;
+        const key = `${candidate.version}-${candidate.tier}`;
         const current = families.get(key);
         if (!current
             || (current.isPreview && !candidate.isPreview)
@@ -502,13 +513,19 @@ export function selectLatestGeminiModels(entries, limit = 5) {
         name: candidate.entry.displayName || candidate.id,
         contextWindow: Number.isFinite(candidate.entry.inputTokenLimit) ? candidate.entry.inputTokenLimit : undefined,
         reasoningLevels: geminiReasoningLevels(candidate.id),
-        ...(candidate.tierRank === 0 ? { defaultReasoningLevel: "high" } : {}),
+        // Argon defaults to Google's recommended medium via the catalog.
+        ...(candidate.tier === "pro" ? { defaultReasoningLevel: "high" } : {}),
     }));
 }
+function geminiVersion(modelId) {
+    return Number.parseFloat(/^gemini-(\d+(?:\.\d+)?)/.exec(modelId)?.[1] ?? "0");
+}
 /** Mirrors the static catalog's per-family thinking support. */
 export function geminiReasoningLevels(modelId) {
-    const version = Number.parseFloat(/^gemini-(\d+(?:\.\d+)?)/.exec(modelId)?.[1] ?? "0");
+    const version = geminiVersion(modelId);
     const isPro = modelId.includes("-pro");
+    if (version >= 4)
+        return ["low", "medium", "high"];
     // Live probes show 3.7 and 3.8 Flash share this newer ladder. Keep the
     // exception bounded to verified releases instead of guessing for 3.9+.
     if (!isPro && (version === 3.7 || version === 3.8)) {

package/dist/provider-openai-codex.d.ts

@@ -47,6 +47,8 @@ export declare function fetchOpenAICodexModels(options: {
 export interface OpenAICodexModelCatalogResult {
     descriptors: CodexModelDescriptor[];
     status: "success" | "unavailable";
+    /** Why each discovery path failed, when status is "unavailable". */
+    reason?: string;
 }
 /**
  * Fetches the account-scoped Codex catalog while preserving the distinction
@@ -58,5 +60,7 @@ export declare function fetchOpenAICodexModelCatalog(options: {
     fetch?: ChatGptFetch;
     /** Bounds both catalog GETs; a stalled warm-up must not pin the in-flight slot. */
     signal?: AbortSignal;
+    /** Per-request timeout, so a slow first path still leaves the fallback a full window. */
+    timeoutMs?: number;
 }): Promise<OpenAICodexModelCatalogResult>;
 export declare function sortCodexModelDescriptors(descriptors: CodexModelDescriptor[]): CodexModelDescriptor[];

package/dist/provider-openai-codex.js

@@ -12,8 +12,9 @@ const TOKEN_REFRESH_GRACE_MS = 5 * 60 * 1000;
 // OpenAI gates new codex models server-side by client_version (each model carries a
 // `minimal_client_version`). Track a recent real Codex CLI release; override via env
 // when OpenAI lifts the gate again before we cut a new release.
-// 2026-09-17: gpt-6-astra requires 0.153.0; 0.155.0 is the current @openai/codex release.
-const CODEX_CLIENT_VERSION = process.env.BUBBLE_CODEX_CLIENT_VERSION?.trim() || "0.155.0";
+// 2026-09-17: gpt-6-astra requires 0.153.0.
+// 2026-10-06: gpt-6.1-sol requires 0.159.0, the version the Codex app sends.
+const CODEX_CLIENT_VERSION = process.env.BUBBLE_CODEX_CLIENT_VERSION?.trim() || "0.159.0";
 /** The Codex client version Bubble claims; the account catalog the server returns depends on it. */
 export function getCodexClientVersion() {
     return CODEX_CLIENT_VERSION;
@@ -346,32 +347,50 @@ export async function fetchOpenAICodexModels(options) {
 export async function fetchOpenAICodexModelCatalog(options) {
     const accountId = extractChatGptAccountId(options.accessToken);
     if (!accountId) {
-        return { descriptors: [], status: "unavailable" };
+        return { descriptors: [], status: "unavailable", reason: "access token has no ChatGPT account id" };
     }
     const fetchImpl = options.fetch ?? chatGptFetch;
+    const failures = [];
     for (const path of MODEL_DISCOVERY_PATHS) {
+        const signal = options.timeoutMs === undefined
+            ? options.signal
+            : options.signal
+                ? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs)])
+                : AbortSignal.timeout(options.timeoutMs);
+        const startedAt = Date.now();
         const response = await fetchImpl(resolveRelativeUrl(options.baseURL, path), {
             method: "GET",
             headers: buildBaseHeaders(options.accessToken, accountId, globalThis.crypto?.randomUUID?.() ?? `bubble_${Date.now()}`, { accept: "application/json" }),
-            signal: options.signal,
-        }).catch(() => undefined);
-        if (!response?.ok)
+            signal,
+        }).catch((error) => {
+            failures.push(`${path}: ${error instanceof Error ? error.message : String(error)} after ${Date.now() - startedAt}ms`);
+            return undefined;
+        });
+        if (!response)
+            continue;
+        if (!response.ok) {
+            failures.push(`${path}: HTTP ${response.status} after ${Date.now() - startedAt}ms`);
             continue;
+        }
         const parsed = await response.json()
             .then((payload) => ({ ok: true, payload }))
             .catch(() => ({ ok: false }));
-        if (!parsed.ok)
+        if (!parsed.ok) {
+            failures.push(`${path}: invalid JSON`);
             continue;
+        }
         const payload = parsed.payload;
         if (!Array.isArray(payload) && !(payload && typeof payload === "object"
-            && (Array.isArray(payload.models) || Array.isArray(payload.data))))
+            && (Array.isArray(payload.models) || Array.isArray(payload.data)))) {
+            failures.push(`${path}: unexpected payload`);
             continue;
+        }
         return {
             descriptors: sortCodexModelDescriptors(extractCodexModelDescriptors(payload)),
             status: "success",
         };
     }
-    return { descriptors: [], status: "unavailable" };
+    return { descriptors: [], status: "unavailable", reason: failures.join("; ") };
 }
 function buildRequestBody(messages, options) {
     const instructions = messages

package/dist/provider-registry.js

@@ -74,6 +74,8 @@ const MODEL_DISCOVERY_FAILURE_TTL_MS = 10_000;
 const MODEL_DISCOVERY_DISK_TTL_MS = 24 * 60 * 60 * 1000;
 /** Discovery must never delay startup or a model picker for long. */
 const MODEL_DISCOVERY_TIMEOUT_MS = 5_000;
+// Per request: the ChatGPT backend is often reached through a user proxy.
+const OPENAI_CODEX_MODEL_DISCOVERY_TIMEOUT_MS = 15_000;
 // Included in the cache identity so a pre-single-model OpenRouter disk cache
 // can never repopulate the picker with the old full remote catalog.
 const OPENROUTER_CATALOG_SCOPE = "ox-alpha-only-v2";
@@ -821,10 +823,10 @@ export class ProviderRegistry {
                 const catalog = await fetchOpenAICodexModelCatalog({
                     baseURL: currentProvider.baseURL,
                     accessToken: currentProvider.apiKey,
-                    signal: AbortSignal.timeout(MODEL_DISCOVERY_TIMEOUT_MS),
+                    timeoutMs: OPENAI_CODEX_MODEL_DISCOVERY_TIMEOUT_MS,
                 });
                 if (catalog.status === "unavailable") {
-                    throw new Error("OpenAI Codex model catalog is unavailable.");
+                    throw new Error(`OpenAI Codex model catalog is unavailable${catalog.reason ? ` (${catalog.reason})` : ""}.`);
                 }
                 const visible = catalog.descriptors.filter((descriptor) => descriptor.visibility !== "hide");
                 return {

package/dist/sdk/index.d.ts

@@ -22,7 +22,7 @@ import type { ResolvedSubagentRoute } from "../agent/categories.js";
 import { type QuestionAnswer, type QuestionRequest } from "../question/controller.js";
 import { SkillRegistry } from "../skills/registry.js";
 import type { SkillSummary } from "../skills/types.js";
-import type { AgentEvent, AgentRunInput, ContentPart, Message, PermissionMode, Provider, ThinkingLevel } from "../types.js";
+import type { AgentEvent, AgentRunInput, ContentPart, Message, PermissionMode, Provider, ThinkingLevel, ToolRegistryEntry } from "../types.js";
 export interface BubbleSdkOptions {
     /** Optional process-local replay window. Active readers never lose unread
      * events. Older cursors fail explicitly; restore durable session history.
@@ -72,8 +72,22 @@ export interface TurnHandlers {
     onStart?: (info: TurnStartInfo) => void;
 }
 export interface RunTurnOptions extends TurnHandlers {
+    /**
+     * Turn-scoped host capabilities. Never cached globally or given to subagents;
+     * follow-up turns the SDK starts for this turn (queued input, pending steers)
+     * reuse this turn's options, these included.
+     */
+    hostTools?: ToolRegistryEntry[];
+    /**
+     * Extra skill directories for this turn, e.g. skills a host app ships with.
+     * Searched after the user's own roots, so a user skill of the same name wins.
+     * Like hostTools, follow-up turns the SDK starts for this turn reuse them.
+     */
+    skillPaths?: string[];
     /** Plain text, or content parts (text + base64 images) for attachments. */
     prompt: string | ContentPart[];
+    /** Preserve an admitted input if cancelled before initialization records it. */
+    preserveInterruptedInput?: boolean;
     /** "provider:model" or bare model id (resolved against the default provider). */
     model?: string;
     mode?: PermissionMode;
@@ -192,9 +206,14 @@ export declare class BubbleSdk {
     }): SdkSessionRef;
     openSession(sessionId: string): SdkSessionHandle;
     getHistory(sessionId: string): Message[];
+    /** Preserve an accepted desktop input cancelled before runTurn was admitted. */
+    recordInterruptedInput(sessionId: string, prompt: string | ContentPart[]): void;
+    private persistInterruptedInput;
     deleteSession(sessionId: string): Promise<void>;
     /** Interrupt the active turn. Queued turns survive unless cancelQueued is true. */
     stop(sessionId: string, options?: SdkStopOptions): number;
+    /** Stop and wait for persistence, cleanup, and terminal event publication. */
+    stopAndWait(sessionId: string, options?: SdkStopOptions): Promise<number>;
     /** Cancel queued turns without interrupting the turn that owns the session slot. */
     clearQueue(sessionId: string): number;
     getSessionRunState(sessionId: string): SdkSessionRunState;
@@ -205,7 +224,7 @@ export declare class BubbleSdk {
     steer(sessionId: string, content: string): SdkSteerResult;
     enqueueTurn(sessionId: string, options: RunTurnOptions): AsyncGenerator<AgentEvent>;
     queueTurn(sessionId: string, options: RunTurnOptions): AsyncGenerator<AgentEvent>;
-    listSkills(cwd?: string): SkillSummary[];
+    listSkills(cwd?: string, skillPaths?: string[]): SkillSummary[];
     /**
      * Ask the host once per folder (onProjectTrust) before this turn loads the
      * repository's allow rules, MCP servers and LSP servers. Trusting restarts

package/dist/sdk/index.js

@@ -118,6 +118,31 @@ export class BubbleSdk {
             return [];
         return this.resolveSession(sessionId)?.manager.getMessages() ?? [];
     }
+    /** Preserve an accepted desktop input cancelled before runTurn was admitted. */
+    recordInterruptedInput(sessionId, prompt) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.recordInterruptedInput(sessionId, prompt);
+        if (this.turnCoordinator.isDeleted(sessionId) || this.getSessionRunState(sessionId).active) {
+            throw new Error(`Cannot record interrupted input while session is active or deleted: ${sessionId}`);
+        }
+        const resolved = this.resolveSession(sessionId);
+        if (!resolved)
+            throw new Error(`Unknown session: ${sessionId}`);
+        this.persistInterruptedInput(resolved, prompt);
+    }
+    persistInterruptedInput(resolved, prompt) {
+        const session = resolved.manager;
+        session.getMessages();
+        const revision = session.getRevision();
+        session.updateMetadata({ cwd: resolved.cwd });
+        session.appendMessage({ role: "user", content: prompt }, revision);
+        session.appendMessage({
+            role: "assistant",
+            content: "[Interrupted by user before execution started.]",
+            error: { name: "MessageAbortedError", message: "Turn stopped during initialization.", aborted: true },
+        }, session.getRevision());
+    }
     async deleteSession(sessionId) {
         const owner = this.ownerForSession(sessionId);
         if (owner && owner !== this)
@@ -147,8 +172,21 @@ export class BubbleSdk {
         const current = this.turnCoordinator.getCurrent(sessionId);
         const runtime = current ? this.turnRuntimes.get(current.id) : undefined;
         runtime?.inputController.closePendingInputs();
-        const stopped = this.turnCoordinator.stopCurrent(sessionId);
-        return stopped + (options.cancelQueued ? this.turnCoordinator.clearQueue(sessionId) : 0);
+        // A reserved turn can release its slot synchronously when cancelled.
+        // Clear the queue first so cancellation cannot promote an unwanted input.
+        const queued = options.cancelQueued ? this.turnCoordinator.clearQueue(sessionId) : 0;
+        return queued + this.turnCoordinator.stopCurrent(sessionId);
+    }
+    /** Stop and wait for persistence, cleanup, and terminal event publication. */
+    async stopAndWait(sessionId, options = {}) {
+        const owner = this.ownerForSession(sessionId);
+        if (owner && owner !== this)
+            return owner.stopAndWait(sessionId, options);
+        const current = this.turnCoordinator.getCurrent(sessionId);
+        const stopping = this.runtimesForSession(sessionId).filter(runtime => options.cancelQueued || runtime.reservation.id === current?.id);
+        const stopped = this.stop(sessionId, options);
+        await Promise.all(stopping.map(runtime => runtime.finished));
+        return stopped;
     }
     /** Cancel queued turns without interrupting the turn that owns the session slot. */
     clearQueue(sessionId) {
@@ -205,10 +243,10 @@ export class BubbleSdk {
         return this.enqueueTurn(sessionId, options);
     }
     // ── Discovery (composer pickers) ─────────────────────────────────────────
-    listSkills(cwd) {
+    listSkills(cwd, skillPaths = []) {
         const registry = new SkillRegistry({
             cwd: cwd || this.defaultCwd,
-            skillPaths: this.userConfig.getSkillPaths(),
+            skillPaths: [...this.userConfig.getSkillPaths(), ...skillPaths],
             disabledSkills: this.userConfig.getDisabledSkills(),
         });
         return registry.summaries();
@@ -284,10 +322,13 @@ export class BubbleSdk {
             outcomes: new Map(),
             options,
             events: new ReplayEventLog(),
+            started: reservation.phase !== "queued",
+            inputRecorded: false,
+            finished: Promise.resolve(),
         };
         this.lastTurnOptions.set(sessionId, inheritableTurnOptions(options));
         this.turnRuntimes.set(reservation.id, runtime);
-        void this.pumpTurn(runtime, resolved);
+        runtime.finished = this.pumpTurn(runtime, resolved);
         return runtime;
     }
     async pumpTurn(runtime, resolved) {
@@ -296,7 +337,7 @@ export class BubbleSdk {
         try {
             for await (const event of this.runReservedTurn(runtime, runtime.options, resolved)) {
                 runtime.events.append(event);
-                // Publish success after the generator's finally releases its slot.
+                // Publish success after the pump's finally releases its slot.
                 // A host can then distinguish idle from an automatically queued steer.
                 if (event.type === "agent_end")
                     completedEvent = event;
@@ -306,8 +347,29 @@ export class BubbleSdk {
         }
         catch (error) {
             failure = error;
+            // Setup can fail before runReservedTurn installs its own cleanup.
+            for (const event of this.rejectOutstandingSteers(runtime, runtime.reservation.signal.aborted ? "turn_cancelled" : "turn_failed")) {
+                runtime.events.append(event);
+                this.publishSessionEvent(runtime, event);
+            }
+            // Desktop users already submitted this input. Even if setup was
+            // interrupted before Agent.run appended it, keep it for a later resume.
+            // Cancelled queued inputs never owned the turn and must stay discarded.
+            if (runtime.options.preserveInterruptedInput && runtime.started && !runtime.inputRecorded
+                && runtime.reservation.signal.aborted && !this.turnCoordinator.isDeleted(runtime.sessionId)) {
+                try {
+                    this.persistInterruptedInput(resolved, runtime.options.prompt);
+                }
+                catch (persistError) {
+                    failure = persistError;
+                }
+            }
         }
         finally {
+            runtime.inputController.closePendingInputs();
+            // Release only after the interrupted input is durable. Keep the runtime
+            // discoverable until the terminal event is published for stopAndWait.
+            runtime.reservation.finish();
             if (failure !== undefined) {
                 // The session-level log never closes per turn, so replay subscribers
                 // need an explicit terminal record — otherwise a failed turn is
@@ -337,6 +399,8 @@ export class BubbleSdk {
         const mode = options.mode ?? "default";
         const planExitMode = options.planExitMode === "bypassPermissions" ? "bypassPermissions" : "default";
         const abortSignal = reservation.signal;
+        await reservation.waitForStart();
+        runtime.started = true;
         let agentRef;
         let streamCompleted = false;
         const hookController = new ExternalHookController({ cwd, sessionId });
@@ -399,10 +463,9 @@ export class BubbleSdk {
         });
         abortSignal.addEventListener("abort", () => questionController.rejectAll(), { once: true });
         try {
-            await reservation.waitForStart();
             const skillRegistry = new SkillRegistry({
                 cwd,
-                skillPaths: this.userConfig.getSkillPaths(),
+                skillPaths: [...this.userConfig.getSkillPaths(), ...(options.skillPaths ?? [])],
                 disabledSkills: this.userConfig.getDisabledSkills(),
             });
             const tools = createAllTools(cwd, skillRegistry, {
@@ -414,6 +477,22 @@ export class BubbleSdk {
                 checkpoints: () => session.getCheckpoints(),
             });
             tools.push(...gateMcpTools(await awaitWithAbort(this.mcpToolsFor(cwd), abortSignal), approvalController));
+            const hostTools = options.hostTools ?? [];
+            const registered = new Set(tools.map(tool => tool.name));
+            for (const tool of hostTools) {
+                if (registered.has(tool.name))
+                    throw new Error(`Duplicate host tool: ${tool.name}`);
+                registered.add(tool.name);
+                const guarded = {
+                    ...tool,
+                    execute: async (args, ctx) => {
+                        throwAbortSignal(abortSignal);
+                        return tool.execute(args, { ...ctx, abortSignal });
+                    },
+                    cloneForChild: () => ({ ...tool, enabled: () => false, execute: async () => ({ content: "Host capability is not available to this child.", isError: true }) }),
+                };
+                tools.push(...(tool.readOnly ? [guarded] : gateMcpTools([guarded], approvalController)));
+            }
             throwAbortSignal(abortSignal);
             const promptCacheKey = session.getOrCreatePromptCacheKey();
             if (!this.turnCoordinator.isDeleted(sessionId)) {
@@ -429,6 +508,8 @@ export class BubbleSdk {
             const memoryPrompt = buildMemoryPrompt(cwd);
             const builtSystemPrompt = buildSystemPrompt({
                 agentName: "Bubble",
+                skills: skillRegistry.summaries(),
+                skillCatalogChars: this.userConfig.getSkillCatalogChars(),
                 configuredProvider: providerId || "none",
                 configuredModel: model ? displayModel(model) : "none",
                 configuredModelId: model || "none",
@@ -487,6 +568,7 @@ export class BubbleSdk {
                 budgetLedger: new BudgetLedger(),
                 fileStateTracker,
                 skills: skillRegistry.summaries(),
+                skillCatalogChars: this.userConfig.getSkillCatalogChars(),
                 memoryPrompt,
                 externalHooks: hookController,
                 // Cross-provider subagent routes (spawn_agent with "provider:model")
@@ -500,6 +582,8 @@ export class BubbleSdk {
                         return;
                     if (this.turnCoordinator.isDeleted(sessionId))
                         return;
+                    if (message.role === "user")
+                        runtime.inputRecorded = true;
                     persistFenced(() => {
                         session.appendMessage(message, contextRevision);
                         contextRevision = session.getRevision();
@@ -576,9 +660,6 @@ export class BubbleSdk {
             this.rejectOutstandingSteers(runtime, streamCompleted ? "no_continuation" : abortSignal.aborted ? "turn_cancelled" : "turn_failed", streamCompleted ? resolved : undefined);
             unsubscribeQuestions();
             questionController.rejectAll();
-            reservation.finish();
-            if (this.turnRuntimes.get(reservation.id) === runtime)
-                this.turnRuntimes.delete(reservation.id);
         }
     }
     // ── Internals ────────────────────────────────────────────────────────────

package/dist/session.d.ts

@@ -114,7 +114,11 @@ export declare class SessionManager {
      * Lives next to the session JSONL as `<session>.checkpoints/`.
      */
     getCheckpoints(): CheckpointStore;
-    /** Entry id of the most recent user message, or "0" before the first one. */
+    /**
+     * Entry id of the most recent user turn (as listUserTurns counts them), or
+     * "0" before the first one. Checkpoints are keyed by it, so edits made after
+     * a tool screenshot or a harness-injected block stay with the user's turn.
+     */
     lastUserEntryId(): string;
     /** User messages after the latest /clear, oldest first — the valid rewind anchors. */
     listUserTurns(): UserTurn[];

package/dist/session.js

@@ -414,13 +414,20 @@ export class SessionManager {
         }
         return this.checkpoints;
     }
-    /** Entry id of the most recent user message, or "0" before the first one. */
+    /**
+     * Entry id of the most recent user turn (as listUserTurns counts them), or
+     * "0" before the first one. Checkpoints are keyed by it, so edits made after
+     * a tool screenshot or a harness-injected block stay with the user's turn.
+     */
     lastUserEntryId() {
         const entries = this.log.list();
         for (let i = entries.length - 1; i >= 0; i--) {
             const entry = entries[i];
-            if (entry.type === "user_message")
-                return entry.id;
+            if (entry.type !== "user_message")
+                continue;
+            if (entry.message.toolObservation || isInternalBlockOnlyContent(entry.message.content))
+                continue;
+            return entry.id;
         }
         return "0";
     }
@@ -443,7 +450,8 @@ export class SessionManager {
                 continue;
             // Harness-injected turns (goal kicks, task wakes) are internal blocks —
             // not rewind anchors, and their markup must never render in the picker.
-            if (isInternalBlockOnlyContent(entry.message.content))
+            // Tool screenshots are user-role only for the provider; not turns either.
+            if (isInternalBlockOnlyContent(entry.message.content) || entry.message.toolObservation)
                 continue;
             const text = messageText(entry.message);
             turns.push({
@@ -617,7 +625,7 @@ function firstUserEntryAfterLatestClear(entries) {
         const entry = entries[i];
         // Skip harness-injected internal blocks (goal kicks, task wakes): they
         // must not become the /resume preview or the deterministic title.
-        if (entry.type === "user_message" && !isInternalBlockOnlyContent(entry.message.content)) {
+        if (entry.type === "user_message" && !isInternalBlockOnlyContent(entry.message.content) && !entry.message.toolObservation) {
             return entry;
         }
     }

package/dist/skills/format.d.ts

@@ -1,2 +1,32 @@
 import type { SkillSummary } from "./types.js";
-export declare function formatSkillsPrompt(skills: SkillSummary[]): string;
+/** Default size of the always-present skill catalog (the listed lines, not the header). */
+export declare const SKILL_CATALOG_CHARS = 12000;
+/** Each description is cut to this length; it only has to tell the model when to load. */
+export declare const SKILL_CATALOG_DESC_CHARS = 120;
+export declare const SKILL_CATALOG_HEADING = "## Skills";
+/** First line under the heading; together they mark the catalog unambiguously. */
+export declare const SKILL_CATALOG_INTRO = "Skills are task-specific instructions loaded on demand. When a task matches a skill below, call `skill` with its exact name before starting, then follow it. Load only what clearly applies.";
+export interface SkillCatalogOptions {
+    /** Budget for the listed lines; 0 turns the catalog off. */
+    budgetChars?: number;
+    /** skill_search is available, so the overflow line can point to it. */
+    searchable?: boolean;
+}
+export interface SkillCatalog {
+    /** The system-prompt section, or "" when there is nothing to list. */
+    text: string;
+    listed: number;
+    unlisted: number;
+    /** Characters used by the listed lines, against budgetChars. */
+    chars: number;
+    budgetChars: number;
+}
+/**
+ * The always-present skill catalog: name and a one-line description per skill,
+ * so the model knows what exists and loads a body with `skill` only when it
+ * applies. Ordering is deterministic (source, then name) so the system prompt
+ * stays byte-identical, and cacheable, while the skill set is unchanged.
+ */
+export declare function buildSkillCatalog(skills: SkillSummary[], options?: SkillCatalogOptions): SkillCatalog;
+/** The catalog section text (see buildSkillCatalog). */
+export declare function formatSkillsPrompt(skills: SkillSummary[], options?: SkillCatalogOptions): string;

package/dist/skills/format.js

@@ -1,47 +1,68 @@
-const MAX_SKILL_DESC_CHARS = 200;
-const SKILLS_BUDGET_CHARS = 6000;
+/** Default size of the always-present skill catalog (the listed lines, not the header). */
+export const SKILL_CATALOG_CHARS = 12_000;
+/** Each description is cut to this length; it only has to tell the model when to load. */
+export const SKILL_CATALOG_DESC_CHARS = 120;
+export const SKILL_CATALOG_HEADING = "## Skills";
+/** First line under the heading; together they mark the catalog unambiguously. */
+export const SKILL_CATALOG_INTRO = "Skills are task-specific instructions loaded on demand. When a task matches a skill below, call `skill` with its exact name before starting, then follow it. Load only what clearly applies.";
 const SOURCE_PRIORITY = {
     project: 0,
     configured: 1,
     user: 2,
 };
-export function formatSkillsPrompt(skills) {
-    if (skills.length === 0)
-        return "";
+/**
+ * The always-present skill catalog: name and a one-line description per skill,
+ * so the model knows what exists and loads a body with `skill` only when it
+ * applies. Ordering is deterministic (source, then name) so the system prompt
+ * stays byte-identical, and cacheable, while the skill set is unchanged.
+ */
+export function buildSkillCatalog(skills, options = {}) {
+    const budgetChars = Math.max(0, Math.floor(options.budgetChars ?? SKILL_CATALOG_CHARS));
+    const empty = { text: "", listed: 0, unlisted: skills.length, chars: 0, budgetChars };
+    if (skills.length === 0 || budgetChars === 0)
+        return empty;
     const sorted = [...skills].sort((a, b) => {
         const ap = SOURCE_PRIORITY[a.source ?? "user"] ?? 3;
         const bp = SOURCE_PRIORITY[b.source ?? "user"] ?? 3;
         if (ap !== bp)
             return ap - bp;
-        return a.name.localeCompare(b.name);
+        // Code-point order, not locale collation: the prompt must be byte-identical across runtimes.
+        return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
     });
-    const header = [
-        "Skills provide specialized instructions and workflows for specific tasks.",
-        "Use the skill system when a task clearly matches a skill description.",
-        "Available skills:",
-    ];
     const lines = [];
     let used = 0;
-    let dropped = 0;
     for (const skill of sorted) {
         const line = formatSkillLine(skill);
-        if (used + line.length + 1 > SKILLS_BUDGET_CHARS) {
-            dropped = sorted.length - lines.length;
+        if (used + line.length + 1 > budgetChars)
             break;
-        }
         lines.push(line);
         used += line.length + 1;
     }
-    if (dropped > 0) {
-        lines.push(`- ... and ${dropped} more skills (use /skills to list all)`);
+    if (lines.length === 0)
+        return empty;
+    const unlisted = sorted.length - lines.length;
+    if (unlisted > 0) {
+        lines.push(options.searchable
+            ? `- … and ${unlisted} more skills not listed here; use skill_search to find them.`
+            : `- … and ${unlisted} more skills not listed here.`);
     }
-    return [...header, ...lines].join("\n");
+    const text = [
+        SKILL_CATALOG_HEADING,
+        SKILL_CATALOG_INTRO,
+        ...lines,
+    ].join("\n");
+    return { text, listed: sorted.length - unlisted, unlisted, chars: used, budgetChars };
+}
+/** The catalog section text (see buildSkillCatalog). */
+export function formatSkillsPrompt(skills, options = {}) {
+    return buildSkillCatalog(skills, options).text;
 }
 function formatSkillLine(skill) {
-    const tagSuffix = skill.tags && skill.tags.length > 0 ? ` [tags: ${skill.tags.join(", ")}]` : "";
-    const rawDesc = skill.description ?? "";
-    const desc = rawDesc.length > MAX_SKILL_DESC_CHARS
-        ? rawDesc.slice(0, MAX_SKILL_DESC_CHARS - 1) + "…"
-        : rawDesc;
-    return `- ${skill.name}: ${desc}${tagSuffix}`;
+    const raw = (skill.description ?? "").replace(/\s+/g, " ").trim();
+    // Cut by code points so an emoji is never split into a lone surrogate, which some APIs reject.
+    const points = Array.from(raw);
+    const desc = points.length > SKILL_CATALOG_DESC_CHARS
+        ? points.slice(0, SKILL_CATALOG_DESC_CHARS - 1).join("").trimEnd() + "…"
+        : raw;
+    return desc ? `- ${skill.name}: ${desc}` : `- ${skill.name}`;
 }

package/dist/slash-commands/commands.d.ts

@@ -1,4 +1,7 @@
+import type { SlashCommand } from "./types.js";
 import type { UnifiedCommand } from "./unified.js";
+/** Rebuild the system prompt from the agent's live options (model, tools, memory, Skills catalog). */
+export declare function syncSystemPrompt(ctx: Pick<Parameters<SlashCommand["handler"]>[1], "agent" | "cwd">, model: string): void;
 /**
  * Public export — built-in commands tagged with `source: "builtin"` so the
  * registry and TUI can group them uniformly alongside MCP-derived commands.