Providers and effort profiles

Providers and effort profiles

A Pedelec session runs through one provider. The application chooses the provider and an intent-level resource profile; the Desktop user chooses the concrete provider arguments behind that profile.

Provider codes

Provider codes are stable lowercase values:

codex, antigravity, opencode, cursor, claude, and ollama.

listProviders() exposes only provider name, code, availability, isDefault, and an optional diagnostic error. isDefault reflects the current Desktop default provider and is independent of available, including when the default provider is unavailable. Executable paths, credentials, model catalogs, and profile effort arguments remain Desktop-internal. Applications may pass a provider-native model identifier to explicit createSession({ model, effort? }); Pedelec does not maintain a catalog or capability matrix. SDK and Extension response parsing ignores newly added fields for forward compatibility.

Effort levels

The shared vocabulary is:

type EffortLevel = "default" | "low" | "high";

default is the user’s normal profile and roughly represents medium intent, but Pedelec does not force a native provider effort value. A profile can select a model, a provider-native effort, or both where the provider supports them. The native value does not have to equal the Pedelec level name.

Provider-native values are still validated against the supported provider CLI contract; they are not arbitrary passthrough strings.

The application can omit the provider and let Desktop defaultProvider decide:

await pedelec.createSession({ effortLevel: "high" });

It can also select both explicitly:

await pedelec.createSession({
  provider: "codex",
  effortLevel: "low",
});

Explicit model configuration

effortLevel and model select different, mutually exclusive modes. Profile mode uses the complete Desktop profile:

await pedelec.createSession({
  provider: "codex",
  effortLevel: "high",
});

Explicit mode uses only the requested model and optional native effort:

await pedelec.createSession({
  provider: "codex",
  model: "gpt-x",
  effort: "max",
});

Model-only explicit mode uses provider-default effort behavior. The explicit configuration is snapshotted independently; changing Desktop profiles later does not change the session. The identifier is not checked against a Pedelec model list; provider availability, model validity, effort support, and account entitlement are provider-dependent and may be reported when the provider starts.

Omitting effortLevel in profile mode selects default. An empty low or high profile for a non-Ollama provider sends no explicit model or effort arguments. There is no fallback from low or high to default.

SDK settings boundary

The SDK can read only:

type PedelecSettings = {
  defaultProvider: ProviderCode | null;
};

It cannot inspect providerSettings, effortsArgs, credentials, or the Desktop profile’s actual model names. Configure the profile in Desktop Settings for profile mode, or pass an explicit provider-native model and optional effort for explicit mode.

Ollama

Ollama is the exception to empty profiles: profile mode requires a --model pair in the selected profile. If it is absent, Core returns MODEL_REQUIRED; it never falls back to the default profile. Explicit { model } mode supplies the model directly and does not require a profile model. Ollama does not currently accept explicit effort. Desktop Settings requires a populated default Ollama model when Ollama is the selected default provider, while low and high remain optional.

Ollama uses the bundled pedelec-agent and the endpoint configured in Desktop Settings. Without a profile model in profile mode, Core returns MODEL_REQUIRED; explicit model mode does not consult that profile. Low and high profiles never fall back to default.

Provider-native skill isolation

Pedelec limits provider-native skill or command discovery so it does not compete with the App-defined Pedelec tool registry. This policy does not remove the provider’s normal sandbox/file capabilities or Pedelec App tools.

Current runtime behavior is provider-specific:

• Codex starts with skills.include_instructions=false.
• Antigravity starts with --disable-slash-commands.
• Persistent Claude Code does not pass --disable-slash-commands, so Claude skills remain available.
• OpenCode overlays its permission configuration with "skill": "deny" when the existing permission value can be safely parsed as an object; an invalid or non-object parent value is left unchanged instead of being replaced.
• Cursor and Ollama currently receive no additional provider-native skill override.

These are runtime implementation details rather than SDK configuration. Applications should define the tools they want the agent to use through skills.tools and should not depend on provider-native skills being discoverable.

Session snapshots

Core resolves the selected profile when a session is created and stores a snapshot of its validated argv tokens. Editing Desktop Settings later does not change commands for that existing or resumed session.