@volter/teams 0.1.71 → 0.1.73

package/browser-channel.d.ts

@@ -46,11 +46,19 @@ export type BrowserTurnAnswer =
   | { code: 0; turn_id?: string; door?: 'runtime' | 'pane' | 'waiting'; text?: string }
   | { code: number; text?: string };
 
+/** The accepted stream ended without a valid receipt; delivery may have occurred. */
+export declare class TurnDeliveryUnconfirmedError extends Error {
+  constructor(message: string);
+}
+
 /**
  * One line typed into the channel's session as its user's own turn; rejects when the machine refuses the stream.
  * `turnKey`: one per typed line, reused on retry, so the machine types the line once.
+ * Receipt waits time out after thirty seconds. Cancellation stops waiting; it
+ * does not undo delivery. After acceptance, a lost, invalid or cancelled receipt
+ * rejects with TurnDeliveryUnconfirmedError. Reuse the same key when retrying it.
  */
-export function sendBrowserTurn(channel: BrowserChannel, text: string, options?: { turnKey?: string }): Promise<BrowserTurnAnswer>;
+export function sendBrowserTurn(channel: BrowserChannel, text: string, options?: { turnKey?: string; signal?: AbortSignal }): Promise<BrowserTurnAnswer>;
 
 export interface MailHistoryEntry {
   id: string; from: string; fromName: string; to: string; text: string; at: number;

package/browser-channel.mjs

@@ -167,19 +167,50 @@ export function openBrowserSession({ origin, teamId, sessionId, token }, { WebSo
   return connectBrowserChannel(socket, channel, `could not reach session ${sessionId} through ${origin}`, 'the server closed the session channel');
 }
 
+/** A turn was accepted by its stream, but its delivery receipt was not obtained. */
+export class TurnDeliveryUnconfirmedError extends Error {
+  constructor(message) { super(message); this.name = 'TurnDeliveryUnconfirmedError'; }
+}
+
 /**
  * One line typed into the channel's session as its user's own turn. Resolves with the machine's answer:
  * `{ code: 0, turn_id, door: 'runtime' | 'pane' | 'waiting' }` (waiting: filed, typed when the session's composer
  * is free), or `{ code, text }` when it was not delivered; rejects when the machine refuses the stream.
  * `turnKey`: one key per line the person typed, reused when they retry it, so a line the machine took after its
  * first send was given up on is not typed twice (a machine of door vocabulary 3 or later keeps each key once).
+ * Receipt waits are bounded to thirty seconds and 256 KB. `signal` cancels the
+ * wait; neither cancellation nor timeout undoes a turn already accepted.
  */
-export async function sendBrowserTurn(channel, text, { turnKey } = {}) {
+export async function sendBrowserTurn(channel, text, { turnKey, signal } = {}) {
+  signal?.throwIfAborted();
   const stream = await channel.open('mail', { request: { op: 'turn', text, ...(turnKey ? { turn_key: String(turnKey) } : {}) } });
-  return new Promise((resolve) => {
-    let answer = '';
-    stream.on('data', (chunk) => { answer += chunk; });
-    stream.on('close', () => { try { resolve(JSON.parse(answer)); } catch { resolve({ code: 1, text: answer || 'no answer from the machine' }); } });
+  return new Promise((resolve, reject) => {
+    let answer = '', settled = false;
+    const cleanup = () => { clearTimeout(timer); stream.off('data', data); stream.off('close', closed); signal?.removeEventListener('abort', cancelled); };
+    const fail = error => {
+      if (settled) return;
+      settled = true; cleanup(); reject(error);
+      // close emits synchronously. A failed wait must not parse an incomplete
+      // receipt as success, or imply that a typed turn was rolled back.
+      stream.close(error.message);
+    };
+    const cancelled = () => fail(new TurnDeliveryUnconfirmedError('Turn delivery wait cancelled'));
+    const timer = setTimeout(() => fail(new TurnDeliveryUnconfirmedError('Turn delivery acknowledgement timed out')), 30_000);
+    const data = chunk => { answer += chunk; if (answer.length > 256_000) fail(new TurnDeliveryUnconfirmedError('Turn delivery receipt too large')); };
+    const closed = reason => {
+      if (settled) return;
+      settled = true; cleanup();
+      // Only an actual machine answer establishes delivery or refusal. A socket
+      // closing, an incomplete JSON frame or an empty receipt cannot prove either.
+      try {
+        const receipt = JSON.parse(answer);
+        if (!receipt || !Number.isInteger(receipt.code)) throw new Error('Invalid receipt');
+        resolve(receipt);
+      } catch { reject(new TurnDeliveryUnconfirmedError(reason || 'No complete delivery receipt from the machine')); }
+    };
+    stream.on('data', data);
+    if (!settled) stream.on('close', closed);
+    if (!settled && signal) { signal.addEventListener('abort', cancelled, { once: true }); if (signal.aborted) cancelled(); }
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",