Creating sessions

Creating sessions

The SDK creates a session handle and Core resolves the provider’s Desktop-configured effort profile.

Choose a workspace first

For an application-managed workspace, let the user choose the folder with the native picker before calling createSession():

const folder = await pedelec.workspaceFolderPicker();
if (!folder) return;

if (!folder.isEmptyFolder && !folder.hasWorkspaceConfig) {
  // The application decides whether to warn the user.
}

const session = await pedelec.createSession({
  workspace: { path: folder.path },
});

The picker returns a folder result or null on cancellation. It is read-only and reports only the root-folder snapshot (isEmptyFolder) and whether .pedelec-workspace.json is a regular file (hasWorkspaceConfig). It does not decide whether the folder is a valid Pedelec workspace or initialize its contents; Core applies the workspace rules during createSession(), then creates the marker after successful custom initialization.

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 and effort

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

Explicit provider creation does not read Desktop settings to resolve model arguments. Core resolves the current provider profile after the request arrives.

Skills and workspace

Effort selection composes with skills and an application-owned workspace:

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

The SDK does not accept a provider model field. Configure model selection in Desktop Settings.

Ollama

The selected Ollama profile must contain a model. An empty selected profile returns MODEL_REQUIRED; low and high do not fall back to default.

Metadata and resume

New sessions expose the normalized effortLevel (default, low, or high) on the session and event contexts. 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.