SDK and RPC mode

#Choose an integration

#Install

npm install autopilot-ai

#Create a session

import { createAgentSession } from "autopilot-ai/sdk";

const { session } = await createAgentSession({
  cwd: "/path/to/project",
  config: {
    openrouterApiKey: process.env.OPENROUTER_API_KEY,
    model: "moonshotai/kimi-k2.7-code",
  },
});

// Stream every event
session.subscribe((event) => {
  console.log(event.type, event);
});

// Run a turn
await session.prompt("Refactor auth to JWT + Redis");

// Correct the agent while it is still running
await session.steer("Use Redis instead of an in-memory store");

// Queue another turn after the current one
await session.followUp("Also add unit tests");

// Clean up
session.dispose();

#createAgentSession options

#Session methods

prompt() options:

#Events

The full types are in src/sdk/types.ts.

#Permission decisions

A permissionHandler or resolvePermission call returns one of:

• "allow", "allow_session" or "deny";
• { decision: "allow" | "deny", scope: "once" | "session" | "pattern" }.

#Blocked prompts

If a UserPromptSubmit hook blocks a prompt, prompt() rejects with PromptBlockedError, which is exported from autopilot-ai/sdk.

#Authentication

The SDK uses the active provider: provider in config (or AUTOPILOT_PROVIDER), otherwise OpenRouter. It needs that provider's key, from providers.<id>.apiKey in config or the provider's environment variable. A custom gateway endpoint (baseUrl and apiKey) needs no other key.

For OpenRouter, the key is resolved in this order:

1. openrouterApiKey in the config option (recommended for apps).
2. OPENROUTER_API_KEY or KIMIFLARE_OPENROUTER_KEY.
3. The config file ~/.config/kimiflare/config.json.

A Requesty key (requestyApiKey, or REQUESTY_API_KEY) also works when no OpenRouter key is set.

In a desktop app, store the key in the OS keychain and pass it explicitly:

import { createAgentSession } from "autopilot-ai/sdk";

const openrouterApiKey = await keytar.getPassword("autopilot", "openrouter");

const { session } = await createAgentSession({
  cwd: projectPath,
  config: { openrouterApiKey },
});

#Ending a session

Call session.dispose() when you're done. It is the reliable way to end a session: it runs SessionEnd hooks, writes the trace's session_end, and stops background subagents, LSP and memory.

As a safety net, a live session also ends if your process exits without dispose(). On beforeExit, SIGTERM, SIGINT or SIGHUP, the SDK runs SessionEnd hooks and flushes OpenTelemetry events within a 3 second budget. It never calls process.exit:

• If your app has its own listener for the signal, the SDK starts the shutdown work and your handler decides what happens next.
• If it doesn't, the SDK finishes the work and re-raises the signal, so the process still exits from it (status 143 for SIGTERM, 130 for SIGINT).

After an uncaught exception or an explicit process.exit(), there is no time for asynchronous work: the SDK only starts the SessionEnd hook commands. If your app handles uncaughtException itself, call dispose() from your handler.

To turn this off:

const { session } = await createAgentSession({ cwd, handleProcessExit: false });

#RPC mode

RPC mode speaks JSONL over stdio: one JSON object per line on stdin, and one per line on stdout.

autopilot --mode rpc

Give the subprocess a provider key (for example OPENROUTER_API_KEY), or a custom gateway endpoint (KIMIFLARE_BASE_URL and KIMIFLARE_API_KEY).

import { spawn } from "node:child_process";

const proc = spawn("npx", ["autopilot-ai", "--mode", "rpc"], {
  cwd: projectPath,
  stdio: ["pipe", "pipe", "pipe"],
});

proc.stdout.on("data", (chunk) => {
  for (const line of chunk.toString().split("\n")) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);
    console.log(event.type, event);
  }
});

proc.stdin.write(JSON.stringify({ type: "new_session" }) + "\n");
proc.stdin.write(JSON.stringify({ type: "prompt", message: "Hello" }) + "\n");

// Answer a permission request
proc.stdin.write(
  JSON.stringify({ type: "resolve_permission", requestId: "req_0", decision: "allow" }) + "\n"
);

// Resume a saved session after a restart
proc.stdin.write(JSON.stringify({ type: "new_session", sessionId: "sdk-session-..." }) + "\n");

#RPC commands

Every command can carry an id, which is echoed on its response.

Session events are written to stdout as they happen, with the same type values as the SDK. Commands sent before new_session get {"type": "error", "error": "No active session"}. Prompts run off the read loop, so you can send resolve_permission or abort while a turn is running.