npm package: @prbe.ai/electron-sdk
Description: PRBE debug agent SDK for Electron apps
Latest version: 0.2.0

# @prbe.ai/electron-sdk

A lightweight TypeScript SDK that adds an AI debug agent to your Electron app. When users hit a bug, the agent investigates autonomously — reading files, searching logs, exploring your codebase — and produces a structured report for your team.

Zero external runtime dependencies. Node.js built-ins only.

## Install

```bash
npm install @prbe.ai/electron-sdk
```

Requires Node.js 18+ (for native `fetch` and `WebSocket`).

## Quick Start

```typescript
import { PRBEAgent, PRBEAgentConfigKey } from "@prbe.ai/electron-sdk";
import { app } from "electron";

const agent = new PRBEAgent({
  [PRBEAgentConfigKey.API_KEY]: "your-api-key",
  [PRBEAgentConfigKey.AUTO_APPROVED_DIRS]: [
    app.getPath("userData"),
    app.getAppPath(),
  ],
});

// Run an investigation
agent.investigate("App crashes when opening settings");
```

## Configuration

All config keys are available via the `PRBEAgentConfigKey` enum:

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `API_KEY` | `string` | *required* | Your PRBE API key |
| `AUTO_APPROVED_DIRS` | `string[]` | *required* | Directories the agent can access without asking the user |
| `APP_DATA_PATH` | `string` | — | Path to the app's data directory (e.g. Electron `userData`). Sent to the agent so it explores this directory first. |
| `BACKGROUND_POLLING` | `boolean` | `true` | Poll for context requests in the background |
| `POLLING_INTERVAL` | `number` | `600000` | Polling interval in ms (10 min) |
| `CAPTURE_CONSOLE` | `boolean` | `true` | Capture `console.*` calls into the log buffer |
| `MAX_LOG_ENTRIES` | `number` | `10000` | Max entries in the in-memory log buffer |
| `INTERACTION_HANDLER` | `PRBEInteractionHandler` | — | Handler for user interaction requests (ask questions, request permissions) |
| `ELECTRON_LOG` | `object` | — | `electron-log` v5 instance for log capture |
| `IPC_MAIN` | `object` | — | Electron `ipcMain` for renderer log forwarding |
| `RENDERER_LOG_CHANNEL` | `string` | `"prbe-renderer-log"` | IPC channel name for renderer logs |

## Listening to State

The agent exposes an observable state via `EventEmitter`:

```typescript
import { PRBEStateEvent } from "@prbe.ai/electron-sdk";

agent.state.on(PRBEStateEvent.STATUS, () => {
  console.log("Status:", agent.state.currentStatus);
  console.log("Events:", agent.state.events);
});

agent.state.on(PRBEStateEvent.ERROR, (payload) => {
  console.error("Investigation error:", payload.message);
});
```

## Custom Tools

Register tools that the AI agent can call during investigations:

```typescript
agent.registerTool(
  "get_database_stats",
  "Returns row counts for all tables in the local database",
  [
    { name: "table_filter", type: ToolParamType.STRING, description: "Optional table name filter", required: false },
  ],
  async (args) => {
    const filter = args.table_filter as string | undefined;
    const stats = await getDbStats(filter);
    return JSON.stringify(stats);
  },
);
```

## Built-in Tools

The SDK ships with 11 built-in tools that the agent uses automatically:

**Filesystem** — `list_directory`, `read_file`, `search_content`, `find_files`, `flag_file`

**Logs** — `read_app_logs`, `search_app_logs`, `clear_app_logs`, `flag_app_logs`

**Interactive** — `ask_user`, `bash_execute` (requires `INTERACTION_HANDLER`)

All filesystem access is sandboxed to your configured `AUTO_APPROVED_DIRS`. The agent can request access to paths outside these directories via the interaction handler, and the user can approve or deny each request individually.

Interactive tools are marked with `interactive: true` in their declaration, which tells the middleware to use a longer timeout (10 minutes) since they require user input.

## Renderer-Safe Types

For renderer/browser code that needs PRBE types without Node.js imports:

```typescript
import type { PRBESerializedState } from "@prbe.ai/electron-sdk/types";
```

## Serialization

Serialize agent state for IPC transport to your renderer process:

```typescript
import { serializePRBEState, DEFAULT_PRBE_STATE } from "@prbe.ai/electron-sdk";

// Send to renderer
const serialized = serializePRBEState(agent.state);
mainWindow.webContents.send("prbe-state", serialized);
```

## Links

- [Website](https://useprobe.ai)

## License

MIT