@flint-dev/sdk 0.2.0 → 0.2.1

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@flint-dev/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TypeScript client SDK for Flint app servers",
   "license": "MIT",
   "author": "Aaron Escalona",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +14,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     }
   },

package/src/app-server-client.ts

@@ -0,0 +1,524 @@
+/**
+ * App Server Client
+ *
+ * Spawns an app-server-compatible child process and communicates
+ * over stdio using JSON-RPC 2.0. Translates app-server notifications
+ * to AgentEvent for TUI consumption.
+ */
+
+import type { AgentEvent } from "./types";
+
+interface JsonRpcRequest {
+  id: number;
+  method: string;
+  params?: unknown;
+}
+
+interface JsonRpcResponse {
+  id: number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+interface JsonRpcNotification {
+  method: string;
+  params?: unknown;
+}
+
+type JsonRpcMessage = JsonRpcResponse | JsonRpcNotification;
+
+export interface AppServerClientOptions {
+  /** Command to spawn the app server */
+  command: string;
+  /** Arguments to pass to the command */
+  args?: string[];
+  /** Working directory for the app server and Claude SDK */
+  cwd: string;
+  /** Environment variables for the app server process */
+  env?: Record<string, string>;
+}
+
+export interface CreateThreadOptions {
+  /** Model to use for the thread (e.g. "claude-sonnet-4-5-20250929") */
+  model?: string;
+  /** Optional provider-specific system prompt override */
+  systemPrompt?: string;
+  /** Optional MCP server config (provider-specific) */
+  mcpServers?: Record<string, unknown>;
+}
+
+export interface PromptOptions {
+  /** Model override for this turn */
+  model?: string;
+}
+
+export interface ResumeThreadOptions {
+  /** Override working directory when resuming */
+  cwd?: string;
+  /** Override model when resuming */
+  model?: string;
+  /** Optional MCP server config (provider-specific) */
+  mcpServers?: Record<string, unknown>;
+}
+
+export class AppServerClient {
+  private stdin: import("bun").FileSink | null = null;
+  private stdout: ReadableStream<Uint8Array> | null = null;
+  private stderr: ReadableStream<Uint8Array> | null = null;
+  private proc: ReturnType<typeof Bun.spawn> | null = null;
+  private nextId = 1;
+  private pendingRequests = new Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  private notificationListeners: Array<(notification: JsonRpcNotification) => void> = [];
+  private buffer = "";
+  private stderrBuffer = "";
+  private stderrHistory: string[] = [];
+  private isClosing = false;
+  private initialized = false;
+  private threadId: string | null = null;
+  private currentTurnId: string | null = null;
+  private readonly command: string;
+  private readonly args: string[];
+  private readonly cwd: string;
+  private readonly env: Record<string, string> | undefined;
+
+  constructor(options: AppServerClientOptions) {
+    this.command = options.command;
+    this.args = options.args ?? [];
+    this.cwd = options.cwd;
+    this.env = options.env;
+  }
+
+  /** Start the app server process and initialize it. */
+  async start(): Promise<void> {
+    this.isClosing = false;
+    const proc = Bun.spawn([this.command, ...this.args], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      cwd: this.cwd,
+      ...(this.env && { env: { ...process.env, ...this.env } }),
+    });
+    this.proc = proc;
+    this.stdin = proc.stdin as import("bun").FileSink;
+    this.stdout = proc.stdout as ReadableStream<Uint8Array>;
+    this.stderr = proc.stderr as ReadableStream<Uint8Array>;
+
+    // Read stdout in background
+    this.readStdout();
+    this.readStderr();
+    this.watchProcessExit(proc);
+
+    // Initialize the server
+    await this.request("initialize", {
+      clientInfo: {
+        name: "flint-tui",
+        version: "0.1.0",
+      },
+    });
+
+    // Send initialized notification (Codex protocol)
+    this.notify("initialized");
+    this.initialized = true;
+  }
+
+  /** Create a new thread. Returns the thread ID. */
+  async createThread(options?: CreateThreadOptions): Promise<string> {
+    const result = (await this.request("thread/start", {
+      cwd: this.cwd,
+      ...(options?.model && { model: options.model }),
+      ...(options?.systemPrompt && { systemPrompt: options.systemPrompt }),
+      ...(options?.mcpServers && { mcpServers: options.mcpServers }),
+    })) as { thread: { id: string } };
+    this.threadId = result.thread.id;
+    return this.threadId;
+  }
+
+  /** Resume an existing thread. Returns the thread ID. */
+  async resumeThread(threadId: string, options?: ResumeThreadOptions): Promise<string> {
+    const result = (await this.request("thread/resume", {
+      threadId,
+      ...(options?.cwd && { cwd: options.cwd }),
+      ...(options?.model && { model: options.model }),
+      ...(options?.mcpServers && { mcpServers: options.mcpServers }),
+    })) as { thread: { id: string } };
+    this.threadId = result.thread.id;
+    return this.threadId;
+  }
+
+  /** Get the active thread ID (if any). */
+  getThreadId(): string | null {
+    return this.threadId;
+  }
+
+  /** Send a prompt and yield AgentEvents as they stream in. */
+  async *prompt(prompt: string, options?: PromptOptions): AsyncGenerator<AgentEvent> {
+    if (!this.threadId) {
+      await this.createThread();
+    }
+
+    // Set up notification listener before sending request
+    const events: AgentEvent[] = [];
+    let resolve: (() => void) | null = null;
+    let done = false;
+
+    const listener = (notification: JsonRpcNotification) => {
+      const translated = this.translateNotification(notification);
+      for (const event of translated) {
+        events.push(event);
+        resolve?.();
+      }
+
+      // Check for terminal notifications
+      if (notification.method === "turn/completed") {
+        done = true;
+        resolve?.();
+      }
+    };
+
+    this.notificationListeners.push(listener);
+
+    try {
+      // Start the turn
+      await this.request("turn/start", {
+        threadId: this.threadId,
+        input: [{ type: "text", text: prompt }],
+        ...(options?.model && { model: options.model }),
+      });
+
+      // Yield events as they come in
+      while (!done) {
+        if (events.length === 0) {
+          await new Promise<void>((r) => {
+            resolve = r;
+          });
+        }
+        while (events.length > 0) {
+          yield events.shift()!;
+        }
+      }
+      // Drain remaining
+      while (events.length > 0) {
+        yield events.shift()!;
+      }
+    } finally {
+      const idx = this.notificationListeners.indexOf(listener);
+      if (idx !== -1) this.notificationListeners.splice(idx, 1);
+    }
+  }
+
+  /** Interrupt the current turn. */
+  async interrupt(): Promise<void> {
+    if (!this.threadId || !this.currentTurnId) return;
+    try {
+      await this.request("turn/interrupt", {
+        threadId: this.threadId,
+        turnId: this.currentTurnId,
+      });
+    } catch {
+      // May fail if no turn in progress
+    }
+  }
+
+  /** Stop the app server process. */
+  close(): void {
+    this.isClosing = true;
+    if (this.proc) {
+      try {
+        this.stdin?.end();
+      } catch {
+        // Already closed
+      }
+      this.proc.kill();
+      this.proc = null;
+      this.stdin = null;
+      this.stdout = null;
+      this.stderr = null;
+    }
+    this.initialized = false;
+    this.threadId = null;
+    this.currentTurnId = null;
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────
+
+  private async request(method: string, params?: unknown): Promise<unknown> {
+    if (!this.stdin) throw new Error("App server not started");
+
+    const id = this.nextId++;
+    const request: JsonRpcRequest = {
+      id,
+      method,
+      ...(params !== undefined && { params }),
+    };
+
+    if (process.env.DEBUG) {
+      console.error(`[sdk] → ${method}`, params ? JSON.stringify(params) : "");
+    }
+
+    return new Promise<unknown>((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+      this.stdin!.write(JSON.stringify(request) + "\n");
+    });
+  }
+
+  private notify(method: string, params?: unknown): void {
+    if (!this.stdin) throw new Error("App server not started");
+    const notification: JsonRpcNotification = {
+      method,
+      ...(params !== undefined && { params }),
+    };
+    this.stdin.write(JSON.stringify(notification) + "\n");
+  }
+
+  private async readStdout(): Promise<void> {
+    if (!this.stdout) return;
+
+    const reader = this.stdout.getReader();
+    const decoder = new TextDecoder();
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        this.buffer += decoder.decode(value, { stream: true });
+
+        let newlineIdx: number;
+        while ((newlineIdx = this.buffer.indexOf("\n")) !== -1) {
+          const line = this.buffer.slice(0, newlineIdx);
+          this.buffer = this.buffer.slice(newlineIdx + 1);
+
+          if (line.trim()) {
+            this.handleMessage(line);
+          }
+        }
+      }
+    } catch {
+      // Process exited
+    }
+  }
+
+  private async readStderr(): Promise<void> {
+    if (!this.stderr) return;
+
+    const reader = this.stderr.getReader();
+    const decoder = new TextDecoder();
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        this.stderrBuffer += decoder.decode(value, { stream: true });
+
+        let newlineIdx: number;
+        while ((newlineIdx = this.stderrBuffer.indexOf("\n")) !== -1) {
+          const line = this.stderrBuffer.slice(0, newlineIdx);
+          this.stderrBuffer = this.stderrBuffer.slice(newlineIdx + 1);
+          this.pushStderrLine(line);
+        }
+      }
+    } catch {
+      // Process exited
+    }
+
+    if (this.stderrBuffer.trim()) {
+      this.pushStderrLine(this.stderrBuffer);
+      this.stderrBuffer = "";
+    }
+  }
+
+  private pushStderrLine(line: string): void {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    this.stderrHistory.push(trimmed);
+    if (this.stderrHistory.length > 60) {
+      this.stderrHistory.shift();
+    }
+
+    if (process.env.DEBUG) {
+      console.error(`[sdk][${this.command} stderr] ${trimmed}`);
+    }
+  }
+
+  private stderrTail(maxLines = 8): string {
+    return this.stderrHistory.slice(-maxLines).join("\n");
+  }
+
+  private async watchProcessExit(proc: ReturnType<typeof Bun.spawn>): Promise<void> {
+    const exitCode = await proc.exited;
+    if (this.proc !== proc || this.isClosing) return;
+
+    const tail = this.stderrTail();
+    const message = tail
+      ? `App server exited with code ${exitCode}\nRecent stderr:\n${tail}`
+      : `App server exited with code ${exitCode}`;
+
+    const error = new Error(message);
+    for (const [, pending] of this.pendingRequests) {
+      pending.reject(error);
+    }
+    this.pendingRequests.clear();
+  }
+
+  private handleMessage(line: string): void {
+    let msg: JsonRpcMessage;
+    try {
+      msg = JSON.parse(line) as JsonRpcMessage;
+    } catch {
+      return;
+    }
+
+    // Response (has id)
+    if ("id" in msg && msg.id != null) {
+      const response = msg as JsonRpcResponse;
+      const pending = this.pendingRequests.get(response.id);
+      if (pending) {
+        this.pendingRequests.delete(response.id);
+        if (response.error) {
+          pending.reject(new Error(response.error.message));
+        } else {
+          pending.resolve(response.result);
+        }
+      }
+      return;
+    }
+
+    // Notification (no id)
+    const notification = msg as JsonRpcNotification;
+    for (const listener of this.notificationListeners) {
+      listener(notification);
+    }
+  }
+
+  /** Translate app-server JSON-RPC notifications to AgentEvents. */
+  private translateNotification(notification: JsonRpcNotification): AgentEvent[] {
+    const events: AgentEvent[] = [];
+    const params = (notification.params ?? {}) as Record<string, unknown>;
+
+    switch (notification.method) {
+      case "item/agentMessage/delta": {
+        events.push({ type: "text", delta: params.delta as string });
+        break;
+      }
+
+      case "item/reasoning/textDelta": {
+        events.push({ type: "reasoning", delta: params.delta as string });
+        break;
+      }
+
+      case "item/started": {
+        const item = params.item as Record<string, unknown>;
+        if (!item) break;
+
+        const itemType = item.type as string;
+        const itemId = item.id as string;
+
+        if (itemType === "commandExecution") {
+          events.push({
+            type: "tool_start",
+            id: itemId,
+            name: "Bash",
+            input: { command: item.command, cwd: item.cwd },
+          });
+        } else if (itemType === "fileChange") {
+          const changes = item.changes as Array<{ path: string; kind: { type: string } }>;
+          const firstChange = changes?.[0];
+          const kindType = firstChange?.kind?.type;
+          const toolName = kindType === "add" ? "Write" : "Edit";
+          events.push({
+            type: "tool_start",
+            id: itemId,
+            name: toolName,
+            input: { file_path: firstChange?.path },
+          });
+        } else if (itemType === "mcpToolCall") {
+          events.push({
+            type: "tool_start",
+            id: itemId,
+            name: String(item.tool ?? "tool"),
+            input: item.arguments,
+          });
+        }
+        break;
+      }
+
+      case "item/completed": {
+        const item = params.item as Record<string, unknown>;
+        if (!item) break;
+
+        const itemId = item.id as string;
+        const itemType = item.type as string;
+
+        if (itemType === "commandExecution") {
+          const exitCode = item.exitCode as number | undefined;
+          events.push({
+            type: "tool_end",
+            id: itemId,
+            result: item.aggregatedOutput,
+            isError: (exitCode ?? 0) !== 0,
+          });
+        } else if (itemType === "fileChange") {
+          events.push({
+            type: "tool_end",
+            id: itemId,
+            result: undefined,
+            isError: false,
+          });
+        } else if (itemType === "mcpToolCall") {
+          events.push({
+            type: "tool_end",
+            id: itemId,
+            result: item.result,
+            isError: false,
+          });
+        }
+        break;
+      }
+
+      case "turn/started": {
+        const turn = params.turn as Record<string, unknown>;
+        if (turn) {
+          this.currentTurnId = turn.id as string;
+        }
+        break;
+      }
+
+      case "turn/completed": {
+        const turn = params.turn as Record<string, unknown>;
+        if (turn) {
+          const status = turn.status as string;
+          if (status === "failed") {
+            const error = turn.error as { message: string } | undefined;
+            events.push({
+              type: "error",
+              message: error?.message ?? "Unknown error",
+            });
+          } else {
+            events.push({ type: "done" });
+          }
+        } else {
+          events.push({ type: "done" });
+        }
+        this.currentTurnId = null;
+        break;
+      }
+
+      case "error": {
+        // Separate error notification — already handled via turn/completed
+        break;
+      }
+
+      // Ignored delta notifications that we don't translate to AgentEvent
+      case "item/commandExecution/outputDelta":
+      case "item/fileChange/outputDelta":
+        break;
+    }
+
+    return events;
+  }
+}

package/src/create-client.ts

@@ -0,0 +1,13 @@
+import { AppServerClient, type AppServerClientOptions } from "./app-server-client";
+import { getProvider, type ProviderConfig } from "./providers";
+
+export type CreateClientOptions = ({ provider: string } & ProviderConfig) | AppServerClientOptions;
+
+export function createClient(options: CreateClientOptions): AppServerClient {
+  if ("provider" in options) {
+    const { provider, ...config } = options;
+    const resolved = getProvider(provider).resolve(config);
+    return new AppServerClient(resolved);
+  }
+  return new AppServerClient(options);
+}

package/src/gateway-client.ts

@@ -0,0 +1,201 @@
+export type GatewayRoutingMode =
+  | "main"
+  | "per-peer"
+  | "per-channel-peer"
+  | "per-account-channel-peer";
+
+export type GatewayChatType = "direct" | "group" | "channel";
+
+export interface GatewayHealth {
+  ok: boolean;
+  provider: string;
+  defaultRoutingMode: GatewayRoutingMode;
+}
+
+export interface GatewayThreadRecord {
+  threadId: string;
+  routingMode: GatewayRoutingMode;
+  provider: string;
+  mcpProfileIds?: string[];
+  channel: string;
+  userId: string;
+  chatType: GatewayChatType;
+  peerId: string;
+  accountId?: string;
+  identityId?: string;
+  channelThreadId?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface GatewayCreateThreadRequest {
+  channel: string;
+  userId: string;
+  text: string;
+  mcpProfileIds?: string[];
+  provider?: string;
+  chatType?: GatewayChatType;
+  peerId?: string;
+  accountId?: string;
+  identityId?: string;
+  channelThreadId?: string;
+  routingMode?: GatewayRoutingMode;
+  idempotencyKey?: string;
+}
+
+export interface GatewaySendThreadRequest {
+  text: string;
+  idempotencyKey?: string;
+}
+
+export interface GatewayReply {
+  threadId: string;
+  routingMode: GatewayRoutingMode;
+  provider: string;
+  reply: string;
+  durationMs?: number;
+  idempotencyKey?: string;
+  cached?: boolean;
+}
+
+export interface GatewayClientOptions {
+  baseUrl: string;
+  headers?: ConstructorParameters<typeof Headers>[0];
+  fetch?: typeof fetch;
+}
+
+export class GatewayHttpError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(status: number, body: unknown) {
+    const errorMessage =
+      body && typeof body === "object" && "error" in body && typeof body.error === "string"
+        ? body.error
+        : `Gateway request failed with status ${status}`;
+    super(errorMessage);
+    this.name = "GatewayHttpError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class GatewayClient {
+  private readonly baseUrl: string;
+  private readonly defaultHeaders: Headers;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: GatewayClientOptions) {
+    this.baseUrl = options.baseUrl.trim().replace(/\/+$/, "");
+    if (!this.baseUrl) {
+      throw new Error("GatewayClient requires a non-empty baseUrl.");
+    }
+    this.defaultHeaders = new Headers(options.headers);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  async health(): Promise<GatewayHealth> {
+    return this.requestJson<GatewayHealth>("GET", "/v1/health");
+  }
+
+  async listThreads(): Promise<GatewayThreadRecord[]> {
+    const result = await this.requestJson<{ data: GatewayThreadRecord[] }>("GET", "/v1/threads");
+    return result.data;
+  }
+
+  async getThread(threadId: string): Promise<GatewayThreadRecord | undefined> {
+    const response = await this.request("GET", `/v1/threads/${encodeURIComponent(threadId)}`);
+    if (response.status === 404) {
+      return undefined;
+    }
+    return this.unwrapData<GatewayThreadRecord>(response);
+  }
+
+  async createThread(
+    payload: GatewayCreateThreadRequest,
+    idempotencyKey?: string,
+  ): Promise<GatewayReply> {
+    return this.requestJson<GatewayReply>("POST", "/v1/threads", payload, idempotencyKey);
+  }
+
+  async sendThreadMessage(
+    threadId: string,
+    payload: GatewaySendThreadRequest | string,
+    idempotencyKey?: string,
+  ): Promise<GatewayReply> {
+    const body = typeof payload === "string" ? { text: payload } : payload;
+    return this.requestJson<GatewayReply>(
+      "POST",
+      `/v1/threads/${encodeURIComponent(threadId)}`,
+      body,
+      idempotencyKey,
+    );
+  }
+
+  async interruptThread(threadId: string): Promise<boolean> {
+    const response = await this.request("POST", `/v1/threads/${encodeURIComponent(threadId)}/interrupt`);
+    if (response.status === 409) {
+      return false;
+    }
+    const result = await this.parseJsonOrThrow<{ interrupted: boolean }>(response);
+    return result.interrupted;
+  }
+
+  private async unwrapData<T>(response: Response): Promise<T> {
+    const parsed = await this.parseJsonOrThrow<{ data?: T }>(response);
+    if (!parsed || typeof parsed !== "object" || !("data" in parsed)) {
+      throw new Error("Gateway response is missing data.");
+    }
+    return parsed.data as T;
+  }
+
+  private async requestJson<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    idempotencyKey?: string,
+  ): Promise<T> {
+    const response = await this.request(method, path, body, idempotencyKey);
+    return this.parseJsonOrThrow<T>(response);
+  }
+
+  private async parseJsonOrThrow<T>(response: Response): Promise<T> {
+    const text = await response.text();
+    let parsed: unknown;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text) as unknown;
+      } catch {
+        parsed = undefined;
+      }
+    }
+    if (!response.ok) {
+      throw new GatewayHttpError(response.status, parsed);
+    }
+    return parsed as T;
+  }
+
+  private request(
+    method: string,
+    path: string,
+    body?: unknown,
+    idempotencyKey?: string,
+  ): Promise<Response> {
+    const headers = new Headers(this.defaultHeaders);
+    if (idempotencyKey?.trim()) {
+      headers.set("idempotency-key", idempotencyKey.trim());
+    }
+
+    const requestInit: RequestInit = {
+      method,
+      headers,
+    };
+
+    if (body !== undefined) {
+      headers.set("content-type", "application/json");
+      requestInit.body = JSON.stringify(body);
+    }
+
+    return this.fetchImpl(`${this.baseUrl}${path}`, requestInit);
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export {
+  AppServerClient,
+  type AppServerClientOptions,
+  type CreateThreadOptions,
+  type PromptOptions,
+  type ResumeThreadOptions,
+} from "./app-server-client";
+export type { AgentEvent } from "./types";
+export { createClient, type CreateClientOptions } from "./create-client";
+export { registerProvider, type Provider, type ProviderConfig } from "./providers";
+export {
+  GatewayClient,
+  GatewayHttpError,
+  type GatewayChatType,
+  type GatewayClientOptions,
+  type GatewayCreateThreadRequest,
+  type GatewayHealth,
+  type GatewayReply,
+  type GatewayRoutingMode,
+  type GatewaySendThreadRequest,
+  type GatewayThreadRecord,
+} from "./gateway-client";

package/src/providers.ts

@@ -0,0 +1,81 @@
+import { join, dirname } from "path";
+import { createRequire } from "module";
+import type { AppServerClientOptions } from "./app-server-client";
+
+export interface ProviderConfig {
+  cwd: string;
+  env?: Record<string, string>;
+}
+
+export interface Provider {
+  resolve(config: ProviderConfig): AppServerClientOptions;
+}
+
+const claudeProvider: Provider = {
+  resolve(config) {
+    const pkgPath = resolvePackagePath("@flint-dev/claude-app-server/package.json");
+    const entry = join(dirname(pkgPath), "src/index.ts");
+    return {
+      command: "bun",
+      args: ["run", entry],
+      cwd: config.cwd,
+      env: config.env,
+    };
+  },
+};
+
+const codexProvider: Provider = {
+  resolve(config) {
+    return {
+      command: "codex",
+      args: ["app-server"],
+      cwd: config.cwd,
+      env: config.env,
+    };
+  },
+};
+
+const piProvider: Provider = {
+  resolve(config) {
+    const pkgPath = resolvePackagePath("@flint-dev/pi-app-server/package.json");
+    const entry = join(dirname(pkgPath), "src/index.ts");
+    return {
+      command: "bun",
+      args: ["run", entry],
+      cwd: config.cwd,
+      env: config.env,
+    };
+  },
+};
+
+const builtins = new Map<string, Provider>([
+  ["claude", claudeProvider],
+  ["codex", codexProvider],
+  ["pi", piProvider],
+]);
+
+const custom = new Map<string, Provider>();
+
+export function registerProvider(name: string, provider: Provider): void {
+  custom.set(name, provider);
+}
+
+export function getProvider(name: string): Provider {
+  const provider = custom.get(name) ?? builtins.get(name);
+  if (!provider) {
+    throw new Error(`Unknown provider: "${name}". Register it with registerProvider().`);
+  }
+  return provider;
+}
+
+function resolvePackagePath(specifier: string): string {
+  const consumerRequire = createRequire(join(process.cwd(), "__placeholder__.js"));
+  try {
+    // First try consumer resolution (published package use-case).
+    return consumerRequire.resolve(specifier);
+  } catch {
+    // Fall back to SDK-local resolution (workspace/dev use-case).
+    const sdkRequire = createRequire(import.meta.url);
+    return sdkRequire.resolve(specifier);
+  }
+}

package/src/types.ts

@@ -0,0 +1,8 @@
+export type AgentEvent =
+  | { type: "init"; sessionId: string }
+  | { type: "text"; delta: string }
+  | { type: "reasoning"; delta: string }
+  | { type: "tool_start"; id: string; name: string; input?: unknown; parentId?: string | null }
+  | { type: "tool_end"; id: string; result?: unknown; isError: boolean; parentId?: string | null }
+  | { type: "done"; usage?: { input: number; output: number } }
+  | { type: "error"; message: string };