Types

All types below are exported from @kaoruisaac/pedelec.

import type {
  PedelecOptions,
  ProviderCode,
  ProviderInfo,
  PedelecSessionStatus,
  PedelecSessionUsage,
  ToolArgsSchema,
  Asset,
  AssetPath,
  ReadAssetType,
  CreateSessionWorkspaceInput,
  WorkspaceFolderPickerResult,
} from "@kaoruisaac/pedelec";

Client and session input

`PedelecOptions`

type PedelecOptions = {
  bridgeTimeoutMs?: number;
};

`ProviderCode`

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

`CreateSessionInput`

type CreateSessionInput<
  TTools extends readonly ToolDefinition[] = readonly ToolDefinition[],
> =
  | {
      provider: ProviderCode;
      effortLevel?: "default" | "low" | "high";
      skills?: SkillsInput<TTools>;
      workspace?: CreateSessionWorkspaceInput;
      autoEndOnDisconnect?: boolean;
    }
  | {
      provider?: undefined;
      effortLevel?: "default" | "low" | "high";
      skills?: SkillsInput<TTools>;
      workspace?: CreateSessionWorkspaceInput;
      autoEndOnDisconnect?: boolean;
    };

effortLevel is provider-independent and may be used with or without provider.

`CreateSessionWorkspaceInput`

type CreateSessionWorkspaceInput = {
  path: string;
};

path is an absolute application-managed workspace path. Pedelec creates missing runtime subdirectories but never deletes this workspace. It may be shared by multiple active sessions and must not overlap the managed workspace root.

`WorkspaceFolderPickerResult`

interface WorkspaceFolderPickerResult {
  path: string;
  isEmptyFolder: boolean;
  hasWorkspaceConfig: boolean;
}

This is the read-only snapshot returned by workspaceFolderPicker(). hasWorkspaceConfig only indicates that .pedelec-workspace.json is a regular file; it does not validate the marker contents.

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;
  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 session’s 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>;
};

`SkillsInput`

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

`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[];
};

Inline handlers 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[];
};

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.

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.