SDK Overview

The edge-pi package is a TypeScript library for building AI-powered coding agents. It is built on the Vercel AI SDK and works with any LanguageModel provider.

Installation

npm install edge-pi ai

You also need a provider package. For example, for Anthropic:

npm install @ai-sdk/anthropic

CodingAgent

The main entry point is the CodingAgent class. It implements the Vercel AI SDK Agent interface and wraps the SDK's tool loop with defaults for coding tasks.

Constructor

import { CodingAgent } from "edge-pi";
import { stepCountIs } from "ai";

const agent = new CodingAgent({
  model,              // Required: Vercel AI LanguageModel
  cwd,                // Working directory (default: process.cwd())
  stopWhen,           // Optional: StopCondition or array (default: run until model stops)
  systemPromptOptions,// Configure the prompt builder
  toolSet,            // "coding" | "readonly" | "all" (default: "coding")
  tools,              // Merge additional tools into the set
  providerOptions,    // Optional provider-specific options passed to model calls
  sessionManager,     // Optional: SessionManager for auto-persist
  compaction,         // Optional: built-in auto/manual context compaction
});

Configuration

Option	Type	Default	Description
`model`	`LanguageModel`	—	Required. Any Vercel AI SDK model.
`cwd`	`string`	`process.cwd()`	Working directory for tools.
`stopWhen`	`StopCondition \| StopCondition[]`	—	Stop condition(s) for the agent loop. Use helpers like `stepCountIs(n)` or `hasToolCall(name)` from `ai`. When omitted, runs until the model stops.
`systemPromptOptions`	`BuildSystemPromptOptions`	—	Configure the system prompt builder.
`toolSet`	`"coding" \| "readonly" \| "all"`	`"coding"`	Which tool set to use.
`tools`	`ToolSet`	—	Additional tools to merge in.
`providerOptions`	`Record<string, Record<string, JSONValue>>`	—	Optional provider-specific options to forward to model calls.
`compaction`	`CompactionConfig`	—	Optional built-in compaction configuration (auto or manual mode via `agent.compact()`).
`sessionManager`	`SessionManager`	—	Optional session manager for auto-persist. Messages are auto-restored on construction and auto-persisted after `generate()` and `stream()`.

Execution Methods

generate()

Non-streaming execution. Runs the tool loop to completion and returns a GenerateTextResult.

const result = await agent.generate({
  prompt: "Read src/index.ts and explain it",
  // Optional: provide messages instead of prompt
  // messages: [{ role: "user", content: "..." }],
});

console.log(result.text);          // Final text response
console.log(result.steps.length);  // Number of tool steps
console.log(result.totalUsage);    // Token usage

stream()

Streaming execution. Returns a Vercel AI StreamTextResult that you can consume incrementally.

const stream = await agent.stream({
  prompt: "Find and fix the bug in src/parser.ts",
});

// Stream text chunks
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

// Or access the full result after streaming
const result = await stream;
console.log(result.usage);

Message Control

The agent provides methods to control messages during and between executions.

setMessages()

Restore a previous message history (e.g., from a session).

agent.setMessages(previousMessages);

steer()

Inject a message between tool steps during execution. Useful for providing corrections mid-loop.

// While the agent is running:
agent.steer({
  role: "user",
  content: "Actually, use the v2 API instead",
});

abort()

Abort the current execution.

agent.abort();

Tool Sets

Three pre-configured tool sets are available:

Set	Tools	Use Case
`coding`	read, bash, edit, write	General coding tasks (default)
`readonly`	read, grep, find, ls	Code review, analysis, exploration
`all`	read, bash, edit, write, grep, find, ls	Full capabilities

See the Tools page for detailed documentation on each tool.

Exports

The edge-pi package exports the following:

// Agent
import { CodingAgent } from "edge-pi";

// Tool factories
import {
  createBashTool,
  createReadTool,
  createWriteTool,
  createEditTool,
  createGrepTool,
  createFindTool,
  createLsTool,
  createCodingTools,
  createReadOnlyTools,
  createAllTools,
} from "edge-pi";

// System prompt
import { buildSystemPrompt } from "edge-pi";

// Session management
import { SessionManager, buildSessionContext } from "edge-pi";

// Compaction
import {
  CompactionConfig,
  generateBranchSummary,
  collectEntriesForBranchSummary,
} from "edge-pi";

// Types (re-exported from Vercel AI SDK)
import type {
  Agent,
  AgentCallParameters,
  AgentStreamParameters,
  CodingAgentConfig,
  LanguageModel,
  ModelMessage,
  GenerateTextResult,
  StopCondition,
  StreamTextResult,
  Tool,
  ToolSet,
  LanguageModelUsage,
} from "edge-pi";