Types

All types below are exported from @kaoruisaac/pedelec.

import type {
  PedelecOptions,
  ProviderCode,
  EffortLevel,
  Effort,
  ProviderInfo,
  PedelecSessionStatus,
  PedelecSessionUsage,
  ToolArgsSchema,
  Asset,
  AssetPath,
  ReadAssetType,
  PedelecWorkspace,
  WorkspaceRunOptions,
  WorkspaceRunResult,
} from "@kaoruisaac/pedelec";

Client and session input

PedelecOptions

type PedelecOptions = {
  runtimeFullAccess?: boolean;
  bridgeTimeoutMs?: number;
};

ProviderCode

type ProviderCode =
  | "codex"
  | "antigravity"
  | "opencode"
  | "cursor"
  | "claude"
  | "ollama";

EffortLevel

type EffortLevel = "default" | "low" | "high";

EffortLevel is the Pedelec/Desktop profile selector. It selects one complete configured profile, including that profile’s model and provider-native effort settings.

Effort

type Effort = "low" | "medium" | "high" | "xhigh" | "max";

Effort is the provider-native reasoning-effort value used only in explicit model mode. It is optional when model is supplied and cannot be used by itself. Provider-specific support is validated at runtime.

CreateSessionInput

type CreateSessionInput<
  TTools extends readonly ToolDefinition[] = readonly ToolDefinition[],
> =
  | {
      provider?: ProviderCode;
      effortLevel?: EffortLevel;
      model?: never;
      effort?: never;
      skills?: SkillsInput<TTools>;
      runtimeFullAccess?: boolean;
      autoEndOnDisconnect?: boolean;
    }
  | {
      provider?: ProviderCode;
      model: string;
      effort?: Effort;
      effortLevel?: never;
      skills?: SkillsInput<TTools>;
      runtimeFullAccess?: boolean;
      autoEndOnDisconnect?: boolean;
    };

effortLevel selects Desktop profile mode. model selects explicit provider configuration and may be paired with provider-native effort; these modes are mutually exclusive. Model-only explicit mode is valid and uses provider-default effort behavior. effort cannot be supplied without model.

PedelecWorkspace

class PedelecWorkspace {
  readonly path: string | null;
  createSession(): Promise<PedelecSession<string>>;
  createSession<const TTools extends readonly ToolDefinition[]>(
    input: CreateSessionInput<TTools>,
  ): Promise<PedelecSession<ToolNameOf<TTools>>>;
  listFiles(path?: string): Promise<string[]>;
  listFolders(path?: string): Promise<string[]>;
  uploadFile(file: File): Promise<string>;
  uploadFile(file: File, targetPath: string): Promise<string>;
  readFile(path: string, type: "text"): Promise<string>;
  readFile<T = JsonValue>(path: string, type: "json"): Promise<T>;
  readFile(path: string, type: "file"): Promise<File>;
  run(script: string, options?: WorkspaceRunOptions): Promise<WorkspaceRunResult>;
}

PedelecWorkspace is returned by openWorkspace(), createSession().workspace, and resumeSession().workspace. Its opaque workspace identity is intentionally not public.

WorkspaceRunOptions

type WorkspaceRunOptions = {
  runtimeModules?: readonly RuntimeModuleDefinition[];
  /** @deprecated Use runtimeModules. Do not provide both fields. */
  denoModules?: readonly RuntimeModuleDefinition[];
  timeoutMs?: number;
};

WorkspaceRunResult

type WorkspaceRunResult = {
  exitCode: number;
  stdout: string;
  stderr: string;
  stdoutTruncated: boolean;
  stderrTruncated: boolean;
}

Provider and settings

ProviderInfo

type ProviderInfo = {
  name: string;
  code: ProviderCode;
  available: boolean;
  isDefault: boolean;
  error: string | null;
};

PedelecSettings

type PedelecSettings = {
  defaultProvider: ProviderCode | null;
};

ApprovalStatus

type ApprovalStatus = {
  installed: boolean;
  approved: boolean;
  agentSessionsApproved?: boolean;
  runtimeFullAccessApproved?: boolean;
  origin: string | null;
  appConnected: boolean;
};

PedelecAvailability

type PedelecAvailability = {
  available: boolean;
  extension: { available: boolean };
  approval: { approved: boolean; origin: string | null };
  desktop: { available: boolean; launchAttempted: boolean };
  error?: PedelecError;
};

PedelecSettings is a public defaults-only DTO: it never contains provider credentials. ProviderInfo only exposes name, code, available, isDefault, and error. isDefault reflects the current Desktop default provider and is independent of available.

available requires every layer. launchAttempted can be true once the non-sensitive approval-status ping is sent; it does not confirm a process launch. appConnected reflects that ping only, not approval or provider readiness.

Assets

AssetPath

type AssetPath = `/${string}`;

The SDK public path for an asset in the Workspace shared store. Physically, the Agent-visible shared store is <workspace.path>/.pedelec-runtime/assets/; the .pedelec-runtime directory is private runtime layout and is not exposed in SDK values. For example, /images/photo.png refers to <workspace.path>/.pedelec-runtime/assets/images/photo.png. Runtime validation also rejects backslashes, empty path segments, . and ...

ReadAssetType

type ReadAssetType = "text" | "json" | "file";

Selects the conversion performed by PedelecSession.readAsset(): strict UTF-8 text, parsed JSON, or a browser File.

Asset

type Asset = {
  name: string;
  path: AssetPath;
  sizeBytes: number;
  modifiedAt: number;
};

modifiedAt is the workspace filesystem modification time. path is workspace-relative and does not reveal the browser user’s absolute local path.

Errors and status

PedelecError

type PedelecError = {
  code: string;
  message: string;
  details?: unknown;
};

Do not assume details has one global shape. Narrow by code and validate before reading.

PedelecSessionStatus

type PedelecSessionStatus =
  | "idle"
  | "running"
  | "waiting_tool_result"
  | "ended"
  | "error";

PedelecSessionUsage

type PedelecSessionUsage = {
  totalTokens?: number;
};

totalTokens is the normalized cumulative token total observed for one session. It is omitted until a supported provider reports a valid value.

JSON value types

JsonPrimitive

type JsonPrimitive = string | number | boolean | null;

JsonValue

type JsonValue =
  | JsonPrimitive
  | JsonValue[]
  | { [key: string]: JsonValue };

Used by tool schema metadata. Runtime tool results should follow the same practical JSON-compatible constraints even when their TypeScript return type is broader.

Tool definitions

ToolSpecificHandler

type ToolSpecificHandler<TArgs = unknown, TResult = unknown> = (
  args: TArgs,
  ctx: ToolCallContext,
) => TResult | Promise<TResult>;

ToolDefinition

type ToolDefinition<
  TArgs = unknown,
  TResult = unknown,
  TName extends string = string,
> = {
  name: TName;
  description: string;
  argsSchema: ToolArgsSchema;
  timeoutMs?: number;
  handler?: ToolSpecificHandler<TArgs, TResult>;
};

RuntimeModuleDefinition

type RuntimeModuleDefinition<TName extends string = string> = {
  name: TName;
  entry: string;
  description?: string;
  usage?: string;
  preferStdinExecution?: boolean;
};

name and entry are the intrinsic fields. entry is a Vite build/dev authoring string; it is not a Desktop filesystem instruction. description and usage are optional Agent-facing metadata, while preferStdinExecution remains a public authoring preference. When it is true, Host Context represents the preference as preferredExecution: "stdin"; the Agent should prefer the global runStdinCommand. File-backed execution remains valid, and no provider-specific shell syntax is part of the shared Host Context contract. The preference does not change bundling or artifact contents. Use pedelecVitePlugin() to prepare the runtime and declaration artifact.

Session skills use the stricter shape below: description and usage must both be non-empty strings. Workspace runs may use the minimal base declaration, but every module must contain a prepared Vite artifact.

type AgentModuleDefinition<TName extends string = string> =
  RuntimeModuleDefinition<TName> & {
    description: string;
    usage: string;
  };

SkillsInput

type SkillsInput<
  TTools extends readonly ToolDefinition[] = readonly ToolDefinition[],
> = {
  guidance: string;
  tools: TTools;
  runtimeModules?: readonly AgentModuleDefinition[];
  /** @deprecated Use runtimeModules. Do not provide both fields. */
  denoModules?: readonly AgentModuleDefinition[];
};

WebMcpInput

type WebMcpSkillsInput<
  TTools extends readonly ToolDefinition[] = readonly ToolDefinition[],
> = {
  tools: TTools;
};

type WebMcpInput<
  TTools extends readonly ToolDefinition[] = readonly ToolDefinition[],
> = {
  skills: WebMcpSkillsInput<TTools>;
};

type WebMcpBinding = {
  available: boolean;
  dispose(): void;
};

pedelec.webmcp() accepts tools only. It does not take guidance or runtimeModules. dispose() aborts that binding’s WebMCP registrations. See the Tools API for availability and handler context limits.

ToolNameOf

type ToolNameOf<TTools extends readonly ToolDefinition[]> = Extract<
  TTools[number]["name"],
  string
>;

Serializable manifests

type SerializableToolManifest = {
  name: string;
  description: string;
  argsSchema: ToolArgsSchema;
  timeoutMs?: number;
};

type SerializableSkillsManifest = {
  guidance: string;
  tools: SerializableToolManifest[];
  denoModules?: Array<{
    name: string;
    description: string;
    usage: string;
    preferStdinExecution?: boolean;
  }>;
};

Inline handlers and the build-time entry field are not part of the serialized manifest.

Tool schema metadata

type ToolArgsSchemaMeta<
  TDefault extends JsonValue = JsonValue,
> = {
  description?: string;
  default?: TDefault;
  examples?: TDefault[];
};

Tool schema nodes

String

type ToolArgsStringSchema = ToolArgsSchemaMeta<string> & {
  type: "string";
  enum?: string[];
  minLength?: number;
  maxLength?: number;
  pattern?: string;
};

Number

type ToolArgsNumberSchema = ToolArgsSchemaMeta<number> & {
  type: "number";
  enum?: number[];
  minimum?: number;
  maximum?: number;
};

Integer

type ToolArgsIntegerSchema = ToolArgsSchemaMeta<number> & {
  type: "integer";
  enum?: number[];
  minimum?: number;
  maximum?: number;
};

Boolean

type ToolArgsBooleanSchema = ToolArgsSchemaMeta<boolean> & {
  type: "boolean";
  enum?: boolean[];
};

Array

type ToolArgsArraySchema = ToolArgsSchemaMeta<JsonValue[]> & {
  type: "array";
  items: ToolArgsSchemaNode;
  minItems?: number;
  maxItems?: number;
  uniqueItems?: boolean;
};

Object

type ToolArgsObjectSchema = ToolArgsSchemaMeta<
  Record<string, JsonValue>
> & {
  type: "object";
  properties?: Record<string, ToolArgsSchemaNode>;
  required?: string[];
  additionalProperties?: boolean;
};

One-of

type ToolArgsOneOfSchema = ToolArgsSchemaMeta & {
  oneOf: ToolArgsSchemaNode[];
};

Node and root aliases

type ToolArgsSchemaNode =
  | ToolArgsStringSchema
  | ToolArgsNumberSchema
  | ToolArgsIntegerSchema
  | ToolArgsBooleanSchema
  | ToolArgsArraySchema
  | ToolArgsObjectSchema
  | ToolArgsOneOfSchema;

type ToolArgsSchema = ToolArgsObjectSchema;

The root alias enforces an object schema at compile time. Object schemas (root and nested) accept extra fields by default; use additionalProperties: false to reject them. This applies to the original tool arguments, including a field named timeoutMs if passed by the agent.

Event contexts

PedelecEventContext

type PedelecEventContext = {
  sessionId: string;
  provider: string;
  effortLevel?: "default" | "low" | "high";
  sessionCreatedAt: number;
  eventReceivedAt?: number;
  eventEmittedAt: number;
  turnId?: string;
  turnStartedAt?: number;
  turnKind?: "user" | "prepare";
  source: "core" | "sdk";
};

ChatEventContext

Context for completed onChat() messages.

type ChatEventContext = PedelecEventContext & {
  type: "chat_message";
  turnId: string;
  turnStartedAt: number;
  eventReceivedAt: number;
};

ChatDeltaEventContext

Context for best-effort incremental onChatDelta() fragments.

type ChatDeltaEventContext = PedelecEventContext & {
  type: "chat_delta";
  turnId: string;
  turnStartedAt: number;
  eventReceivedAt: number;
};

ToolCallContext

type ToolCallContext = PedelecEventContext & {
  type: "tool_call";
  toolRequestId: string;
  tool: string;
  turnId: string;
  turnStartedAt: number;
  eventReceivedAt: number;
};

StatusEventContext

type StatusEventContext = PedelecEventContext & {
  type: "status_changed" | "sdk_status_changed";
  status: PedelecSessionStatus;
  previousStatus: PedelecSessionStatus;
};

ErrorEventContext

type ErrorEventContext = PedelecEventContext & {
  type: "error" | "sdk_error";
};

EndedEventContext

type EndedEventContext = PedelecEventContext & {
  type: "ended" | "sdk_ended";
};

Fields marked optional in the base context are present only when relevant. Treat IDs as opaque and timestamps as browser diagnostics, not security claims.

Legacy module compatibility

DenoModuleDefinition, defineDenoModule() and denoModules remain usable and are marked @deprecated in TypeScript. Migrate to RuntimeModuleDefinition, defineRuntimeModule() and runtimeModules. Supply exactly one module field per skills/options object; supplying both rejects with INVALID_INPUT, even when either list is empty. The internal SerializableSkillsManifest.denoModules wire field remains unchanged.

// Existing integrations remain valid:
import { defineDenoModule, defineRuntimeModule, type DenoModuleDefinition } from "@kaoruisaac/pedelec";
const legacy: DenoModuleDefinition = defineDenoModule({ name: "project-tools", entry: "./agent/project-tools.ts" });
await workspace.run('import "project-tools";', { denoModules: [legacy] });
// New integrations:
const modern = defineRuntimeModule({ name: "project-tools", entry: "./agent/project-tools.ts" });
await workspace.run('import "project-tools";', { runtimeModules: [modern] });