@kaoruisaac/pedelec 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,566 @@
 # Pedelec SDK
+
 [![npm version](https://img.shields.io/npm/v/@kaoruisaac/pedelec.svg)](https://www.npmjs.com/package/@kaoruisaac/pedelec)
+
 Browser SDK for connecting a web app to the Pedelec Chrome Extension and Desktop Runtime.
 
+The SDK lets a browser page create local agent sessions, send user text, receive streamed assistant output, handle tool calls in the web app, and resume or end sessions.
+
+## Requirements
+
+Pedelec SDK runs in a browser page context. It is not intended for Node.js, SSR server code, or background workers.
+
+Before using it, the user needs:
+
+- Pedelec Chrome Extension installed.
+- Pedelec Desktop App running.
+- Chrome Native Messaging host registered by the Desktop App.
+- The target provider available locally. CLI-backed providers use commands such as `codex`, `gemini`, `opencode`, `cursor`, or `claude`; the Ollama provider uses Pedelec's bundled `pedelec-agent`.
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install @kaoruisaac/pedelec
+```
+
+Import the SDK in browser-side TypeScript:
+
+```ts
+import { Pedelec, defineTool } from "@kaoruisaac/pedelec";
+```
+
+For local development before publishing:
+
+```bash
+npm install ../path/to/pedelec/sdk
+```
+
+To build the SDK from this repository:
+
+```bash
+cd sdk
+npm install
+npm run build
+```
+
+## Quick Start
+
+```ts
+import { Pedelec, defineTool } from "@kaoruisaac/pedelec";
+
+const pedelec = new Pedelec();
+
+const session = await pedelec.createSession({
+  provider: "codex",
+  model: "gpt-5",
+  skills: {
+    guidance: "Use get_current_page when you need browser page context.",
+    tools: [
+      defineTool({
+        name: "get_current_page",
+        description: "Read the current browser page title and URL.",
+        argsSchema: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+        handler: () => ({
+          url: location.href,
+          title: document.title,
+        }),
+      }),
+    ],
+  },
+});
+
+session.onChat((text) => {
+  console.log(text);
+});
+
+session.onStatus((status) => {
+  console.log("status", status);
+});
+
+session.onError((error) => {
+  console.error(error.code, error.message, error.details);
+});
+
+await session.sendText("Analyze the current page state.");
+```
+
+`sendText()` resolves after the current agent turn is done. If the same session is already running a prompt, another `sendText()` rejects with `SESSION_BUSY`.
+
+## Create a Client
+
+```ts
+const pedelec = new Pedelec({
+  bridgeTimeoutMs: 30_000,
+});
+```
+
+`bridgeTimeoutMs` controls how long SDK requests wait for an extension response. The default is 30 seconds. Values below 1 ms are clamped to 1 ms.
+
+## Check Approval Status
+
+The extension may ask the user to approve the current origin before a page can create or resume sessions. You can check status before showing a connect button.
+
+```ts
+const status = await pedelec.getApprovalStatus();
+
+if (!status.installed) {
+  console.log("Pedelec extension is not available.");
+} else if (!status.approved) {
+  console.log(`${status.origin} still needs approval.`);
+}
+```
+
+Return shape:
+
+```ts
+type ApprovalStatus = {
+  installed: boolean;
+  approved: boolean;
+  origin: string | null;
+};
+```
+
+If the extension cannot be reached, `getApprovalStatus()` returns `{ installed: false, approved: false, origin }` instead of throwing for extension unavailable cases.
+
+## Providers
+
+List available providers on the user's machine:
+
+```ts
+const providers = await pedelec.listProviders();
+
+for (const provider of providers) {
+  console.log(provider.code, provider.available, provider.path, provider.error);
+}
+```
+
+```ts
+type ProviderCode = "codex" | "gemini" | "opencode" | "cursor" | "claude" | "ollama";
+
+type ProviderInfo = {
+  name: string;
+  code: ProviderCode;
+  path: string | null;
+  available: boolean;
+  error: string | null;
+};
+```
+
+Supported provider codes:
+
+| Provider | Code | Example model |
+| --- | --- | --- |
+| Codex | `codex` | `gpt-5` |
+| Gemini | `gemini` | provider-supported model id |
+| OpenCode | `opencode` | `ollama/qwen2.5-coder:14b` |
+| Cursor | `cursor` | `gpt-5` |
+| Claude Code | `claude` | `sonnet` |
+| Ollama | `ollama` | `qwen3-14b-32k:latest` |
+
+`available: false` usually means the provider CLI is not installed or is not available in `PATH`.
+For Ollama, `available: true` only means Pedelec can find `pedelec-agent`; it does not mean the Ollama server is running or the selected model is installed.
+
+## Settings
+
+Read the Desktop App default provider and per-provider models:
+
+```ts
+const settings = await pedelec.getSettings();
+
+console.log(settings.defaultProvider);
+console.log(settings.defaultModels.codex);
+console.log(settings.defaultModels.gemini);
+console.log(settings.defaultModels.ollama);
+```
+
+```ts
+type PedelecSettings = {
+  defaultProvider: ProviderCode | null;
+  defaultModels: Partial<Record<ProviderCode, string>>;
+};
+```
+
+## Create Sessions
+
+Use the Desktop App default provider:
+
+```ts
+const session = await pedelec.createSession();
+```
+
+Use default provider with skills:
+
+```ts
+const session = await pedelec.createSession({
+  skills: {
+    guidance: "Use update_counter when the user asks to change the counter.",
+    tools: [
+      defineTool({
+        name: "update_counter",
+        description: "Update the visible counter by delta.",
+        argsSchema: {
+          type: "object",
+          required: ["delta"],
+          properties: {
+            delta: {
+              type: "number",
+              description: "Counter delta.",
+            },
+          },
+        },
+      }),
+    ],
+  },
+});
+```
+
+If no default provider is configured, this rejects with `DEFAULT_PROVIDER_NOT_SET`. If the default provider is configured but unavailable, it rejects with `DEFAULT_PROVIDER_UNAVAILABLE`. If the default provider has its own default model, the SDK sends that model with the session request.
+
+Use an explicit provider:
+
+```ts
+const session = await pedelec.createSession({
+  provider: "codex",
+});
+```
+
+When only `provider` is passed, the SDK uses that provider's own Desktop App default model if one is configured. Otherwise, it sends the provider without a model and lets the provider CLI use its own default behavior.
+Ollama is the exception: it requires a model, so provider-only Ollama sessions need `defaultModels.ollama` or they fail with `MODEL_REQUIRED`.
+
+Use an explicit provider and model:
+
+```ts
+const session = await pedelec.createSession({
+  provider: "ollama",
+  model: "qwen3-14b-32k:latest",
+});
+```
+
+Ollama sessions are executed by the `pedelec-agent` binary bundled with the Desktop App, not by the `ollama` CLI. You still need to start the local Ollama server yourself. Ollama requires a model from the session input or `defaultModels.ollama`; otherwise the CoreRuntime returns `MODEL_REQUIRED`.
+
+By default, SDK-created sessions are page-scoped. `autoEndOnDisconnect` defaults to `true`, so the Desktop thread is ended when the last SDK connection for that session disconnects, such as on page refresh or tab close. Keep the default for demo and page-scoped apps. Set `autoEndOnDisconnect: false` when you need to resume the same session after navigation or share it across pages:
+
+```ts
+const session = await pedelec.createSession({
+  provider: "codex",
+  autoEndOnDisconnect: false,
+});
+```
+
+`model` cannot be provided without `provider`.
+
+```ts
+type CreateSessionInput =
+  | {
+      provider: ProviderCode;
+      model?: string;
+      skills?: SkillsInput;
+      autoEndOnDisconnect?: boolean;
+    }
+  | {
+      provider?: undefined;
+      skills?: SkillsInput;
+      autoEndOnDisconnect?: boolean;
+    };
+```
+
+## Stream Responses
+
+`onChat()` receives text deltas. A delta is not guaranteed to be a sentence or paragraph, so UI code should append chunks.
+
+```ts
+let assistantText = "";
+
+session.onChat((text) => {
+  assistantText += text;
+  renderAssistantMessage(assistantText);
+});
+```
+
+The returned function unsubscribes the handler:
+
+```ts
+const unsubscribe = session.onChat((text) => {
+  console.log(text);
+});
+
+unsubscribe();
+```
+
+## Send Text
+
+```ts
+try {
+  await session.sendText("Summarize this workspace.");
+} catch (error) {
+  console.error("send failed", error);
+}
+```
+
+`sendText(text)` sets the session status to `running`, sends the prompt to the runtime, and resolves after a `done` or idle status event. It rejects if the session ends, errors, disconnects, or is already busy.
+
+## Session Status
+
+```ts
+session.onStatus((status) => {
+  switch (status) {
+    case "idle":
+      break;
+    case "running":
+      break;
+    case "waiting_tool_result":
+      break;
+    case "ended":
+      break;
+    case "error":
+      break;
+  }
+});
+
+console.log(session.getStatus());
+```
+
+```ts
+type PedelecSessionStatus =
+  | "idle"
+  | "running"
+  | "waiting_tool_result"
+  | "ended"
+  | "error";
+```
+
+| Status | Meaning |
+| --- | --- |
+| `idle` | The session can accept another prompt. |
+| `running` | The agent is processing user text. |
+| `waiting_tool_result` | The agent requested a tool result from the web app. |
+| `ended` | The session has ended and cannot receive more text. |
+| `error` | The session entered an error state. |
+
+## Tool Calling
+
+Use `skills` to tell the agent what tools your web app can handle. `guidance` is high-level instruction for the agent, and `tools` is the typed list of callable frontend capabilities. Core automatically generates `tools.md` and per-tool spec artifacts inside the sandbox; SDK users do not write or host those files.
+
+Inline handlers are registered locally and are not sent to Core:
+
+```ts
+const session = await pedelec.createSession({
+  provider: "codex",
+  skills: {
+    guidance: "Use get_current_page for browser context.",
+    tools: [
+      defineTool({
+        name: "get_current_page",
+        description: "Read the current browser page title and URL.",
+        argsSchema: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+        handler: () => ({
+          url: location.href,
+          title: document.title,
+          selectedText: window.getSelection()?.toString() ?? "",
+        }),
+      }),
+    ],
+  },
+});
+```
+
+You can also register handlers after session creation. A named `onTool(name, handler)` handler overrides an inline handler for the same tool:
+
+```ts
+const session = await pedelec.createSession({
+  provider: "codex",
+  skills: {
+    guidance: "Use update_counter when the user asks to change the counter.",
+    tools: [
+      defineTool({
+        name: "update_counter",
+        description: "Update the visible counter by delta.",
+        argsSchema: {
+          type: "object",
+          required: ["delta"],
+          properties: {
+            delta: {
+              type: "number",
+              description: "Counter delta.",
+            },
+          },
+        },
+      }),
+    ],
+  },
+});
+
+session.onTool("update_counter", async (args) => {
+  const { delta } = args as { delta: number };
+  counter.value += delta;
+  return {
+    counter: counter.value,
+    delta,
+  };
+});
+```
+
+Tool results must be JSON-serializable. If no handler is registered, the SDK returns a `TOOL_HANDLER_NOT_FOUND` error result. If the handler throws, the SDK returns a `TOOL_HANDLER_ERROR` error result.
+
+The legacy generic form `session.onTool((tool, args) => ...)` remains available as a fallback handler.
+
+### Tool Args Schema
+
+`defineTool` uses `argsSchema` to describe the tool arguments sent to the provider and agent. The root schema must be an object:
+
+```ts
+defineTool({
+  name: "update_counter",
+  description: "Update the visible counter by delta.",
+  argsSchema: {
+    type: "object",
+    required: ["delta"],
+    properties: {
+      delta: {
+        type: "number",
+        description: "Counter delta.",
+      },
+    },
+  },
+});
+```
+
+`argsSchema` is the Pedelec Tool Args Schema subset, not full JSON Schema. It supports common `string`, `number`, `integer`, `boolean`, `array`, `object`, and `oneOf` nodes with fields such as `description`, `default`, `examples`, `enum`, `minimum`, `maximum`, `minItems`, `maxItems`, and `required`.
+
+`default` is guidance for the agent; the SDK does not automatically fill missing argument values. Shorthand schemas such as `input: { delta: "number" }` are no longer supported.
+
+The first version does not support `$defs`, `$ref`, `additionalProperties`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`, or `format`. Reuse schema fragments with TypeScript constants instead of JSON Schema references.
+
+## Resume Sessions
+
+If you have saved a `sessionId`, resume it later:
+
+```ts
+const session = await pedelec.resumeSession("thread_abc123");
+
+session.onChat((text) => {
+  console.log(text);
+});
+
+await session.sendText("Continue the previous task.");
+```
+
+`resumeSession(sessionId)` rejects with `INVALID_INPUT` when `sessionId` is empty.
+
+## End Sessions
+
+```ts
+await session.end();
+```
+
+After a session ends, future `sendText()` calls reject with `SESSION_ENDED`.
+
+Listen for runtime-ended sessions:
+
 ```ts
-import { Pedelec } from "@kaoruisaac/pedelec";
+session.onEnded(() => {
+  console.log("session ended");
+});
 ```
 
-See the repository README for full setup and usage documentation.
+## Low-Level Requests
+
+Most apps should use the typed methods above. `request<T>(type, payload)` is exposed for advanced integrations that need to call bridge operations directly.
+
+```ts
+const result = await pedelec.request<{ sessionId: string }>("create_session", {
+  input: {
+    provider: "codex",
+    skills: undefined,
+    autoEndOnDisconnect: true,
+  },
+});
+```
+
+Low-level requests still use the SDK bridge timeout and reject with `PedelecError` objects.
+
+## Error Handling
+
+Register `onError()` for session-level errors and use `try/catch` around async SDK calls.
+
+```ts
+session.onError((error) => {
+  console.error("session error", error.code, error.message, error.details);
+});
+
+try {
+  await session.sendText("Update the selected content.");
+} catch (error) {
+  console.error("request failed", error);
+}
+```
+
+```ts
+type PedelecError = {
+  code: string;
+  message: string;
+  details?: unknown;
+};
+```
+
+Common error codes:
+
+| Code | Meaning |
+| --- | --- |
+| `EXTENSION_UNAVAILABLE` | The SDK is not running in a supported browser page, or the extension cannot be reached. |
+| `EXTENSION_DISCONNECTED` | The extension connection was interrupted. |
+| `SDK_BRIDGE_TIMEOUT` | The extension did not respond before `bridgeTimeoutMs`. |
+| `SDK_PROTOCOL_ERROR` | The extension response did not match the SDK protocol. |
+| `SDK_TRANSPORT_ERROR` | A bridge request failed at the transport layer. |
+| `APPROVAL_REJECTED` | The user rejected approval for the current origin. |
+| `APPROVAL_TIMEOUT` | The user did not complete origin approval in time. |
+| `OPEN_POPUP_FAILED` | The extension could not open the approval popup. |
+| `NATIVE_HOST_UNAVAILABLE` | Chrome Native Messaging host cannot be reached. |
+| `DEFAULT_PROVIDER_NOT_SET` | The Desktop App has no default provider configured. |
+| `DEFAULT_PROVIDER_UNAVAILABLE` | The configured default provider is not currently available. |
+| `INVALID_INPUT` | The request input is invalid, such as model without provider or empty session id. |
+| `SESSION_BUSY` | The session already has a prompt in progress. |
+| `SESSION_ENDED` | The session has ended. |
+| `SESSION_ERROR` | The runtime reported a session error. |
+| `TOOL_HANDLER_NOT_FOUND` | The agent called a tool but no web app handler is registered. |
+| `TOOL_HANDLER_ERROR` | The web app tool handler threw an error. |
+| `SUBMIT_TOOL_RESULT_FAILED` | The SDK could not submit a tool result back to the runtime. |
+
+## Public API Summary
+
+```ts
+class Pedelec {
+  constructor(options?: { bridgeTimeoutMs?: number });
+  createSession(input?: CreateSessionInput): Promise<PedelecSession>;
+  listProviders(): Promise<ProviderInfo[]>;
+  getSettings(): Promise<PedelecSettings>;
+  getApprovalStatus(): Promise<ApprovalStatus>;
+  resumeSession(sessionId: string): Promise<PedelecSession>;
+  request<T>(type: string, payload?: Record<string, unknown>): Promise<T>;
+}
+
+class PedelecSession {
+  readonly sessionId: string;
+  readonly provider: string;
+  readonly model?: string;
+
+  sendText(text: string): Promise<void>;
+  onChat(handler: (text: string) => void): () => void;
+  onTool(handler: (tool: string, args: unknown) => unknown | Promise<unknown>): () => void;
+  onError(handler: (error: PedelecError) => void): () => void;
+  onStatus(handler: (status: PedelecSessionStatus) => void): () => void;
+  onEnded(handler: () => void): () => void;
+  getStatus(): PedelecSessionStatus;
+  end(): Promise<void>;
+}
+```

package/dist/index.d.ts

@@ -1,16 +1,89 @@
 export type PedelecOptions = {
     bridgeTimeoutMs?: number;
 };
-export type ProviderCode = "codex" | "gemini" | "opencode" | "cursor" | "claude";
+export type ProviderCode = "codex" | "gemini" | "opencode" | "cursor" | "claude" | "ollama";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ToolArgsSchemaMeta<TDefault extends JsonValue = JsonValue> = {
+    description?: string;
+    default?: TDefault;
+    examples?: TDefault[];
+};
+export type ToolArgsStringSchema = ToolArgsSchemaMeta<string> & {
+    type: "string";
+    enum?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+};
+export type ToolArgsNumberSchema = ToolArgsSchemaMeta<number> & {
+    type: "number";
+    enum?: number[];
+    minimum?: number;
+    maximum?: number;
+};
+export type ToolArgsIntegerSchema = ToolArgsSchemaMeta<number> & {
+    type: "integer";
+    enum?: number[];
+    minimum?: number;
+    maximum?: number;
+};
+export type ToolArgsBooleanSchema = ToolArgsSchemaMeta<boolean> & {
+    type: "boolean";
+    enum?: boolean[];
+};
+export type ToolArgsArraySchema = ToolArgsSchemaMeta<JsonValue[]> & {
+    type: "array";
+    items: ToolArgsSchemaNode;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+};
+export type ToolArgsObjectSchema = ToolArgsSchemaMeta<Record<string, JsonValue>> & {
+    type: "object";
+    properties?: Record<string, ToolArgsSchemaNode>;
+    required?: string[];
+};
+export type ToolArgsOneOfSchema = ToolArgsSchemaMeta & {
+    oneOf: ToolArgsSchemaNode[];
+};
+export type ToolArgsSchemaNode = ToolArgsStringSchema | ToolArgsNumberSchema | ToolArgsIntegerSchema | ToolArgsBooleanSchema | ToolArgsArraySchema | ToolArgsObjectSchema | ToolArgsOneOfSchema;
+export type ToolArgsSchema = ToolArgsObjectSchema;
+export type ToolSpecificHandler<TArgs = unknown, TResult = unknown> = (args: TArgs) => TResult | Promise<TResult>;
+export type ToolDefinition<TArgs = unknown, TResult = unknown> = {
+    name: string;
+    description: string;
+    argsSchema: ToolArgsSchema;
+    timeoutMs?: number;
+    handler?: ToolSpecificHandler<TArgs, TResult>;
+};
+export type SkillsInput = {
+    guidance: string;
+    tools: ToolDefinition[];
+};
+export type SerializableToolManifest = {
+    name: string;
+    description: string;
+    argsSchema: ToolArgsSchema;
+    timeoutMs?: number;
+};
+export type SerializableSkillsManifest = {
+    guidance: string;
+    tools: SerializableToolManifest[];
+};
 type CreateSessionInputWithProvider = {
     provider: ProviderCode;
     model?: string;
-    skillsUrls?: string[];
+    skills?: SkillsInput;
+    autoEndOnDisconnect?: boolean;
 };
 type CreateSessionInputWithDefaults = {
     provider?: undefined;
     model?: never;
-    skillsUrls?: string[];
+    skills?: SkillsInput;
+    autoEndOnDisconnect?: boolean;
 };
 export type CreateSessionInput = CreateSessionInputWithProvider | CreateSessionInputWithDefaults;
 export type ProviderInfo = {
@@ -22,7 +95,7 @@ export type ProviderInfo = {
 };
 export type PedelecSettings = {
     defaultProvider: ProviderCode | null;
-    defaultModel: string | null;
+    defaultModels: Partial<Record<ProviderCode, string>>;
 };
 export type ApprovalStatus = {
     installed: boolean;
@@ -73,10 +146,11 @@ type SessionEvent = {
     seq?: number;
 };
 type ChatHandler = (text: string) => void;
-type ToolHandler = (tool: string, args: unknown) => unknown | Promise<unknown>;
+type GenericToolHandler = (tool: string, args: unknown) => unknown | Promise<unknown>;
 type ErrorHandler = (error: PedelecError) => void;
 type StatusHandler = (status: PedelecSessionStatus) => void;
 type EndedHandler = () => void;
+export declare function defineTool<TArgs = unknown, TResult = unknown>(tool: ToolDefinition<TArgs, TResult>): ToolDefinition<TArgs, TResult>;
 export declare class Pedelec {
     private readonly pageWindow;
     private readonly channelId;
@@ -114,21 +188,25 @@ export declare class PedelecSession {
     readonly model?: string;
     private status;
     private pendingSend;
-    private toolHandler;
+    private genericToolHandler;
+    private inlineToolHandlers;
+    private readonly namedToolHandlers;
     private readonly chatHandlers;
     private readonly errorHandlers;
     private readonly statusHandlers;
     private readonly endedHandlers;
-    constructor(client: Pedelec, sessionId: string, provider: string, model?: string);
+    constructor(client: Pedelec, sessionId: string, provider: string, model?: string, inlineToolHandlers?: Map<string, ToolSpecificHandler>);
     sendText(text: string): Promise<void>;
     onChat(handler: ChatHandler): () => void;
-    onTool(handler: ToolHandler): () => void;
+    onTool(handler: GenericToolHandler): () => void;
+    onTool<TArgs = unknown, TResult = unknown>(toolName: string, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
     onError(handler: ErrorHandler): () => void;
     onStatus(handler: StatusHandler): () => void;
     onEnded(handler: EndedHandler): () => void;
     getStatus(): PedelecSessionStatus;
     end(): Promise<void>;
     handleEvent(event: SessionEvent): void;
+    replaceInlineToolHandlers(handlers: Map<string, ToolSpecificHandler>): void;
     private handleToolCall;
     private resolvePendingSend;
     private rejectPendingSend;

package/dist/index.js

@@ -1,6 +1,92 @@
 import { PEDELEC_EXTENSION_ID } from "./extension-id.js";
 const SDK_EXTERNAL_PORT_NAME = "pedelec-sdk-external";
 const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
+const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
+export function defineTool(tool) {
+    return tool;
+}
+function normalizeSkillsInput(value) {
+    const handlers = new Map();
+    if (value === undefined)
+        return { handlers };
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw makeError("INVALID_INPUT", "skills must be an object");
+    }
+    const skills = value;
+    if (typeof skills.guidance !== "string") {
+        throw makeError("INVALID_INPUT", "skills.guidance must be a string");
+    }
+    if (!Array.isArray(skills.tools)) {
+        throw makeError("INVALID_INPUT", "skills.tools must be an array");
+    }
+    const seen = new Set();
+    const tools = skills.tools.map((tool, index) => {
+        if (!tool || typeof tool !== "object" || Array.isArray(tool)) {
+            throw makeError("INVALID_INPUT", "skills.tools entries must be objects", { index });
+        }
+        const rawTool = tool;
+        if (typeof rawTool.name !== "string" || !TOOL_NAME_PATTERN.test(rawTool.name)) {
+            throw makeError("INVALID_INPUT", "tool name is invalid", { index, toolName: rawTool.name });
+        }
+        if (seen.has(rawTool.name)) {
+            throw makeError("INVALID_INPUT", "duplicate tool name", { toolName: rawTool.name });
+        }
+        seen.add(rawTool.name);
+        if (typeof rawTool.description !== "string" || rawTool.description.trim().length === 0) {
+            throw makeError("INVALID_INPUT", "tool description must be a non-empty string", {
+                toolName: rawTool.name,
+            });
+        }
+        if (rawTool.timeoutMs !== undefined &&
+            (!Number.isInteger(rawTool.timeoutMs) || rawTool.timeoutMs <= 0)) {
+            throw makeError("INVALID_INPUT", "tool timeoutMs must be a positive integer", {
+                toolName: rawTool.name,
+            });
+        }
+        if (rawTool.handler !== undefined && typeof rawTool.handler !== "function") {
+            throw makeError("INVALID_INPUT", "tool handler must be a function", { toolName: rawTool.name });
+        }
+        if (rawTool.input !== undefined) {
+            throw makeError("INVALID_INPUT", "tool input is no longer supported; use argsSchema", {
+                toolName: rawTool.name,
+            });
+        }
+        const argsSchema = normalizeToolArgsSchema(rawTool.argsSchema, rawTool.name);
+        if (rawTool.handler)
+            handlers.set(rawTool.name, rawTool.handler);
+        return {
+            name: rawTool.name,
+            description: rawTool.description,
+            argsSchema,
+            ...(rawTool.timeoutMs === undefined ? {} : { timeoutMs: rawTool.timeoutMs }),
+        };
+    });
+    return {
+        manifest: {
+            guidance: skills.guidance,
+            tools,
+        },
+        handlers,
+    };
+}
+function normalizeToolArgsSchema(argsSchema, toolName) {
+    if (!argsSchema || typeof argsSchema !== "object" || Array.isArray(argsSchema)) {
+        throw makeError("INVALID_INPUT", "tool argsSchema must be an object", { toolName });
+    }
+    const schema = argsSchema;
+    if (schema.type !== "object") {
+        throw makeError("INVALID_INPUT", "tool argsSchema must describe an object", { toolName });
+    }
+    try {
+        return JSON.parse(JSON.stringify(schema));
+    }
+    catch (err) {
+        throw makeError("INVALID_INPUT", "tool argsSchema must be serializable", {
+            toolName,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 export class Pedelec {
     pageWindow;
     channelId;
@@ -28,13 +114,14 @@ export class Pedelec {
             input: {
                 provider: resolvedInput.provider,
                 model: resolvedInput.model,
-                skillsUrls: resolvedInput.skillsUrls,
+                skills: resolvedInput.skills,
+                autoEndOnDisconnect: resolvedInput.autoEndOnDisconnect,
             },
         });
         if (!result.sessionId) {
             throw makeError("SDK_PROTOCOL_ERROR", "create_session response did not include sessionId");
         }
-        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.model);
+        return this.registerSession(result.sessionId, resolvedInput.provider, resolvedInput.model, resolvedInput.inlineToolHandlers);
     }
     async listProviders() {
         const result = await this.request("list_providers");
@@ -130,28 +217,31 @@ export class Pedelec {
         const provider = typeof raw.provider === "string" ? raw.provider.trim() : "";
         const hasProvider = provider.length > 0;
         const hasModel = raw.model !== undefined;
+        const autoEndOnDisconnect = raw.autoEndOnDisconnect !== false;
+        const normalizedSkills = normalizeSkillsInput(raw.skills);
         if (!hasProvider && hasModel) {
             throw makeError("INVALID_INPUT", "model cannot be provided without provider");
         }
-        const skillsUrls = Array.isArray(raw.skillsUrls) ? raw.skillsUrls : [];
         const userModel = typeof raw.model === "string" ? raw.model : undefined;
         if (!hasProvider) {
-            return this.resolveDefaultCreateSessionInput(skillsUrls);
+            return this.resolveDefaultCreateSessionInput(normalizedSkills, autoEndOnDisconnect);
         }
         if (!isProviderCode(provider)) {
             throw makeError("INVALID_INPUT", "provider is not supported", { provider });
         }
         let model = userModel;
         if (model === undefined) {
-            return this.resolveProviderOnlyCreateSessionInput(provider, skillsUrls);
+            return this.resolveProviderOnlyCreateSessionInput(provider, normalizedSkills, autoEndOnDisconnect);
         }
         return {
             provider: provider,
             model,
-            skillsUrls,
+            skills: normalizedSkills.manifest,
+            inlineToolHandlers: normalizedSkills.handlers,
+            autoEndOnDisconnect,
         };
     }
-    async resolveDefaultCreateSessionInput(skillsUrls) {
+    async resolveDefaultCreateSessionInput(normalizedSkills, 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.");
@@ -159,18 +249,20 @@ export class Pedelec {
         await this.assertDefaultProviderAvailable(settings.defaultProvider);
         return {
             provider: settings.defaultProvider,
-            model: settings.defaultModel ?? undefined,
-            skillsUrls,
+            model: settings.defaultModels[settings.defaultProvider] ?? undefined,
+            skills: normalizedSkills.manifest,
+            inlineToolHandlers: normalizedSkills.handlers,
+            autoEndOnDisconnect,
         };
     }
-    async resolveProviderOnlyCreateSessionInput(provider, skillsUrls) {
+    async resolveProviderOnlyCreateSessionInput(provider, normalizedSkills, autoEndOnDisconnect) {
         const settings = await this.getSettings();
         return {
             provider,
-            model: settings.defaultProvider === provider && settings.defaultModel
-                ? settings.defaultModel
-                : undefined,
-            skillsUrls,
+            model: settings.defaultModels[provider] ?? undefined,
+            skills: normalizedSkills.manifest,
+            inlineToolHandlers: normalizedSkills.handlers,
+            autoEndOnDisconnect,
         };
     }
     async assertDefaultProviderAvailable(provider) {
@@ -180,11 +272,13 @@ export class Pedelec {
             throw makeError("DEFAULT_PROVIDER_UNAVAILABLE", "Default provider is not currently available. Open the Pedelec desktop app Settings page and choose an available provider.", { provider });
         }
     }
-    registerSession(sessionId, provider, model) {
+    registerSession(sessionId, provider, model, inlineToolHandlers = new Map()) {
         const existing = this.sessions.get(sessionId);
-        if (existing)
+        if (existing) {
+            existing.replaceInlineToolHandlers(inlineToolHandlers);
             return existing;
-        const session = new PedelecSession(this, sessionId, provider, model);
+        }
+        const session = new PedelecSession(this, sessionId, provider, model, inlineToolHandlers);
         this.sessions.set(sessionId, session);
         return session;
     }
@@ -271,16 +365,19 @@ export class PedelecSession {
     model;
     status = "idle";
     pendingSend = null;
-    toolHandler = null;
+    genericToolHandler = null;
+    inlineToolHandlers = new Map();
+    namedToolHandlers = new Map();
     chatHandlers = new Set();
     errorHandlers = new Set();
     statusHandlers = new Set();
     endedHandlers = new Set();
-    constructor(client, sessionId, provider, model) {
+    constructor(client, sessionId, provider, model, inlineToolHandlers = new Map()) {
         this.client = client;
         this.sessionId = sessionId;
         this.provider = provider;
         this.model = model;
+        this.inlineToolHandlers = new Map(inlineToolHandlers);
     }
     sendText(text) {
         if (this.status === "ended") {
@@ -310,11 +407,27 @@ export class PedelecSession {
         this.chatHandlers.add(handler);
         return () => this.chatHandlers.delete(handler);
     }
-    onTool(handler) {
-        this.toolHandler = handler;
+    onTool(toolNameOrHandler, maybeHandler) {
+        if (typeof toolNameOrHandler === "string") {
+            const toolName = toolNameOrHandler;
+            if (!TOOL_NAME_PATTERN.test(toolName)) {
+                throw makeError("INVALID_INPUT", "tool name is invalid", { toolName });
+            }
+            if (typeof maybeHandler !== "function") {
+                throw makeError("INVALID_INPUT", "tool handler must be a function", { toolName });
+            }
+            this.namedToolHandlers.set(toolName, maybeHandler);
+            return () => {
+                if (this.namedToolHandlers.get(toolName) === maybeHandler) {
+                    this.namedToolHandlers.delete(toolName);
+                }
+            };
+        }
+        const handler = toolNameOrHandler;
+        this.genericToolHandler = handler;
         return () => {
-            if (this.toolHandler === handler) {
-                this.toolHandler = null;
+            if (this.genericToolHandler === handler) {
+                this.genericToolHandler = null;
             }
         };
     }
@@ -392,18 +505,26 @@ export class PedelecSession {
             this.markEnded();
         }
     }
+    replaceInlineToolHandlers(handlers) {
+        this.inlineToolHandlers = new Map(handlers);
+    }
     async handleToolCall(event) {
         let result;
-        if (!this.toolHandler) {
-            result = {
-                error: makeError("TOOL_HANDLER_NOT_FOUND", `No tool handler registered for ${event.tool}`, {
-                    tool: event.tool,
-                }),
-            };
+        const namedHandler = this.namedToolHandlers.get(event.tool);
+        const inlineHandler = this.inlineToolHandlers.get(event.tool);
+        if (namedHandler) {
+            try {
+                result = await namedHandler(event.args);
+            }
+            catch (err) {
+                result = {
+                    error: normalizeError(err, "TOOL_HANDLER_ERROR", "Tool handler failed"),
+                };
+            }
         }
-        else {
+        else if (inlineHandler) {
             try {
-                result = await this.toolHandler(event.tool, event.args);
+                result = await inlineHandler(event.args);
             }
             catch (err) {
                 result = {
@@ -411,6 +532,23 @@ export class PedelecSession {
                 };
             }
         }
+        else if (this.genericToolHandler) {
+            try {
+                result = await this.genericToolHandler(event.tool, event.args);
+            }
+            catch (err) {
+                result = {
+                    error: normalizeError(err, "TOOL_HANDLER_ERROR", "Tool handler failed"),
+                };
+            }
+        }
+        else {
+            result = {
+                error: makeError("TOOL_HANDLER_NOT_FOUND", `No tool handler registered for ${event.tool}`, {
+                    tool: event.tool,
+                }),
+            };
+        }
         try {
             await this.client.request("submit_tool_result", {
                 sessionId: this.sessionId,
@@ -470,14 +608,23 @@ function isSessionEvent(message) {
 function isSettings(value) {
     if (!value || typeof value !== "object")
         return false;
+    if (Array.isArray(value))
+        return false;
     const settings = value;
+    const defaultModels = settings.defaultModels;
+    if (settings.defaultModel !== undefined)
+        return false;
+    if (!defaultModels || typeof defaultModels !== "object" || Array.isArray(defaultModels)) {
+        return false;
+    }
     return ((settings.defaultProvider === null ||
         settings.defaultProvider === "codex" ||
         settings.defaultProvider === "gemini" ||
         settings.defaultProvider === "opencode" ||
         settings.defaultProvider === "cursor" ||
-        settings.defaultProvider === "claude") &&
-        (settings.defaultModel === null || typeof settings.defaultModel === "string"));
+        settings.defaultProvider === "claude" ||
+        settings.defaultProvider === "ollama") &&
+        Object.entries(defaultModels).every(([provider, model]) => isProviderCode(provider) && typeof model === "string"));
 }
 function isApprovalStatus(value) {
     if (!value || typeof value !== "object")
@@ -492,7 +639,8 @@ function isProviderCode(value) {
         value === "gemini" ||
         value === "opencode" ||
         value === "cursor" ||
-        value === "claude");
+        value === "claude" ||
+        value === "ollama");
 }
 function makeError(code, message, details) {
     return details === undefined ? { code, message } : { code, message, details };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/kaoruisaac/pedelec.git",
+    "url": "git+https://github.com/kaoruisaac/pedelec.git",
     "directory": "sdk"
   },
   "scripts": {