@machinemetrics/agent-event-protocol 0.1.0

package/README.md

@@ -0,0 +1,274 @@
+# @machinemetrics/agent-event-protocol
+
+A transport-agnostic event protocol for streaming agent responses. Defines the schema and utilities for real-time communication between AI agents and clients.
+
+## Installation
+
+```bash
+npm install @machinemetrics/agent-event-protocol
+```
+
+## Design Principles
+
+1. **Simple** - Easy to understand and implement
+2. **Flexible** - Supports future features without breaking changes
+3. **Type-safe** - Strong contracts between client and server
+4. **Observable** - Easy to monitor and debug
+5. **Transport-agnostic** - Same events work over SSE, NDJSON, WebSocket, NATS, etc.
+
+## Protocol Overview
+
+The protocol defines a streaming event schema for agent responses. All events are self-identifying JSON payloads with common fields:
+
+- `event` - Event type identifier
+- `requestId` - Correlates all events to the originating request
+- `timestamp` - ISO 8601 timestamp for observability
+
+### Message Flow
+
+```
+┌─────────┐                                    ┌─────────┐
+│ Client  │                                    │ Server  │
+└────┬────┘                                    └────┬────┘
+     │                                              │
+     │  POST /v1/agents/{agentName}/stream         │
+     │  { messages, threadId?, context? }          │
+     ├─────────────────────────────────────────────>│
+     │                                              │
+     │  metadata: {threadId, requestId, agentId}   │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+     │  text: {blockId, stage: "start"}            │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+     │  text: {blockId, stage: "delta", delta}     │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+     │  text: {blockId, stage: "stop"}             │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+     │  done: {content, usage, finishReason}       │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+```
+
+### Client Action Flow
+
+When the agent needs client-side action, the stream pauses and resumes via a new request:
+
+```
+┌─────────┐                                    ┌─────────┐
+│ Client  │                                    │ Server  │
+└────┬────┘                                    └────┬────┘
+     │                                              │
+     │  POST /stream { messages, threadId? }       │
+     ├─────────────────────────────────────────────>│
+     │                                              │
+     │  continuation: {actionId, kind, payload}    │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+     │  done: {finishReason: "action_required"}    │
+     │<─────────────────────────────────────────────┤
+     │                                              │
+     │  (client handles action based on kind)      │
+     │                                              │
+     │  POST /stream { messages, threadId,         │
+     │    context: { actionResults: [...] }}       │
+     ├─────────────────────────────────────────────>│
+     │                                              │
+     │  (agent continues with result)              │
+     │                                              │
+```
+
+## Event Types
+
+The protocol defines 9 event types covering the complete lifecycle of an agent response.
+
+| Event | Description |
+|-------|-------------|
+| `metadata` | Stream initialization with threadId, requestId, agentId |
+| `text` | Streaming text output with stage lifecycle |
+| `thinking` | Model reasoning/thinking content (extended thinking) |
+| `tool_call` | Tool invocation with streaming arguments |
+| `tool_result` | Tool execution result (status and summary only) |
+| `done` | Stream complete with full content array |
+| `error` | Error condition with code and retry guidance |
+| `aborted` | Client cancellation acknowledgment |
+| `continuation` | Pause for client action (tools, approval, input) |
+
+### Terminal Events
+
+Each request must end with exactly one terminal event: `done`, `error`, or `aborted`.
+
+## Event Lifecycle (Stage Pattern)
+
+Content events (`text`, `thinking`, `tool_call`, `tool_result`) use a consistent stage pattern:
+
+| Stage | Description |
+|-------|-------------|
+| `start` | Block begins, includes `blockIndex` for ordering |
+| `delta` | Content chunk, includes `deltaIndex` for ordering within block |
+| `stop` | Block complete, includes final data for that block type |
+
+## Request Schema
+
+```typescript
+type AgentRequest = {
+  messages: InputMessage[];   // New user input
+  threadId?: string;          // Resume existing thread
+  context?: {
+    actionResults?: ActionResult[];  // Results from continuation events
+    [key: string]: unknown;          // Additional passthrough data
+  };
+};
+```
+
+Only `messages` is required. The server loads thread history from storage via `threadId`.
+
+## Content Blocks
+
+**User Content Blocks** (in requests):
+- `text` - Plain text input
+
+**Assistant Content Blocks** (in responses):
+- `text` - Text output
+- `thinking` - Model reasoning
+- `tool_use` - Tool invocation with args
+- `tool_result` - Tool result status and summary (no full payloads)
+
+## Error Handling
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `auth_failed` | Authentication failed |
+| `thread_not_found` | Thread does not exist |
+| `thread_access_denied` | Thread ownership violation |
+| `invalid_message_format` | Invalid request format |
+| `message_too_large` | Message exceeds size limit |
+| `rate_limit_exceeded` | Rate limit hit |
+| `stream_timeout` | Stream timed out |
+| `agent_error` | Agent execution error |
+| `tool_error` | Tool execution error |
+| `internal_error` | Internal server error |
+| `invalid_action_id` | Action ID not found or already resolved |
+
+### HTTP Status Mapping
+
+| Status | Error Codes |
+|--------|-------------|
+| 400 | `invalid_message_format`, `invalid_action_id` |
+| 401 | `auth_failed` |
+| 403 | `thread_access_denied` |
+| 404 | `thread_not_found` |
+| 413 | `message_too_large` |
+| 429 | `rate_limit_exceeded` |
+| 500 | `internal_error` |
+| 504 | `stream_timeout` |
+
+### Retry Guidance
+
+- `retryable: true` - Client can retry with backoff
+- `retryable: false` - Don't retry, user action required
+
+## SSE Transport
+
+Server-Sent Events is the default transport implementation.
+
+### Wire Format
+
+```
+Content-Type: text/event-stream
+Connection: keep-alive
+Cache-Control: no-cache
+
+event: metadata
+data: {"event":"metadata","requestId":"req-1","threadId":"th-1","agentId":"agent","timestamp":"..."}
+
+event: text
+data: {"event":"text","requestId":"req-1","messageId":"msg-1","blockId":"b0","stage":"start","blockIndex":0,"timestamp":"..."}
+
+event: text
+data: {"event":"text","requestId":"req-1","messageId":"msg-1","blockId":"b0","stage":"delta","delta":"Hello","deltaIndex":0,"timestamp":"..."}
+
+event: done
+data: {"event":"done","requestId":"req-1","messageId":"msg-1","threadId":"th-1","content":[...],"finishReason":"stop","timestamp":"..."}
+```
+
+### Keepalive
+
+Servers should send SSE comment lines (`: heartbeat\n\n`) every 15 seconds to prevent proxy timeouts.
+
+### Utilities
+
+```typescript
+import { encodeSSE, parseSSEChunk } from '@machinemetrics/agent-event-protocol';
+
+// Server: encode events for streaming
+const sseData = encodeSSE('text', { event: 'text', ... });
+
+// Client: parse incoming chunks
+const { events, remainder } = parseSSEChunk(chunk);
+```
+
+## Extensibility
+
+**Adding new events is backward compatible:**
+- Clients should ignore unknown event types
+- New optional fields can be added to existing events
+- No version bump required for additive changes
+
+**Breaking changes require new endpoint version:**
+```
+/v1/agents/{agentName}/stream  → Current
+/v2/agents/{agentName}/stream  → Breaking changes
+```
+
+## Exports
+
+```typescript
+import {
+  // Core types
+  InputMessage,
+  AgentRequest,
+  AgentEvent,
+  ActionResult,
+  UserContentBlock,
+  AssistantContentBlock,
+  EventStage,
+  MetadataEvent,
+  TextEvent,
+  ThinkingEvent,
+  ToolCallEvent,
+  ToolResultEvent,
+  DoneEvent,
+  ErrorEvent,
+  AbortedEvent,
+  ContinuationEvent,
+
+  // Schemas (Zod validators)
+  AgentRequestSchema,
+  AgentEventSchema,
+  // ... all event schemas
+
+  // SSE utilities
+  encodeSSE,
+  parseSSEChunk,
+  ParsedEvent,
+  ParseResult,
+
+  // Constants
+  PROTOCOL_VERSION,
+  EVENT_TYPES,
+} from '@machinemetrics/agent-event-protocol';
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build       # Build the package (ESM + CJS)
+pnpm test        # Run tests
+pnpm typecheck   # Type check
+```

package/dist/chunk-RSG7CUUT.js

@@ -0,0 +1,220 @@
+import {
+  AgentEventSchema
+} from "./chunk-WZD2VBMM.js";
+
+// src/sse/encode.ts
+function encodeSSE(event, data) {
+  return `event: ${event}
+data: ${JSON.stringify(data)}
+
+`;
+}
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest;
+  describe("encodeSSE", () => {
+    it("formats SSE event correctly", () => {
+      const result = encodeSSE("metadata", {
+        event: "metadata",
+        requestId: "req-1",
+        threadId: "th-1",
+        agentId: "test-agent",
+        timestamp: "2025-01-01T00:00:00.000Z"
+      });
+      expect(result).toBe(
+        'event: metadata\ndata: {"event":"metadata","requestId":"req-1","threadId":"th-1","agentId":"test-agent","timestamp":"2025-01-01T00:00:00.000Z"}\n\n'
+      );
+    });
+    it("handles special characters in data", () => {
+      const result = encodeSSE("text", {
+        event: "text",
+        requestId: "req-1",
+        messageId: "msg-1",
+        blockId: "b1",
+        stage: "delta",
+        delta: "Hello\nWorld",
+        deltaIndex: 0,
+        timestamp: "2025-01-01T00:00:00.000Z"
+      });
+      expect(result).toContain("Hello\\nWorld");
+      expect(result).toMatch(/^event: text\ndata: .+\n\n$/);
+    });
+    it("handles unicode characters", () => {
+      const result = encodeSSE("text", {
+        event: "text",
+        requestId: "req-1",
+        messageId: "msg-1",
+        blockId: "b1",
+        stage: "delta",
+        delta: "\u4F60\u597D\u4E16\u754C \u{1F30D}",
+        deltaIndex: 0,
+        timestamp: "2025-01-01T00:00:00.000Z"
+      });
+      expect(result).toContain("\u4F60\u597D\u4E16\u754C \u{1F30D}");
+    });
+    it("handles empty object data", () => {
+      const result = encodeSSE("custom", {});
+      expect(result).toBe("event: custom\ndata: {}\n\n");
+    });
+  });
+}
+
+// src/sse/parse.ts
+function parseSSEChunk(chunk) {
+  const events = [];
+  const blocks = chunk.split("\n\n");
+  for (let i = 0; i < blocks.length - 1; i++) {
+    const block = blocks[i];
+    const parsed = parseBlock(block);
+    if (parsed !== null) {
+      events.push(parsed);
+    }
+  }
+  const lastBlock = blocks[blocks.length - 1] ?? "";
+  const remainder = lastBlock;
+  return { events, remainder };
+}
+function parseBlock(block) {
+  const lines = block.split("\n");
+  let eventType = null;
+  let data = null;
+  for (const line of lines) {
+    if (line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event: ")) {
+      eventType = line.slice(7);
+      continue;
+    }
+    if (line.startsWith("data: ")) {
+      data = line.slice(6);
+      continue;
+    }
+  }
+  if (data === null) {
+    return null;
+  }
+  return parseAndValidate(data, eventType);
+}
+function parseAndValidate(data, eventType) {
+  let parsed;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return { success: false, error: "Invalid JSON", raw: data };
+  }
+  const result = AgentEventSchema.safeParse(parsed);
+  if (result.success) {
+    if (eventType !== null && result.data.event !== eventType) {
+      return {
+        success: false,
+        error: `Event type mismatch: header says '${eventType}', data says '${result.data.event}'`,
+        raw: parsed
+      };
+    }
+    return { success: true, event: result.data };
+  }
+  return {
+    success: false,
+    error: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+    raw: parsed
+  };
+}
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest;
+  describe("parseSSEChunk", () => {
+    it("parses a single complete event", () => {
+      const chunk = 'event: metadata\ndata: {"event":"metadata","requestId":"req-1","threadId":"th-1","agentId":"test-agent","timestamp":"2025-01-01T00:00:00.000Z"}\n\n';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      expect(result.events[0]?.success).toBe(true);
+      if (result.events[0]?.success) {
+        expect(result.events[0].event.event).toBe("metadata");
+        expect(result.events[0].event.requestId).toBe("req-1");
+      }
+      expect(result.remainder).toBe("");
+    });
+    it("parses multiple events in one chunk", () => {
+      const chunk = 'event: text\ndata: {"event":"text","requestId":"req-1","messageId":"msg-1","blockId":"b1","stage":"start","blockIndex":0,"timestamp":"2025-01-01T00:00:00.000Z"}\n\nevent: text\ndata: {"event":"text","requestId":"req-1","messageId":"msg-1","blockId":"b1","stage":"delta","delta":"Hello","deltaIndex":0,"timestamp":"2025-01-01T00:00:00.001Z"}\n\n';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(2);
+      expect(result.events[0]?.success).toBe(true);
+      expect(result.events[1]?.success).toBe(true);
+      if (result.events[0]?.success && result.events[1]?.success) {
+        expect(result.events[0].event.event).toBe("text");
+        expect(result.events[1].event.event).toBe("text");
+      }
+      expect(result.remainder).toBe("");
+    });
+    it("returns remainder for partial event", () => {
+      const chunk = 'event: metadata\ndata: {"event":"metadata","requestId":"req-1","threadId":"th-1","agentId":"test-agent","timestamp":"2025-01-01T00:00:00.000Z"}\n\nevent: text\ndata: {"event":"text","request';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      expect(result.events[0]?.success).toBe(true);
+      expect(result.remainder).toContain("event: text");
+      expect(result.remainder).toContain('data: {"event":"text","request');
+    });
+    it("ignores SSE comments", () => {
+      const chunk = ': heartbeat\nevent: metadata\ndata: {"event":"metadata","requestId":"req-1","threadId":"th-1","agentId":"test-agent","timestamp":"2025-01-01T00:00:00.000Z"}\n\n';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      expect(result.events[0]?.success).toBe(true);
+    });
+    it("returns error for invalid JSON", () => {
+      const chunk = "event: text\ndata: {invalid json}\n\n";
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      const event = result.events[0];
+      expect(event.success).toBe(false);
+      if (!event.success) {
+        expect(event.error).toBe("Invalid JSON");
+      }
+    });
+    it("returns error for invalid event schema", () => {
+      const chunk = 'event: text\ndata: {"event":"text","invalidField":"value"}\n\n';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      const event = result.events[0];
+      expect(event.success).toBe(false);
+      if (!event.success) {
+        expect(event.error).toContain("requestId");
+      }
+    });
+    it("returns error for event type mismatch", () => {
+      const chunk = 'event: metadata\ndata: {"event":"text","requestId":"req-1","messageId":"msg-1","blockId":"b1","stage":"start","blockIndex":0,"timestamp":"2025-01-01T00:00:00.000Z"}\n\n';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      const event = result.events[0];
+      expect(event.success).toBe(false);
+      if (!event.success) {
+        expect(event.error).toContain("mismatch");
+      }
+    });
+    it("handles data without event line", () => {
+      const chunk = 'data: {"event":"metadata","requestId":"req-1","threadId":"th-1","agentId":"test-agent","timestamp":"2025-01-01T00:00:00.000Z"}\n\n';
+      const result = parseSSEChunk(chunk);
+      expect(result.events).toHaveLength(1);
+      expect(result.events[0]?.success).toBe(true);
+    });
+    it("handles empty chunk", () => {
+      const result = parseSSEChunk("");
+      expect(result.events).toHaveLength(0);
+      expect(result.remainder).toBe("");
+    });
+    it("buffers partial chunks correctly across calls", () => {
+      const part1 = 'event: text\ndata: {"event":"text","requestId":"req-1",';
+      const part2 = '"messageId":"msg-1","blockId":"b1","stage":"start","blockIndex":0,"timestamp":"2025-01-01T00:00:00.000Z"}\n\n';
+      const result1 = parseSSEChunk(part1);
+      expect(result1.events).toHaveLength(0);
+      expect(result1.remainder).not.toBe("");
+      const result2 = parseSSEChunk(result1.remainder + part2);
+      expect(result2.events).toHaveLength(1);
+      expect(result2.events[0]?.success).toBe(true);
+    });
+  });
+}
+
+export {
+  encodeSSE,
+  parseSSEChunk
+};
+//# sourceMappingURL=chunk-RSG7CUUT.js.map

package/dist/chunk-RSG7CUUT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sse/encode.ts","../src/sse/parse.ts"],"sourcesContent":["/**\n * Encodes an event and data payload into SSE wire format.\n *\n * Output format: `event: {event}\\ndata: {json}\\n\\n`\n *\n * The data object is JSON serialized. Newlines in string values are escaped\n * by JSON.stringify, ensuring valid SSE format.\n *\n * @param event - Event type identifier (e.g., 'text', 'done', 'error')\n * @param data - Event payload object to serialize as JSON\n * @returns SSE-formatted string ready for streaming\n */\nexport function encodeSSE(event: string, data: object): string {\n  return `event: ${event}\\ndata: ${JSON.stringify(data)}\\n\\n`;\n}\n\nif (import.meta.vitest) {\n  const { describe, it, expect } = import.meta.vitest;\n\n  describe('encodeSSE', () => {\n    it('formats SSE event correctly', () => {\n      const result = encodeSSE('metadata', {\n        event: 'metadata',\n        requestId: 'req-1',\n        threadId: 'th-1',\n        agentId: 'test-agent',\n        timestamp: '2025-01-01T00:00:00.000Z',\n      });\n\n      expect(result).toBe(\n        'event: metadata\\n' +\n          'data: {\"event\":\"metadata\",\"requestId\":\"req-1\",\"threadId\":\"th-1\",\"agentId\":\"test-agent\",\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n',\n      );\n    });\n\n    it('handles special characters in data', () => {\n      const result = encodeSSE('text', {\n        event: 'text',\n        requestId: 'req-1',\n        messageId: 'msg-1',\n        blockId: 'b1',\n        stage: 'delta',\n        delta: 'Hello\\nWorld',\n        deltaIndex: 0,\n        timestamp: '2025-01-01T00:00:00.000Z',\n      });\n\n      expect(result).toContain('Hello\\\\nWorld');\n      expect(result).toMatch(/^event: text\\ndata: .+\\n\\n$/);\n    });\n\n    it('handles unicode characters', () => {\n      const result = encodeSSE('text', {\n        event: 'text',\n        requestId: 'req-1',\n        messageId: 'msg-1',\n        blockId: 'b1',\n        stage: 'delta',\n        delta: '你好世界 🌍',\n        deltaIndex: 0,\n        timestamp: '2025-01-01T00:00:00.000Z',\n      });\n\n      expect(result).toContain('你好世界 🌍');\n    });\n\n    it('handles empty object data', () => {\n      const result = encodeSSE('custom', {});\n      expect(result).toBe('event: custom\\ndata: {}\\n\\n');\n    });\n  });\n}\n","import { AgentEventSchema } from '../core/schemas.js';\nimport type { AgentEvent } from '../core/types.js';\n\n/**\n * Result of parsing a single SSE event.\n * On success, contains a validated AgentEvent.\n * On failure, contains the error message and the raw parsed data.\n */\nexport type ParsedEvent =\n  | { success: true; event: AgentEvent }\n  | { success: false; error: string; raw: unknown };\n\n/**\n * Result of parsing an SSE chunk.\n * Contains successfully parsed events and any incomplete data to buffer for the next chunk.\n */\nexport type ParseResult = {\n  /** Array of parsed events (may include failures with error details). */\n  events: ParsedEvent[];\n  /** Incomplete data at end of chunk; prepend to next chunk before parsing. */\n  remainder: string;\n};\n\n/**\n * Parses an SSE chunk into validated protocol events.\n *\n * Handles partial chunks by returning unparsed data as remainder.\n * The remainder should be prepended to the next chunk before parsing.\n *\n * Each SSE block is validated against AgentEventSchema. Invalid events\n * are returned with success: false and error details.\n *\n * SSE comments (lines starting with ':') are ignored, including heartbeats.\n *\n * @param chunk - Raw SSE data (may contain multiple events or partial data)\n * @returns Object with parsed events array and remainder string for buffering\n */\nexport function parseSSEChunk(chunk: string): ParseResult {\n  const events: ParsedEvent[] = [];\n  const blocks = chunk.split('\\n\\n');\n\n  for (let i = 0; i < blocks.length - 1; i++) {\n    const block = blocks[i]!;\n    const parsed = parseBlock(block);\n    if (parsed !== null) {\n      events.push(parsed);\n    }\n  }\n\n  const lastBlock = blocks[blocks.length - 1] ?? '';\n  const remainder = lastBlock;\n\n  return { events, remainder };\n}\n\n/**\n * Parses a single SSE block into a ParsedEvent.\n * Returns null for blocks without data (e.g., comment-only blocks).\n */\nfunction parseBlock(block: string): ParsedEvent | null {\n  const lines = block.split('\\n');\n  let eventType: string | null = null;\n  let data: string | null = null;\n\n  for (const line of lines) {\n    if (line.startsWith(':')) {\n      continue;\n    }\n    if (line.startsWith('event: ')) {\n      eventType = line.slice(7);\n      continue;\n    }\n    if (line.startsWith('data: ')) {\n      data = line.slice(6);\n      continue;\n    }\n  }\n\n  if (data === null) {\n    return null;\n  }\n\n  return parseAndValidate(data, eventType);\n}\n\n/**\n * Parses JSON data and validates against AgentEventSchema.\n * Checks that the event type in data matches the SSE event header if present.\n */\nfunction parseAndValidate(data: string, eventType: string | null): ParsedEvent {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(data);\n  } catch {\n    return { success: false, error: 'Invalid JSON', raw: data };\n  }\n\n  const result = AgentEventSchema.safeParse(parsed);\n  if (result.success) {\n    if (eventType !== null && result.data.event !== eventType) {\n      return {\n        success: false,\n        error: `Event type mismatch: header says '${eventType}', data says '${result.data.event}'`,\n        raw: parsed,\n      };\n    }\n    return { success: true, event: result.data };\n  }\n\n  return {\n    success: false,\n    error: result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '),\n    raw: parsed,\n  };\n}\n\nif (import.meta.vitest) {\n  const { describe, it, expect } = import.meta.vitest;\n\n  describe('parseSSEChunk', () => {\n    it('parses a single complete event', () => {\n      const chunk =\n        'event: metadata\\n' +\n        'data: {\"event\":\"metadata\",\"requestId\":\"req-1\",\"threadId\":\"th-1\",\"agentId\":\"test-agent\",\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      expect(result.events[0]?.success).toBe(true);\n      if (result.events[0]?.success) {\n        expect(result.events[0].event.event).toBe('metadata');\n        expect(result.events[0].event.requestId).toBe('req-1');\n      }\n      expect(result.remainder).toBe('');\n    });\n\n    it('parses multiple events in one chunk', () => {\n      const chunk =\n        'event: text\\n' +\n        'data: {\"event\":\"text\",\"requestId\":\"req-1\",\"messageId\":\"msg-1\",\"blockId\":\"b1\",\"stage\":\"start\",\"blockIndex\":0,\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n' +\n        'event: text\\n' +\n        'data: {\"event\":\"text\",\"requestId\":\"req-1\",\"messageId\":\"msg-1\",\"blockId\":\"b1\",\"stage\":\"delta\",\"delta\":\"Hello\",\"deltaIndex\":0,\"timestamp\":\"2025-01-01T00:00:00.001Z\"}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(2);\n      expect(result.events[0]?.success).toBe(true);\n      expect(result.events[1]?.success).toBe(true);\n      if (result.events[0]?.success && result.events[1]?.success) {\n        expect(result.events[0].event.event).toBe('text');\n        expect(result.events[1].event.event).toBe('text');\n      }\n      expect(result.remainder).toBe('');\n    });\n\n    it('returns remainder for partial event', () => {\n      const chunk =\n        'event: metadata\\n' +\n        'data: {\"event\":\"metadata\",\"requestId\":\"req-1\",\"threadId\":\"th-1\",\"agentId\":\"test-agent\",\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n' +\n        'event: text\\n' +\n        'data: {\"event\":\"text\",\"request';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      expect(result.events[0]?.success).toBe(true);\n      expect(result.remainder).toContain('event: text');\n      expect(result.remainder).toContain('data: {\"event\":\"text\",\"request');\n    });\n\n    it('ignores SSE comments', () => {\n      const chunk =\n        ': heartbeat\\n' +\n        'event: metadata\\n' +\n        'data: {\"event\":\"metadata\",\"requestId\":\"req-1\",\"threadId\":\"th-1\",\"agentId\":\"test-agent\",\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      expect(result.events[0]?.success).toBe(true);\n    });\n\n    it('returns error for invalid JSON', () => {\n      const chunk = 'event: text\\n' + 'data: {invalid json}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      const event = result.events[0]!;\n      expect(event.success).toBe(false);\n      if (!event.success) {\n        expect(event.error).toBe('Invalid JSON');\n      }\n    });\n\n    it('returns error for invalid event schema', () => {\n      const chunk = 'event: text\\n' + 'data: {\"event\":\"text\",\"invalidField\":\"value\"}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      const event = result.events[0]!;\n      expect(event.success).toBe(false);\n      if (!event.success) {\n        expect(event.error).toContain('requestId');\n      }\n    });\n\n    it('returns error for event type mismatch', () => {\n      const chunk =\n        'event: metadata\\n' +\n        'data: {\"event\":\"text\",\"requestId\":\"req-1\",\"messageId\":\"msg-1\",\"blockId\":\"b1\",\"stage\":\"start\",\"blockIndex\":0,\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      const event = result.events[0]!;\n      expect(event.success).toBe(false);\n      if (!event.success) {\n        expect(event.error).toContain('mismatch');\n      }\n    });\n\n    it('handles data without event line', () => {\n      const chunk =\n        'data: {\"event\":\"metadata\",\"requestId\":\"req-1\",\"threadId\":\"th-1\",\"agentId\":\"test-agent\",\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n';\n\n      const result = parseSSEChunk(chunk);\n\n      expect(result.events).toHaveLength(1);\n      expect(result.events[0]?.success).toBe(true);\n    });\n\n    it('handles empty chunk', () => {\n      const result = parseSSEChunk('');\n      expect(result.events).toHaveLength(0);\n      expect(result.remainder).toBe('');\n    });\n\n    it('buffers partial chunks correctly across calls', () => {\n      const part1 = 'event: text\\ndata: {\"event\":\"text\",\"requestId\":\"req-1\",';\n      const part2 =\n        '\"messageId\":\"msg-1\",\"blockId\":\"b1\",\"stage\":\"start\",\"blockIndex\":0,\"timestamp\":\"2025-01-01T00:00:00.000Z\"}\\n\\n';\n\n      const result1 = parseSSEChunk(part1);\n      expect(result1.events).toHaveLength(0);\n      expect(result1.remainder).not.toBe('');\n\n      const result2 = parseSSEChunk(result1.remainder + part2);\n      expect(result2.events).toHaveLength(1);\n      expect(result2.events[0]?.success).toBe(true);\n    });\n  });\n}\n"],"mappings":"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","names":[]}