{"_id":"@aos-agent/protocol","_rev":"4-42a388e0c32710a8694d718b8694c26f","name":"@aos-agent/protocol","dist-tags":{"latest":"0.85.1"},"versions":{"0.84.2":{"name":"@aos-agent/protocol","version":"0.84.2","keywords":["aos-agent","protocol","cbor","binary","framing"],"author":{"name":"Earendil Works"},"license":"MIT","_id":"@aos-agent/protocol@0.84.2","maintainers":[{"name":"aosagent","email":"guanwenpeng2001@gmail.com"}],"homepage":"https://github.com/guanwenpeng2001-bot/AOS-Agent#readme","bugs":{"url":"https://github.com/guanwenpeng2001-bot/AOS-Agent/issues"},"dist":{"shasum":"357bea76f18a988b1052287b957dbab5d54a30a1","tarball":"https://registry.npmjs.org/@aos-agent/protocol/-/protocol-0.84.2.tgz","fileCount":34,"integrity":"sha512-XaPnMxd7uvP6VuXdN1UBr/aiL1KJENd4s/cEOWAIrFHOk34CXryAOXZ5K5xogOICStOYjVt6Dm0hgCCag7xCew==","signatures":[{"sig":"MEYCIQC/QWutUKaBmwD+KqiWXh1+VbtCwYm8VzZv8wdxB+L/KwIhAKY7D6ErlqC4ZTxTnwR6PzbGbrxsp33YOwVPjtgZjzS8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":882466},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest --run","build":"tsgo -p tsconfig.build.json","clean":"shx rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"aosagent","email":"guanwenpeng2001@gmail.com"},"repository":{"url":"git+https://github.com/guanwenpeng2001-bot/AOS-Agent.git","type":"git","directory":"packages/protocol"},"_npmVersion":"12.0.2","description":"Transport-neutral CBOR protocol for remote AOS Agent sessions","directories":{},"_nodeVersion":"24.18.1","dependencies":{"typebox":"1.3.7"},"_hasShrinkwrap":false,"devDependencies":{"shx":"0.4.0","vitest":"4.1.9"},"_npmOperationalInternal":{"tmp":"tmp/protocol_0.84.2_1786323618972_0.1278894398367323","host":"s3://npm-registry-packages-npm-production"}},"0.84.3":{"name":"@aos-agent/protocol","version":"0.84.3","keywords":["aos-agent","protocol","cbor","binary","framing"],"author":{"name":"Earendil Works"},"license":"MIT","_id":"@aos-agent/protocol@0.84.3","maintainers":[{"name":"aosagent","email":"guanwenpeng2001@gmail.com"}],"homepage":"https://github.com/guanwenpeng2001-bot/AOS-Agent#readme","bugs":{"url":"https://github.com/guanwenpeng2001-bot/AOS-Agent/issues"},"dist":{"shasum":"fd629ed71b1a562b3d7fb3a9614dfe1a07545693","tarball":"https://registry.npmjs.org/@aos-agent/protocol/-/protocol-0.84.3.tgz","fileCount":34,"integrity":"sha512-wvXhb8bCgPvXU7GO1J+DmBThrqjTCd0cU0helkbjjP2eKxjjbvhIz9pTB7kj447T2i1yTVa/M5CEv8ZF+vzqng==","signatures":[{"sig":"MEUCIC2E9QR12AK0I662iLlyTlEy0SdEybFbzzeNEOn1b3pCAiEA4kznCY8suvBV64TuowgE3E6TbbhYWTiP61IV1dJF26E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aos-agent%2fprotocol@0.84.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":882466},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d92430128236cc1f285dcbb4f03ddd56ed81f8da","scripts":{"test":"vitest --run","build":"tsgo -p tsconfig.build.json","clean":"shx rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9f0808e1-7e58-4f0a-9ede-7b63d7f06e95"}},"repository":{"url":"git+https://github.com/guanwenpeng2001-bot/AOS-Agent.git","type":"git","directory":"packages/protocol"},"_npmVersion":"11.5.1","description":"Transport-neutral CBOR protocol for remote AOS Agent sessions","directories":{},"_nodeVersion":"24.18.0","dependencies":{"typebox":"1.3.7"},"_hasShrinkwrap":false,"devDependencies":{"shx":"0.4.0","vitest":"4.1.9"},"_npmOperationalInternal":{"tmp":"tmp/protocol_0.84.3_1786383921462_0.7080713290524869","host":"s3://npm-registry-packages-npm-production"}},"0.85.0":{"name":"@aos-agent/protocol","version":"0.85.0","keywords":["aos-agent","protocol","cbor","binary","framing"],"author":{"name":"AOS Agent"},"license":"MIT","_id":"@aos-agent/protocol@0.85.0","maintainers":[{"name":"aosagent","email":"guanwenpeng2001@gmail.com"}],"homepage":"https://github.com/guanwenpeng2001-bot/AOS-Agent#readme","bugs":{"url":"https://github.com/guanwenpeng2001-bot/AOS-Agent/issues"},"dist":{"shasum":"093e053892e6116f95e4f700b8e62481e7a7e7f5","tarball":"https://registry.npmjs.org/@aos-agent/protocol/-/protocol-0.85.0.tgz","fileCount":34,"integrity":"sha512-wiGVZ3wl2GT+BI+Cn3iVsINd/izEBonRBC7GisAGH5SjO8Zae8rHmpr1GqPn0wpqI+vsgtKWbN2/Q4ZplCdzLA==","signatures":[{"sig":"MEUCIDwlWP4hw/BkyZWXcgZPpO/Go+ulGFPBfvFwd04KkqEHAiEAmiDXtZAhiMSjMyYIMjKbDqsQ/WVZAwXs2fvnDCnPfJ8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aos-agent%2fprotocol@0.85.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":882461},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a305bd6d376b447cbdc0b92711a54e9778d24695","scripts":{"test":"vitest --run","build":"tsgo -p tsconfig.build.json","clean":"shx rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9f0808e1-7e58-4f0a-9ede-7b63d7f06e95"}},"repository":{"url":"git+https://github.com/guanwenpeng2001-bot/AOS-Agent.git","type":"git","directory":"packages/protocol"},"_npmVersion":"11.5.1","description":"Transport-neutral CBOR protocol for remote AOS Agent sessions","directories":{},"_nodeVersion":"24.19.0","dependencies":{"typebox":"1.3.7"},"_hasShrinkwrap":false,"devDependencies":{"shx":"0.4.0","vitest":"4.1.9"},"_npmOperationalInternal":{"tmp":"tmp/protocol_0.85.0_1788326533229_0.049347342631426594","host":"s3://npm-registry-packages-npm-production"}},"0.85.1":{"name":"@aos-agent/protocol","version":"0.85.1","description":"Transport-neutral CBOR protocol for remote AOS Agent sessions","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"clean":"shx rm -rf dist","build":"tsgo -p tsconfig.build.json","test":"vitest --run","prepublishOnly":"npm run clean && npm run build"},"keywords":["aos-agent","protocol","cbor","binary","framing"],"author":{"name":"AOS Agent"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/guanwenpeng2001-bot/AOS-Agent.git","directory":"packages/protocol"},"engines":{"node":">=22.19.0"},"dependencies":{"typebox":"1.3.7"},"devDependencies":{"shx":"0.4.0","vitest":"4.1.9"},"_id":"@aos-agent/protocol@0.85.1","gitHead":"8fc01dea402bced66d545cf6febddcd944d8943b","bugs":{"url":"https://github.com/guanwenpeng2001-bot/AOS-Agent/issues"},"homepage":"https://github.com/guanwenpeng2001-bot/AOS-Agent#readme","_nodeVersion":"24.20.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-1XJeN2Kf4m6vURl+m/wvx8/2ZH/1fAhgwKUmqoXoPXuxbgLGbP5IetDHJ7rKgM6667H+ETPFQkJLmUvM/YFL+g==","shasum":"22cf8c7cc20c236e55f7531c00253cf741c4b43c","tarball":"https://registry.npmjs.org/@aos-agent/protocol/-/protocol-0.85.1.tgz","fileCount":34,"unpackedSize":882461,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aos-agent%2fprotocol@0.85.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCieKgTIwk1Drr6gLlHM0PSaqVbtzgTgBWNrwEBpiC6DwIhALKvRCgv06rnsshjXmeBLcjI6DIr7HhBu/CxudoUf9FO"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9f0808e1-7e58-4f0a-9ede-7b63d7f06e95"}},"directories":{},"maintainers":[{"name":"aosagent","email":"guanwenpeng2001@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/protocol_0.85.1_1788451899096_0.9307441657994557"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-10T01:00:18.862Z","modified":"2026-09-03T16:11:40.104Z","0.84.2":"2026-08-10T01:00:19.120Z","0.84.3":"2026-08-10T17:45:21.613Z","0.85.0":"2026-09-02T05:22:13.386Z","0.85.1":"2026-09-03T16:11:39.236Z"},"bugs":{"url":"https://github.com/guanwenpeng2001-bot/AOS-Agent/issues"},"author":{"name":"AOS Agent"},"license":"MIT","homepage":"https://github.com/guanwenpeng2001-bot/AOS-Agent#readme","keywords":["aos-agent","protocol","cbor","binary","framing"],"repository":{"type":"git","url":"git+https://github.com/guanwenpeng2001-bot/AOS-Agent.git","directory":"packages/protocol"},"description":"Transport-neutral CBOR protocol for remote AOS Agent sessions","maintainers":[{"name":"aosagent","email":"guanwenpeng2001@gmail.com"}],"readme":"# @aos-agent/protocol\n\nRuntime-neutral schemas, types, CBOR encoding, and byte-stream framing for the experimental AOS Agent protocol.\n\nProtocol version `1` uses binary messages with this wire layout:\n\n1. A four-byte unsigned big-endian payload length.\n2. One definite-length CBOR item containing the message.\n\nThe first client message is always `hello`, containing `PROTOCOL_VERSION`. Subsequent messages use correlated request/response envelopes and server event envelopes. Session and server snapshots are authoritative. Progress events are transient UI hints and must not be reduced into authoritative state. Transports complete authentication before protocol bytes are exchanged.\n\nSession lists contain `SessionMetadata`, the normalized durable metadata available without acquiring a session runtime. Only `id` and `createdAt` are required; `updatedAt`, `parentSessionId`, `sessionName`, and `cwd` are included when supported by the backing store. Runtime state such as phase, model, thinking level, attachment, and locking appears only in an acquired `SessionSnapshot`.\n\n## Validated message API\n\n`encodeClientMessage()` and `encodeServerMessage()` validate a message and return a complete framed `Uint8Array`. The incremental decoders accept arbitrary fragmentation or coalescing, so they work with streams, sockets, and custom byte transports.\n\n```ts\nimport {\n  PROTOCOL_VERSION,\n  createServerMessageDecoder,\n  encodeClientMessage,\n  type ClientHello,\n} from \"@aos-agent/protocol\";\n\nconst hello: ClientHello = {\n  type: \"hello\",\n  version: PROTOCOL_VERSION,\n};\n\ntransport.send(encodeClientMessage(hello));\n\nconst decoder = createServerMessageDecoder({ maxFrameLength: 1024 * 1024 });\nfor (const message of decoder.push(incomingChunk)) {\n  handleServerMessage(message);\n}\ndecoder.end(); // Call when the byte stream closes to detect truncation.\n```\n\n`ClientMessageDecoder` and `ServerMessageDecoder` are also available directly. Schema violations, malformed CBOR, and invalid framing throw `ProtocolValidationError`. Validation errors do not retain rejected payloads.\n\n`parseClientMessage()` and `parseServerMessage()` only validate already-decoded values. They do not parse JSON strings.\n\n## Transport support\n\nEvery transport carries the same complete bytes: `[uint32-be CBOR length][CBOR payload]`. Transports may split or coalesce those bytes arbitrarily.\n\nThis package does not bundle a transport. Consumers provide a byte-stream transport that preserves byte order and reports stream closure. Custom transports must handle arbitrary frame fragmentation and coalescing.\n\nAll transports are untrusted. Configure matching frame limits and enforce access controls appropriate for the transport before exposing a connection to the protocol. Unix sockets can use filesystem permissions, while network transports can authenticate during connection establishment.\n\n## Encoding and framing\n\n`encodeCbor()` and `decodeCbor()` implement the protocol's strict RFC 8949 subset. `encodeFrame()` and `FrameDecoder` handle framing independently of schemas and CBOR.\n\nThe CBOR subset supports:\n\n- `null` and booleans\n- finite numbers, with integers restricted to JavaScript's safe range and non-integers encoded as float64\n- UTF-8 strings\n- `Uint8Array` byte strings\n- definite-length arrays\n- definite-length maps represented by objects with unique string keys\n\nUndefined object properties are omitted. JSON-valued protocol fields reject CBOR byte strings and non-plain objects. Top-level undefined, undefined array entries, sparse arrays, non-finite or unsafe numbers, tags, indefinite-length items, malformed UTF-8, trailing data, excessive nesting, and oversized values are rejected.\n\nDefault limits are 16 MiB per CBOR payload/frame, 1,000,000 array elements or map entries, and 64 nested item levels. Options can configure these limits. A frame decoder validates the declared length before buffering payload bytes.\n\nAll schemas reject unknown object properties. The protocol is experimental and has no compatibility guarantees.\n","readmeFilename":"README.md"}