@moureau/pipeflow 0.0.1 → 0.0.2

package/dist/esm/transport/streamobject/reference/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/reference/index.ts"],
+  "sourcesContent": ["export {\n  ReferenceDecoder,\n  Receiver,\n  decode,\n  encodeText,\n  executeRecords,\n  materializeObject,\n  parseBooleanPayload,\n  parseIntegerPayload,\n  parseNumberPayload,\n} from \"./reference\";\nexport type {\n  Decoder,\n  Event,\n  FieldDef,\n  FieldType,\n  FieldValue,\n  Payload,\n  ScalarValue,\n  Schema,\n  StreamRecord,\n} from \"./reference\";\n"],
+  "mappings": "AAAA,OACE,oBAAAA,EACA,YAAAC,EACA,UAAAC,EACA,cAAAC,EACA,kBAAAC,EACA,qBAAAC,EACA,uBAAAC,EACA,uBAAAC,EACA,sBAAAC,MACK",
+  "names": ["ReferenceDecoder", "Receiver", "decode", "encodeText", "executeRecords", "materializeObject", "parseBooleanPayload", "parseIntegerPayload", "parseNumberPayload"]
+}

package/dist/esm/transport/streamobject/reference/reference.js

@@ -0,0 +1,2 @@
+var v=Object.defineProperty;var s=(r,e)=>v(r,"name",{value:e,configurable:!0});const y=/^-?(0|[1-9][0-9]*)$/,w=/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/;function E(r){if(!y.test(r)||r==="-0")return null;const e=Number(r);return Number.isSafeInteger(e)?e:null}s(E,"parseIntegerPayload");function x(r){if(!w.test(r))return null;const e=Number(r);return Number.isFinite(e)?e:null}s(x,"parseNumberPayload");function k(r){return r==="0"?!1:r==="1"?!0:null}s(k,"parseBooleanPayload");function h(r,e,t){switch(r){case"string":return e;case"integer":{const n=E(e);if(n===null)throw new Error(`field ${t}: invalid integer payload`);return n}case"number":{const n=x(e);if(n===null)throw new Error(`field ${t}: invalid number payload`);return n}case"boolean":{const n=k(e);if(n===null)throw new Error(`field ${t}: invalid boolean payload`);return n}}}s(h,"parseTyped");class u{static{s(this,"Receiver")}schema;state;acc;events=[];onEvent;ended=!1;constructor(e,t){this.schema=e,this.onEvent=t,this.state=new Uint8Array(e.length),this.acc=new Array(e.length)}append(e,t){if(this.assertActive(),this.assertField(e),this.state[e]===2)throw new Error(`field ${e}: append after completion`);const n=this.schema[e];if(n.mode==="array"){const i=this.acc[e]??=[],o=n.maxItems;if(i.length>=o)throw new Error(`field ${e}: exceeds maxItems=${o}`);if(n.maxLength!==void 0&&t.length>n.maxLength)throw new Error(`field ${e}: item exceeds maxLength=${n.maxLength}`);i.push(t)}else{const i=this.acc[e]??="";if(n.maxLength!==void 0&&i.length+t.length>n.maxLength)throw new Error(`field ${e}: exceeds maxLength=${n.maxLength}`);this.acc[e]=i+t}this.state[e]=1}complete(e){if(this.assertActive(),this.assertField(e),this.state[e]===2)throw new Error(`field ${e}: completed twice`);const t=this.schema[e];if(this.state[e]===0){if(t.type!=="string"&&t.mode!=="array")throw new Error(`field ${e}: cannot complete an empty ${t.type} field`);this.state[e]=2,this.emit({kind:"field",field:e,value:t.mode==="array"?[]:""});return}this.state[e]=2,this.emit({kind:"field",field:e,value:S(this.schema,e,this.acc[e])})}objectComplete(){this.assertActive(),this.ended=!0,this.emit({kind:"object-complete"})}objectAbort(){this.assertActive(),this.ended=!0,this.emit({kind:"object-abort"})}getEvents(){return this.events}get isEnded(){return this.ended}assertActive(){if(this.ended)throw new Error("object already ended")}assertField(e){if(e<0||e>=this.schema.length)throw new Error(`unknown field ${e}`)}emit(e){this.events.push(e),this.onEvent?.(e)}}function S(r,e,t){const n=r[e];return n.mode==="array"?t.map(i=>h(n.type,i,e)):h(n.type,t,e)}s(S,"materialize");function M(r,e){const t=new u(r);for(const n of e)switch(n.kind){case"append":t.append(n.field,n.payload);break;case"complete":t.complete(n.field);break;case"object-complete":t.objectComplete();break;case"object-abort":t.objectAbort();break}if(!t.isEnded)throw new Error("stream ended before object completion");return t.getEvents()}s(M,"executeRecords");function P(r,e){const t={};for(const n of e)n.kind==="field"&&R(t,r[n.field].path,n.value);return t}s(P,"materializeObject");function R(r,e,t){let n=r;for(let i=0;i<e.length-1;i++){const o=e[i];(typeof n[o]!="object"||n[o]===null)&&(n[o]={}),n=n[o]}n[e[e.length-1]]=t}s(R,"setPath");function T(r){let e="";for(const t of r)switch(t.kind){case"append":e+=`${t.field}:${t.payload.length}:${t.payload};`;break;case"complete":e+=`!${t.field};`;break;case"object-complete":e+="!;";break;case"object-abort":e+="~;";break}return e}s(T,"encodeText");class ${static{s(this,"ReferenceDecoder")}receiver;state="header";fieldId="";length="";payload="";remaining=0;constructor(e,t){this.receiver=new u(e,t)}push(e){for(let t=0;t<e.length;t++){const n=e[t];switch(this.state){case"header":this.onHeader(n);break;case"field-id":this.onFieldId(n);break;case"length":this.onLength(n);break;case"payload":this.onPayload(n);break;case"payload-end":this.onPayloadEnd(n);break;case"control":this.onControl(n);break;case"abort":this.onAbort(n);break}}}end(){if(!this.receiver.isEnded)throw new Error("stream ended before object completion");return this.receiver.getEvents()}onHeader(e){if(c(e)){this.reset(),this.fieldId=e,this.state="field-id";return}if(e==="!"){this.reset(),this.state="control";return}if(e==="~"){this.state="abort";return}throw new Error(`expected record start, got ${JSON.stringify(e)}`)}onFieldId(e){if(c(e)){this.fieldId+=e;return}if(e===":"){this.state="length";return}throw new Error(`expected ':' after field id, got ${JSON.stringify(e)}`)}onLength(e){if(c(e)){this.length+=e;return}if(e===":"){if(this.length==="")throw new Error("empty payload length");this.remaining=Number(this.length),this.payload="",this.state=this.remaining===0?"payload-end":"payload";return}throw new Error(`expected ':' after length, got ${JSON.stringify(e)}`)}onPayload(e){this.payload+=e,--this.remaining===0&&(this.state="payload-end")}onPayloadEnd(e){if(e!==";")throw new Error(`expected ';' after payload, got ${JSON.stringify(e)}`);this.receiver.append(Number(this.fieldId),this.payload),this.state="header"}onControl(e){if(c(e)){this.fieldId+=e;return}if(e===";"){this.fieldId===""?this.receiver.objectComplete():this.receiver.complete(Number(this.fieldId)),this.state="header";return}throw new Error(`expected field id or ';' after '!', got ${JSON.stringify(e)}`)}onAbort(e){if(e!==";")throw new Error(`expected ';' after '~', got ${JSON.stringify(e)}`);this.receiver.objectAbort(),this.state="header"}reset(){this.fieldId="",this.length="",this.payload="",this.remaining=0}}function c(r){return r>="0"&&r<="9"}s(c,"isDigit");function C(r,e){const t=new $(e);for(const n of r)t.push(n);return t.end()}s(C,"decode");function V(r){let e=r>>>0;return()=>{e=e+1831565813>>>0;let t=e;return t=Math.imul(t^t>>>15,t|1),t^=t+Math.imul(t^t>>>7,t|61),((t^t>>>14)>>>0)/4294967296}}s(V,"mulberry32");function O(r,e){const t=[];for(let o=1;o<r.length;o++)e()<.3&&t.push(o);const n=[];let i=0;for(const o of t)n.push(r.slice(i,o)),i=o;return n.push(r.slice(i)),n}s(O,"fragment");function D(r){const e=[];for(let t=1;t<r.length;t++)e.push([r.slice(0,t),r.slice(t)]);return e}s(D,"allSingleCuts");function J(r){const e=[];for(let t=0;t<1<<r.length-1;t++){const n=[];let i=0;for(let o=1;o<r.length;o++)t&1<<o-1&&(n.push(r.slice(i,o)),i=o);n.push(r.slice(i)),e.push(n)}return e}s(J,"allCompositions");const p=["string","integer","number","boolean"],m="abZ09;:!~ \xE9\u{1F600}";function B(r){const e=1+Math.floor(r()*4),t=[];for(let n=0;n<e;n++){const i=p[Math.floor(r()*p.length)],o=r()<.4;t.push({path:[`f${n}`],type:i,...o?{mode:"array",maxItems:1+Math.floor(r()*4)}:{},...r()<.8?{maxLength:1+Math.floor(r()*16)}:{}})}return t}s(B,"randomSchema");function j(r,e){let t="";for(;t.length<e&&r()<.85;)t+=m[Math.floor(r()*m.length)];return t}s(j,"randomString");function I(r,e,t){switch(e){case"string":return r()<.15?"":j(r,t);case"integer":return String(Math.floor(r()*2e3)-1e3);case"number":{const n=r();return n<.4?String(Math.floor(r()*2e3)-1e3):n<.7?String(Math.round((r()*2e3-1e3)*100)/100):String((r()*2-1)*1e10)}case"boolean":return r()<.5?"0":"1"}}s(I,"randomTyped");function f(r,e,t){const n=t??12;for(let i=0;i<100;i++){const o=I(r,e,n);if(o.length<=n)return o}return e==="string"?"":"0"}s(f,"payloadFor");function F(r,e){if(r.length===0)return[];const t=[];let n=0;for(let i=1;i<e;i++){const o=Math.floor(i*r.length/e);t.push(r.slice(n,o)),n=o}return t.push(r.slice(n)),t.filter(i=>i.length>0)}s(F,"splitFragments");function A(r,e,t){const n=e[t],i=[];if(n.mode==="array"){const l=n.maxItems,b=Math.floor(r()*(l+1));for(let d=0;d<b;d++)i.push({kind:"append",field:t,payload:f(r,n.type,n.maxLength)});return r()<.8&&i.push({kind:"complete",field:t}),i}const o=f(r,n.type,n.maxLength),a=F(o,1+Math.floor(r()*4));for(const l of a)i.push({kind:"append",field:t,payload:l});const g=n.type==="string";return(i.length>0?r()<.85:g&&r()<.5)&&i.push({kind:"complete",field:t}),i}s(A,"fieldRecords");function H(r,e){const t=e.map((o,a)=>({field:a,records:A(r,e,a),pos:0})),n=[];let i=t.reduce((o,a)=>o+a.records.length,0);for(;i>0;){let o=t[Math.floor(r()*t.length)];for(;o.pos>=o.records.length;)o=t[(o.field+1)%t.length];n.push(o.records[o.pos]),o.pos++,i--}return n.push(r()<.1?{kind:"object-abort"}:{kind:"object-complete"}),n}s(H,"generateValidRecords");export{u as Receiver,$ as ReferenceDecoder,J as allCompositions,D as allSingleCuts,C as decode,T as encodeText,M as executeRecords,A as fieldRecords,O as fragment,H as generateValidRecords,P as materializeObject,V as mulberry32,k as parseBooleanPayload,E as parseIntegerPayload,x as parseNumberPayload,B as randomSchema};
+//# sourceMappingURL=reference.js.map

package/dist/esm/transport/streamobject/reference/reference.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/reference/reference.ts"],
+  "sourcesContent": ["/**\n * StreamObject Protocol v0.1 \u2014 reference implementation (the executable spec).\n *\n * Deliberately boring: no arena, no pooling, no typed-array chunk chains.\n * Its purpose is to pin down semantics so the optimized receiver can be\n * validated against it instead of inventing behavior.\n *\n * Layering:\n *   records --(encodeText)--> text --(fragment)--> chunks\n *   chunks --(ReferenceDecoder)--> events\n *   records --(Receiver / executeRecords)--> events   <- the oracle\n *\n * Contract (the property every decoder must satisfy):\n *   decode(fragment(encodeText(records)))  ===  executeRecords(records)\n *\n * See README.md (in this directory) for the normative spec this implements.\n */\n\nexport type Payload = string; // payload as a JS string (UTF-16 code units)\n\nexport type StreamRecord =\n  | { kind: \"append\"; field: number; payload: Payload }\n  | { kind: \"complete\"; field: number }\n  | { kind: \"object-complete\" }\n  | { kind: \"object-abort\" };\n\nexport type FieldType = \"string\" | \"integer\" | \"number\" | \"boolean\";\n\nexport interface FieldDef {\n  path: string[];\n  type: FieldType;\n  mode?: \"array\";\n  /** Required for array fields. */\n  maxItems?: number;\n  /** Scalar: cap on accumulated payload length. Array: cap per item. */\n  maxLength?: number;\n}\n\nexport type Schema = FieldDef[];\n\nexport type ScalarValue = string | number | boolean;\nexport type FieldValue = ScalarValue | ScalarValue[];\n\nexport type Event =\n  | { kind: \"field\"; field: number; value: FieldValue }\n  /** Adapter-observable item completion (arrays); not emitted by the v0.1 wire decoder. */\n  | { kind: \"item\"; field: number; index: number; value: ScalarValue }\n  | { kind: \"object-complete\" }\n  | { kind: \"object-abort\" };\n\n// ---- canonical typed payloads (spec \u00A72.1) -----------------------------------\n\nconst INTEGER_RE = /^-?(0|[1-9][0-9]*)$/;\nconst NUMBER_RE = /^-?(0|[1-9][0-9]*)(\\.[0-9]+)?([eE][+-]?[0-9]+)?$/;\n\nexport function parseIntegerPayload(s: string): number | null {\n  if (!INTEGER_RE.test(s)) return null;\n  if (s === \"-0\") return null;\n  const n = Number(s);\n  return Number.isSafeInteger(n) ? n : null;\n}\n\nexport function parseNumberPayload(s: string): number | null {\n  if (!NUMBER_RE.test(s)) return null;\n  const n = Number(s);\n  return Number.isFinite(n) ? n : null;\n}\n\nexport function parseBooleanPayload(s: string): boolean | null {\n  if (s === \"0\") return false;\n  if (s === \"1\") return true;\n  return null;\n}\n\nfunction parseTyped(type: FieldType, s: string, field: number): ScalarValue {\n  switch (type) {\n    case \"string\":\n      return s;\n    case \"integer\": {\n      const v = parseIntegerPayload(s);\n      if (v === null) throw new Error(`field ${field}: invalid integer payload`);\n      return v;\n    }\n    case \"number\": {\n      const v = parseNumberPayload(s);\n      if (v === null) throw new Error(`field ${field}: invalid number payload`);\n      return v;\n    }\n    case \"boolean\": {\n      const v = parseBooleanPayload(s);\n      if (v === null) throw new Error(`field ${field}: invalid boolean payload`);\n      return v;\n    }\n  }\n}\n\n// ---- semantic engine (shared by oracle and decoder) --------------------------\n\nexport class Receiver {\n  private readonly schema: Schema;\n  private readonly state: Uint8Array; // 0 unseen, 1 streaming, 2 done\n  private readonly acc: Array<string | string[]>;\n  private readonly events: Event[] = [];\n  private readonly onEvent: ((event: Event) => void) | undefined;\n  private ended = false;\n\n  constructor(schema: Schema, onEvent?: (event: Event) => void) {\n    this.schema = schema;\n    this.onEvent = onEvent;\n    this.state = new Uint8Array(schema.length);\n    this.acc = new Array(schema.length);\n  }\n\n  append(field: number, payload: string): void {\n    this.assertActive();\n    this.assertField(field);\n    if (this.state[field] === 2) {\n      throw new Error(`field ${field}: append after completion`);\n    }\n    const def = this.schema[field]!;\n    if (def.mode === \"array\") {\n      const items = (this.acc[field] ??= []) as string[];\n      const maxItems = def.maxItems as number;\n      if (items.length >= maxItems) {\n        throw new Error(`field ${field}: exceeds maxItems=${maxItems}`);\n      }\n      if (def.maxLength !== undefined && payload.length > def.maxLength) {\n        throw new Error(`field ${field}: item exceeds maxLength=${def.maxLength}`);\n      }\n      items.push(payload);\n    } else {\n      const current = (this.acc[field] ??= \"\") as string;\n      if (def.maxLength !== undefined && current.length + payload.length > def.maxLength) {\n        throw new Error(`field ${field}: exceeds maxLength=${def.maxLength}`);\n      }\n      this.acc[field] = current + payload;\n    }\n    this.state[field] = 1;\n  }\n\n  complete(field: number): void {\n    this.assertActive();\n    this.assertField(field);\n    if (this.state[field] === 2) {\n      throw new Error(`field ${field}: completed twice`);\n    }\n    const def = this.schema[field]!;\n    if (this.state[field] === 0) {\n      if (def.type !== \"string\" && def.mode !== \"array\") {\n        throw new Error(`field ${field}: cannot complete an empty ${def.type} field`);\n      }\n      this.state[field] = 2;\n      this.emit({ kind: \"field\", field, value: def.mode === \"array\" ? [] : \"\" });\n      return;\n    }\n    this.state[field] = 2;\n    this.emit({\n      kind: \"field\",\n      field,\n      value: materialize(this.schema, field, this.acc[field] as string | string[]),\n    });\n  }\n\n  objectComplete(): void {\n    this.assertActive();\n    this.ended = true;\n    this.emit({ kind: \"object-complete\" });\n  }\n\n  objectAbort(): void {\n    this.assertActive();\n    this.ended = true;\n    this.emit({ kind: \"object-abort\" });\n  }\n\n  getEvents(): Event[] {\n    return this.events;\n  }\n\n  get isEnded(): boolean {\n    return this.ended;\n  }\n\n  private assertActive(): void {\n    if (this.ended) throw new Error(\"object already ended\");\n  }\n\n  private assertField(field: number): void {\n    if (field < 0 || field >= this.schema.length) {\n      throw new Error(`unknown field ${field}`);\n    }\n  }\n\n  private emit(event: Event): void {\n    this.events.push(event);\n    this.onEvent?.(event);\n  }\n}\n\nfunction materialize(schema: Schema, field: number, raw: string | string[]): FieldValue {\n  const def = schema[field]!;\n  if (def.mode === \"array\") {\n    return (raw as string[]).map((item) => parseTyped(def.type, item, field));\n  }\n  return parseTyped(def.type, raw as string, field);\n}\n\n/** The oracle: execute logical records directly. */\nexport function executeRecords(schema: Schema, records: StreamRecord[]): Event[] {\n  const receiver = new Receiver(schema);\n  for (const record of records) {\n    switch (record.kind) {\n      case \"append\":\n        receiver.append(record.field, record.payload);\n        break;\n      case \"complete\":\n        receiver.complete(record.field);\n        break;\n      case \"object-complete\":\n        receiver.objectComplete();\n        break;\n      case \"object-abort\":\n        receiver.objectAbort();\n        break;\n    }\n  }\n  if (!receiver.isEnded) throw new Error(\"stream ended before object completion\");\n  return receiver.getEvents();\n}\n\n// ---- materialization ----------------------------------------------------------\n\nexport function materializeObject(schema: Schema, events: Event[]): Record<string, unknown> {\n  const object: Record<string, unknown> = {};\n  for (const event of events) {\n    if (event.kind !== \"field\") continue;\n    setPath(object, schema[event.field]!.path, event.value);\n  }\n  return object;\n}\n\nfunction setPath(object: Record<string, unknown>, path: string[], value: unknown): void {\n  let target = object;\n  for (let i = 0; i < path.length - 1; i++) {\n    const key = path[i]!;\n    if (typeof target[key] !== \"object\" || target[key] === null) {\n      target[key] = {};\n    }\n    target = target[key] as Record<string, unknown>;\n  }\n  target[path[path.length - 1]!] = value;\n}\n\n// ---- reference text encoding (spec \u00A78) ----------------------------------------\n\nexport function encodeText(records: StreamRecord[]): string {\n  let out = \"\";\n  for (const record of records) {\n    switch (record.kind) {\n      case \"append\":\n        out += `${record.field}:${record.payload.length}:${record.payload};`;\n        break;\n      case \"complete\":\n        out += `!${record.field};`;\n        break;\n      case \"object-complete\":\n        out += \"!;\";\n        break;\n      case \"object-abort\":\n        out += \"~;\";\n        break;\n    }\n  }\n  return out;\n}\n\n// ---- reference decoder ----------------------------------------------------------\n\n/**\n * The contract every implementation (including the future arena-backed\n * receiver) must satisfy:\n *\n *   push(fragment(encodeText(records))) + end()  ===  executeRecords(schema, records)\n */\nexport interface Decoder {\n  push(chunk: string): void;\n  end(): Event[];\n}\n\ntype ParserState = \"header\" | \"field-id\" | \"length\" | \"payload\" | \"payload-end\" | \"control\" | \"abort\";\n\nexport class ReferenceDecoder implements Decoder {\n  private readonly receiver: Receiver;\n  private state: ParserState = \"header\";\n  private fieldId = \"\";\n  private length = \"\";\n  private payload = \"\";\n  private remaining = 0;\n\n  constructor(schema: Schema, onEvent?: (event: Event) => void) {\n    this.receiver = new Receiver(schema, onEvent);\n  }\n\n  push(chunk: string): void {\n    for (let i = 0; i < chunk.length; i++) {\n      const c = chunk[i]!;\n      switch (this.state) {\n        case \"header\":\n          this.onHeader(c);\n          break;\n        case \"field-id\":\n          this.onFieldId(c);\n          break;\n        case \"length\":\n          this.onLength(c);\n          break;\n        case \"payload\":\n          this.onPayload(c);\n          break;\n        case \"payload-end\":\n          this.onPayloadEnd(c);\n          break;\n        case \"control\":\n          this.onControl(c);\n          break;\n        case \"abort\":\n          this.onAbort(c);\n          break;\n      }\n    }\n  }\n\n  end(): Event[] {\n    if (!this.receiver.isEnded) throw new Error(\"stream ended before object completion\");\n    return this.receiver.getEvents();\n  }\n\n  private onHeader(c: string): void {\n    if (isDigit(c)) {\n      this.reset();\n      this.fieldId = c;\n      this.state = \"field-id\";\n      return;\n    }\n    if (c === \"!\") {\n      this.reset();\n      this.state = \"control\";\n      return;\n    }\n    if (c === \"~\") {\n      this.state = \"abort\";\n      return;\n    }\n    throw new Error(`expected record start, got ${JSON.stringify(c)}`);\n  }\n\n  private onFieldId(c: string): void {\n    if (isDigit(c)) {\n      this.fieldId += c;\n      return;\n    }\n    if (c === \":\") {\n      this.state = \"length\";\n      return;\n    }\n    throw new Error(`expected ':' after field id, got ${JSON.stringify(c)}`);\n  }\n\n  private onLength(c: string): void {\n    if (isDigit(c)) {\n      this.length += c;\n      return;\n    }\n    if (c === \":\") {\n      if (this.length === \"\") throw new Error(\"empty payload length\");\n      this.remaining = Number(this.length);\n      this.payload = \"\";\n      this.state = this.remaining === 0 ? \"payload-end\" : \"payload\";\n      return;\n    }\n    throw new Error(`expected ':' after length, got ${JSON.stringify(c)}`);\n  }\n\n  private onPayload(c: string): void {\n    this.payload += c;\n    if (--this.remaining === 0) this.state = \"payload-end\";\n  }\n\n  private onPayloadEnd(c: string): void {\n    if (c !== \";\") throw new Error(`expected ';' after payload, got ${JSON.stringify(c)}`);\n    this.receiver.append(Number(this.fieldId), this.payload);\n    this.state = \"header\";\n  }\n\n  private onControl(c: string): void {\n    if (isDigit(c)) {\n      this.fieldId += c;\n      return;\n    }\n    if (c === \";\") {\n      if (this.fieldId === \"\") this.receiver.objectComplete();\n      else this.receiver.complete(Number(this.fieldId));\n      this.state = \"header\";\n      return;\n    }\n    throw new Error(`expected field id or ';' after '!', got ${JSON.stringify(c)}`);\n  }\n\n  private onAbort(c: string): void {\n    if (c !== \";\") throw new Error(`expected ';' after '~', got ${JSON.stringify(c)}`);\n    this.receiver.objectAbort();\n    this.state = \"header\";\n  }\n\n  private reset(): void {\n    this.fieldId = \"\";\n    this.length = \"\";\n    this.payload = \"\";\n    this.remaining = 0;\n  }\n}\n\nfunction isDigit(c: string): boolean {\n  return c >= \"0\" && c <= \"9\";\n}\n\n/** Decode a sequence of transport chunks into events. */\nexport function decode(chunks: string[], schema: Schema): Event[] {\n  const decoder = new ReferenceDecoder(schema);\n  for (const chunk of chunks) decoder.push(chunk);\n  return decoder.end();\n}\n\n// ---- test utilities: rng, fragmentation, generators ----------------------------\n\nexport type Rng = () => number;\n\nexport function mulberry32(seed: number): Rng {\n  let a = seed >>> 0;\n  return () => {\n    a = (a + 0x6d2b79f5) >>> 0;\n    let t = a;\n    t = Math.imul(t ^ (t >>> 15), t | 1);\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\nexport function fragment(text: string, rng: Rng): string[] {\n  const cuts: number[] = [];\n  for (let i = 1; i < text.length; i++) {\n    if (rng() < 0.3) cuts.push(i);\n  }\n  const chunks: string[] = [];\n  let prev = 0;\n  for (const cut of cuts) {\n    chunks.push(text.slice(prev, cut));\n    prev = cut;\n  }\n  chunks.push(text.slice(prev));\n  return chunks;\n}\n\n/** Every single-cut fragmentation of a message. */\nexport function allSingleCuts(text: string): string[][] {\n  const out: string[][] = [];\n  for (let i = 1; i < text.length; i++) {\n    out.push([text.slice(0, i), text.slice(i)]);\n  }\n  return out;\n}\n\n/** Every composition into 1..n chunks \u2014 2^(n-1) cases. Only for small messages. */\nexport function allCompositions(text: string): string[][] {\n  const out: string[][] = [];\n  for (let mask = 0; mask < 1 << (text.length - 1); mask++) {\n    const chunks: string[] = [];\n    let prev = 0;\n    for (let i = 1; i < text.length; i++) {\n      if (mask & (1 << (i - 1))) {\n        chunks.push(text.slice(prev, i));\n        prev = i;\n      }\n    }\n    chunks.push(text.slice(prev));\n    out.push(chunks);\n  }\n  return out;\n}\n\n// ---- random valid stream generators ----------------------------------------------\n\nconst TYPES: FieldType[] = [\"string\", \"integer\", \"number\", \"boolean\"];\nconst ALPHABET = \"abZ09;:!~ \u00E9\uD83D\uDE00\"; // protocol punctuation inside payloads + astral chars\n\nexport function randomSchema(rng: Rng): Schema {\n  const count = 1 + Math.floor(rng() * 4);\n  const schema: Schema = [];\n  for (let i = 0; i < count; i++) {\n    const type = TYPES[Math.floor(rng() * TYPES.length)]!;\n    const isArray = rng() < 0.4;\n    schema.push({\n      path: [`f${i}`],\n      type,\n      ...(isArray ? { mode: \"array\" as const, maxItems: 1 + Math.floor(rng() * 4) } : {}),\n      ...(rng() < 0.8 ? { maxLength: 1 + Math.floor(rng() * 16) } : {}),\n    });\n  }\n  return schema;\n}\n\nfunction randomString(rng: Rng, cap: number): string {\n  let s = \"\";\n  while (s.length < cap && rng() < 0.85) {\n    s += ALPHABET[Math.floor(rng() * ALPHABET.length)]!;\n  }\n  return s;\n}\n\nfunction randomTyped(rng: Rng, type: FieldType, cap: number): string {\n  switch (type) {\n    case \"string\":\n      return rng() < 0.15 ? \"\" : randomString(rng, cap);\n    case \"integer\":\n      return String(Math.floor(rng() * 2000) - 1000);\n    case \"number\": {\n      const r = rng();\n      if (r < 0.4) return String(Math.floor(rng() * 2000) - 1000);\n      if (r < 0.7) return String(Math.round((rng() * 2000 - 1000) * 100) / 100);\n      return String((rng() * 2 - 1) * 1e10);\n    }\n    case \"boolean\":\n      return rng() < 0.5 ? \"0\" : \"1\";\n  }\n}\n\n/** A payload that satisfies the type and (when set) the length cap. */\nfunction payloadFor(rng: Rng, type: FieldType, cap: number | undefined): string {\n  const limit = cap ?? 12;\n  for (let i = 0; i < 100; i++) {\n    const p = randomTyped(rng, type, limit);\n    if (p.length <= limit) return p;\n  }\n  return type === \"string\" ? \"\" : \"0\";\n}\n\nfunction splitFragments(s: string, count: number): string[] {\n  if (s.length === 0) return [];\n  const chunks: string[] = [];\n  let prev = 0;\n  for (let i = 1; i < count; i++) {\n    const cut = Math.floor((i * s.length) / count);\n    chunks.push(s.slice(prev, cut));\n    prev = cut;\n  }\n  chunks.push(s.slice(prev));\n  return chunks.filter((c) => c.length > 0);\n}\n\n/** Records for one field: appends (one item each for arrays), maybe a completion. */\nexport function fieldRecords(rng: Rng, schema: Schema, field: number): StreamRecord[] {\n  const def = schema[field]!;\n  const records: StreamRecord[] = [];\n\n  if (def.mode === \"array\") {\n    const maxItems = def.maxItems as number;\n    const count = Math.floor(rng() * (maxItems + 1));\n    for (let i = 0; i < count; i++) {\n      records.push({ kind: \"append\", field, payload: payloadFor(rng, def.type, def.maxLength) });\n    }\n    if (rng() < 0.8) records.push({ kind: \"complete\", field });\n    return records;\n  }\n\n  // scalar: generate the final payload, then fragment it across appends\n  const total = payloadFor(rng, def.type, def.maxLength);\n  const fragments = splitFragments(total, 1 + Math.floor(rng() * 4));\n  for (const fragment of fragments) {\n    records.push({ kind: \"append\", field, payload: fragment });\n  }\n\n  const canCompleteEmpty = def.type === \"string\";\n  const hasContent = records.length > 0;\n  if (hasContent ? rng() < 0.85 : canCompleteEmpty && rng() < 0.5) {\n    records.push({ kind: \"complete\", field });\n  }\n  return records;\n}\n\n/** A valid record sequence for the schema, randomly scheduled. */\nexport function generateValidRecords(rng: Rng, schema: Schema): StreamRecord[] {\n  const queues = schema.map((_, field) => ({\n    field,\n    records: fieldRecords(rng, schema, field),\n    pos: 0,\n  }));\n  const out: StreamRecord[] = [];\n  let remaining = queues.reduce((n, q) => n + q.records.length, 0);\n\n  while (remaining > 0) {\n    let queue = queues[Math.floor(rng() * queues.length)]!;\n    while (queue.pos >= queue.records.length) {\n      queue = queues[(queue.field + 1) % queues.length]!;\n    }\n    out.push(queue.records[queue.pos]!);\n    queue.pos++;\n    remaining--;\n  }\n\n  out.push(rng() < 0.1 ? { kind: \"object-abort\" } : { kind: \"object-complete\" });\n  return out;\n}\n"],
+  "mappings": "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",
+  "names": ["INTEGER_RE", "NUMBER_RE", "parseIntegerPayload", "s", "n", "__name", "parseNumberPayload", "parseBooleanPayload", "parseTyped", "type", "field", "v", "Receiver", "schema", "onEvent", "payload", "def", "items", "maxItems", "current", "materialize", "event", "raw", "item", "executeRecords", "records", "receiver", "record", "materializeObject", "events", "object", "setPath", "path", "value", "target", "key", "encodeText", "out", "ReferenceDecoder", "chunk", "i", "c", "isDigit", "decode", "chunks", "decoder", "mulberry32", "seed", "a", "fragment", "text", "rng", "cuts", "prev", "cut", "allSingleCuts", "allCompositions", "mask", "TYPES", "ALPHABET", "randomSchema", "count", "isArray", "randomString", "cap", "randomTyped", "r", "payloadFor", "limit", "p", "splitFragments", "fieldRecords", "total", "fragments", "canCompleteEmpty", "generateValidRecords", "queues", "_", "remaining", "q", "queue"]
+}

package/dist/esm/transport/streamobject/stream-object/index.js

@@ -0,0 +1,2 @@
+import{StreamObject as t}from"./stream-object.js";export{t as StreamObject};
+//# sourceMappingURL=index.js.map

package/dist/esm/transport/streamobject/stream-object/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/stream-object/index.ts"],
+  "sourcesContent": ["export { StreamObject } from \"./stream-object\";\nexport type {\n  ErrorHandler,\n  FieldHandler,\n  ItemHandler,\n  ObjectDoneHandler,\n  StreamObjectOptions,\n} from \"./stream-object\";\n"],
+  "mappings": "AAAA,OAAS,gBAAAA,MAAoB",
+  "names": ["StreamObject"]
+}

package/dist/esm/transport/streamobject/stream-object/stream-object.js

@@ -0,0 +1,2 @@
+var n=Object.defineProperty;var r=(i,a)=>n(i,"name",{value:a,configurable:!0});import{FieldStream as c}from"../field-stream/field-stream.js";import{JsonToStreamObjectAdapter as l}from"../json-adapter/json-adapter.js";class h extends c{constructor(o,e,t={}){super(e,t);this.source=o}source;static{r(this,"StreamObject")}started=!1;async start(){if(this.started)throw new Error("StreamObject already started");this.started=!0;const o=new l(this.schema,{onFieldDone:r((e,t)=>this.emitField(e,t),"onFieldDone"),onItemDone:r((e,t,s)=>this.emitItem(e,t,s),"onItemDone"),onObjectDone:r(()=>this.emitObject(o.getEvents()),"onObjectDone")});try{for await(const e of this.source){if(this.cancelled)break;for(let t=0;t<e.length&&!this.cancelled;t++)o.push(e[t])}if(!this.cancelled&&!this.objectCompleted)throw new Error("stream ended before object completion")}catch(e){if(this.cancelled)return;this.fail(e)}}}export{h as StreamObject};
+//# sourceMappingURL=stream-object.js.map

package/dist/esm/transport/streamobject/stream-object/stream-object.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/stream-object/stream-object.ts"],
+  "sourcesContent": ["/**\n * StreamObject \u2014 consumes an AsyncIterable of text chunks through the\n * incremental JSON adapter and exposes the FieldStream completion API.\n *\n *   const stream = new StreamObject(source, schema);\n *   stream.when(\"summary\", (summary) => { ... });            // field completion\n *   stream.whenItem(\"searchQueries\", (query, i) => { ... }); // item completion\n *   stream.whenObjectDone((object) => { ... });              // whole object\n *   stream.onError((error) => { ... });                      // failures\n *   await stream.start();\n *\n * `when` means completion, not mutation: handlers never see chunks, JSON,\n * SSE, or the wire codec. Handlers are invoked synchronously at the\n * completion boundary and never block the source; async handlers run\n * concurrently and their rejections are routed to onError. `cancel()` stops\n * the source and invokes the optional onCancel hook (e.g. to abort the\n * producer's request).\n *\n * Errors: delivered to onError handlers when registered; otherwise start()\n * rejects with the error. Cancelling the stream is not an error.\n */\n\nimport { FieldStream, type FieldStreamOptions } from \"../field-stream/field-stream\";\nimport { JsonToStreamObjectAdapter } from \"../json-adapter/json-adapter\";\nimport type { Schema } from \"../reference/reference\";\n\nexport type {\n  ErrorHandler,\n  FieldHandler,\n  FieldStreamOptions,\n  ItemHandler,\n  ObjectDoneHandler,\n} from \"../field-stream/field-stream\";\n\nexport type StreamObjectOptions = FieldStreamOptions;\n\nexport class StreamObject extends FieldStream {\n  private started = false;\n\n  constructor(\n    private readonly source: AsyncIterable<string>,\n    schema: Schema,\n    options: StreamObjectOptions = {},\n  ) {\n    super(schema, options);\n  }\n\n  async start(): Promise<void> {\n    if (this.started) throw new Error(\"StreamObject already started\");\n    this.started = true;\n\n    const adapter = new JsonToStreamObjectAdapter(this.schema, {\n      onFieldDone: (field, value) => this.emitField(field, value),\n      onItemDone: (field, index, value) => this.emitItem(field, index, value),\n      onObjectDone: () => this.emitObject(adapter.getEvents()),\n    });\n\n    try {\n      for await (const chunk of this.source) {\n        if (this.cancelled) break;\n        for (let i = 0; i < chunk.length; i++) {\n          if (this.cancelled) break;\n          adapter.push(chunk[i]!);\n        }\n      }\n      if (!this.cancelled && !this.objectCompleted) {\n        throw new Error(\"stream ended before object completion\");\n      }\n    } catch (error) {\n      if (this.cancelled) return; // intended cancellation (e.g. producer aborted)\n      this.fail(error);\n    }\n  }\n}\n"],
+  "mappings": "+EAsBA,OAAS,eAAAA,MAA4C,+BACrD,OAAS,6BAAAC,MAAiC,+BAanC,MAAMC,UAAqBF,CAAY,CAG5C,YACmBG,EACjBC,EACAC,EAA+B,CAAC,EAChC,CACA,MAAMD,EAAQC,CAAO,EAJJ,YAAAF,CAKnB,CALmB,OAxCrB,MAoC8C,CAAAG,EAAA,qBACpC,QAAU,GAUlB,MAAM,OAAuB,CAC3B,GAAI,KAAK,QAAS,MAAM,IAAI,MAAM,8BAA8B,EAChE,KAAK,QAAU,GAEf,MAAMC,EAAU,IAAIN,EAA0B,KAAK,OAAQ,CACzD,YAAaK,EAAA,CAACE,EAAOC,IAAU,KAAK,UAAUD,EAAOC,CAAK,EAA7C,eACb,WAAYH,EAAA,CAACE,EAAOE,EAAOD,IAAU,KAAK,SAASD,EAAOE,EAAOD,CAAK,EAA1D,cACZ,aAAcH,EAAA,IAAM,KAAK,WAAWC,EAAQ,UAAU,CAAC,EAAzC,eAChB,CAAC,EAED,GAAI,CACF,gBAAiBI,KAAS,KAAK,OAAQ,CACrC,GAAI,KAAK,UAAW,MACpB,QAASC,EAAI,EAAGA,EAAID,EAAM,QACpB,MAAK,UADuBC,IAEhCL,EAAQ,KAAKI,EAAMC,CAAC,CAAE,CAE1B,CACA,GAAI,CAAC,KAAK,WAAa,CAAC,KAAK,gBAC3B,MAAM,IAAI,MAAM,uCAAuC,CAE3D,OAASC,EAAO,CACd,GAAI,KAAK,UAAW,OACpB,KAAK,KAAKA,CAAK,CACjB,CACF,CACF",
+  "names": ["FieldStream", "JsonToStreamObjectAdapter", "StreamObject", "source", "schema", "options", "__name", "adapter", "field", "value", "index", "chunk", "i", "error"]
+}

package/dist/types/agents/agent.d.ts

@@ -2,6 +2,8 @@ import { Tool } from "./tools/tools.js";
 import type { LLM, LLMMessage } from "../providers/llm/types.js";
 export interface AgentOptions {
     name: string;
+    /** Names a participant might use to address this agent. */
+    aliases?: string[];
     context?: string;
     tools?: Tool<never, unknown>[];
     /** LLM provider used by `run()`. Injected by `Pipeflow.agent()`. */
@@ -40,6 +42,7 @@ export interface AgentRunResult {
  */
 export declare class Agent {
     readonly name: string;
+    readonly aliases: string[];
     readonly context: string;
     private readonly toolRegistry;
     /** LLM provider used by `run()` and the orchestrator. */

package/dist/types/agents/tools/tools.d.ts

@@ -1,9 +1,30 @@
-export interface ToolOptions<TArgs, TResult> {
+import { z } from "zod";
+/**
+ * Zod schemas for a tool's arguments. `in` shapes what the model sends (and
+ * derives the LLM-facing JSON schema); `out` is what `execute` receives after
+ * validation. Keeping them separate means `in` stays plain JSON-schema-able
+ * while `out` may transform, normalize, or narrow.
+ */
+export interface ToolSchema<TOut, TIn> {
+    /** What the model sends — derives the LLM-facing JSON schema. */
+    in: z.ZodType<TIn>;
+    /** What `execute` receives, validated at run time. Defaults to `in`. */
+    out?: z.ZodType<TOut>;
+}
+export interface ToolOptions<TOut, TResult, TIn> {
     name: string;
     description: string;
-    /** JSON schema describing the arguments for the LLM. */
+    /**
+     * Zod schemas for the tool arguments — the single source of truth: `in`
+     * derives the LLM-facing JSON schema (`parameters`), and `out` (defaulting
+     * to `in`) validates the arguments at `execute()` time, so a model sending
+     * garbage surfaces a clear tool error instead of a crash inside the tool.
+     * Mutually exclusive with `parameters`.
+     */
+    schema?: ToolSchema<TOut, TIn>;
+    /** JSON schema describing the arguments for the LLM (no runtime validation). */
     parameters?: Record<string, unknown>;
-    execute: (args: TArgs) => TResult | Promise<TResult>;
+    execute: (args: TOut) => TResult | Promise<TResult>;
 }
 /**
  * A capability exposed by the application to an agent.
@@ -11,12 +32,13 @@ export interface ToolOptions<TArgs, TResult> {
  * Tools execute in the application's backend: Pipeflow never runs
  * application code directly.
  */
-export declare class Tool<TArgs = Record<string, unknown>, TResult = unknown> {
+export declare class Tool<TOut = Record<string, unknown>, TResult = unknown, TIn = TOut> {
     readonly name: string;
     readonly description: string;
     readonly parameters: Record<string, unknown> | undefined;
+    private readonly parse;
     private readonly executor;
-    constructor(options: ToolOptions<TArgs, TResult>);
+    constructor(options: ToolOptions<TOut, TResult, TIn>);
     /** Execute the tool. Sync throws and rejections both surface as rejections. */
-    execute(args: TArgs): Promise<TResult>;
+    execute(args: TIn): Promise<TResult>;
 }

package/dist/types/conversations/conversation/conversation.d.ts

@@ -1,12 +1,22 @@
 import type { Agent } from "../../agents/agent.js";
 import type { Persistence } from "../../persistence/persistence.js";
+import type { STT } from "../../providers/stt/types.js";
+import type { TTS } from "../../providers/tts/types.js";
 import type { AudioChunk, ConversationId, ConversationState, ConversationStatus, Generation, Participant, ParticipantInput, Turn, UserId } from "../types.js";
 import { Transcription, type TranscriptEntry, type TranscriptEntryInput } from "../transcription/transcription.js";
 import type { ToolCall, ToolCallResult } from "../types.js";
+/** Timing points a generation can record, keyed by the stream event. */
+type TimingPoint = "firstToken" | "firstTtsText" | "firstTtsRequest" | "firstTtsAudio";
 export interface ConversationOptions {
     id: ConversationId;
     agents?: Agent[];
     persistence?: Persistence;
+    /**
+     * STT provider used to attach realtime processing automatically on
+     * `start()`.
+     */
+    stt?: STT;
+    tts?: TTS;
 }
 export interface ConversationEvents {
     start: {
@@ -25,6 +35,12 @@ export interface ConversationEvents {
         userId: UserId;
         audio: AudioChunk;
     };
+    /** A finalized text turn via `send()`. Consumed by the orchestrator. */
+    "text-in": {
+        conversationId: ConversationId;
+        userId: UserId;
+        text: string;
+    };
     /** Generated audio to be played by the application. */
     audio: {
         conversationId: ConversationId;
@@ -42,6 +58,20 @@ export interface ConversationEvents {
         conversationId: ConversationId;
         generation: Generation;
     };
+    /**
+     * The current generation's text, streamed as LLM deltas arrive. Emitted by
+     * the orchestrator; the agent name is included when the generation is known.
+     */
+    "text-delta": {
+        conversationId: ConversationId;
+        text: string;
+        agentName?: string;
+    };
+    /** The current (top-level) generation finished generating. */
+    "generation-complete": {
+        conversationId: ConversationId;
+        generation: Generation;
+    };
     /** Live STT partials, for captions and fast UX. Not persisted. */
     "partial-transcript": {
         conversationId: ConversationId;
@@ -75,10 +105,11 @@ export interface ConversationEvents {
  * The public realtime conversation API.
  *
  * A `Conversation` is a runtime handle to a persistent conversation:
- * lifecycle (`start`/`stop`), participants, audio intake (`listen`), and
- * events. The orchestrator (added later) subscribes to `audio-in` and
- * pushes generated audio, turns, transcripts, and tool calls back through
- * the `push*`/`requestToolCall` methods.
+ * lifecycle (`start`/`stop`), participants, audio intake (`listen`), text
+ * turns (`send`), and events. When an STT provider or agents are configured,
+ * `start()` automatically attaches the orchestrator, which runs the
+ * STT/LLM/TTS pipeline (or routes text turns) and pushes generated audio,
+ * turns, transcripts, and tool calls back through conversation events.
  */
 export declare class Conversation {
     readonly id: ConversationId;
@@ -86,13 +117,21 @@ export declare class Conversation {
     readonly transcription: Transcription;
     readonly state: ConversationState;
     private readonly persistence;
+    private readonly stt;
+    private readonly tts;
     private readonly listeners;
     private readonly pendingToolCallsById;
+    private readonly subGenerations;
     private nextAudioSequence;
     constructor(options: ConversationOptions);
     get status(): ConversationStatus;
     get participants(): Participant[];
-    start(): void;
+    /**
+     * Move the conversation into the started state. This attaches the
+     * orchestrator whenever there is realtime work: an STT provider (voice
+     * pipeline) or agents to route text turns to (`send()`).
+     */
+    start(): Promise<void>;
     stop(): Promise<void>;
     participate(input: ParticipantInput | ParticipantInput[]): Promise<Participant[]>;
     /**
@@ -103,7 +142,22 @@ export declare class Conversation {
         userId: UserId;
         audio: Uint8Array;
     }): void;
-    /** Interrupt the current agent output (stop TTS, cancel the generation). */
+    /**
+     * Send a finalized text turn, bypassing STT. Triggers the same pipeline as
+     * a transcribed utterance (routing, coordination, generation, resume) —
+     * useful for text-first integrations such as chat or Discord text channels.
+     */
+    send(input: {
+        userId: UserId;
+        text: string;
+    }): void;
+    /**
+     * Stop the currently active generation and prevent any further generated
+     * audio from reaching the conversation. The orchestrator cancels the LLM
+     * and TTS streams, force-resolves pending tool calls, and discards queued
+     * audio; the next participant turn starts fresh. Interrupt responsiveness
+     * is a tested invariant — audio stops within ~100ms of this call.
+     */
     interrupt(): void;
     on<K extends keyof ConversationEvents>(event: K, listener: (payload: ConversationEvents[K]) => void): () => void;
     /**
@@ -117,8 +171,20 @@ export declare class Conversation {
     pushTurn(turn: Turn): Promise<void>;
     /** Append a transcript entry and notify listeners. */
     pushTranscript(input: Omit<TranscriptEntryInput, "conversationId">): Promise<TranscriptEntry>;
+    /**
+     * Stream the current generation's text, as produced by the orchestrator
+     * from LLM deltas. Emits the `text-delta` event so applications can render
+     * or act on partial replies.
+     */
+    pushTextDelta(text: string): void;
     /** Push an agent generation into the conversation. */
     pushGeneration(generation: Generation): Promise<void>;
+    /**
+     * Record a timing point on a generation. Without an id this targets the
+     * current generation; with one, a dispatched sub-generation. Each point is
+     * recorded at most once.
+     */
+    noteTiming(point: TimingPoint, generationId?: string): void;
     /** Tool calls requested by the model that are awaiting resolution. */
     get pendingToolCalls(): ToolCall[];
     /**
@@ -131,8 +197,21 @@ export declare class Conversation {
     resolveToolCall(result: ToolCallResult): void;
     /** Mark the current generation as completed, recording its final text. */
     completeGeneration(text?: string): Promise<void>;
+    /**
+     * Push a sub-generation: a task the coordinator dispatched to another
+     * agent. Unlike `pushGeneration`, it does not become the conversation's
+     * current generation, so parallel tasks don't clobber the coordinator's
+     * own in-flight generation.
+     */
+    pushSubGeneration(generation: Generation): Promise<void>;
+    /** Mark a dispatched sub-generation as completed with its final text. */
+    completeSubGeneration(id: string, text?: string): Promise<void>;
+    /** Mark a dispatched sub-generation as cancelled (e.g. barge-in). */
+    cancelSubGeneration(id: string): Promise<void>;
     /** The live in-memory transcript. */
     transcript(): TranscriptEntry[];
     private cancelCurrentGeneration;
+    private buildRealtime;
     private emitState;
 }
+export {};

package/dist/types/conversations/conversations.d.ts

@@ -1,18 +1,28 @@
 import type { Agent } from "../agents/agent.js";
 import type { Persistence } from "../persistence/persistence.js";
+import type { STT } from "../providers/stt/types.js";
+import type { TTS } from "../providers/tts/types.js";
 import type { ConversationId } from "./types.js";
 import type { TranscriptEntry } from "./transcription/transcription.js";
 import { Conversation } from "./conversation/conversation.js";
 export interface CreateConversationOptions {
     agents?: Agent[];
 }
+export interface ConversationsOptions {
+    persistence: Persistence;
+    /** Passed to conversations so `start()` can attach realtime processing. */
+    stt?: STT;
+    tts?: TTS;
+}
 /**
  * The conversations API surface of a Pipeflow instance: create persistent
  * conversations and retrieve their transcripts.
  */
 export declare class Conversations {
     private readonly persistence;
-    constructor(persistence: Persistence);
+    private readonly stt;
+    private readonly tts;
+    constructor(options: ConversationsOptions);
     /** Create a persistent conversation. Realtime execution is separate. */
     create(options?: CreateConversationOptions): Promise<Conversation>;
     /** Retrieve the persisted transcript of a conversation. */

package/dist/types/conversations/index.d.ts

@@ -1,4 +1,4 @@
-export type { AudioChunk, ConversationId, ConversationState, ConversationStatus, Generation, GenerationStatus, Participant, ParticipantInput, ToolCall, ToolCallResult, Turn, TurnId, UserId, } from "./types.js";
+export type { AudioChunk, ConversationId, ConversationState, ConversationStatus, Generation, GenerationStatus, GenerationTiming, Participant, ParticipantInput, ToolCall, ToolCallResult, Turn, TurnId, UserId, } from "./types.js";
 export { createConversationState } from "./types.js";
 export { Conversation } from "./conversation/index.js";
 export type { ConversationEvents, ConversationOptions, } from "./conversation/index.js";
@@ -6,5 +6,6 @@ export { Conversations } from "./conversations.js";
 export type { CreateConversationOptions } from "./conversations.js";
 export { Orchestrator } from "./orchestration/orchestrator/index.js";
 export type { OrchestratorOptions } from "./orchestration/orchestrator/index.js";
+export { ConversationStream } from "./stream/index.js";
 export { Transcription, TranscriptEntry } from "./transcription/index.js";
 export type { TranscriptEntryInput, TranscriptSpeakerKind, } from "./transcription/index.js";

package/dist/types/conversations/orchestration/coordination/coordination.d.ts

@@ -0,0 +1,192 @@
+import type { Agent } from "../../../agents/agent.js";
+import type { LLM, LLMMessage, LLMToolDefinition } from "../../../providers/llm/types.js";
+/**
+ * One task delegated to an agent: a self-contained prompt for a roster member.
+ */
+export interface DelegatedTask {
+    agent: string;
+    prompt: string;
+}
+/**
+ * The outcome of a delegated agent run (or sub-coordination, via `error`).
+ */
+export interface DelegationResult {
+    agent: string;
+    text: string;
+    error?: string;
+}
+/** What a coordination's LLM may decide to do next. */
+export type DelegateAction = {
+    action: "agents";
+    tasks: DelegatedTask[];
+} | {
+    action: "coordination";
+    coordination: string;
+    input?: unknown;
+} | {
+    action: "clarify";
+    missing: string[];
+} | {
+    action: "user";
+    question: string;
+} | {
+    action: "complete";
+    output: string;
+};
+/**
+ * The runtime a coordination reasons against: the roster, every registered
+ * coordination, and the primitives for delegating work. Supplied by the
+ * orchestrator, so coordinations never couple to it directly.
+ */
+export interface CoordinationRuntime {
+    readonly agents: readonly Agent[];
+    readonly coordinations: readonly Coordination[];
+    /** Shared LLM used for coordination reasoning. */
+    readonly llm: LLM;
+    /** Shared conversation history, seeded into fresh runs. */
+    readonly history: readonly LLMMessage[];
+    /** Run one or more agents in parallel (text-only) and return their outputs. */
+    delegateAgentTasks(tasks: DelegatedTask[]): Promise<DelegationResult[]>;
+    /**
+     * Ask the user a question. Never returns: it throws `CoordinationSuspension`
+     * carrying the innermost frame, which the orchestrator catches to park the
+     * execution until the user answers.
+     */
+    askUser(frame: PendingFrame, question: string): Promise<never>;
+    /** Stream a delta to speech (TTS narration). */
+    onDelta(delta: string): void;
+    /** Flush pending narration (e.g. before delegating or suspending). */
+    flushSpeech(): void;
+    /** Speak a standalone sentence (e.g. a `complete` output). */
+    speak(sentence: string): void;
+    /** True once an interrupt/stop has cancelled this run. */
+    isCancelled(): boolean;
+    /** Throw if the run exceeded the coordination step budget. */
+    checkBudget(): void;
+}
+export interface CoordinationOptions {
+    name: string;
+    /** System prompt describing the coordination's reasoning role. */
+    prompt?: string;
+    /** Overrides the runtime's shared LLM for this coordination. */
+    llm?: LLM;
+    maxTokens?: number;
+    /** Hard wall-clock limit for a single run (including suspensions). */
+    maxDurationMs?: number;
+    /**
+     * Deterministic cap on user-question rounds per run (both the structured
+     * `clarify` action and open-ended `user` questions, across suspensions).
+     * Once exhausted, the coordination is told to state reasonable
+     * assumptions and complete. Defaults to 2.
+     */
+    maxQuestionRounds?: number;
+}
+/**
+ * A coordination registered in the orchestrator by name — the registry key
+ * is the coordination's name, so it is not repeated here.
+ */
+export type CoordinationRegistration = Omit<CoordinationOptions, "name">;
+/**
+ * Render a batched clarification question from the missing details, so the
+ * wording is deterministic regardless of how the model phrases the labels.
+ */
+export declare function renderClarifyQuestion(missing: string[]): string;
+/**
+ * The system prompt for a `clarify` coordination: a generic,
+ * domain-agnostic information-acquisition unit. It turns an underspecified
+ * request into a clear one by asking the user for missing details via the
+ * structured `clarify` action (batched), with a hard two-round cap enforced
+ * by the runtime. Register it alongside `understand`:
+ *
+ * ```ts
+ * coordinations: { clarify: { prompt: buildClarifyPrompt() } }
+ * ```
+ */
+export declare function buildClarifyPrompt(): string;
+/**
+ * The resumable state of one coordination invocation. Plain data so it can be
+ * parked in a `PendingExecution` while waiting for the user.
+ */
+export interface CoordinationState {
+    messages: LLMMessage[];
+    startedAt: number;
+    /** Everything the coordination has spoken so far, for the final record. */
+    narration: string;
+    /** How many user-question rounds this run has used (across suspensions). */
+    questionRounds: number;
+    /** Tool call id awaiting a sub-coordination result, for resume replies. */
+    pendingToolCallId?: string;
+}
+/** One frame of a suspended execution stack (outermost first). */
+export interface PendingFrame {
+    coordination: Coordination;
+    state: CoordinationState;
+}
+/** Thrown when a coordination asks the user; carries the whole frame stack. */
+export declare class CoordinationSuspension extends Error {
+    readonly frames: PendingFrame[];
+    readonly question: string;
+    constructor(frames: PendingFrame[], question: string);
+}
+/** Thrown when a coordination run is cancelled (interrupt/stop). */
+export declare class CoordinationCancelled extends Error {
+    constructor();
+}
+/** Thrown when a coordination exceeded its step or duration budget. */
+export declare class CoordinationBudgetExceeded extends Error {
+    constructor(detail: string);
+}
+/**
+ * The tool definition that lets a coordination's LLM choose the next execution
+ * target: agents (one or more, in parallel), another coordination, the user,
+ * or completion.
+ *
+ * The parameters are deliberately FLAT (action enum + optional fields) even
+ * though the parser enforces a discriminated union per action. Why: Amazon
+ * Bedrock (nova) ignores `oneOf` in tool input schemas, which makes the tool
+ * effectively empty — the model stops calling it and answers directly instead
+ * (measured: 0/2 tool calls and ~5k-token essays vs reliable ~1s calls with
+ * the flat shape). The flat schema works across every provider tested; the
+ * discriminated contract is enforced when the call is parsed, and an invalid
+ * combination costs one bounded retry rather than a broken tool.
+ */
+export declare function delegateToolDefinition(agents: readonly Agent[], coordinations: readonly Coordination[]): LLMToolDefinition;
+export declare function parseDelegateAction(argumentsJson: string, agents: readonly Agent[], coordinations: readonly Coordination[]): DelegateAction;
+/**
+ * A hardcoded reasoning/control-flow unit. Unlike an `Agent` (input → LLM →
+ * output), a coordination decides *what should happen next*: run agents, pass
+ * work to another coordination, ask the user, or complete. Definitions are
+ * stateless; each invocation carries its own `CoordinationState`, which can be
+ * parked (suspended) while waiting for the user and resumed later.
+ */
+export declare class Coordination {
+    readonly name: string;
+    readonly prompt: string;
+    readonly maxTokens: number | undefined;
+    readonly maxDurationMs: number | undefined;
+    readonly maxQuestionRounds: number;
+    private readonly runtime;
+    private readonly llm;
+    private cachedToolDefinition;
+    private cachedSchema;
+    constructor(options: CoordinationOptions, runtime: CoordinationRuntime);
+    /** The delegate tool definition, generated once from the roster. */
+    private toolDefinition;
+    /** Parse a `delegate` tool call against the roster's strict schema. */
+    private parseDelegate;
+    /** Run the coordination with fresh state (seeded with the shared history). */
+    run(input?: unknown): Promise<unknown>;
+    /** Resume a suspended state with the user's answer. */
+    resume(state: CoordinationState, answer: string): Promise<unknown>;
+    /** Continue a suspended state with an injected message (e.g. a sub-result). */
+    continueWith(state: CoordinationState, message: LLMMessage): Promise<unknown>;
+    /**
+     * The coordination loop: one LLM round trip per iteration, choosing the next
+     * execution target via the `delegate` tool. Throws `CoordinationSuspension`
+     * when asking the user; the state carried in the suspension is resumable.
+     */
+    private loop;
+    /** Delegate to a sub-coordination, attaching this frame on suspension. */
+    private delegateToCoordination;
+    private completeOutput;
+}

package/dist/types/conversations/orchestration/coordination/index.d.ts

@@ -0,0 +1,2 @@
+export { Coordination, CoordinationSuspension, CoordinationCancelled, CoordinationBudgetExceeded, delegateToolDefinition, parseDelegateAction, } from "./coordination.js";
+export type { CoordinationOptions, CoordinationRuntime, CoordinationState, DelegateAction, DelegatedTask, DelegationResult, PendingFrame, } from "./coordination.js";