@agentapplicationprotocol/sdk 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,9 @@ TypeScript SDK for the [Agent Application Protocol (AAP)](https://github.com/age
 npm install @agentapplicationprotocol/sdk
 ```
 
-## [Examples](./src/examples/)
+## Examples
 
-## [CHANGELOG](./CHANGELOG.md)
+- [Web playground](https://agentapplicationprotocol.github.io/playground/)
+- [Example agents](https://github.com/agentapplicationprotocol/agents)
+
+## [CHANGELOG](./CHANGELOG.md)

package/dist/client.d.ts

@@ -15,8 +15,17 @@ export declare class Client {
     constructor({ baseUrl, apiKey }: ClientOptions);
     private url;
     private request;
+    private streamRequest;
     /** GET /meta */
     getMeta(): Promise<MetaResponse>;
+    /** GET /sessions */
+    listSessions(params?: {
+        after?: string;
+    }): Promise<SessionListResponse>;
+    /** Fetches all session IDs across all pages. */
+    listAllSessions(): Promise<string[]>;
+    /** GET /session/:id */
+    getSession(sessionId: string): Promise<SessionResponse>;
     /** PUT /session — non-streaming */
     createSession(req: CreateSessionRequest & {
         stream?: "none";
@@ -33,14 +42,6 @@ export declare class Client {
     sendTurn(sessionId: string, req: SessionTurnRequest & {
         stream: "delta" | "message";
     }): Promise<AsyncIterable<SSEEvent>>;
-    /** GET /session/:id */
-    getSession(sessionId: string): Promise<SessionResponse>;
-    /** GET /sessions */
-    listSessions(params?: {
-        limit?: number;
-        after?: string;
-    }): Promise<SessionListResponse>;
     /** DELETE /session/:id */
     deleteSession(sessionId: string): Promise<void>;
-    private streamRequest;
 }

package/dist/client.js

@@ -15,7 +15,10 @@ exports.ClientError = ClientError;
 class Client {
     constructor({ baseUrl, apiKey }) {
         this.baseUrl = baseUrl.replace(/\/$/, "");
-        this.headers = { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` };
+        this.headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        };
     }
     url(path) {
         return `${this.baseUrl}${path}`;
@@ -34,11 +37,48 @@ class Client {
             return undefined;
         return res.json();
     }
+    async streamRequest(method, path, body) {
+        const res = await fetch(this.url(path), {
+            method,
+            headers: { ...this.headers, Accept: "text/event-stream" },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok || !res.body) {
+            const text = await res.text().catch(() => res.statusText);
+            throw new ClientError(method, path, res.status, text);
+        }
+        return parseSSE(res.body);
+    }
     /** GET /meta */
     getMeta() {
         return this.request("GET", "/meta");
     }
+    /** GET /sessions */
+    listSessions(params) {
+        let path = "/sessions";
+        if (params?.after) {
+            path += "?" + new URLSearchParams({ after: params.after }).toString();
+        }
+        return this.request("GET", path);
+    }
+    /** Fetches all session IDs across all pages. */
+    async listAllSessions() {
+        const sessions = [];
+        let after;
+        do {
+            const res = await this.listSessions({ after });
+            sessions.push(...res.sessions);
+            after = res.next;
+        } while (after);
+        return sessions;
+    }
+    /** GET /session/:id */
+    getSession(sessionId) {
+        return this.request("GET", `/session/${sessionId}`);
+    }
     createSession(req) {
+        if (req.messages.at(-1)?.role !== "user")
+            throw new Error("Last message must be a user message");
         if (req.stream === "delta" || req.stream === "message") {
             return this.streamRequest("PUT", "/session", req);
         }
@@ -50,37 +90,10 @@ class Client {
         }
         return this.request("POST", `/session/${sessionId}`, req);
     }
-    /** GET /session/:id */
-    getSession(sessionId) {
-        return this.request("GET", `/session/${sessionId}`);
-    }
-    /** GET /sessions */
-    listSessions(params) {
-        let path = "/sessions";
-        if (params) {
-            const entries = Object.entries(params).filter((e) => e[1] !== undefined);
-            if (entries.length > 0) {
-                path += "?" + new URLSearchParams(entries.map(([k, v]) => [k, String(v)])).toString();
-            }
-        }
-        return this.request("GET", path);
-    }
     /** DELETE /session/:id */
     deleteSession(sessionId) {
         return this.request("DELETE", `/session/${sessionId}`);
     }
-    async streamRequest(method, path, body) {
-        const res = await fetch(this.url(path), {
-            method,
-            headers: { ...this.headers, Accept: "text/event-stream" },
-            body: JSON.stringify(body),
-        });
-        if (!res.ok || !res.body) {
-            const text = await res.text().catch(() => res.statusText);
-            throw new ClientError(method, path, res.status, text);
-        }
-        return parseSSE(res.body);
-    }
 }
 exports.Client = Client;
 async function* parseSSE(body) {

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const client_1 = require("./client");
+const BASE_URL = "https://example.com";
+const API_KEY = "test-key";
+function mockFetch(body, status = 200) {
+    return vitest_1.vi.fn().mockResolvedValue({
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: "OK",
+        json: () => Promise.resolve(body),
+        text: () => Promise.resolve(String(body)),
+        body: null,
+    });
+}
+function mockSSEFetch(events, status = 200) {
+    const chunks = events.map(({ event, ...data }) => new TextEncoder().encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+    let i = 0;
+    const body = {
+        getReader: () => ({
+            read: async () => i < chunks.length ? { done: false, value: chunks[i++] } : { done: true, value: undefined },
+            releaseLock: vitest_1.vi.fn(),
+        }),
+    };
+    return vitest_1.vi
+        .fn()
+        .mockResolvedValue({
+        ok: status >= 200 && status < 300,
+        status,
+        body,
+        text: () => Promise.resolve(""),
+    });
+}
+let client;
+(0, vitest_1.beforeEach)(() => {
+    client = new client_1.Client({ baseUrl: BASE_URL, apiKey: API_KEY });
+});
+(0, vitest_1.describe)("Client", () => {
+    (0, vitest_1.it)("strips trailing slash from baseUrl", () => {
+        const c = new client_1.Client({ baseUrl: BASE_URL + "/", apiKey: API_KEY });
+        const fetch = mockFetch({});
+        vitest_1.vi.stubGlobal("fetch", fetch);
+        c.getMeta();
+        (0, vitest_1.expect)(fetch.mock.calls[0][0]).toBe(`${BASE_URL}/meta`);
+    });
+    (0, vitest_1.it)("sends Authorization header", async () => {
+        const fetch = mockFetch({ version: 1, agents: [] });
+        vitest_1.vi.stubGlobal("fetch", fetch);
+        await client.getMeta();
+        (0, vitest_1.expect)(fetch.mock.calls[0][1].headers["Authorization"]).toBe(`Bearer ${API_KEY}`);
+    });
+    (0, vitest_1.it)("getMeta: GET /meta", async () => {
+        const meta = { version: 1, agents: [] };
+        vitest_1.vi.stubGlobal("fetch", mockFetch(meta));
+        (0, vitest_1.expect)(await client.getMeta()).toEqual(meta);
+    });
+    (0, vitest_1.it)("getSession: GET /session/:id", async () => {
+        const session = { sessionId: "s1", agent: { name: "a" } };
+        vitest_1.vi.stubGlobal("fetch", mockFetch(session));
+        (0, vitest_1.expect)(await client.getSession("s1")).toEqual(session);
+    });
+    (0, vitest_1.it)("listSessions: GET /sessions without cursor", async () => {
+        const res = { sessions: ["s1"] };
+        const fetch = mockFetch(res);
+        vitest_1.vi.stubGlobal("fetch", fetch);
+        await client.listSessions();
+        (0, vitest_1.expect)(fetch.mock.calls[0][0]).toBe(`${BASE_URL}/sessions`);
+    });
+    (0, vitest_1.it)("listSessions: appends after param", async () => {
+        const fetch = mockFetch({ sessions: [] });
+        vitest_1.vi.stubGlobal("fetch", fetch);
+        await client.listSessions({ after: "cursor1" });
+        (0, vitest_1.expect)(fetch.mock.calls[0][0]).toBe(`${BASE_URL}/sessions?after=cursor1`);
+    });
+    (0, vitest_1.it)("listAllSessions: paginates until no next", async () => {
+        const fetch = vitest_1.vi
+            .fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ sessions: ["s1"], next: "c1" }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ sessions: ["s2"] }),
+        });
+        vitest_1.vi.stubGlobal("fetch", fetch);
+        (0, vitest_1.expect)(await client.listAllSessions()).toEqual(["s1", "s2"]);
+        (0, vitest_1.expect)(fetch).toHaveBeenCalledTimes(2);
+    });
+    (0, vitest_1.it)("deleteSession: DELETE /session/:id returns void on 204", async () => {
+        vitest_1.vi.stubGlobal("fetch", vitest_1.vi.fn().mockResolvedValue({ ok: true, status: 204 }));
+        await (0, vitest_1.expect)(client.deleteSession("s1")).resolves.toBeUndefined();
+    });
+    (0, vitest_1.it)("createSession: throws if last message is not a user message", () => {
+        vitest_1.vi.stubGlobal("fetch", mockFetch({}));
+        (0, vitest_1.expect)(() => client.createSession({
+            agent: { name: "a" },
+            messages: [{ role: "assistant", content: "hi" }],
+        })).toThrow("Last message must be a user message");
+    });
+    (0, vitest_1.it)("createSession: non-streaming returns AgentResponse", async () => {
+        const res = { sessionId: "s1", stopReason: "end_turn", messages: [] };
+        vitest_1.vi.stubGlobal("fetch", mockFetch(res, 201));
+        const result = await client.createSession({
+            agent: { name: "a" },
+            messages: [{ role: "user", content: "hi" }],
+        });
+        (0, vitest_1.expect)(result).toEqual(res);
+    });
+    (0, vitest_1.it)("createSession: streaming returns SSE events", async () => {
+        const events = [
+            { event: "session_start", sessionId: "s1" },
+            { event: "turn_start" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        vitest_1.vi.stubGlobal("fetch", mockSSEFetch(events));
+        const stream = await client.createSession({
+            agent: { name: "a" },
+            messages: [{ role: "user", content: "hi" }],
+            stream: "message",
+        });
+        const received = [];
+        for await (const e of stream)
+            received.push(e);
+        (0, vitest_1.expect)(received).toEqual(events);
+    });
+    (0, vitest_1.it)("sendTurn: non-streaming returns AgentResponse", async () => {
+        const res = { stopReason: "end_turn", messages: [] };
+        vitest_1.vi.stubGlobal("fetch", mockFetch(res));
+        const result = await client.sendTurn("s1", { messages: [{ role: "user", content: "hi" }] });
+        (0, vitest_1.expect)(result).toEqual(res);
+    });
+    (0, vitest_1.it)("sendTurn: streaming returns SSE events", async () => {
+        const events = [
+            { event: "turn_start" },
+            { event: "text", text: "hello" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        vitest_1.vi.stubGlobal("fetch", mockSSEFetch(events));
+        const stream = await client.sendTurn("s1", {
+            messages: [{ role: "user", content: "hi" }],
+            stream: "message",
+        });
+        const received = [];
+        for await (const e of stream)
+            received.push(e);
+        (0, vitest_1.expect)(received).toEqual(events);
+    });
+    (0, vitest_1.it)("streamRequest: throws ClientError on non-ok response", async () => {
+        vitest_1.vi.stubGlobal("fetch", vitest_1.vi
+            .fn()
+            .mockResolvedValue({
+            ok: false,
+            status: 403,
+            body: null,
+            text: () => Promise.resolve("Forbidden"),
+        }));
+        await (0, vitest_1.expect)(client.createSession({
+            agent: { name: "a" },
+            messages: [{ role: "user", content: "hi" }],
+            stream: "delta",
+        })).rejects.toThrow(client_1.ClientError);
+    });
+    (0, vitest_1.it)("throws ClientError on non-ok response", async () => {
+        vitest_1.vi.stubGlobal("fetch", vitest_1.vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 401, text: () => Promise.resolve("Unauthorized") }));
+        await (0, vitest_1.expect)(client.getMeta()).rejects.toThrow(client_1.ClientError);
+    });
+    (0, vitest_1.it)("ClientError has correct properties", async () => {
+        vitest_1.vi.stubGlobal("fetch", vitest_1.vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 404, text: () => Promise.resolve("Not Found") }));
+        const err = await client.getSession("x").catch((e) => e);
+        (0, vitest_1.expect)(err).toBeInstanceOf(client_1.ClientError);
+        (0, vitest_1.expect)(err.status).toBe(404);
+        (0, vitest_1.expect)(err.method).toBe("GET");
+        (0, vitest_1.expect)(err.path).toBe("/session/x");
+    });
+});

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { Client, ClientError } from "./client";
 export type { ClientOptions } from "./client";
-export { Server, writeSSEEvents } from "./server";
+export { Server } from "./server";
 export type { ServerHandler, ServerOptions } from "./server";
-export type { Message, ToolPermissionMessage, ContentBlock, ToolSpec, ServerToolRef, AgentOption, StreamMode, StopReason, JSONSchema, AgentConfig, CreateSessionRequest, SessionTurnRequest, AgentResponse, SessionResponse, SessionListResponse, MetaResponse, AgentInfo, SSEEvent, } from "./types";
+export { sseEventsToMessages, resolvePendingToolUse } from "./utils";
+export type * from "./types";

package/dist/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeSSEEvents = exports.Server = exports.ClientError = exports.Client = void 0;
+exports.resolvePendingToolUse = exports.sseEventsToMessages = exports.Server = exports.ClientError = exports.Client = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
 Object.defineProperty(exports, "ClientError", { enumerable: true, get: function () { return client_1.ClientError; } });
 var server_1 = require("./server");
 Object.defineProperty(exports, "Server", { enumerable: true, get: function () { return server_1.Server; } });
-Object.defineProperty(exports, "writeSSEEvents", { enumerable: true, get: function () { return server_1.writeSSEEvents; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "sseEventsToMessages", { enumerable: true, get: function () { return utils_1.sseEventsToMessages; } });
+Object.defineProperty(exports, "resolvePendingToolUse", { enumerable: true, get: function () { return utils_1.resolvePendingToolUse; } });

package/dist/server.d.ts

@@ -1,21 +1,26 @@
 import { Hono } from "hono";
-import type { SSEStreamingApi } from "hono/streaming";
+import type { Context } from "hono";
 import { AgentResponse, CreateSessionRequest, MetaResponse, SessionListResponse, SessionResponse, SessionTurnRequest, SSEEvent } from "./types";
 export interface ServerHandler {
     getMeta(): Promise<MetaResponse>;
-    createSession(req: CreateSessionRequest): Promise<AgentResponse | AsyncIterable<SSEEvent>> | AsyncIterable<SSEEvent>;
-    sendTurn(sessionId: string, req: SessionTurnRequest): Promise<AgentResponse | AsyncIterable<SSEEvent>> | AsyncIterable<SSEEvent>;
-    getSession(sessionId: string): Promise<SessionResponse>;
     listSessions(params: {
         after?: string;
     }): Promise<SessionListResponse>;
+    getSession(sessionId: string): Promise<SessionResponse>;
+    /** The last message in `req.messages` is guaranteed to be a user message. */
+    createSession(req: CreateSessionRequest): Promise<AgentResponse | AsyncIterable<SSEEvent>>;
+    sendTurn(sessionId: string, req: SessionTurnRequest): Promise<AgentResponse | AsyncIterable<SSEEvent>>;
     deleteSession(sessionId: string): Promise<void>;
 }
-export type { SSEStreamingApi };
-export declare function writeSSEEvents(stream: SSEStreamingApi, events: AsyncIterable<SSEEvent>): Promise<void>;
 export interface ServerOptions {
-    /** Called on every request (except GET /meta) to authenticate. Return false to reject. */
-    authenticate?: (apiKey: string) => boolean | Promise<boolean>;
+    /**
+     * Called on every request to authenticate. Return false to reject.
+     * Use `c.req.path` to allow unauthenticated access to specific routes.
+     * @example
+     * // Allow unauthenticated access to GET /meta
+     * authenticate: (apiKey, c) => c.req.path === "/meta" || apiKey === "secret"
+     */
+    authenticate?: (apiKey: string, c: Context) => boolean | Promise<boolean>;
     /** CORS origin(s) to allow. Disabled by default. */
     cors?: string | string[];
     /** Base path to mount all routes under, e.g. "/api/v1". */
@@ -24,6 +29,4 @@ export interface ServerOptions {
 export declare class Server {
     readonly app: Hono;
     constructor(handler: ServerHandler, options?: ServerOptions);
-    /** Returns the Hono fetch handler, ready to pass to any runtime (Node, Bun, Deno, etc.) */
-    fetch: (req: Request) => Response | Promise<Response>;
 }

package/dist/server.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Server = void 0;
-exports.writeSSEEvents = writeSSEEvents;
 const hono_1 = require("hono");
 const cors_1 = require("hono/cors");
 const streaming_1 = require("hono/streaming");
+// --- SSE helper ---
 async function writeSSEEvents(stream, events) {
     for await (const { event, ...data } of events) {
         await stream.writeSSE({ event, data: JSON.stringify(data) });
@@ -12,37 +12,34 @@ async function writeSSEEvents(stream, events) {
 }
 class Server {
     constructor(handler, options = {}) {
-        /** Returns the Hono fetch handler, ready to pass to any runtime (Node, Bun, Deno, etc.) */
-        this.fetch = (req) => this.app.fetch(req);
         this.app = new hono_1.Hono();
         const { authenticate } = options;
         const router = options.base ? this.app.basePath(options.base) : this.app;
         if (options.cors !== undefined) {
             router.use("*", (0, cors_1.cors)({ origin: options.cors }));
         }
-        const auth = async (apiKey) => {
-            if (!authenticate)
-                return true;
-            return authenticate(apiKey);
-        };
         const getApiKey = (authHeader) => authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
-        // GET /meta — auth optional
-        router.get("/meta", async (c) => {
-            const meta = await handler.getMeta();
-            return c.json(meta);
-        });
-        // Auth middleware for all other routes
+        // Auth middleware for all routes
         router.use("*", async (c, next) => {
+            if (!authenticate)
+                return next();
             const apiKey = getApiKey(c.req.header("Authorization"));
-            if (!(await auth(apiKey)))
+            if (!(await authenticate(apiKey, c)))
                 return c.json({ error: "Unauthorized" }, 401);
             return next();
         });
+        // GET /meta
+        router.get("/meta", async (c) => {
+            const meta = await handler.getMeta();
+            return c.json(meta);
+        });
         // PUT /session
         router.put("/session", async (c) => {
             const req = await c.req.json();
+            if (req.messages.at(-1)?.role !== "user")
+                return c.json({ error: "Last message must be a user message" }, 400);
             const result = await handler.createSession(req);
-            if (isAsyncIterable(result)) {
+            if (req.stream === "delta" || req.stream === "message") {
                 return (0, streaming_1.streamSSE)(c, (stream) => writeSSEEvents(stream, result));
             }
             return c.json(result, 201);
@@ -51,7 +48,7 @@ class Server {
         router.post("/session/:id", async (c) => {
             const req = await c.req.json();
             const result = await handler.sendTurn(c.req.param("id"), req);
-            if (isAsyncIterable(result)) {
+            if (req.stream === "delta" || req.stream === "message") {
                 return (0, streaming_1.streamSSE)(c, (stream) => writeSSEEvents(stream, result));
             }
             return c.json(result);
@@ -75,6 +72,3 @@ class Server {
     }
 }
 exports.Server = Server;
-function isAsyncIterable(value) {
-    return value != null && typeof value[Symbol.asyncIterator] === "function";
-}

package/dist/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.test.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const server_1 = require("./server");
+const meta = { version: 1, agents: [] };
+const session = { sessionId: "s1", agent: { name: "a" } };
+const agentResponse = { stopReason: "end_turn", messages: [] };
+const sessionList = { sessions: ["s1"] };
+async function* sseEvents() {
+    yield { event: "turn_start" };
+    yield { event: "text", text: "hi" };
+    yield { event: "turn_stop", stopReason: "end_turn" };
+}
+function makeHandler(overrides = {}) {
+    return {
+        getMeta: vitest_1.vi.fn().mockResolvedValue(meta),
+        listSessions: vitest_1.vi.fn().mockResolvedValue(sessionList),
+        getSession: vitest_1.vi.fn().mockResolvedValue(session),
+        createSession: vitest_1.vi.fn().mockResolvedValue(agentResponse),
+        sendTurn: vitest_1.vi.fn().mockResolvedValue(agentResponse),
+        deleteSession: vitest_1.vi.fn().mockResolvedValue(undefined),
+        ...overrides,
+    };
+}
+function req(method, path, body, headers) {
+    return new Request(`http://localhost${path}`, {
+        method,
+        headers: { "Content-Type": "application/json", ...headers },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+}
+(0, vitest_1.describe)("Server", () => {
+    (0, vitest_1.it)("GET /meta returns meta", async () => {
+        const server = new server_1.Server(makeHandler());
+        const res = await server.app.fetch(req("GET", "/meta"));
+        (0, vitest_1.expect)(res.status).toBe(200);
+        (0, vitest_1.expect)(await res.json()).toEqual(meta);
+    });
+    (0, vitest_1.it)("GET /session/:id returns session", async () => {
+        const server = new server_1.Server(makeHandler());
+        const res = await server.app.fetch(req("GET", "/session/s1"));
+        (0, vitest_1.expect)(res.status).toBe(200);
+        (0, vitest_1.expect)(await res.json()).toEqual(session);
+    });
+    (0, vitest_1.it)("GET /sessions returns session list", async () => {
+        const handler = makeHandler();
+        const server = new server_1.Server(handler);
+        const res = await server.app.fetch(req("GET", "/sessions?after=cursor1"));
+        (0, vitest_1.expect)(res.status).toBe(200);
+        (0, vitest_1.expect)(await res.json()).toEqual(sessionList);
+        (0, vitest_1.expect)(handler.listSessions).toHaveBeenCalledWith({ after: "cursor1" });
+    });
+    (0, vitest_1.it)("PUT /session returns 400 if last message is not a user message", async () => {
+        const server = new server_1.Server(makeHandler());
+        const res = await server.app.fetch(req("PUT", "/session", {
+            agent: { name: "a" },
+            messages: [{ role: "assistant", content: "hi" }],
+        }));
+        (0, vitest_1.expect)(res.status).toBe(400);
+    });
+    (0, vitest_1.it)("PUT /session returns 201 with AgentResponse", async () => {
+        const server = new server_1.Server(makeHandler());
+        const res = await server.app.fetch(req("PUT", "/session", { agent: { name: "a" }, messages: [{ role: "user", content: "hi" }] }));
+        (0, vitest_1.expect)(res.status).toBe(201);
+        (0, vitest_1.expect)(await res.json()).toEqual(agentResponse);
+    });
+    (0, vitest_1.it)("PUT /session with stream returns SSE", async () => {
+        const server = new server_1.Server(makeHandler({ createSession: vitest_1.vi.fn().mockResolvedValue(sseEvents()) }));
+        const res = await server.app.fetch(req("PUT", "/session", {
+            agent: { name: "a" },
+            messages: [{ role: "user", content: "hi" }],
+            stream: "message",
+        }));
+        (0, vitest_1.expect)(res.status).toBe(200);
+        (0, vitest_1.expect)(res.headers.get("content-type")).toContain("text/event-stream");
+    });
+    (0, vitest_1.it)("POST /session/:id returns AgentResponse", async () => {
+        const server = new server_1.Server(makeHandler());
+        const res = await server.app.fetch(req("POST", "/session/s1", { messages: [{ role: "user", content: "hi" }] }));
+        (0, vitest_1.expect)(res.status).toBe(200);
+        (0, vitest_1.expect)(await res.json()).toEqual(agentResponse);
+    });
+    (0, vitest_1.it)("POST /session/:id with stream returns SSE", async () => {
+        const server = new server_1.Server(makeHandler({ sendTurn: vitest_1.vi.fn().mockResolvedValue(sseEvents()) }));
+        const res = await server.app.fetch(req("POST", "/session/s1", { messages: [{ role: "user", content: "hi" }], stream: "delta" }));
+        (0, vitest_1.expect)(res.status).toBe(200);
+        (0, vitest_1.expect)(res.headers.get("content-type")).toContain("text/event-stream");
+    });
+    (0, vitest_1.it)("DELETE /session/:id returns 204", async () => {
+        const server = new server_1.Server(makeHandler());
+        const res = await server.app.fetch(req("DELETE", "/session/s1"));
+        (0, vitest_1.expect)(res.status).toBe(204);
+    });
+    (0, vitest_1.it)("authenticate: returns 401 when rejected", async () => {
+        const server = new server_1.Server(makeHandler(), { authenticate: () => false });
+        const res = await server.app.fetch(req("GET", "/meta"));
+        (0, vitest_1.expect)(res.status).toBe(401);
+    });
+    (0, vitest_1.it)("authenticate: passes apiKey and context", async () => {
+        const authenticate = vitest_1.vi.fn().mockReturnValue(true);
+        const server = new server_1.Server(makeHandler(), { authenticate });
+        await server.app.fetch(req("GET", "/meta", undefined, { Authorization: "Bearer mykey" }));
+        (0, vitest_1.expect)(authenticate).toHaveBeenCalledWith("mykey", vitest_1.expect.objectContaining({ req: vitest_1.expect.anything() }));
+    });
+    (0, vitest_1.it)("authenticate: allows per-route logic", async () => {
+        const server = new server_1.Server(makeHandler(), {
+            authenticate: (_, c) => c.req.path === "/meta",
+        });
+        const metaRes = await server.app.fetch(req("GET", "/meta"));
+        (0, vitest_1.expect)(metaRes.status).toBe(200);
+        const sessRes = await server.app.fetch(req("GET", "/session/s1"));
+        (0, vitest_1.expect)(sessRes.status).toBe(401);
+    });
+    (0, vitest_1.it)("base path prefixes all routes", async () => {
+        const server = new server_1.Server(makeHandler(), { base: "/api/v1" });
+        const res = await server.app.fetch(req("GET", "/api/v1/meta"));
+        (0, vitest_1.expect)(res.status).toBe(200);
+    });
+    (0, vitest_1.it)("cors: sets Access-Control-Allow-Origin header", async () => {
+        const server = new server_1.Server(makeHandler(), { cors: "https://example.com" });
+        const res = await server.app.fetch(req("GET", "/meta", undefined, { Origin: "https://example.com" }));
+        (0, vitest_1.expect)(res.headers.get("access-control-allow-origin")).toBe("https://example.com");
+    });
+});

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { JSONSchema7 } from "json-schema";
 export type JSONSchema = JSONSchema7;
+/** A single block of content within a message. */
 export type ContentBlock = {
     type: "text";
     text: string;
@@ -13,122 +14,195 @@ export type ContentBlock = {
     input: Record<string, unknown>;
 } | {
     type: "image";
-    mimeType: string;
-    data: string;
+    /** Supports `https://` URLs and `data:` URIs (base64). */
+    url: string;
 };
-export type Message = {
+/** A system-role message providing instructions to the agent. */
+export interface SystemMessage {
     role: "system";
     content: string;
-} | {
+}
+/** A user-role message. */
+export interface UserMessage {
     role: "user";
     content: string | ContentBlock[];
-} | {
+}
+/** An assistant-role message. */
+export interface AssistantMessage {
     role: "assistant";
     content: string | ContentBlock[];
-} | {
+}
+/** A tool result message returned by the application after a `tool_use` block. */
+export interface ToolMessage {
     role: "tool";
     toolCallId: string;
     content: string | ContentBlock[];
-};
-export type ToolPermissionMessage = {
+}
+/** A message that can appear in conversation history. */
+export type HistoryMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+/** Grants or denies permission for the server to invoke a tool on the client's behalf. */
+export interface ToolPermissionMessage {
     role: "tool_permission";
     toolCallId: string;
+    /** Whether the client grants permission for the tool call. */
     granted: boolean;
+    /** Optional explanation, especially useful when `granted` is `false`. */
     reason?: string;
-};
+}
+/** Declares a tool (application-side in requests; server-side in `/meta`). */
 export interface ToolSpec {
     name: string;
     title?: string;
     description: string;
     inputSchema: JSONSchema;
 }
+/** References a server-side tool to enable for a session. */
 export interface ServerToolRef {
+    /** Server tool name as declared in `/meta`. */
     name: string;
-    trust: boolean;
+    /** If `true`, the server may invoke this tool without requesting client permission. Defaults to `false`. */
+    trust?: boolean;
 }
+/** A configurable option the client may set per request. */
 export type AgentOption = {
+    type: "text";
     name: string;
     title?: string;
     description?: string;
-    type: "text";
     default: string;
 } | {
+    type: "secret";
     name: string;
     title?: string;
     description?: string;
-    type: "secret";
     default: string;
 } | {
+    type: "select";
     name: string;
     title?: string;
     description?: string;
-    type: "select";
     options: string[];
     default: string;
 };
+/** Describes an agent available on the server, as returned by `GET /meta`. */
 export interface AgentInfo {
+    /** Unique identifier for the agent on this server. */
     name: string;
+    /** Human-readable display name. */
     title?: string;
+    /** Semantic version of the agent. */
     version: string;
     description?: string;
+    /** Server-side tools the agent exposes to the client for configuration. */
     tools?: ToolSpec[];
+    /** Configurable options the client may set per request. */
     options?: AgentOption[];
+    /** Declares what the agent supports. Missing fields should be treated as unsupported. */
     capabilities?: {
+        /** Declares what history the agent can return in `GET /session/:id`. */
         history?: {
+            /** Server can return compacted history. */
             compacted?: Record<string, never>;
+            /** Server can return full uncompacted history. */
             full?: Record<string, never>;
         };
+        /** Declares which stream modes the agent supports. */
         stream?: {
+            /** Agent supports `"delta"` streaming. */
             delta?: Record<string, never>;
+            /** Agent supports `"message"` streaming. */
             message?: Record<string, never>;
+            /** Agent supports non-streaming (`"none"`) responses. */
             none?: Record<string, never>;
         };
+        /** Declares what application-provided inputs the agent supports. */
         application?: {
+            /** Agent accepts application-side tools in requests. */
             tools?: Record<string, never>;
         };
+        /** Declares what image input the agent supports. */
+        image?: {
+            /** Agent accepts `https://` image URLs. */
+            http?: Record<string, never>;
+            /** Agent accepts `data:` URI (base64) images. */
+            data?: Record<string, never>;
+        };
     };
 }
+/** Response body for `GET /meta`. */
 export interface MetaResponse {
+    /** AAP protocol version. */
     version: number;
     agents: AgentInfo[];
 }
 export type StreamMode = "delta" | "message" | "none";
 export type StopReason = "end_turn" | "tool_use" | "max_tokens" | "refusal" | "error";
+/** Agent configuration supplied with a request. */
 export interface AgentConfig {
+    /** Agent name to invoke. */
     name: string;
+    /** Server-side tools to enable. If omitted, all exposed agent tools are disabled. */
     tools?: ServerToolRef[];
+    /** Key-value pairs matching the agent's declared options. */
     options?: Record<string, string>;
 }
+/** Request body for `PUT /session`. */
 export interface CreateSessionRequest {
+    /** Agent configuration. `name` is required at session creation. */
     agent: AgentConfig;
+    /** Response mode. Defaults to `"none"`. */
     stream?: StreamMode;
-    messages: Message[];
+    /** Seed history. The last message must be a `user` message. */
+    messages: HistoryMessage[];
+    /** Application-side tools with full schema. */
     tools?: ToolSpec[];
 }
+/** Request body for `POST /session/:id`. */
 export interface SessionTurnRequest {
+    /** Session-level agent overrides. Agent name cannot be changed. */
+    agent?: Omit<AgentConfig, "name">;
+    /** Response mode. Defaults to `"none"`. */
     stream?: StreamMode;
-    messages: (Message | ToolPermissionMessage)[];
+    /** A single user message, or a mixed list of tool results and tool permissions. */
+    messages: (UserMessage | ToolMessage | ToolPermissionMessage)[];
+    /** Application-side tools. Overrides tools declared at session creation. */
     tools?: ToolSpec[];
-    agent?: Omit<AgentConfig, "name">;
 }
+/** JSON response body for non-streaming (`stream: "none"`) requests. */
 export interface AgentResponse {
+    /** Present in `PUT /session` response only. */
     sessionId?: string;
     stopReason: StopReason;
-    messages: Message[];
+    messages: HistoryMessage[];
 }
+/** Response body for `GET /session/:id`. */
 export interface SessionResponse {
     sessionId: string;
+    /** Secret option values in `agent.options` are redacted (e.g. `"***"`). */
     agent: AgentConfig;
-    tools: ToolSpec[];
+    /** Application-side tools declared for this session. */
+    tools?: ToolSpec[];
     history?: {
-        compacted?: Message[];
-        full?: Message[];
+        /** Omitted if the server chooses not to expose. */
+        compacted?: HistoryMessage[];
+        /** Omitted if the server chooses not to expose. */
+        full?: HistoryMessage[];
     };
 }
+/** Response body for `GET /sessions`. */
 export interface SessionListResponse {
+    /** Array of session IDs. */
     sessions: string[];
-    nextCursor?: string;
+    /** Pagination cursor; absent when there are no more results. Pass as `after` to get the next page. */
+    next?: string;
+}
+/** A tool call emitted by the agent during a streaming turn. */
+export interface ToolCallEvent {
+    toolCallId: string;
+    name: string;
+    input: Record<string, unknown>;
 }
+/** SSE event data for `stream: "delta"` and `stream: "message"` responses. */
 export type SSEEvent = {
     event: "session_start";
     sessionId: string;
@@ -146,12 +220,9 @@ export type SSEEvent = {
 } | {
     event: "thinking";
     thinking: string;
-} | {
+} | ({
     event: "tool_call";
-    toolCallId: string;
-    name: string;
-    input: Record<string, unknown>;
-} | {
+} & ToolCallEvent) | {
     event: "tool_result";
     toolCallId: string;
     content: string | ContentBlock[];

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { HistoryMessage, SSEEvent, ToolCallEvent, ToolSpec } from "./types";
+/**
+ * Converts a list of SSE events into `HistoryMessage[]`.
+ * Handles delta accumulation, tool call/result pairing, and assistant message finalization.
+ */
+export declare function sseEventsToMessages(events: SSEEvent[]): HistoryMessage[];
+/**
+ * Inspects the last assistant message in `messages` and classifies its unresolved `tool_use` blocks
+ * into client-side tools (matched against `clientTools`) and server-side tools (requiring permission).
+ */
+export declare function resolvePendingToolUse(messages: HistoryMessage[], clientTools?: ToolSpec[]): {
+    client: ToolCallEvent[];
+    server: ToolCallEvent[];
+};

package/dist/utils.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sseEventsToMessages = sseEventsToMessages;
+exports.resolvePendingToolUse = resolvePendingToolUse;
+/**
+ * Converts a list of SSE events into `HistoryMessage[]`.
+ * Handles delta accumulation, tool call/result pairing, and assistant message finalization.
+ */
+function sseEventsToMessages(events) {
+    const history = [];
+    const blocks = [];
+    let textAcc = "";
+    let thinkingAcc = "";
+    for (const event of events) {
+        // flush delta accumulators when a non-delta event arrives
+        if (event.event !== "text_delta" && event.event !== "thinking_delta") {
+            if (textAcc) {
+                blocks.push({ type: "text", text: textAcc });
+                textAcc = "";
+            }
+            if (thinkingAcc) {
+                blocks.push({ type: "thinking", thinking: thinkingAcc });
+                thinkingAcc = "";
+            }
+        }
+        switch (event.event) {
+            case "text_delta":
+                textAcc += event.delta;
+                break;
+            case "thinking_delta":
+                thinkingAcc += event.delta;
+                break;
+            case "text":
+                blocks.push({ type: "text", text: event.text });
+                break;
+            case "thinking":
+                blocks.push({ type: "thinking", thinking: event.thinking });
+                break;
+            case "tool_call":
+                // accumulate tool_use blocks into the current assistant message
+                blocks.push({
+                    type: "tool_use",
+                    toolCallId: event.toolCallId,
+                    name: event.name,
+                    input: event.input,
+                });
+                break;
+            case "tool_result":
+                // flush accumulated assistant blocks before appending the tool result
+                if (blocks.length > 0) {
+                    history.push({ role: "assistant", content: [...blocks] });
+                    blocks.length = 0;
+                }
+                history.push({ role: "tool", toolCallId: event.toolCallId, content: event.content });
+                break;
+            case "turn_stop":
+                // finalize the assistant message
+                if (blocks.length > 0)
+                    history.push({ role: "assistant", content: blocks });
+                break;
+        }
+    }
+    return history;
+}
+/**
+ * Inspects the last assistant message in `messages` and classifies its unresolved `tool_use` blocks
+ * into client-side tools (matched against `clientTools`) and server-side tools (requiring permission).
+ */
+function resolvePendingToolUse(messages, clientTools) {
+    const last = [...messages].reverse().find((m) => m.role === "assistant");
+    if (!last || !Array.isArray(last.content))
+        return { client: [], server: [] };
+    const resolved = new Set(messages.filter((m) => m.role === "tool").map((m) => m.toolCallId));
+    const clientNames = new Set(clientTools?.map((t) => t.name) ?? []);
+    const client = [];
+    const server = [];
+    for (const block of last.content) {
+        if (block.type !== "tool_use" || resolved.has(block.toolCallId))
+            continue;
+        const { toolCallId, name, input } = block;
+        (clientNames.has(name) ? client : server).push({ toolCallId, name, input });
+    }
+    return { client, server };
+}

package/dist/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils.test.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const utils_1 = require("./utils");
+(0, vitest_1.describe)("sseEventsToMessages", () => {
+    (0, vitest_1.it)("converts text event to assistant message", () => {
+        const events = [
+            { event: "turn_start" },
+            { event: "text", text: "hello" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        (0, vitest_1.expect)((0, utils_1.sseEventsToMessages)(events)).toEqual([
+            { role: "assistant", content: [{ type: "text", text: "hello" }] },
+        ]);
+    });
+    (0, vitest_1.it)("accumulates text_delta into text block", () => {
+        const events = [
+            { event: "text_delta", delta: "hel" },
+            { event: "text_delta", delta: "lo" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        (0, vitest_1.expect)((0, utils_1.sseEventsToMessages)(events)).toEqual([
+            { role: "assistant", content: [{ type: "text", text: "hello" }] },
+        ]);
+    });
+    (0, vitest_1.it)("accumulates thinking_delta into thinking block", () => {
+        const events = [
+            { event: "thinking_delta", delta: "thin" },
+            { event: "thinking_delta", delta: "king" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        (0, vitest_1.expect)((0, utils_1.sseEventsToMessages)(events)).toEqual([
+            { role: "assistant", content: [{ type: "thinking", thinking: "thinking" }] },
+        ]);
+    });
+    (0, vitest_1.it)("converts thinking event to thinking block", () => {
+        const events = [
+            { event: "thinking", thinking: "deep thought" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        (0, vitest_1.expect)((0, utils_1.sseEventsToMessages)(events)).toEqual([
+            { role: "assistant", content: [{ type: "thinking", thinking: "deep thought" }] },
+        ]);
+    });
+    (0, vitest_1.it)("flushes assistant message before tool_result", () => {
+        const events = [
+            { event: "tool_call", toolCallId: "c1", name: "search", input: { q: "x" } },
+            { event: "tool_result", toolCallId: "c1", content: "result" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        const messages = (0, utils_1.sseEventsToMessages)(events);
+        (0, vitest_1.expect)(messages).toContainEqual({
+            role: "assistant",
+            content: [{ type: "tool_use", toolCallId: "c1", name: "search", input: { q: "x" } }],
+        });
+        (0, vitest_1.expect)(messages).toContainEqual({ role: "tool", toolCallId: "c1", content: "result" });
+    });
+    (0, vitest_1.it)("flushes delta accumulators when non-delta event arrives", () => {
+        const events = [
+            { event: "text_delta", delta: "hi" },
+            { event: "tool_call", toolCallId: "c1", name: "fn", input: {} },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        const messages = (0, utils_1.sseEventsToMessages)(events);
+        const assistant = messages.find((m) => m.role === "assistant");
+        (0, vitest_1.expect)(Array.isArray(assistant?.content) && assistant.content[0]).toEqual({
+            type: "text",
+            text: "hi",
+        });
+    });
+    (0, vitest_1.it)("returns empty array for events with no content", () => {
+        const events = [
+            { event: "turn_start" },
+            { event: "turn_stop", stopReason: "end_turn" },
+        ];
+        (0, vitest_1.expect)((0, utils_1.sseEventsToMessages)(events)).toEqual([]);
+    });
+});
+(0, vitest_1.describe)("resolvePendingToolUse", () => {
+    const clientTool = {
+        name: "client_tool",
+        description: "d",
+        inputSchema: { type: "object" },
+    };
+    (0, vitest_1.it)("classifies client and server tools", () => {
+        const messages = [
+            {
+                role: "assistant",
+                content: [
+                    { type: "tool_use", toolCallId: "c1", name: "client_tool", input: {} },
+                    { type: "tool_use", toolCallId: "s1", name: "server_tool", input: {} },
+                ],
+            },
+        ];
+        const { client, server } = (0, utils_1.resolvePendingToolUse)(messages, [clientTool]);
+        (0, vitest_1.expect)(client).toEqual([{ toolCallId: "c1", name: "client_tool", input: {} }]);
+        (0, vitest_1.expect)(server).toEqual([{ toolCallId: "s1", name: "server_tool", input: {} }]);
+    });
+    (0, vitest_1.it)("skips tool_use blocks already resolved by tool_result", () => {
+        const messages = [
+            {
+                role: "assistant",
+                content: [{ type: "tool_use", toolCallId: "c1", name: "client_tool", input: {} }],
+            },
+            { role: "tool", toolCallId: "c1", content: "done" },
+        ];
+        (0, vitest_1.expect)((0, utils_1.resolvePendingToolUse)(messages, [clientTool])).toEqual({ client: [], server: [] });
+    });
+    (0, vitest_1.it)("returns empty if last assistant message has string content", () => {
+        const messages = [{ role: "assistant", content: "plain" }];
+        (0, vitest_1.expect)((0, utils_1.resolvePendingToolUse)(messages)).toEqual({ client: [], server: [] });
+    });
+    (0, vitest_1.it)("returns empty if no assistant message in history", () => {
+        const messages = [{ role: "user", content: "hi" }];
+        (0, vitest_1.expect)((0, utils_1.resolvePendingToolUse)(messages)).toEqual({ client: [], server: [] });
+    });
+    (0, vitest_1.it)("finds last assistant message even if not the last message", () => {
+        const messages = [
+            {
+                role: "assistant",
+                content: [{ type: "tool_use", toolCallId: "c1", name: "client_tool", input: {} }],
+            },
+            { role: "tool", toolCallId: "c1", content: "done" },
+            { role: "user", content: "thanks" },
+        ];
+        // last message is user, but last assistant has resolved tool — should return empty
+        (0, vitest_1.expect)((0, utils_1.resolvePendingToolUse)(messages, [clientTool])).toEqual({ client: [], server: [] });
+    });
+});

package/package.json

@@ -1,36 +1,35 @@
 {
   "name": "@agentapplicationprotocol/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for the Agent Application Protocol (AAP)",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
   "files": [
     "dist"
   ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch",
-    "example:basic:server": "tsx src/examples/01-basic/server.ts",
-    "example:basic:client": "tsx src/examples/01-basic/client.ts",
-    "example:streaming:server": "tsx src/examples/02-streaming/server.ts",
-    "example:streaming:client": "tsx src/examples/02-streaming/client.ts",
-    "example:client-tool:server": "tsx src/examples/03-client-tool/server.ts",
-    "example:client-tool:client": "tsx src/examples/03-client-tool/client.ts",
-    "example:server-tool-permission:server": "tsx src/examples/04-server-tool-permission/server.ts",
-    "example:server-tool-permission:client": "tsx src/examples/04-server-tool-permission/client.ts",
-    "example:server-tool-inline:server": "tsx src/examples/05-server-tool-inline/server.ts",
-    "example:server-tool-inline:client": "tsx src/examples/05-server-tool-inline/client.ts"
+    "test": "vitest run --exclude 'dist/**'",
+    "prepare": "husky",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "eventsource-parser": "^3.0.6",
+    "hono": "^4.12.8"
   },
-  "license": "Apache-2.0",
   "devDependencies": {
-    "@hono/node-server": "^1.19.11",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "oxfmt": "^0.42.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
   },
-  "dependencies": {
-    "eventsource-parser": "^3.0.6",
-    "hono": "^4.12.8"
+  "lint-staged": {
+    "*.{ts,json,md}": "oxfmt"
   }
 }