@agent-os/attached-stream

Purpose

Runtime-neutral frame algebra and JSON text codecs for attached live streams: a session can receive input frames, emit output/progress frames, and eventually emit one terminal frame.

Public API Status

0.5.x public-experimental. Experimental exports are listed in PUBLIC_API.md to prevent accidental exports; they are not frozen.

Invariant

Attached stream frames are transport/progress data, not ledger facts. The package does not open sockets, allocate streamRef, write ledger events, own tenant auth, or promise reconnect/resume. Terminal settlement belongs to the runtime handler that consumes the terminal frame.

Inbound and outbound frames use independent sequence spaces. Only explicit cancel input is cancel intent; transport detach is not cancel.

Minimal Usage

Use the package for codec and projection at the UI or backend wire boundary.

import {
  decodeAttachedStreamMessage,
  encodeAttachedStreamMessage,
  projectAttachedStream,
} from "@agent-os/attached-stream";

For v1, clients reconnect by attaching a new stream. Old stream state is not resumed.

Verification

cd packages/composers/attached-stream
bun run test