{"_id":"@aevatar/kit-protocol","_rev":"5-a96792b4f8ba225c10dac2b6990a41e9","name":"@aevatar/kit-protocol","dist-tags":{"latest":"1.2.1"},"versions":{"0.3.0":{"name":"@aevatar/kit-protocol","version":"0.3.0","keywords":["aevatar","ag-ui","protocol","sse","streaming"],"_id":"@aevatar/kit-protocol@0.3.0","maintainers":[{"name":"potterf","email":"potter.sun@aelf.io"}],"homepage":"https://github.com/aevatar/aevatarkit-ui#readme","bugs":{"url":"https://github.com/aevatar/aevatarkit-ui/issues"},"dist":{"shasum":"6ce2ef8f8576642f16349d246aeba5357694279c","tarball":"https://registry.npmjs.org/@aevatar/kit-protocol/-/kit-protocol-0.3.0.tgz","fileCount":9,"integrity":"sha512-f6l9EpWoDp2NWRp6Kfj6dTS6ZDFm87GKmAVmoLYY1DuA4CCU2lxGbB5QyqZPAip2HVCgiv/vOx2aRLveoyVvCw==","signatures":[{"sig":"MEQCIEoL0dZq/jUEnucC9HRO1SRLEogZXjra0rHjiJtxDodGAiBegjZx36SDYHSl+q9eTP/6VMMYSKGtMGU0bDjxsP4Xng==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":141484},"main":"./dist/index.js","_from":"file:aevatar-kit-protocol-0.3.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"potterf","email":"potter.sun@aelf.io"},"_resolved":"/private/var/folders/d9/bmbzh5n14v7byzn_zznk3gr80000gn/T/75541d6bb1034bf8fd486a97479e97bb/aevatar-kit-protocol-0.3.0.tgz","_integrity":"sha512-f6l9EpWoDp2NWRp6Kfj6dTS6ZDFm87GKmAVmoLYY1DuA4CCU2lxGbB5QyqZPAip2HVCgiv/vOx2aRLveoyVvCw==","repository":{"url":"git+https://github.com/aevatar/aevatarkit-ui.git","type":"git","directory":"packages/kit-protocol"},"_npmVersion":"10.7.0","description":"AG-UI Protocol implementation for AevatarKit SDK","directories":{},"_nodeVersion":"18.20.3","dependencies":{"@aevatar/kit-types":"0.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/kit-protocol_0.3.0_1767687868978_0.02853767124685458","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aevatar/kit-protocol","version":"1.0.0","keywords":["aevatar","ag-ui","protocol","sse","streaming"],"_id":"@aevatar/kit-protocol@1.0.0","maintainers":[{"name":"potterf","email":"potter.sun@aelf.io"}],"homepage":"https://github.com/aevatar/aevatarkit-ui#readme","bugs":{"url":"https://github.com/aevatar/aevatarkit-ui/issues"},"dist":{"shasum":"42186a08ded8418a69e1ca316f3801910978b14c","tarball":"https://registry.npmjs.org/@aevatar/kit-protocol/-/kit-protocol-1.0.0.tgz","fileCount":9,"integrity":"sha512-Ih7cQAUgXUl5nMZNhgYllEMlNBbqbAtm9iXMeNGEet90S169m/4nw8RYoPhgUShWPhV15o+PqNn0KcclRbSKqg==","signatures":[{"sig":"MEUCIG9QPI7204VQz6RGd98Y/5m8exsH5/eRI0mARFRV5qG6AiEA7W9FPhuer+Iei+uTQC4m80h1VuZ71mpvAkjlYZz6Abc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":143178},"main":"./dist/index.js","_from":"file:aevatar-kit-protocol-1.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"potterf","email":"potter.sun@aelf.io"},"_resolved":"/private/var/folders/d9/bmbzh5n14v7byzn_zznk3gr80000gn/T/763c7ae55eb544c01a8ae1ee554eb5e2/aevatar-kit-protocol-1.0.0.tgz","_integrity":"sha512-Ih7cQAUgXUl5nMZNhgYllEMlNBbqbAtm9iXMeNGEet90S169m/4nw8RYoPhgUShWPhV15o+PqNn0KcclRbSKqg==","repository":{"url":"git+https://github.com/aevatar/aevatarkit-ui.git","type":"git","directory":"packages/kit-protocol"},"_npmVersion":"10.7.0","description":"AG-UI Protocol implementation for AevatarKit SDK","directories":{},"_nodeVersion":"18.20.3","dependencies":{"@aevatar/kit-types":"0.3.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/kit-protocol_1.0.0_1767757709897_0.2967524384250191","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aevatar/kit-protocol","version":"1.1.0","keywords":["aevatar","ag-ui","protocol","sse","streaming"],"_id":"@aevatar/kit-protocol@1.1.0","maintainers":[{"name":"potterf","email":"potter.sun@aelf.io"}],"homepage":"https://github.com/aevatar/aevatarkit-ui#readme","bugs":{"url":"https://github.com/aevatar/aevatarkit-ui/issues"},"dist":{"shasum":"688d3152b8f454a28eaf2f3dbb69f8a641dfdbf3","tarball":"https://registry.npmjs.org/@aevatar/kit-protocol/-/kit-protocol-1.1.0.tgz","fileCount":9,"integrity":"sha512-vWA/JswYfo+wYDBUPDcy24YdE9bCkzzamzBV7u7SVMo8WKobFLqD6cDywMvzrqLG5j/yjgRA94iHvGqARbJzkQ==","signatures":[{"sig":"MEUCIQD1frWvfFZB3qMEklEvk3oT385FeOe3sPwGNHFhDyIkRAIgTY7jzfxXuaP3GCq6Looevl+cWTP1yZmiGMxlXZfSPt4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":143178},"main":"./dist/index.js","_from":"file:aevatar-kit-protocol-1.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"potterf","email":"potter.sun@aelf.io"},"_resolved":"/private/var/folders/d9/bmbzh5n14v7byzn_zznk3gr80000gn/T/3ed7e9b2767f6d87599fdccbb53f8835/aevatar-kit-protocol-1.1.0.tgz","_integrity":"sha512-vWA/JswYfo+wYDBUPDcy24YdE9bCkzzamzBV7u7SVMo8WKobFLqD6cDywMvzrqLG5j/yjgRA94iHvGqARbJzkQ==","repository":{"url":"git+https://github.com/aevatar/aevatarkit-ui.git","type":"git","directory":"packages/kit-protocol"},"_npmVersion":"10.7.0","description":"AG-UI Protocol implementation for AevatarKit SDK","directories":{},"_nodeVersion":"18.20.3","dependencies":{"@aevatar/kit-types":"1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/kit-protocol_1.1.0_1767769288141_0.005507009390198547","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@aevatar/kit-protocol","version":"1.2.0","keywords":["aevatar","ag-ui","protocol","sse","streaming"],"_id":"@aevatar/kit-protocol@1.2.0","maintainers":[{"name":"potterf","email":"potter.sun@aelf.io"}],"homepage":"https://github.com/aevatar/aevatarkit-ui#readme","bugs":{"url":"https://github.com/aevatar/aevatarkit-ui/issues"},"dist":{"shasum":"9b652d640bcee03fc94194ba645b0e513c031209","tarball":"https://registry.npmjs.org/@aevatar/kit-protocol/-/kit-protocol-1.2.0.tgz","fileCount":9,"integrity":"sha512-KYAjw+6XOsQKewHDpPq7fGUiMx5Qo/+99eLtjV0/Pv1SWi36PR6FuV6czZzLNL/zz4OOs6mRP1l/r5qh4Ufg5A==","signatures":[{"sig":"MEUCIQDlOonsCf6pnzMrKn2IxfTXkKnxWHrv47Rwgj7/2w7NuQIgCNcGKr4aAtFJlCABZPqy73YQBAaHEO8EchUMMLioLKk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":262831},"main":"./dist/index.js","_from":"file:aevatar-kit-protocol-1.2.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"potterf","email":"potter.sun@aelf.io"},"_resolved":"/private/var/folders/d9/bmbzh5n14v7byzn_zznk3gr80000gn/T/445f8df5eb6ec28e4c3868859939c323/aevatar-kit-protocol-1.2.0.tgz","_integrity":"sha512-KYAjw+6XOsQKewHDpPq7fGUiMx5Qo/+99eLtjV0/Pv1SWi36PR6FuV6czZzLNL/zz4OOs6mRP1l/r5qh4Ufg5A==","repository":{"url":"git+https://github.com/aevatar/aevatarkit-ui.git","type":"git","directory":"packages/kit-protocol"},"_npmVersion":"10.7.0","description":"AG-UI Protocol implementation for AevatarKit SDK","directories":{},"_nodeVersion":"18.20.3","dependencies":{"@aevatar/kit-types":"1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.0.0","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/kit-protocol_1.2.0_1768204662717_0.8868473851280583","host":"s3://npm-registry-packages-npm-production"}},"1.2.1":{"name":"@aevatar/kit-protocol","version":"1.2.1","description":"AG-UI Protocol implementation for AevatarKit SDK","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"dependencies":{"@aevatar/kit-types":"1.2.1"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^1.0.0"},"repository":{"type":"git","url":"git+https://github.com/aevatar/aevatarkit-ui.git","directory":"packages/kit-protocol"},"homepage":"https://github.com/aevatar/aevatarkit-ui#readme","publishConfig":{"access":"public"},"keywords":["aevatar","ag-ui","protocol","sse","streaming"],"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","clean":"rm -rf dist","test":"vitest"},"_id":"@aevatar/kit-protocol@1.2.1","bugs":{"url":"https://github.com/aevatar/aevatarkit-ui/issues"},"_integrity":"sha512-k2r2nc6JdEqI99gRDJvdhC9fM0C7xQg0GO/hh60hKYMVLB/FmEtaxkMM54Vx3GL2b0xuNdaKQI+139NMhvpDiw==","_resolved":"/private/var/folders/d9/bmbzh5n14v7byzn_zznk3gr80000gn/T/be0d0a2e425ea6b19076aa823f61a67b/aevatar-kit-protocol-1.2.1.tgz","_from":"file:aevatar-kit-protocol-1.2.1.tgz","_nodeVersion":"18.20.3","_npmVersion":"10.7.0","dist":{"integrity":"sha512-k2r2nc6JdEqI99gRDJvdhC9fM0C7xQg0GO/hh60hKYMVLB/FmEtaxkMM54Vx3GL2b0xuNdaKQI+139NMhvpDiw==","shasum":"530919de6db7e9ec625c0c6ec2157b155a280412","tarball":"https://registry.npmjs.org/@aevatar/kit-protocol/-/kit-protocol-1.2.1.tgz","fileCount":9,"unpackedSize":433356,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA+Auv1Mg+Sp+HRK2t+o2/lOrBwTR3f0ryldZksojKY3AiBEF9pyW/GDCCBl9mKnKktYYpKQhOuGgDNkougHJk3Vsg=="}]},"_npmUser":{"name":"potterf","email":"potter.sun@aelf.io"},"directories":{},"maintainers":[{"name":"potterf","email":"potter.sun@aelf.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kit-protocol_1.2.1_1768983991983_0.17123099343707282"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-06T08:24:28.892Z","modified":"2026-01-21T08:26:32.297Z","0.3.0":"2026-01-06T08:24:29.145Z","1.0.0":"2026-01-07T03:48:30.033Z","1.1.0":"2026-01-07T07:01:28.290Z","1.2.0":"2026-01-12T07:57:42.858Z","1.2.1":"2026-01-21T08:26:32.137Z"},"bugs":{"url":"https://github.com/aevatar/aevatarkit-ui/issues"},"homepage":"https://github.com/aevatar/aevatarkit-ui#readme","keywords":["aevatar","ag-ui","protocol","sse","streaming"],"repository":{"type":"git","url":"git+https://github.com/aevatar/aevatarkit-ui.git","directory":"packages/kit-protocol"},"description":"AG-UI Protocol implementation for AevatarKit SDK","maintainers":[{"name":"potterf","email":"potter.sun@aelf.io"}],"readme":"# @aevatar/kit-protocol\n\n**AG-UI Protocol Implementation - Pure protocol layer, zero business assumptions**\n\n## Philosophy\n\nThis package is **protocol-only**. It does not:\n\n- ❌ Assume any REST API endpoint format\n- ❌ Manage sessions or runs (that's your business logic)\n- ❌ Provide UI components (that's your design)\n- ❌ Make HTTP requests (you handle that)\n\nIt only:\n\n- ✅ Implements AG-UI protocol (SSE parsing, event routing)\n- ✅ Provides typed event stream with rich callbacks\n- ✅ Handles connection management with metrics\n- ✅ JSON Patch (RFC 6902) for STATE_DELTA\n- ✅ Message buffer for TEXT_MESSAGE_* aggregation\n- ✅ Supports Aevatar extensions (optional)\n\n## Installation\n\n```bash\npnpm add @aevatar/kit-protocol @aevatar/kit-types\n```\n\n## Quick Start\n\n### Vanilla TypeScript\n\n```ts\nimport { createEventStream } from '@aevatar/kit-protocol';\n\nconst stream = createEventStream({\n  url: 'http://localhost:5000/api/sessions/abc/events',\n  autoReconnect: true,\n  onReconnecting: (attempt, max, delay) => {\n    console.log(`Reconnecting ${attempt}/${max} in ${delay}ms`);\n  },\n  onReconnectFailed: () => {\n    console.error('Connection lost permanently');\n  },\n});\n\nstream.on('TEXT_MESSAGE_CONTENT', (e) => console.log(e.delta));\nstream.on('RUN_FINISHED', (e) => stream.disconnect());\n\nstream.connect();\n```\n\n### Type-Safe Custom Events\n\n```ts\nimport { createEventStream } from '@aevatar/kit-protocol';\n\n// Define your custom event types\ninterface MyEvents {\n  'worker.update': { id: string; status: string };\n  'task.complete': { taskId: string; result: unknown };\n}\n\n// Create a type-safe stream\nconst stream = createEventStream<MyEvents>({\n  url: '/api/events',\n});\n\n// event.value is typed as { id: string; status: string }\nstream.onCustom('worker.update', (event) => {\n  console.log(event.value.id, event.value.status);\n});\n\nstream.connect();\n```\n\n### Batch Event Registration\n\n```ts\nimport { createEventStream } from '@aevatar/kit-protocol';\n\n    const stream = createEventStream({\n  url: '/api/events',\n  router: {\n    standard: {\n      RUN_STARTED: () => console.log('Started'),\n      RUN_FINISHED: () => console.log('Finished'),\n      TEXT_MESSAGE_CONTENT: (e) => console.log(e.delta),\n    },\n    custom: {\n      'app.progress': (e) => console.log('Progress:', e.value),\n    },\n  },\n    });\n\n    stream.connect();\n```\n\n### Message Aggregation\n\n```ts\nimport { createEventRouter, bindMessageAggregation } from '@aevatar/kit-protocol';\n\nconst router = createEventRouter();\n\nconst { buffer, unsubscribe } = bindMessageAggregation(router, {\n  onMessageStart: (id) => console.log('Started:', id),\n  onMessageChunk: (id, content) => updateUI(content),\n  onMessageComplete: (id, content) => saveMessage(content),\n});\n\n// Route events (from your SSE connection)\nrouter.route(event);\n```\n\n### JSON Patch for State Updates\n\n```ts\nimport { applyJsonPatch } from '@aevatar/kit-protocol';\n\nconst state = { count: 0, items: [] };\n\nstream.on('STATE_DELTA', (event) => {\n  const newState = applyJsonPatch(state, event.delta);\n  console.log('New state:', newState);\n});\n```\n\n## API Reference\n\n### `createEventStream(options)`\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `url` | `string` | - | SSE endpoint URL |\n| `autoReconnect` | `boolean` | `true` | Auto reconnect on disconnect |\n| `reconnectDelayMs` | `number` | `1000` | Initial reconnect delay |\n| `maxReconnectAttempts` | `number` | `10` | Max reconnect attempts |\n| `onStatusChange` | `(status) => void` | - | Status change callback |\n| `onError` | `(error, context) => void` | - | Error with context |\n| `onReconnecting` | `(attempt, max, delay) => void` | - | Reconnection attempt |\n| `onReconnectFailed` | `(context) => void` | - | All attempts failed |\n| `onReconnected` | `() => void` | - | Successfully reconnected |\n| `router` | `EventRouterOptions` | - | Batch event registration |\n\n**Methods:**\n\n```ts\nstream.connect()      // Connect to SSE\nstream.disconnect()   // Disconnect\nstream.reconnect()    // Force reconnect\nstream.on(type, fn)   // Subscribe to event type\nstream.onCustom(name, fn)   // Subscribe to CUSTOM by name\nstream.onAevatar(name, fn)  // Subscribe to Aevatar events\nstream.onAny(fn)      // Subscribe to all events\nstream.getMetrics()   // Get connection metrics\nstream.getRouter()    // Get underlying router\n```\n\n### `createEventRouter<T>(options?)`\n\nType-safe event router with batch registration.\n\n```ts\nconst router = createEventRouter<MyCustomEvents>({\n  standard: { RUN_STARTED: (e) => {} },\n  custom: { 'my.event': (e) => {} },\n});\n\n// Later: batch register more\nconst unsub = router.registerStandard({\n  RUN_FINISHED: (e) => {},\n});\n```\n\n### `applyJsonPatch(target, operations)`\n\nApply RFC 6902 JSON Patch operations (immutable).\n\n```ts\nconst result = applyJsonPatch(obj, [\n  { op: 'replace', path: '/count', value: 1 },\n  { op: 'add', path: '/items/-', value: 'new' },\n]);\n```\n\n### `createMessageBuffer()`\n\nLow-level message buffer for manual control.\n\n```ts\nconst buffer = createMessageBuffer();\nbuffer.start('msg-1');\nbuffer.append('msg-1', 'chunk');\nconst final = buffer.end('msg-1');\n```\n\n### `bindMessageAggregation(router, callbacks)`\n\nAuto-bind TEXT_MESSAGE_* events to callbacks.\n\n```ts\nconst { buffer, unsubscribe } = bindMessageAggregation(router, {\n  onMessageStart: (id) => {},\n  onMessageChunk: (id, accumulated, delta) => {},\n  onMessageComplete: (id, fullContent) => {},\n});\n```\n\n## Design Philosophy\n\n### Why no session/run management?\n\nDifferent backends have different:\n- API endpoints (`/runs` vs `/run`)\n- Request formats (`{ message }` vs `{ axioms, goal }`)\n- Authentication mechanisms\n\nThe protocol layer shouldn't know about these.\n\n### Why type-safe custom events?\n\nBusiness applications need to extend AG-UI with domain events. Type safety catches errors at compile time rather than runtime.\n\n### Why separate JSON Patch utility?\n\nSTATE_DELTA events use RFC 6902. Providing a correct implementation avoids every consumer re-implementing it.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}