@kaoruisaac/pedelec 0.3.5 → 0.4.1

package/README.md

@@ -24,7 +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;
+- open an application-managed workspace with the native directory picker or an explicit path;
 - send user instructions and receive streamed assistant text;
 - expose narrowly scoped browser-side tools to the agent;
 - resume or end sessions; and
@@ -223,7 +223,7 @@ const path = await session.uploadAsset(file);
 const assets = await session.listAssets();
 ```
 
-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.
+Assets are stored in the Workspace shared by the Session. 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. When several sessions share a Workspace, they share this `.pedelec-runtime/assets/` area.
 
 ```ts
 const text = await session.readAsset("/report.txt", "text");
@@ -235,37 +235,80 @@ Public asset paths use `/...` with `assets/` as their implicit root; nested path
 
 ## Workspace
 
-Workspace is the filesystem root in which the Agent works. Pedelec stores its private runtime data under `<workspace>/.pedelec-runtime/`.
+Workspace is the filesystem root in which the Agent works. Pedelec stores its private runtime data under `<workspace>/.pedelec-runtime/`. There are two supported flows:
 
-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:
+### Explicit Workspace
+
+```ts
+const workspace = await pedelec.openWorkspace();
+if (!workspace) return;
+
+const session = await workspace.createSession({
+  model: "gpt-5.6-sol",
+  effort: "high",
+});
+```
+
+`openWorkspace()` without a path opens the native folder picker. User cancellation resolves to `null`; no Workspace or Session is created. The returned `PedelecWorkspace` handle is the object to retain and reuse. An explicit path bypasses the picker:
+
+```ts
+const workspace = await pedelec.openWorkspace("C:\\workspace\\project-a");
+```
+
+Pedelec initializes `.pedelec-runtime` for Workspace-owned runtime data without clearing project files or existing private data. Assets, logs, and temporary data are Workspace-level, while generated Session skills and Deno Module state are isolated per Thread. Applications should not depend on the private `.pedelec-runtime` subdirectory layout. Explicit Workspaces are application-managed, are never deleted by Pedelec, and can own multiple Sessions. An explicit path must not overlap Pedelec's managed workspace root.
+
+### Managed convenience
 
 ```ts
 const session = await pedelec.createSession({
-  provider: "codex",
-  workspace: { path: "C:\\workspace\\project-a" },
+  effortLevel: "high",
 });
+console.log(session.workspace.path); // null for managed Workspace
 ```
 
-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.
+`Pedelec.createSession()` creates a temporary Desktop-managed Workspace automatically. It no longer accepts Workspace configuration; use `openWorkspace()` followed by `workspace.createSession()` for an explicit Workspace. Every created or resumed Session exposes its Workspace as `session.workspace`.
+
+### Workspace methods
 
-## Selecting an Application Workspace
+`workspace.listFiles(path?)` and `workspace.listFolders(path?)` recursively return Workspace-relative paths. An omitted path lists from the Workspace root; `/` is the separator and results are lexicographically sorted. The `.pedelec-runtime` directory is included. Symlinks and junctions are neither followed nor returned. Results are not silently truncated: an oversized response fails with `WORKSPACE_LIST_TOO_LARGE`, so retry with a narrower path.
 
-Use `workspaceFolderPicker()` when the application wants the user to choose a local workspace before creating a session:
+`workspace.run(script, options?)` executes application-supplied Deno code in the Workspace:
 
 ```ts
-const folder = await pedelec.workspaceFolderPicker();
-if (!folder) return; // The user cancelled the native picker.
+const result = await workspace.run(
+  "console.log(JSON.stringify({ ok: true }))",
+  { timeoutMs: 60_000 },
+);
 
-if (!folder.isEmptyFolder && !folder.hasWorkspaceConfig) {
-  // The application decides whether to warn the user.
+if (result.stdoutTruncated) {
+  throw new Error("Workspace script output was truncated");
 }
+const value = JSON.parse(result.stdout);
+```
 
-const session = await pedelec.createSession({
-  workspace: { path: folder.path },
+The default timeout is 60 seconds; `timeoutMs` must be a positive integer. The return value is the raw `DenoRunOutput` shape: `exitCode`, `stdout`, `stderr`, `stdoutTruncated`, and `stderrTruncated`. A non-zero `exitCode` still resolves normally. The application parses `stdout` when it wants a function-like return value. Check truncation flags before relying on output; an oversized browser response fails with `WORKSPACE_RUN_OUTPUT_TOO_LARGE`.
+
+`workspace.run()` has read and write access to the Workspace, but no network, host environment, subprocess execution, FFI, or `sys` permission. The existing no-remote, cached-only, and no-npm runtime restrictions still apply. This is a direct deterministic capability for an approved Web application to read and modify the opened Workspace; it is not unrestricted host code execution and is not mediated by an Agent.
+
+Several `workspace.run()` calls in one Workspace may execute concurrently. A Workspace run cannot start while any Session in that Workspace has an active Agent/provider operation. Conversely, a Session in that Workspace cannot begin `sendText()` or provider preparation while one or more Workspace runs are active. This rule is Workspace-wide, including operations started through another `PedelecSession` handle; conflicts reject with `WORKSPACE_BUSY`.
+
+Session `skills.denoModules` belong to the Session/Thread that declares them and are available only to Agent-side `pedelec-deno` execution for that Thread. Workspace runs accept the same Vite-prepared declarations explicitly:
+
+```ts
+const sceneTools = defineDenoModule({
+  name: "scene-tools",
+  entry: "./deno/scene-tools.ts",
 });
+
+const result = await workspace.run(
+  `import { buildScene } from "scene-tools";\nawait buildScene();`,
+  { denoModules: [sceneTools] },
+);
 ```
 
-`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.
+`workspace.run()` does not inherit any Session Deno Modules, and Sessions do not inherit modules used by Workspace runs. The Vite-prepared package is cached privately per Workspace and authorized SDK origin; each run receives an import map containing exactly its requested names. A ready module name is immutable for the lifetime of the Core process, and Workspace-run modules never appear in Agent Host Context. The private Workspace-run cache is reset when Core restarts; project files, assets, and Thread module snapshots are preserved.
+
+The Workspace handle outlives an individual Session conceptually. Ending a Session does not close or delete a custom Workspace, and Pedelec does not delete it during app cleanup. Managed Workspaces remain under Desktop cleanup ownership and are not promised to disappear immediately when a Thread ends. The browser capability is runtime-scoped; reopen the custom Workspace after a Desktop/Core restart when necessary. `pedelec.resumeSession(sessionId)` returns a Session that already includes `session.workspace`; the application does not need to call `openWorkspace()` separately. Same-handle `session.resume()` preserves the existing Workspace handle, subject to the existing Core/thread and transport caveats.
 
 ---
 

package/dist/index.d.ts

@@ -18,11 +18,15 @@ export type Asset = {
 };
 export type DenoModuleDefinition<TName extends string = string> = {
     name: TName;
-    description: string;
+    description?: string;
     entry: string;
-    usage: string;
+    usage?: string;
     preferStdinExecution?: boolean;
 };
+type AgentDenoModuleDefinition<TName extends string = string> = DenoModuleDefinition<TName> & {
+    description: string;
+    usage: string;
+};
 export type ToolArgsSchemaMeta<TDefault extends JsonValue = JsonValue> = {
     description?: string;
     default?: TDefault;
@@ -79,7 +83,7 @@ export type ToolDefinition<TArgs = unknown, TResult = unknown, TName extends str
 export type SkillsInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     guidance: string;
     tools: TTools;
-    denoModules?: readonly DenoModuleDefinition[];
+    denoModules?: readonly AgentDenoModuleDefinition[];
 };
 export type ToolNameOf<TTools extends readonly ToolDefinition[]> = Extract<TTools[number]["name"], string>;
 export type SerializableToolManifest = {
@@ -99,17 +103,19 @@ export type SerializableSkillsManifest = {
     tools: SerializableToolManifest[];
     denoModules?: SerializableDenoModuleManifest[];
 };
-export type CreateSessionWorkspaceInput = {
-    path: string;
+export type WorkspaceRunOptions = {
+    timeoutMs?: number;
+    denoModules?: readonly DenoModuleDefinition[];
+};
+export type WorkspaceRunResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
 };
-export interface WorkspaceFolderPickerResult {
-    path: string;
-    isEmptyFolder: boolean;
-    hasWorkspaceConfig: boolean;
-}
 type CreateSessionSharedInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     skills?: SkillsInput<TTools>;
-    workspace?: CreateSessionWorkspaceInput;
     autoEndOnDisconnect?: boolean;
 };
 type ProfileSessionConfiguration = {
@@ -308,7 +314,29 @@ 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 function defineDenoModule<const TName extends string>(module: DenoModuleDefinition<TName>): DenoModuleDefinition<TName>;
+export declare function defineDenoModule<const TModule extends DenoModuleDefinition>(module: TModule): TModule;
+type PreparedWorkspaceDenoModule = {
+    name: string;
+    runtimeSource: string;
+    typesSource: string;
+};
+export declare class PedelecWorkspace {
+    private readonly client;
+    private workspaceId;
+    private currentPath;
+    constructor(client: Pedelec, workspaceId: string, path: string | null);
+    get path(): string | null;
+    createSession(): Promise<PedelecSession<string>>;
+    createSession<const TTools extends readonly ToolDefinition[]>(input: CreateSessionInput<TTools>): Promise<PedelecSession<ToolNameOf<TTools>>>;
+    listFiles(path?: string): Promise<string[]>;
+    listFolders(path?: string): Promise<string[]>;
+    run(script: string, options?: WorkspaceRunOptions): Promise<WorkspaceRunResult>;
+    /** @internal */
+    get workspaceIdInternal(): string;
+    /** @internal */
+    hydrate(workspaceId: string, path: string | null): void;
+    private list;
+}
 export declare class Pedelec {
     private readonly pageWindow;
     private readonly channelId;
@@ -323,16 +351,25 @@ export declare class Pedelec {
     constructor(options?: PedelecOptions);
     createSession(): Promise<PedelecSession<string>>;
     createSession<const TTools extends readonly ToolDefinition[]>(input: CreateSessionInput<TTools>): Promise<PedelecSession<ToolNameOf<TTools>>>;
+    /** @internal */
+    createSessionInternal<const TTools extends readonly ToolDefinition[]>(input?: CreateSessionInput<TTools>, workspace?: PedelecWorkspace): Promise<PedelecSession<ToolNameOf<TTools>>>;
     private uploadDenoModuleArtifact;
+    /** @internal */
+    uploadWorkspaceDenoModuleArtifact(workspaceId: string, module: PreparedWorkspaceDenoModule): Promise<void>;
+    private uploadDenoModuleArtifactWithTicket;
     private abortSessionSetup;
     private completeSessionSetup;
-    workspaceFolderPicker(): Promise<WorkspaceFolderPickerResult | null>;
+    openWorkspace(): Promise<PedelecWorkspace | null>;
+    openWorkspace(path: string): Promise<PedelecWorkspace>;
     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;
+    /** @internal */
+    requestWithOptions<T>(type: string, payload?: Record<string, unknown>, options?: {
+        timeoutMs?: number | null;
+    }): Promise<T>;
     unregisterSession(sessionId: string): void;
     /** @internal */
     registerExistingSession(session: PedelecSession<any>): void;
@@ -363,6 +400,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     readonly sessionId: string;
     readonly provider: string;
     readonly effortLevel?: EffortLevel;
+    readonly workspace: PedelecWorkspace;
     readonly sessionCreatedAt: number;
     readonly usage: PedelecSessionUsage;
     private status;
@@ -386,7 +424,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private readonly recoveredToolCalls;
     private readonly handledToolRequestIds;
     private authoritativePendingToolRequest;
-    constructor(client: Pedelec, sessionId: string, provider: string, effortLevel?: EffortLevel, inlineToolHandlers?: Map<string, ToolSpecificHandler>, autoEndOnDisconnect?: boolean);
+    constructor(client: Pedelec, sessionId: string, provider: string, workspace: PedelecWorkspace, effortLevel?: EffortLevel, inlineToolHandlers?: Map<string, ToolSpecificHandler>, autoEndOnDisconnect?: boolean);
     prepare(): Promise<void>;
     sendText(text: string): Promise<void>;
     onChat(handler: ChatHandler): () => void;

package/dist/index.js

@@ -39,6 +39,46 @@ export function defineTool(tool) {
 export function defineDenoModule(module) {
     return module;
 }
+function normalizeWorkspaceDenoModules(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw makeError("INVALID_INPUT", "options.denoModules must be an array");
+    }
+    const seen = new Set();
+    return value.map((module, index) => {
+        if (!module || typeof module !== "object" || Array.isArray(module)) {
+            throw makeError("INVALID_INPUT", "options.denoModules entries must be objects", { index });
+        }
+        const rawModule = module;
+        if (!isValidDenoModuleName(rawModule.name)) {
+            throw makeError("INVALID_INPUT", "Deno Module name is invalid", {
+                index,
+                moduleName: rawModule.name,
+            });
+        }
+        if (seen.has(rawModule.name)) {
+            throw makeError("INVALID_INPUT", "duplicate Deno Module name", {
+                moduleName: rawModule.name,
+            });
+        }
+        seen.add(rawModule.name);
+        if (rawModule.preferStdinExecution !== undefined && typeof rawModule.preferStdinExecution !== "boolean") {
+            throw makeError("INVALID_INPUT", "Deno Module preferStdinExecution must be a boolean", {
+                moduleName: rawModule.name,
+            });
+        }
+        const artifact = getPreparedDenoModuleArtifact(module);
+        if (!artifact) {
+            throw makeError("INVALID_INPUT", `Deno module "${rawModule.name}" was not prepared. Configure pedelecVitePlugin() in the Vite project.`, { moduleName: rawModule.name });
+        }
+        return {
+            name: rawModule.name,
+            runtimeSource: artifact.runtimeSource,
+            typesSource: artifact.typesSource,
+        };
+    });
+}
 function normalizeSkillsInput(value) {
     const handlers = new Map();
     if (value === undefined)
@@ -190,6 +230,92 @@ function normalizeToolArgsSchema(argsSchema, toolName) {
         });
     }
 }
+export class PedelecWorkspace {
+    client;
+    workspaceId;
+    currentPath;
+    constructor(client, workspaceId, path) {
+        this.client = client;
+        this.workspaceId = workspaceId;
+        this.currentPath = path;
+    }
+    get path() {
+        return this.currentPath;
+    }
+    async createSession(input = {}) {
+        return this.client.createSessionInternal(input, this);
+    }
+    listFiles(path) {
+        return this.list("workspace_list_files", path);
+    }
+    listFolders(path) {
+        return this.list("workspace_list_folders", path);
+    }
+    run(script, options = {}) {
+        if (typeof script !== "string") {
+            return Promise.reject(makeError("INVALID_INPUT", "script must be a string"));
+        }
+        if (!isPlainObject(options)) {
+            return Promise.reject(makeError("INVALID_INPUT", "options must be an object"));
+        }
+        const timeoutMs = options.timeoutMs;
+        if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs <= 0)) {
+            return Promise.reject(makeError("INVALID_INPUT", "timeoutMs must be a positive integer"));
+        }
+        let modules;
+        try {
+            modules = normalizeWorkspaceDenoModules(options.denoModules);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const run = async () => {
+            if (modules.length > 0) {
+                const prepared = await this.client.request("prepare_workspace_deno_modules", {
+                    workspaceId: this.workspaceId,
+                    moduleNames: modules.map(({ name }) => name),
+                });
+                const missingModuleNames = normalizeWorkspaceDenoModulePrepareResponse(prepared, modules.map(({ name }) => name));
+                const modulesByName = new Map(modules.map((module) => [module.name, module]));
+                for (const name of missingModuleNames) {
+                    const module = modulesByName.get(name);
+                    if (!module) {
+                        throw makeError("SDK_PROTOCOL_ERROR", "prepare_workspace_deno_modules response was inconsistent");
+                    }
+                    await this.client.uploadWorkspaceDenoModuleArtifact(this.workspaceId, module);
+                }
+            }
+            return this.client.requestWithOptions("workspace_run", {
+                workspaceId: this.workspaceId,
+                script,
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(modules.length === 0 ? {} : { denoModules: modules.map(({ name }) => name) }),
+            }, { timeoutMs: null }).then(normalizeWorkspaceRunResponse);
+        };
+        return run();
+    }
+    /** @internal */
+    get workspaceIdInternal() {
+        return this.workspaceId;
+    }
+    /** @internal */
+    hydrate(workspaceId, path) {
+        this.workspaceId = workspaceId;
+        this.currentPath = path;
+    }
+    list(type, path) {
+        if (path !== undefined && typeof path !== "string") {
+            return Promise.reject(makeError("INVALID_INPUT", "path must be a string when provided"));
+        }
+        if (path !== undefined && path.trim().length === 0) {
+            return Promise.reject(makeError("INVALID_INPUT", "path must not be empty when provided"));
+        }
+        return this.client.request(type, {
+            workspaceId: this.workspaceId,
+            ...(path === undefined ? {} : { path }),
+        }).then(normalizeWorkspaceListResponse);
+    }
+}
 export class Pedelec {
     pageWindow;
     channelId;
@@ -212,6 +338,10 @@ export class Pedelec {
         this.connectExtension();
     }
     async createSession(input = {}) {
+        return this.createSessionInternal(input);
+    }
+    /** @internal */
+    async createSessionInternal(input = {}, workspace) {
         const resolvedOrPromise = this.resolveCreateSessionInput(input);
         const resolvedInput = resolvedOrPromise instanceof Promise ? await resolvedOrPromise : resolvedOrPromise;
         const result = await this.request("create_session", {
@@ -221,36 +351,48 @@ export class Pedelec {
                 effort: resolvedInput.effort,
                 effortLevel: resolvedInput.effortLevel,
                 skills: resolvedInput.skills,
-                workspace: resolvedInput.workspace,
+                ...(workspace ? { workspaceId: workspace.workspaceIdInternal } : {}),
                 autoEndOnDisconnect: resolvedInput.autoEndOnDisconnect,
             },
         });
-        if (!result.sessionId) {
-            throw makeError("SDK_PROTOCOL_ERROR", "create_session response did not include sessionId");
+        const normalizedResult = normalizeCreateSessionResponse(result);
+        if (workspace && normalizedResult.workspace.workspaceId !== workspace.workspaceIdInternal) {
+            throw makeError("SDK_PROTOCOL_ERROR", "create_session response returned a different Workspace", {
+                expectedWorkspaceId: workspace.workspaceIdInternal,
+                actualWorkspaceId: normalizedResult.workspace.workspaceId,
+            });
         }
-        if (resolvedInput.model !== undefined && result.explicitModelConfigApplied !== true) {
+        if (resolvedInput.model !== undefined && normalizedResult.explicitModelConfigApplied !== true) {
             const error = makeError("SDK_PROTOCOL_ERROR", "The connected Pedelec Extension/Desktop does not support explicit model configuration. Update Pedelec components and try again.", { feature: "explicitModelConfig" });
-            await this.abortSessionSetup(result.sessionId);
+            await this.abortSessionSetup(normalizedResult.sessionId);
             throw error;
         }
         try {
             for (const module of resolvedInput.denoModules) {
-                await this.uploadDenoModuleArtifact(result.sessionId, module);
+                await this.uploadDenoModuleArtifact(normalizedResult.sessionId, module);
             }
             if (resolvedInput.denoModules.length > 0) {
-                await this.completeSessionSetup(result.sessionId);
+                await this.completeSessionSetup(normalizedResult.sessionId);
             }
         }
         catch (error) {
             // The thread exists at this point but is not exposed through the SDK
             // session registry yet.  Keep the setup failure as the caller-visible
             // error even if the best-effort cleanup transport also fails.
-            await this.abortSessionSetup(result.sessionId);
+            await this.abortSessionSetup(normalizedResult.sessionId);
             throw normalizeError(error, "DENO_MODULE_UPLOAD_FAILED", "Deno Module setup failed");
         }
-        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.effortLevel, resolvedInput.inlineToolHandlers, resolvedInput.autoEndOnDisconnect);
+        const sessionWorkspace = workspace ?? new PedelecWorkspace(this, normalizedResult.workspace.workspaceId, normalizedResult.workspace.path);
+        return this.registerSession(normalizedResult.sessionId, resolvedInput.provider, resolvedInput.effortLevel, resolvedInput.inlineToolHandlers, resolvedInput.autoEndOnDisconnect, sessionWorkspace);
     }
     async uploadDenoModuleArtifact(sessionId, module) {
+        await this.uploadDenoModuleArtifactWithTicket(module, "create_deno_module_upload", { sessionId, moduleName: module.name });
+    }
+    /** @internal */
+    async uploadWorkspaceDenoModuleArtifact(workspaceId, module) {
+        await this.uploadDenoModuleArtifactWithTicket(module, "create_workspace_deno_module_upload", { workspaceId, moduleName: module.name });
+    }
+    async uploadDenoModuleArtifactWithTicket(module, ticketType, ticketPayload) {
         const envelope = JSON.stringify({
             version: 1,
             format: "esm",
@@ -262,9 +404,8 @@ export class Pedelec {
         if (expectedSizeBytes <= 0 || expectedSizeBytes > MAX_ASSET_UPLOAD_BYTES) {
             throw makeError("DENO_MODULE_ARTIFACT_TOO_LARGE", `Deno Module "${module.name}" artifact exceeds the 100 MiB limit`, { moduleName: module.name, expectedSizeBytes, maxSizeBytes: MAX_ASSET_UPLOAD_BYTES });
         }
-        const ticket = await this.request("create_deno_module_upload", {
-            sessionId,
-            moduleName: module.name,
+        const ticket = await this.request(ticketType, {
+            ...ticketPayload,
             expectedSizeBytes,
         });
         if (!isPlainObject(ticket) || typeof ticket.uploadUrl !== "string" || ticket.uploadUrl.length === 0 ||
@@ -316,9 +457,13 @@ export class Pedelec {
     async completeSessionSetup(sessionId) {
         await this.request("complete_session_setup", { sessionId });
     }
-    async workspaceFolderPicker() {
-        const result = await this.requestWithOptions("pick_workspace_folder", {}, { timeoutMs: null });
-        return normalizeWorkspaceFolderPickerResponse(result);
+    async openWorkspace(path) {
+        if (path !== undefined && (typeof path !== "string" || path.trim().length === 0)) {
+            throw makeError("INVALID_INPUT", "path must be a non-empty string when provided");
+        }
+        const result = await this.requestWithOptions("open_workspace", path === undefined ? {} : { path }, path === undefined ? { timeoutMs: null } : {});
+        const workspace = normalizeOpenWorkspaceResponse(result);
+        return workspace === null ? null : new PedelecWorkspace(this, workspace.workspaceId, workspace.path);
     }
     async listProviders() {
         const providers = normalizeProviderInfoList(await this.request("list_providers"));
@@ -358,16 +503,23 @@ export class Pedelec {
         const existing = this.sessions.get(sessionId);
         const session = existing && !existing.isTransportDetached()
             ? existing
-            : this.registerSession(sessionId, "", undefined, new Map(), false);
+            : this.registerSession(sessionId, "", undefined, new Map(), false, new PedelecWorkspace(this, "", null));
         try {
             const result = await this.request("resume_session", {
                 sessionId,
             });
-            if (!result.sessionId) {
-                throw makeError("SDK_PROTOCOL_ERROR", "resume_session response did not include sessionId");
+            const normalizedResult = normalizeResumeSessionResponse(result);
+            if (normalizedResult.sessionId !== sessionId) {
+                throw makeError("SDK_PROTOCOL_ERROR", "resume_session response did not match sessionId");
+            }
+            if (existing && existing.workspace.workspaceIdInternal !== normalizedResult.workspace.workspaceId) {
+                throw makeError("SDK_PROTOCOL_ERROR", "resume_session response returned a different Workspace");
+            }
+            if (session !== existing) {
+                session.workspace.hydrate(normalizedResult.workspace.workspaceId, normalizedResult.workspace.path);
             }
-            if (typeof result.autoEndOnDisconnect === "boolean") {
-                session.setAutoEndOnDisconnect(result.autoEndOnDisconnect);
+            if (typeof normalizedResult.autoEndOnDisconnect === "boolean") {
+                session.setAutoEndOnDisconnect(normalizedResult.autoEndOnDisconnect);
             }
             return session;
         }
@@ -380,6 +532,7 @@ export class Pedelec {
     request(type, payload = {}) {
         return this.requestWithOptions(type, payload);
     }
+    /** @internal */
     requestWithOptions(type, payload = {}, options = {}) {
         let port;
         try {
@@ -394,7 +547,9 @@ export class Pedelec {
             type,
             requestId,
             ...payload,
-            ...(type === "create_session" ? { callerSdkVersion: SDK_VERSION } : {}),
+            ...(type === "create_session" || type === "open_workspace"
+                ? { callerSdkVersion: SDK_VERSION }
+                : {}),
         };
         return new Promise((resolve, reject) => {
             const timeoutMs = options.timeoutMs === undefined ? this.bridgeTimeoutMs : options.timeoutMs;
@@ -514,16 +669,14 @@ export class Pedelec {
             const effort = normalizeCreateSessionEffortInput(raw.effort);
             const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
             const normalizedSkills = normalizeSkillsInput(raw.skills);
-            const workspace = normalizeCreateSessionWorkspaceInput(raw.workspace);
             if (!hasProvider) {
-                return this.resolveDefaultCreateSessionInput(model, effort, undefined, normalizedSkills, workspace, autoEndOnDisconnect);
+                return this.resolveDefaultCreateSessionInput(model, effort, undefined, normalizedSkills, autoEndOnDisconnect);
             }
             return {
                 provider: provider,
                 model,
                 effort,
                 skills: normalizedSkills.manifest,
-                workspace,
                 inlineToolHandlers: normalizedSkills.handlers,
                 denoModules: normalizedSkills.denoModules,
                 autoEndOnDisconnect,
@@ -538,15 +691,13 @@ export class Pedelec {
         }
         const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
         const normalizedSkills = normalizeSkillsInput(raw.skills);
-        const workspace = normalizeCreateSessionWorkspaceInput(raw.workspace);
         if (!hasProvider) {
-            return this.resolveDefaultCreateSessionInput(undefined, undefined, effortLevel, normalizedSkills, workspace, autoEndOnDisconnect);
+            return this.resolveDefaultCreateSessionInput(undefined, undefined, effortLevel, normalizedSkills, autoEndOnDisconnect);
         }
         return {
             provider: provider,
             effortLevel,
             skills: normalizedSkills.manifest,
-            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             denoModules: normalizedSkills.denoModules,
             autoEndOnDisconnect,
@@ -604,7 +755,7 @@ export class Pedelec {
             };
         }
     }
-    async resolveDefaultCreateSessionInput(model, effort, effortLevel, normalizedSkills, workspace, autoEndOnDisconnect) {
+    async resolveDefaultCreateSessionInput(model, effort, effortLevel, normalizedSkills, 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.");
@@ -616,7 +767,6 @@ export class Pedelec {
             effort,
             effortLevel,
             skills: normalizedSkills.manifest,
-            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             denoModules: normalizedSkills.denoModules,
             autoEndOnDisconnect,
@@ -629,13 +779,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(), autoEndOnDisconnect = false) {
+    registerSession(sessionId, provider, effortLevel, inlineToolHandlers = new Map(), autoEndOnDisconnect = false, workspace) {
         const existing = this.sessions.get(sessionId);
         if (existing && !existing.isTransportDetached()) {
             existing.replaceInlineToolHandlers(inlineToolHandlers);
             return existing;
         }
-        const session = new PedelecSession(this, sessionId, provider, effortLevel, inlineToolHandlers, autoEndOnDisconnect);
+        const session = new PedelecSession(this, sessionId, provider, workspace, effortLevel, inlineToolHandlers, autoEndOnDisconnect);
         this.sessions.set(sessionId, session);
         return session;
     }
@@ -766,21 +916,6 @@ export class Pedelec {
         }
     }
 }
-function normalizeCreateSessionWorkspaceInput(value) {
-    if (value === undefined)
-        return undefined;
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw makeError("INVALID_INPUT", "workspace must be an object");
-    }
-    const path = value.path;
-    if (typeof path !== "string") {
-        throw makeError("INVALID_INPUT", "workspace.path must be a string");
-    }
-    if (path.trim().length === 0) {
-        throw makeError("INVALID_INPUT", "workspace.path must not be empty");
-    }
-    return { path };
-}
 function normalizeCreateSessionModelInput(value) {
     if (value === undefined)
         return undefined;
@@ -802,6 +937,7 @@ export class PedelecSession {
     sessionId;
     provider;
     effortLevel;
+    workspace;
     sessionCreatedAt = Date.now();
     usage = { totalTokens: undefined };
     status = "idle";
@@ -825,11 +961,12 @@ export class PedelecSession {
     recoveredToolCalls = new Map();
     handledToolRequestIds = new Set();
     authoritativePendingToolRequest = undefined;
-    constructor(client, sessionId, provider, effortLevel, inlineToolHandlers = new Map(), autoEndOnDisconnect = false) {
+    constructor(client, sessionId, provider, workspace, effortLevel, inlineToolHandlers = new Map(), autoEndOnDisconnect = false) {
         this.client = client;
         this.sessionId = sessionId;
         this.provider = provider;
         this.effortLevel = effortLevel;
+        this.workspace = workspace;
         this.inlineToolHandlers = new Map(inlineToolHandlers);
         this.autoEndOnDisconnect = autoEndOnDisconnect;
     }
@@ -1615,21 +1752,86 @@ function normalizePedelecSettings(value) {
     }
     return { defaultProvider: value.defaultProvider };
 }
-function normalizeWorkspaceFolderPickerResponse(value) {
-    if (!isPlainObject(value) || !("path" in value)) {
-        throw makeError("SDK_PROTOCOL_ERROR", "pick_workspace_folder response had an invalid shape");
+function normalizeWorkspaceCapability(value, context) {
+    if (!isPlainObject(value) || typeof value.workspaceId !== "string" || value.workspaceId.trim().length === 0 ||
+        (value.path !== null && (typeof value.path !== "string" || value.path.length === 0))) {
+        throw makeError("SDK_PROTOCOL_ERROR", `${context} response had an invalid Workspace shape`);
     }
-    const path = value.path;
-    if (path === null)
+    return {
+        workspaceId: value.workspaceId,
+        path: value.path,
+    };
+}
+function normalizeOpenWorkspaceResponse(value) {
+    if (value === null)
         return null;
-    if (typeof path !== "string" || path.length === 0 ||
-        typeof value.isEmptyFolder !== "boolean" || typeof value.hasWorkspaceConfig !== "boolean") {
-        throw makeError("SDK_PROTOCOL_ERROR", "pick_workspace_folder response had an invalid shape");
+    if (!isPlainObject(value) || !("workspace" in value)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "open_workspace response had an invalid shape");
+    }
+    if (value.workspace === null)
+        return null;
+    return normalizeWorkspaceCapability(value.workspace, "open_workspace");
+}
+function normalizeCreateSessionResponse(value) {
+    if (!isPlainObject(value) || typeof value.sessionId !== "string" || value.sessionId.trim().length === 0 ||
+        !("workspace" in value)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "create_session response had an invalid shape");
+    }
+    if ("explicitModelConfigApplied" in value && typeof value.explicitModelConfigApplied !== "boolean") {
+        throw makeError("SDK_PROTOCOL_ERROR", "create_session response had an invalid model configuration flag");
+    }
+    return {
+        sessionId: value.sessionId,
+        workspace: normalizeWorkspaceCapability(value.workspace, "create_session"),
+        ...(typeof value.explicitModelConfigApplied === "boolean"
+            ? { explicitModelConfigApplied: value.explicitModelConfigApplied }
+            : {}),
+    };
+}
+function normalizeResumeSessionResponse(value) {
+    if (!isPlainObject(value) || typeof value.sessionId !== "string" || value.sessionId.trim().length === 0 ||
+        typeof value.autoEndOnDisconnect !== "boolean" || !("workspace" in value)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "resume_session response had an invalid shape");
+    }
+    return {
+        sessionId: value.sessionId,
+        autoEndOnDisconnect: value.autoEndOnDisconnect,
+        workspace: normalizeWorkspaceCapability(value.workspace, "resume_session"),
+    };
+}
+function normalizeWorkspaceListResponse(value) {
+    const paths = Array.isArray(value) ? value : isPlainObject(value) ? value.paths : undefined;
+    if (!Array.isArray(paths) || paths.some((path) => typeof path !== "string")) {
+        throw makeError("SDK_PROTOCOL_ERROR", "workspace list response had an invalid shape");
+    }
+    return paths;
+}
+function normalizeWorkspaceDenoModulePrepareResponse(value, requestedNames) {
+    if (!isPlainObject(value) || !Array.isArray(value.missingModuleNames)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "prepare_workspace_deno_modules response had an invalid shape");
+    }
+    const requested = new Set(requestedNames);
+    const seen = new Set();
+    for (const name of value.missingModuleNames) {
+        if (typeof name !== "string" || !requested.has(name) || seen.has(name)) {
+            throw makeError("SDK_PROTOCOL_ERROR", "prepare_workspace_deno_modules response had unknown or duplicate modules");
+        }
+        seen.add(name);
+    }
+    return value.missingModuleNames;
+}
+function normalizeWorkspaceRunResponse(value) {
+    if (!isPlainObject(value) || !Number.isInteger(value.exitCode) || typeof value.stdout !== "string" ||
+        typeof value.stderr !== "string" || typeof value.stdoutTruncated !== "boolean" ||
+        typeof value.stderrTruncated !== "boolean") {
+        throw makeError("SDK_PROTOCOL_ERROR", "workspace_run response had an invalid shape");
     }
     return {
-        path,
-        isEmptyFolder: value.isEmptyFolder,
-        hasWorkspaceConfig: value.hasWorkspaceConfig,
+        exitCode: value.exitCode,
+        stdout: value.stdout,
+        stderr: value.stderr,
+        stdoutTruncated: value.stdoutTruncated,
+        stderrTruncated: value.stderrTruncated,
     };
 }
 function normalizeProviderInfoList(value) {

package/dist/index.type-test.js

@@ -6,16 +6,16 @@ const spriteTools = defineDenoModule({
     usage: `import { previewActorSource } from "sprite-tools";`,
     preferStdinExecution: true,
 });
+const workspaceTools = defineDenoModule({
+    name: "workspace-tools",
+    entry: "./workspace/workspace-tools.ts",
+});
 const spriteName = spriteTools.name;
 const spriteDefinition = spriteTools;
 void spriteName;
 void spriteDefinition;
-// @ts-expect-error Deno Module usage is required by the public authoring API
-defineDenoModule({
-    name: "missing-usage",
-    description: "Missing usage.",
-    entry: "./agent/missing-usage.ts",
-});
+const workspaceName = workspaceTools.name;
+void workspaceName;
 // @ts-expect-error Deno Module entry remains required at authoring time
 defineDenoModule({
     name: "missing-entry",
@@ -29,9 +29,6 @@ defineDenoModule({
     entry: 42,
     usage: 'import "non-string-entry";',
 });
-function workspaceInputHasPublicType() {
-    return { path: "C:\\workspace\\project" };
-}
 async function typedOnToolNameFromCreateSession() {
     const pedelec = new Pedelec();
     const session = await pedelec.createSession({
@@ -126,10 +123,37 @@ async function noSkillsFallsBackToString() {
     const pedelec = new Pedelec();
     const session = await pedelec.createSession({
         provider: "codex",
-        workspace: { path: "C:\\workspace\\project" },
     });
-    const typedWorkspace = workspaceInputHasPublicType();
-    void typedWorkspace;
+    session.workspace.run("console.log('workspace')", { denoModules: [workspaceTools] });
+    session.workspace.run("console.log('workspace')", { denoModules: [spriteTools] });
+    await pedelec.createSession({
+        provider: "codex",
+        skills: { guidance: "Use modules.", tools: [],
+            // @ts-expect-error Workspace-only declarations do not satisfy Session metadata requirements
+            denoModules: [workspaceTools] },
+    });
+    const descriptionOnly = defineDenoModule({
+        name: "description-only",
+        description: "Missing usage.",
+        entry: "./agent/description-only.ts",
+    });
+    await pedelec.createSession({
+        provider: "codex",
+        skills: { guidance: "Use modules.", tools: [],
+            // @ts-expect-error Session metadata requires usage as well as description
+            denoModules: [descriptionOnly] },
+    });
+    const usageOnly = defineDenoModule({
+        name: "usage-only",
+        entry: "./agent/usage-only.ts",
+        usage: 'import "usage-only";',
+    });
+    await pedelec.createSession({
+        provider: "codex",
+        skills: { guidance: "Use modules.", tools: [],
+            // @ts-expect-error Session metadata requires description as well as usage
+            denoModules: [usageOnly] },
+    });
     session.onTool((name) => {
         const anyString = name;
         return anyString;
@@ -192,14 +216,32 @@ async function availabilityHasPublicType() {
     void availability;
     void promise;
 }
-async function workspaceFolderPickerHasPublicType() {
+async function workspacePublicTypeContract() {
     const pedelec = new Pedelec();
-    const result = pedelec.workspaceFolderPicker();
-    void result;
+    const maybeWorkspace = await pedelec.openWorkspace();
+    const workspace = await pedelec.openWorkspace("C:\\workspace\\project");
+    const files = workspace.listFiles();
+    const folders = workspace.listFolders("src");
+    const run = workspace.run("console.log('hello')", { timeoutMs: 1000 });
+    const session = await workspace.createSession({
+        skills: {
+            guidance: "Use tools.",
+            tools: [defineTool({ name: "workspace_tool", description: "Tool", argsSchema: { type: "object" } })],
+        },
+    });
+    session.workspace;
+    maybeWorkspace?.listFiles();
+    void files;
+    void folders;
+    void run;
+    // @ts-expect-error workspace is now selected through openWorkspace
+    pedelec.createSession({ workspace: { path: "C:\\workspace\\project" } });
+    // @ts-expect-error the removed picker API must not be public
+    pedelec.workspaceFolderPicker();
 }
 function directoryPickerIsRemoved() {
     const pedelec = new Pedelec();
-    // @ts-expect-error directoryPicker was removed in favor of workspaceFolderPicker
+    // @ts-expect-error directoryPicker was removed in favor of openWorkspace
     pedelec.directoryPicker();
 }
 function publicSecurityTypesAreRestricted() {
@@ -222,7 +264,7 @@ void noSkillsFallsBackToString;
 void effortLevelPublicTypeContract;
 void listAssetsHasPublicTypes;
 void availabilityHasPublicType;
-void workspaceFolderPickerHasPublicType;
+void workspacePublicTypeContract;
 void directoryPickerIsRemoved;
 void publicSecurityTypesAreRestricted;
 const baseContext = {

package/dist/version.generated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.3.5";
+export declare const SDK_VERSION = "0.4.1";

package/dist/version.generated.js

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

package/dist/vite.js

@@ -980,7 +980,7 @@ function readDeclaration(node, sourceFile) {
             values.set(name, property.initializer);
     }
     const name = readStringField(values, "name", sourceFile, node);
-    const description = readStringField(values, "description", sourceFile, node);
+    const description = readOptionalStringField(values, "description", sourceFile, node);
     if (values.has("code")) {
         throw declarationError(sourceFile, values.get("code"), "defineDenoModule() does not support inline code; use a static entry");
     }
@@ -993,7 +993,7 @@ function readDeclaration(node, sourceFile) {
     const entry = readStaticString(entryExpression);
     if (entry === null)
         throw declarationError(sourceFile, entryExpression, "defineDenoModule() entry must be a string literal");
-    const usage = readStringField(values, "usage", sourceFile, node);
+    const usage = readOptionalStringField(values, "usage", sourceFile, node);
     return {
         name,
         description,
@@ -1007,6 +1007,16 @@ function readDeclaration(node, sourceFile) {
         entryEnd: entryExpression.end,
     };
 }
+function readOptionalStringField(values, field, sourceFile, node) {
+    if (!values.has(field))
+        return undefined;
+    const expression = values.get(field);
+    const value = readStaticString(expression);
+    if (value === null) {
+        throw declarationError(sourceFile, expression ?? node, `defineDenoModule() field must be a static string when provided: ${field}`);
+    }
+    return value;
+}
 function replaceSourceRange(source, start, end, replacement) {
     return source.slice(0, start) + replacement + source.slice(end);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run test && npm run type-test && npm run build"
   },
   "dependencies": {
-    "typescript": "^5.8.3"
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "vite": "^8.0.0"
@@ -48,8 +48,8 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
-    "vite": "^8.0.0",
-    "vitest": "^4.1.8"
+    "@types/node": "24.13.6",
+    "vite": "8.3.0",
+    "vitest": "4.1.11"
   }
 }