@kenkaiiii/ggcoder 4.11.2 → 4.12.1

package/dist/core/agent-session.d.ts

@@ -3,6 +3,16 @@ import { EventBus } from "./event-bus.js";
 import { SlashCommandRegistry } from "./slash-commands.js";
 import { type BranchInfo } from "./session-manager.js";
 import type { BackgroundProcess } from "./process-manager.js";
+/** A chat attachment (image / video / other file) prepared for the model. The
+ *  raw base64 `data` rides native blocks; `path` (when persisted to disk) lets
+ *  the agent's tools open the file directly. */
+export interface SessionAttachment {
+    kind: "image" | "video" | "file";
+    mediaType: string;
+    data: string;
+    name: string;
+    path?: string;
+}
 export interface AgentSessionOptions {
     provider: Provider;
     model: string;
@@ -31,6 +41,16 @@ export interface AgentSessionOptions {
      * resumable identity.
      */
     transient?: boolean;
+    /**
+     * If true, `initialize()` returns WITHOUT waiting for MCP servers to connect —
+     * the connection runs in the background and tools are appended when ready.
+     * Hosts whose readiness is gated on `initialize()` (the gg-app sidecar, which
+     * can't emit its listening handshake until init resolves) set this so a slow
+     * or hanging stdio MCP server (e.g. a first-run `npx -y …` download) can't
+     * delay the session from becoming usable. Default (false) keeps the CLI's
+     * connect-before-ready behavior so MCP tools are present on the first turn.
+     */
+    backgroundMcpConnect?: boolean;
     /**
      * Plan-mode callbacks. When provided, the `enter_plan`/`exit_plan` tools are
      * registered and the session manages plan-mode restrictions + system-prompt
@@ -58,6 +78,10 @@ export declare class AgentSession {
     private extensionLoader;
     private messages;
     private tools;
+    /** Rebuilds the read tool for a new model (video byte cap is baked in at
+     *  creation). Called from switchModel so video-capable models get the
+     *  read-tool's native-video path after a mid-session model change. */
+    private rebuildReadTool;
     private skills;
     private cacheKeyLogged;
     private hookStats;
@@ -73,6 +97,9 @@ export declare class AgentSession {
     private regroundingInjected;
     private compactionOccurred;
     private originalRequest;
+    /** True after the cache has been pre-warmed for this session. Ensures we only
+     *  fire the warm-up call once (before the first real turn). */
+    private cachePrewarmed;
     private userQueue;
     private processManager?;
     private lspManager?;
@@ -97,7 +124,26 @@ export declare class AgentSession {
     private currentLeafId;
     private opts;
     constructor(options: AgentSessionOptions);
+    /**
+     * Derive the output-token cap for a model. Follows the active model's
+     * `maxOutputTokens` so a session booted on a large-output model (e.g. Kimi's
+     * 256K) doesn't carry that cap to a smaller one (e.g. Opus's 128K) after a
+     * model switch — that mismatch surfaces from the provider as
+     * `max_tokens: 262144 > 128000, which is the maximum allowed …`. An explicit
+     * `maxTokens` override is honored but clamped to the model's ceiling.
+     */
+    private resolveMaxTokens;
     initialize(): Promise<void>;
+    /**
+     * Connect all configured MCP servers and append their tools to `this.tools`.
+     * Resolves the GLM api key first (Z.AI's bundled servers need it). Never
+     * throws — a failed connect is logged and skipped — so it is safe to either
+     * `await` (CLI: tools ready before the first turn) or fire-and-forget
+     * (sidecar: `backgroundMcpConnect`, so a slow stdio server can't stall
+     * startup). Tools are pushed onto the live array the agent loop reads each
+     * turn, so background-connected servers become available on the next prompt.
+     */
+    private connectMcpServers;
     /**
      * Process user input. Handles slash commands or runs agent loop.
      */
@@ -109,13 +155,13 @@ export declare class AgentSession {
      * agent can open them with its tools. Slash-command parsing is skipped —
      * attachments are always a direct conversational turn.
      */
-    promptWithAttachments(text: string, attachments: Array<{
-        kind: "image" | "video" | "file";
-        mediaType: string;
-        data: string;
-        name: string;
-        path?: string;
-    }>): Promise<void>;
+    promptWithAttachments(text: string, attachments: SessionAttachment[]): Promise<void>;
+    /**
+     * Build the native content blocks (text + image/video notes + file notes) for
+     * a user message with attachments. Shared by {@link promptWithAttachments} and
+     * the mid-run steering drain so queued media is delivered identically.
+     */
+    private buildAttachmentParts;
     /**
      * Reset per-run self-correction hook state. Mirrors the TUI's run_start
      * resets so each run evaluates the hooks from a clean slate. `originalRequest`
@@ -168,12 +214,14 @@ export declare class AgentSession {
     listBranches(): Promise<BranchInfo[]>;
     getState(): AgentSessionState;
     getPlanMode(): boolean;
-    /** Queue a user message to be injected mid-run as steering. Returns the new
-     *  queue length. No-op semantics are the caller's concern. */
-    queueMessage(text: string): number;
+    /** Queue a user message (optionally with attachments) to be injected mid-run
+     *  as steering. Returns the new queue length. No-op semantics are the caller's
+     *  concern. */
+    queueMessage(text: string, attachments?: SessionAttachment[]): number;
     /** Number of messages currently queued. */
     getQueuedCount(): number;
-    /** Clear the queue, returning the combined text (to restore to the composer). */
+    /** Clear the queue, returning the combined text (to restore to the composer).
+     *  Queued attachments are dropped on cancel — the composer only restores text. */
     drainQueue(): string;
     /** Snapshot of background processes (bash run_in_background), newest-state. */
     listBackgroundProcesses(): BackgroundProcess[];
@@ -209,6 +257,13 @@ export declare class AgentSession {
     setThinkingLevel(level: ThinkingLevel | undefined): void;
     /** Replace the abort signal (e.g. after cancellation). */
     setSignal(signal: AbortSignal): void;
+    /** True when speedProfile is "optimized" (1-h cache TTL + pre-warm). */
+    private isSpeedOptimized;
+    /** Fire a cache pre-warm request for Anthropic so the first real turn is a
+     *  cache read instead of a cold write. No-op for other providers and when
+     *  speedProfile is not "optimized". Entirely best-effort — any failure is
+     *  swallowed so prewarm never blocks or aborts the real prompt. */
+    private maybePrewarmCache;
     private getPromptCacheKey;
     /** Stable cache-routing key for downstream sub-agent processes. */
     getCurrentCacheKey(): string | undefined;

package/dist/core/agent-session.d.ts.map

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

package/dist/core/agent-session.js

@@ -1,5 +1,5 @@
 import { agentLoop, isAbortError } from "@kenkaiiii/gg-agent";
-import { ProviderError, } from "@kenkaiiii/gg-ai";
+import { ProviderError, prewarmAnthropicCache, } from "@kenkaiiii/gg-ai";
 import { EventBus } from "./event-bus.js";
 import { SlashCommandRegistry, createBuiltinCommands, } from "./slash-commands.js";
 import { PROMPT_COMMANDS, getPromptCommand } from "./prompt-commands.js";
@@ -16,7 +16,7 @@ import { discoverSkills } from "./skills.js";
 import { ensureAppDirs } from "../config.js";
 import { buildSystemPrompt } from "../system-prompt.js";
 import { createTools, createWebSearchTool, } from "../tools/index.js";
-import { MCPClientManager, getMCPServers, getAllMcpServers } from "./mcp/index.js";
+import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
 import { log } from "./logger.js";
 import { setEstimatorModel } from "./compaction/token-estimator.js";
 import { discoverAgents } from "./agents.js";
@@ -37,6 +37,10 @@ export class AgentSession {
     extensionLoader = new ExtensionLoader();
     messages = [];
     tools = [];
+    /** Rebuilds the read tool for a new model (video byte cap is baked in at
+     *  creation). Called from switchModel so video-capable models get the
+     *  read-tool's native-video path after a mid-session model change. */
+    rebuildReadTool;
     skills = [];
     cacheKeyLogged = false;
     // ── Self-correction hook state (mirrors the TUI's useAgentLoop refs) ──
@@ -63,9 +67,13 @@ export class AgentSession {
     regroundingInjected = false;
     compactionOccurred = false;
     originalRequest = "";
+    /** True after the cache has been pre-warmed for this session. Ensures we only
+     *  fire the warm-up call once (before the first real turn). */
+    cachePrewarmed = false;
     // Messages queued by the user while a run is in flight. Drained at the
     // mid-loop steering boundary (user steering wins over the hooks), mirroring
-    // the TUI's getSteeringMessages.
+    // the TUI's getSteeringMessages. Each entry carries its own attachments so a
+    // user can queue media (images/video/files) mid-run, not just plain text.
     userQueue = [];
     processManager;
     lspManager;
@@ -95,10 +103,27 @@ export class AgentSession {
         this.model = options.model;
         this.cwd = options.cwd;
         this.baseUrl = options.baseUrl;
-        this.maxTokens = options.maxTokens ?? getModel(options.model)?.maxOutputTokens ?? 16384;
+        this.maxTokens = this.resolveMaxTokens(options.model);
         this.thinkingLevel = options.thinkingLevel;
         this.customSystemPrompt = options.systemPrompt;
     }
+    /**
+     * Derive the output-token cap for a model. Follows the active model's
+     * `maxOutputTokens` so a session booted on a large-output model (e.g. Kimi's
+     * 256K) doesn't carry that cap to a smaller one (e.g. Opus's 128K) after a
+     * model switch — that mismatch surfaces from the provider as
+     * `max_tokens: 262144 > 128000, which is the maximum allowed …`. An explicit
+     * `maxTokens` override is honored but clamped to the model's ceiling.
+     */
+    resolveMaxTokens(modelId) {
+        const modelInfo = getModel(modelId);
+        if (this.opts.maxTokens) {
+            return modelInfo
+                ? Math.min(this.opts.maxTokens, modelInfo.maxOutputTokens)
+                : this.opts.maxTokens;
+        }
+        return modelInfo?.maxOutputTokens ?? 16384;
+    }
     async initialize() {
         // Set model for accurate token estimation
         setEstimatorModel(this.model);
@@ -125,12 +150,13 @@ export class AgentSession {
             globalAgentsDir: paths.agentsDir,
             projectDir: this.cwd,
         });
-        const { tools, processManager, lspManager } = createTools(this.cwd, {
+        const { tools, processManager, rebuildReadTool, lspManager } = await createTools(this.cwd, {
             agents,
             skills: this.skills,
             provider: this.provider,
             model: this.model,
             lspDiagnostics: this.settingsManager.get("lspDiagnostics"),
+            authStorage: this.authStorage,
             // Lazy — sessionId/model/provider can change after createTools() runs, so
             // sub-agent spawns read the current parent state at execution time.
             getProvider: () => this.provider,
@@ -147,26 +173,22 @@ export class AgentSession {
                 : {}),
         });
         this.tools = tools;
+        this.rebuildReadTool = rebuildReadTool;
         this.processManager = processManager;
         this.lspManager = lspManager;
-        // Connect MCP servers (non-blocking — failures are logged and skipped)
+        // Connect MCP servers. The connect attempt itself can block for up to the
+        // per-server connect timeout (~30s) — a slow stdio server such as a
+        // first-run `npx -y @playwright/mcp` download stalls here. When the host
+        // gates its own readiness on initialize() (the gg-app sidecar can't emit
+        // its listening handshake until this resolves), `backgroundMcpConnect`
+        // moves the connect off the critical path so the session becomes usable
+        // immediately and tools are appended whenever the servers come up.
         this.mcpManager = new MCPClientManager();
-        try {
-            let apiKey;
-            if (this.provider === "glm") {
-                try {
-                    const glmCreds = await this.authStorage.resolveCredentials("glm");
-                    apiKey = glmCreds.accessToken;
-                }
-                catch {
-                    // GLM not configured — skip Z.AI MCP servers
-                }
-            }
-            const mcpTools = await this.mcpManager.connectAll(getMCPServers(this.provider, apiKey));
-            this.tools.push(...mcpTools);
+        if (this.opts.backgroundMcpConnect) {
+            void this.connectMcpServers();
         }
-        catch (err) {
-            log("WARN", "mcp", `MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            await this.connectMcpServers();
         }
         const basePrompt = this.customSystemPrompt ??
             (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider));
@@ -236,6 +258,47 @@ export class AgentSession {
         await this.extensionLoader.loadAll(paths.extensionsDir, extContext);
         this.eventBus.emit("session_start", { sessionId: this.sessionId });
     }
+    /**
+     * Connect all configured MCP servers and append their tools to `this.tools`.
+     * Resolves the GLM api key first (Z.AI's bundled servers need it). Never
+     * throws — a failed connect is logged and skipped — so it is safe to either
+     * `await` (CLI: tools ready before the first turn) or fire-and-forget
+     * (sidecar: `backgroundMcpConnect`, so a slow stdio server can't stall
+     * startup). Tools are pushed onto the live array the agent loop reads each
+     * turn, so background-connected servers become available on the next prompt.
+     */
+    async connectMcpServers() {
+        if (!this.mcpManager)
+            return;
+        try {
+            let apiKey;
+            if (this.provider === "glm") {
+                try {
+                    const glmCreds = await this.authStorage.resolveCredentials("glm");
+                    apiKey = glmCreds.accessToken;
+                }
+                catch {
+                    // GLM not configured — skip Z.AI MCP servers
+                }
+            }
+            const mcpTools = await this.mcpManager.connectAll(await getAllMcpServers(this.provider, apiKey, this.cwd));
+            this.tools.push(...mcpTools);
+            // Background connect resolves AFTER initialize() has already built the
+            // system prompt (the default path awaits this before buildSystemPrompt,
+            // so its prompt already lists the tools). Refresh messages[0] so the
+            // model is also told about the MCP tools by name on its next turn —
+            // mirrors the TUI's replaceSystemPrompt after connectInitialMcpTools.
+            // Safe ordering: this method's first await yields before initialize()
+            // sets `messages`, and connectAll (process spawn / network) always
+            // resolves long after the local-only remainder of init has finished.
+            if (this.opts.backgroundMcpConnect && mcpTools.length > 0) {
+                await this.rebuildSystemPromptInPlace();
+            }
+        }
+        catch (err) {
+            log("WARN", "mcp", `MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /**
      * Process user input. Handles slash commands or runs agent loop.
      */
@@ -285,14 +348,59 @@ export class AgentSession {
      * attachments are always a direct conversational turn.
      */
     async promptWithAttachments(text, attachments) {
+        const parts = this.buildAttachmentParts(text, attachments);
+        if (parts.length === 0)
+            return;
+        const userMessage = { role: "user", content: parts };
+        this.messages.push(userMessage);
+        await this.persistMessage(userMessage);
+        this.lastPersistedIndex = this.messages.length;
+        await this.runLoop();
+    }
+    /**
+     * Build the native content blocks (text + image/video notes + file notes) for
+     * a user message with attachments. Shared by {@link promptWithAttachments} and
+     * the mid-run steering drain so queued media is delivered identically.
+     */
+    buildAttachmentParts(text, attachments) {
         const parts = [];
         const fileNotes = [];
+        const modelSupportsVideo = getModel(this.model)?.supportsVideo ?? false;
         for (const a of attachments) {
             if (a.kind === "image") {
                 parts.push({ type: "image", mediaType: a.mediaType, data: a.data });
+                if (a.path) {
+                    parts.push({ type: "text", text: `[Image saved at ${a.path}]` });
+                }
             }
             else if (a.kind === "video") {
-                parts.push({ type: "video", mediaType: a.mediaType, data: a.data });
+                // Mirror the CLI's buildUserContentWithAttachments: never send inline
+                // VideoContent in the user message. Video-capable models (Kimi/Gemini/
+                // MiniMax) watch video via the read tool, which auto-compresses to the
+                // model's byte cap and delivers it in the provider's required shape.
+                // Non-video models get a plain note so they know to use ffmpeg. The file
+                // was already saved to disk by prepareAttachments in the sidecar.
+                if (modelSupportsVideo && a.path) {
+                    parts.push({
+                        type: "text",
+                        text: `The user attached a video at ${a.path}. You CAN watch it: call the read tool ` +
+                            `on this exact path now, then answer based on what you see. Do not say you ` +
+                            `cannot watch video — reading the file lets you analyze it.`,
+                    });
+                }
+                else if (a.path) {
+                    parts.push({
+                        type: "text",
+                        text: `[User attached a video file at ${a.path}. You cannot watch video directly; ` +
+                            `if needed, use ffmpeg to extract frames or audio.]`,
+                    });
+                }
+                else {
+                    parts.push({
+                        type: "text",
+                        text: `[User attached a video file but it could not be saved for analysis.]`,
+                    });
+                }
             }
             else if (a.path) {
                 fileNotes.push(`- ${a.name} (saved at ${a.path})`);
@@ -306,13 +414,7 @@ export class AgentSession {
         }
         if (textParts.length > 0)
             parts.unshift({ type: "text", text: textParts.join("\n\n") });
-        if (parts.length === 0)
-            return;
-        const userMessage = { role: "user", content: parts };
-        this.messages.push(userMessage);
-        await this.persistMessage(userMessage);
-        this.lastPersistedIndex = this.messages.length;
-        await this.runLoop();
+        return parts;
     }
     /**
      * Reset per-run self-correction hook state. Mirrors the TUI's run_start
@@ -406,8 +508,18 @@ export class AgentSession {
         // User steering wins: drain any messages queued during this run first so the
         // agent sees them mid-loop instead of after it stops.
         if (this.userQueue.length > 0) {
-            const merged = this.userQueue.splice(0).join("\n\n");
-            return [{ role: "user", content: merged }];
+            const queued = this.userQueue.splice(0);
+            // Plain-text-only queue: keep the simple merged-string message.
+            if (queued.every((m) => m.attachments.length === 0)) {
+                const merged = queued.map((m) => m.text).join("\n\n");
+                return [{ role: "user", content: merged }];
+            }
+            // Any queued attachments → deliver one user message with text + media
+            // blocks built the same way as a non-queued attachment prompt.
+            const parts = [];
+            for (const m of queued)
+                parts.push(...this.buildAttachmentParts(m.text, m.attachments));
+            return [{ role: "user", content: parts }];
         }
         if (!this.settingsManager.get("idealReviewEnabled"))
             return null;
@@ -507,7 +619,9 @@ export class AgentSession {
                 defaultHeaders: this.provider === "moonshot" && isKimiCodingEndpoint(effectiveBaseUrl)
                     ? kimiCodingHeaders()
                     : undefined,
-                cacheRetention: "short",
+                // speedProfile "optimized": 1-h cache TTL (survives turns >5 min apart)
+                // + pre-warm before the first turn. "baseline": current 5-min default.
+                cacheRetention: this.isSpeedOptimized() ? "long" : "short",
                 promptCacheKey: this.getPromptCacheKey(),
                 supportsImages: modelInfo?.supportsImages,
                 supportsVideo: modelInfo?.supportsVideo,
@@ -526,6 +640,11 @@ export class AgentSession {
             }
         };
         try {
+            // Fire cache pre-warm before the first turn (Anthropic + speedProfile optimized).
+            // Runs concurrently with nothing — it must complete before runAgentLoop so
+            // the cache is warm when the real request arrives. Best-effort: swallowed
+            // inside maybePrewarmCache/prewarmAnthropicCache.
+            await this.maybePrewarmCache(creds);
             await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
         }
         catch (err) {
@@ -565,7 +684,25 @@ export class AgentSession {
             this.provider = provider;
         this.model = model;
         setEstimatorModel(model);
-        this.eventBus.emit("model_change", { provider: this.provider, model: this.model });
+        // maxTokens must follow the active model — it was frozen at the boot
+        // model's `maxOutputTokens` in the constructor, so without this a session
+        // booted on e.g. Kimi (256K) keeps sending that cap after switching to a
+        // smaller model (Opus 128K), which the provider rejects.
+        this.maxTokens = this.resolveMaxTokens(model);
+        this.eventBus.emit("model_change", {
+            provider: this.provider,
+            model: this.model,
+            supportsVideo: getModel(this.model)?.supportsVideo ?? false,
+        });
+        // Rebuild the read tool for the new model's video byte cap. The tool's
+        // video capability (description + native-video execute path) is baked in
+        // at creation from the model's maxVideoBytes, so switching to/from a
+        // video-capable model mid-session needs a fresh tool object — mirrors
+        // the TUI's rebuildReadTool call on model switch.
+        if (this.rebuildReadTool) {
+            const newReadTool = this.rebuildReadTool(model);
+            this.tools = this.tools.map((t) => (t.name === "read" ? newReadTool : t));
+        }
         // Update provider-specific tools when provider changes
         if (provider && provider !== prevProvider) {
             // Add/remove client-side web_search tool based on provider.
@@ -718,19 +855,24 @@ export class AgentSession {
     getPlanMode() {
         return this.planModeRef.current;
     }
-    /** Queue a user message to be injected mid-run as steering. Returns the new
-     *  queue length. No-op semantics are the caller's concern. */
-    queueMessage(text) {
-        this.userQueue.push(text);
+    /** Queue a user message (optionally with attachments) to be injected mid-run
+     *  as steering. Returns the new queue length. No-op semantics are the caller's
+     *  concern. */
+    queueMessage(text, attachments = []) {
+        this.userQueue.push({ text, attachments });
         return this.userQueue.length;
     }
     /** Number of messages currently queued. */
     getQueuedCount() {
         return this.userQueue.length;
     }
-    /** Clear the queue, returning the combined text (to restore to the composer). */
+    /** Clear the queue, returning the combined text (to restore to the composer).
+     *  Queued attachments are dropped on cancel — the composer only restores text. */
     drainQueue() {
-        return this.userQueue.splice(0).join("\n\n");
+        return this.userQueue
+            .splice(0)
+            .map((m) => m.text)
+            .join("\n\n");
     }
     /** Snapshot of background processes (bash run_in_background), newest-state. */
     listBackgroundProcesses() {
@@ -826,6 +968,44 @@ export class AgentSession {
     setSignal(signal) {
         this.opts = { ...this.opts, signal };
     }
+    /** True when speedProfile is "optimized" (1-h cache TTL + pre-warm). */
+    isSpeedOptimized() {
+        return this.settingsManager?.get("speedProfile") === "optimized";
+    }
+    /** Fire a cache pre-warm request for Anthropic so the first real turn is a
+     *  cache read instead of a cold write. No-op for other providers and when
+     *  speedProfile is not "optimized". Entirely best-effort — any failure is
+     *  swallowed so prewarm never blocks or aborts the real prompt. */
+    async maybePrewarmCache(creds) {
+        if (this.cachePrewarmed || !this.isSpeedOptimized() || this.provider !== "anthropic") {
+            return;
+        }
+        this.cachePrewarmed = true;
+        try {
+            const userAgent = await getClaudeCliUserAgent();
+            const systemText = typeof this.messages[0]?.content === "string" ? this.messages[0].content : "";
+            if (!systemText)
+                return;
+            await prewarmAnthropicCache({
+                apiKey: creds.accessToken,
+                model: this.model,
+                system: systemText,
+                tools: this.tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                    ...(t.rawInputSchema ? { rawInputSchema: t.rawInputSchema } : {}),
+                })),
+                baseUrl: this.baseUrl ?? creds.baseUrl,
+                userAgent,
+                cacheRetention: "long",
+                signal: this.opts.signal,
+            });
+        }
+        catch {
+            // Best-effort — prewarm failure must never block the session.
+        }
+    }
     getPromptCacheKey() {
         if (this.opts.promptCacheKey)
             return this.opts.promptCacheKey;