@kaoruisaac/pedelec 0.2.12 → 0.3.0

package/README.md

@@ -121,10 +121,15 @@ const session = await pedelec.createSession({
 });
 
 session.onChat((text) => {
-  // Incremental text stream from the agent.
+  // One completed logical assistant message.
   console.log(text);
 });
 
+session.onChatDelta((delta) => {
+  // Optional best-effort incremental text for live UI.
+  console.log(delta);
+});
+
 session.onStatus((status) => {
   // idle | running | waiting_tool_result | ended | error
   console.log("status", status);
@@ -137,7 +142,19 @@ session.onError((error) => {
 await session.sendText("Please help me analyze the current page state");
 ```
 
-`sendText()` resolves after the current agent response completes. If the session is already handling a previous prompt, the new `sendText()` call is rejected to prevent multiple concurrent requests from running in the same session.
+`sendText()` resolves after Core reports the matching semantic operation as completed. An `idle` status or bridge request response alone does not complete it. If the session is already handling a previous prompt, the new `sendText()` call is rejected to prevent multiple concurrent requests from running in the same session.
+
+## End and resume a session
+
+```ts
+await session.end();
+await session.resume();
+
+console.log(session.getStatus()); // "idle"
+await session.sendText("Continue");
+```
+
+`session.resume()` reactivates the same non-detached handle and Core thread when Core still knows the thread and its recorded workspace still exists. It preserves handlers and session state, does not contact the provider runtime, and leaves provider startup/resume lazy until the next operation. A missing workspace returns `WORKSPACE_OPEN_FAILED`; a thread lost after a Desktop/Core restart returns `THREAD_NOT_FOUND`. `pedelec.resumeSession(sessionId)` is a separate reattachment API: it returns a new handle and does not implicitly revive an ended thread. A transport-detached old handle must use that API.
 
 ## Session assets
 

package/dist/index.d.ts

@@ -142,6 +142,9 @@ export type PedelecError = {
     details?: unknown;
 };
 export type PedelecSessionStatus = "idle" | "running" | "waiting_tool_result" | "ended" | "error";
+export type PedelecSessionUsage = {
+    totalTokens?: number;
+};
 export type PedelecEventContext = {
     sessionId: string;
     provider: string;
@@ -155,6 +158,12 @@ export type PedelecEventContext = {
     source: "core" | "sdk";
 };
 export type ChatEventContext = PedelecEventContext & {
+    type: "chat_message";
+    turnId: string;
+    turnStartedAt: number;
+    eventReceivedAt: number;
+};
+export type ChatDeltaEventContext = PedelecEventContext & {
     type: "chat_delta";
     turnId: string;
     turnStartedAt: number;
@@ -184,31 +193,52 @@ type SessionEvent = {
     channelId: string;
     sessionId: string;
     seq?: number;
+    operationId?: string;
+    text: string;
+} | {
+    type: "chat_message";
+    channelId: string;
+    sessionId: string;
+    seq?: number;
+    operationId?: string;
     text: string;
 } | {
     type: "status_changed";
     channelId: string;
     sessionId: string;
     seq?: number;
+    operationId?: string;
     status: PedelecSessionStatus;
 } | {
     type: "tool_call";
     channelId: string;
     sessionId: string;
     seq?: number;
+    operationId: string;
     toolRequestId: string;
     tool: string;
     args: unknown;
 } | {
-    type: "done";
+    type: "operation_completed";
+    channelId: string;
+    sessionId: string;
+    seq?: number;
+    operationId: string;
+    operationKind: "user" | "prepare";
+    success: boolean;
+    error?: PedelecError;
+} | {
+    type: "usage_updated";
     channelId: string;
     sessionId: string;
     seq?: number;
+    totalTokens: number;
 } | {
     type: "error";
     channelId?: string;
     sessionId?: string;
     seq?: number;
+    operationId?: string;
     error?: PedelecError;
 } | {
     type: "ended";
@@ -216,11 +246,41 @@ type SessionEvent = {
     sessionId: string;
     seq?: number;
 };
+type SessionSnapshot = {
+    threadId: string;
+    status: string;
+    latestSeq: number;
+    usage?: {
+        totalTokens: number;
+    };
+    activeOperation?: {
+        operationId: string;
+        operationKind: "user" | "prepare";
+        startedAt: string;
+    };
+    lastCompletedOperation?: {
+        operationId: string;
+        operationKind: "user" | "prepare";
+        success: boolean;
+        error?: PedelecError;
+        completedAt: string;
+    };
+    pendingToolRequest?: {
+        requestId: string;
+        threadId: string;
+        operationId: string;
+        toolName: string;
+        args: unknown;
+        createdAt: string;
+        timeoutMs: number;
+    };
+};
 type EventDispatchMeta = {
     source: "core" | "sdk";
     eventReceivedAt?: number;
 };
 type ChatHandler = (text: string, ctx: ChatEventContext) => void;
+type ChatDeltaHandler = (text: string, ctx: ChatDeltaEventContext) => void;
 type GenericToolHandler<TToolName extends string = string> = (tool: TToolName, args: unknown, ctx: ToolCallContext) => unknown | Promise<unknown>;
 type ErrorHandler = (error: PedelecError, ctx: ErrorEventContext) => void;
 type StatusHandler = (status: PedelecSessionStatus, ctx: StatusEventContext) => void;
@@ -235,6 +295,8 @@ export declare class Pedelec {
     private readonly lastSeqBySession;
     private nextRequestNumber;
     private port;
+    private pageActivityListenersAttached;
+    private lastReportedPageActive;
     constructor(options?: PedelecOptions);
     createSession(): Promise<PedelecSession<string>>;
     createSession<const TTools extends readonly ToolDefinition[]>(input: CreateSessionInput<TTools>): Promise<PedelecSession<ToolNameOf<TTools>>>;
@@ -246,6 +308,16 @@ export declare class Pedelec {
     request<T>(type: string, payload?: Record<string, unknown>): Promise<T>;
     private requestWithOptions;
     unregisterSession(sessionId: string): void;
+    /** @internal */
+    registerExistingSession(session: PedelecSession<any>): void;
+    /** @internal */
+    isSessionRegistered(sessionId: string, session: PedelecSession<any>): boolean;
+    private attachPageActivityListeners;
+    private isDocumentHidden;
+    private isDocumentFocused;
+    private isPageForegroundActive;
+    private postSdkHello;
+    private reportPageActivity;
     private resolveCreateSessionInput;
     checkAvailability(): Promise<PedelecAvailability>;
     private resolveDefaultCreateSessionInput;
@@ -266,26 +338,33 @@ export declare class PedelecSession<TToolName extends string = string> {
     readonly provider: string;
     readonly effortLevel?: EffortLevel;
     readonly sessionCreatedAt: number;
+    readonly usage: PedelecSessionUsage;
     private status;
-    private pendingSend;
-    private pendingPrepare;
+    private pendingOperation;
     private preparePromise;
     private uploadPromise;
+    private reactivationPromise;
     private ending;
     private prepared;
+    private autoEndOnDisconnect;
     private activeTurn;
     private transportDetached;
     private genericToolHandler;
     private inlineToolHandlers;
     private readonly namedToolHandlers;
     private readonly chatHandlers;
+    private readonly chatDeltaHandlers;
     private readonly errorHandlers;
     private readonly statusHandlers;
     private readonly endedHandlers;
-    constructor(client: Pedelec, sessionId: string, provider: string, effortLevel?: EffortLevel, inlineToolHandlers?: Map<string, ToolSpecificHandler>);
+    private readonly recoveredToolCalls;
+    private readonly handledToolRequestIds;
+    private authoritativePendingToolRequest;
+    constructor(client: Pedelec, sessionId: string, provider: string, effortLevel?: EffortLevel, inlineToolHandlers?: Map<string, ToolSpecificHandler>, autoEndOnDisconnect?: boolean);
     prepare(): Promise<void>;
     sendText(text: string): Promise<void>;
     onChat(handler: ChatHandler): () => void;
+    onChatDelta(handler: ChatDeltaHandler): () => void;
     onTool(handler: GenericToolHandler<TToolName>): () => void;
     onTool<TArgs = unknown, TResult = unknown>(toolName: TToolName, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
     uploadAsset(file: File): Promise<AssetPath>;
@@ -299,28 +378,39 @@ export declare class PedelecSession<TToolName extends string = string> {
     onEnded(handler: EndedHandler): () => void;
     getStatus(): PedelecSessionStatus;
     end(): Promise<void>;
+    resume(): Promise<void>;
+    /** @internal */
+    setAutoEndOnDisconnect(autoEndOnDisconnect: boolean): void;
     handleEvent(event: SessionEvent, meta?: EventDispatchMeta): void;
+    /** @internal */
+    handleSnapshot(snapshot: SessionSnapshot, meta?: EventDispatchMeta): void;
     replaceInlineToolHandlers(handlers: Map<string, ToolSpecificHandler>): void;
     /** @internal */
     isTransportDetached(): boolean;
     /** @internal */
     handleTransportDisconnect(error: PedelecError): void;
-    private handleToolCall;
-    private resolvePendingSend;
-    private resolvePendingPrepare;
-    private resolveActivePending;
-    private rejectPendingSend;
-    private rejectPendingPrepare;
+    private handleToolCallOnce;
     private rejectActivePending;
-    private clearPendingSend;
-    private clearPendingPrepare;
     private markEnded;
     private emitError;
     private setStatus;
-    private requireActiveTurn;
+    private requireOperationTurn;
+    private updateUsage;
+    private matchesActiveOperation;
+    private markOperationRequestSettled;
+    private failOperationFromRequest;
+    private completeOperation;
+    private maybeSettleOperation;
+    private rejectOperation;
+    private queueSnapshotTool;
+    private reconcileRecoveredToolCalls;
+    private isAuthoritativeToolRequestCurrent;
+    private hasToolHandler;
+    private drainRecoveredToolCalls;
     private finishActiveTurn;
     private createBaseContext;
     private createChatContext;
+    private createChatDeltaContext;
     private createToolCallContext;
     private createStatusContext;
     private createErrorContext;

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 = {}) {
@@ -148,7 +153,7 @@ export class Pedelec {
         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 workspaceFolderPicker() {
         const result = await this.requestWithOptions("pick_workspace_folder", {}, { timeoutMs: null });
@@ -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() : "";
@@ -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)
@@ -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");
 }
@@ -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);

package/dist/index.type-test.js

@@ -50,10 +50,20 @@ async function typedOnToolNameFromCreateSession() {
     });
     session.onChat((_text, ctx) => {
         const chatCtx = ctx;
+        const messageType = ctx.type;
         const receivedAt = ctx.eventReceivedAt;
         void receivedAt;
+        void messageType;
         void chatCtx;
     });
+    session.onChatDelta((_text, ctx) => {
+        const chatDeltaCtx = ctx;
+        const deltaType = ctx.type;
+        const receivedAt = ctx.eventReceivedAt;
+        void receivedAt;
+        void deltaType;
+        void chatDeltaCtx;
+    });
     session.onStatus((_status, ctx) => {
         const statusCtx = ctx;
         const previous = ctx.previousStatus;
@@ -68,6 +78,7 @@ async function typedOnToolNameFromCreateSession() {
         const endedCtx = ctx;
         return endedCtx;
     });
+    await session.resume();
 }
 async function resumedSessionFallsBackToString() {
     const pedelec = new Pedelec();

package/dist/version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.2.12";
+export declare const SDK_VERSION = "0.3.0";

package/dist/version.generated.js

@@ -1,2 +1,2 @@
 // Generated from sdk/package.json. Do not edit manually.
-export const SDK_VERSION = "0.2.12";
+export const SDK_VERSION = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",