@renseiai/agentfactory-server 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rensei AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @renseiai/agentfactory-server
+
+Redis-backed infrastructure for [AgentFactory](https://github.com/renseiai/agentfactory). Provides work queue, session storage, worker pool management, issue locking, and webhook idempotency.
+
+## Installation
+
+```bash
+npm install @renseiai/agentfactory-server
+```
+
+Requires a Redis instance (works with Redis, Upstash, Vercel KV, or any Redis-compatible store).
+
+## What It Provides
+
+| Component | Description |
+|-----------|-------------|
+| **WorkQueue** | Priority queue with atomic claim/release (sorted sets) |
+| **SessionStorage** | Key-value session state (status, cost, timestamps) |
+| **WorkerStorage** | Worker registration, heartbeat, capacity tracking |
+| **IssueLock** | Per-issue mutex with pending queue |
+| **AgentTracking** | QA attempt counts, agent-worked history |
+| **WebhookIdempotency** | Dedup webhook deliveries with TTL |
+| **TokenStorage** | OAuth token storage and retrieval |
+| **RateLimit** | Token bucket rate limiting |
+| **WorkerAuth** | API key verification for workers |
+| **RedisEventBus** | Governor event bus backed by Redis Streams (consumer groups, MAXLEN trim) |
+| **RedisEventDeduplicator** | Governor event dedup using SETNX with TTL |
+| **RedisOverrideStorage** | Governor human override state (HOLD, PRIORITY) |
+| **RedisProcessingStateStorage** | Top-of-funnel phase tracking (research, backlog-creation) |
+
+## Quick Start
+
+```typescript
+import { createRedisClient, enqueueWork, claimWork } from '@renseiai/agentfactory-server'
+
+// Redis client (auto-reads REDIS_URL from env)
+const redis = createRedisClient()
+
+// Enqueue a work item with priority
+await enqueueWork({
+  issueId: 'issue-uuid',
+  identifier: 'PROJ-123',
+  workType: 'development',
+  priority: 2,
+  prompt: 'Implement the login feature...',
+})
+
+// Worker claims next item
+const work = await claimWork('worker-1')
+if (work) {
+  console.log(`Claimed: ${work.identifier} [${work.workType}]`)
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `REDIS_URL` | Yes | Redis connection URL (e.g., `redis://localhost:6379`) |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@renseiai/agentfactory](https://www.npmjs.com/package/@renseiai/agentfactory) | Core orchestrator |
+| [@renseiai/agentfactory-cli](https://www.npmjs.com/package/@renseiai/agentfactory-cli) | CLI tools (worker, orchestrator) |
+| [@renseiai/agentfactory-nextjs](https://www.npmjs.com/package/@renseiai/agentfactory-nextjs) | Next.js webhook server |
+
+## License
+
+MIT

package/dist/src/a2a-server.d.ts

@@ -0,0 +1,88 @@
+/**
+ * A2A Server Handlers
+ *
+ * Framework-agnostic utilities for exposing AgentFactory fleet capabilities
+ * via the Agent-to-Agent (A2A) protocol. Provides AgentCard generation,
+ * JSON-RPC request routing, and SSE event formatting.
+ *
+ * Consuming applications wire these handlers into their own HTTP server
+ * (Express, Hono, Next.js, etc.) — this module has no framework dependency.
+ */
+import type { A2aAgentCard, A2aAuthScheme, A2aMessage, A2aSkill, A2aTask, A2aTaskEvent, JsonRpcRequest, JsonRpcResponse } from './a2a-types.js';
+/** Configuration for building an AgentCard */
+export interface A2aServerConfig {
+    /** Human-readable agent name */
+    name: string;
+    /** Short description of the agent's purpose */
+    description: string;
+    /** Base URL where A2A endpoints are exposed */
+    url: string;
+    /** Semantic version of the agent (defaults to '1.0.0') */
+    version?: string;
+    /** Explicit skill list; when omitted skills are derived from AgentWorkType */
+    skills?: A2aSkill[];
+    /** Whether the agent supports SSE streaming (defaults to false) */
+    streaming?: boolean;
+    /** Authentication schemes the endpoint accepts */
+    authSchemes?: A2aAuthScheme[];
+}
+/**
+ * Build an A2A AgentCard from the supplied configuration.
+ *
+ * If no explicit skills are provided the card is populated with skills
+ * derived from every known {@link AgentWorkType}.
+ *
+ * @param config - Server configuration
+ * @returns A fully-formed AgentCard
+ */
+export declare function buildAgentCard(config: A2aServerConfig): A2aAgentCard;
+/** Callbacks that the consuming application must supply */
+export interface A2aHandlerOptions {
+    /** Handle an incoming message, optionally targeting an existing task */
+    onSendMessage: (message: A2aMessage, taskId?: string) => Promise<A2aTask>;
+    /** Retrieve an existing task by ID */
+    onGetTask: (taskId: string) => Promise<A2aTask | null>;
+    /** Cancel an existing task by ID */
+    onCancelTask: (taskId: string) => Promise<A2aTask | null>;
+    /**
+     * Verify the Authorization header.
+     * Defaults to Bearer-token verification via {@link verifyApiKey}.
+     */
+    verifyAuth?: (authHeader: string | undefined) => boolean;
+}
+/**
+ * A framework-agnostic function that accepts a parsed JSON-RPC request
+ * (plus an optional Authorization header) and returns a JSON-RPC response.
+ */
+export type A2aRequestHandler = (request: JsonRpcRequest, authHeader?: string) => Promise<JsonRpcResponse>;
+/**
+ * Create a framework-agnostic A2A request handler.
+ *
+ * The returned function processes a single JSON-RPC request and returns
+ * the corresponding response. The consuming application is responsible
+ * for HTTP parsing, serialisation, and transport.
+ *
+ * Supported methods:
+ * - `message/send` — send a message (optionally to an existing task)
+ * - `tasks/get`    — retrieve a task by ID
+ * - `tasks/cancel` — cancel a task by ID
+ *
+ * @param options - Callbacks for task lifecycle and (optional) auth
+ * @returns An async handler function
+ */
+export declare function createA2aRequestHandler(options: A2aHandlerOptions): A2aRequestHandler;
+/**
+ * Format an A2A task event as a Server-Sent Events (SSE) message.
+ *
+ * The output follows the SSE text/event-stream format:
+ * ```
+ * event: <type>
+ * data: <JSON payload>
+ *
+ * ```
+ *
+ * @param event - The task event to format
+ * @returns A string ready to write to an SSE response stream
+ */
+export declare function formatSseEvent(event: A2aTaskEvent): string;
+//# sourceMappingURL=a2a-server.d.ts.map

package/dist/src/a2a-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-server.d.ts","sourceRoot":"","sources":["../../src/a2a-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,cAAc,EACd,eAAe,EAChB,MAAM,gBAAgB,CAAA;AAMvB,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAA;IACX,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,kDAAkD;IAClD,WAAW,CAAC,EAAE,aAAa,EAAE,CAAA;CAC9B;AA2ED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CAmBpE;AAMD,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,aAAa,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACzE,sCAAsC;IACtC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IACtD,oCAAoC;IACpC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IACzD;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAA;CACzD;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,KAChB,OAAO,CAAC,eAAe,CAAC,CAAA;AAwC7B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAoErF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAG1D"}

package/dist/src/a2a-server.integration.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Integration tests for the A2A Server
+ *
+ * Wires the A2A request handler to mock task callbacks and verifies
+ * end-to-end JSON-RPC handling, AgentCard generation, SSE formatting,
+ * and auth integration.
+ */
+export {};
+//# sourceMappingURL=a2a-server.integration.test.d.ts.map

package/dist/src/a2a-server.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-server.integration.test.d.ts","sourceRoot":"","sources":["../../src/a2a-server.integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/src/a2a-server.integration.test.js

@@ -0,0 +1,397 @@
+/**
+ * Integration tests for the A2A Server
+ *
+ * Wires the A2A request handler to mock task callbacks and verifies
+ * end-to-end JSON-RPC handling, AgentCard generation, SSE formatting,
+ * and auth integration.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { buildAgentCard, createA2aRequestHandler, formatSseEvent, } from './a2a-server.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeRequest(method, params, id = 'req-1') {
+    return { jsonrpc: '2.0', id, method, params };
+}
+function makeMessage(text, role = 'user') {
+    return { role, parts: [{ type: 'text', text }] };
+}
+function makeTask(overrides = {}) {
+    return {
+        id: 'task-1',
+        status: 'submitted',
+        messages: [],
+        artifacts: [],
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// 1. Full message/send -> task lifecycle
+// ---------------------------------------------------------------------------
+describe('A2A Server — full task lifecycle', () => {
+    it('creates a task via message/send, retrieves it, and cancels it', async () => {
+        // In-memory task store
+        const tasks = new Map();
+        const onSendMessage = vi.fn(async (message, _taskId) => {
+            const task = {
+                id: 'task-lifecycle-1',
+                status: 'working',
+                messages: [message],
+                artifacts: [],
+            };
+            tasks.set(task.id, task);
+            return task;
+        });
+        const onGetTask = vi.fn(async (taskId) => {
+            return tasks.get(taskId) ?? null;
+        });
+        const onCancelTask = vi.fn(async (taskId) => {
+            const task = tasks.get(taskId);
+            if (!task)
+                return null;
+            task.status = 'canceled';
+            return task;
+        });
+        const handler = createA2aRequestHandler({
+            onSendMessage,
+            onGetTask,
+            onCancelTask,
+            verifyAuth: () => true,
+        });
+        // Step 1: Send message
+        const sendRes = await handler(makeRequest('message/send', { message: makeMessage('Build the feature') }));
+        expect(sendRes.error).toBeUndefined();
+        const createdTask = sendRes.result;
+        expect(createdTask.id).toBe('task-lifecycle-1');
+        expect(createdTask.status).toBe('working');
+        expect(createdTask.messages).toHaveLength(1);
+        expect(createdTask.messages[0].parts[0]).toMatchObject({ type: 'text', text: 'Build the feature' });
+        expect(onSendMessage).toHaveBeenCalledWith(makeMessage('Build the feature'), undefined);
+        // Step 2: Get task
+        const getRes = await handler(makeRequest('tasks/get', { taskId: 'task-lifecycle-1' }));
+        expect(getRes.error).toBeUndefined();
+        const retrievedTask = getRes.result;
+        expect(retrievedTask.id).toBe('task-lifecycle-1');
+        expect(retrievedTask.status).toBe('working');
+        expect(onGetTask).toHaveBeenCalledWith('task-lifecycle-1');
+        // Step 3: Cancel task
+        const cancelRes = await handler(makeRequest('tasks/cancel', { taskId: 'task-lifecycle-1' }));
+        expect(cancelRes.error).toBeUndefined();
+        const canceledTask = cancelRes.result;
+        expect(canceledTask.id).toBe('task-lifecycle-1');
+        expect(canceledTask.status).toBe('canceled');
+        expect(onCancelTask).toHaveBeenCalledWith('task-lifecycle-1');
+    });
+    it('returns -32001 when getting a non-existent task', async () => {
+        const handler = createA2aRequestHandler({
+            onSendMessage: vi.fn(async () => makeTask()),
+            onGetTask: vi.fn(async () => null),
+            onCancelTask: vi.fn(async () => null),
+            verifyAuth: () => true,
+        });
+        const res = await handler(makeRequest('tasks/get', { taskId: 'nonexistent' }));
+        expect(res.error?.code).toBe(-32001);
+        expect(res.error?.message).toBe('Task not found');
+    });
+    it('returns -32001 when canceling a non-existent task', async () => {
+        const handler = createA2aRequestHandler({
+            onSendMessage: vi.fn(async () => makeTask()),
+            onGetTask: vi.fn(async () => null),
+            onCancelTask: vi.fn(async () => null),
+            verifyAuth: () => true,
+        });
+        const res = await handler(makeRequest('tasks/cancel', { taskId: 'nonexistent' }));
+        expect(res.error?.code).toBe(-32001);
+        expect(res.error?.message).toBe('Task not found');
+    });
+    it('passes taskId to onSendMessage for follow-up messages', async () => {
+        const onSendMessage = vi.fn(async () => makeTask({ id: 'task-followup', status: 'working' }));
+        const handler = createA2aRequestHandler({
+            onSendMessage,
+            onGetTask: vi.fn(async () => null),
+            onCancelTask: vi.fn(async () => null),
+            verifyAuth: () => true,
+        });
+        await handler(makeRequest('message/send', {
+            message: makeMessage('Continue working'),
+            taskId: 'task-followup',
+        }));
+        expect(onSendMessage).toHaveBeenCalledWith(makeMessage('Continue working'), 'task-followup');
+    });
+    it('returns -32603 when onSendMessage throws an error', async () => {
+        const handler = createA2aRequestHandler({
+            onSendMessage: vi.fn(async () => { throw new Error('Queue overflow'); }),
+            onGetTask: vi.fn(async () => null),
+            onCancelTask: vi.fn(async () => null),
+            verifyAuth: () => true,
+        });
+        const res = await handler(makeRequest('message/send', { message: makeMessage('hello') }));
+        expect(res.error?.code).toBe(-32603);
+        expect(res.error?.message).toBe('Queue overflow');
+    });
+    it('returns -32601 for unknown methods', async () => {
+        const handler = createA2aRequestHandler({
+            onSendMessage: vi.fn(async () => makeTask()),
+            onGetTask: vi.fn(async () => null),
+            onCancelTask: vi.fn(async () => null),
+            verifyAuth: () => true,
+        });
+        const res = await handler(makeRequest('tasks/unknown'));
+        expect(res.error?.code).toBe(-32601);
+        expect(res.error?.message).toContain('Method not found');
+        expect(res.error?.message).toContain('tasks/unknown');
+    });
+    it('always returns JSON-RPC 2.0 version and echoes request id', async () => {
+        const handler = createA2aRequestHandler({
+            onSendMessage: vi.fn(async () => makeTask()),
+            onGetTask: vi.fn(async () => makeTask()),
+            onCancelTask: vi.fn(async () => null),
+            verifyAuth: () => true,
+        });
+        const res = await handler(makeRequest('tasks/get', { taskId: 'task-1' }, 'my-req-42'));
+        expect(res.jsonrpc).toBe('2.0');
+        expect(res.id).toBe('my-req-42');
+    });
+});
+// ---------------------------------------------------------------------------
+// 2. AgentCard generation end-to-end
+// ---------------------------------------------------------------------------
+describe('A2A Server — AgentCard generation', () => {
+    it('builds a complete agent card with all fields', () => {
+        const config = {
+            name: 'FleetCoordinator',
+            description: 'Coordinates work across multiple agents',
+            url: 'https://fleet.example.com/a2a',
+            version: '2.1.0',
+            streaming: true,
+            authSchemes: [
+                { type: 'http', scheme: 'bearer' },
+                { type: 'apiKey', in: 'header', name: 'x-api-key' },
+            ],
+        };
+        const card = buildAgentCard(config);
+        expect(card.name).toBe('FleetCoordinator');
+        expect(card.description).toBe('Coordinates work across multiple agents');
+        expect(card.url).toBe('https://fleet.example.com/a2a');
+        expect(card.version).toBe('2.1.0');
+        expect(card.capabilities.streaming).toBe(true);
+        expect(card.capabilities.pushNotifications).toBe(false);
+        expect(card.capabilities.stateTransitionHistory).toBe(false);
+        expect(card.authentication).toEqual([
+            { type: 'http', scheme: 'bearer' },
+            { type: 'apiKey', in: 'header', name: 'x-api-key' },
+        ]);
+        expect(card.defaultInputContentTypes).toEqual(['text/plain']);
+        expect(card.defaultOutputContentTypes).toEqual(['text/plain']);
+    });
+    it('auto-generates skills from work types when none provided', () => {
+        const card = buildAgentCard({
+            name: 'Worker',
+            description: 'Generic worker',
+            url: 'https://worker.example.com/a2a',
+        });
+        expect(card.skills.length).toBeGreaterThan(0);
+        const skillIds = card.skills.map(s => s.id);
+        expect(skillIds).toContain('code-development');
+        expect(skillIds).toContain('quality-assurance');
+        expect(skillIds).toContain('research-analysis');
+        expect(skillIds).toContain('backlog-creation');
+        expect(skillIds).toContain('inflight-work');
+        expect(skillIds).toContain('acceptance-review');
+        expect(skillIds).toContain('refinement');
+        expect(skillIds).toContain('coordination');
+        expect(skillIds).toContain('qa-coordination');
+        expect(skillIds).toContain('acceptance-coordination');
+        // Each skill should have an id, name, and description
+        for (const skill of card.skills) {
+            expect(skill.id).toBeTruthy();
+            expect(skill.name).toBeTruthy();
+            expect(skill.description).toBeTruthy();
+        }
+    });
+    it('uses explicit skills when provided', () => {
+        const card = buildAgentCard({
+            name: 'Specialist',
+            description: 'A specialist agent',
+            url: 'https://specialist.example.com/a2a',
+            skills: [
+                {
+                    id: 'data-analysis',
+                    name: 'Data Analysis',
+                    description: 'Analyze data sets and produce reports',
+                    tags: ['analysis'],
+                },
+            ],
+        });
+        expect(card.skills).toHaveLength(1);
+        expect(card.skills[0].id).toBe('data-analysis');
+        expect(card.skills[0].name).toBe('Data Analysis');
+        expect(card.skills[0].tags).toEqual(['analysis']);
+    });
+    it('defaults version to 1.0.0 and streaming to false', () => {
+        const card = buildAgentCard({
+            name: 'Default',
+            description: 'Defaults test',
+            url: 'https://default.example.com/a2a',
+        });
+        expect(card.version).toBe('1.0.0');
+        expect(card.capabilities.streaming).toBe(false);
+    });
+    it('omits authentication when no authSchemes provided', () => {
+        const card = buildAgentCard({
+            name: 'NoAuth',
+            description: 'No auth agent',
+            url: 'https://noauth.example.com/a2a',
+        });
+        expect(card.authentication).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// 3. SSE event formatting round-trip
+// ---------------------------------------------------------------------------
+describe('A2A Server — SSE formatting round-trip', () => {
+    it('formats and parses TaskStatusUpdate correctly', () => {
+        const event = {
+            type: 'TaskStatusUpdate',
+            taskId: 'task-rt-1',
+            status: 'working',
+            message: makeMessage('Processing your request...', 'agent'),
+            final: false,
+        };
+        const formatted = formatSseEvent(event);
+        // Parse the SSE output
+        const lines = formatted.split('\n');
+        expect(lines[0]).toBe('event: TaskStatusUpdate');
+        const dataLine = lines[1];
+        expect(dataLine.startsWith('data: ')).toBe(true);
+        const parsed = JSON.parse(dataLine.slice(6));
+        expect(parsed.type).toBe('TaskStatusUpdate');
+        expect(parsed.taskId).toBe('task-rt-1');
+        expect(parsed.status).toBe('working');
+        expect(parsed.message.role).toBe('agent');
+        expect(parsed.message.parts[0].text).toBe('Processing your request...');
+        expect(parsed.final).toBe(false);
+        // Ends with double newline
+        expect(formatted.endsWith('\n\n')).toBe(true);
+    });
+    it('formats and parses TaskArtifactUpdate correctly', () => {
+        const event = {
+            type: 'TaskArtifactUpdate',
+            taskId: 'task-rt-2',
+            artifact: {
+                name: 'output.json',
+                parts: [{ type: 'data', data: { result: 42, status: 'ok' } }],
+            },
+        };
+        const formatted = formatSseEvent(event);
+        const lines = formatted.split('\n');
+        expect(lines[0]).toBe('event: TaskArtifactUpdate');
+        const parsed = JSON.parse(lines[1].slice(6));
+        expect(parsed.type).toBe('TaskArtifactUpdate');
+        expect(parsed.taskId).toBe('task-rt-2');
+        expect(parsed.artifact.name).toBe('output.json');
+        expect(parsed.artifact.parts[0].data).toEqual({ result: 42, status: 'ok' });
+    });
+    it('produces valid SSE format with event and data lines separated by double newline', () => {
+        const event = {
+            type: 'TaskStatusUpdate',
+            taskId: 'task-fmt',
+            status: 'completed',
+            final: true,
+        };
+        const formatted = formatSseEvent(event);
+        // Should match the exact SSE spec: event line, data line, empty line
+        const pattern = /^event: \w+\ndata: .+\n\n$/;
+        expect(formatted).toMatch(pattern);
+    });
+    it('round-trips a completed status event with final: true', () => {
+        const original = {
+            type: 'TaskStatusUpdate',
+            taskId: 'task-complete',
+            status: 'completed',
+            message: makeMessage('All done!', 'agent'),
+            final: true,
+        };
+        const formatted = formatSseEvent(original);
+        const dataLine = formatted.split('\n')[1];
+        const roundTripped = JSON.parse(dataLine.slice(6));
+        expect(roundTripped.type).toBe(original.type);
+        expect(roundTripped.taskId).toBe(original.taskId);
+        expect(roundTripped.status).toBe(original.status);
+        expect(roundTripped.final).toBe(original.final);
+        expect(roundTripped.message).toEqual(original.message);
+    });
+});
+// ---------------------------------------------------------------------------
+// 4. Auth integration
+// ---------------------------------------------------------------------------
+describe('A2A Server — auth integration', () => {
+    function createAuthHandler(validTokens) {
+        const verifyAuth = (authHeader) => {
+            if (!authHeader)
+                return false;
+            const token = authHeader.startsWith('Bearer ')
+                ? authHeader.slice(7)
+                : authHeader;
+            return validTokens.includes(token);
+        };
+        return createA2aRequestHandler({
+            onSendMessage: vi.fn(async () => makeTask()),
+            onGetTask: vi.fn(async () => makeTask()),
+            onCancelTask: vi.fn(async () => makeTask({ status: 'canceled' })),
+            verifyAuth,
+        });
+    }
+    it('allows requests with a valid Bearer token', async () => {
+        const handler = createAuthHandler(['valid-token-123']);
+        const res = await handler(makeRequest('tasks/get', { taskId: 'task-1' }), 'Bearer valid-token-123');
+        expect(res.error).toBeUndefined();
+        expect(res.result).toBeDefined();
+    });
+    it('allows requests with a valid raw API key', async () => {
+        const handler = createAuthHandler(['raw-api-key-456']);
+        const res = await handler(makeRequest('tasks/get', { taskId: 'task-1' }), 'raw-api-key-456');
+        expect(res.error).toBeUndefined();
+        expect(res.result).toBeDefined();
+    });
+    it('rejects requests with an invalid token', async () => {
+        const handler = createAuthHandler(['valid-token-123']);
+        const res = await handler(makeRequest('tasks/get', { taskId: 'task-1' }), 'Bearer wrong-token');
+        expect(res.error?.code).toBe(-32000);
+        expect(res.error?.message).toBe('Unauthorized');
+        expect(res.result).toBeUndefined();
+    });
+    it('rejects requests with no auth header', async () => {
+        const handler = createAuthHandler(['valid-token-123']);
+        const res = await handler(makeRequest('tasks/get', { taskId: 'task-1' }));
+        expect(res.error?.code).toBe(-32000);
+        expect(res.error?.message).toBe('Unauthorized');
+    });
+    it('rejects requests with empty auth header', async () => {
+        const handler = createAuthHandler(['valid-token-123']);
+        const res = await handler(makeRequest('tasks/get', { taskId: 'task-1' }), '');
+        expect(res.error?.code).toBe(-32000);
+        expect(res.error?.message).toBe('Unauthorized');
+    });
+    it('allows different methods when auth passes', async () => {
+        const handler = createAuthHandler(['super-secret']);
+        // message/send
+        const sendRes = await handler(makeRequest('message/send', { message: makeMessage('hi') }), 'Bearer super-secret');
+        expect(sendRes.error).toBeUndefined();
+        // tasks/get
+        const getRes = await handler(makeRequest('tasks/get', { taskId: 'task-1' }), 'Bearer super-secret');
+        expect(getRes.error).toBeUndefined();
+        // tasks/cancel
+        const cancelRes = await handler(makeRequest('tasks/cancel', { taskId: 'task-1' }), 'Bearer super-secret');
+        expect(cancelRes.error).toBeUndefined();
+    });
+    it('blocks all methods when auth fails', async () => {
+        const handler = createAuthHandler(['good-key']);
+        const sendRes = await handler(makeRequest('message/send', { message: makeMessage('hi') }), 'Bearer bad-key');
+        expect(sendRes.error?.code).toBe(-32000);
+        const getRes = await handler(makeRequest('tasks/get', { taskId: 'task-1' }), 'Bearer bad-key');
+        expect(getRes.error?.code).toBe(-32000);
+        const cancelRes = await handler(makeRequest('tasks/cancel', { taskId: 'task-1' }), 'Bearer bad-key');
+        expect(cancelRes.error?.code).toBe(-32000);
+    });
+});