@kaoruisaac/pedelec 0.2.11 → 0.2.12

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
@@ -146,7 +146,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 +156,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
 
-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:
+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 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>;
@@ -238,7 +238,7 @@ 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>;
+    workspaceFolderPicker(): Promise<WorkspaceFolderPickerResult | null>;
     listProviders(): Promise<ProviderInfo[]>;
     getSettings(): Promise<PedelecSettings>;
     getApprovalStatus(): Promise<ApprovalStatus>;
@@ -288,12 +288,12 @@ export declare class PedelecSession<TToolName extends string = string> {
     onChat(handler: ChatHandler): () => 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;

package/dist/index.js

@@ -141,7 +141,7 @@ export class Pedelec {
                 provider: resolvedInput.provider,
                 effortLevel: resolvedInput.effortLevel,
                 skills: resolvedInput.skills,
-                sandbox: resolvedInput.sandbox,
+                workspace: resolvedInput.workspace,
                 autoEndOnDisconnect: resolvedInput.autoEndOnDisconnect,
             },
         });
@@ -150,9 +150,9 @@ 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 workspaceFolderPicker() {
+        const result = await this.requestWithOptions("pick_workspace_folder", {}, { timeoutMs: null });
+        return normalizeWorkspaceFolderPickerResponse(result);
     }
     async listProviders() {
         return normalizeProviderInfoList(await this.request("list_providers"));
@@ -258,15 +258,15 @@ export class Pedelec {
         }
         const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
         const normalizedSkills = normalizeSkillsInput(raw.skills);
-        const sandbox = normalizeCreateSessionSandboxInput(raw.sandbox);
+        const workspace = normalizeCreateSessionWorkspaceInput(raw.workspace);
         if (!hasProvider) {
-            return this.resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, sandbox, autoEndOnDisconnect);
+            return this.resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, workspace, autoEndOnDisconnect);
         }
         return {
             provider: provider,
             effortLevel,
             skills: normalizedSkills.manifest,
-            sandbox,
+            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             autoEndOnDisconnect,
         };
@@ -323,7 +323,7 @@ export class Pedelec {
             };
         }
     }
-    async resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, sandbox, autoEndOnDisconnect) {
+    async resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, workspace, autoEndOnDisconnect) {
         const settings = await this.getSettings();
         if (!settings.defaultProvider) {
             throw makeError("DEFAULT_PROVIDER_NOT_SET", "Default provider is not set. Open the Pedelec desktop app Settings page and choose a default provider.");
@@ -333,7 +333,7 @@ export class Pedelec {
             provider: settings.defaultProvider,
             effortLevel,
             skills: normalizedSkills.manifest,
-            sandbox,
+            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             autoEndOnDisconnect,
         };
@@ -462,18 +462,18 @@ export class Pedelec {
         }
     }
 }
-function normalizeCreateSessionSandboxInput(value) {
+function normalizeCreateSessionWorkspaceInput(value) {
     if (value === undefined)
         return undefined;
     if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw makeError("INVALID_INPUT", "sandbox must be an object");
+        throw makeError("INVALID_INPUT", "workspace must be an object");
     }
     const path = value.path;
     if (typeof path !== "string") {
-        throw makeError("INVALID_INPUT", "sandbox.path must be a string");
+        throw makeError("INVALID_INPUT", "workspace.path must be a string");
     }
     if (path.trim().length === 0) {
-        throw makeError("INVALID_INPUT", "sandbox.path must not be empty");
+        throw makeError("INVALID_INPUT", "workspace.path must not be empty");
     }
     return { path };
 }
@@ -1033,21 +1033,21 @@ function normalizePedelecSettings(value) {
     }
     return { defaultProvider: value.defaultProvider };
 }
-function normalizeSandboxFolderPickerResponse(value) {
+function normalizeWorkspaceFolderPickerResponse(value) {
     if (!isPlainObject(value) || !("path" in value)) {
-        throw makeError("SDK_PROTOCOL_ERROR", "pick_sandbox_folder response had an invalid shape");
+        throw makeError("SDK_PROTOCOL_ERROR", "pick_workspace_folder response had an invalid shape");
     }
     const path = value.path;
     if (path === null)
         return null;
     if (typeof path !== "string" || path.length === 0 ||
-        typeof value.isEmptyFolder !== "boolean" || typeof value.hasSandboxConfig !== "boolean") {
-        throw makeError("SDK_PROTOCOL_ERROR", "pick_sandbox_folder response had an invalid shape");
+        typeof value.isEmptyFolder !== "boolean" || typeof value.hasWorkspaceConfig !== "boolean") {
+        throw makeError("SDK_PROTOCOL_ERROR", "pick_workspace_folder response had an invalid shape");
     }
     return {
         path,
         isEmptyFolder: value.isEmptyFolder,
-        hasSandboxConfig: value.hasSandboxConfig,
+        hasWorkspaceConfig: value.hasWorkspaceConfig,
     };
 }
 function normalizeProviderInfoList(value) {

package/dist/index.type-test.js

@@ -1,5 +1,5 @@
 import { Pedelec, defineTool, } from "./index";
-function sandboxInputHasPublicType() {
+function workspaceInputHasPublicType() {
     return { path: "C:\\workspace\\project" };
 }
 async function typedOnToolNameFromCreateSession() {
@@ -84,10 +84,10 @@ async function noSkillsFallsBackToString() {
     const pedelec = new Pedelec();
     const session = await pedelec.createSession({
         provider: "codex",
-        sandbox: { path: "C:\\workspace\\project" },
+        workspace: { path: "C:\\workspace\\project" },
     });
-    const typedSandbox = sandboxInputHasPublicType();
-    void typedSandbox;
+    const typedWorkspace = workspaceInputHasPublicType();
+    void typedWorkspace;
     session.onTool((name) => {
         const anyString = name;
         return anyString;
@@ -100,6 +100,10 @@ async function effortLevelPublicTypeContract() {
     const pedelec = new Pedelec();
     await pedelec.createSession({ effortLevel: "high" });
     const session = await pedelec.createSession({ provider: "codex", effortLevel: "low" });
+    // @ts-expect-error the removed sandbox input is not part of the public contract
+    pedelec.createSession({ provider: "codex", sandbox: { path: "C:\\workspace\\legacy" } });
+    // @ts-expect-error the removed sandbox picker is not part of the public contract
+    pedelec.sandboxFolderPicker();
     // @ts-expect-error model is no longer a createSession option
     pedelec.createSession({ provider: "codex", model: "gpt-5" });
     // @ts-expect-error session no longer exposes provider model
@@ -136,14 +140,14 @@ async function availabilityHasPublicType() {
     void availability;
     void promise;
 }
-async function sandboxFolderPickerHasPublicType() {
+async function workspaceFolderPickerHasPublicType() {
     const pedelec = new Pedelec();
-    const result = pedelec.sandboxFolderPicker();
+    const result = pedelec.workspaceFolderPicker();
     void result;
 }
 function directoryPickerIsRemoved() {
     const pedelec = new Pedelec();
-    // @ts-expect-error directoryPicker was removed in favor of sandboxFolderPicker
+    // @ts-expect-error directoryPicker was removed in favor of workspaceFolderPicker
     pedelec.directoryPicker();
 }
 function publicSecurityTypesAreRestricted() {
@@ -164,7 +168,7 @@ void noSkillsFallsBackToString;
 void effortLevelPublicTypeContract;
 void listAssetsHasPublicTypes;
 void availabilityHasPublicType;
-void sandboxFolderPickerHasPublicType;
+void workspaceFolderPickerHasPublicType;
 void directoryPickerIsRemoved;
 void publicSecurityTypesAreRestricted;
 const baseContext = {

package/dist/version.generated.d.ts

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

package/dist/version.generated.js

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

package/package.json

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