@love-moon/ai-sdk 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @love-moon/ai-sdk
 
+## 0.14.0
+
+### Minor Changes
+
+- e168077: Support `/clear` in task chats. Fire detects a bare `/clear` message (like
+  `/compact`) and drops the AI's context instead of sending the text to the model.
+  Sessions advertise `capabilities.clear` and implement the new optional
+  `runClear()` on top of each backend's own native reset, so the backend process,
+  browser or RPC connection stays up:
+
+  - claude: native `/clear` slash command (the SDK's `conversation_reset` reports
+    the new conversation id)
+  - codex app-server: `thread/start` on the live transport
+  - codex exec: drops the replayed history, which is the whole context for a
+    stateless CLI
+  - copilot: `createSession()` on the same client; the old conversation is
+    detached, not deleted
+  - kimi wire and legacy print: the CLI's built-in `/clear` (prompt mode opts out)
+  - opencode: `session.create` on the same `opencode serve`
+  - dsh: rotates onto a fresh wire session id and keeps the runtime subprocess
+  - chat-web: `newChat()` in the same browser and profile
+
+  Backends without the capability (external providers) fall back to closing the
+  session and continuing on a brand-new one. Either way the task's chat history is
+  kept and the task is rebound to the session the backend ends up on, so a later
+  restart resumes the cleared conversation rather than the old one. The codex
+  fresh-session bootstrap lock now covers that fallback too, and the kimi wire
+  transport drops configured `--continue`/`--resume`/`--session` flags (like kimi
+  print already did) so they cannot reattach a cleared session to the old
+  conversation. Two caveats: the configured `pre_prompt` is not re-sent to the
+  cleared session, and a chat-web task running with
+  `CONDUCTOR_AI_SDK_DISABLE_WORKER=1` can only clear natively — its fallback would
+  hit the browser profile lock, because in that mode the lock owner is fire itself.
+
+- 12a829c: Show each AI reply's token usage beside its timestamp: the turn's tokens, the
+  task total after it, and the input cache share (the part of the turn's input
+  served from the prompt cache).
+
+  - `@love-moon/ai-sdk`: new `summarizeTurnUsage(usage)` normalizes a turn's usage
+    into `{ tokens, inputTokens, cachedInputTokens }` (Claude: fresh input + cache
+    writes + cache reads; Codex: input already includes cached). The Codex
+    app-server provider's turn/goal `usage` now also carries `turnInputTokens` and
+    `turnCachedInputTokens`.
+  - `@love-moon/conductor-sdk`: `sendTurnUsage` accepts `input_tokens`,
+    `cached_input_tokens` and the reply's `message_id`.
+  - `conductor fire` reports a finished turn's usage after its reply, naming that
+    reply (for streamed sessions, the turn's last streamed reply), so the server
+    records it on the message (`metadata.turn_usage`) and pushes it to open chats.
+
+### Patch Changes
+
+- d4f6fb9: Add opt-in Codex reply timing diagnostics to distinguish first-text generation
+  from buffering before a complete message is forwarded. Traces contain IDs and
+  monotonic durations, never prompt or reply text.
+
 ## 0.13.3
 
 ### Patch Changes

package/dist/client.d.ts

@@ -19,6 +19,7 @@ export class RemoteAiSession extends EventEmitter<[never]> {
         capabilities: {
             goal?: boolean | undefined;
             compact?: boolean | undefined;
+            clear?: boolean | undefined;
         };
     };
     sessionMessageHandler: any;
@@ -53,6 +54,7 @@ export class RemoteAiSession extends EventEmitter<[never]> {
         capabilities: {
             goal?: boolean | undefined;
             compact?: boolean | undefined;
+            clear?: boolean | undefined;
         };
     };
     usesSessionFileReplyStream(): boolean;
@@ -72,6 +74,7 @@ export class RemoteAiSession extends EventEmitter<[never]> {
     runTurn(promptText: any, options?: {}): Promise<any>;
     runGoal(goal: any, options?: {}): Promise<any>;
     runCompact(request?: {}, options?: {}): Promise<any>;
+    runClear(request?: {}, options?: {}): Promise<any>;
     getGoal(): Promise<any>;
     clearGoal(): Promise<any>;
     close(): Promise<void>;
@@ -112,6 +115,7 @@ declare class LocalAiSessionProxy extends EventEmitter<[never]> {
         capabilities: {
             goal?: boolean | undefined;
             compact?: boolean | undefined;
+            clear?: boolean | undefined;
         };
     };
     readyPromise: Promise<any>;
@@ -131,6 +135,7 @@ declare class LocalAiSessionProxy extends EventEmitter<[never]> {
     runTurn(promptText: any, options?: {}): Promise<any>;
     runGoal(goal: any, options?: {}): Promise<any>;
     runCompact(request?: {}, options?: {}): Promise<any>;
+    runClear(request?: {}, options?: {}): Promise<any>;
     getGoal(): Promise<any>;
     clearGoal(): Promise<any>;
     close(): Promise<void>;

package/dist/client.js

@@ -14,6 +14,11 @@ function createUnsupportedCompactError(name) {
     err.reason = "unsupported_compact";
     return err;
 }
+function createUnsupportedClearError(name) {
+    const err = new Error(`runClear() is not supported by backend session (${name || "unknown"}).`);
+    err.reason = "unsupported_clear";
+    return err;
+}
 const WORKER_PATH = fileURLToPath(new URL("./worker.js", import.meta.url));
 function sanitizeOptionsForWorker(options = {}) {
     const sanitized = {};
@@ -232,6 +237,16 @@ export class RemoteAiSession extends EventEmitter {
             progressHandler: typeof onProgress === "function" ? onProgress : null,
         });
     }
+    async runClear(request = {}, options = {}) {
+        await this.readyPromise;
+        if (!this.snapshot?.capabilities || this.snapshot.capabilities.clear !== true) {
+            throw createUnsupportedClearError(this.snapshot?.provider || this.snapshot?.backend);
+        }
+        const { onProgress, ...restOptions } = options || {};
+        return this.callWorker("runClear", [request, restOptions], {
+            progressHandler: typeof onProgress === "function" ? onProgress : null,
+        });
+    }
     async getGoal() {
         // Propagate worker-creation errors instead of masking them as "no goal".
         // See N3 in the review.
@@ -699,6 +714,13 @@ class LocalAiSessionProxy extends EventEmitter {
         }
         return await session.runCompact(request, options);
     }
+    async runClear(request = {}, options = {}) {
+        const session = await this.readyPromise;
+        if (this.snapshot?.capabilities?.clear !== true || typeof session.runClear !== "function") {
+            throw createUnsupportedClearError(session?.constructor?.name);
+        }
+        return await session.runClear(request, options);
+    }
     async getGoal() {
         const session = await this.readyPromise;
         const capabilities = resolveSessionCapabilities(session);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { BUILT_IN_BACKENDS } from "./built-in-backends.js";
 export { PROVIDER_MEDIA_CAPABILITIES } from "./media-adapters.js";
+export { summarizeTurnUsage } from "./turn-usage.js";
 export { createAiSession, RemoteAiSession } from "./client.js";
 export { isClaudeRootPermissionRestricted, resolveClaudeCommandForRoot, resolveClaudePermissionPolicy } from "./providers/claude-agent-sdk-session.js";
 export { appendContextFilesToPrompt, normalizeContextFiles } from "./context-files.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { BUILT_IN_BACKENDS } from "./built-in-backends.js";
 export { PROVIDER_MEDIA_CAPABILITIES } from "./media-adapters.js";
 export { isClaudeRootPermissionRestricted, resolveClaudeCommandForRoot, resolveClaudePermissionPolicy, } from "./providers/claude-agent-sdk-session.js";
 export { appendContextFilesToPrompt, normalizeContextFiles } from "./context-files.js";
+export { summarizeTurnUsage } from "./turn-usage.js";
 export { assertMediaCapabilities, fileMediaToBase64, fileMediaToDataUri, normalizeMediaInputs, resolveTurnMedia, } from "./media-input.js";
 export { GOAL_STATUSES, TERMINAL_GOAL_STATUSES, isGoalStatus, isTerminalGoalStatus, } from "./shared.js";
 export { AiManager, accountNameFromPath, checkInstall, checkInstallAll, checkNetwork, checkNetworkAll, getClaudeQuota, getCodexQuota, getCopilotQuota, getCurrentCodexAccount, getDshQuota, readCachedDshQuota, resolveDeepSeekCredential, getExternalQuota, getExternalQuotaList, getKimiQuota, listCodexAccounts, loadAiManagerConfig, normalizeExternalQuota, normalizeExternalQuotaList, parseAuthFile, parseAuthFileContents, parseCopilotQuotaSnapshots, readCachedCodexQuota, resolveClaudeCredential, switchCodexAccount, } from "./manager/index.js";

package/dist/providers/chat-web-session.d.ts

@@ -110,6 +110,7 @@ export class ChatWebSession extends EventEmitter<[never]> {
             updated_at: string;
         } | null;
         capabilities: {
+            clear: boolean;
             media: Readonly<{
                 image: "unsupported";
             }>;
@@ -162,6 +163,23 @@ export class ChatWebSession extends EventEmitter<[never]> {
     getChatWebModule(): Promise<any>;
     boot(): Promise<void>;
     bootInternal(): Promise<void>;
+    /**
+     * Native clear: start a new conversation in the SAME browser and profile
+     * (chat-web clicks the provider's "new chat" control, falling back to
+     * navigating home — both land on an empty chat), so no Chromium relaunch and
+     * no re-login. The old conversation stays in the provider's account.
+     *
+     * The new `/c/{uuid}` only exists after the next reply, so we drop back to a
+     * synthetic id until then — `ensureSessionInfo()` reports `sessionIdDeferred`
+     * for exactly this window.
+     */
+    runClear(): Promise<{
+        clear: {
+            status: string;
+        };
+        usage: null;
+        metadata: {};
+    }>;
     /**
      * Adopt the provider-side conversation id (ChatGPT /c/{uuid} or
      * equivalent) as our canonical sessionId, update sessionInfo, and emit

package/dist/providers/chat-web-session.js

@@ -212,7 +212,7 @@ export class ChatWebSession extends EventEmitter {
                 ? { ready: true, command: this.providerConversationUrl() }
                 : null,
             currentTurnStatus: this.getCurrentTurnStatus(),
-            capabilities: { media: PROVIDER_MEDIA_CAPABILITIES[CHAT_WEB_SESSION_VARIANT] },
+            capabilities: { clear: true, media: PROVIDER_MEDIA_CAPABILITIES[CHAT_WEB_SESSION_VARIANT] },
             chatWebProvider: this.chatWebProvider,
             providerConversationId: this.providerConversationId,
             providerUrl: this.providerConversationUrl(),
@@ -355,6 +355,49 @@ export class ChatWebSession extends EventEmitter {
         this.trace(`session ready provider=${this.chatWebProvider} id=${this.sessionId}`);
         this.emit("session", this.getSessionInfo());
     }
+    /**
+     * Native clear: start a new conversation in the SAME browser and profile
+     * (chat-web clicks the provider's "new chat" control, falling back to
+     * navigating home — both land on an empty chat), so no Chromium relaunch and
+     * no re-login. The old conversation stays in the provider's account.
+     *
+     * The new `/c/{uuid}` only exists after the next reply, so we drop back to a
+     * synthetic id until then — `ensureSessionInfo()` reports `sessionIdDeferred`
+     * for exactly this window.
+     */
+    async runClear() {
+        if (this.closeRequested) {
+            throw this.createSessionClosedError();
+        }
+        if (this.currentTurn) {
+            const error = new Error("chat-web turn already in progress");
+            error.reason = "turn_already_running";
+            throw error;
+        }
+        // Nothing has been said yet — fire boots the browser at announce time, so
+        // "booted" alone does not mean there is a conversation to walk away from.
+        if (!this.providerConversationId && this.history.length === 0) {
+            return { clear: { status: "noop" }, usage: null, metadata: {} };
+        }
+        await this.boot();
+        if (typeof this.chatSession?.newChat !== "function") {
+            throw new Error(`chat-web provider "${this.chatWebProvider}" cannot start a new chat`);
+        }
+        await this.chatSession.newChat();
+        this.providerConversationId = undefined;
+        this.sessionId = `chat-web-${this.chatWebProvider}-${Date.now().toString(36)}`;
+        this.sessionInfo = {
+            ...(this.sessionInfo || {}),
+            backend: this.backend,
+            sessionId: this.sessionId,
+            providerConversationId: undefined,
+            providerUrl: undefined,
+        };
+        this.history = [];
+        this.emit("session", this.getSessionInfo());
+        // No id to report: the provider mints one on the next reply.
+        return { clear: { status: "cleared" }, usage: null, metadata: {} };
+    }
     /**
      * Adopt the provider-side conversation id (ChatGPT /c/{uuid} or
      * equivalent) as our canonical sessionId, update sessionInfo, and emit

package/dist/providers/claude-agent-sdk-session.d.ts

@@ -10,6 +10,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
     static capabilities: Readonly<{
         goal: true;
         compact: true;
+        clear: true;
         media: Readonly<{
             image: "native";
         }>;
@@ -18,6 +19,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
     getCapabilities(): {
         goal: true;
         compact: true;
+        clear: true;
         media: Readonly<{
             image: "native";
         }>;
@@ -47,6 +49,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
         suppressReply: boolean;
         compactMetadata: null;
         compactError: string;
+        conversationReset: string;
         emittedAssistantMessage: boolean;
         fullText: string;
         items: never[];
@@ -95,6 +98,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
         capabilities: {
             goal: true;
             compact: true;
+            clear: true;
             media: Readonly<{
                 image: "native";
             }>;
@@ -175,6 +179,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
         metadata?: undefined;
         compactMetadata?: undefined;
         compactError?: undefined;
+        conversationReset?: undefined;
     } | {
         text: any;
         usage: any;
@@ -190,6 +195,7 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
         };
         compactMetadata: undefined;
         compactError: string | undefined;
+        conversationReset: string | undefined;
     }>;
     /**
      * Trigger Claude's native `/goal` slash command. Implemented by sending the
@@ -228,6 +234,34 @@ export class ClaudeAgentSdkSession extends EventEmitter<[never]> {
     runCompact(request?: import("../shared.js").CompactRequest, { onProgress }?: {
         onProgress?: Function;
     }): Promise<import("../shared.js").CompactResult>;
+    /**
+     * Native `/clear`: the CLI handles the slash command itself and continues on
+     * a new session id, so the process stays up and only the context is dropped.
+     * A session id that did NOT move means the command was not handled natively.
+     */
+    runClear(request?: {}, { onProgress }?: {
+        onProgress?: null | undefined;
+    }): Promise<{
+        clear: {
+            status: string;
+            sessionId?: undefined;
+        };
+        usage: null;
+        metadata: {};
+    } | {
+        clear: {
+            status: string;
+            sessionId: any;
+        };
+        usage: any;
+        metadata: {
+            source: string;
+            sessionId: any;
+            totalCostUsd: number | undefined;
+            modelUsage: any;
+            structuredOutput: any;
+        } | undefined;
+    }>;
     close(): Promise<void>;
 }
 import { EventEmitter } from "node:events";

package/dist/providers/claude-agent-sdk-session.js

@@ -234,6 +234,7 @@ export class ClaudeAgentSdkSession extends EventEmitter {
     static capabilities = Object.freeze({
         goal: true,
         compact: true,
+        clear: true,
         media: PROVIDER_MEDIA_CAPABILITIES[CLAUDE_PROVIDER_VARIANT],
     });
     getCapabilities() {
@@ -835,6 +836,12 @@ export class ClaudeAgentSdkSession extends EventEmitter {
                     }
                 }
                 return;
+            case "conversation_reset":
+                // Emitted by /clear (and other fresh-session flows): the CLI mounted a
+                // new transcript, so this is the authoritative "context cleared" signal.
+                currentTurn.conversationReset = normalizeText(message.new_conversation_id) || "";
+                this.updateSessionInfo(currentTurn.conversationReset);
+                return;
             case "rate_limit_event":
                 this.updateSessionInfo(message.session_id || message.sessionId);
                 this.rateLimitInfo =
@@ -911,6 +918,7 @@ export class ClaudeAgentSdkSession extends EventEmitter {
             suppressReply,
             compactMetadata: null,
             compactError: "",
+            conversationReset: "",
             emittedAssistantMessage: false,
             fullText: "",
             items: [],
@@ -1014,6 +1022,7 @@ export class ClaudeAgentSdkSession extends EventEmitter {
                 },
                 compactMetadata: currentTurn.compactMetadata || undefined,
                 compactError: currentTurn.compactError || undefined,
+                conversationReset: currentTurn.conversationReset || undefined,
             };
         }
         catch (error) {
@@ -1202,6 +1211,30 @@ export class ClaudeAgentSdkSession extends EventEmitter {
             metadata: turnResult.metadata,
         };
     }
+    /**
+     * Native `/clear`: the CLI handles the slash command itself and continues on
+     * a new session id, so the process stays up and only the context is dropped.
+     * A session id that did NOT move means the command was not handled natively.
+     */
+    async runClear(request = {}, { onProgress = null } = {}) {
+        if (!this.sessionId || this.pendingHistorySeed) {
+            return { clear: { status: "noop" }, usage: null, metadata: {} };
+        }
+        const previousSessionId = this.sessionId;
+        const turnResult = await this.runTurn("/clear", { onProgress, suppressReply: true });
+        const cleared = Boolean(turnResult.conversationReset || (this.sessionId && this.sessionId !== previousSessionId));
+        if (cleared) {
+            this.history = [];
+        }
+        return {
+            clear: {
+                status: cleared ? "cleared" : "noop",
+                sessionId: cleared ? this.sessionId : undefined,
+            },
+            usage: turnResult.usage,
+            metadata: turnResult.metadata,
+        };
+    }
     async close() {
         if (this.closed) {
             return;

package/dist/providers/codex-app-server-session.d.ts

@@ -13,6 +13,7 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     backend: string;
     options: {};
     logger: any;
+    traceReplyLatency: boolean;
     cwd: any;
     resumeSessionId: any;
     sessionId: any;
@@ -31,13 +32,26 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     nativeSessionId: string;
     rateLimits: any;
     tokenUsage: any;
-    turnTokenBaseline: number | null;
+    turnTokenBaseline: {
+        totalTokens: number;
+        inputTokens: number;
+        cachedInputTokens: number;
+    } | {
+        totalTokens: number;
+        inputTokens?: undefined;
+        cachedInputTokens?: undefined;
+    } | {
+        inputTokens?: number | undefined;
+        cachedInputTokens?: number | undefined;
+        totalTokens: number;
+    } | null;
     turnTokensSeen: boolean;
     currentTurnStatus: any;
     currentTurnActivityAt: number;
     now: any;
     turnDeadlineMs: any;
     currentTurn: {
+        startedAt: number;
         turnId: string;
         fullText: string;
         activeAssistantMessageId: string;
@@ -132,6 +146,13 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     markTurnStartedStatus(): void;
     failPendingTurnStart(error: any): Promise<void>;
     boot(): Promise<void>;
+    buildThreadParams(): {
+        cwd: any;
+        approvalPolicy: string;
+        sandbox: string;
+        personality: string;
+        ephemeral: boolean;
+    };
     bootInternal(): Promise<void>;
     applyThreadInfo(payload: any, { resumeReady }?: {
         resumeReady?: boolean | undefined;
@@ -140,10 +161,11 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     /** Start counting a turn's tokens from the thread total known right now. */
     beginTurnTokenAccounting(): void;
     /**
-     * Thread token usage plus `turnTotalTokens`: tokens spent since the current
-     * turn (or goal) started. Codex only reports thread-cumulative totals, and
-     * only when a response completes, so a turn that ended before any response
-     * did has unknown usage.
+     * Thread token usage plus `turnTotalTokens` (and its `turnInputTokens` /
+     * `turnCachedInputTokens` split): tokens spent since the current turn (or
+     * goal) started. Codex only reports thread-cumulative totals, and only when
+     * a response completes, so a turn that ended before any response did has
+     * unknown usage.
      */
     snapshotTokenUsage(): any;
     resolveContextUsagePercent(): number | undefined;
@@ -188,6 +210,7 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
     }): Promise<void>;
     emitAssistantMessage(text: any): Promise<void>;
     finalizeActiveAssistantMessage(currentTurn?: {
+        startedAt: number;
         turnId: string;
         fullText: string;
         activeAssistantMessageId: string;
@@ -228,6 +251,7 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         useInitialImages?: boolean | undefined;
     }): string;
     getCurrentTurn(): {
+        startedAt: number;
         turnId: string;
         fullText: string;
         activeAssistantMessageId: string;
@@ -252,12 +276,21 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         goalMode: boolean;
     } | null;
     ensureCurrentTurn(params: any): {
+        startedAt: number;
         turnId: string;
         fullText: string;
         activeAssistantMessageId: string;
         activeAssistantMessageText: string;
         resolve: null;
         reject: null;
+    } | {
+        turnId: string;
+        fullText: string;
+        activeAssistantMessageId: string;
+        activeAssistantMessageText: string;
+        resolve: null;
+        reject: null;
+        suppressReply: boolean;
     } | {
         turnId: string;
         fullText: string;
@@ -287,7 +320,44 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
      * @param {import("../shared.js").CompactRequest} [request]
      * @returns {Promise<import("../shared.js").CompactResult>}
      */
-    runCompact(request?: import("../shared.js").CompactRequest): Promise<import("../shared.js").CompactResult>;
+    /**
+     * Native clear: start a fresh thread on the SAME app-server connection. The
+     * process, transport and model config stay up; only the conversation is
+     * replaced, so the next turn runs against an empty thread.
+     */
+    runClear(): Promise<{
+        clear: {
+            status: string;
+            sessionId?: undefined;
+        };
+        usage: null;
+        metadata: {};
+    } | {
+        clear: {
+            status: string;
+            sessionId: any;
+        };
+        usage: null;
+        metadata: {};
+    }>;
+    runCompact(request?: {}): Promise<{
+        compact: {
+            status: string;
+            instructionsApplied: boolean;
+        };
+        usage: null;
+        metadata: {};
+    } | {
+        compact: {
+            status: string;
+            instructionsApplied: boolean;
+        };
+        usage: any;
+        metadata: {
+            source: string;
+            threadId: any;
+        };
+    }>;
     /**
      * Normalize a goal payload from a codex `thread/goal/*` notification into
      * the cross-layer {@link GoalState} shape.