Creating sessions

Creating sessions

The SDK creates a session handle. Choose either Desktop profile mode, where effortLevel selects the complete configured profile, or explicit model mode, where model and optional provider-native effort are snapshotted independently of Desktop profiles.

Choose a workspace first

The managed convenience path is pedelec.createSession(). It creates a managed Workspace automatically, exposes it as session.workspace, and does not accept a Workspace option. Use the explicit flow below when the application needs a custom Workspace.

For an application-managed workspace, open the workspace before creating a session. With no path, Pedelec opens the native folder picker and returns null when the user cancels:

const workspace = await pedelec.openWorkspace();
if (!workspace) return;

const session = await workspace.createSession({
  provider: "codex",
  effortLevel: "high",
});

An explicit path uses the same validation and initialization flow without opening a picker:

const workspace = await pedelec.openWorkspace("C:\\workspace\\project-a");
const session = await workspace.createSession({ provider: "codex" });

PedelecWorkspace exposes path, createSession(), listFiles(), listFolders(), uploadFile(), readFile(), and run(). See the PedelecWorkspace reference for method semantics, security, concurrency, and lifetime. A managed session created with pedelec.createSession() also exposes its managed Workspace as session.workspace; the Workspace handle remains available after session.end().

const session = await pedelec.createSession();

When no input is supplied, SDK reads only defaultProvider, validates its availability, and uses effort level default.

Choose an effort level

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

This provider-independent form is useful when the application describes intent while the Desktop user owns provider configuration.

Choose provider, model, and effort

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

provider and effortLevel select Desktop profile mode:

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

Explicit model mode is independent:

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

model is trimmed and used directly. Model-only requests are valid and use provider-default effort behavior. effort requires model, and explicit mode cannot include effortLevel. The SDK and Extension pass the declarative values through, while Core validates provider support and stores the final immutable snapshot. The SDK does not maintain a model catalog; availability, model validity, effort support, and entitlement remain provider-dependent.

For explicit model mode, Core returns explicitModelConfigApplied: true. The SDK requires this acknowledgment before uploading Runtime Modules or exposing the session; an older Extension/Desktop combination is aborted and reported as incompatible instead of silently using profile semantics.

Skills

Effort selection composes with skills. Application-owned Workspaces are selected through openWorkspace() and then passed implicitly by calling workspace.createSession():

const session = await pedelec.createSession({
  provider: "claude",
  effortLevel: "default",
  skills: {
    guidance: "Use the declared tools and report structured failures.",
    tools,
  },
});

Desktop Settings is the model source only in profile mode. Explicit model mode does not read or merge with a Desktop profile.

Runtime Modules

Configure the Vite plugin, then mount modules for an Agent Session through skills.runtimeModules:

vite.config.ts

import { defineConfig } from "vite";
import { pedelecVitePlugin } from "@kaoruisaac/pedelec/vite";

export default defineConfig({ plugins: [pedelecVitePlugin()] });

import { defineRuntimeModule } from "@kaoruisaac/pedelec";

const projectTools = defineRuntimeModule({
  name: "project-tools",
  description: "Utilities for project data processing.",
  entry: "./agent/project-tools.ts",
  usage: `import { buildManifest } from "project-tools";`,
  preferStdinExecution: true,
});

const session = await pedelec.createSession({
  skills: {
    guidance: "Use project-tools for project data tasks.",
    tools: [],
    runtimeModules: [projectTools],
  },
});

Session Runtime Modules are scoped to that Thread’s Agent. See TypeScript Runtime in Pedelec for choosing an execution path, Runtime Modules for preparation and use, and Tools API for exact contracts.

Ollama

The selected Ollama profile must contain a model in profile mode, so an empty selected profile returns MODEL_REQUIRED. Explicit createSession({ provider: "ollama", model: "qwen3:30b" }) supplies the model directly and is valid; Ollama currently does not accept explicit effort. Low and high do not fall back to default.

Metadata and resume

Profile-mode sessions expose the normalized effortLevel (default, low, or high) on the session and event contexts. Explicit model sessions expose undefined because they did not select a Desktop profile. A fresh resumeSession(sessionId) handle may not recover provider or effort metadata because the bridge currently returns only the session ID; Core still uses its stored command snapshot.

session.onChat((_text, context) => {
  console.log(context.provider, context.effortLevel);
});

autoEndOnDisconnect remains available for lifecycle control. Tool type inference is unchanged.

Explicit Full Runtime Access

Sandbox is the default. Full Access requires three separate conditions: an Instance created with runtimeFullAccess: true, explicit user approval of both Allow Agent Sessions and Allow Full Runtime Access in the Extension, and runtimeFullAccess: true on session creation.

const privileged = new Pedelec({ runtimeFullAccess: true });
// After the user explicitly grants both permissions in the Extension:
const sandbox = await privileged.createSession({ runtimeFullAccess: false });
const full = await privileged.createSession({ runtimeFullAccess: true });

Review the Extension permissions before creating sessions. An Instance requesting Full Access cannot create any session with only the Agent Sessions grant, including a Sandbox session. A standard Instance cannot request a Full Access session, even if another Instance on the same Origin has permission. Ordinary Origin approval never substitutes for the Full Access grant; the Popup offers an additional permission review with Full Access unchecked by default. getApprovalStatus() only reads status and does not open that review.

The Thread mode is fixed at creation and preserved on resume. Instances on the same Origin and Threads in the same Workspace retain their own requested modes. workspace.run() defaults to Sandbox and can request Full Access per invocation, and Provider sandbox settings are unchanged. Full Access changes the TypeScript Runtime’s OS permissions only. Revoking the Full Access grant rejects subsequent high-privilege execution and attempts to cancel affected running processes; unrelated Origins retain their grants.

Upgrade the SDK, Extension, and Desktop together when using Full Access. Missing mode acknowledgment is an error, never a successful downgrade. See Error Codes for authorization and protocol failures.