@kaoruisaac/pedelec 0.1.2 → 0.1.4

package/README.md

@@ -66,25 +66,26 @@ const session = await pedelec.createSession({
           properties: {},
           required: [],
         },
-        handler: () => ({
+        handler: (_args, ctx) => ({
           url: location.href,
           title: document.title,
+          turnId: ctx.turnId,
         }),
       }),
     ],
   },
 });
 
-session.onChat((text) => {
-  console.log(text);
+session.onChat((text, ctx) => {
+  console.log(ctx.turnId, text);
 });
 
-session.onStatus((status) => {
-  console.log("status", status);
+session.onStatus((status, ctx) => {
+  console.log("status", status, "previous", ctx.previousStatus);
 });
 
-session.onError((error) => {
-  console.error(error.code, error.message, error.details);
+session.onError((error, ctx) => {
+  console.error(ctx.type, error.code, error.message, error.details);
 });
 
 await session.sendText("Analyze the current page state.");
@@ -277,7 +278,8 @@ type CreateSessionInput =
 ```ts
 let assistantText = "";
 
-session.onChat((text) => {
+session.onChat((text, ctx) => {
+  console.debug("chat delta for turn", ctx.turnId, ctx.eventReceivedAt);
   assistantText += text;
   renderAssistantMessage(assistantText);
 });
@@ -286,8 +288,8 @@ session.onChat((text) => {
 The returned function unsubscribes the handler:
 
 ```ts
-const unsubscribe = session.onChat((text) => {
-  console.log(text);
+const unsubscribe = session.onChat((text, ctx) => {
+  console.log(ctx.turnId, text);
 });
 
 unsubscribe();
@@ -308,7 +310,8 @@ try {
 ## Session Status
 
 ```ts
-session.onStatus((status) => {
+session.onStatus((status, ctx) => {
+  console.debug("status changed from", ctx.previousStatus, "to", ctx.status);
   switch (status) {
     case "idle":
       break;
@@ -363,10 +366,11 @@ const session = await pedelec.createSession({
           properties: {},
           required: [],
         },
-        handler: () => ({
+        handler: (_args, ctx) => ({
           url: location.href,
           title: document.title,
           selectedText: window.getSelection()?.toString() ?? "",
+          turnId: ctx.turnId,
         }),
       }),
     ],
@@ -400,8 +404,9 @@ const session = await pedelec.createSession({
   },
 });
 
-session.onTool("update_counter", async (args) => {
+session.onTool("update_counter", async (args, ctx) => {
   const { delta } = args as { delta: number };
+  console.debug("tool call", ctx.toolRequestId, ctx.turnId);
   counter.value += delta;
   return {
     counter: counter.value,
@@ -412,7 +417,37 @@ session.onTool("update_counter", async (args) => {
 
 Tool results must be JSON-serializable. If no handler is registered, the SDK returns a `TOOL_HANDLER_NOT_FOUND` error result. If the handler throws, the SDK returns a `TOOL_HANDLER_ERROR` error result.
 
-The legacy generic form `session.onTool((tool, args) => ...)` remains available as a fallback handler.
+The generic form `session.onTool((tool, args, ctx) => ...)` remains available as a fallback handler.
+
+### Event Context and UI Lifecycles
+
+All user-facing event callbacks receive context metadata. The SDK provides `ctx.sessionId`, `ctx.provider`, `ctx.model`, `ctx.turnId`, `ctx.turnStartedAt`, `ctx.eventReceivedAt`, `ctx.eventEmittedAt`, and `ctx.source` where they apply. `turnId` is SDK-local metadata for one accepted `sendText()` turn; it is not sent to Core and should not be parsed.
+
+Apps should still use their own UI lifecycle state to decide whether a late callback is stale:
+
+```ts
+let lifecycleId = 0;
+
+function createWorldSession(session: PedelecSession) {
+  const generation = ++lifecycleId;
+
+  session.onTool("spawn_basic_shapes", async (args, ctx) => {
+    if (generation !== lifecycleId) {
+      return {
+        error: {
+          code: "STALE_TOOL_CALL",
+          message: "This tool call belongs to an older UI lifecycle.",
+        },
+      };
+    }
+
+    console.debug("handling tool", ctx.toolRequestId, ctx.turnId, ctx.turnStartedAt);
+    return spawnBasicShapes(args);
+  });
+}
+```
+
+The SDK context helps you inspect which session and turn produced an event. It does not automatically know whether your current canvas, page, render mode, or world instance is still valid.
 
 ### Tool Args Schema
 
@@ -448,8 +483,8 @@ If you have saved a `sessionId`, resume it later:
 ```ts
 const session = await pedelec.resumeSession("thread_abc123");
 
-session.onChat((text) => {
-  console.log(text);
+session.onChat((text, ctx) => {
+  console.log(ctx.turnId, text);
 });
 
 await session.sendText("Continue the previous task.");
@@ -468,8 +503,8 @@ After a session ends, future `sendText()` calls reject with `SESSION_ENDED`.
 Listen for runtime-ended sessions:
 
 ```ts
-session.onEnded(() => {
-  console.log("session ended");
+session.onEnded((ctx) => {
+  console.log("session ended", ctx.source);
 });
 ```
 
@@ -494,8 +529,8 @@ Low-level requests still use the SDK bridge timeout and reject with `PedelecErro
 Register `onError()` for session-level errors and use `try/catch` around async SDK calls.
 
 ```ts
-session.onError((error) => {
-  console.error("session error", error.code, error.message, error.details);
+session.onError((error, ctx) => {
+  console.error("session error", ctx.type, error.code, error.message, error.details);
 });
 
 try {
@@ -555,11 +590,11 @@ class PedelecSession {
   readonly model?: string;
 
   sendText(text: string): Promise<void>;
-  onChat(handler: (text: string) => void): () => void;
-  onTool(handler: (tool: string, args: unknown) => unknown | Promise<unknown>): () => void;
-  onError(handler: (error: PedelecError) => void): () => void;
-  onStatus(handler: (status: PedelecSessionStatus) => void): () => void;
-  onEnded(handler: () => void): () => void;
+  onChat(handler: (text: string, ctx: ChatEventContext) => void): () => void;
+  onTool(handler: (tool: string, args: unknown, ctx: ToolCallContext) => unknown | Promise<unknown>): () => void;
+  onError(handler: (error: PedelecError, ctx: ErrorEventContext) => void): () => void;
+  onStatus(handler: (status: PedelecSessionStatus, ctx: StatusEventContext) => void): () => void;
+  onEnded(handler: (ctx: EndedEventContext) => void): () => void;
   getStatus(): PedelecSessionStatus;
   end(): Promise<void>;
 }

package/dist/index.d.ts

@@ -51,18 +51,19 @@ export type ToolArgsOneOfSchema = ToolArgsSchemaMeta & {
 };
 export type ToolArgsSchemaNode = ToolArgsStringSchema | ToolArgsNumberSchema | ToolArgsIntegerSchema | ToolArgsBooleanSchema | ToolArgsArraySchema | ToolArgsObjectSchema | ToolArgsOneOfSchema;
 export type ToolArgsSchema = ToolArgsObjectSchema;
-export type ToolSpecificHandler<TArgs = unknown, TResult = unknown> = (args: TArgs) => TResult | Promise<TResult>;
-export type ToolDefinition<TArgs = unknown, TResult = unknown> = {
-    name: string;
+export type ToolSpecificHandler<TArgs = unknown, TResult = unknown> = (args: TArgs, ctx: ToolCallContext) => TResult | Promise<TResult>;
+export type ToolDefinition<TArgs = unknown, TResult = unknown, TName extends string = string> = {
+    name: TName;
     description: string;
     argsSchema: ToolArgsSchema;
     timeoutMs?: number;
     handler?: ToolSpecificHandler<TArgs, TResult>;
 };
-export type SkillsInput = {
+export type SkillsInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     guidance: string;
-    tools: ToolDefinition[];
+    tools: TTools;
 };
+export type ToolNameOf<TTools extends readonly ToolDefinition[]> = Extract<TTools[number]["name"], string>;
 export type SerializableToolManifest = {
     name: string;
     description: string;
@@ -73,19 +74,19 @@ export type SerializableSkillsManifest = {
     guidance: string;
     tools: SerializableToolManifest[];
 };
-type CreateSessionInputWithProvider = {
+type CreateSessionInputWithProvider<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider: ProviderCode;
     model?: string;
-    skills?: SkillsInput;
+    skills?: SkillsInput<TTools>;
     autoEndOnDisconnect?: boolean;
 };
-type CreateSessionInputWithDefaults = {
+type CreateSessionInputWithDefaults<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider?: undefined;
     model?: never;
-    skills?: SkillsInput;
+    skills?: SkillsInput<TTools>;
     autoEndOnDisconnect?: boolean;
 };
-export type CreateSessionInput = CreateSessionInputWithProvider | CreateSessionInputWithDefaults;
+export type CreateSessionInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = CreateSessionInputWithProvider<TTools> | CreateSessionInputWithDefaults<TTools>;
 export type ProviderInfo = {
     name: string;
     code: ProviderCode;
@@ -108,6 +109,43 @@ export type PedelecError = {
     details?: unknown;
 };
 export type PedelecSessionStatus = "idle" | "running" | "waiting_tool_result" | "ended" | "error";
+export type PedelecEventContext = {
+    sessionId: string;
+    provider: string;
+    model?: string;
+    sessionCreatedAt: number;
+    eventReceivedAt?: number;
+    eventEmittedAt: number;
+    turnId?: string;
+    turnStartedAt?: number;
+    turnKind?: "user" | "prepare";
+    source: "core" | "sdk";
+};
+export type ChatEventContext = PedelecEventContext & {
+    type: "chat_delta";
+    turnId: string;
+    turnStartedAt: number;
+    eventReceivedAt: number;
+};
+export type ToolCallContext = PedelecEventContext & {
+    type: "tool_call";
+    toolRequestId: string;
+    tool: string;
+    turnId: string;
+    turnStartedAt: number;
+    eventReceivedAt: number;
+};
+export type StatusEventContext = PedelecEventContext & {
+    type: "status_changed" | "sdk_status_changed";
+    status: PedelecSessionStatus;
+    previousStatus: PedelecSessionStatus;
+};
+export type ErrorEventContext = PedelecEventContext & {
+    type: "error" | "sdk_error";
+};
+export type EndedEventContext = PedelecEventContext & {
+    type: "ended" | "sdk_ended";
+};
 type SessionEvent = {
     type: "chat_delta";
     channelId: string;
@@ -145,12 +183,16 @@ type SessionEvent = {
     sessionId: string;
     seq?: number;
 };
-type ChatHandler = (text: string) => void;
-type GenericToolHandler = (tool: string, args: unknown) => unknown | Promise<unknown>;
-type ErrorHandler = (error: PedelecError) => void;
-type StatusHandler = (status: PedelecSessionStatus) => void;
-type EndedHandler = () => void;
-export declare function defineTool<TArgs = unknown, TResult = unknown>(tool: ToolDefinition<TArgs, TResult>): ToolDefinition<TArgs, TResult>;
+type EventDispatchMeta = {
+    source: "core" | "sdk";
+    eventReceivedAt?: number;
+};
+type ChatHandler = (text: string, ctx: ChatEventContext) => 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;
+type EndedHandler = (ctx: EndedEventContext) => void;
+export declare function defineTool<TArgs = unknown, TResult = unknown, const TName extends string = string>(tool: ToolDefinition<TArgs, TResult, TName>): ToolDefinition<TArgs, TResult, TName>;
 export declare class Pedelec {
     private readonly pageWindow;
     private readonly channelId;
@@ -162,11 +204,12 @@ export declare class Pedelec {
     private disconnectedError;
     private port;
     constructor(options?: PedelecOptions);
-    createSession(input?: CreateSessionInput): Promise<PedelecSession>;
+    createSession(): Promise<PedelecSession<string>>;
+    createSession<const TTools extends readonly ToolDefinition[]>(input: CreateSessionInput<TTools>): Promise<PedelecSession<ToolNameOf<TTools>>>;
     listProviders(): Promise<ProviderInfo[]>;
     getSettings(): Promise<PedelecSettings>;
     getApprovalStatus(): Promise<ApprovalStatus>;
-    resumeSession(sessionId: string): Promise<PedelecSession>;
+    resumeSession(sessionId: string): Promise<PedelecSession<string>>;
     request<T>(type: string, payload?: Record<string, unknown>): Promise<T>;
     unregisterSession(sessionId: string): void;
     private resolveCreateSessionInput;
@@ -181,13 +224,18 @@ export declare class Pedelec {
     private handleDisconnect;
     private broadcastError;
 }
-export declare class PedelecSession {
+export declare class PedelecSession<TToolName extends string = string> {
     private readonly client;
     readonly sessionId: string;
     readonly provider: string;
     readonly model?: string;
+    readonly sessionCreatedAt: number;
     private status;
     private pendingSend;
+    private pendingPrepare;
+    private preparePromise;
+    private prepared;
+    private activeTurn;
     private genericToolHandler;
     private inlineToolHandlers;
     private readonly namedToolHandlers;
@@ -196,23 +244,37 @@ export declare class PedelecSession {
     private readonly statusHandlers;
     private readonly endedHandlers;
     constructor(client: Pedelec, sessionId: string, provider: string, model?: string, inlineToolHandlers?: Map<string, ToolSpecificHandler>);
+    prepare(): Promise<void>;
     sendText(text: string): Promise<void>;
     onChat(handler: ChatHandler): () => void;
-    onTool(handler: GenericToolHandler): () => void;
-    onTool<TArgs = unknown, TResult = unknown>(toolName: string, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
+    onTool(handler: GenericToolHandler<TToolName>): () => void;
+    onTool<TArgs = unknown, TResult = unknown>(toolName: TToolName, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
     onError(handler: ErrorHandler): () => void;
     onStatus(handler: StatusHandler): () => void;
     onEnded(handler: EndedHandler): () => void;
     getStatus(): PedelecSessionStatus;
     end(): Promise<void>;
-    handleEvent(event: SessionEvent): void;
+    handleEvent(event: SessionEvent, meta?: EventDispatchMeta): void;
     replaceInlineToolHandlers(handlers: Map<string, ToolSpecificHandler>): void;
     private handleToolCall;
     private resolvePendingSend;
+    private resolvePendingPrepare;
+    private resolveActivePending;
     private rejectPendingSend;
+    private rejectPendingPrepare;
+    private rejectActivePending;
     private clearPendingSend;
+    private clearPendingPrepare;
     private markEnded;
     private emitError;
     private setStatus;
+    private requireActiveTurn;
+    private finishActiveTurn;
+    private createBaseContext;
+    private createChatContext;
+    private createToolCallContext;
+    private createStatusContext;
+    private createErrorContext;
+    private createEndedContext;
 }
 export {};

package/dist/index.js

@@ -309,8 +309,12 @@ export class Pedelec {
             return;
         }
         if (isSessionEvent(message) && this.isNewEvent(message)) {
+            const eventReceivedAt = Date.now();
             if (message.sessionId) {
-                this.sessions.get(message.sessionId)?.handleEvent(message);
+                this.sessions.get(message.sessionId)?.handleEvent(message, {
+                    source: "core",
+                    eventReceivedAt,
+                });
             }
             else if (message.type === "error") {
                 this.broadcastError(normalizeError(message.error, "SDK_TRANSPORT_ERROR", "Pedelec transport error"));
@@ -354,7 +358,7 @@ export class Pedelec {
     }
     broadcastError(error) {
         for (const session of this.sessions.values()) {
-            session.handleEvent({ type: "error", sessionId: session.sessionId, error });
+            session.handleEvent({ type: "error", sessionId: session.sessionId, error }, { source: "sdk" });
         }
     }
 }
@@ -363,8 +367,13 @@ export class PedelecSession {
     sessionId;
     provider;
     model;
+    sessionCreatedAt = Date.now();
     status = "idle";
     pendingSend = null;
+    pendingPrepare = null;
+    preparePromise = null;
+    prepared = false;
+    activeTurn = null;
     genericToolHandler = null;
     inlineToolHandlers = new Map();
     namedToolHandlers = new Map();
@@ -379,14 +388,63 @@ export class PedelecSession {
         this.model = model;
         this.inlineToolHandlers = new Map(inlineToolHandlers);
     }
-    sendText(text) {
+    prepare() {
         if (this.status === "ended") {
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
         }
         if (this.pendingSend) {
             return Promise.reject(makeError("SESSION_BUSY", "session is already running", { sessionId: this.sessionId }));
         }
-        this.setStatus("running");
+        if (this.prepared) {
+            return Promise.resolve();
+        }
+        if (this.preparePromise) {
+            return this.preparePromise;
+        }
+        const turn = createTurn("prepare");
+        this.activeTurn = turn;
+        this.setStatus("running", { source: "sdk" });
+        const donePromise = new Promise((resolve, reject) => {
+            this.pendingPrepare = { resolve, reject };
+        });
+        const requestPromise = this.client
+            .request("prepare_session", {
+            sessionId: this.sessionId,
+        })
+            .catch((err) => {
+            const error = normalizeError(err, "PREPARE_FAILED", "prepare failed");
+            this.emitError(error, { source: "sdk" });
+            this.clearPendingPrepare();
+            this.finishActiveTurn(turn);
+            throw error;
+        });
+        this.preparePromise = Promise.all([requestPromise, donePromise])
+            .then(() => {
+            this.prepared = true;
+        })
+            .finally(() => {
+            this.preparePromise = null;
+        });
+        return this.preparePromise;
+    }
+    async sendText(text) {
+        if (this.preparePromise) {
+            try {
+                await this.preparePromise;
+            }
+            catch {
+                // prepare is an optimization; sendText falls back to the original first-run path.
+            }
+        }
+        if (this.status === "ended") {
+            return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
+        }
+        if (this.pendingSend || this.pendingPrepare) {
+            return Promise.reject(makeError("SESSION_BUSY", "session is already running", { sessionId: this.sessionId }));
+        }
+        const turn = createTurn("user");
+        this.activeTurn = turn;
+        this.setStatus("running", { source: "sdk" });
         const donePromise = new Promise((resolve, reject) => {
             this.pendingSend = { resolve, reject };
         });
@@ -397,8 +455,9 @@ export class PedelecSession {
         })
             .catch((err) => {
             const error = normalizeError(err, "SEND_TEXT_FAILED", "sendText failed");
+            this.emitError(error, { source: "sdk" });
             this.clearPendingSend();
-            this.emitError(error);
+            this.finishActiveTurn(turn);
             throw error;
         });
         return Promise.all([requestPromise, donePromise]).then(() => undefined);
@@ -456,65 +515,73 @@ export class PedelecSession {
         }
         catch (err) {
             const error = normalizeError(err, "END_SESSION_FAILED", "end failed");
-            this.emitError(error);
+            this.emitError(error, { source: "sdk" });
             throw error;
         }
-        this.markEnded();
+        this.markEnded({ source: "sdk" });
         this.client.unregisterSession(this.sessionId);
     }
-    handleEvent(event) {
+    handleEvent(event, meta = { source: "sdk" }) {
         if (event.type === "chat_delta") {
+            const turn = this.requireActiveTurn("chat_delta", meta);
+            if (!turn)
+                return;
+            if (turn.kind === "prepare")
+                return;
             for (const handler of this.chatHandlers) {
-                handler(event.text);
+                handler(event.text, this.createChatContext(meta, turn));
             }
             return;
         }
         if (event.type === "status_changed") {
-            this.setStatus(event.status);
+            this.setStatus(event.status, meta);
             if (event.status === "idle") {
-                this.resolvePendingSend();
+                this.resolveActivePending();
             }
             else if (event.status === "ended") {
-                this.markEnded();
+                this.markEnded(meta);
             }
             else if (event.status === "error") {
                 const error = makeError("SESSION_ERROR", "session entered error status", { sessionId: this.sessionId });
-                this.rejectPendingSend(error);
-                this.emitError(error);
+                this.emitError(error, meta);
+                this.rejectActivePending(error);
             }
             return;
         }
         if (event.type === "tool_call") {
-            this.setStatus("waiting_tool_result");
-            this.handleToolCall(event);
+            const turn = this.requireActiveTurn("tool_call", meta);
+            if (!turn)
+                return;
+            this.setStatus("waiting_tool_result", meta);
+            this.handleToolCall(event, meta, turn);
             return;
         }
         if (event.type === "done") {
-            this.setStatus("idle");
-            this.resolvePendingSend();
+            this.setStatus("idle", meta);
+            this.resolveActivePending();
             return;
         }
         if (event.type === "error") {
-            this.setStatus("error");
+            this.setStatus("error", meta);
             const error = normalizeError(event.error, "SESSION_ERROR", "session error");
-            this.rejectPendingSend(error);
-            this.emitError(error);
+            this.emitError(error, meta);
+            this.rejectActivePending(error);
             return;
         }
         if (event.type === "ended") {
-            this.markEnded();
+            this.markEnded(meta);
         }
     }
     replaceInlineToolHandlers(handlers) {
         this.inlineToolHandlers = new Map(handlers);
     }
-    async handleToolCall(event) {
+    async handleToolCall(event, meta, turn) {
         let result;
         const namedHandler = this.namedToolHandlers.get(event.tool);
         const inlineHandler = this.inlineToolHandlers.get(event.tool);
         if (namedHandler) {
             try {
-                result = await namedHandler(event.args);
+                result = await namedHandler(event.args, this.createToolCallContext(event, meta, turn));
             }
             catch (err) {
                 result = {
@@ -524,7 +591,7 @@ export class PedelecSession {
         }
         else if (inlineHandler) {
             try {
-                result = await inlineHandler(event.args);
+                result = await inlineHandler(event.args, this.createToolCallContext(event, meta, turn));
             }
             catch (err) {
                 result = {
@@ -534,7 +601,7 @@ export class PedelecSession {
         }
         else if (this.genericToolHandler) {
             try {
-                result = await this.genericToolHandler(event.tool, event.args);
+                result = await this.genericToolHandler(event.tool, event.args, this.createToolCallContext(event, meta, turn));
             }
             catch (err) {
                 result = {
@@ -557,45 +624,152 @@ export class PedelecSession {
             });
         }
         catch (err) {
-            this.emitError(normalizeError(err, "SUBMIT_TOOL_RESULT_FAILED", "submit_tool_result failed"));
+            this.emitError(normalizeError(err, "SUBMIT_TOOL_RESULT_FAILED", "submit_tool_result failed"), {
+                source: "sdk",
+            });
         }
     }
     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;
     }
-    markEnded() {
+    clearPendingPrepare() {
+        this.pendingPrepare = null;
+    }
+    markEnded(meta = { source: "sdk" }) {
         const wasEnded = this.status === "ended";
-        this.setStatus("ended");
-        this.rejectPendingSend(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
+        this.setStatus("ended", meta);
         if (!wasEnded) {
             for (const handler of this.endedHandlers) {
-                handler();
+                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();
     }
-    emitError(error) {
+    emitError(error, meta = { source: "sdk" }) {
         for (const handler of this.errorHandlers) {
-            handler(error);
+            handler(error, this.createErrorContext(meta));
         }
     }
-    setStatus(status) {
+    setStatus(status, meta = { source: "sdk" }) {
         if (this.status === status)
             return;
+        const previousStatus = this.status;
         this.status = status;
         for (const handler of this.statusHandlers) {
-            handler(status);
+            handler(status, this.createStatusContext(status, previousStatus, meta));
+        }
+    }
+    requireActiveTurn(type, meta) {
+        if (this.activeTurn)
+            return this.activeTurn;
+        this.emitError(makeError("SDK_PROTOCOL_ERROR", `${type} event was received without an active turn`, {
+            sessionId: this.sessionId,
+        }), { source: "sdk", eventReceivedAt: meta.eventReceivedAt });
+        return null;
+    }
+    finishActiveTurn(turn = this.activeTurn) {
+        if (!turn || !this.activeTurn)
+            return;
+        if (this.activeTurn.turnId === turn.turnId) {
+            this.activeTurn = null;
         }
     }
+    createBaseContext(meta, turn = this.activeTurn) {
+        return {
+            sessionId: this.sessionId,
+            provider: this.provider,
+            model: this.model,
+            sessionCreatedAt: this.sessionCreatedAt,
+            ...(meta.eventReceivedAt === undefined ? {} : { eventReceivedAt: meta.eventReceivedAt }),
+            eventEmittedAt: Date.now(),
+            ...(turn ? { turnId: turn.turnId, turnStartedAt: turn.turnStartedAt, turnKind: turn.kind } : {}),
+            source: meta.source,
+        };
+    }
+    createChatContext(meta, turn) {
+        return {
+            ...this.createBaseContext(meta, turn),
+            type: "chat_delta",
+            turnId: turn.turnId,
+            turnStartedAt: turn.turnStartedAt,
+            eventReceivedAt: meta.eventReceivedAt ?? Date.now(),
+            source: "core",
+        };
+    }
+    createToolCallContext(event, meta, turn) {
+        return {
+            ...this.createBaseContext(meta, turn),
+            type: "tool_call",
+            toolRequestId: event.toolRequestId,
+            tool: event.tool,
+            turnId: turn.turnId,
+            turnStartedAt: turn.turnStartedAt,
+            eventReceivedAt: meta.eventReceivedAt ?? Date.now(),
+            source: "core",
+        };
+    }
+    createStatusContext(status, previousStatus, meta) {
+        return {
+            ...this.createBaseContext(meta),
+            type: meta.source === "core" ? "status_changed" : "sdk_status_changed",
+            status,
+            previousStatus,
+        };
+    }
+    createErrorContext(meta) {
+        return {
+            ...this.createBaseContext(meta),
+            type: meta.source === "core" ? "error" : "sdk_error",
+        };
+    }
+    createEndedContext(meta) {
+        return {
+            ...this.createBaseContext(meta),
+            type: meta.source === "core" ? "ended" : "sdk_ended",
+        };
+    }
 }
 function isSessionEvent(message) {
     return (message.type === "chat_delta" ||
@@ -651,6 +825,16 @@ function createChannelId() {
         : Math.random().toString(36).slice(2);
     return `pedelec_${Date.now()}_${random}`;
 }
+function createTurn(kind = "user") {
+    const random = typeof crypto !== "undefined" && "randomUUID" in crypto
+        ? crypto.randomUUID()
+        : Math.random().toString(36).slice(2);
+    return {
+        turnId: `turn_${Date.now()}_${random}`,
+        turnStartedAt: Date.now(),
+        kind,
+    };
+}
 function getCurrentOrigin(pageWindow) {
     const origin = pageWindow?.location?.origin;
     return typeof origin === "string" && origin ? origin : null;

package/dist/index.type-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.type-test.js

@@ -0,0 +1,101 @@
+import { Pedelec, defineTool, } from "./index";
+async function typedOnToolNameFromCreateSession() {
+    const pedelec = new Pedelec();
+    const session = await pedelec.createSession({
+        provider: "codex",
+        skills: {
+            guidance: "Use available tools.",
+            tools: [
+                defineTool({
+                    name: "get_selection",
+                    description: "Get selected text.",
+                    argsSchema: { type: "object", properties: {}, required: [] },
+                }),
+                defineTool({
+                    name: "replace_text",
+                    description: "Replace selected text.",
+                    argsSchema: { type: "object", properties: {}, required: [] },
+                }),
+            ],
+        },
+    });
+    session.onTool((name, args, ctx) => {
+        const allowed = name;
+        const stillUnknown = args;
+        const toolCtx = ctx;
+        return { allowed, stillUnknown, toolCtx };
+    });
+    session.onTool("get_selection", async (args, ctx) => {
+        const stillUnknown = args;
+        const toolName = ctx.tool;
+        const turnId = ctx.turnId;
+        return { ok: true, stillUnknown, toolName, turnId };
+    });
+    session.onTool("replace_text", async () => {
+        return { ok: true };
+    });
+    // @ts-expect-error tool name must come from skills.tools[].name
+    session.onTool("not_exists", async () => {
+        return { ok: false };
+    });
+    session.onTool((name, _args, ctx) => {
+        // @ts-expect-error generic handler name should not be arbitrary string
+        const invalid = name;
+        // @ts-expect-error user-facing context must not expose core seq
+        const noSeq = ctx.seq;
+        return noSeq ?? invalid;
+    });
+    session.onChat((_text, ctx) => {
+        const chatCtx = ctx;
+        const receivedAt = ctx.eventReceivedAt;
+        void receivedAt;
+        void chatCtx;
+    });
+    session.onStatus((_status, ctx) => {
+        const statusCtx = ctx;
+        const previous = ctx.previousStatus;
+        void previous;
+        void statusCtx;
+    });
+    session.onError((_error, ctx) => {
+        const errorCtx = ctx;
+        return errorCtx;
+    });
+    session.onEnded((ctx) => {
+        const endedCtx = ctx;
+        return endedCtx;
+    });
+}
+async function resumedSessionFallsBackToString() {
+    const pedelec = new Pedelec();
+    const session = await pedelec.resumeSession("thread_1");
+    session.onTool((name) => {
+        const anyString = name;
+        return anyString;
+    });
+    session.onTool("runtime_tool_name", async () => {
+        return { ok: true };
+    });
+}
+async function noSkillsFallsBackToString() {
+    const pedelec = new Pedelec();
+    const session = await pedelec.createSession({ provider: "codex" });
+    session.onTool((name) => {
+        const anyString = name;
+        return anyString;
+    });
+    session.onTool("runtime_tool_name", async () => {
+        return { ok: true };
+    });
+}
+void typedOnToolNameFromCreateSession;
+void resumedSessionFallsBackToString;
+void noSkillsFallsBackToString;
+const baseContext = {
+    sessionId: "thread_1",
+    provider: "codex",
+    sessionCreatedAt: Date.now(),
+    eventEmittedAt: Date.now(),
+    source: "sdk",
+};
+void baseContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
-    "prepublishOnly": "npm run test && npm run build"
+    "type-test": "tsc -p tsconfig.type-test.json",
+    "prepublishOnly": "npm run test && npm run type-test && npm run build"
   },
   "devDependencies": {
     "typescript": "^5.8.3",