@kaoruisaac/pedelec 0.1.4 → 0.1.6

package/README.md

@@ -2,50 +2,83 @@
 
 [![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.
+## Documentation
 
-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.
+- [Pedelec documentation](https://kaoruisaac.github.io/pedelec/)
+- [GitHub repository](https://github.com/kaoruisaac/pedelec)
 
-## Requirements
 
-Pedelec SDK runs in a browser page context. It is not intended for Node.js, SSR server code, or background workers.
+Pedelec is a browser SDK and local bridge for applications that want to work with AI coding agents such as Codex, Gemini, OpenCode, Cursor, Claude Code, or an Ollama-backed agent.
 
-Before using it, the user needs:
+A web application can use Pedelec to:
 
-- 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`.
+- create an agent session on the user's machine;
+- send user instructions and receive streamed assistant text;
+- expose narrowly scoped browser-side tools to the agent;
+- resume or end sessions; and
+- upload and list completed sandbox assets; and
+- show connection, approval, provider, and lifecycle state in the UI.
 
-## Installation
+## Why Pedelec exists
 
-Install from npm:
+A normal chat API accepts text and returns text. An agent integration often needs more:
+
+- The agent may need to inspect the page, editor, canvas, selection, or application state.
+- The application may need to ask the user for confirmation while an agent turn is paused.
+- The user may want to use a provider CLI that is already installed and authenticated locally.
+- The browser should not receive permission to launch arbitrary local processes directly.
+
+Pedelec separates those responsibilities. Your web application owns the UI and the tool handlers. The Pedelec extension and desktop runtime own the local transport, session lifecycle, and provider process.
+
+```text
+Web application
+  ↓ @kaoruisaac/pedelec
+Pedelec Chrome Extension
+  ↓ Chrome Native Messaging
+Pedelec native host
+  ↓ local Core IPC
+Pedelec Desktop Runtime
+  ↓ provider process
+Codex / Gemini / OpenCode / Cursor / Claude Code / Ollama
+```
+## SDK Prerequisites
+
+The Pedelec SDK must run in a browser page environment and requires:
+
+1. The user has installed the Pedelec Chrome Extension.
+2. The user has started the Pedelec Desktop App.
+3. The Desktop App has registered the Chrome Native Messaging host.
+4. The target provider is available on the user's machine. CLI-backed providers use commands such as `codex`, `gemini`, `opencode`, `cursor`, or `claude`; the Ollama provider uses Pedelec's bundled `pedelec-agent`.
+
+The SDK is not suitable for direct use in Node.js, an SSR server, or a background worker; it needs extension runtime messaging from a Chrome page environment.
+
+---
+
+## Installing and Importing the SDK
+
+The SDK package is located in `sdk/`:
 
 ```bash
-npm install @kaoruisaac/pedelec
+cd sdk
+npm install
+npm run build
 ```
 
-Import the SDK in browser-side TypeScript:
+Import it from the Web App:
 
 ```ts
 import { Pedelec, defineTool } from "@kaoruisaac/pedelec";
 ```
 
-For local development before publishing:
+If it has not been published to npm yet, install it from a local path first:
 
 ```bash
 npm install ../path/to/pedelec/sdk
 ```
 
-To build the SDK from this repository:
+---
 
-```bash
-cd sdk
-npm install
-npm run build
-```
-
-## Quick Start
+## Minimal Example
 
 ```ts
 import { Pedelec, defineTool } from "@kaoruisaac/pedelec";
@@ -66,175 +99,87 @@ const session = await pedelec.createSession({
           properties: {},
           required: [],
         },
-        handler: (_args, ctx) => ({
+        handler: () => ({
           url: location.href,
           title: document.title,
-          turnId: ctx.turnId,
         }),
       }),
     ],
   },
 });
 
-session.onChat((text, ctx) => {
-  console.log(ctx.turnId, text);
+session.onChat((text) => {
+  // Incremental text stream from the agent.
+  console.log(text);
 });
 
-session.onStatus((status, ctx) => {
-  console.log("status", status, "previous", ctx.previousStatus);
+session.onStatus((status) => {
+  // idle | running | waiting_tool_result | ended | error
+  console.log("status", status);
 });
 
-session.onError((error, ctx) => {
-  console.error(ctx.type, error.code, error.message, error.details);
+session.onError((error) => {
+  console.error(error.code, error.message, error.details);
 });
 
-await session.sendText("Analyze the current page state.");
+await session.sendText("Please help me 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`.
+`sendText()` resolves after the current agent response completes. If the session is already handling a previous prompt, the new `sendText()` call is rejected to prevent multiple concurrent requests from running in the same session.
 
-## Create a Client
+## Listing uploaded assets
 
 ```ts
-const pedelec = new Pedelec({
-  bridgeTimeoutMs: 30_000,
-});
+const path = await session.uploadAsset(file);
+const assets = await session.listAssets();
 ```
 
-`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.
+`listAssets()` lists only the first level of `input/`, ordered by filesystem modification time (newest first). Each item's `name` is the actual sandbox filename and may differ from the original `File.name`; `modifiedAt` is a filesystem modification timestamp, not an exact upload time. `path` is an agent-sandbox-relative `input/...` path and never an absolute local path. It may be called while the agent is running. Ended sessions reject with `SESSION_ENDED`. Recursive listing, pagination, download, deletion, rename, and move are not supported.
+
+---
 
-## Check Approval Status
+## Creating a Session
 
-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.
+The first time an origin calls `createSession()` or `resumeSession()`, the extension asks the user to approve that origin in the popup. After approval, the same origin can create sessions directly.
+
+You can query the current origin's approval status first to decide whether to show UI such as "Connect Pedelec":
 
 ```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.`);
-}
+console.log(status.installed, status.approved, status.origin);
 ```
 
-Return shape:
+For a complete Extension, approval, and Desktop readiness probe, use `checkAvailability()`. It never creates/resumes a session or opens approval. When approved it validates Desktop by calling `getSettings()`, which may invoke the existing Native Host auto-launch fallback.
 
 ```ts
-type ApprovalStatus = {
-  installed: boolean;
-  approved: boolean;
-  origin: string | null;
-};
+const availability = await pedelec.checkAvailability();
+if (availability.available) startUi();
 ```
 
-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:
+An unavailable extension may be disconnected rather than absent. `desktop.launchAttempted` means the settings probe was sent, not that Desktop was confirmed to have launched. Invalid settings responses also count as Desktop unavailable in this probe.
 
-```ts
-const providers = await pedelec.listProviders();
-
-for (const provider of providers) {
-  console.log(provider.code, provider.available, provider.path, provider.error);
-}
-```
+### Specifying Provider and Model
 
 ```ts
-type ProviderCode = "codex" | "gemini" | "opencode" | "cursor" | "claude" | "ollama";
-
-type ProviderInfo = {
-  name: string;
-  code: ProviderCode;
-  path: string | null;
-  available: boolean;
-  error: string | null;
-};
+const session = await pedelec.createSession({
+  provider: "opencode",
+  model: "ollama/qwen2.5-coder:14b",
+});
 ```
 
-Supported provider codes:
+Currently supported provider codes in the SDK:
 
 | Provider | Code | Example model |
 | --- | --- | --- |
 | Codex | `codex` | `gpt-5` |
-| Gemini | `gemini` | provider-supported model id |
+| Gemini | `gemini` | Any model ID supported by the provider |
 | 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:
+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 and specify a model explicitly or configure `defaultModels.ollama` in Settings:
 
 ```ts
 const session = await pedelec.createSession({
@@ -242,360 +187,3 @@ const session = await pedelec.createSession({
   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, ctx) => {
-  console.debug("chat delta for turn", ctx.turnId, ctx.eventReceivedAt);
-  assistantText += text;
-  renderAssistantMessage(assistantText);
-});
-```
-
-The returned function unsubscribes the handler:
-
-```ts
-const unsubscribe = session.onChat((text, ctx) => {
-  console.log(ctx.turnId, 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, ctx) => {
-  console.debug("status changed from", ctx.previousStatus, "to", ctx.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: (_args, ctx) => ({
-          url: location.href,
-          title: document.title,
-          selectedText: window.getSelection()?.toString() ?? "",
-          turnId: ctx.turnId,
-        }),
-      }),
-    ],
-  },
-});
-```
-
-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, ctx) => {
-  const { delta } = args as { delta: number };
-  console.debug("tool call", ctx.toolRequestId, ctx.turnId);
-  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 generic form `session.onTool((tool, args, ctx) => ...)` remains available as a fallback handler.
-
-### Event Context and UI Lifecycles
-
-All user-facing event callbacks receive context metadata. The SDK provides `ctx.sessionId`, `ctx.provider`, `ctx.model`, `ctx.turnId`, `ctx.turnStartedAt`, `ctx.eventReceivedAt`, `ctx.eventEmittedAt`, and `ctx.source` where they apply. `turnId` is SDK-local metadata for one accepted `sendText()` turn; it is not sent to Core and should not be parsed.
-
-Apps should still use their own UI lifecycle state to decide whether a late callback is stale:
-
-```ts
-let lifecycleId = 0;
-
-function createWorldSession(session: PedelecSession) {
-  const generation = ++lifecycleId;
-
-  session.onTool("spawn_basic_shapes", async (args, ctx) => {
-    if (generation !== lifecycleId) {
-      return {
-        error: {
-          code: "STALE_TOOL_CALL",
-          message: "This tool call belongs to an older UI lifecycle.",
-        },
-      };
-    }
-
-    console.debug("handling tool", ctx.toolRequestId, ctx.turnId, ctx.turnStartedAt);
-    return spawnBasicShapes(args);
-  });
-}
-```
-
-The SDK context helps you inspect which session and turn produced an event. It does not automatically know whether your current canvas, page, render mode, or world instance is still valid.
-
-### 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, ctx) => {
-  console.log(ctx.turnId, 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
-session.onEnded((ctx) => {
-  console.log("session ended", ctx.source);
-});
-```
-
-## 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, ctx) => {
-  console.error("session error", ctx.type, 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, ctx: ChatEventContext) => void): () => void;
-  onTool(handler: (tool: string, args: unknown, ctx: ToolCallContext) => unknown | Promise<unknown>): () => void;
-  onError(handler: (error: PedelecError, ctx: ErrorEventContext) => void): () => void;
-  onStatus(handler: (status: PedelecSessionStatus, ctx: StatusEventContext) => void): () => void;
-  onEnded(handler: (ctx: EndedEventContext) => void): () => void;
-  getStatus(): PedelecSessionStatus;
-  end(): Promise<void>;
-}
-```

package/dist/index.d.ts

@@ -6,6 +6,13 @@ export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
 };
+export type SandboxAssetPath = `input/${string}`;
+export type SandboxAsset = {
+    name: string;
+    path: SandboxAssetPath;
+    sizeBytes: number;
+    modifiedAt: number;
+};
 export type ToolArgsSchemaMeta<TDefault extends JsonValue = JsonValue> = {
     description?: string;
     default?: TDefault;
@@ -103,6 +110,21 @@ export type ApprovalStatus = {
     approved: boolean;
     origin: string | null;
 };
+export type PedelecAvailability = {
+    available: boolean;
+    extension: {
+        available: boolean;
+    };
+    approval: {
+        approved: boolean;
+        origin: string | null;
+    };
+    desktop: {
+        available: boolean;
+        launchAttempted: boolean;
+    };
+    error?: PedelecError;
+};
 export type PedelecError = {
     code: string;
     message: string;
@@ -213,6 +235,7 @@ export declare class Pedelec {
     request<T>(type: string, payload?: Record<string, unknown>): Promise<T>;
     unregisterSession(sessionId: string): void;
     private resolveCreateSessionInput;
+    checkAvailability(): Promise<PedelecAvailability>;
     private resolveDefaultCreateSessionInput;
     private resolveProviderOnlyCreateSessionInput;
     private assertDefaultProviderAvailable;
@@ -234,6 +257,7 @@ export declare class PedelecSession<TToolName extends string = string> {
     private pendingSend;
     private pendingPrepare;
     private preparePromise;
+    private uploadPromise;
     private prepared;
     private activeTurn;
     private genericToolHandler;
@@ -249,6 +273,8 @@ export declare class PedelecSession<TToolName extends string = string> {
     onChat(handler: ChatHandler): () => void;
     onTool(handler: GenericToolHandler<TToolName>): () => void;
     onTool<TArgs = unknown, TResult = unknown>(toolName: TToolName, handler: ToolSpecificHandler<TArgs, TResult>): () => void;
+    uploadAsset(file: File): Promise<SandboxAssetPath>;
+    listAssets(): Promise<SandboxAsset[]>;
     onError(handler: ErrorHandler): () => void;
     onStatus(handler: StatusHandler): () => void;
     onEnded(handler: EndedHandler): () => void;

package/dist/index.js

@@ -1,6 +1,29 @@
 import { PEDELEC_EXTENSION_ID } from "./extension-id.js";
 const SDK_EXTERNAL_PORT_NAME = "pedelec-sdk-external";
 const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
+function normalizeListAssetsResponse(response) {
+    if (!response || typeof response !== "object" || Array.isArray(response))
+        return invalidListAssetsResponse(response);
+    const assets = response.assets;
+    if (!Array.isArray(assets))
+        return invalidListAssetsResponse(response);
+    return assets.map((asset, index) => {
+        if (!asset || typeof asset !== "object" || Array.isArray(asset))
+            return invalidListAssetsResponse({ index, asset });
+        const { name, path, sizeBytes, modifiedAt } = asset;
+        const validName = typeof name === "string" && name.length > 0 && name !== "." && name !== ".." && !name.includes("/") && !name.includes("\\");
+        const validPath = typeof path === "string" && !path.includes("\\") && path === `input/${name}` && !path.split("/").includes("..");
+        const validNumber = (value) => typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+        if (!validName || !validPath || !validNumber(sizeBytes) || !validNumber(modifiedAt)) {
+            return invalidListAssetsResponse({ index, asset });
+        }
+        return { name, path: path, sizeBytes: sizeBytes, modifiedAt: modifiedAt };
+    });
+}
+function invalidListAssetsResponse(details) {
+    throw makeError("SDK_PROTOCOL_ERROR", "list_assets response had an invalid shape", { response: details });
+}
+const MAX_ASSET_UPLOAD_BYTES = 100 * 1024 * 1024;
 const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.-]*$/;
 export function defineTool(tool) {
     return tool;
@@ -241,6 +264,58 @@ export class Pedelec {
             autoEndOnDisconnect,
         };
     }
+    async checkAvailability() {
+        const origin = getCurrentOrigin(this.pageWindow);
+        let approval;
+        try {
+            approval = await this.getApprovalStatus();
+        }
+        catch (err) {
+            const error = normalizeError(err, "SDK_TRANSPORT_ERROR", "Could not read Pedelec approval status.");
+            return {
+                available: false,
+                extension: { available: !isExtensionUnavailableError(error) },
+                approval: { approved: false, origin },
+                desktop: { available: false, launchAttempted: false },
+                error,
+            };
+        }
+        if (!approval.installed) {
+            return {
+                available: false,
+                extension: { available: false },
+                approval: { approved: false, origin: approval.origin ?? origin },
+                desktop: { available: false, launchAttempted: false },
+            };
+        }
+        if (!approval.approved) {
+            return {
+                available: false,
+                extension: { available: true },
+                approval: { approved: false, origin: approval.origin },
+                desktop: { available: false, launchAttempted: false },
+            };
+        }
+        try {
+            await this.getSettings();
+            return {
+                available: true,
+                extension: { available: true },
+                approval: { approved: true, origin: approval.origin },
+                desktop: { available: true, launchAttempted: true },
+            };
+        }
+        catch (err) {
+            const error = normalizeError(err, "SDK_TRANSPORT_ERROR", "Could not reach Pedelec Desktop.");
+            return {
+                available: false,
+                extension: { available: true },
+                approval: { approved: true, origin: approval.origin },
+                desktop: { available: false, launchAttempted: true },
+                error,
+            };
+        }
+    }
     async resolveDefaultCreateSessionInput(normalizedSkills, autoEndOnDisconnect) {
         const settings = await this.getSettings();
         if (!settings.defaultProvider) {
@@ -372,6 +447,7 @@ export class PedelecSession {
     pendingSend = null;
     pendingPrepare = null;
     preparePromise = null;
+    uploadPromise = null;
     prepared = false;
     activeTurn = null;
     genericToolHandler = null;
@@ -392,7 +468,7 @@ export class PedelecSession {
         if (this.status === "ended") {
             return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
         }
-        if (this.pendingSend) {
+        if (this.pendingSend || this.uploadPromise) {
             return Promise.reject(makeError("SESSION_BUSY", "session is already running", { sessionId: this.sessionId }));
         }
         if (this.prepared) {
@@ -428,6 +504,9 @@ export class PedelecSession {
         return this.preparePromise;
     }
     async sendText(text) {
+        if (this.uploadPromise) {
+            return Promise.reject(makeError("SESSION_BUSY", "an asset upload is in progress", { sessionId: this.sessionId }));
+        }
         if (this.preparePromise) {
             try {
                 await this.preparePromise;
@@ -490,6 +569,48 @@ export class PedelecSession {
             }
         };
     }
+    uploadAsset(file) {
+        if (this.status === "ended")
+            return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
+        if (this.pendingSend || this.pendingPrepare || this.preparePromise || this.uploadPromise || this.status !== "idle") {
+            return Promise.reject(makeError("SESSION_BUSY", "session is busy", { sessionId: this.sessionId }));
+        }
+        if (typeof File === "undefined" || !(file instanceof File) || !file.name || file.size < 0) {
+            return Promise.reject(makeError("INVALID_INPUT", "uploadAsset requires a browser File with a filename"));
+        }
+        if (file.size > MAX_ASSET_UPLOAD_BYTES)
+            return Promise.reject(makeError("ASSET_TOO_LARGE", "asset exceeds the 100 MiB limit"));
+        this.uploadPromise = this.client.request("create_asset_upload", {
+            sessionId: this.sessionId, filename: file.name, sizeBytes: file.size, mimeType: file.type,
+        }).then(async (ticket) => {
+            if (!ticket?.uploadUrl || !ticket.token)
+                throw makeError("SDK_PROTOCOL_ERROR", "asset upload ticket was invalid");
+            let response;
+            try {
+                response = await fetch(ticket.uploadUrl, { method: "PUT", headers: { Authorization: `Bearer ${ticket.token}`, "Content-Type": file.type || "application/octet-stream" }, body: file, credentials: "omit" });
+            }
+            catch (error) {
+                throw normalizeError(error, "ASSET_UPLOAD_FAILED", "asset upload failed");
+            }
+            let payload = null;
+            try {
+                payload = await response.json();
+            }
+            catch { /* normalized below */ }
+            if (!response.ok)
+                throw normalizeError(payload?.error, "ASSET_UPLOAD_FAILED", "asset upload failed");
+            if (typeof payload?.path !== "string" || !payload.path.startsWith("input/") || payload.path.includes(".."))
+                throw makeError("SDK_PROTOCOL_ERROR", "asset upload response had an invalid path");
+            return payload.path;
+        }).finally(() => { this.uploadPromise = null; });
+        return this.uploadPromise;
+    }
+    listAssets() {
+        if (this.status === "ended") {
+            return Promise.reject(makeError("SESSION_ENDED", "session has ended", { sessionId: this.sessionId }));
+        }
+        return this.client.request("list_assets", { sessionId: this.sessionId }).then(normalizeListAssetsResponse);
+    }
     onError(handler) {
         this.errorHandlers.add(handler);
         return () => this.errorHandlers.delete(handler);
@@ -839,6 +960,9 @@ function getCurrentOrigin(pageWindow) {
     const origin = pageWindow?.location?.origin;
     return typeof origin === "string" && origin ? origin : null;
 }
+function isExtensionUnavailableError(error) {
+    return error.code === "EXTENSION_UNAVAILABLE" || error.code === "EXTENSION_DISCONNECTED";
+}
 function normalizeError(err, fallbackCode, fallbackMessage) {
     if (!err)
         return makeError(fallbackCode, fallbackMessage);

package/dist/index.type-test.js

@@ -88,9 +88,26 @@ async function noSkillsFallsBackToString() {
         return { ok: true };
     });
 }
+async function listAssetsHasPublicTypes() {
+    const pedelec = new Pedelec();
+    const session = await pedelec.resumeSession("thread_1");
+    const assets = await session.listAssets();
+    assets;
+    const path = assets[0].path;
+    path;
+}
+async function availabilityHasPublicType() {
+    const pedelec = new Pedelec();
+    const availability = await pedelec.checkAvailability();
+    const promise = pedelec.checkAvailability();
+    void availability;
+    void promise;
+}
 void typedOnToolNameFromCreateSession;
 void resumedSessionFallsBackToString;
 void noSkillsFallsBackToString;
+void listAssetsHasPublicTypes;
+void availabilityHasPublicType;
 const baseContext = {
     sessionId: "thread_1",
     provider: "codex",

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@kaoruisaac/pedelec",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],