@kaoruisaac/pedelec 0.2.11 → 0.3.0

package/dist/index.js

@@ -1,6 +1,8 @@
 import { PEDELEC_EXTENSION_ID } from "./extension-id.js";
 import { SDK_VERSION } from "./version.generated.js";
 const SDK_EXTERNAL_PORT_NAME = "pedelec-sdk-external";
+const PAGE_ACTIVITY_MESSAGE_TYPE = "page_activity";
+const SDK_HELLO_MESSAGE_TYPE = "sdk_hello";
 const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
 function normalizeListAssetsResponse(response) {
     if (!response || typeof response !== "object" || Array.isArray(response))
@@ -124,6 +126,8 @@ export class Pedelec {
     lastSeqBySession = new Map();
     nextRequestNumber = 1;
     port = null;
+    pageActivityListenersAttached = false;
+    lastReportedPageActive = null;
     constructor(options = {}) {
         this.pageWindow = typeof window === "undefined" ? null : window;
         this.channelId = createChannelId();
@@ -131,6 +135,7 @@ export class Pedelec {
         if (!this.pageWindow) {
             return;
         }
+        this.attachPageActivityListeners();
         this.connectExtension();
     }
     async createSession(input = {}) {
@@ -141,18 +146,18 @@ export class Pedelec {
                 provider: resolvedInput.provider,
                 effortLevel: resolvedInput.effortLevel,
                 skills: resolvedInput.skills,
-                sandbox: resolvedInput.sandbox,
+                workspace: resolvedInput.workspace,
                 autoEndOnDisconnect: resolvedInput.autoEndOnDisconnect,
             },
         });
         if (!result.sessionId) {
             throw makeError("SDK_PROTOCOL_ERROR", "create_session response did not include sessionId");
         }
-        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.effortLevel, resolvedInput.inlineToolHandlers);
+        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.effortLevel, resolvedInput.inlineToolHandlers, resolvedInput.autoEndOnDisconnect);
     }
-    async sandboxFolderPicker() {
-        const result = await this.requestWithOptions("pick_sandbox_folder", {}, { timeoutMs: null });
-        return normalizeSandboxFolderPickerResponse(result);
+    async workspaceFolderPicker() {
+        const result = await this.requestWithOptions("pick_workspace_folder", {}, { timeoutMs: null });
+        return normalizeWorkspaceFolderPickerResponse(result);
     }
     async listProviders() {
         return normalizeProviderInfoList(await this.request("list_providers"));
@@ -182,13 +187,27 @@ export class Pedelec {
         if (!sessionId?.trim()) {
             throw makeError("INVALID_INPUT", "sessionId is required");
         }
-        const result = await this.request("resume_session", {
-            sessionId,
-        });
-        if (!result.sessionId) {
-            throw makeError("SDK_PROTOCOL_ERROR", "resume_session response did not include sessionId");
+        const existing = this.sessions.get(sessionId);
+        const session = existing && !existing.isTransportDetached()
+            ? existing
+            : this.registerSession(sessionId, "", undefined, new Map(), false);
+        try {
+            const result = await this.request("resume_session", {
+                sessionId,
+            });
+            if (!result.sessionId) {
+                throw makeError("SDK_PROTOCOL_ERROR", "resume_session response did not include sessionId");
+            }
+            if (typeof result.autoEndOnDisconnect === "boolean") {
+                session.setAutoEndOnDisconnect(result.autoEndOnDisconnect);
+            }
+            return session;
+        }
+        catch (error) {
+            if (session !== existing)
+                this.unregisterSession(sessionId);
+            throw error;
         }
-        return this.registerSession(result.sessionId, "", undefined);
     }
     request(type, payload = {}) {
         return this.requestWithOptions(type, payload);
@@ -245,6 +264,76 @@ export class Pedelec {
         this.sessions.delete(sessionId);
         this.lastSeqBySession.delete(sessionId);
     }
+    /** @internal */
+    registerExistingSession(session) {
+        this.sessions.set(session.sessionId, session);
+    }
+    /** @internal */
+    isSessionRegistered(sessionId, session) {
+        return this.sessions.get(sessionId) === session;
+    }
+    attachPageActivityListeners() {
+        if (this.pageActivityListenersAttached || !this.pageWindow)
+            return;
+        this.pageActivityListenersAttached = true;
+        this.pageWindow.addEventListener("focus", () => {
+            if (!this.isDocumentHidden())
+                this.reportPageActivity(true, { force: true });
+        });
+        this.pageWindow.document?.addEventListener("visibilitychange", () => {
+            if (this.isDocumentHidden()) {
+                this.reportPageActivity(false);
+                return;
+            }
+            if (this.isDocumentFocused())
+                this.reportPageActivity(true);
+        });
+    }
+    isDocumentHidden() {
+        const doc = this.pageWindow?.document;
+        if (!doc)
+            return true;
+        if (typeof doc.hidden === "boolean")
+            return doc.hidden;
+        return doc.visibilityState === "hidden";
+    }
+    isDocumentFocused() {
+        const doc = this.pageWindow?.document;
+        if (!doc || typeof doc.hasFocus !== "function")
+            return false;
+        try {
+            return doc.hasFocus();
+        }
+        catch (_err) {
+            return false;
+        }
+    }
+    isPageForegroundActive() {
+        return !this.isDocumentHidden() && this.isDocumentFocused();
+    }
+    postSdkHello(port) {
+        try {
+            port.postMessage({ type: SDK_HELLO_MESSAGE_TYPE, sdkVersion: SDK_VERSION });
+        }
+        catch (err) {
+            const error = normalizeError(err, "EXTENSION_DISCONNECTED", "Pedelec extension disconnected.");
+            this.handleDisconnect(port, error);
+        }
+    }
+    reportPageActivity(active, options = {}) {
+        if (!this.port)
+            return;
+        if (!options.force && this.lastReportedPageActive === active)
+            return;
+        try {
+            this.port.postMessage({ type: PAGE_ACTIVITY_MESSAGE_TYPE, active });
+            this.lastReportedPageActive = active;
+        }
+        catch (err) {
+            const error = normalizeError(err, "EXTENSION_DISCONNECTED", "Pedelec extension disconnected.");
+            this.handleDisconnect(this.port, error);
+        }
+    }
     resolveCreateSessionInput(input) {
         const raw = (input ?? {});
         const provider = typeof raw.provider === "string" ? raw.provider.trim() : "";
@@ -258,15 +347,15 @@ export class Pedelec {
         }
         const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
         const normalizedSkills = normalizeSkillsInput(raw.skills);
-        const sandbox = normalizeCreateSessionSandboxInput(raw.sandbox);
+        const workspace = normalizeCreateSessionWorkspaceInput(raw.workspace);
         if (!hasProvider) {
-            return this.resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, sandbox, autoEndOnDisconnect);
+            return this.resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, workspace, autoEndOnDisconnect);
         }
         return {
             provider: provider,
             effortLevel,
             skills: normalizedSkills.manifest,
-            sandbox,
+            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             autoEndOnDisconnect,
         };
@@ -323,7 +412,7 @@ export class Pedelec {
             };
         }
     }
-    async resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, sandbox, autoEndOnDisconnect) {
+    async resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, workspace, autoEndOnDisconnect) {
         const settings = await this.getSettings();
         if (!settings.defaultProvider) {
             throw makeError("DEFAULT_PROVIDER_NOT_SET", "Default provider is not set. Open the Pedelec desktop app Settings page and choose a default provider.");
@@ -333,7 +422,7 @@ export class Pedelec {
             provider: settings.defaultProvider,
             effortLevel,
             skills: normalizedSkills.manifest,
-            sandbox,
+            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             autoEndOnDisconnect,
         };
@@ -345,13 +434,13 @@ export class Pedelec {
             throw makeError("DEFAULT_PROVIDER_UNAVAILABLE", "Default provider is not currently available. Open the Pedelec desktop app Settings page and choose an available provider.", { provider });
         }
     }
-    registerSession(sessionId, provider, effortLevel, inlineToolHandlers = new Map()) {
+    registerSession(sessionId, provider, effortLevel, inlineToolHandlers = new Map(), autoEndOnDisconnect = false) {
         const existing = this.sessions.get(sessionId);
         if (existing && !existing.isTransportDetached()) {
             existing.replaceInlineToolHandlers(inlineToolHandlers);
             return existing;
         }
-        const session = new PedelecSession(this, sessionId, provider, effortLevel, inlineToolHandlers);
+        const session = new PedelecSession(this, sessionId, provider, effortLevel, inlineToolHandlers, autoEndOnDisconnect);
         this.sessions.set(sessionId, session);
         return session;
     }
@@ -370,10 +459,13 @@ export class Pedelec {
             port.onMessage.addListener((message) => this.handlePortMessage(port, message));
             port.onDisconnect.addListener(() => this.handleDisconnect(port));
             this.port = port;
+            this.postSdkHello(port);
+            this.reportPageActivity(this.isPageForegroundActive(), { force: true });
             return port;
         }
         catch (err) {
             this.port = null;
+            this.lastReportedPageActive = null;
             throw normalizeError(err, "EXTENSION_UNAVAILABLE", "Pedelec extension is unavailable.");
         }
     }
@@ -398,6 +490,22 @@ export class Pedelec {
             this.handleResponse(message);
             return;
         }
+        if (message.type === "session_snapshot") {
+            if (message.sessionId) {
+                const latestSeq = message.snapshot?.latestSeq;
+                if (typeof latestSeq === "number") {
+                    const current = this.lastSeqBySession.get(message.sessionId);
+                    if (current === undefined || latestSeq > current) {
+                        this.lastSeqBySession.set(message.sessionId, latestSeq);
+                    }
+                }
+                this.sessions.get(message.sessionId)?.handleSnapshot(message.snapshot, {
+                    source: "core",
+                    eventReceivedAt: Date.now(),
+                });
+            }
+            return;
+        }
         if (isSessionEvent(message) && this.isNewEvent(message)) {
             const eventReceivedAt = Date.now();
             if (message.sessionId) {
@@ -441,6 +549,7 @@ export class Pedelec {
         const runtime = globalThis.chrome?.runtime;
         const error = normalizeError(disconnectError ?? runtime?.lastError, "EXTENSION_DISCONNECTED", "Pedelec extension disconnected.");
         this.port = null;
+        this.lastReportedPageActive = null;
         this.invalidateSessions(error);
         for (const [requestId, pending] of this.pendingRequests) {
             if (pending.port !== port)
@@ -462,18 +571,18 @@ export class Pedelec {
         }
     }
 }
-function normalizeCreateSessionSandboxInput(value) {
+function normalizeCreateSessionWorkspaceInput(value) {
     if (value === undefined)
         return undefined;
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw makeError("INVALID_INPUT", "sandbox must be an object");
+        throw makeError("INVALID_INPUT", "workspace must be an object");
     }
     const path = value.path;
     if (typeof path !== "string") {
-        throw makeError("INVALID_INPUT", "sandbox.path must be a string");
+        throw makeError("INVALID_INPUT", "workspace.path must be a string");
     }
     if (path.trim().length === 0) {
-        throw makeError("INVALID_INPUT", "sandbox.path must not be empty");
+        throw makeError("INVALID_INPUT", "workspace.path must not be empty");
     }
     return { path };
 }
@@ -483,34 +592,43 @@ export class PedelecSession {
     provider;
     effortLevel;
     sessionCreatedAt = Date.now();
+    usage = { totalTokens: undefined };
     status = "idle";
-    pendingSend = null;
-    pendingPrepare = null;
+    pendingOperation = null;
     preparePromise = null;
     uploadPromise = null;
+    reactivationPromise = null;
     ending = false;
     prepared = false;
+    autoEndOnDisconnect;
     activeTurn = null;
     transportDetached = false;
     genericToolHandler = null;
     inlineToolHandlers = new Map();
     namedToolHandlers = new Map();
     chatHandlers = new Set();
+    chatDeltaHandlers = new Set();
     errorHandlers = new Set();
     statusHandlers = new Set();
     endedHandlers = new Set();
-    constructor(client, sessionId, provider, effortLevel, inlineToolHandlers = new Map()) {
+    recoveredToolCalls = new Map();
+    handledToolRequestIds = new Set();
+    authoritativePendingToolRequest = undefined;
+    constructor(client, sessionId, provider, effortLevel, inlineToolHandlers = new Map(), autoEndOnDisconnect = false) {
         this.client = client;
         this.sessionId = sessionId;
         this.provider = provider;
         this.effortLevel = effortLevel;
         this.inlineToolHandlers = new Map(inlineToolHandlers);
+        this.autoEndOnDisconnect = autoEndOnDisconnect;
     }
     prepare() {
         if (this.transportDetached || this.status === "ended") {
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
         }
-        if (this.pendingSend) {
+        if (this.pendingOperation?.turn.kind === "user" ||
+            (this.activeTurn && this.activeTurn.kind !== "prepare") ||
+            this.activeTurn?.external) {
             return Promise.reject(makeError("SESSION_BUSY", "session is already running", { sessionId: this.sessionId }));
         }
         if (this.prepared) {
@@ -520,24 +638,32 @@ export class PedelecSession {
             return this.preparePromise;
         }
         const turn = createTurn("prepare");
+        const priorStatus = this.status;
         this.activeTurn = turn;
         this.setStatus("running", { source: "sdk" });
-        const donePromise = new Promise((resolve, reject) => {
-            this.pendingPrepare = { resolve, reject };
+        const operationPromise = new Promise((resolve, reject) => {
+            this.pendingOperation = {
+                turn,
+                resolve,
+                reject,
+                priorStatus,
+                requestSettled: false,
+            };
         });
-        const requestPromise = this.client
+        void this.client
             .request("prepare_session", {
             sessionId: this.sessionId,
+            operationId: turn.turnId,
         })
-            .catch((err) => {
+            .then(() => {
+            this.markOperationRequestSettled(turn);
+        }, (err) => {
             const error = normalizeError(err, "PREPARE_FAILED", "prepare failed");
             if (!this.transportDetached)
                 this.emitError(error, { source: "sdk" });
-            this.clearPendingPrepare();
-            this.finishActiveTurn(turn);
-            throw error;
+            this.failOperationFromRequest(turn, error);
         });
-        this.preparePromise = Promise.all([requestPromise, donePromise])
+        this.preparePromise = operationPromise
             .then(() => {
             this.prepared = true;
         })
@@ -558,34 +684,46 @@ export class PedelecSession {
         if (this.transportDetached || this.status === "ended") {
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
         }
-        if (this.pendingSend || this.pendingPrepare) {
+        if (this.pendingOperation || this.activeTurn) {
             return Promise.reject(makeError("SESSION_BUSY", "session is already running", { sessionId: this.sessionId }));
         }
         const turn = createTurn("user");
+        const priorStatus = this.status;
         this.activeTurn = turn;
         this.setStatus("running", { source: "sdk" });
-        const donePromise = new Promise((resolve, reject) => {
-            this.pendingSend = { resolve, reject };
+        const operationPromise = new Promise((resolve, reject) => {
+            this.pendingOperation = {
+                turn,
+                resolve,
+                reject,
+                priorStatus,
+                requestSettled: false,
+            };
         });
-        const requestPromise = this.client
+        void this.client
             .request("send_text", {
             sessionId: this.sessionId,
             text,
+            operationId: turn.turnId,
         })
-            .catch((err) => {
+            .then(() => {
+            this.markOperationRequestSettled(turn);
+        }, (err) => {
             const error = normalizeError(err, "SEND_TEXT_FAILED", "sendText failed");
             if (!this.transportDetached)
                 this.emitError(error, { source: "sdk" });
-            this.clearPendingSend();
-            this.finishActiveTurn(turn);
-            throw error;
+            this.failOperationFromRequest(turn, error);
         });
-        return Promise.all([requestPromise, donePromise]).then(() => undefined);
+        return operationPromise;
     }
     onChat(handler) {
         this.chatHandlers.add(handler);
         return () => this.chatHandlers.delete(handler);
     }
+    onChatDelta(handler) {
+        this.chatDeltaHandlers.add(handler);
+        return () => this.chatDeltaHandlers.delete(handler);
+    }
     onTool(toolNameOrHandler, maybeHandler) {
         if (typeof toolNameOrHandler === "string") {
             const toolName = toolNameOrHandler;
@@ -596,6 +734,7 @@ export class PedelecSession {
                 throw makeError("INVALID_INPUT", "tool handler must be a function", { toolName });
             }
             this.namedToolHandlers.set(toolName, maybeHandler);
+            void this.drainRecoveredToolCalls();
             return () => {
                 if (this.namedToolHandlers.get(toolName) === maybeHandler) {
                     this.namedToolHandlers.delete(toolName);
@@ -604,6 +743,7 @@ export class PedelecSession {
         }
         const handler = toolNameOrHandler;
         this.genericToolHandler = handler;
+        void this.drainRecoveredToolCalls();
         return () => {
             if (this.genericToolHandler === handler) {
                 this.genericToolHandler = null;
@@ -743,9 +883,73 @@ export class PedelecSession {
         this.markEnded({ source: "sdk" });
         this.client.unregisterSession(this.sessionId);
     }
+    resume() {
+        if (this.transportDetached) {
+            return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
+        }
+        if (this.reactivationPromise)
+            return this.reactivationPromise;
+        if (this.status !== "ended")
+            return Promise.resolve();
+        const wasRegistered = this.client.isSessionRegistered(this.sessionId, this);
+        const promise = (async () => {
+            if (!wasRegistered) {
+                // end() intentionally removed the handle from the registry. Put the
+                // exact same object back before the ended snapshot can arrive.
+                this.client.registerExistingSession(this);
+            }
+            try {
+                const result = await this.client.request("reactivate_session", {
+                    sessionId: this.sessionId,
+                    autoEndOnDisconnect: this.autoEndOnDisconnect,
+                });
+                if (result?.sessionId !== this.sessionId) {
+                    throw makeError("SDK_PROTOCOL_ERROR", "reactivate_session response did not include sessionId");
+                }
+                if (this.status !== "idle") {
+                    throw makeError("SDK_PROTOCOL_ERROR", "reactivate_session resolved before the authoritative idle snapshot", { sessionId: this.sessionId });
+                }
+                this.ending = false;
+            }
+            catch (err) {
+                const error = normalizeError(err, "SESSION_RESUME_FAILED", "session resume failed");
+                if (!this.transportDetached)
+                    this.emitError(error, { source: "sdk" });
+                if (!wasRegistered && isDeterministicResumeError(error) && this.status !== "idle") {
+                    this.client.unregisterSession(this.sessionId);
+                }
+                throw error;
+            }
+        })();
+        const guardedPromise = promise.finally(() => {
+            if (this.reactivationPromise === guardedPromise)
+                this.reactivationPromise = null;
+        });
+        this.reactivationPromise = guardedPromise;
+        return guardedPromise;
+    }
+    /** @internal */
+    setAutoEndOnDisconnect(autoEndOnDisconnect) {
+        this.autoEndOnDisconnect = autoEndOnDisconnect;
+    }
     handleEvent(event, meta = { source: "sdk" }) {
+        if (event.type === "usage_updated") {
+            this.updateUsage(event.totalTokens);
+            return;
+        }
         if (event.type === "chat_delta") {
-            const turn = this.requireActiveTurn("chat_delta", meta);
+            const turn = this.requireOperationTurn(event.operationId, "chat_delta", meta);
+            if (!turn)
+                return;
+            if (turn.kind === "prepare")
+                return;
+            for (const handler of this.chatDeltaHandlers) {
+                handler(event.text, this.createChatDeltaContext(meta, turn));
+            }
+            return;
+        }
+        if (event.type === "chat_message") {
+            const turn = this.requireOperationTurn(event.operationId, "chat_message", meta);
             if (!turn)
                 return;
             if (turn.kind === "prepare")
@@ -756,44 +960,109 @@ export class PedelecSession {
             return;
         }
         if (event.type === "status_changed") {
+            if (event.operationId && !this.matchesActiveOperation(event.operationId))
+                return;
+            if (!event.operationId && this.activeTurn)
+                return;
             this.setStatus(event.status, meta);
-            if (event.status === "idle") {
-                this.resolveActivePending();
-            }
-            else if (event.status === "ended") {
+            if (event.status === "idle")
+                this.ending = false;
+            if (event.status === "ended") {
                 this.markEnded(meta);
             }
             else if (event.status === "error") {
                 const error = makeError("SESSION_ERROR", "session entered error status", { sessionId: this.sessionId });
                 this.emitError(error, meta);
-                this.rejectActivePending(error);
             }
             return;
         }
         if (event.type === "tool_call") {
-            const turn = this.requireActiveTurn("tool_call", meta);
+            const turn = this.requireOperationTurn(event.operationId, "tool_call", meta);
             if (!turn)
                 return;
+            this.authoritativePendingToolRequest = {
+                operationId: event.operationId,
+                requestId: event.toolRequestId,
+            };
             this.setStatus("waiting_tool_result", meta);
-            this.handleToolCall(event, meta, turn);
+            if (this.recoveredToolCalls.has(event.toolRequestId)) {
+                this.recoveredToolCalls.delete(event.toolRequestId);
+            }
+            if (turn.external && !this.hasToolHandler(event.tool)) {
+                this.recoveredToolCalls.set(event.toolRequestId, event);
+                return;
+            }
+            void this.handleToolCallOnce(event, meta, turn);
             return;
         }
-        if (event.type === "done") {
-            this.setStatus("idle", meta);
-            this.resolveActivePending();
+        if (event.type === "operation_completed") {
+            if (!this.matchesActiveOperation(event.operationId))
+                return;
+            if (this.activeTurn?.kind !== event.operationKind)
+                return;
+            this.authoritativePendingToolRequest = null;
+            this.setStatus(event.success ? "idle" : event.operationKind === "prepare" ? "idle" : "error", meta);
+            this.completeOperation(this.activeTurn, event.success, event.error);
             return;
         }
         if (event.type === "error") {
-            this.setStatus("error", meta);
+            if (event.operationId && !this.matchesActiveOperation(event.operationId))
+                return;
             const error = normalizeError(event.error, "SESSION_ERROR", "session error");
             this.emitError(error, meta);
-            this.rejectActivePending(error);
+            if (!event.operationId)
+                this.setStatus("error", meta);
             return;
         }
         if (event.type === "ended") {
             this.markEnded(meta);
         }
     }
+    /** @internal */
+    handleSnapshot(snapshot, meta = { source: "core" }) {
+        if (!snapshot || snapshot.threadId !== this.sessionId)
+            return;
+        if (snapshot.usage)
+            this.updateUsage(snapshot.usage.totalTokens);
+        if (snapshot.status === "idle")
+            this.ending = false;
+        const active = snapshot.activeOperation;
+        const pending = this.pendingOperation;
+        this.reconcileRecoveredToolCalls(snapshot);
+        if (!pending) {
+            this.setStatus(coreStatusToSdkStatus(snapshot.status), meta);
+            if (active) {
+                this.activeTurn = {
+                    turnId: active.operationId,
+                    turnStartedAt: parseSnapshotTime(active.startedAt),
+                    kind: active.operationKind,
+                    external: true,
+                };
+                this.queueSnapshotTool(snapshot, this.activeTurn);
+            }
+            else if (this.activeTurn?.external) {
+                this.activeTurn = null;
+            }
+            if (snapshot.status === "ended")
+                this.markEnded(meta);
+            return;
+        }
+        if (active?.operationId === pending.turn.turnId && active.operationKind === pending.turn.kind) {
+            this.setStatus(coreStatusToSdkStatus(snapshot.status), meta);
+            this.queueSnapshotTool(snapshot, pending.turn);
+            return;
+        }
+        const completed = snapshot.lastCompletedOperation;
+        if (completed?.operationId === pending.turn.turnId && completed.operationKind === pending.turn.kind) {
+            this.setStatus(completed.success ? "idle" : completed.operationKind === "prepare" ? "idle" : "error", meta);
+            this.completeOperation(pending.turn, completed.success, completed.error);
+            return;
+        }
+        const error = makeError("SDK_LIFECYCLE_SYNC_ERROR", "authoritative session snapshot did not match the active SDK operation", { sessionId: this.sessionId, operationId: pending.turn.turnId });
+        this.emitError(error, { source: "sdk" });
+        this.rejectOperation(pending.turn, error);
+        this.setStatus(coreStatusToSdkStatus(snapshot.status), meta);
+    }
     replaceInlineToolHandlers(handlers) {
         this.inlineToolHandlers = new Map(handlers);
     }
@@ -810,7 +1079,10 @@ export class PedelecSession {
         this.emitError(error, { source: "sdk" });
         this.rejectActivePending(error);
     }
-    async handleToolCall(event, meta, turn) {
+    async handleToolCallOnce(event, meta, turn) {
+        if (this.handledToolRequestIds.has(event.toolRequestId))
+            return;
+        this.handledToolRequestIds.add(event.toolRequestId);
         let result;
         const namedHandler = this.namedToolHandlers.get(event.tool);
         const inlineHandler = this.inlineToolHandlers.get(event.tool);
@@ -851,7 +1123,7 @@ export class PedelecSession {
                 }),
             };
         }
-        if (this.transportDetached)
+        if (this.transportDetached || !this.isAuthoritativeToolRequestCurrent(event))
             return;
         try {
             await this.client.request("submit_tool_result", {
@@ -866,51 +1138,10 @@ export class PedelecSession {
             });
         }
     }
-    resolvePendingSend() {
-        const pending = this.pendingSend;
-        this.pendingSend = null;
-        pending?.resolve();
-        this.finishActiveTurn();
-    }
-    resolvePendingPrepare() {
-        const pending = this.pendingPrepare;
-        this.pendingPrepare = null;
-        pending?.resolve();
-        this.finishActiveTurn();
-    }
-    resolveActivePending() {
-        if (this.activeTurn?.kind === "prepare") {
-            this.resolvePendingPrepare();
-        }
-        else {
-            this.resolvePendingSend();
-        }
-    }
-    rejectPendingSend(error) {
-        const pending = this.pendingSend;
-        this.pendingSend = null;
-        pending?.reject(error);
-        this.finishActiveTurn();
-    }
-    rejectPendingPrepare(error) {
-        const pending = this.pendingPrepare;
-        this.pendingPrepare = null;
-        pending?.reject(error);
-        this.finishActiveTurn();
-    }
     rejectActivePending(error) {
-        if (this.activeTurn?.kind === "prepare") {
-            this.rejectPendingPrepare(error);
-        }
-        else {
-            this.rejectPendingSend(error);
-        }
-    }
-    clearPendingSend() {
-        this.pendingSend = null;
-    }
-    clearPendingPrepare() {
-        this.pendingPrepare = null;
+        const turn = this.activeTurn;
+        if (turn)
+            this.rejectOperation(turn, error);
     }
     markEnded(meta = { source: "sdk" }) {
         const wasEnded = this.status === "ended";
@@ -920,9 +1151,9 @@ export class PedelecSession {
                 handler(this.createEndedContext(meta));
             }
         }
-        this.rejectPendingSend(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
-        this.rejectPendingPrepare(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
-        this.finishActiveTurn();
+        const error = makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId });
+        if (this.activeTurn)
+            this.rejectOperation(this.activeTurn, error);
     }
     emitError(error, meta = { source: "sdk" }) {
         for (const handler of this.errorHandlers) {
@@ -938,14 +1169,140 @@ export class PedelecSession {
             handler(status, this.createStatusContext(status, previousStatus, meta));
         }
     }
-    requireActiveTurn(type, meta) {
-        if (this.activeTurn)
+    requireOperationTurn(operationId, type, meta) {
+        if (operationId && this.activeTurn?.turnId === operationId) {
             return this.activeTurn;
-        this.emitError(makeError("SDK_PROTOCOL_ERROR", `${type} event was received without an active turn`, {
+        }
+        this.emitError(makeError("SDK_PROTOCOL_ERROR", `${type} event did not match the active operation`, {
             sessionId: this.sessionId,
+            operationId,
         }), { source: "sdk", eventReceivedAt: meta.eventReceivedAt });
         return null;
     }
+    updateUsage(totalTokens) {
+        if (!isValidSessionUsageTotalTokens(totalTokens))
+            return;
+        if (this.usage.totalTokens === undefined || totalTokens >= this.usage.totalTokens) {
+            this.usage.totalTokens = totalTokens;
+        }
+    }
+    matchesActiveOperation(operationId) {
+        return this.activeTurn?.turnId === operationId;
+    }
+    markOperationRequestSettled(turn) {
+        const pending = this.pendingOperation;
+        if (!pending || pending.turn.turnId !== turn.turnId)
+            return;
+        pending.requestSettled = true;
+        this.maybeSettleOperation(pending);
+    }
+    failOperationFromRequest(turn, error) {
+        const pending = this.pendingOperation;
+        if (!pending || pending.turn.turnId !== turn.turnId)
+            return;
+        // A semantic terminal may have arrived before the bridge response. Keep the
+        // operation reserved until that response boundary is observed, but never let
+        // a delayed request failure overwrite its matching terminal result.
+        if (pending.completed) {
+            pending.requestSettled = true;
+            this.maybeSettleOperation(pending);
+            return;
+        }
+        this.setStatus(turn.kind === "prepare" || isAdmissionRejection(error) ? pending.priorStatus : "error", { source: "sdk" });
+        this.rejectOperation(turn, error);
+    }
+    completeOperation(turn, success, error) {
+        const pending = this.pendingOperation;
+        if (!pending || pending.turn.turnId !== turn.turnId) {
+            if (this.activeTurn?.turnId === turn.turnId && turn.external)
+                this.finishActiveTurn(turn);
+            return;
+        }
+        pending.completed = { success, error };
+        this.maybeSettleOperation(pending);
+    }
+    maybeSettleOperation(pending) {
+        if (!pending.requestSettled || !pending.completed)
+            return;
+        const turn = pending.turn;
+        this.pendingOperation = null;
+        this.finishActiveTurn(turn);
+        if (pending.completed.success)
+            pending.resolve();
+        else
+            pending.reject(pending.completed.error ?? makeError("SESSION_ERROR", "session operation failed"));
+    }
+    rejectOperation(turn, error) {
+        const pending = this.pendingOperation;
+        if (pending && pending.turn.turnId === turn.turnId) {
+            this.pendingOperation = null;
+            this.finishActiveTurn(turn);
+            pending.reject(error);
+            return;
+        }
+        this.finishActiveTurn(turn);
+    }
+    queueSnapshotTool(snapshot, turn) {
+        const request = snapshot.pendingToolRequest;
+        if (!request || request.operationId !== turn.turnId)
+            return;
+        if (this.handledToolRequestIds.has(request.requestId))
+            return;
+        this.recoveredToolCalls.set(request.requestId, {
+            type: "tool_call",
+            channelId: "",
+            sessionId: this.sessionId,
+            seq: snapshot.latestSeq,
+            operationId: request.operationId,
+            toolRequestId: request.requestId,
+            tool: request.toolName,
+            args: request.args,
+        });
+        void this.drainRecoveredToolCalls();
+    }
+    reconcileRecoveredToolCalls(snapshot) {
+        const active = snapshot.activeOperation;
+        const pending = active && snapshot.pendingToolRequest?.operationId === active.operationId
+            ? snapshot.pendingToolRequest
+            : undefined;
+        this.authoritativePendingToolRequest = pending
+            ? { operationId: pending.operationId, requestId: pending.requestId }
+            : null;
+        for (const [requestId, event] of this.recoveredToolCalls) {
+            if (!active ||
+                !pending ||
+                event.operationId !== active.operationId ||
+                event.toolRequestId !== pending.requestId) {
+                this.recoveredToolCalls.delete(requestId);
+            }
+        }
+    }
+    isAuthoritativeToolRequestCurrent(event) {
+        const pending = this.authoritativePendingToolRequest;
+        if (pending === undefined)
+            return true;
+        if (pending === null)
+            return false;
+        return (pending.operationId === event.operationId &&
+            pending.requestId === event.toolRequestId);
+    }
+    hasToolHandler(toolName) {
+        return this.namedToolHandlers.has(toolName) ||
+            this.inlineToolHandlers.has(toolName) ||
+            this.genericToolHandler !== null;
+    }
+    async drainRecoveredToolCalls() {
+        const turn = this.activeTurn;
+        if (!turn)
+            return;
+        for (const [requestId, event] of Array.from(this.recoveredToolCalls.entries())) {
+            if (event.operationId !== turn.turnId || !this.hasToolHandler(event.tool))
+                continue;
+            this.recoveredToolCalls.delete(requestId);
+            this.setStatus("waiting_tool_result", { source: "core" });
+            await this.handleToolCallOnce(event, { source: "core", eventReceivedAt: Date.now() }, turn);
+        }
+    }
     finishActiveTurn(turn = this.activeTurn) {
         if (!turn || !this.activeTurn)
             return;
@@ -966,6 +1323,16 @@ export class PedelecSession {
         };
     }
     createChatContext(meta, turn) {
+        return {
+            ...this.createBaseContext(meta, turn),
+            type: "chat_message",
+            turnId: turn.turnId,
+            turnStartedAt: turn.turnStartedAt,
+            eventReceivedAt: meta.eventReceivedAt ?? Date.now(),
+            source: "core",
+        };
+    }
+    createChatDeltaContext(meta, turn) {
         return {
             ...this.createBaseContext(meta, turn),
             type: "chat_delta",
@@ -1010,9 +1377,11 @@ export class PedelecSession {
 }
 function isSessionEvent(message) {
     return (message.type === "chat_delta" ||
+        message.type === "chat_message" ||
         message.type === "status_changed" ||
         message.type === "tool_call" ||
-        message.type === "done" ||
+        message.type === "operation_completed" ||
+        message.type === "usage_updated" ||
         message.type === "error" ||
         message.type === "ended");
 }
@@ -1033,21 +1402,21 @@ function normalizePedelecSettings(value) {
     }
     return { defaultProvider: value.defaultProvider };
 }
-function normalizeSandboxFolderPickerResponse(value) {
+function normalizeWorkspaceFolderPickerResponse(value) {
     if (!isPlainObject(value) || !("path" in value)) {
-        throw makeError("SDK_PROTOCOL_ERROR", "pick_sandbox_folder response had an invalid shape");
+        throw makeError("SDK_PROTOCOL_ERROR", "pick_workspace_folder response had an invalid shape");
     }
     const path = value.path;
     if (path === null)
         return null;
     if (typeof path !== "string" || path.length === 0 ||
-        typeof value.isEmptyFolder !== "boolean" || typeof value.hasSandboxConfig !== "boolean") {
-        throw makeError("SDK_PROTOCOL_ERROR", "pick_sandbox_folder response had an invalid shape");
+        typeof value.isEmptyFolder !== "boolean" || typeof value.hasWorkspaceConfig !== "boolean") {
+        throw makeError("SDK_PROTOCOL_ERROR", "pick_workspace_folder response had an invalid shape");
     }
     return {
         path,
         isEmptyFolder: value.isEmptyFolder,
-        hasSandboxConfig: value.hasSandboxConfig,
+        hasWorkspaceConfig: value.hasWorkspaceConfig,
     };
 }
 function normalizeProviderInfoList(value) {
@@ -1081,6 +1450,23 @@ function createTurn(kind = "user") {
         kind,
     };
 }
+function isValidSessionUsageTotalTokens(value) {
+    return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+function coreStatusToSdkStatus(status) {
+    if (status === "waitingToolResult")
+        return "waiting_tool_result";
+    if (status === "starting" || status === "stopping")
+        return "running";
+    if (status === "idle" || status === "running" || status === "ended" || status === "error") {
+        return status;
+    }
+    return "error";
+}
+function parseSnapshotTime(value) {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : Date.now();
+}
 function getCurrentOrigin(pageWindow) {
     const origin = pageWindow?.location?.origin;
     return typeof origin === "string" && origin ? origin : null;
@@ -1088,6 +1474,22 @@ function getCurrentOrigin(pageWindow) {
 function isExtensionUnavailableError(error) {
     return error.code === "EXTENSION_UNAVAILABLE" || error.code === "EXTENSION_DISCONNECTED";
 }
+function isAdmissionRejection(error) {
+    return error.code === "THREAD_BUSY" ||
+        error.code === "THREAD_ENDED" ||
+        error.code === "THREAD_ACCESS_DENIED" ||
+        error.code === "THREAD_NOT_FOUND" ||
+        error.code === "INVALID_INPUT";
+}
+function isDeterministicResumeError(error) {
+    return error.code === "THREAD_BUSY" ||
+        error.code === "THREAD_ENDED" ||
+        error.code === "THREAD_ACCESS_DENIED" ||
+        error.code === "THREAD_NOT_FOUND" ||
+        error.code === "WORKSPACE_OPEN_FAILED" ||
+        error.code === "PROVIDER_COMMAND_FAILED" ||
+        error.code === "INVALID_INPUT";
+}
 function normalizeError(err, fallbackCode, fallbackMessage) {
     if (!err)
         return makeError(fallbackCode, fallbackMessage);