@kaoruisaac/pedelec 0.3.4 → 0.3.5

package/README.md

@@ -318,19 +318,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 +352,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;
@@ -106,23 +107,26 @@ export interface WorkspaceFolderPickerResult {
     isEmptyFolder: boolean;
     hasWorkspaceConfig: boolean;
 }
-type CreateSessionInputWithProvider<TTools extends readonly ToolDefinition[] = readonly ToolDefinition[]> = {
-    provider: ProviderCode;
-    model?: string;
-    effortLevel?: EffortLevel;
+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;

package/dist/index.js

@@ -218,6 +218,7 @@ export class Pedelec {
             input: {
                 provider: resolvedInput.provider,
                 model: resolvedInput.model,
+                effort: resolvedInput.effort,
                 effortLevel: resolvedInput.effortLevel,
                 skills: resolvedInput.skills,
                 workspace: resolvedInput.workspace,
@@ -227,8 +228,8 @@ export class Pedelec {
         if (!result.sessionId) {
             throw makeError("SDK_PROTOCOL_ERROR", "create_session response did not include sessionId");
         }
-        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" });
+        if (resolvedInput.model !== undefined && result.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);
             throw error;
         }
@@ -506,6 +507,31 @@ 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);
+            const workspace = normalizeCreateSessionWorkspaceInput(raw.workspace);
+            if (!hasProvider) {
+                return this.resolveDefaultCreateSessionInput(model, effort, undefined, normalizedSkills, workspace, autoEndOnDisconnect);
+            }
+            return {
+                provider: provider,
+                model,
+                effort,
+                skills: normalizedSkills.manifest,
+                workspace,
+                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");
@@ -514,11 +540,10 @@ export class Pedelec {
         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, workspace, autoEndOnDisconnect);
         }
         return {
             provider: provider,
-            model,
             effortLevel,
             skills: normalizedSkills.manifest,
             workspace,
@@ -579,7 +604,7 @@ export class Pedelec {
             };
         }
     }
-    async resolveDefaultCreateSessionInput(model, effortLevel, normalizedSkills, workspace, autoEndOnDisconnect) {
+    async resolveDefaultCreateSessionInput(model, effort, effortLevel, normalizedSkills, workspace, autoEndOnDisconnect) {
         const settings = await this.getSettings();
         if (!settings.defaultProvider) {
             throw makeError("DEFAULT_PROVIDER_NOT_SET", "Default provider is not set. Open the Pedelec desktop app Settings page and choose a default provider.");
@@ -588,6 +613,7 @@ export class Pedelec {
         return {
             provider: settings.defaultProvider,
             model,
+            effort,
             effortLevel,
             skills: normalizedSkills.manifest,
             workspace,
@@ -763,6 +789,14 @@ 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;
@@ -1569,6 +1603,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);
 }

package/dist/index.type-test.js

@@ -147,7 +147,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

package/dist/version.generated.d.ts

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

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.3.5";

package/package.json

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