@kaoruisaac/pedelec 0.1.26 → 0.2.1

package/README.md

@@ -8,7 +8,17 @@
 - [Pedelec documentation](https://kaoruisaac.github.io/pedelec/)
 - [GitHub repository](https://github.com/kaoruisaac/pedelec)
 
+## Agent Skill
 
+If you use an AI coding agent that supports skills, run the following command from the project you want to integrate with Pedelec:
+
+```bash
+npx skills add kaoruisaac/pedelec
+```
+
+This installs the `pedelec-integration` skill, which guides the agent through SDK setup, session lifecycle, frontend tools, Provider and effort selection, connection/recovery UX, and integration verification. For exact SDK APIs and behavior, continue to use the installed SDK declarations and the official documentation as the source of truth.
+
+---
 Pedelec is a browser SDK and local bridge for applications that want to work with AI coding agents such as Codex, Antigravity, OpenCode, Cursor, Claude Code, or an Ollama-backed agent.
 
 A web application can use Pedelec to:
@@ -88,7 +98,7 @@ const pedelec = new Pedelec();
 
 const session = await pedelec.createSession({
   provider: "codex",
-  model: "gpt-5",
+  effortLevel: "high",
   skills: {
     guidance: "Use get_current_page when you need browser page context.",
     tools: [
@@ -145,6 +155,19 @@ const result = await session.readAsset("/model.glb", "file");
 
 Public asset paths use `/...` with `assets/` as their implicit root; nested paths such as `/results/model.glb` are supported up to 100 MiB.
 
+## Sandbox workspace
+
+By default, each session receives a temporary Desktop-managed sandbox. To use an application-owned workspace that can persist across sessions, pass an absolute path:
+
+```ts
+const session = await pedelec.createSession({
+  provider: "codex",
+  sandbox: { path: "C:\\workspace\\project-a" },
+});
+```
+
+Pedelec creates missing `skills/`, `assets/`, `logs/`, and `tmp/` directories and preserves existing files. It never deletes an explicit workspace, and multiple active sessions may share it. Filesystem write conflicts are the application's responsibility. An explicit path must not overlap Pedelec's managed sandbox root.
+
 ---
 
 ## Creating a Session
@@ -174,31 +197,31 @@ if (availability.available) startUi();
 
 An unavailable extension may be disconnected rather than absent. `desktop.launchAttempted` means the settings probe was sent, not that Desktop was confirmed to have launched. Invalid settings responses also count as Desktop unavailable in this probe.
 
-### Specifying Provider and Model
+### Selecting Provider and Effort
 
 ```ts
 const session = await pedelec.createSession({
-  provider: "opencode",
-  model: "ollama/qwen2.5-coder:14b",
+  provider: "codex",
+  effortLevel: "high",
 });
+
+// Or let Desktop Settings choose the provider.
+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 mapping is not exposed through the SDK.
+
 Currently supported provider codes in the SDK:
 
-| Provider | Code | Example model |
-| --- | --- | --- |
-| Codex | `codex` | `gpt-5` |
-| Antigravity | `antigravity` | Any model ID supported by the provider |
-| OpenCode | `opencode` | `ollama/qwen2.5-coder:14b` |
-| Cursor | `cursor` | `gpt-5` |
-| Claude Code | `claude` | `sonnet` |
-| Ollama | `ollama` | `qwen3-14b-32k:latest` |
+| Provider | Code |
+| --- | --- |
+| Codex | `codex` |
+| Antigravity | `antigravity` |
+| OpenCode | `opencode` |
+| Cursor | `cursor` |
+| Claude Code | `claude` |
+| Ollama | `ollama` |
 
-Ollama sessions are executed by the `pedelec-agent` binary bundled with the Desktop App, not by the `ollama` CLI. You still need to start the local Ollama server yourself and specify a model explicitly or configure `defaultModels.ollama` in Settings:
+Ollama sessions are executed by the bundled `pedelec-agent`. The selected Ollama effort profile must contain a model in Desktop Settings; otherwise Core returns `MODEL_REQUIRED`. Low and high profiles are optional, but there is no fallback between profiles.
 
-```ts
-const session = await pedelec.createSession({
-  provider: "ollama",
-  model: "qwen3-14b-32k:latest",
-});
-```
+`getSettings()` returns only `{ defaultProvider }`. It never exposes provider settings, effort arguments, credentials, or model names.

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export type PedelecOptions = {
     bridgeTimeoutMs?: number;
 };
 export type ProviderCode = "codex" | "antigravity" | "opencode" | "cursor" | "claude" | "ollama";
+export type EffortLevel = "default" | "low" | "high";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
@@ -82,16 +83,21 @@ export type SerializableSkillsManifest = {
     guidance: string;
     tools: SerializableToolManifest[];
 };
+export type CreateSessionSandboxInput = {
+    path: string;
+};
 type CreateSessionInputWithProvider<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider: ProviderCode;
-    model?: string;
+    effortLevel?: EffortLevel;
     skills?: SkillsInput<TTools>;
+    sandbox?: CreateSessionSandboxInput;
     autoEndOnDisconnect?: boolean;
 };
 type CreateSessionInputWithDefaults<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
     provider?: undefined;
-    model?: never;
+    effortLevel?: EffortLevel;
     skills?: SkillsInput<TTools>;
+    sandbox?: CreateSessionSandboxInput;
     autoEndOnDisconnect?: boolean;
 };
 export type CreateSessionInput<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = CreateSessionInputWithProvider<TTools> | CreateSessionInputWithDefaults<TTools>;
@@ -103,7 +109,6 @@ export type ProviderInfo = {
 };
 export type PedelecSettings = {
     defaultProvider: ProviderCode | null;
-    defaultModels: Partial<Record<ProviderCode, string>>;
 };
 export type ApprovalStatus = {
     installed: boolean;
@@ -135,7 +140,7 @@ export type PedelecSessionStatus = "idle" | "running" | "waiting_tool_result" |
 export type PedelecEventContext = {
     sessionId: string;
     provider: string;
-    model?: string;
+    effortLevel?: EffortLevel;
     sessionCreatedAt: number;
     eventReceivedAt?: number;
     eventEmittedAt: number;
@@ -237,7 +242,6 @@ export declare class Pedelec {
     private resolveCreateSessionInput;
     checkAvailability(): Promise<PedelecAvailability>;
     private resolveDefaultCreateSessionInput;
-    private resolveProviderOnlyCreateSessionInput;
     private assertDefaultProviderAvailable;
     private registerSession;
     private ensureExtensionPort;
@@ -253,7 +257,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private readonly client;
     readonly sessionId: string;
     readonly provider: string;
-    readonly model?: string;
+    readonly effortLevel?: EffortLevel;
     readonly sessionCreatedAt: number;
     private status;
     private pendingSend;
@@ -271,7 +275,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private readonly errorHandlers;
     private readonly statusHandlers;
     private readonly endedHandlers;
-    constructor(client: Pedelec, sessionId: string, provider: string, model?: string, inlineToolHandlers?: Map<string, ToolSpecificHandler>);
+    constructor(client: Pedelec, sessionId: string, provider: string, effortLevel?: EffortLevel, inlineToolHandlers?: Map<string, ToolSpecificHandler>);
     prepare(): Promise<void>;
     sendText(text: string): Promise<void>;
     onChat(handler: ChatHandler): () => void;

package/dist/index.js

@@ -138,15 +138,16 @@ export class Pedelec {
         const result = await this.request("create_session", {
             input: {
                 provider: resolvedInput.provider,
-                model: resolvedInput.model,
+                effortLevel: resolvedInput.effortLevel,
                 skills: resolvedInput.skills,
+                sandbox: resolvedInput.sandbox,
                 autoEndOnDisconnect: resolvedInput.autoEndOnDisconnect,
             },
         });
         if (!result.sessionId) {
             throw makeError("SDK_PROTOCOL_ERROR", "create_session response did not include sessionId");
         }
-        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.model, resolvedInput.inlineToolHandlers);
+        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.effortLevel, resolvedInput.inlineToolHandlers);
     }
     async listProviders() {
         return normalizeProviderInfoList(await this.request("list_providers"));
@@ -230,24 +231,24 @@ export class Pedelec {
         const raw = (input ?? {});
         const provider = typeof raw.provider === "string" ? raw.provider.trim() : "";
         const hasProvider = provider.length > 0;
-        const hasModel = raw.model !== undefined;
+        if (raw.model !== undefined) {
+            throw makeError("INVALID_INPUT", "model is no longer supported; configure provider effort profiles in Desktop Settings");
+        }
+        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);
-        if (!hasProvider && hasModel) {
-            throw makeError("INVALID_INPUT", "model cannot be provided without provider");
-        }
-        const userModel = typeof raw.model === "string" ? raw.model : undefined;
+        const sandbox = normalizeCreateSessionSandboxInput(raw.sandbox);
         if (!hasProvider) {
-            return this.resolveDefaultCreateSessionInput(normalizedSkills, autoEndOnDisconnect);
-        }
-        let model = userModel;
-        if (model === undefined) {
-            return this.resolveProviderOnlyCreateSessionInput(provider, normalizedSkills, autoEndOnDisconnect);
+            return this.resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, sandbox, autoEndOnDisconnect);
         }
         return {
             provider: provider,
-            model,
+            effortLevel,
             skills: normalizedSkills.manifest,
+            sandbox,
             inlineToolHandlers: normalizedSkills.handlers,
             autoEndOnDisconnect,
         };
@@ -304,7 +305,7 @@ export class Pedelec {
             };
         }
     }
-    async resolveDefaultCreateSessionInput(normalizedSkills, autoEndOnDisconnect) {
+    async resolveDefaultCreateSessionInput(effortLevel, normalizedSkills, sandbox, 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.");
@@ -312,18 +313,9 @@ export class Pedelec {
         await this.assertDefaultProviderAvailable(settings.defaultProvider);
         return {
             provider: settings.defaultProvider,
-            model: settings.defaultModels[settings.defaultProvider] ?? undefined,
-            skills: normalizedSkills.manifest,
-            inlineToolHandlers: normalizedSkills.handlers,
-            autoEndOnDisconnect,
-        };
-    }
-    async resolveProviderOnlyCreateSessionInput(provider, normalizedSkills, autoEndOnDisconnect) {
-        const settings = await this.getSettings();
-        return {
-            provider,
-            model: settings.defaultModels[provider] ?? undefined,
+            effortLevel,
             skills: normalizedSkills.manifest,
+            sandbox,
             inlineToolHandlers: normalizedSkills.handlers,
             autoEndOnDisconnect,
         };
@@ -335,13 +327,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, model, inlineToolHandlers = new Map()) {
+    registerSession(sessionId, provider, effortLevel, inlineToolHandlers = new Map()) {
         const existing = this.sessions.get(sessionId);
         if (existing && !existing.isTransportDetached()) {
             existing.replaceInlineToolHandlers(inlineToolHandlers);
             return existing;
         }
-        const session = new PedelecSession(this, sessionId, provider, model, inlineToolHandlers);
+        const session = new PedelecSession(this, sessionId, provider, effortLevel, inlineToolHandlers);
         this.sessions.set(sessionId, session);
         return session;
     }
@@ -450,11 +442,26 @@ export class Pedelec {
         }
     }
 }
+function normalizeCreateSessionSandboxInput(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw makeError("INVALID_INPUT", "sandbox must be an object");
+    }
+    const path = value.path;
+    if (typeof path !== "string") {
+        throw makeError("INVALID_INPUT", "sandbox.path must be a string");
+    }
+    if (path.trim().length === 0) {
+        throw makeError("INVALID_INPUT", "sandbox.path must not be empty");
+    }
+    return { path };
+}
 export class PedelecSession {
     client;
     sessionId;
     provider;
-    model;
+    effortLevel;
     sessionCreatedAt = Date.now();
     status = "idle";
     pendingSend = null;
@@ -472,11 +479,11 @@ export class PedelecSession {
     errorHandlers = new Set();
     statusHandlers = new Set();
     endedHandlers = new Set();
-    constructor(client, sessionId, provider, model, inlineToolHandlers = new Map()) {
+    constructor(client, sessionId, provider, effortLevel, inlineToolHandlers = new Map()) {
         this.client = client;
         this.sessionId = sessionId;
         this.provider = provider;
-        this.model = model;
+        this.effortLevel = effortLevel;
         this.inlineToolHandlers = new Map(inlineToolHandlers);
     }
     prepare() {
@@ -930,7 +937,7 @@ export class PedelecSession {
         return {
             sessionId: this.sessionId,
             provider: this.provider,
-            model: this.model,
+            ...(this.effortLevel ? { effortLevel: this.effortLevel } : {}),
             sessionCreatedAt: this.sessionCreatedAt,
             ...(meta.eventReceivedAt === undefined ? {} : { eventReceivedAt: meta.eventReceivedAt }),
             eventEmittedAt: Date.now(),
@@ -993,22 +1000,18 @@ function isProviderCode(value) {
     return value === "codex" || value === "antigravity" || value === "opencode" ||
         value === "cursor" || value === "claude" || value === "ollama";
 }
+function isEffortLevel(value) {
+    return value === "default" || value === "low" || value === "high";
+}
 function isPlainObject(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function normalizePedelecSettings(value) {
     if (!isPlainObject(value) || (value.defaultProvider !== null && !isProviderCode(value.defaultProvider)) ||
-        !isPlainObject(value.defaultModels)) {
+        "defaultModels" in value || "providerSettings" in value) {
         throw makeError("SDK_PROTOCOL_ERROR", "get_settings response had invalid shape");
     }
-    const defaultModels = {};
-    for (const [code, model] of Object.entries(value.defaultModels)) {
-        if (!isProviderCode(code) || typeof model !== "string") {
-            throw makeError("SDK_PROTOCOL_ERROR", "get_settings response had invalid shape");
-        }
-        defaultModels[code] = model;
-    }
-    return { defaultProvider: value.defaultProvider, defaultModels };
+    return { defaultProvider: value.defaultProvider };
 }
 function normalizeProviderInfoList(value) {
     if (!Array.isArray(value))

package/dist/index.type-test.js

@@ -1,4 +1,7 @@
 import { Pedelec, defineTool, } from "./index";
+function sandboxInputHasPublicType() {
+    return { path: "C:\\workspace\\project" };
+}
 async function typedOnToolNameFromCreateSession() {
     const pedelec = new Pedelec();
     const session = await pedelec.createSession({
@@ -79,7 +82,12 @@ async function resumedSessionFallsBackToString() {
 }
 async function noSkillsFallsBackToString() {
     const pedelec = new Pedelec();
-    const session = await pedelec.createSession({ provider: "codex" });
+    const session = await pedelec.createSession({
+        provider: "codex",
+        sandbox: { path: "C:\\workspace\\project" },
+    });
+    const typedSandbox = sandboxInputHasPublicType();
+    void typedSandbox;
     session.onTool((name) => {
         const anyString = name;
         return anyString;
@@ -88,6 +96,17 @@ async function noSkillsFallsBackToString() {
         return { ok: true };
     });
 }
+async function effortLevelPublicTypeContract() {
+    const pedelec = new Pedelec();
+    await pedelec.createSession({ effortLevel: "high" });
+    const session = await pedelec.createSession({ provider: "codex", effortLevel: "low" });
+    // @ts-expect-error model is no longer a createSession option
+    pedelec.createSession({ provider: "codex", model: "gpt-5" });
+    // @ts-expect-error session no longer exposes provider model
+    session.model;
+    // @ts-expect-error unsupported effort level
+    pedelec.createSession({ effortLevel: "medium" });
+}
 async function listAssetsHasPublicTypes() {
     const pedelec = new Pedelec();
     const session = await pedelec.resumeSession("thread_1");
@@ -132,6 +151,7 @@ function publicSecurityTypesAreRestricted() {
 void typedOnToolNameFromCreateSession;
 void resumedSessionFallsBackToString;
 void noSkillsFallsBackToString;
+void effortLevelPublicTypeContract;
 void listAssetsHasPublicTypes;
 void availabilityHasPublicType;
 void publicSecurityTypesAreRestricted;

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.1.26",
+  "version": "0.2.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "skills",
     "README.md",
     "LICENSE"
   ],