@kaoruisaac/pedelec 0.2.11 → 0.3.0

package/README.md

@@ -28,7 +28,7 @@ A web application can use Pedelec to:
 - send user instructions and receive streamed assistant text;
 - expose narrowly scoped browser-side tools to the agent;
 - resume or end sessions; and
-- upload and list completed sandbox assets; and
+- upload and list completed workspace assets; and
 - show connection, approval, provider, and lifecycle state in the UI.
 
 ## Why Pedelec exists
@@ -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
 
@@ -146,7 +163,7 @@ const path = await session.uploadAsset(file);
 const assets = await session.listAssets();
 ```
 
-The physical shared App/Agent directory is `.pedelec-sandbox/assets/`. In the SDK contract, `assets/` is its implicit root: `listAssets()` recursively lists regular files at every level as a flat array, ordered by filesystem modification time (newest first) and then by name; nested paths such as `/results/report.json` are returned in full. Directory entries and symlinks are excluded, as are `.pedelec-*` entries at every level; other dotfiles are included. It may run while the agent runs. One session can only upload one file at a time, but uploads can run alongside prepare or agent execution.
+The physical shared App/Agent directory is `.pedelec-runtime/assets/`. In the SDK contract, `assets/` is its implicit root: `listAssets()` recursively lists regular files at every level as a flat array, ordered by filesystem modification time (newest first) and then by name; nested paths such as `/results/report.json` are returned in full. Directory entries and symlinks are excluded, as are `.pedelec-*` entries at every level; other dotfiles are included. It may run while the agent runs. One session can only upload one file at a time, but uploads can run alongside prepare or agent execution.
 
 ```ts
 const text = await session.readAsset("/report.txt", "text");
@@ -156,37 +173,39 @@ const result = await session.readAsset("/model.glb", "file");
 
 Public asset paths use `/...` with `assets/` as their implicit root; nested paths such as `/results/model.glb` are supported up to 100 MiB.
 
-## Sandbox workspace
+## Workspace
+
+Workspace is the filesystem root in which the Agent works. Pedelec stores its private runtime data under `<workspace>/.pedelec-runtime/`.
 
-By default, each session receives a temporary Desktop-managed sandbox. To use an application-owned workspace that can persist across sessions, pass an absolute path:
+By default, each session receives a temporary Desktop-managed workspace. To use an application-owned workspace that can persist across sessions, pass an absolute path:
 
 ```ts
 const session = await pedelec.createSession({
   provider: "codex",
-  sandbox: { path: "C:\\workspace\\project-a" },
+  workspace: { path: "C:\\workspace\\project-a" },
 });
 ```
 
-Pedelec creates `.pedelec-sandbox/` with missing `assets/`, `logs/`, `skills/`, and `tmp/` subdirectories, preserving existing project files and existing private data. It never deletes an explicit workspace, and multiple active sessions may share it. Filesystem write conflicts are the application's responsibility. An explicit path must not overlap Pedelec's managed sandbox root.
+Pedelec creates `.pedelec-runtime/` with missing `assets/`, `logs/`, `skills/`, and `tmp/` subdirectories, preserving existing project files and existing private data. It never deletes an explicit workspace, and multiple active sessions may share it. Filesystem write conflicts are the application's responsibility. An explicit path must not overlap Pedelec's managed workspace root.
 
 ## Selecting an Application Workspace
 
-Use `sandboxFolderPicker()` when the application wants the user to choose a local workspace before creating a session:
+Use `workspaceFolderPicker()` when the application wants the user to choose a local workspace before creating a session:
 
 ```ts
-const folder = await pedelec.sandboxFolderPicker();
+const folder = await pedelec.workspaceFolderPicker();
 if (!folder) return; // The user cancelled the native picker.
 
-if (!folder.isEmptyFolder && !folder.hasSandboxConfig) {
+if (!folder.isEmptyFolder && !folder.hasWorkspaceConfig) {
   // The application decides whether to warn the user.
 }
 
 const session = await pedelec.createSession({
-  sandbox: { path: folder.path },
+  workspace: { path: folder.path },
 });
 ```
 
-`sandboxFolderPicker()` returns `Promise<SandboxFolderPickerResult | null>`. It is a read-only snapshot: it does not validate or initialize the selected folder, create workspace directories, or create the sandbox marker. `isEmptyFolder` only reports whether the selected folder root has any filesystem entry. `hasSandboxConfig` is true only when `.pedelec-lock.json` exists as a regular file; its JSON is not parsed. The picker requires the same origin approval as other sensitive Desktop APIs, and cancellation returns `null`. `createSession()` still applies the full sandbox rules and creates the marker after successful custom sandbox initialization. The marker currently records the SDK version and normalized caller origin but does not restrict reuse by origin or SDK version.
+`workspaceFolderPicker()` returns `Promise<WorkspaceFolderPickerResult | null>`. It is a read-only snapshot: it does not validate or initialize the selected folder, create workspace directories, or create the workspace marker. `isEmptyFolder` only reports whether the selected folder root has any filesystem entry. `hasWorkspaceConfig` is true only when `.pedelec-workspace.json` exists as a regular file; its JSON is not parsed. The picker requires the same origin approval as other sensitive Desktop APIs, and cancellation returns `null`. `createSession()` still applies the full workspace rules and creates the marker after successful custom workspace initialization. The marker currently records the SDK version and normalized caller origin but does not restrict reuse by origin or SDK version.
 
 ---
 

package/dist/index.d.ts

@@ -7,11 +7,11 @@ export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export type SandboxAssetPath = `/${string}`;
+export type AssetPath = `/${string}`;
 export type ReadAssetType = "text" | "json" | "file";
-export type SandboxAsset = {
+export type Asset = {
     name: string;
-    path: SandboxAssetPath;
+    path: AssetPath;
     sizeBytes: number;
     modifiedAt: number;
 };
@@ -83,26 +83,26 @@ export type SerializableSkillsManifest = {
     guidance: string;
     tools: SerializableToolManifest[];
 };
-export type CreateSessionSandboxInput = {
+export type CreateSessionWorkspaceInput = {
     path: string;
 };
-export interface SandboxFolderPickerResult {
+export interface WorkspaceFolderPickerResult {
     path: string;
     isEmptyFolder: boolean;
-    hasSandboxConfig: boolean;
+    hasWorkspaceConfig: boolean;
 }
 type CreateSessionInputWithProvider<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider: ProviderCode;
     effortLevel?: EffortLevel;
     skills?: SkillsInput<TTools>;
-    sandbox?: CreateSessionSandboxInput;
+    workspace?: CreateSessionWorkspaceInput;
     autoEndOnDisconnect?: boolean;
 };
 type CreateSessionInputWithDefaults<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider?: undefined;
     effortLevel?: EffortLevel;
     skills?: SkillsInput<TTools>;
-    sandbox?: CreateSessionSandboxInput;
+    workspace?: CreateSessionWorkspaceInput;
     autoEndOnDisconnect?: boolean;
 };
 export type CreateSessionInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = CreateSessionInputWithProvider<TTools> | CreateSessionInputWithDefaults<TTools>;
@@ -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,10 +295,12 @@ 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>>>;
-    sandboxFolderPicker(): Promise<SandboxFolderPickerResult | null>;
+    workspaceFolderPicker(): Promise<WorkspaceFolderPickerResult | null>;
     listProviders(): Promise<ProviderInfo[]>;
     getSettings(): Promise<PedelecSettings>;
     getApprovalStatus(): Promise<ApprovalStatus>;
@@ -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,61 +338,79 @@ 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<SandboxAssetPath>;
-    uploadAsset(file: File, targetPath: SandboxAssetPath): Promise<SandboxAssetPath>;
-    listAssets(): Promise<SandboxAsset[]>;
-    readAsset(path: SandboxAssetPath, type: "text"): Promise<string>;
-    readAsset<T = JsonValue>(path: SandboxAssetPath, type: "json"): Promise<T>;
-    readAsset(path: SandboxAssetPath, type: "file"): Promise<File>;
+    uploadAsset(file: File): Promise<AssetPath>;
+    uploadAsset(file: File, targetPath: AssetPath): Promise<AssetPath>;
+    listAssets(): Promise<Asset[]>;
+    readAsset(path: AssetPath, type: "text"): Promise<string>;
+    readAsset<T = JsonValue>(path: AssetPath, type: "json"): Promise<T>;
+    readAsset(path: AssetPath, type: "file"): Promise<File>;
     onError(handler: ErrorHandler): () => void;
     onStatus(handler: StatusHandler): () => void;
     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;