cosmos-agent-sdk — TypeScript client

@augmentcode/cosmos-agent-sdk — the TypeScript client for the Auggie v2 SDK / RPC protocol. It spawns auggie-v2 --mode rpc as a subprocess, speaks the newline-delimited JSON protocol defined in ../../spec, and exposes a typed, ergonomic API on top of it.

Toolchain

• Bun for install / build / test.
• Biome via ultracite for lint / format.
• tsup for the build (ESM + .d.ts).

Commands

bun install       # install dependencies
bun run build     # emit dist/ (JS + .d.ts)
bun run lint      # biome ci
bun test          # run the unit suite
bun run conformance  # drive the real client against the shared golden fixtures

Quick start

import { AuggieClient } from "@augmentcode/cosmos-agent-sdk";

const client = new AuggieClient({
  // Answer reply-expecting extension-UI requests; fire-and-forget need no reply.
  extensionUIHandler(request) {
    if (request.method === "confirm") {
      return { type: "extension_ui_response", id: request.id, confirmed: true };
    }
    return; // fall back to cancelled for other reply-expecting methods
  },
});

// Stream every agent event.
client.onEvent((event) => console.log(event.type));

// Prompt and wait for the turn to finish (idle = the agent_end event).
await client.promptAndWait("List the files in this repo");

// Typed commands return their correlated response.
const state = await client.send({ type: "get_state" });

client.close();

Architecture

The client is layered so each concern is independently testable:

• Types (src/types/) — mirror the four JSON Schemas in spec/schema/ exactly: commands, responses, events, and the bidirectional extension-UI protocol. Deep external structures are modeled permissively per the spec's permissiveness policy.
• Transport (src/transport/) — the byte-level boundary. SubprocessTransport spawns the agent and moves JSONL frames over its stdio (stderr = logs, not protocol); FakeTransport replays canned wire messages in-memory for tests and conformance without spawning a binary.
• Protocol (src/protocol/) — JSONL framing and the classification of stdout lines into responses / events / extension-UI requests, tolerating unknown top-level types as warnings.
• Session & facade (src/session.ts, src/client.ts) — request/response correlation by id, event streaming, waitForIdle on agent_end, and extension-UI round-trips.

Conformance

conformance-adapter.mjs binds the real client to the shared conformance/ runner: it drives RpcSession over FakeTransport through every golden fixture, exercising the real parsing, typing, correlation, event-routing, and extension-UI code paths. bun run conformance builds the client and runs all vectors, exiting non-zero on any failure.