@kaoruisaac/pedelec 0.2.1 → 0.2.3

package/README.md

@@ -24,6 +24,7 @@ Pedelec is a browser SDK and local bridge for applications that want to work wit
 A web application can use Pedelec to:
 
 - create an agent session on the user's machine;
+- choose an application-managed workspace with the native directory picker;
 - send user instructions and receive streamed assistant text;
 - expose narrowly scoped browser-side tools to the agent;
 - resume or end sessions; and
@@ -168,6 +169,25 @@ const session = await pedelec.createSession({
 
 Pedelec creates missing `skills/`, `assets/`, `logs/`, and `tmp/` directories and preserves existing files. 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.
 
+## Selecting an Application Workspace
+
+Use `sandboxFolderPicker()` when the application wants the user to choose a local workspace before creating a session:
+
+```ts
+const folder = await pedelec.sandboxFolderPicker();
+if (!folder) return; // The user cancelled the native picker.
+
+if (!folder.isEmptyFolder && !folder.hasSandboxConfig) {
+  // The application decides whether to warn the user.
+}
+
+const session = await pedelec.createSession({
+  sandbox: { 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-sandbox.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.
+
 ---
 
 ## Creating a Session

package/dist/index.d.ts

@@ -86,6 +86,11 @@ export type SerializableSkillsManifest = {
 export type CreateSessionSandboxInput = {
     path: string;
 };
+export interface SandboxFolderPickerResult {
+    path: string;
+    isEmptyFolder: boolean;
+    hasSandboxConfig: boolean;
+}
 type CreateSessionInputWithProvider<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider: ProviderCode;
     effortLevel?: EffortLevel;
@@ -233,11 +238,13 @@ export declare class Pedelec {
     constructor(options?: PedelecOptions);
     createSession(): Promise<PedelecSession<string>>;
     createSession<const TTools extends readonly ToolDefinition[]>(input: CreateSessionInput<TTools>): Promise<PedelecSession<ToolNameOf<TTools>>>;
+    sandboxFolderPicker(): Promise<SandboxFolderPickerResult | null>;
     listProviders(): Promise<ProviderInfo[]>;
     getSettings(): Promise<PedelecSettings>;
     getApprovalStatus(): Promise<ApprovalStatus>;
     resumeSession(sessionId: string): Promise<PedelecSession<string>>;
     request<T>(type: string, payload?: Record<string, unknown>): Promise<T>;
+    private requestWithOptions;
     unregisterSession(sessionId: string): void;
     private resolveCreateSessionInput;
     checkAvailability(): Promise<PedelecAvailability>;

package/dist/index.js

@@ -1,4 +1,5 @@
 import { PEDELEC_EXTENSION_ID } from "./extension-id.js";
+import { SDK_VERSION } from "./version.generated.js";
 const SDK_EXTERNAL_PORT_NAME = "pedelec-sdk-external";
 const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
 function normalizeListAssetsResponse(response) {
@@ -149,6 +150,10 @@ export class Pedelec {
         }
         return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.effortLevel, resolvedInput.inlineToolHandlers);
     }
+    async sandboxFolderPicker() {
+        const result = await this.requestWithOptions("pick_sandbox_folder", {}, { timeoutMs: null });
+        return normalizeSandboxFolderPickerResponse(result);
+    }
     async listProviders() {
         return normalizeProviderInfoList(await this.request("list_providers"));
     }
@@ -186,6 +191,9 @@ export class Pedelec {
         return this.registerSession(result.sessionId, "", undefined);
     }
     request(type, payload = {}) {
+        return this.requestWithOptions(type, payload);
+    }
+    requestWithOptions(type, payload = {}, options = {}) {
         let port;
         try {
             port = this.ensureExtensionPort();
@@ -194,15 +202,24 @@ export class Pedelec {
             return Promise.reject(normalizeError(err, "EXTENSION_UNAVAILABLE", "Pedelec extension is unavailable."));
         }
         const requestId = `sdk_${Date.now()}_${this.nextRequestNumber++}`;
-        const message = { channelId: this.channelId, type, requestId, ...payload };
+        const message = {
+            channelId: this.channelId,
+            type,
+            requestId,
+            ...payload,
+            ...(type === "create_session" ? { callerSdkVersion: SDK_VERSION } : {}),
+        };
         return new Promise((resolve, reject) => {
-            const timeoutId = setTimeout(() => {
-                this.pendingRequests.delete(requestId);
-                reject(makeError("SDK_BRIDGE_TIMEOUT", "Pedelec extension did not respond.", {
-                    requestId,
-                    type,
-                }));
-            }, this.bridgeTimeoutMs);
+            const timeoutMs = options.timeoutMs === undefined ? this.bridgeTimeoutMs : options.timeoutMs;
+            const timeoutId = timeoutMs === null
+                ? null
+                : setTimeout(() => {
+                    this.pendingRequests.delete(requestId);
+                    reject(makeError("SDK_BRIDGE_TIMEOUT", "Pedelec extension did not respond.", {
+                        requestId,
+                        type,
+                    }));
+                }, timeoutMs);
             this.pendingRequests.set(requestId, {
                 port,
                 resolve: (value) => resolve(value),
@@ -214,7 +231,8 @@ export class Pedelec {
             }
             catch (err) {
                 this.pendingRequests.delete(requestId);
-                clearTimeout(timeoutId);
+                if (timeoutId !== null)
+                    clearTimeout(timeoutId);
                 const error = normalizeError(err, "EXTENSION_DISCONNECTED", "Pedelec extension disconnected.");
                 if (this.port === port) {
                     this.handleDisconnect(port, error);
@@ -398,7 +416,8 @@ export class Pedelec {
         if (!pending)
             return;
         this.pendingRequests.delete(message.requestId);
-        clearTimeout(pending.timeoutId);
+        if (pending.timeoutId !== null)
+            clearTimeout(pending.timeoutId);
         if (message.ok) {
             pending.resolve(message.result);
         }
@@ -427,7 +446,8 @@ export class Pedelec {
             if (pending.port !== port)
                 continue;
             this.pendingRequests.delete(requestId);
-            clearTimeout(pending.timeoutId);
+            if (pending.timeoutId !== null)
+                clearTimeout(pending.timeoutId);
             pending.reject(error);
         }
     }
@@ -1013,6 +1033,23 @@ function normalizePedelecSettings(value) {
     }
     return { defaultProvider: value.defaultProvider };
 }
+function normalizeSandboxFolderPickerResponse(value) {
+    if (!isPlainObject(value) || !("path" in value)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "pick_sandbox_folder response had an invalid shape");
+    }
+    const path = value.path;
+    if (path === null)
+        return null;
+    if (typeof path !== "string" || path.length === 0 ||
+        typeof value.isEmptyFolder !== "boolean" || typeof value.hasSandboxConfig !== "boolean") {
+        throw makeError("SDK_PROTOCOL_ERROR", "pick_sandbox_folder response had an invalid shape");
+    }
+    return {
+        path,
+        isEmptyFolder: value.isEmptyFolder,
+        hasSandboxConfig: value.hasSandboxConfig,
+    };
+}
 function normalizeProviderInfoList(value) {
     if (!Array.isArray(value))
         throw makeError("SDK_PROTOCOL_ERROR", "list_providers response was not an array");

package/dist/index.type-test.js

@@ -136,6 +136,16 @@ async function availabilityHasPublicType() {
     void availability;
     void promise;
 }
+async function sandboxFolderPickerHasPublicType() {
+    const pedelec = new Pedelec();
+    const result = pedelec.sandboxFolderPicker();
+    void result;
+}
+function directoryPickerIsRemoved() {
+    const pedelec = new Pedelec();
+    // @ts-expect-error directoryPicker was removed in favor of sandboxFolderPicker
+    pedelec.directoryPicker();
+}
 function publicSecurityTypesAreRestricted() {
     const status = {
         installed: true,
@@ -154,6 +164,8 @@ void noSkillsFallsBackToString;
 void effortLevelPublicTypeContract;
 void listAssetsHasPublicTypes;
 void availabilityHasPublicType;
+void sandboxFolderPickerHasPublicType;
+void directoryPickerIsRemoved;
 void publicSecurityTypesAreRestricted;
 const baseContext = {
     sessionId: "thread_1",

package/dist/version.generated.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.2.3";

package/dist/version.generated.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,8 +24,11 @@
     "directory": "sdk"
   },
   "scripts": {
+    "prebuild": "node scripts/generate-version.mjs",
     "build": "tsc -p tsconfig.json",
+    "pretest": "node scripts/generate-version.mjs",
     "test": "vitest run",
+    "pretype-test": "node scripts/generate-version.mjs",
     "type-test": "tsc -p tsconfig.type-test.json",
     "prepublishOnly": "npm run test && npm run type-test && npm run build"
   },