visionclaw 0.1.191-beta.2 → 0.1.191-beta.4

package/dist/agent/engines/claude/cli-resolver.d.ts

@@ -0,0 +1,16 @@
+export type ClaudeCliResolution = {
+    kind: "native";
+    path: string;
+} | {
+    kind: "legacy-cli-js";
+    path: string;
+} | {
+    kind: "sdk-default";
+};
+export declare function resolveClaudeCliExecutable(): ClaudeCliResolution;
+/** Convenience wrapper — return just the path, or `undefined` when we should
+ *  leave the option unset and let the SDK do its own lookup. */
+export declare function getClaudeExecutablePath(): string | undefined;
+/** For tests. */
+export declare function _resetClaudeCliResolverCache(): void;
+//# sourceMappingURL=cli-resolver.d.ts.map

package/dist/agent/engines/claude/cli-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-resolver.d.ts","sourceRoot":"","sources":["../../../../src/agent/engines/claude/cli-resolver.ts"],"names":[],"mappings":"AA8BA,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAQ5B,wBAAgB,0BAA0B,IAAI,mBAAmB,CAIhE;AAED;gEACgE;AAChE,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,SAAS,CAG5D;AAsCD,iBAAiB;AACjB,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/dist/agent/engines/claude/cli-resolver.js

@@ -0,0 +1,83 @@
+/**
+ * Resolve the executable path that `@anthropic-ai/claude-agent-sdk` should
+ * spawn as its "Claude Code" subprocess.
+ *
+ * Why we need this:
+ *   - In 0.2.108–0.2.112 the SDK shipped a `cli.js` alongside `sdk.mjs`, and
+ *     the intended way to pin it from a bundled app was to pass
+ *     `pathToClaudeCodeExecutable` pointing at that file.
+ *   - Starting with 0.2.113 (published 2026-04-14) the SDK tarball dropped
+ *     `cli.js` entirely and switched to a platform-specific native binary
+ *     shipped via an optional peer package
+ *     `@anthropic-ai/claude-agent-sdk-<platform>-<arch>`.
+ *   - Our previous implementation hard-coded `cli.js`, so a stock
+ *     `pnpm install` that pulled the newer SDK caused the child process to
+ *     fail with `MODULE_NOT_FOUND`, which in turn surfaced as an async EPIPE
+ *     in the parent.
+ *
+ * Resolution order:
+ *   1. The native binary from `claude-agent-sdk-<platform>-<arch>/claude`
+ *      (the forward-compatible choice for 0.2.113+).
+ *   2. A legacy `cli.js` next to `sdk.mjs` (still valid for 0.2.112 and older).
+ *   3. `null`, meaning: let the SDK resolve the executable itself. Recent SDK
+ *      versions implement the same fallback chain internally and throw a
+ *      clear `ReferenceError` if nothing is found, which is much easier to
+ *      diagnose than a silent EPIPE.
+ */
+import { createRequire } from "module";
+import fs from "fs";
+import path from "path";
+/**
+ * Resolve once per process — filesystem lookups here are cheap but the result
+ * never changes for a given installation.
+ */
+let cached;
+export function resolveClaudeCliExecutable() {
+    if (cached)
+        return cached;
+    cached = doResolve();
+    return cached;
+}
+/** Convenience wrapper — return just the path, or `undefined` when we should
+ *  leave the option unset and let the SDK do its own lookup. */
+export function getClaudeExecutablePath() {
+    const r = resolveClaudeCliExecutable();
+    return r.kind === "sdk-default" ? undefined : r.path;
+}
+function doResolve() {
+    const _require = createRequire(import.meta.url);
+    // 1. Modern native binary (claude-agent-sdk >= 0.2.113).
+    const nativePkg = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}`;
+    try {
+        const pkgJsonPath = _require.resolve(`${nativePkg}/package.json`);
+        const pkgDir = path.dirname(pkgJsonPath);
+        // The package ships a single executable named `claude`.
+        const candidate = path.join(pkgDir, "claude");
+        if (fs.existsSync(candidate)) {
+            return { kind: "native", path: candidate };
+        }
+    }
+    catch {
+        // Optional dep not installed — fall through to legacy cli.js.
+    }
+    // 2. Legacy JS entry (claude-agent-sdk <= 0.2.112).
+    try {
+        const sdkDir = path.dirname(_require.resolve("@anthropic-ai/claude-agent-sdk"));
+        const candidate = path.join(sdkDir, "cli.js");
+        if (fs.existsSync(candidate)) {
+            return { kind: "legacy-cli-js", path: candidate };
+        }
+    }
+    catch {
+        // No SDK at all — let the caller's catch handle this.
+    }
+    // 3. Give up and let the SDK resolve on its own. Newer versions still have
+    //    a reasonable internal lookup and will throw a clear error if nothing
+    //    works, rather than silently spawning a missing module.
+    return { kind: "sdk-default" };
+}
+/** For tests. */
+export function _resetClaudeCliResolverCache() {
+    cached = undefined;
+}
+//# sourceMappingURL=cli-resolver.js.map

package/dist/agent/engines/claude/cli-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-resolver.js","sourceRoot":"","sources":["../../../../src/agent/engines/claude/cli-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAOxB;;;GAGG;AACH,IAAI,MAAuC,CAAC;AAE5C,MAAM,UAAU,0BAA0B;IACxC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,SAAS,EAAE,CAAC;IACrB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;gEACgE;AAChE,MAAM,UAAU,uBAAuB;IACrC,MAAM,CAAC,GAAG,0BAA0B,EAAE,CAAC;IACvC,OAAO,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvD,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEhD,yDAAyD;IACzD,MAAM,SAAS,GAAG,kCAAkC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IACvF,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,SAAS,eAAe,CAAC,CAAC;QAClE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACzC,wDAAwD;QACxD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC9C,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CACzB,QAAQ,CAAC,OAAO,CAAC,gCAAgC,CAAC,CACnD,CAAC;QACF,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC9C,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACpD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;IAED,2EAA2E;IAC3E,0EAA0E;IAC1E,4DAA4D;IAC5D,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;AACjC,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,4BAA4B;IAC1C,MAAM,GAAG,SAAS,CAAC;AACrB,CAAC"}

package/dist/agent/engines/claude/session-browser-policy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Ensure Chrome is running (Playwriter mode). On the first Playwriter tool call
+ * of each turn we force a clean restart to reset stale extension connections;
+ * later calls in the same turn only ensure Chrome is up.
+ *
+ * Returns true when a connection reset was performed for this turn.
+ */
+export declare function ensurePlaywriterChrome(didResetConnectionsThisTurn: boolean): boolean;
+//# sourceMappingURL=session-browser-policy.d.ts.map

package/dist/agent/engines/claude/session-browser-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-browser-policy.d.ts","sourceRoot":"","sources":["../../../../src/agent/engines/claude/session-browser-policy.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,2BAA2B,EAAE,OAAO,GACnC,OAAO,CAmBT"}

package/dist/agent/engines/claude/session-browser-policy.js

@@ -0,0 +1,49 @@
+import { execSync } from "node:child_process";
+import { logger } from "../../../logger.js";
+/**
+ * Force Chrome to restart once per turn before the first Playwriter tool call.
+ * This clears stale extension relay connections from earlier sessions so the
+ * Playwriter MCP sees a single fresh extension connection.
+ */
+function restartChromeForPlaywriter() {
+    try {
+        execSync("pkill -x 'Google Chrome'", { stdio: "ignore" });
+    }
+    catch {
+        // pkill exits non-zero when Chrome is not running — expected.
+    }
+    try {
+        execSync('open -a "Google Chrome"', { stdio: "ignore" });
+    }
+    catch (err) {
+        logger.warn(`Failed to restart Chrome for Playwriter: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Ensure Chrome is running (Playwriter mode). On the first Playwriter tool call
+ * of each turn we force a clean restart to reset stale extension connections;
+ * later calls in the same turn only ensure Chrome is up.
+ *
+ * Returns true when a connection reset was performed for this turn.
+ */
+export function ensurePlaywriterChrome(didResetConnectionsThisTurn) {
+    if (!didResetConnectionsThisTurn) {
+        logger.system("Resetting Chrome before Playwriter session");
+        restartChromeForPlaywriter();
+        return true;
+    }
+    try {
+        execSync("pgrep -x 'Google Chrome'", { stdio: "ignore" });
+    }
+    catch {
+        logger.system("Chrome not running — launching for Playwriter extension");
+        try {
+            execSync('open -a "Google Chrome"', { stdio: "ignore" });
+        }
+        catch (err) {
+            logger.warn(`Failed to launch Chrome: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=session-browser-policy.js.map

package/dist/agent/engines/claude/session-browser-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-browser-policy.js","sourceRoot":"","sources":["../../../../src/agent/engines/claude/session-browser-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;GAIG;AACH,SAAS,0BAA0B;IACjC,IAAI,CAAC;QACH,QAAQ,CAAC,0BAA0B,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;IAED,IAAI,CAAC;QACH,QAAQ,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,4CAA4C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9G,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,2BAAoC;IAEpC,IAAI,CAAC,2BAA2B,EAAE,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,4CAA4C,CAAC,CAAC;QAC5D,0BAA0B,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,QAAQ,CAAC,0BAA0B,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,MAAM,CAAC,yDAAyD,CAAC,CAAC;QACzE,IAAI,CAAC;YACH,QAAQ,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,4BAA4B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/agent/engines/claude/session.d.ts

@@ -0,0 +1,275 @@
+import { type Query, type SDKMessage, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { MessageParam } from "@anthropic-ai/sdk/resources";
+import type { SessionMode } from "../../mailbox.js";
+import type { ScreenshotInjector } from "../../screenshot-injector.js";
+import type { AgentSessionConstructorArgs, AgentSessionLike, AgentStreamMessage, InjectMessageOptions, SendAndStreamOptions, UsageSnapshot } from "../session-types.js";
+export type { SDKMessage, SDKUserMessage };
+export type { SystemPromptConfig } from "../session-types.js";
+/**
+ * Used-token threshold (fraction of context window) at which we trigger
+ * compaction for **large** context windows (>= {@link COMPACT_MAX_CONTEXT_WINDOW}).
+ *
+ * Smaller windows scale up to {@link COMPACT_SMALL_WINDOW_USED_PCT_THRESHOLD}
+ * via {@link getCompactUsedPctThreshold}.
+ */
+export declare const COMPACT_LARGE_WINDOW_USED_PCT_THRESHOLD = 0.7;
+export declare const MAX_BASE64_IMAGE_BLOCKS = 10;
+/** When total image blocks (real + placeholder) exceed this, trigger compaction
+ *  to avoid hitting Claude API's 100-image limit. */
+export declare const IMAGE_COMPACT_THRESHOLD = 80;
+/**
+ * Wraps the V1 query() API with a long-lived async generator for streaming
+ * input. This allows injecting additional user messages while the agent is
+ * processing (interrupt messages), instead of waiting for the query to
+ * finish before sending the next message.
+ */
+export declare class ClaudeAgentSession implements AgentSessionLike {
+    private config;
+    private buildSystemPrompt;
+    private runtimeSurface;
+    private getDualSessionEnabled;
+    private getAndroidUseEnabled;
+    /** Working directory for the SDK subprocess. Defaults to profile config dir. */
+    private readonly sessionCwd;
+    private nativeTools;
+    /** Resolved external MCP servers (playwright, serpapi, etc.) for this runtime. */
+    private externalMcpServers;
+    /** Dynamic MCP servers added at runtime via manage_mcp_servers tool. */
+    private dynamicMcpServers;
+    private currentQuery;
+    private warmQuery;
+    private warmUpPromise;
+    private warmReadyAtMs;
+    private sessionId;
+    private transcriptPath;
+    readonly mode: SessionMode;
+    /**
+     * Pending message queue for the long-lived generator.
+     * When a message is injected, it's pushed here and the waiting
+     * generator is woken up via the resolver.
+     */
+    private pendingMessages;
+    private messageResolver;
+    private generatorClosed;
+    private _orphanedInjections;
+    private lastCompactRequestAtMs;
+    private compactInFlight;
+    private stopRequested;
+    /**
+     * Tracks whether we've seeded `<profile>/.claude/settings.local.json`
+     * with our auto-memory directory override this process-lifetime. The seed
+     * helper is itself idempotent, but this flag keeps hot paths (every
+     * `consume()` / `warmUp()`) from hitting the filesystem repeatedly.
+     */
+    private autoMemorySeedDone;
+    /** Optional: auto-injects screenshots after Playwright tool calls. */
+    private _screenshotInjector;
+    /** AbortController passed to the SDK; aborting it cleanly stops the running query. */
+    private abortController;
+    private warmAbortController;
+    /**
+     * Timer that proactively replaces the pre-warmed subprocess at
+     * `WARM_REFRESH_TTL_MS` intervals. Cleared when the warm is consumed,
+     * on stop, or before arming a new one.
+     */
+    private warmRefreshTimer;
+    private lastUsageSnapshot;
+    private playwriterConnectionsResetThisTurn;
+    constructor({ config, buildSystemPrompt, runtimeSurface, sessionContext, }: AgentSessionConstructorArgs);
+    set screenshotInjector(injector: ScreenshotInjector | null);
+    /**
+     * Seed `<profile>/.claude/settings.local.json` once per process so the
+     * CLI's auto-memory lands inside the active profile instead of the
+     * default `~/.claude/projects/...` tree. Called from every CLI-spawn
+     * path (warm + cold); the underlying helper is itself idempotent.
+     *
+     * Gated on the `autoMemorySeedDone` flag so the happy path doesn't
+     * re-read/re-write the file every turn. The flag is set **only on
+     * success** — if the first attempt fails (permissions, disk full, etc.)
+     * the next warm/cold spawn will retry until it lands, instead of
+     * silently leaving the CLI on its default memory path for the rest of
+     * the session.
+     */
+    private ensureAutoMemorySeeded;
+    /**
+     * Build a fresh mcpServers record with a new visionclaw tool server instance.
+     * This avoids the "Already connected to a transport" error when the same
+     * McpServer instance is reused across concurrent/sequential query() calls.
+     */
+    private buildMcpServers;
+    private buildNativeToolOptions;
+    private buildHooks;
+    /**
+     * Build the shared Claude query options used for both pre-warm and live runs.
+     */
+    private buildQueryOptions;
+    /**
+     * Cancel any pending proactive-refresh timer. Idempotent.
+     */
+    private clearWarmRefreshTimer;
+    /**
+     * Arm the proactive-refresh timer. Caller must ensure any previous timer
+     * is cleared. Uses `.unref()` so the process can exit while a warm
+     * subprocess is idle — the refresh is purely a background optimization
+     * and should never hold the event loop alive on its own.
+     */
+    private scheduleWarmRefresh;
+    /**
+     * Handler for the refresh timer. Covers two cases:
+     *  1. Normal TTL refresh: `warmQuery` is non-null → close the stale
+     *     subprocess and start a fresh one.
+     *  2. Retry after a previous failure: `warmQuery` is null → just
+     *     attempt warmUp again (no teardown needed).
+     *
+     * If the warm was already consumed between timer arming and firing,
+     * the consume path would have cleared the timer, so we shouldn't
+     * reach here in that case.
+     */
+    private performWarmRefresh;
+    /**
+     * Post-warmUp follow-up for performWarmRefresh. Kept in its own method so
+     * TS's control-flow narrowing in performWarmRefresh doesn't treat these
+     * fields as having their pre-await values.
+     */
+    private handleWarmRefreshOutcome;
+    /**
+     * Send the initial user message and return the query generator to stream
+     * responses. The underlying async generator stays open so that additional
+     * messages can be injected via injectMessage().
+     */
+    warmUp(): Promise<void>;
+    sendAndStream(content: MessageParam["content"], options?: SendAndStreamOptions): AsyncIterable<AgentStreamMessage>;
+    /**
+     * Inject a new user message into the running query stream.
+     * The agent will see this as a follow-up user message in the conversation.
+     * Only works while a query is active (between sendAndStream and closeInput).
+     *
+     * @returns true if the message was injected, false if the generator is closed.
+     */
+    injectMessage(content: MessageParam["content"], options?: InjectMessageOptions): boolean;
+    /**
+     * Signal the input generator to close.
+     * Any injected messages still in the pending queue are counted as
+     * orphaned — they were accepted by injectMessage but never delivered
+     * to the SDK.
+     */
+    closeInput(): void;
+    /**
+     * Returns true if injected messages were lost when the generator closed.
+     */
+    get hasOrphanedInjections(): boolean;
+    get isInputClosed(): boolean;
+    /**
+     * Request that the current agent turn be stopped.
+     * Uses the SDK's AbortController to cleanly signal the running query to
+     * stop, then closes the input stream so the loop returns to idle.
+     */
+    requestStop(): void;
+    isStopRequested(): boolean;
+    clearStop(): void;
+    /**
+     * Update the persisted session ID.
+     *
+     * Only saves on first capture (null → id). Once set, a different ID from
+     * the SDK is ignored — it means the resume failed and the SDK created a
+     * throwaway conversation. Persisting it would corrupt session.json and
+     * orphan the real transcript.
+     */
+    captureSessionId(id: string | undefined): void;
+    captureTranscriptPath(p: string | undefined | null): void;
+    getSessionId(): string | null;
+    /**
+     * Proactively request compaction by running the /compact slash command as a
+     * separate one-turn query resumed from the current session.
+     *
+     * This is more reliable than injecting "/compact" into the streaming prompt
+     * because the running query may treat it as ordinary text.
+     */
+    requestCompaction(): Promise<void>;
+    captureUsageSnapshot(snapshot: UsageSnapshot): void;
+    /**
+     * Update the usage snapshot after the SDK performs mid-query auto-compaction.
+     * Uses `pre_tokens` (the post-compaction token count) and the last known
+     * context window to compute an accurate `usedPct`, preventing the post-query
+     * `maybeCompact` from triggering a redundant compaction.
+     */
+    capturePostCompactionSnapshot(postCompactionTokens: number): void;
+    /**
+     * Unified between-turn compaction gate.  Triggers compaction when **either**:
+     *  1. Token usage exceeds the context-window threshold, OR
+     *  2. Total image blocks (real + placeholder) in the transcript reach
+     *     `imageThreshold`, approaching Claude API's 100-image limit.
+     *
+     * Both triggers share the same cooldown and in-flight guard so we never
+     * run two back-to-back compactions in the same between-turn pass.
+     */
+    maybeCompact(options?: {
+        /**
+         * Optional explicit override. When set, takes precedence over the
+         * context-window-aware auto-scaling done by
+         * {@link getCompactUsedPctThreshold}.
+         */
+        usedPctThreshold?: number;
+        cooldownMs?: number;
+        imageThreshold?: number;
+    }): Promise<void>;
+    getTranscriptPath(): string | null;
+    /**
+     * Derive the transcript path from the session ID and config dir, even before
+     * the SDK subprocess has started and reported it via hooks.
+     */
+    private deriveTranscriptPath;
+    getUsageSnapshot(): UsageSnapshot | null;
+    /** Returns the live Query object, or null if no query is active. */
+    getCurrentQuery(): Query | null;
+    /**
+     * Validation adapter around `Query.getContextUsage()` (SDK 0.2.114+).
+     *
+     * The SDK's `Query` interface exposes `getContextUsage()` as a control
+     * request over the streaming bridge. It returns a rich breakdown:
+     *
+     * ```ts
+     * {
+     *   categories: { name: string; tokens: number; color: string; isDeferred?: boolean }[];
+     *   totalTokens: number;
+     *   maxTokens: number;       // context window for the *active* model
+     *   rawMaxTokens: number;    // nominal max before any reductions
+     *   percentage: number;      // UI percentage (0..100)
+     *   gridRows: ...[];         // TUI-only
+     *   model: string;
+     *   memoryFiles: { path: string; type: string; tokens: number }[];
+     *   mcpTools: { name: string; serverName: string; tokens: number }[];
+     * }
+     * ```
+     *
+     * We map it onto our existing {@link UsageSnapshot} shape:
+     *   - `usedInputTokens` ← `totalTokens`
+     *   - `contextWindow`   ← `maxTokens` (post-reduction; matches what the
+     *                         model actually has to work with right now)
+     *   - `usedPct`         ← computed from the two above, NOT from the
+     *                         SDK's `percentage` field. The SDK's value is
+     *                         UI-scale (0..100); our consumers expect 0..1.
+     *                         Computing locally keeps both fields internally
+     *                         consistent.
+     *   - `allImageBlocks`  — intentionally preserved from any existing
+     *                         snapshot; `getContextUsage` doesn't know about
+     *                         raw image-block counts in the transcript, so
+     *                         we don't clobber the value that
+     *                         {@link captureUsageSnapshot} maintains.
+     *
+     * This is purely a read adapter — no callers in compaction or the
+     * wake loop should depend on it yet. It exists to let us sanity-check
+     * the live SDK response before wiring any behavior changes around it.
+     * Returns null when no live query is active, when the method is absent
+     * on the active Query instance (e.g. an older CLI), or when the call
+     * errors transiently.
+     *
+     * TODO: we should update snapshot based on this.
+     */
+    getLiveContextUsage(): Promise<UsageSnapshot | null>;
+    /** Replace the full set of dynamic MCP servers (used when loading from disk). */
+    setDynamicMcpServers(servers: Record<string, Record<string, unknown>>): void;
+    /** Get the current dynamic MCP servers record. */
+    getDynamicMcpServers(): Record<string, Record<string, unknown>>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/agent/engines/claude/session.d.ts.map

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