@agentapplicationprotocol/server 0.4.1 → 0.5.0

package/README.md

@@ -0,0 +1,34 @@
+# @agentapplicationprotocol/server
+
+[![npm version](https://img.shields.io/npm/v/@agentapplicationprotocol/server)](https://www.npmjs.com/package/@agentapplicationprotocol/server)
+
+AAP server for the [Agent Application Protocol (AAP)](https://github.com/agentapplicationprotocol/agent-application-protocol).
+
+## Installation
+
+```bash
+npm install @agentapplicationprotocol/server
+```
+
+## Usage
+
+```ts
+import { Hono } from "hono";
+import { aap, Agent, Session } from "@agentapplicationprotocol/server";
+
+const agent = new Agent("my-agent", { version: "1.0.0" });
+
+const app = new Hono();
+app.route(
+  "/",
+  aap({
+    getMeta: () => ({ version: 1, agents: [agent.info] }),
+    // ... implement Handler interface
+  }),
+);
+```
+
+## Examples
+
+- [Basic agent](./src/examples/basic)
+- [Compact history agent](./src/examples/compact-history)

package/dist/src/agent.test.d.ts

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

package/dist/src/agent.test.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const agent_1 = require("./agent");
+const zod_1 = __importDefault(require("zod"));
+(0, vitest_1.describe)("Agent", () => {
+    (0, vitest_1.it)("initializes with name and defaults", () => {
+        const agent = new agent_1.Agent("my-agent");
+        (0, vitest_1.expect)(agent.info.name).toBe("my-agent");
+        (0, vitest_1.expect)(agent.info.version).toBe("1.0.0");
+        (0, vitest_1.expect)(agent.info.tools).toEqual([]);
+        (0, vitest_1.expect)(agent.tools.size).toBe(0);
+    });
+    (0, vitest_1.it)("accepts title, description, version options", () => {
+        const agent = new agent_1.Agent("a", { title: "T", description: "D", version: "2.0.0" });
+        (0, vitest_1.expect)(agent.info.title).toBe("T");
+        (0, vitest_1.expect)(agent.info.description).toBe("D");
+        (0, vitest_1.expect)(agent.info.version).toBe("2.0.0");
+    });
+    (0, vitest_1.it)("option() adds an option and returns this", () => {
+        const agent = new agent_1.Agent("a");
+        const result = agent.option({ type: "text", name: "model", default: "gpt-4" });
+        (0, vitest_1.expect)(result).toBe(agent);
+        (0, vitest_1.expect)(agent.info.options).toHaveLength(1);
+        (0, vitest_1.expect)(agent.info.options[0].name).toBe("model");
+    });
+    (0, vitest_1.it)("image() sets image capability and returns this", () => {
+        const agent = new agent_1.Agent("a");
+        const result = agent.image({ http: {} });
+        (0, vitest_1.expect)(result).toBe(agent);
+        (0, vitest_1.expect)(agent.info.capabilities?.image).toEqual({ http: {} });
+    });
+    (0, vitest_1.it)("history() sets history capability and returns this", () => {
+        const agent = new agent_1.Agent("a");
+        const result = agent.history({});
+        (0, vitest_1.expect)(result).toBe(agent);
+        (0, vitest_1.expect)(agent.info.capabilities?.history).toEqual({});
+    });
+    (0, vitest_1.it)("tool() registers tool spec and executor", async () => {
+        const agent = new agent_1.Agent("a");
+        agent.tool("add", {
+            description: "adds two numbers",
+            inputSchema: zod_1.default.object({ a: zod_1.default.number(), b: zod_1.default.number() }),
+            outputSchema: zod_1.default.number(),
+        }, async ({ a, b }) => a + b);
+        (0, vitest_1.expect)(agent.info.tools).toHaveLength(1);
+        (0, vitest_1.expect)(agent.info.tools[0].name).toBe("add");
+        (0, vitest_1.expect)(agent.tools.has("add")).toBe(true);
+        const result = await agent.tools.get("add")(JSON.stringify({ a: 2, b: 3 }));
+        (0, vitest_1.expect)(JSON.parse(result)).toBe(5);
+    });
+    (0, vitest_1.it)("tool() validates output with outputSchema", async () => {
+        const agent = new agent_1.Agent("a");
+        agent.tool("greet", { inputSchema: zod_1.default.object({ name: zod_1.default.string() }), outputSchema: zod_1.default.string() }, async ({ name }) => `hello ${name}`);
+        const result = await agent.tools.get("greet")(JSON.stringify({ name: "world" }));
+        (0, vitest_1.expect)(JSON.parse(result)).toBe("hello world");
+    });
+});

package/dist/src/examples/basic/index.d.ts

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

package/dist/src/examples/basic/index.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_server_1 = require("@hono/node-server");
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const hono_1 = require("hono");
+const cors_1 = require("hono/cors");
+const server_js_1 = require("../../server.js");
+const agent_js_1 = require("../../agent.js");
+const model_js_1 = require("../../model.js");
+const openai_1 = require("@ai-sdk/openai");
+const session_js_1 = require("../../session.js");
+/** In-memory session store. */
+const sessions = new Map();
+/** Agent definition with options, capabilities, and tools. */
+const agent = new agent_js_1.Agent("basic-agent", {
+    version: "0.1.0",
+    description: "An AAP-compatible agent powered by Vercel AI SDK.",
+})
+    .image({ http: {}, data: {} })
+    .history({ compacted: {}, full: {} })
+    .option({
+    name: "baseURL",
+    title: "LLM Base URL",
+    description: "OpenAI-compatible base URL",
+    type: "text",
+    default: "",
+})
+    .option({
+    name: "apiKey",
+    title: "LLM API Key",
+    description: "OpenAI API key",
+    type: "secret",
+    default: "",
+})
+    .option({
+    name: "model",
+    title: "Model",
+    description: "Model ID to use",
+    type: "text",
+    default: "gpt-4o",
+})
+    .tool("web_fetch", {
+    description: "Fetch the text content of a URL",
+    inputSchema: zod_1.z.object({ url: zod_1.z.string().describe("URL to fetch") }),
+}, async ({ url }) => {
+    const res = await fetch(url);
+    const text = await res.text();
+    return text
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 8000);
+});
+const handler = {
+    getMeta() {
+        return { version: 1, agents: [agent.info] };
+    },
+    createSession(req) {
+        const sessionId = `sess_${(0, node_crypto_1.randomUUID)()}`;
+        // Build the model from client-supplied options
+        const openai = (0, openai_1.createOpenAI)({
+            baseURL: req.agent.options?.baseURL || undefined,
+            apiKey: req.agent.options?.apiKey || undefined,
+        });
+        const model = new model_js_1.AiModelProvider(openai.chat(req.agent.options?.model ?? "gpt-4o"));
+        const session = new session_js_1.Session(sessionId, agent, model, req.agent, req.tools);
+        sessions.set(sessionId, session);
+        return session.runNewSession(req);
+    },
+    sendTurn(sessionId, req) {
+        const session = sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session not found: ${sessionId}`);
+        return session.runTurn(req);
+    },
+    async getSession(sessionId, history) {
+        const session = sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session not found: ${sessionId}`);
+        // history is never compacted, so compacted and full are the same
+        const historyData = history ? { [history]: session.history } : undefined;
+        return { ...session.toSessionResponse(), history: historyData };
+    },
+    async listSessions() {
+        return { sessions: [...sessions.keys()] };
+    },
+    async deleteSession(sessionId) {
+        sessions.delete(sessionId);
+    },
+};
+const port = Number(process.env.PORT ?? 3010);
+const app = new hono_1.Hono();
+app.use("*", (0, cors_1.cors)({ origin: "*" }));
+app.route("/", (0, server_js_1.aap)(handler));
+(0, node_server_1.serve)({ fetch: app.fetch, port });
+console.log(`basic-agent running on http://localhost:${port}`);

package/dist/src/examples/compact-history/index.d.ts

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

package/dist/src/examples/compact-history/index.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_server_1 = require("@hono/node-server");
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const hono_1 = require("hono");
+const cors_1 = require("hono/cors");
+const server_js_1 = require("../../server.js");
+const agent_js_1 = require("../../agent.js");
+const model_js_1 = require("../../model.js");
+const openai_1 = require("@ai-sdk/openai");
+const session_js_1 = require("./session.js");
+/** Agent definition with options, capabilities, and tools. */
+const agent = new agent_js_1.Agent("compact-history-agent", {
+    version: "0.1.0",
+    description: "An AAP-compatible agent with sliding-window history compaction, powered by Vercel AI SDK.",
+})
+    .image({ http: {}, data: {} })
+    .history({ compacted: {}, full: {} })
+    .option({
+    name: "baseURL",
+    title: "LLM Base URL",
+    description: "OpenAI-compatible base URL",
+    type: "text",
+    default: "",
+})
+    .option({
+    name: "apiKey",
+    title: "LLM API Key",
+    description: "OpenAI API key",
+    type: "secret",
+    default: "",
+})
+    .option({
+    name: "model",
+    title: "Model",
+    description: "Model ID to use",
+    type: "text",
+    default: "gpt-4o",
+})
+    .tool("web_fetch", {
+    description: "Fetch the text content of a URL",
+    inputSchema: zod_1.z.object({ url: zod_1.z.string().describe("URL to fetch") }),
+}, async ({ url }) => {
+    const res = await fetch(url);
+    const text = await res.text();
+    return text
+        .replace(/<[^>]+>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 8000);
+});
+const handler = {
+    getMeta() {
+        return { version: 1, agents: [agent.info] };
+    },
+    createSession(req) {
+        const sessionId = `sess_${(0, node_crypto_1.randomUUID)()}`;
+        // Build the model from client-supplied options
+        const openai = (0, openai_1.createOpenAI)({
+            baseURL: req.agent.options?.baseURL || undefined,
+            apiKey: req.agent.options?.apiKey || undefined,
+        });
+        const model = new model_js_1.AiModelProvider(openai.chat(req.agent.options?.model ?? "gpt-4o"));
+        const session = new session_js_1.TruncatedHistorySession(sessionId, agent, model, req.agent, req.tools);
+        session_js_1.sessions.set(sessionId, session);
+        return session.runNewSession(req);
+    },
+    sendTurn(sessionId, req) {
+        const session = session_js_1.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session not found: ${sessionId}`);
+        return session.runTurn(req);
+    },
+    async getSession(sessionId, history) {
+        const session = session_js_1.sessions.get(sessionId);
+        if (!session)
+            throw new Error(`Session not found: ${sessionId}`);
+        // history exposes both the compacted window and the full uncompacted history
+        const historyData = history === "compacted"
+            ? { compacted: session.history }
+            : history === "full"
+                ? { full: session.fullHistory }
+                : undefined;
+        return { ...session.toSessionResponse(), history: historyData };
+    },
+    async listSessions() {
+        return { sessions: [...session_js_1.sessions.keys()] };
+    },
+    async deleteSession(sessionId) {
+        session_js_1.sessions.delete(sessionId);
+    },
+};
+const port = Number(process.env.PORT ?? 3010);
+const app = new hono_1.Hono();
+app.use("*", (0, cors_1.cors)({ origin: "*" }));
+app.route("/", (0, server_js_1.aap)(handler));
+(0, node_server_1.serve)({ fetch: app.fetch, port });
+console.log(`compact-history-agent running on http://localhost:${port}`);

package/dist/src/examples/compact-history/session.d.ts

@@ -0,0 +1,18 @@
+import type { AgentResponse, DeltaSSEEvent, HistoryMessage } from "@agentapplicationprotocol/core";
+import { Session } from "../../session.js";
+/** In-memory session store. */
+export declare const sessions: Map<string, TruncatedHistorySession>;
+/**
+ * Session subclass with sliding-window history compaction.
+ * `this.history` holds the compacted window sent to the model.
+ * `fullHistory` retains the complete uncompacted history.
+ */
+export declare class TruncatedHistorySession extends Session {
+    fullHistory: HistoryMessage[];
+    /** Appends new history entries to `fullHistory` and trims `this.history` to the compacted window. */
+    private syncAndCompact;
+    /** Streams the model response, then compacts history. */
+    protected stream(messages: HistoryMessage[]): AsyncIterable<DeltaSSEEvent>;
+    /** Calls the model, then compacts history. */
+    protected call(messages: HistoryMessage[]): Promise<AgentResponse>;
+}

package/dist/src/examples/compact-history/session.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TruncatedHistorySession = exports.sessions = void 0;
+const session_js_1 = require("../../session.js");
+/** In-memory session store. */
+exports.sessions = new Map();
+const COMPACTED_HISTORY_SIZE = 10;
+/** Trims history to the last `COMPACTED_HISTORY_SIZE` messages, ensuring the window never starts on a `tool` message. */
+function compact(history) {
+    if (history.length <= COMPACTED_HISTORY_SIZE)
+        return history;
+    let start = history.length - COMPACTED_HISTORY_SIZE;
+    // skip leading tool messages to avoid orphaned tool results
+    while (start < history.length && history[start].role === "tool")
+        start++;
+    return history.slice(start);
+}
+/**
+ * Session subclass with sliding-window history compaction.
+ * `this.history` holds the compacted window sent to the model.
+ * `fullHistory` retains the complete uncompacted history.
+ */
+class TruncatedHistorySession extends session_js_1.Session {
+    constructor() {
+        super(...arguments);
+        this.fullHistory = [];
+    }
+    /** Appends new history entries to `fullHistory` and trims `this.history` to the compacted window. */
+    syncAndCompact(before) {
+        this.fullHistory.push(...this.history.slice(before));
+        this.history = compact(this.history);
+    }
+    /** Streams the model response, then compacts history. */
+    async *stream(messages) {
+        const before = this.history.length;
+        for await (const e of super.stream(messages))
+            yield e;
+        this.syncAndCompact(before);
+    }
+    /** Calls the model, then compacts history. */
+    async call(messages) {
+        const before = this.history.length;
+        const res = await super.call(messages);
+        this.syncAndCompact(before);
+        return res;
+    }
+}
+exports.TruncatedHistorySession = TruncatedHistorySession;

package/dist/src/model.test.d.ts

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

package/dist/src/model.test.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const model_1 = require("./model");
+// --- ModelProvider base class ---
+class ConcreteModel extends model_1.ModelProvider {
+    async *stream(_history) {
+        yield { event: "text_delta", delta: "hello" };
+        yield { event: "turn_stop", stopReason: "end_turn" };
+    }
+}
+(0, vitest_1.describe)("ModelProvider", () => {
+    (0, vitest_1.it)("call() falls back to stream() and returns AgentResponse", async () => {
+        const model = new ConcreteModel();
+        const res = await model.call([{ role: "user", content: "hi" }], []);
+        (0, vitest_1.expect)(res.stopReason).toBe("end_turn");
+        (0, vitest_1.expect)(res.messages).toHaveLength(1);
+        (0, vitest_1.expect)(res.messages[0]).toMatchObject({ role: "assistant" });
+    });
+});
+function makeLM() {
+    return {
+        specificationVersion: "v2",
+        provider: "test",
+        modelId: "test-model",
+        defaultObjectGenerationMode: undefined,
+        doStream: vitest_1.vi.fn(),
+        doGenerate: vitest_1.vi.fn(),
+    };
+}
+function mockStream(lm, chunks) {
+    lm.doStream.mockResolvedValue({
+        stream: new ReadableStream({
+            start(controller) {
+                for (const chunk of chunks)
+                    controller.enqueue(chunk);
+                controller.close();
+            },
+        }),
+        rawValue: {},
+        warnings: [],
+    });
+}
+function mockGenerate(lm, finishReason, content) {
+    lm.doGenerate.mockResolvedValue({
+        finishReason,
+        usage: { inputTokens: 1, outputTokens: 1 },
+        content,
+        rawValue: {},
+        warnings: [],
+        response: { id: "r1", timestamp: new Date(), modelId: "test-model", headers: {} },
+    });
+}
+(0, vitest_1.describe)("AiModelProvider", () => {
+    (0, vitest_1.it)("stores the language model", () => {
+        const lm = makeLM();
+        (0, vitest_1.expect)(new model_1.AiModelProvider(lm).model).toBe(lm);
+    });
+    (0, vitest_1.it)("stream() yields text_delta and turn_stop", async () => {
+        const lm = makeLM();
+        mockStream(lm, [
+            { type: "text-delta", id: "t1", delta: "hello", providerMetadata: undefined },
+            {
+                type: "finish",
+                finishReason: "stop",
+                usage: { inputTokens: 1, outputTokens: 1 },
+                providerMetadata: undefined,
+            },
+        ]);
+        const events = [];
+        for await (const e of new model_1.AiModelProvider(lm).stream([{ role: "user", content: "hi" }], [])) {
+            events.push(e);
+        }
+        (0, vitest_1.expect)(events.some((e) => e.event === "text_delta")).toBe(true);
+        (0, vitest_1.expect)(events.some((e) => e.event === "turn_stop")).toBe(true);
+    });
+    (0, vitest_1.it)("stream() yields thinking_delta and tool_call", async () => {
+        const lm = makeLM();
+        mockStream(lm, [
+            { type: "reasoning-delta", id: "r1", delta: "hmm", providerMetadata: undefined },
+            {
+                type: "tool-call",
+                toolCallId: "c1",
+                toolName: "fn",
+                input: { x: 1 },
+                providerMetadata: undefined,
+            },
+            {
+                type: "finish",
+                finishReason: "tool-calls",
+                usage: { inputTokens: 1, outputTokens: 1 },
+                providerMetadata: undefined,
+            },
+        ]);
+        const events = [];
+        for await (const e of new model_1.AiModelProvider(lm).stream([{ role: "user", content: "hi" }], [])) {
+            events.push(e);
+        }
+        (0, vitest_1.expect)(events.some((e) => e.event === "thinking_delta")).toBe(true);
+        (0, vitest_1.expect)(events.some((e) => e.event === "tool_call")).toBe(true);
+        (0, vitest_1.expect)(events.find((e) => e.event === "turn_stop")).toMatchObject({ stopReason: "tool_use" });
+    });
+    (0, vitest_1.it)("call() returns AgentResponse with text content", async () => {
+        const lm = makeLM();
+        mockGenerate(lm, "stop", [{ type: "text", text: "done" }]);
+        const res = await new model_1.AiModelProvider(lm).call([{ role: "user", content: "hi" }], []);
+        (0, vitest_1.expect)(res.stopReason).toBe("end_turn");
+        (0, vitest_1.expect)(res.messages[0].role).toBe("assistant");
+    });
+    (0, vitest_1.it)("call() maps reasoning and tool-call blocks in response", async () => {
+        const lm = makeLM();
+        mockGenerate(lm, "stop", [
+            { type: "reasoning", text: "thinking..." },
+            { type: "tool-call", toolCallId: "c1", toolName: "fn", input: { x: 1 } },
+        ]);
+        const res = await new model_1.AiModelProvider(lm).call([{ role: "user", content: "hi" }], []);
+        const blocks = res.messages.find((m) => m.role === "assistant").content;
+        (0, vitest_1.expect)(blocks.some((b) => b.type === "thinking")).toBe(true);
+        (0, vitest_1.expect)(blocks.some((b) => b.type === "tool_use")).toBe(true);
+    });
+    (0, vitest_1.it)("call() passes system, image (data URI), assistant with thinking/tool_use, and tool messages", async () => {
+        const lm = makeLM();
+        mockGenerate(lm, "tool-calls", [
+            { type: "tool-call", toolCallId: "c1", toolName: "fn", input: { x: 1 } },
+        ]);
+        const history = [
+            { role: "system", content: "be helpful" },
+            { role: "user", content: [{ type: "image", url: "data:image/png;base64,abc" }] },
+            {
+                role: "assistant",
+                content: [
+                    { type: "thinking", thinking: "hmm" },
+                    { type: "tool_use", toolCallId: "c1", name: "fn", input: { x: 1 } },
+                ],
+            },
+            { role: "tool", toolCallId: "c1", content: "result" },
+        ];
+        const res = await new model_1.AiModelProvider(lm).call(history, []);
+        (0, vitest_1.expect)(res.stopReason).toBe("tool_use");
+    });
+    (0, vitest_1.it)("call() maps finishReason variants correctly", async () => {
+        const cases = [
+            ["length", "max_tokens"],
+            ["content-filter", "refusal"],
+            ["error", "error"],
+        ];
+        for (const [finishReason, expected] of cases) {
+            const lm = makeLM();
+            mockGenerate(lm, finishReason, []);
+            const res = await new model_1.AiModelProvider(lm).call([{ role: "user", content: "hi" }], []);
+            (0, vitest_1.expect)(res.stopReason).toBe(expected);
+        }
+    });
+});

package/dist/src/server.test.d.ts

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