{"_id":"@codehz/conversation","_rev":"7-e9788c8a6d7823c9ce2a1f59c19919d9","name":"@codehz/conversation","dist-tags":{"latest":"0.2.4"},"versions":{"0.0.0":{"name":"@codehz/conversation","version":"0.0.0","_id":"@codehz/conversation@0.0.0","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"dist":{"shasum":"8c36d7ea7603a17911b559a18dba05951baf2b4d","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.0.0.tgz","fileCount":18,"integrity":"sha512-uYissGbqXAeg+nV8lJGVb22OYsZzSSGT99MNiCARDPKgaA97WPgGMiv7FzTmEGYEnMPxZnVwKlhrU7YJf2F3dA==","signatures":[{"sig":"MEYCIQDRxRh3iIcJ+MdiZDKmMdvvZqnML05pVoW63f243upG9AIhAPFkcmRKFv0QjSnccmwWmDVAVpxrX3QNciDlFHfYf4gN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":174559},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./package.json":"./package.json"},"gitHead":"530b64f10ec4d7cbca53064df3e9685e677ae051","scripts":{"lint":"oxlint","test":"bun test","build":"tsdown","format":"oxfmt --write","prepare":"husky","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","build:watch":"tsdown --watch","format:check":"oxfmt --check","test:coverage":"bun test --coverage","prepublishOnly":"tsdown"},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"_npmVersion":"11.16.0","description":"Event-sourced conversation engine with a Bun WebSocket server and React client hooks.","directories":{},"lint-staged":{"*.{json,md,html,css}":["oxfmt --write"],"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"]},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","oxfmt":"^0.55.0","react":"^19.0.0","oxlint":"^1.70.0","tsdown":"^0.22.3","publint":"^0.3.21","react-dom":"^19.0.0","@types/bun":"latest","typescript":"^6.0.3","lint-staged":"^17.0.7","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@happy-dom/global-registrator":"^17.0.0"},"peerDependencies":{"react":">=19"},"_npmOperationalInternal":{"tmp":"tmp/conversation_0.0.0_1781696402283_0.8126106323213393","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@codehz/conversation","version":"0.1.0","_id":"@codehz/conversation@0.1.0","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"dist":{"shasum":"96feeb4e3851b8f3a7cd1a7fdc14867bb1e49fbe","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.1.0.tgz","fileCount":19,"integrity":"sha512-2anX3HjA1E/3NHHMdgh3EvuHzAqCp6gXOpJMzJr1R65qA7895k8zi62ec6UPlGpTq4dTqGGIC7foR56dWRMWrw==","signatures":[{"sig":"MEQCIELOFRVkPLP3XJJGaffZAlwHv8aFFnEdB7crdcCg78A0AiBTzk7g6UFadBPDD+AOvAQeGmeq4J1R7402u0tphvpalA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":255063},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./package.json":"./package.json"},"gitHead":"c1f1312c8a92a4eadb93db57a50ebdb00a8f24b7","scripts":{"lint":"oxlint","test":"bun test","build":"tsdown","format":"oxfmt --write","prepare":"husky","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","build:watch":"tsdown --watch","format:check":"oxfmt --check","test:coverage":"bun test --coverage","prepublishOnly":"tsdown"},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"_npmVersion":"11.16.0","description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","directories":{},"lint-staged":{"*.{json,md,html,css}":["oxfmt --write"],"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"]},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","oxfmt":"^0.55.0","react":"^19.0.0","oxlint":"^1.70.0","tsdown":"^0.22.3","publint":"^0.3.21","react-dom":"^19.0.0","@types/bun":"latest","typescript":"^6.0.3","lint-staged":"^17.0.7","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@happy-dom/global-registrator":"^17.0.0"},"peerDependencies":{"react":">=19"},"_npmOperationalInternal":{"tmp":"tmp/conversation_0.1.0_1781705098633_0.1835208504808925","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@codehz/conversation","version":"0.2.0","_id":"@codehz/conversation@0.2.0","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"dist":{"shasum":"a1974f6dfc5b688dc09bb1d6eb2161618c605fee","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.2.0.tgz","fileCount":31,"integrity":"sha512-xeNwKkuPtZPLfJbcQjMYInvEebS9D7yFkbZLKS4rI4l4xUf5nXd2u3ie5NqT4iy6q9JQyPGJRPnJDGGE+iuDng==","signatures":[{"sig":"MEUCIQCHTZ52ZOur6+XiuEx0bDMdES9wFwPt3Qz6vdGKM7Hn7AIgS11G6oVu/VxThNrmfc0+2zpL0ckBShmRX/bOQ8LOiAo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":328178},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./trace":{"types":"./dist/trace/index.d.ts","import":"./dist/trace/index.js","default":"./dist/trace/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./package.json":"./package.json"},"gitHead":"686714399de840206ecf3e56c1c6377650380ec1","scripts":{"lint":"oxlint","test":"bun test","build":"tsdown","format":"oxfmt --write","prepare":"husky","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","build:watch":"tsdown --watch","format:check":"oxfmt --check","test:coverage":"bun test --coverage","prepublishOnly":"tsdown"},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"_npmVersion":"11.16.0","description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","directories":{},"lint-staged":{"*.{json,md,html,css}":["oxfmt --write"],"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"]},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","oxfmt":"^0.55.0","react":"^19.0.0","oxlint":"^1.70.0","tsdown":"^0.22.3","publint":"^0.3.21","react-dom":"^19.0.0","@types/bun":"latest","typescript":"^6.0.3","lint-staged":"^17.0.7","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@happy-dom/global-registrator":"^17.0.0"},"peerDependencies":{"react":">=19"},"_npmOperationalInternal":{"tmp":"tmp/conversation_0.2.0_1781712000730_0.39817335745039695","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@codehz/conversation","version":"0.2.1","_id":"@codehz/conversation@0.2.1","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"dist":{"shasum":"7ee4c45316f4b909fdb23d80fcd8f0b847998750","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.2.1.tgz","fileCount":31,"integrity":"sha512-p7tR/+xWG7blDDX82dwZAqzE2Zg1FspLMYMe3Y5mSqAazSt8xH7GGLP2m7UPu/HexNnFtxXtSdjFEZwd0BDyxg==","signatures":[{"sig":"MEUCIQCwRgxVoKDkAqD7Ko4FXg+oB6ODobaTBFFJCfLt5Cy+nAIgH6P9935YYixHIFpIGMO9G4Cv8w041Y82x0EtdQSQCvo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":351750},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./trace":{"types":"./dist/trace/index.d.ts","import":"./dist/trace/index.js","default":"./dist/trace/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./package.json":"./package.json"},"gitHead":"d79d81881226b6f64a46b837b7fceb7c1f2c6774","scripts":{"lint":"oxlint","test":"bun test","build":"tsdown","format":"oxfmt --write","prepare":"husky","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","build:watch":"tsdown --watch","format:check":"oxfmt --check","test:coverage":"bun test --coverage","prepublishOnly":"tsdown"},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"_npmVersion":"11.16.0","description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","directories":{},"lint-staged":{"*.{json,md,html,css}":["oxfmt --write"],"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"]},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","oxfmt":"^0.55.0","react":"^19.0.0","oxlint":"^1.70.0","tsdown":"^0.22.3","publint":"^0.3.21","react-dom":"^19.0.0","@types/bun":"latest","typescript":"^6.0.3","lint-staged":"^17.0.7","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@happy-dom/global-registrator":"^17.0.0"},"peerDependencies":{"react":">=19"},"_npmOperationalInternal":{"tmp":"tmp/conversation_0.2.1_1781715446821_0.20879789019198114","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@codehz/conversation","version":"0.2.2","_id":"@codehz/conversation@0.2.2","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"dist":{"shasum":"cce7637e9c8e676cb3f1e15f43a63933346acf76","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.2.2.tgz","fileCount":31,"integrity":"sha512-/povFlpYmfhgKZzj5psgKc6xi6z2EmIIQgjjegtDcuPfKgqDif2MBZU+c1LtCn+mjD1gAh9V48AZ/UuaGP01hw==","signatures":[{"sig":"MEQCIGy4JYTG5G8VE4PDO8t0siK1X6q7ounKvmYVXQIKhk87AiAktuEIinpX6+kpn7Na5+NiLbo86lvx7fV8yDxPDiksWA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":356548},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./trace":{"types":"./dist/trace/index.d.ts","import":"./dist/trace/index.js","default":"./dist/trace/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./package.json":"./package.json"},"gitHead":"c9c882ae4c02fe484de55c2a4af3cb894601931b","scripts":{"lint":"oxlint","test":"bun test","build":"tsdown","format":"oxfmt --write","prepare":"husky","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","build:watch":"tsdown --watch","format:check":"oxfmt --check","test:coverage":"bun test --coverage","prepublishOnly":"tsdown"},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"_npmVersion":"11.16.0","description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","directories":{},"lint-staged":{"*.{json,md,html,css}":["oxfmt --write"],"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"]},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","oxfmt":"^0.55.0","react":"^19.0.0","oxlint":"^1.70.0","tsdown":"^0.22.3","publint":"^0.3.21","react-dom":"^19.0.0","@types/bun":"latest","typescript":"^6.0.3","lint-staged":"^17.0.7","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@happy-dom/global-registrator":"^17.0.0"},"peerDependencies":{"react":">=19"},"_npmOperationalInternal":{"tmp":"tmp/conversation_0.2.2_1781722909761_0.1823774211321081","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@codehz/conversation","version":"0.2.3","_id":"@codehz/conversation@0.2.3","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"dist":{"shasum":"6e96f5f59dd2ebe03efa44f744f354876176f733","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.2.3.tgz","fileCount":31,"integrity":"sha512-BYG0zeQa+zO4rdhCHalqeHchQrU2Phzx5wEOwWbyARHkKguec660IgWJRIcWQ6K2GgEKcpfshZa8ioCr4F/pdg==","signatures":[{"sig":"MEQCIFLCS12db0CQLzPM5uIrxJynIuNMDzibgIRq3Dwhzj3uAiBnfZlVI0tvdsXF6Fw1aU8SuelUJpQ8QTd17VVfkM+2JA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":356804},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./trace":{"types":"./dist/trace/index.d.ts","import":"./dist/trace/index.js","default":"./dist/trace/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./package.json":"./package.json"},"gitHead":"a15f56d77a5017187813df6c24fdd3f0b50f4eb5","scripts":{"lint":"oxlint","test":"bun test","build":"tsdown","format":"oxfmt --write","prepare":"husky","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","build:watch":"tsdown --watch","format:check":"oxfmt --check","test:coverage":"bun test --coverage","prepublishOnly":"tsdown"},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"_npmVersion":"11.16.0","description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","directories":{},"lint-staged":{"*.{json,md,html,css}":["oxfmt --write"],"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"]},"_nodeVersion":"26.2.0","_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","oxfmt":"^0.55.0","react":"^19.0.0","oxlint":"^1.70.0","tsdown":"^0.22.3","publint":"^0.3.21","react-dom":"^19.0.0","@types/bun":"latest","typescript":"^6.0.3","lint-staged":"^17.0.7","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@happy-dom/global-registrator":"^17.0.0"},"peerDependencies":{"react":">=19"},"_npmOperationalInternal":{"tmp":"tmp/conversation_0.2.3_1781723951880_0.23225177946128772","host":"s3://npm-registry-packages-npm-production"}},"0.2.4":{"name":"@codehz/conversation","version":"0.2.4","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js","default":"./dist/core/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js","default":"./dist/server/index.js"},"./react":{"types":"./dist/react/index.d.ts","import":"./dist/react/index.js","default":"./dist/react/index.js"},"./trace":{"types":"./dist/trace/index.d.ts","import":"./dist/trace/index.js","default":"./dist/trace/index.js"},"./package.json":"./package.json"},"scripts":{"build":"tsdown","build:watch":"tsdown --watch","prepublishOnly":"tsdown","test":"bun test","test:coverage":"bun test --coverage","format":"oxfmt --write","format:check":"oxfmt --check","lint":"oxlint","lint:fix":"oxlint --fix","typecheck":"tsc --noEmit","prepare":"husky"},"devDependencies":{"@happy-dom/global-registrator":"^17.0.0","@testing-library/dom":"^10.0.0","@testing-library/react":"^16.0.0","@types/bun":"latest","@types/react":"^19.2.2","@types/react-dom":"^19.2.2","husky":"^9.1.7","lint-staged":"^17.0.7","oxfmt":"^0.55.0","oxlint":"^1.70.0","publint":"^0.3.21","react":"^19.0.0","react-dom":"^19.0.0","tsdown":"^0.22.3","typescript":"^6.0.3"},"peerDependencies":{"react":">=19"},"lint-staged":{"*.{ts,tsx,js,jsx,mjs,cjs}":["oxfmt --write","oxlint --fix"],"*.{json,md,html,css}":["oxfmt --write"]},"gitHead":"beb457fa2d3a2e5b1664f292e9dc9aa4699d1d07","_id":"@codehz/conversation@0.2.4","description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","_nodeVersion":"26.2.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-dYvfQR4rkwXRPXY1Cbjxa8G8qTwLTBv+YPM0n9w0uxS8DP+mTODfZKb7S66+gSv5PmOUI1Ad229uAUjTIDhZGA==","shasum":"6392249d2853134f89587afdb3c1199c1a20a9d2","tarball":"https://registry.npmjs.org/@codehz/conversation/-/conversation-0.2.4.tgz","fileCount":31,"unpackedSize":365704,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC+xqCcJXDqfcmNALwJ1rSjWQpw/2Vi523KiWCzztaZRgIgF608xFCnJ7PpqSWG8XKS/dozammUSPKUzQkegZkAUoY="}]},"_npmUser":{"name":"codehz","email":"CodeHz@Outlook.com"},"directories":{},"maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/conversation_0.2.4_1781727073559_0.5683623119523888"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T11:40:02.113Z","modified":"2026-06-17T20:11:13.879Z","0.0.0":"2026-06-17T11:40:02.414Z","0.1.0":"2026-06-17T14:04:58.763Z","0.2.0":"2026-06-17T16:00:00.881Z","0.2.1":"2026-06-17T16:57:27.018Z","0.2.2":"2026-06-17T19:01:49.929Z","0.2.3":"2026-06-17T19:19:12.081Z","0.2.4":"2026-06-17T20:11:13.745Z"},"description":"`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:","maintainers":[{"name":"codehz","email":"CodeHz@Outlook.com"}],"readme":"# @codehz/conversation\n\n`@codehz/conversation` is a Bun-first conversation sync library for AI applications. It provides:\n\n- canonical message history with branching active-path state\n- run lifecycle and durable streaming events\n- snapshot + event-log recovery\n- audience-aware projection (`public` / `protected` / `private`)\n- structured input request / submission envelope\n- host event channel (shared seq axis with conversation events)\n- trace sidecar with independent `TraceStore`\n- plugin pipeline (command/event interception, projection, lifecycle hooks)\n- run driver host (driver registration, match, HostAPI facade)\n- Bun WebSocket sync with audience-aware projection\n- React client/hooks for vNext conversation state\n\nThe library owns protocol and synchronization. The host owns agent execution, routing, auth, storage partitioning, and tool implementations.\n\n## Install\n\n```bash\nbun install\n```\n\n## Build and test\n\n```bash\nbun run build\nbun run typecheck\nbun test\n```\n\n## Package surfaces\n\n| Import path                         | Description                                                          |\n| ----------------------------------- | -------------------------------------------------------------------- |\n| `@codehz/conversation`              | vNext — all exported types, engine, server, react, trace             |\n| `@codehz/conversation/vnext`        | Same as default (vNext entry point)                                  |\n| `@codehz/conversation/vnext/core`   | Core types, reducer, projection, commands                            |\n| `@codehz/conversation/vnext/server` | `ConversationEngine`, storage contracts, sync server, plugin, driver |\n| `@codehz/conversation/vnext/react`  | `ConversationClient`, React hooks, `ConversationProvider`            |\n| `@codehz/conversation/vnext/trace`  | Trace types, store contract, projection helpers                      |\n\n## Core concepts\n\n### Messages\n\nCanonical history is stored as `Message` nodes:\n\n- roles: `system | user | assistant | tool`\n- tree shape via `parentId`\n- optional `runId`\n- ordered structured `parts`\n- protocol-level `Visibility: \"public\" | \"protected\" | \"private\"`\n\n`MessagePart` is a closed union:\n\n- `text`\n- `reasoning`\n- `tool-call`\n- `tool-result`\n- `file`\n- `source`\n- `data`\n- `step-marker`\n\n### Runs\n\nRuns are first-class records with status, checkpoints, visibility, and output message ids. A single run may materialize multiple messages.\n\n### Visibility & Audience\n\nMessages, parts, runs, host events, and traces carry `Visibility`:\n\n- `public`: visible to all audiences\n- `protected`: visible to `controlled` / `host` / `system` audiences\n- `private`: visible only to `host` / `system` audiences\n\nThe host provides a `ProjectionPolicy` to determine per-audience visibility and field-level projection. The `Audience` is declared at connection time.\n\n### Persistence\n\nStorage is host-owned through three separate contracts:\n\n- **`EventStore`**: append-only event log with atomic batch writes\n- **`SnapshotStore`**: full-state snapshot storage\n- **`TraceStore`**: independent trace record storage\n\n```ts\ninterface EventStore {\n  append(envelopes: readonly EventEnvelope[]): Promise<void>;\n  getEvents(fromSeq: number): Promise<readonly EventEnvelope[]>;\n  getLastSeq(): Promise<number>;\n}\n```\n\nSnapshots are part of the protocol contract. Recovery loads the latest snapshot, then replays tail events.\n\n### Structured Input\n\n`RunInputRequest` supports `message | form | approval | selection | custom` kinds. Submissions use an `InputSubmissionEnvelope` that wraps typed payloads.\n\n### Host Events\n\n`HostEvent` shares the same seq axis as `ConversationEvent`, ensuring deterministic replay order. Host events are projected through the same `ProjectionPolicy` as conversation events.\n\n### Trace\n\nTrace records are stored in an independent `TraceStore`. Summaries are emitted into the main sync stream as `trace.summaryAppended` events for real-time client delivery.\n\n## Typical host flow\n\nClient submission creates a user message and a pending run. A registered `RunDriver` (or manual `subscribe`) handles `run.requested`:\n\nRecommended high-level entry points:\n\n- `engine.startRun(...)` for host-initiated runs\n- `host.beginAssistantMessage(...)` for streaming assistant output\n\n### Using a RunDriver (vNext)\n\n```ts\nconst driverHost = new DriverHost();\ndriverHost.register(\n  new CallbackDriver(\"echo-agent\", async (ctx) => {\n    const { run, host } = ctx;\n    await host.transitionRun(run.id, \"running\");\n    const writer = await host.beginAssistantMessage({\n      runId: run.id,\n      parentId: ctx.trigger.id,\n    });\n    await writer.text(\"Hello!\");\n    await writer.done();\n    await host.transitionRun(run.id, \"completed\");\n  }),\n);\n\nconst engine = new ConversationEngine({\n  eventStore,\n  snapshotStore,\n  traceStore,\n  compactionPolicy,\n  metrics,\n  driverHost,\n});\n```\n\n### Using subscribe (manual)\n\n```ts\nengine.subscribe((envelope) => {\n  if (envelope.kind === \"conversation\" && envelope.event.type === \"run.requested\") {\n    void startAgent(envelope.event.payload.runId);\n  }\n});\n```\n\n## React client\n\n`ConversationClient` handles:\n\n- WebSocket connection and reconnect\n- `lastSeq` persistence\n- `sync.snapshot` + incremental replay\n- gap/reset handling\n- generic `sendCommand` for all command types\n\nIn React, mount the client under `ConversationProvider`. The provider owns `connect()` / `disconnect()` by default, so components do not need a manual `useEffect` just to open the socket.\n\nHooks expose projected state:\n\n- `useConversation<T>(selector)`, `useMessage(id)`, `useActiveMessageIds()`\n- `useRun(runId)`, `useActiveRun()`, `useRunsByStatus(status)`\n- `useMessageBlocks(messageId)`, `usePendingInput(runId)`, `useRunToolEvents(runId)`\n- `useVariantGroup(messageId)`\n- `useHostEvents()`, `useHostEventsByNamespace(namespace)`\n- `useTraceSummaries()`, `useTraceSummariesByRun(runId)`\n- `useConnectionStatus()`, `useSendCommand()`, `useReconnect()`\n\n## Minimal host example\n\nThe example under [`examples/minimal-host`](./examples/minimal-host) demonstrates vNext:\n\n- structured message input\n- host events (agent lifecycle)\n- trace sidecar (agent traces)\n- driver registration (`CallbackDriver`)\n- audience-aware sync\n\nRun it with:\n\n```bash\ncd examples/minimal-host\nbun install\nbun start\n```\n\nThen open `http://localhost:3000`.\n\n## References\n\n- [DESIGN.md](./DESIGN.md) - vNext protocol and architecture\n","readmeFilename":"README.md"}