@kaoruisaac/pedelec 0.3.4 → 0.4.0

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.
 
 ---
 
@@ -318,19 +361,28 @@ const session = await pedelec.createSession({
 const defaultSession = await pedelec.createSession({ effortLevel: "low" });
 ```
 
-The SDK uses the provider-independent effort levels `default`, `low`, and `high`. An omitted level means `default`. Desktop users map each provider's profiles to concrete model and native effort arguments. That profile remains the default source of both values, but an application may optionally override only the model for one session:
+The SDK supports two mutually exclusive session configuration modes. In Desktop profile mode, `effortLevel` selects the complete Desktop profile, including its configured model and native effort arguments. An omitted level means `default`:
 
 ```ts
-const specializedSession = await pedelec.createSession({
+const profileSession = await pedelec.createSession({
   provider: "codex",
   effortLevel: "high",
+});
+```
+
+In explicit model mode, `model` selects the provider-native model directly and does not read or inherit any Desktop profile. The optional `effort` is provider-native and uses `low`, `medium`, `high`, `xhigh`, or `max`:
+
+```ts
+const modelSession = await pedelec.createSession({
+  provider: "codex",
   model: "gpt-x",
+  effort: "max",
 });
 ```
 
-`model` is an optional provider-native identifier. Omitting it preserves the existing Desktop-profile behavior; providing it does not disable `effortLevel`, replaces only the selected profile's model, and leaves its native effort arguments intact. The SDK does not expose or maintain a model catalog, and it does not translate the identifier into provider CLI flags. Model validity and account entitlement remain provider-dependent, so an invalid or unavailable model may fail when the provider starts.
+Model-only requests are valid and use the provider's default effort behavior. `effort` requires `model`; `model` cannot be combined with `effortLevel`. The SDK does not expose or maintain a model catalog, and it does not translate the identifier into provider CLI flags. Model validity, effort support, and account entitlement remain provider-dependent, so an invalid or unavailable configuration may fail when the provider starts.
 
-For an explicit model, the SDK requires an acknowledgment from Core that the override was applied before it exposes the session or starts Deno Module setup. If the connected Extension/Desktop is too old to provide that acknowledgment, the SDK aborts the newly created setup and reports a compatibility error instead of silently ignoring the model.
+Explicit model requests require an `explicitModelConfigApplied` acknowledgment from Core before the SDK exposes the session or starts Deno Module setup. If the connected Extension/Desktop is too old to provide that acknowledgment, the SDK aborts the newly created setup and reports a compatibility error instead of silently using a different configuration.
 
 Currently supported provider codes in the SDK:
 
@@ -343,6 +395,6 @@ Currently supported provider codes in the SDK:
 | Claude Code | `claude` |
 | Ollama | `ollama` |
 
-Ollama sessions are executed by the bundled `pedelec-agent`. The selected Ollama effort profile must contain a model unless `createSession({ model })` supplies the explicit model override; otherwise Core returns `MODEL_REQUIRED`. Low and high profiles are optional, but there is no fallback between profiles.
+Ollama sessions are executed by the bundled `pedelec-agent`. In profile mode, the selected Ollama effort profile must contain a model; otherwise Core returns `MODEL_REQUIRED`. In explicit model mode, `{ model }` supplies the model directly. Ollama currently does not accept an explicit `effort`. Low and high profiles are optional, but there is no fallback between profiles.
 
 `getSettings()` returns only `{ defaultProvider }`. It never exposes provider settings, effort arguments, credentials, or model names.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type PedelecOptions = {
 };
 export type ProviderCode = "codex" | "antigravity" | "opencode" | "cursor" | "claude" | "ollama";
 export type EffortLevel = "default" | "low" | "high";
+export type Effort = "low" | "medium" | "high" | "xhigh" | "max";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
@@ -17,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;
@@ -78,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 = {
@@ -98,31 +103,36 @@ export type SerializableSkillsManifest = {
     tools: SerializableToolManifest[];
     denoModules?: SerializableDenoModuleManifest[];
 };
-export type CreateSessionWorkspaceInput = {
-    path: string;
+export type WorkspaceRunOptions = {
+    timeoutMs?: number;
+    denoModules?: readonly DenoModuleDefinition[];
 };
-export interface WorkspaceFolderPickerResult {
-    path: string;
-    isEmptyFolder: boolean;
-    hasWorkspaceConfig: boolean;
-}
-type CreateSessionInputWithProvider<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
-    provider: ProviderCode;
-    model?: string;
-    effortLevel?: EffortLevel;
+export type WorkspaceRunResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+};
+type CreateSessionSharedInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     skills?: SkillsInput<TTools>;
-    workspace?: CreateSessionWorkspaceInput;
     autoEndOnDisconnect?: boolean;
 };
-type CreateSessionInputWithDefaults<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
-    provider?: undefined;
-    model?: string;
+type ProfileSessionConfiguration = {
+    model?: never;
+    effort?: never;
     effortLevel?: EffortLevel;
-    skills?: SkillsInput<TTools>;
-    workspace?: CreateSessionWorkspaceInput;
-    autoEndOnDisconnect?: boolean;
 };
-export type CreateSessionInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = CreateSessionInputWithProvider<TTools> | CreateSessionInputWithDefaults<TTools>;
+type ExplicitModelSessionConfiguration = {
+    model: string;
+    effort?: Effort;
+    effortLevel?: never;
+};
+export type CreateSessionInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = (CreateSessionSharedInput<TTools> & {
+    provider?: ProviderCode;
+} & ProfileSessionConfiguration) | (CreateSessionSharedInput<TTools> & {
+    provider?: ProviderCode;
+} & ExplicitModelSessionConfiguration);
 export type ProviderInfo = {
     name: string;
     code: ProviderCode;
@@ -304,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;
@@ -319,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;
@@ -359,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;
@@ -382,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,44 +338,61 @@ 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", {
             input: {
                 provider: resolvedInput.provider,
                 model: resolvedInput.model,
+                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.modelOverrideApplied !== true) {
-            const error = makeError("SDK_PROTOCOL_ERROR", "The connected Pedelec Extension/Desktop does not support createSession model override. Update Pedelec components and try again.", { feature: "modelOverride" });
-            await this.abortSessionSetup(result.sessionId);
+        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(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",
@@ -261,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 ||
@@ -315,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"));
@@ -357,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 (typeof result.autoEndOnDisconnect === "boolean") {
-                session.setAutoEndOnDisconnect(result.autoEndOnDisconnect);
+            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 normalizedResult.autoEndOnDisconnect === "boolean") {
+                session.setAutoEndOnDisconnect(normalizedResult.autoEndOnDisconnect);
             }
             return session;
         }
@@ -379,6 +532,7 @@ export class Pedelec {
     request(type, payload = {}) {
         return this.requestWithOptions(type, payload);
     }
+    /** @internal */
     requestWithOptions(type, payload = {}, options = {}) {
         let port;
         try {
@@ -393,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;
@@ -506,22 +662,42 @@ export class Pedelec {
         const provider = typeof raw.provider === "string" ? raw.provider.trim() : "";
         const hasProvider = provider.length > 0;
         const model = normalizeCreateSessionModelInput(raw.model);
+        if (model !== undefined) {
+            if (raw.effortLevel !== undefined) {
+                throw makeError("INVALID_INPUT", "effortLevel cannot be combined with model");
+            }
+            const effort = normalizeCreateSessionEffortInput(raw.effort);
+            const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
+            const normalizedSkills = normalizeSkillsInput(raw.skills);
+            if (!hasProvider) {
+                return this.resolveDefaultCreateSessionInput(model, effort, undefined, normalizedSkills, autoEndOnDisconnect);
+            }
+            return {
+                provider: provider,
+                model,
+                effort,
+                skills: normalizedSkills.manifest,
+                inlineToolHandlers: normalizedSkills.handlers,
+                denoModules: normalizedSkills.denoModules,
+                autoEndOnDisconnect,
+            };
+        }
+        if (raw.effort !== undefined) {
+            throw makeError("INVALID_INPUT", "effort requires model");
+        }
         const effortLevel = raw.effortLevel === undefined ? "default" : raw.effortLevel;
         if (!isEffortLevel(effortLevel)) {
             throw makeError("INVALID_INPUT", "effortLevel must be one of default, low, or high");
         }
         const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
         const normalizedSkills = normalizeSkillsInput(raw.skills);
-        const workspace = normalizeCreateSessionWorkspaceInput(raw.workspace);
         if (!hasProvider) {
-            return this.resolveDefaultCreateSessionInput(model, effortLevel, normalizedSkills, workspace, autoEndOnDisconnect);
+            return this.resolveDefaultCreateSessionInput(undefined, undefined, effortLevel, normalizedSkills, autoEndOnDisconnect);
         }
         return {
             provider: provider,
-            model,
             effortLevel,
             skills: normalizedSkills.manifest,
-            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             denoModules: normalizedSkills.denoModules,
             autoEndOnDisconnect,
@@ -579,7 +755,7 @@ export class Pedelec {
             };
         }
     }
-    async resolveDefaultCreateSessionInput(model, 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.");
@@ -588,9 +764,9 @@ export class Pedelec {
         return {
             provider: settings.defaultProvider,
             model,
+            effort,
             effortLevel,
             skills: normalizedSkills.manifest,
-            workspace,
             inlineToolHandlers: normalizedSkills.handlers,
             denoModules: normalizedSkills.denoModules,
             autoEndOnDisconnect,
@@ -603,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;
     }
@@ -740,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;
@@ -763,11 +924,20 @@ function normalizeCreateSessionModelInput(value) {
     }
     return value.trim();
 }
+function normalizeCreateSessionEffortInput(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isEffort(value)) {
+        throw makeError("INVALID_INPUT", "effort must be one of low, medium, high, xhigh, or max");
+    }
+    return value;
+}
 export class PedelecSession {
     client;
     sessionId;
     provider;
     effortLevel;
+    workspace;
     sessionCreatedAt = Date.now();
     usage = { totalTokens: undefined };
     status = "idle";
@@ -791,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;
     }
@@ -1569,6 +1740,9 @@ function isProviderCode(value) {
 function isEffortLevel(value) {
     return value === "default" || value === "low" || value === "high";
 }
+function isEffort(value) {
+    return value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max";
+}
 function isPlainObject(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -1578,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`);
+    }
+    return {
+        workspaceId: value.workspaceId,
+        path: value.path,
+    };
+}
+function normalizeOpenWorkspaceResponse(value) {
+    if (value === null)
+        return null;
+    if (!isPlainObject(value) || !("workspace" in value)) {
+        throw makeError("SDK_PROTOCOL_ERROR", "open_workspace response had an invalid shape");
     }
-    const path = value.path;
-    if (path === null)
+    if (value.workspace === 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");
+    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;
@@ -147,7 +171,17 @@ async function effortLevelPublicTypeContract() {
     // @ts-expect-error the removed sandbox picker is not part of the public contract
     pedelec.sandboxFolderPicker();
     await pedelec.createSession({ model: "gpt-5" });
+    await pedelec.createSession({ provider: "codex", model: "gpt-5", effort: "max" });
+    const explicitEffort = "xhigh";
+    await pedelec.createSession({ provider: "codex", model: "gpt-5", effort: explicitEffort });
+    // @ts-expect-error explicit model mode cannot select a Desktop effort profile
     await pedelec.createSession({ provider: "codex", model: "gpt-5", effortLevel: "high" });
+    // @ts-expect-error explicit effort requires an explicit model
+    await pedelec.createSession({ provider: "codex", effort: "high" });
+    // @ts-expect-error explicit model, effort, and Desktop profile are mutually exclusive
+    await pedelec.createSession({ model: "gpt-5", effort: "max", effortLevel: "low" });
+    // @ts-expect-error unsupported provider-native effort value
+    await pedelec.createSession({ model: "gpt-5", effort: "default" });
     // @ts-expect-error session no longer exposes provider model
     session.model;
     // @ts-expect-error unsupported effort level
@@ -182,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() {
@@ -212,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.4";
+export declare const SDK_VERSION = "0.4.0";

package/dist/version.generated.js

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

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.4",
+  "version": "0.4.0",
   "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"
   }
 }