@unoverse-platform/studio 0.1.96 → 0.1.98

package/vendor/base/src/manifests/runtime/duplex/audioLane.ts

@@ -30,6 +30,51 @@ export interface AudioLane {
   setAudioDataHandler?(fn: (sessionId: string, data: ArrayBuffer) => void | Promise<void>): void;
   setControlMessageHandler?(fn: (sessionId: string, message: any) => void | Promise<void>): void;
   startAudioSession?(sessionId: string, conversationId: string): void;
+
+  /**
+   * WHAT THIS LANE SPEAKS, when it is not the browser.
+   *
+   * `rate` is the lane's sample rate and `codec` how its samples are packed. Absent means the
+   * browser lane's own shape (16 kHz PCM16), which is what every lane was until there was a
+   * second one.
+   *
+   * It is on the LANE and not in a node's config for a reason worth keeping: this is a fact of
+   * the far end, not a preference. A phone is 8 kHz mu-law because the phone network is, and a
+   * wrong value is an error nowhere — the vendor transcribes at the wrong speed and it reads as
+   * poor accuracy. Nobody choosing it can choose better than the lane already knows.
+   */
+  rate?: number;
+  codec?: "pcm16" | "mulaw";
+
+  /**
+   * IS ANYONE THERE YET? Resolves true once the far end is listening, false if it never will be.
+   *
+   * ABSENT MEANS ALREADY CONNECTED, which is the browser: the page dialled us, so its socket
+   * exists before the node runs and there is nothing to wait for. A lane that has to REACH
+   * someone is the other case, and the difference matters more than it sounds. A telephone rings
+   * for twenty or thirty seconds, and without this the vendor session opens immediately, the
+   * model speaks its opening line to a ringing tone, and by the time a person says hello the
+   * greeting has already happened and been thrown away (observed live 2026-09-20).
+   *
+   * `false` is a call that was never answered: busy, declined, or rung out. The session must not
+   * open at all for one of those, or a realtime model sits billing by the minute against a
+   * telephone nobody picked up.
+   */
+  whenConnected?(conversationId: string): Promise<boolean>;
+
+  /**
+   * END THE CALL AT THE FAR END. Not closing our socket to the vendor: that stops the MODEL,
+   * and the two are different things on every lane that reaches a person.
+   *
+   * ABSENT MEANS THERE IS NOTHING TO HANG UP, which is the browser: the page holds the session
+   * and closing it is the page's own business. A lane that REACHED someone is the other case,
+   * and until this existed it could not let them go. Measured live 2026-09-22: the model said
+   * goodbye, the vendor session closed on time, and the telephone stayed open with the person
+   * listening to silence until THEY hung up, because no code anywhere ran in this direction.
+   *
+   * Called once, from the session's `finish`, so every way a call can end ends the call.
+   */
+  hangUp?(conversationId: string): void;
 }
 
 
@@ -37,9 +82,67 @@ export interface AudioLane {
 const BYTES_PER_SAMPLE = 2;
 const DEFAULT_COALESCE_BYTES = 32768;
 const DEFAULT_COALESCE_MS = 50;
-/** What the browser captures at. Not configurable, because the capture side is ours. */
+/** What the browser captures at. The default when a lane does not declare its own rate. */
 export const CLIENT_RATE = 16000;
 
+/**
+ * G.711 mu-law, the codec of the telephone network, and the only non-PCM lane here.
+ *
+ * ONE BYTE PER SAMPLE instead of two, logarithmically companded: it spends its resolution
+ * where a human ear is sensitive and throws it away where it is not. That is why a phone call
+ * at 8 kHz and 64 kbit/s is intelligible at all, and also why converting is a TABLE rather than
+ * a scale — the relationship between a byte and a sample is not linear.
+ *
+ * Both directions are written out rather than pulled from a package, because the encoding is
+ * twelve lines, fixed since 1972, and a dependency that has to be audited is worse than a
+ * function that can be read. The tests are the reference: a round trip is lossy by design (16
+ * bits into 8 and back), so they assert closeness, never equality.
+ */
+const MULAW_BIAS = 0x84;
+const MULAW_CLIP = 32635;
+
+/** PCM16 sample -> one mu-law byte. */
+function encodeMulawSample(sample: number): number {
+  let sign = (sample >> 8) & 0x80;
+  if (sign !== 0) sample = -sample;
+  if (sample > MULAW_CLIP) sample = MULAW_CLIP;
+  sample += MULAW_BIAS;
+  // The exponent is the position of the highest set bit: mu-law is a floating point format
+  // with a 3-bit exponent and a 4-bit mantissa, which is exactly what the companding IS.
+  let exponent = 7;
+  for (let mask = 0x4000; (sample & mask) === 0 && exponent > 0; exponent--, mask >>= 1);
+  const mantissa = (sample >> (exponent + 3)) & 0x0f;
+  // Inverted on the wire, which is the part everyone forgets: a decoder fed un-inverted bytes
+  // produces sound, just the wrong sound, so nothing errors and the call is simply noise.
+  return ~(sign | (exponent << 4) | mantissa) & 0xff;
+}
+
+/** One mu-law byte -> PCM16 sample. */
+function decodeMulawByte(byte: number): number {
+  byte = ~byte & 0xff;
+  const sign = byte & 0x80;
+  const exponent = (byte >> 4) & 0x07;
+  const mantissa = byte & 0x0f;
+  let sample = ((mantissa << 3) + MULAW_BIAS) << exponent;
+  sample -= MULAW_BIAS;
+  return sign !== 0 ? -sample : sample;
+}
+
+/** A buffer of mu-law bytes -> PCM16 little-endian. One byte in, two bytes out. */
+export function mulawToPcm16(input: Buffer): Buffer {
+  const out = Buffer.alloc(input.length * BYTES_PER_SAMPLE);
+  for (let i = 0; i < input.length; i++) out.writeInt16LE(decodeMulawByte(input[i]), i * BYTES_PER_SAMPLE);
+  return out;
+}
+
+/** PCM16 little-endian -> mu-law bytes. Two bytes in, one byte out. */
+export function pcm16ToMulaw(input: Buffer): Buffer {
+  const samples = Math.floor(input.length / BYTES_PER_SAMPLE);
+  const out = Buffer.alloc(samples);
+  for (let i = 0; i < samples; i++) out[i] = encodeMulawSample(input.readInt16LE(i * BYTES_PER_SAMPLE));
+  return out;
+}
+
 /**
  * Resample PCM16 by linear interpolation.
  *
@@ -76,11 +179,50 @@ export function resamplePcm16(input: Buffer, fromRate: number, toRate: number):
  * audio must be thrown away, because the user is already talking over the sentence it belongs
  * to. Transcribed from the retired WebSocketAudioPublisher.
  */
+/**
+ * PCM16 at the vendor's rate -> whatever this lane speaks.
+ *
+ * IDENTITY FOR THE BROWSER LANE, and that is load-bearing rather than an optimisation. The
+ * browser lane declares no rate and no codec, so this returns the very same Buffer object it
+ * was given — byte for byte what shipped before there was a second lane, and what the long
+ * comment in `flush` below is about. A lane that says nothing gets nothing done to it.
+ */
+function forLane(lane: AudioLane, pcm: Buffer, vendorRate: number, passthrough = false): Buffer {
+  /**
+   * NOTHING TO DO, because the vendor is already speaking the lane's own codec.
+   *
+   * A telephone is 8 kHz mu-law and several vendors accept 8 kHz mu-law, so when a node says it
+   * asked for that (`in.laneCodecs` in api/audio.yaml) these bytes ARE the bytes to put on the
+   * wire. Converting them would decode to PCM, resample 8 kHz to 24 kHz and back, and re-encode,
+   * to arrive at audio no better than it started: a phone call cannot be made higher fidelity by
+   * being carried at a higher rate, only rounder at the edges.
+   *
+   * OPT-IN, and that is the point of the flag. A vendor that was never told to speak mu-law is
+   * still sending PCM, and passing that through would be noise at the wrong speed. Absent the
+   * declaration this is exactly the code that shipped.
+   */
+  if (passthrough) return pcm;
+  if (lane.rate === undefined && lane.codec === undefined) return pcm;
+  const resampled = resamplePcm16(pcm, vendorRate, lane.rate ?? CLIENT_RATE);
+  return lane.codec === "mulaw" ? pcm16ToMulaw(resampled) : resampled;
+}
+
 export function makeAudioBuffer(
   lane: AudioLane,
   conversationId: string,
   targetBytes = DEFAULT_COALESCE_BYTES,
   maxDelayMs = DEFAULT_COALESCE_MS,
+  /**
+   * What the VENDOR is sending, so `forLane` knows what it is converting FROM. Defaults to the
+   * browser's rate, which is also the no-conversion case, so an existing caller is unchanged.
+   */
+  vendorRate = CLIENT_RATE,
+  /**
+   * The vendor is sending this lane's OWN codec, so the frames need no conversion at all. Set
+   * by the session when a node's `in.laneCodecs` names what the lane speaks. Default false: an
+   * existing caller converts exactly as it always did.
+   */
+  passthrough = false,
 ) {
   let chunks: Buffer[] = [];
   let total = 0;
@@ -108,6 +250,20 @@ export function makeAudioBuffer(
     if (!chunks.length) return;
     const combined = Buffer.concat(chunks);
 
+    /**
+     * ONE BYTE PER SAMPLE, so there is no odd byte to hold back.
+     *
+     * Everything below is PCM16 arithmetic: two bytes per sample, an odd length is half a sample,
+     * and the client's `new Int16Array(buffer)` throws on one. Mu-law is one byte per sample, so
+     * every length is already whole and aligning would hold back a complete sample for no reason.
+     */
+    if (passthrough) {
+      chunks = [];
+      total = 0;
+      lane.sendAudio(conversationId, forLane(lane, combined, vendorRate, true));
+      return;
+    }
+
     /**
      * SEND A WHOLE BUFFER, NEVER A VIEW. This is what the retired node did and the drift from it
      * was audible: nothing but a light crackle.
@@ -124,7 +280,7 @@ export function makeAudioBuffer(
     if (combined.length % 2 === 0) {
       chunks = [];
       total = 0;
-      lane.sendAudio(conversationId, combined);
+      lane.sendAudio(conversationId, forLane(lane, combined, vendorRate, passthrough));
       return;
     }
 
@@ -143,7 +299,7 @@ export function makeAudioBuffer(
     }
     chunks = [Buffer.from(combined.subarray(aligned))];
     total = 1;
-    lane.sendAudio(conversationId, Buffer.from(combined.subarray(0, aligned)));
+    lane.sendAudio(conversationId, forLane(lane, Buffer.from(combined.subarray(0, aligned)), vendorRate, passthrough));
   };
 
   return {

package/vendor/base/src/manifests/runtime/duplex/session.ts

@@ -40,7 +40,7 @@ import { assertAllowedHost } from "../http/allowedHosts.js";
 import type { Emitter } from "../events.js";
 // The audio lane lives next door: this file owns the VENDOR socket, that one owns the bytes and
 // the browser. See the header of audioLane.ts for why they are separate files.
-import { makeAudioBuffer, resamplePcm16, CLIENT_RATE, type AudioLane } from "./audioLane.js";
+import { makeAudioBuffer, resamplePcm16, mulawToPcm16, CLIENT_RATE, type AudioLane } from "./audioLane.js";
 
 /**
  * PLATFORM CEILINGS, independent of anything a manifest says — the same arrangement `poll` has,
@@ -55,11 +55,15 @@ import { makeAudioBuffer, resamplePcm16, CLIENT_RATE, type AudioLane } from "./a
  *   MAX   a session that is active but has run absurdly long, e.g. an open mic in an empty room
  *         keeping VAD busy indefinitely.
  */
+/** How long the line stays open after the last audio frame, once the model has asked to hang up. */
+const HANG_UP_DRAIN_MS = 1500;
+
 const IDLE_TIMEOUT_MS = 30_000;
 const MAX_SESSION_MS = 30 * 60_000;
 
 import { offerDiscovered, parseMaybeJson, recordToolTrace, type ToolBridge } from "../tools/toolloop.js";
 import { applyInForce, renderSkillsText, type InForceSkill } from "../tools/regionSkills.js";
+import { registerLiveInput, liveInputKey } from "../../../platform/liveInput.js";
 
 
 /** Resolve one manifest message against the run scope, with `extra` layered on top. */
@@ -69,7 +73,7 @@ async function message(spec: unknown, ctx: RunContext, extra: Record<string, unk
 
 export interface DuplexResult {
   /** Why the session ended, for the caller to record. */
-  reason: "closed" | "ended" | "error" | "idle" | "maxDuration";
+  reason: "closed" | "ended" | "error" | "idle" | "maxDuration" | "notConnected";
   error?: string;
 }
 
@@ -110,11 +114,98 @@ export async function runDuplexSession(opts: {
   // A session always authenticates, hence `true` rather than reading the auth block.
   assertAllowedHost(url, node.allowedHosts, node.type, true);
 
+  /**
+   * WHAT THE CONVERSATION HAS ACCUMULATED, which no single event carries.
+   *
+   *   seen   the latest event of each type. A reply names the request it answers (a vendor's
+   *          delegation id), and that request arrived on an earlier event than the reply.
+   *   said   the text the vendor has streamed so far, in order, one entry per run of the same
+   *          event type. A hand-off carries no text of its own, so a row describing it reads
+   *          what was said before it; the transcript at the end is the whole list.
+   *
+   * Given to every events row and every `send` rule. Audio deltas never reach either: they
+   * leave on the audio lane before this is written.
+   *
+   * SET UP BEFORE THE CONNECT GATE BELOW, and that ordering is load-bearing. A call that rings
+   * out returns early, and the events table still runs its `complete` rows on the way out — so
+   * a row reading `said` for the transcript threw "unknown identifier 'said'" and the node
+   * FAILED instead of finishing (observed live 2026-09-20). A call nobody answered is an
+   * ordinary outcome, not a broken node: the scope exists for the whole run, and the transcript
+   * of a call that never happened is simply empty.
+   */
+  const seen: Record<string, any> = {};
+  const said: { type: string; text: string }[] = [];
+  emitter.extend({ seen, said });
+
+  /**
+   * THE RINGING AND THE GETTING READY HAPPEN AT THE SAME TIME.
+   *
+   * A lane that has to REACH its far end says so with `whenConnected` (audioLane.ts). We start
+   * it here, which for a telephone is the moment it begins to ring, AND WE DO NOT WAIT: the
+   * vendor socket is opened, the handshake exchanged and the opening line composed against the
+   * ringing tone, so that all of it is finished before anybody picks up.
+   *
+   * IT USED TO WAIT, and the reason was that a realtime session is billed from the moment it
+   * opens, so a call nobody answers would be paid for in full. That was the wrong thing to
+   * optimise. Waiting moved the entire setup — socket, handshake, and the model composing its
+   * first sentence — to AFTER the person said hello, and they heard every second of it as
+   * silence (measured live 2026-09-20: six seconds between answer and first word). A few cents
+   * on a call that rings out is cheaper than a call that sounds broken on every answer.
+   *
+   * The greeting cannot be played to a ringing tone, and it is not: the lane holds what is
+   * generated early and flushes it the instant the call connects (twilioAudio.ts). So the only
+   * thing that still waits for the answer is the sound itself.
+   *
+   * The browser lane declares no `whenConnected` at all, because the page dialled US and its
+   * socket is already there. Nothing below changes for it.
+   */
+  let answered: Promise<boolean> | null = null;
+  if (lane?.whenConnected) {
+    lane.startAudioSession?.(conversationId, conversationId);
+    answered = lane.whenConnected(conversationId);
+  }
+
   const ws = new WebSocket(url, { headers });
-  const buffer = lane && outSpec ? makeAudioBuffer(lane, conversationId, outSpec.coalesceBytes, outSpec.coalesceMs) : null;
+
+
+  /**
+   * WHAT THE VENDOR SENDS, which the lane converts FROM. `in.resampleTo` is the rate this
+   * session's manifest asks the vendor to LISTEN at, and every vendor here is symmetric — the
+   * handshake in api/run.yaml sets one format for input and output together — so it is also the
+   * rate the vendor SPEAKS at. Stated here rather than inferred at the far end, because a lane
+   * that guessed wrong would sound fine and simply be the wrong speed.
+   */
+  const vendorRate = inSpec?.resampleTo ?? CLIENT_RATE;
+
+  /**
+   * IS THE VENDOR ALREADY SPEAKING THIS LANE'S LANGUAGE?
+   *
+   * A node may declare in `api/audio.yaml` which lane codecs its vendor can take raw
+   * (`in.laneCodecs: [mulaw]`), and ask for that codec in its own handshake. When the lane
+   * speaks one of them, the bytes need no conversion in either direction: a telephone's 8 kHz
+   * mu-law goes to the vendor untouched and comes back untouched.
+   *
+   * The conversion it skips is not merely wasted, it is LOSSY IN BOTH DIRECTIONS: decode to
+   * PCM, interpolate 8 kHz up to 24 kHz, and at the far end interpolate back down and
+   * re-compand. A phone call is 8 kHz whatever is done to it, so all that work can only round
+   * the edges off it.
+   *
+   * ABSENT MEANS TODAY'S BEHAVIOUR, exactly. A node that declares nothing (Realtime, Grok, and
+   * every browser lane) converts as it always has, because a vendor that was not asked for
+   * mu-law is not sending it, and handing its PCM straight to a telephone would be noise.
+   */
+  const passthrough = !!lane?.codec && (inSpec?.laneCodecs ?? []).includes(lane.codec);
+
+  const buffer =
+    lane && outSpec
+      ? makeAudioBuffer(lane, conversationId, outSpec.coalesceBytes, outSpec.coalesceMs, vendorRate, passthrough)
+      : null;
 
   let settled = false;
   let closing = false;
+  /** Set once `control.endWhen` has fired; cleared only by the hang-up it schedules. */
+  let ending = false;
+  let drainTimer: ReturnType<typeof setTimeout> | undefined;
   /**
    * Is the assistant mid-utterance? The vendor has no "about to speak" event, so the FIRST audio
    * delta after silence is the start, and the client gates playback on being told. Transcribed from
@@ -136,6 +227,10 @@ export async function runDuplexSession(opts: {
    */
   const skills = new Map<string, InForceSkill>();
 
+
+  /** Set while the session is open and takes `CONTINUE` inputs; cleared when it ends. */
+  let unregisterLive: (() => void) | undefined;
+
   const send = (payload: unknown) => {
     if (ws.readyState !== WebSocket.OPEN) return;
     ws.send(JSON.stringify(payload));
@@ -183,14 +278,68 @@ export async function runDuplexSession(opts: {
       }, IDLE_TIMEOUT_MS);
     };
 
+    /**
+     * THE ONE PLACE A SESSION ENDS, and now the one place a CALL ends with it.
+     *
+     * Closing the vendor socket stops the model. It does not reach the person: on a telephone
+     * the carrier holds the line and will hold it until somebody hangs up. Those are two far
+     * ends and both have to be let go, so the lane is told here rather than at any one of the
+     * ways a session can finish — every one of them comes through this function, and a hang-up
+     * written beside only the deliberate one is a hang-up that never happens on a timeout, an
+     * error, or a vendor that dropped.
+     */
     const finish = (result: DuplexResult) => {
       if (settled) return;
       settled = true;
+      unregisterLive?.();
       if (idleTimer) clearTimeout(idleTimer);
+      if (drainTimer) clearTimeout(drainTimer);
       clearTimeout(maxTimer);
+      try {
+        lane?.hangUp?.(conversationId);
+      } catch (err: any) {
+        // A far end we could not let go of is worth saying out loud and is not worth failing
+        // the run over: the work the call did is already done and already emitted.
+        onError?.(`hang up failed: ${err?.message ?? err}`);
+      }
       resolve(result);
     };
 
+    /**
+     * HANGING UP AFTER THE LAST WORD, not during it.
+     *
+     * `control.endWhen` is true the moment the vendor reports the tool call, and the goodbye it
+     * was called alongside is still going down the wire. Shutting down there cuts the line
+     * mid-sentence, which is heard as the call dropping rather than ending (2026-09-22).
+     *
+     * So the decision and the hang-up are two things. The decision stands; the hang-up waits
+     * for the audio to stop arriving. Every frame that follows pushes this back, so a long
+     * closing sentence is never truncated, and a model that says nothing after calling the tool
+     * still hangs up within the settle.
+     */
+    const hangUpOnceQuiet = () => {
+      if (drainTimer) clearTimeout(drainTimer);
+      drainTimer = setTimeout(() => {
+        buffer?.flush();
+        void shutdown("ended").then((reason) => finish({ reason: reason ?? "ended" }));
+      }, HANG_UP_DRAIN_MS);
+    };
+
+    /**
+     * NOBODY EVER PICKED UP. Not an error — a call that rang out is a thing that happens, and the
+     * workflow should read it as such rather than as a broken node. The session we opened in front
+     * of it is closed here, which is the price of having been ready.
+     */
+    void answered?.then((ok) => {
+      if (ok) return;
+      try {
+        ws.close();
+      } catch {
+        /* never opened */
+      }
+      finish({ reason: "notConnected" });
+    });
+
     ws.on("open", async () => {
       touch();
       try {
@@ -236,15 +385,76 @@ export async function runDuplexSession(opts: {
           for (const m of ([] as any[]).concat(built ?? [])) if (m) send(m);
         }
 
+        /**
+         * TAKE `CONTINUE` INPUTS WHILE THE CALL RUNS (calls-that-loop.md, `transport: ws`).
+         *
+         * Another node's output, wired into this node's CONTINUE input, arrives here rather than
+         * starting the node again, which would open a second conversation. The `send` rules with
+         * `on: input` say what the vendor is told; the value is in scope as `input.value`.
+         *
+         * Registered AFTER the handshake, so nothing can be sent to a session the vendor has not
+         * been told about yet.
+         */
+        const key = liveInputKey(ctx.scope?.executionId, ctx.scope?.nodeId);
+        if (key) {
+          unregisterLive = registerLiveInput(key, async (handle, value) => {
+            if (ws.readyState !== WebSocket.OPEN) return false;
+            touch();
+            const scope = { input: { handle, value }, seen, said };
+            let sent = 0;
+            for (const rule of call.send ?? []) {
+              if (rule.on !== "input") continue;
+              if (rule.when && !(await evaluate(rule.when, { ...ctx, ...scope } as any))) continue;
+              for (const m of ([] as any[]).concat((await message(rule.message, ctx, scope)) ?? [])) {
+                if (m) {
+                  send(m);
+                  sent++;
+                }
+              }
+            }
+            // Named, not silent: an input wired to a node that says nothing about it is a
+            // canvas edge that looks connected and does nothing.
+            console.log(
+              sent
+                ? `[manifests] ${node.type}: input "${handle}" taken mid-call, ${sent} message(s) sent`
+                : `[manifests] ${node.type}: input "${handle}" arrived mid-call but no send rule has on: input`,
+            );
+            return true;
+          });
+        }
+
         if (lane && inSpec) {
-          lane.startAudioSession?.(conversationId, conversationId);
+          // Already started above for a lane that had to reach its far end, and starting a phone
+          // lane twice would place a second call.
+          if (!lane.whenConnected) lane.startAudioSession?.(conversationId, conversationId);
 
           lane.setAudioDataHandler?.(async (sessionId, data) => {
             if (sessionId !== conversationId || ws.readyState !== WebSocket.OPEN) return;
             touch();
             const raw = Buffer.from(data);
             const rate = inSpec.resampleTo ?? CLIENT_RATE;
-            const pcm = resamplePcm16(raw, CLIENT_RATE, rate);
+
+            // NOTHING TO DO: the vendor asked for this lane's own codec (see `passthrough`
+            // above), so these are the bytes to send. The rate travels as the LANE's, because
+            // that is what the samples actually are.
+            if (passthrough) {
+              send(
+                await message(inSpec.message, ctx, {
+                  audio: { base64: raw.toString("base64"), bytes: raw.length, rate: lane.rate ?? CLIENT_RATE },
+                }),
+              );
+              return;
+            }
+            /**
+             * DECODE BEFORE RESAMPLING. A mu-law byte is one sample, not half of one, so
+             * interpolating the raw bytes would treat pairs of samples as single ones and
+             * produce half-speed noise. And mu-law is logarithmic, so even the arithmetic
+             * would be wrong: the midpoint of two bytes is not the midpoint of two sounds.
+             *
+             * The browser lane declares neither, so both lines are identity for it.
+             */
+            const decoded = lane.codec === "mulaw" ? mulawToPcm16(raw) : raw;
+            const pcm = resamplePcm16(decoded, lane.rate ?? CLIENT_RATE, rate);
             send(
               await message(inSpec.message, ctx, {
                 audio: { base64: pcm.toString("base64"), bytes: pcm.length, rate },
@@ -275,17 +485,57 @@ export async function runDuplexSession(opts: {
       }
       const type = String(event?.type ?? "");
 
+      // A REJECTED SESSION MUST SAY WHY. Every vendor this runtime speaks names its complaint in
+      // an `error` event and then closes; without this line a refused handshake looks exactly like
+      // a quiet call, with nothing in any log to say which field was refused.
+      if (type === "error") {
+        console.log(`[manifests] ${node.type}: vendor error ${JSON.stringify(event.error ?? event)}`);
+      }
+
       // Billed per RESPONSE, so a ten-turn call carries ten usage blocks and the collector sums
       // them. Above the dispatch, because the frame carrying usage must not depend on which
       // branch claims it. `sniffUsage` already reads `payload.response.usage` — no manifest change.
       usage?.see(event);
 
+      /**
+       * THE MODEL HANGING UP, which nothing else can express.
+       *
+       * `control.endOn` is the LANE's list: a carrier's `stop` frame, a browser tab closing.
+       * Both mean the PERSON left. Nothing there can say the model is finished, and GPT-Live
+       * sends no end-of-call event of its own, so a call whose business was done simply stayed
+       * open: the assistant said goodbye, stopped talking, and the line was held until the idle
+       * timer fired minutes later (observed live 2026-09-22, and heard as silence).
+       *
+       * `control.endWhen` is that missing half: an expression over each vendor event, and when
+       * it is true the session shuts down exactly as a hang-up does. A manifest decides what
+       * counts — for a vendor with function calling it is a tool named `end_call`.
+       *
+       * ABSENT MEANS TODAY'S BEHAVIOUR. A node that declares nothing runs the same code it
+       * always did, which is why Realtime and Grok are untouched.
+       */
+      if (audio.control?.endWhen && !closing) {
+        let done = false;
+        try {
+          done = !!(await evaluate(audio.control.endWhen, { ...ctx, response: event } as any));
+        } catch {
+          // A malformed test must not kill a live call: the only safe reading is "not finished".
+        }
+        if (done && !ending) {
+          // DECIDED, NOT DONE. `hangUpOnceQuiet` waits for the goodbye to finish going out;
+          // see its comment for why this is not a shutdown on the spot.
+          ending = true;
+          hangUpOnceQuiet();
+        }
+      }
+
       try {
         // AUDIO, the one thing that bypasses an output connector, and only because MCP cannot
         // carry it.
         if (outSpec && type === outSpec.match) {
           // SPEECH_STARTED, once per utterance. The client sets up playback on it, so audio sent
           // before it is audio nobody hears.
+          // Still talking, so the hang-up waits: every frame pushes the settle back.
+          if (ending) hangUpOnceQuiet();
           if (!speaking) {
             speaking = true;
             lane?.sendControl(conversationId, {
@@ -347,6 +597,48 @@ export async function runDuplexSession(opts: {
         if (audio.control?.userStopped && type === audio.control.userStopped) {
           lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "USER_SPEECH_ENDED" });
         }
+        // Work done off the call (a vendor's hand-off to a backend), for the call state's "thinking".
+        if (audio.control?.toolUse && type === audio.control.toolUse) {
+          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "TOOL_USE" });
+        }
+        if (audio.control?.toolUseCompleted && type === audio.control.toolUseCompleted) {
+          lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "TOOL_USE_COMPLETED" });
+        }
+
+        /**
+         * WHAT THE VENDOR ACTUALLY SENDS, on demand. Three fixes in a row were built on a guess
+         * about which event carries a tool call's id, and each one was wrong in a new way,
+         * because nothing here ever printed the truth. DUPLEX_TRACE=1 prints every inbound event
+         * type once, and prints in full any event carrying a call id or a delegation — the two
+         * things a reply has to be addressed to.
+         */
+        // Remembered BEFORE the rows run, so a row firing on this event can read it too.
+        seen[type] = event;
+
+        /**
+         * AND UNDER WHATEVER NAME THE MANIFEST ASKED FOR. `seen[type]` keeps the latest event of
+         * each type, which loses one thing to another whenever a vendor gives two different
+         * things the same type: OpenAI ends a function call and the model's own message both as
+         * `response.output_item.done`, so the message overwrites the call and its `call_id`
+         * goes with it. A reply with no id to address is a model left waiting, heard on the call
+         * as silence (measured 2026-09-22).
+         *
+         * The manifest says which events matter to it, so the runtime keeps no vendor knowledge.
+         * A test that throws keeps the slot as it was: remembering nothing is recoverable,
+         * killing the session over a bad expression is not.
+         */
+        for (const [name, test] of Object.entries(call.keep ?? {})) {
+          try {
+            if (await evaluate(test as string, { ...ctx, response: event } as any)) seen[name] = event;
+          } catch {
+            /* a malformed test must not take the call down */
+          }
+        }
+        if (typeof event?.delta === "string" && event.delta) {
+          const last = said[said.length - 1];
+          if (last && last.type === type) last.text += event.delta;
+          else said.push({ type, text: event.delta });
+        }
 
         // EVERYTHING ELSE, to the events table, exactly as an sse reply. This is the path that
         // reaches the client over MCP streaming.
@@ -463,7 +755,7 @@ export async function runDuplexSession(opts: {
               }
               // The same timeline row an HTTP agent's tool call draws. `runToolLoop` has recorded
               // these since the migration; the socket never called it, so voice tools were invisible.
-              recordToolTrace(node, ctx, name, parseMaybeJson(rawArgs), output, toolStart, toolOk);
+              recordToolTrace(node, ctx, name, parseMaybeJson(rawArgs), output, toolStart, toolOk, tools.kindOf?.(name) ?? "tool");
               // After the catch, so a tool that THREW still stops the dots. Spinning forever is
               // worse than no indicator: it promises something still coming.
               lane?.sendControl(conversationId, { type: "AUDIO_STATE", state: "TOOL_USE_COMPLETED" });
@@ -486,9 +778,9 @@ export async function runDuplexSession(opts: {
           // AWAITED, for the same reason the audio path is: `evaluate` is async, so `!promise` is
           // always false and an un-awaited `when` never blocks anything. Every reactive send would
           // fire regardless of its condition — silently, since firing too often looks like working.
-          if (rule.when && !(await evaluate(rule.when, { ...ctx, response: event } as any))) continue;
+          if (rule.when && !(await evaluate(rule.when, { ...ctx, response: event, seen, said } as any))) continue;
           // A list, because one rule may need several messages (add the item, then ask for a reply).
-          for (const m of ([] as any[]).concat((await message(rule.message, ctx, { response: event })) ?? [])) {
+          for (const m of ([] as any[]).concat((await message(rule.message, ctx, { response: event, seen, said })) ?? [])) {
             if (m) send(m);
           }
         }
@@ -503,7 +795,10 @@ export async function runDuplexSession(opts: {
       finish({ reason: "error", error: err?.message ?? String(err) });
     });
 
-    ws.on("close", () => {
+    ws.on("close", (code, reason) => {
+      // The vendor hanging up on its own is the other half of a refusal: its close code and
+      // reason are often the only explanation it gives.
+      if (!closing) console.log(`[manifests] ${node.type}: vendor closed the session (${code}) ${String(reason || "")}`);
       buffer?.flush();
       finish({ reason: closing ? "ended" : "closed" });
     });