feat(calls): prepare guest labels and live waiting-room controls

README.md

@@ -2834,3 +2834,19 @@ Campaign analytics shows `Skipped by frequency cap`; recipient output includes
 This implementation keeps the published SDK pin unchanged. Release waits for a
 matching SDK prerelease and accepted API contract; source support does not imply
 package publication or beta availability.
+
+## Guest participants and waiting rooms (unreleased)
+
+Call participant output preserves optional `guest` and `name` fields. A name is unverified display text; the public participant ID remains the identity used for controls. A phone number is optional.
+
+`calls media --control-input commands.jsonl` reads explicit host commands on the same media connection. Use a file or pipe separate from PCM input; `--control-input -` reads stdin when `--input` does not use stdin. Each nonblank line is one command:
+
+```json
+{"action":"set_approval_required","enabled":true}
+{"action":"admit","participantId":"739182640518203"}
+{"action":"deny","participantId":"739182640518204"}
+```
+
+The command reports waiting-room state and matching results to stderr, as JSON lines with `--json`. It never opens another connection to impersonate the host or retries an uncertain command. Check the current roster before deciding to send another action after `waiting_room_control_unknown`. Rendered names are quoted so control characters cannot become terminal instructions.
+
+This source requires a Calls SDK that implements waiting-room controls. The pinned published SDK does not yet provide them, so the flag fails before connecting in ordinary builds. Physical-package acceptance uses the exact candidate SDK recorded in `contracts/calls-guests.candidate.json`; it is not registry or deployed API acceptance. Do not publish this counterpart until the matching SDK and API have the required environment acceptance.

contracts/calls-guests.candidate.json

@@ -0,0 +1,27 @@
+{
+  "sourceAccepted": false,
+  "published": false,
+  "apiVersion": "2026-09-22",
+  "apiSource": "0983e9263de1f0887b249faf9d85207d543989e3",
+  "sdkSource": "e6df859b2560c67a87f947f8c4cf13e2361cfc95",
+  "sdkSnippetExport": "b9454930a2a821cccde2881efeb4430a0a96e676",
+  "physicalPackageSha256": "34b858821df0405c215306997a3e3cfdbea1cf404db90c09422be4075018cda4",
+  "publishedDependencyUnchanged": true,
+  "operations": ["set_approval_required", "admit", "deny"],
+  "authority": "same held live media connection; backend checks call owner and current provider admin",
+  "replay": "never automatic; a matching acknowledgement is required",
+  "evidence": "POLYMORFA_GUEST_SDK_REQUIRED=1 native CLI calls-sockets fixture with candidate package",
+  "releaseGates": [
+    "accepted API and SDK source",
+    "matching staging acceptance before nightly",
+    "matching production acceptance before stable",
+    "native paired-host waiting-room moderation acceptance",
+    "matching published SDK version before dependency pin",
+    "CLI merge and publication after the matching SDK dependency is pinned"
+  ],
+  "acceptance": {
+    "publishedDependency": "format, lint, typecheck, build, reference checks and full suite pass: 1175 tests, 1 candidate-only skip; old SDK refuses unsupported controls before connecting",
+    "candidatePackage": "typecheck, build and all 1176 tests pass with physical SDK archive, including native held-connection guest moderation; emitted browser module and production audit pass",
+    "dependencyPin": "published version unchanged until matching SDK publication and API environment acceptance; full candidate source compatibility is verified"
+  }
+}

contracts/cli-reference.json

@@ -12613,6 +12613,18 @@
           "env": null,
           "helpGroup": "GLOBAL"
         },
+        {
+          "name": "control-input",
+          "char": null,
+          "type": "option",
+          "required": false,
+          "multiple": false,
+          "default": null,
+          "options": [],
+          "description": "Read waiting-room commands as JSON lines from a file or - for stdin, on this live connection. Requires a Calls SDK with waiting-room support.",
+          "env": null,
+          "helpGroup": null
+        },
         {
           "name": "exclusive",
           "char": null,

scripts/verify-browser.mjs

@@ -97,7 +97,10 @@ const sent = await actual.runCommand(
     'Hello from Polymorfa',
   ],
   {
-    env: {POLYMORFA_CLIENT_TOKEN: 'pmfa_ct_' + 'fixture'.repeat(6)},
+    env: {
+      POLYMORFA_CLIENT_TOKEN:
+        'pmfa_ct_Zml4dHVyZWZpeHR1cmVmaXh0dXJlZml4dHVyZWZpeHR1cmVmaXh0dXJl',
+    },
     fetch: async (input, init = {}) => {
       requests.push({
         path: new URL(String(input)).pathname,

src/commands/calls/media.ts

@@ -1,8 +1,12 @@
-import {assertCallMediaMuteSupported} from '../../services/call-media-controls.js'
+import {
+  assertCallMediaMuteSupported,
+  assertWaitingRoomSupported,
+} from '../../services/call-media-controls.js'
 import {createWriteStream, type ReadStream, type WriteStream} from 'node:fs'
 import {open, stat} from 'node:fs/promises'
 import {once} from 'node:events'
 import {resolve} from 'node:path'
+import type {Readable} from 'node:stream'
 
 import {Args, Flags} from '@oclif/core'
 import {PolymorfaConfigurationError} from '@polymorfa/sdk'
@@ -37,6 +41,10 @@ export default class CallsMedia extends BaseCommand {
   ]
 
   static override flags = {
+    'control-input': Flags.string({
+      description:
+        'Read waiting-room commands as JSON lines from a file or - for stdin, on this live connection. Requires a Calls SDK with waiting-room support.',
+    }),
     muted: Flags.boolean({
       exclusive: ['input'],
       description:
@@ -81,6 +89,27 @@ export default class CallsMedia extends BaseCommand {
   async run(): Promise<void> {
     const {args, flags} = await this.parse(CallsMedia)
     if (flags.muted) assertCallMediaMuteSupported()
+    if (flags['control-input'] !== undefined) assertWaitingRoomSupported()
+    if (
+      flags['control-input'] === '-' &&
+      (flags.input === '-' || process.stdin.isTTY)
+    ) {
+      throw new PolymorfaConfigurationError(
+        'Pipe JSON lines to --control-input - separately from PCM input.',
+        'control-input',
+      )
+    }
+    if (
+      flags['control-input'] &&
+      flags['control-input'] !== '-' &&
+      flags.output !== '-' &&
+      (await sameFile(flags['control-input'], flags.output))
+    ) {
+      throw new PolymorfaConfigurationError(
+        '--control-input and --output name the same file.',
+        'control-input',
+      )
+    }
     if (flags.output === '-' && process.stdout.isTTY) {
       throw new PolymorfaConfigurationError(
         'Received audio is binary. Redirect standard output or pass --output <file>.',
@@ -119,6 +148,18 @@ export default class CallsMedia extends BaseCommand {
         throw inputFailed(inputPath, error)
       }
     }
+    let controls: Readable | undefined
+    if (flags['control-input'] !== undefined) {
+      try {
+        controls =
+          flags['control-input'] === '-'
+            ? process.stdin
+            : (await open(flags['control-input'], 'r')).createReadStream()
+      } catch (error) {
+        inputFile?.destroy()
+        throw inputFailed(flags['control-input'], error)
+      }
+    }
     const json = this.outputMode(flags) === 'json'
     const quiet = this.outputMode(flags) === 'quiet'
     const report = (value: object, human: string): void => {
@@ -158,6 +199,7 @@ export default class CallsMedia extends BaseCommand {
       halt.abort()
     }
     input?.on('error', onInputError)
+    controls?.on('error', onInputError)
 
     // Flush and close the output file once; its errors arrive asynchronously.
     let outputClosed = false
@@ -177,6 +219,7 @@ export default class CallsMedia extends BaseCommand {
           exclusive: flags.exclusive,
           muted: flags.muted,
           input,
+          controls,
           leaveOnEnd: flags['leave-on-eof'],
           output,
           participant: flags.participant,
@@ -202,6 +245,8 @@ export default class CallsMedia extends BaseCommand {
       // it (a microphone, tail -f), which would keep the process alive.
       if (input === process.stdin) process.stdin.destroy()
       input?.off('error', onInputError)
+      controls?.destroy()
+      controls?.off('error', onInputError)
       await closeOutput()
     }
     if (fileError !== undefined) throw outputFailed(flags.output, fileError)
@@ -222,6 +267,8 @@ function renderMediaStatus(
       return `Connected to call ${status.callId} as connection ${status.connectionId} at ${status.sampleRate} Hz.`
     case 'placed':
       return `Placed call ${status.callId}; waiting for an answer.`
+    case 'waiting_room_control_result':
+      return `Waiting-room command ${status.sequence} (${status.action}): ${status.ok ? 'confirmed' : (status.code ?? 'failed')}.`
     case 'input_ended':
       return `Sent all input audio (${status.bytes} bytes).`
     default:

src/listener/forwarding.ts

@@ -322,7 +322,9 @@ function send(
         path: `${destination.url.pathname}${destination.url.search}`,
         port: destination.url.port || undefined,
         rejectUnauthorized: !(input.skipVerify && destination.loopback),
-        servername: hostname(destination.url),
+        servername: isIP(hostname(destination.url))
+          ? ''
+          : hostname(destination.url),
         signal: input.signal,
         timeout: 10_000,
       },

src/output/calls.ts

@@ -58,12 +58,26 @@ export function renderCallActivity(activity: CallActivity): string {
         `participant=${activity.participant.id}`,
         `state=${activity.participant.state}`,
       )
+      if ((activity.participant as {guest?: boolean}).guest === true)
+        fields.push('guest=true')
+      if (typeof (activity.participant as {name?: string}).name === 'string')
+        fields.push(
+          `name=${JSON.stringify((activity.participant as {name?: string}).name)}`,
+        )
       break
     case 'participant_left':
       fields.push(`participant=${activity.participantId}`)
       if (activity.reason !== undefined)
         fields.push(`reason=${activity.reason}`)
       break
+    case 'waiting_room':
+      fields.push(
+        `approvalRequired=${activity.room.enabled}`,
+        `isAdmin=${activity.room.isAdmin}`,
+        `inWaitingRoom=${activity.room.inWaitingRoom}`,
+        `users=${JSON.stringify(activity.room.users)}`,
+      )
+      break
     case 'ended':
       fields.push(`reason=${activity.reason}`, `duration=${activity.duration}s`)
       break

src/services/call-media-controls.ts

@@ -30,3 +30,123 @@ export async function muteCallMedia(call: object): Promise<void> {
     )
   }
 }
+
+export interface WaitingRoomCommand {
+  readonly action: 'set_approval_required' | 'admit' | 'deny'
+  readonly enabled?: boolean
+  readonly participantId?: string
+}
+interface WaitingRoomControls {
+  setApprovalRequired(enabled: boolean): Promise<void>
+  admitParticipant(participantId: string): Promise<void>
+  denyParticipant(participantId: string): Promise<void>
+}
+
+export function assertWaitingRoomSupported(
+  candidate: object = Call.prototype,
+): asserts candidate is WaitingRoomControls {
+  const controls = candidate as Partial<WaitingRoomControls>
+  if (
+    typeof controls.setApprovalRequired !== 'function' ||
+    typeof controls.admitParticipant !== 'function' ||
+    typeof controls.denyParticipant !== 'function'
+  ) {
+    throw new PolymorfaConfigurationError(
+      'This CLI build needs a published Calls SDK with waiting-room support before --control-input can be used.',
+      'control-input',
+    )
+  }
+}
+
+/** One command uses only the Call's current media connection. Never retry it. */
+export async function moderateWaitingRoom(
+  call: object,
+  command: WaitingRoomCommand,
+): Promise<void> {
+  assertWaitingRoomSupported(call)
+  if (command.action === 'set_approval_required')
+    await call.setApprovalRequired(command.enabled!)
+  else if (command.action === 'admit')
+    await call.admitParticipant(command.participantId!)
+  else await call.denyParticipant(command.participantId!)
+}
+
+/** Read bounded UTF-8 JSON lines from a file or pipe, separate from PCM input. */
+export async function* waitingRoomCommands(
+  input: AsyncIterable<Uint8Array>,
+): AsyncGenerator<WaitingRoomCommand> {
+  const decoder = new TextDecoder('utf-8', {fatal: true})
+  let pending = ''
+  function parse(line: string): WaitingRoomCommand {
+    let value: unknown
+    try {
+      value = JSON.parse(line)
+    } catch {
+      throw invalidControl()
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+      throw invalidControl()
+    const command = value as Record<string, unknown>
+    const keys = Object.keys(command).sort().join(',')
+    if (
+      command.action === 'set_approval_required' &&
+      keys === 'action,enabled' &&
+      typeof command.enabled === 'boolean'
+    )
+      return {action: command.action, enabled: command.enabled}
+    if (
+      (command.action === 'admit' || command.action === 'deny') &&
+      keys === 'action,participantId' &&
+      typeof command.participantId === 'string' &&
+      /^[1-9][0-9]{0,18}$/.test(command.participantId)
+    )
+      return {action: command.action, participantId: command.participantId}
+    throw invalidControl()
+  }
+  for await (const chunk of input) {
+    // Process pieces so one large read never grows the pending line without bound.
+    for (let offset = 0; offset < chunk.length; offset += 1024) {
+      pending += decoder.decode(chunk.subarray(offset, offset + 1024), {
+        stream: true,
+      })
+      let newline: number
+      while ((newline = pending.indexOf('\n')) !== -1) {
+        const line = pending.slice(0, newline).trim()
+        if (newline > 4096) throw invalidControl()
+        pending = pending.slice(newline + 1)
+        if (line) yield parse(line)
+      }
+      if (pending.length > 4096) throw invalidControl()
+    }
+  }
+  pending += decoder.decode()
+  if (pending.trim()) yield parse(pending.trim())
+}
+function invalidControl(): PolymorfaConfigurationError {
+  return new PolymorfaConfigurationError(
+    'Expected a JSON line with action set_approval_required and enabled, or action admit/deny and a public participantId. Lines must be at most 4096 characters.',
+    'control-input',
+  )
+}
+
+export interface CallWaitingRoom {
+  readonly enabled: boolean
+  readonly isAdmin: boolean
+  readonly inWaitingRoom: boolean
+  readonly users: readonly {
+    readonly id: string
+    readonly state: string
+    readonly guest?: boolean
+    readonly name?: string
+  }[]
+}
+export function observeWaitingRoom(
+  call: object,
+  listener: (state: CallWaitingRoom) => void,
+): void {
+  ;(
+    call as {
+      on(event: 'waitingRoom', listener: (state: CallWaitingRoom) => void): void
+    }
+  ).on('waitingRoom', listener)
+}