Requirements and Browser Support

Pedelec is a browser-to-local-runtime integration. Installing the npm package is only one part of the setup. The user’s browser and machine must also provide the extension, desktop runtime, native messaging registration, and at least one usable provider.

Required components

1. A supported browser page

The SDK connects through chrome.runtime.connect(extensionId). It must run in a normal browser page where the Pedelec Chrome Extension is installed and external connections are allowed.

The current extension accepts these page origins:

• production pages served over https://;
• http://localhost/...; and
• http://127.0.0.1/....

A production site served only over plain HTTP is not an allowed external origin. file:// pages, opaque origins, and arbitrary LAN HTTP hostnames are also not part of the supported connection pattern.

Note

Origin includes scheme, host, and port. For example, http://localhost:3000 and http://localhost:5173 are different origins and may require separate approval.

2. Pedelec Chrome Extension

The extension must be installed and enabled in the same browser profile that opens the web application.

getApprovalStatus() reports installed: false when the SDK cannot reach the extension. This result can also represent an extension connection that was lost, so the UI should describe it as “extension unavailable” rather than assuming it was never installed.

3. Pedelec Desktop App

The desktop application owns sessions, provider processes, settings, and the local runtime endpoint. After the user has opened it once to complete installation, Native Host registration, and launch-config creation, the native host tries to start it in the background when a Core request arrives and it is not running.

This fallback is not guaranteed: a missing launch config, damaged installation, an unstartable executable, or a Core that does not become ready in time can still cause CORE_RUNTIME_UNAVAILABLE. The extension may be reachable while the desktop application is unavailable.

4. Registered Native Messaging host

The Desktop App must register the Pedelec native host for Chrome. The extension uses that host to cross the browser security boundary.

If registration is missing or broken, expect NATIVE_HOST_UNAVAILABLE, NATIVE_CONNECTION_CLOSED, or a Core runtime availability error.

5. At least one available provider

Use listProviders() to inspect the user’s machine:

const providers = await pedelec.listProviders();
const available = providers.filter((provider) => provider.available);

CLI-backed providers normally require the provider command to be:

• installed;
• visible in the environment used by the Desktop App;
• authenticated if the provider requires login; and
• compatible with the selected model identifier.

For Ollama, provider availability only confirms that Pedelec can find its bundled agent executable. It does not prove that the configured endpoint is reachable, authentication is valid, or the requested model exists.

The default endpoint is http://127.0.0.1:11434; users must start a local Ollama server for that URL, or configure a remote/Ollama Cloud endpoint. Desktop Settings includes an API-key field. The current pedelec-agent requires a non-empty OLLAMA_API_KEY, so use ollama for a local server or a valid key for an authenticated endpoint.

JavaScript and package requirements

The SDK package is ESM and ships TypeScript declarations. It is intended for modern frontend build tools and browser-side TypeScript or JavaScript.

import { Pedelec, defineTool } from "@kaoruisaac/pedelec";

No framework is required. SolidJS, React, Vue, Astro client islands, and vanilla TypeScript can all use the same public API as long as client initialization happens in the browser.

Unsupported execution environments

Do not construct the client in:

• Node.js scripts;
• an SSR server render;
• server actions or API routes;
• a Web Worker or Service Worker;
• a browser extension background worker that is not a normal approved page integration; or
• test runners without a compatible Chrome extension runtime mock.

The constructor detects the absence of window and creates a client that rejects transport calls with EXTENSION_UNAVAILABLE. That client does not later reconnect itself when hydration occurs. Create a new client inside a browser-only lifecycle instead.

let pedelec: Pedelec | undefined;

if (typeof window !== "undefined") {
  pedelec = new Pedelec();
}

Framework integrations should prefer their client lifecycle hook rather than a module-level condition. For example, initialize inside SolidJS onMount() or React useEffect().

SSR-safe package usage

Importing types is safe on the server:

import type { PedelecSession, ProviderInfo } from "@kaoruisaac/pedelec";

Importing the runtime module is also generally possible, but calling new Pedelec() during server rendering creates an unusable disconnected instance. Keep the instance outside serialized server state and create it after hydration.

Provider and effort compatibility

Desktop Settings maps each provider’s default, low, and high effort profile to provider-supported model/effort arguments. Pedelec validates provider-supported argument names and native effort values, but does not maintain a universal model catalog.

Ollama requires a model in the selected Desktop effort profile. If the selected profile is empty, session creation fails with MODEL_REQUIRED; it does not fall back to another tier.

Preflight checklist

Before showing the main agent UI, verify:

1. The code is running after browser hydration.
2. getApprovalStatus() does not report the extension as unavailable.
3. The current origin can be approved.
4. listProviders() returns at least one available provider.
5. The Desktop App was opened once after installation; handle a failed automatic launch by asking the user to open it or repair installation.
6. The selected effort profile is meaningful to the selected provider.
7. The UI handles disconnects and does not assume setup remains valid forever.

Continue with Installation to add the package and verify the complete chain.