@perkos/perkos-voice 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PerkOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# PerkOS Voice
+
+Runtime-facing voice gateway contracts and orchestration for PerkOS agents.
+
+```text
+PerkOS Web ── media ── LiveKit ── media ── PerkOS Voice Gateway ── agent runtime
+     │                                      │
+     └──────── control: PerkOS API/Meetings ┘
+
+PerkOS-A2A and PerkOS-Chat: capability/control only; never audio or transcripts.
+```
+
+## Runnable gateway foundation
+
+This repository now provides a container-ready gateway foundation:
+
+- strict, provider-neutral voice capability handshake validation;
+- availability decisions for absent/invalid capability, ownership, expiry,
+  requested mode, interruption, and transcript support;
+- an explicit session state machine covering authorization, join, listening,
+  thinking, speaking, correlated cancellation/barge-in, failure, and closure;
+- a real outbound LiveKit Node adapter with microphone-only publication;
+- a provider-neutral BYO speech HTTP boundary;
+- a verified OpenClaw OpenResponses runtime adapter (not Talk integration);
+- file-based or authenticated M2M short-lived grant delivery;
+- `/health`, `/ready`, and strictly redacted `/capabilities` endpoints;
+- deterministic in-memory/fake implementations and gateway orchestration;
+- an API-level rule that `saved` transcripts require explicit consent.
+
+This phase includes no paid speech provider, provider account or key, deployment,
+Bragi mutation, Web change, audio/transcript persistence, or content logging.
+`off` is the default transcript policy. Saved transcripts are not advertised or
+accepted by this runnable adapter.
+
+External invited agents use `external_owner` (BYO Voice): the owner configures
+and pays the provider beside their runtime. PerkOS receives only the public
+capability handshake and an agent-scoped authorization grant. Provider names,
+credentials, raw audio, transcripts, and private addresses are rejected from or
+absent in the public control contracts.
+
+## Local development
+
+Requires Node.js 20+.
+
+```bash
+npm ci
+npm run lint
+npm run build
+npm test
+```
+
+The tests use no live networking, LiveKit room, or speech provider.
+
+External-agent installation and acceptance are standardized by
+`external-agent-contract.schema.json` and
+`docs/external-agent-onboarding.md`. The contract is deliberately independent
+of the agent's chat surface and its preflight reports only allow-listed stage
+codes.
+
+Runtime installation follows a hybrid plugin model. Hermes, OpenClaw and
+ZeroClaw use thin native plugins that manage the same immutable Voice gateway;
+the plugins do not carry media or expose private chat. The neutral install
+contract and built-in profiles are exported from `src/installer.ts`. See
+`docs/plans/2026-09-01-standard-runtime-plugin-installer-design.md`.
+
+When PerkOS-A2A is already installed, optional Voice enrollment uses two exact
+control markers: `PERKOS_VOICE_PROBE` and `PERKOS_VOICE_ENROLL`. The exported
+`@perkos/perkos-voice/a2a` boundary reports runtime support and writes a claimed
+credential directly to a mode-0600 plugin file. It never returns the credential
+to A2A or the model. Enrollment remains action-required until the native Voice
+service and owner-selected speech provider are ready and publish capability.
+
+OpenClaw installs the npm extension and supervises the gateway as a native
+service. Hermes uses the equivalent managed-service emitter:
+
+```bash
+perkos-voice-install-hermes --emit \
+  --agent-id AGENT_ID --agent-name Athena --environment dev \
+  --voice-env-file ~/.perkos/voice/athena-dev.env \
+  --secret-file ~/.perkos/voice/athena-dev.secrets.json
+```
+
+Review the emitted launchd plist or systemd unit before installing it. Secrets
+remain in the referenced mode-0600 file and are never embedded in the unit.
+
+ZeroClaw uses the same review-first service model because its sandboxed WASM
+plugins cannot supervise host processes or read the gateway secret file. The
+installer binds the verified authenticated local `POST /webhook` adapter:
+
+```bash
+perkos-voice-install-zeroclaw --emit \
+  --agent-id AGENT_ID --agent-name Nova --environment dev \
+  --voice-env-file ~/.perkos/voice/nova-dev.env \
+  --secret-file ~/.perkos/voice/nova-dev.secrets.json
+```
+
+Do not expose ZeroClaw's webhook publicly. The installer rejects non-loopback,
+credential-bearing, query-bearing, or non-`/webhook` runtime URLs.
+
+## Configuration and startup
+
+Copy `config.example.env` only as a field reference. The production container
+expects a root-owned mode-0600 JSON file shaped like
+`config.secrets.example.json` at `VOICE_SECRET_SOURCE_FILE`. Its audited
+bootstrap copies it into a 0600 least-privilege path on required tmpfs, clears
+its temporary buffer, drops supplementary groups and root privileges, and only
+then starts the gateway. Do not commit real values. LiveKit grants are either mounted at
+`VOICE_GRANT_FILE` or fetched just in time from `VOICE_GRANT_ENDPOINT` with the
+separate gateway credential in the secret file. Tokens must never be placed in
+URLs, logs, A2A, or Chat.
+
+The generic BYO speech sidecar contract is:
+
+- `POST <VOICE_SPEECH_ENDPOINT>/transcribe`, body `audio/pcm`, response `{ "text": "..." }`;
+- `POST <VOICE_SPEECH_ENDPOINT>/synthesize`, JSON request, streaming signed
+  16-bit little-endian 48 kHz mono PCM response.
+
+The external owner operates that sidecar and retains the provider key. PerkOS
+does not select a provider or receive its key. The OpenClaw adapter supports
+the local `/v1/responses` interface and the OpenAI-compatible
+`/v1/chat/completions` interface. Select the latter with
+`OPENCLAW_API_MODE=chat_completions`, `OPENCLAW_ENDPOINT`, and an explicit
+`OPENCLAW_CHAT_MODEL` that routes to Bragi's own runtime. Tool execution stays
+inside OpenClaw. `UnavailableOpenClawTalkAdapter`
+exists explicitly because a supported Talk runtime contract has not been
+verified.
+
+For the cost-controlled OpenAI pilot, set `VOICE_SPEECH_MODE=openai_turn` and
+place `openAiApiKey` only in the mounted runtime secret JSON. The gateway uses
+the Audio transcription and speech endpoints, never the Realtime API. Input is
+segmented into bounded silence-delimited turns; the default mini models limit
+cost, and audio/transcript content is neither logged nor persisted. Provider
+readiness probes model metadata and does not submit billable speech content.
+
+When `VOICE_CAPABILITY_PUBLISH_ENDPOINT` and its separate runtime credential
+are configured, the gateway publishes only the strict public capability
+handshake after provider and OpenClaw probes pass. A failed probe publishes an
+unavailable handshake on the next refresh. The receiving control plane must
+authenticate, validate, expire, and serve that handshake to Web.
+`VOICE_AGENT_ID` remains the enrolled agent identifier used by the endpoint,
+M2M authorization, and dynamic session control. Set the non-secret
+`VOICE_CANONICAL_AGENT_NAME` to the registry name placed in the public
+capability payload; production publication fails closed when it is absent.
+
+Dynamic production sessions use `VOICE_SESSION_CONTROL_ENDPOINT`. The gateway
+polls with its existing M2M credential, atomically claims only a matching
+short-lived agent session, obtains the existing scoped LiveKit grant, and
+reports joined/completed/failed lifecycle state. Project and meeting IDs are no
+longer production startup settings; they arrive only in the claimed,
+consent-bound session. Cancellation or expiry closes the media room fail-closed.
+
+The control plane also snapshots the owner-selected `speechVoice` into each
+claimed session. OpenAI turn synthesis uses that allow-listed value without a
+gateway restart. Precedence is `OPENAI_SPEECH_VOICE_OVERRIDE` (optional operator
+emergency override), then the session preference, then legacy
+`OPENAI_SPEECH_VOICE`, then `alloy`. `speechVoice` is public configuration only;
+provider credentials and endpoints remain runtime secrets.
+
+The initial Bragi pilot also includes a root-only outbound encrypted-delivery
+receiver. It uses an RSA-3072 ephemeral key, signed one-use claim, OAEP-SHA256
+decryption, signed nonce-protected in-memory delivery discovery, atomic
+mode-0600 gateway-secret update, and a credential-derived
+receipt proof that does not transmit the bearer credential. See
+`docs/plans/2026-08-14-bragi-encrypted-server-delivery.md`. This bridge is
+deliberately bound to Bragi and is not a general enrollment workflow.
+
+```bash
+docker build -t perkos-voice:local .
+docker compose -f docker-compose.production.example.yml config
+```
+
+The Compose file is a host-specific template: use an immutable release image,
+replace only the root-owned source path, and keep its read-only filesystem,
+restricted capabilities and tmpfs mount. `VOICE_RUNTIME_REQUIRE_TMPFS=false`
+exists for local diagnostics only and must not be used for production.
+The runtime image installs Debian's standard `ca-certificates` bundle and
+fails its image build if that trust bundle is absent or empty. TLS verification
+remains enabled; no custom CA path or `NODE_EXTRA_CA_CERTS` override is needed.
+
+Liveness is `GET /health`. Readiness is `GET /ready` and returns 503 until
+grant delivery, speech-provider access, and local OpenClaw access are probed.
+`GET /capabilities` is always public-safe and never includes tokens, provider
+details, private addresses, audio, or transcripts.
+
+Session failures emit only a fixed stage enum (`grant_obtain`,
+`livekit_connect`, `audio_source_create`, `track_create`, `track_publish`,
+`gateway_start`, `status_joined`, or `turn_loop`). Upstream errors, URLs,
+tokens, identifiers, audio, and transcript content are never copied into logs.
+LiveKit connect and initial track publication are bounded and clean up partial
+room/track state before returning a fixed failure.
+
+## Public surface
+
+The package root exports public types, capability validation/reasoning, the
+state machine, gateway, provider-neutral ports, and deterministic fakes. The
+existing `@perkos/perkos-voice/types` subpath remains compatible.
+
+## Integration handoff
+
+1. **PerkOS API/Meetings** should authenticate the caller and later mint a
+   short-lived `VoiceGatewayGrant` scoped to the exact meeting and agent. Tokens
+   stay out of A2A/Chat payloads and logs.
+2. **PerkOS Web** should request that grant, join LiveKit directly, and render
+   the state/cancellation outcomes. It must not receive provider credentials.
+3. **Agent runtimes** should run this gateway beside the runtime and connect
+   outbound to LiveKit. External agents declare `external_owner`; managed AWS
+   agents will use future server-side managed adapters.
+4. **PerkOS-A2A/Chat** may exchange the allow-listed capability handshake and
+   session control identifiers only. They must never carry audio chunks, base64
+   audio, provider keys, or raw transcripts.
+5. A production deployment still requires an owner-supplied speech adapter,
+   an enrolled M2M credential, operational LiveKit/OpenClaw configuration, and
+   an API consumer for the verified capability publication.
+   Bragi remains unavailable until those separate operations are approved.
+
+The P0 design remains in `docs/plans/2026-08-14-p0-voice-gateway-design.md`;
+the runnable phase note is in
+`docs/plans/2026-08-14-runnable-gateway-foundation.md`.

package/dist/a2aEnrollment.d.ts

@@ -0,0 +1,41 @@
+import { type RuntimeProtocol, type SupportedRuntime } from "./installer.js";
+export declare const PERKOS_VOICE_PROBE_MARKER: "PERKOS_VOICE_PROBE";
+export declare const PERKOS_VOICE_ENROLL_MARKER: "PERKOS_VOICE_ENROLL";
+export type A2AVoiceEnrollment = {
+    version: "perkos.voice.a2a-enrollment/v1";
+    agentId: string;
+    agentName: string;
+    environment: "dev" | "qa" | "production";
+    credential: string;
+    audience: "perkos-voice-gateway-grant:v1";
+    expiresAt: string;
+    sessionControlEndpoint: string;
+    grantEndpoint: string;
+    capabilityPublishEndpoint: string;
+};
+export type A2AVoiceHandlerOptions = {
+    apiBaseUrl: string;
+    agentId: string;
+    relayApiKey: string;
+    runtime: SupportedRuntime;
+    protocol?: RuntimeProtocol;
+    fetcher?: typeof fetch;
+    configure: (enrollment: A2AVoiceEnrollment) => Promise<{
+        ready: boolean;
+        actionCode?: string;
+    }>;
+};
+/**
+ * Persist a claimed enrollment at the native plugin boundary. The durable
+ * credential never returns to A2A or the model. Runtime installers may watch
+ * this file and complete service activation; until then the safe response is
+ * action-required rather than a false ready signal.
+ */
+export declare function configureA2AVoiceEnrollment(enrollment: A2AVoiceEnrollment, options?: {
+    stateDirectory?: string;
+}): Promise<{
+    ready: false;
+    actionCode: "service_activation_required";
+}>;
+/** Handle only exact fixed markers. Arbitrary natural-language prompts remain normal agent input. */
+export declare function handleA2AVoiceMarker(message: string, options: A2AVoiceHandlerOptions): Promise<string | null>;

package/dist/a2aEnrollment.js

@@ -0,0 +1,110 @@
+import { RUNTIME_PROFILES } from "./installer.js";
+import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export const PERKOS_VOICE_PROBE_MARKER = "PERKOS_VOICE_PROBE";
+export const PERKOS_VOICE_ENROLL_MARKER = "PERKOS_VOICE_ENROLL";
+/**
+ * Persist a claimed enrollment at the native plugin boundary. The durable
+ * credential never returns to A2A or the model. Runtime installers may watch
+ * this file and complete service activation; until then the safe response is
+ * action-required rather than a false ready signal.
+ */
+export async function configureA2AVoiceEnrollment(enrollment, options = {}) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/u.test(enrollment.agentId))
+        throw new Error("agent_id_invalid");
+    const root = options.stateDirectory ?? join(homedir(), ".perkos", "voice");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    await chmod(root, 0o700);
+    const target = join(root, `${enrollment.agentId}-${enrollment.environment}.enrollment.json`);
+    const temporary = join(root, `.${enrollment.agentId}-${randomUUID()}.tmp`);
+    const document = JSON.stringify({
+        version: enrollment.version,
+        agentId: enrollment.agentId,
+        agentName: enrollment.agentName,
+        environment: enrollment.environment,
+        grantCredential: enrollment.credential,
+        capabilityPublishCredential: enrollment.credential,
+        expiresAt: enrollment.expiresAt,
+        sessionControlEndpoint: enrollment.sessionControlEndpoint,
+        grantEndpoint: enrollment.grantEndpoint,
+        capabilityPublishEndpoint: enrollment.capabilityPublishEndpoint,
+    });
+    await writeFile(temporary, `${document}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, target);
+    await chmod(target, 0o600);
+    return { ready: false, actionCode: "service_activation_required" };
+}
+function endpoint(options, suffix) {
+    return `${options.apiBaseUrl.replace(/\/$/u, "")}/agents/${encodeURIComponent(options.agentId)}/voice-credential/${suffix}`;
+}
+function supported(options) {
+    const profile = RUNTIME_PROFILES[options.runtime];
+    return Boolean(profile && (!options.protocol || profile.protocols.includes(options.protocol)));
+}
+async function post(options, suffix, body) {
+    return (options.fetcher ?? fetch)(endpoint(options, suffix), {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${options.relayApiKey}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body ?? {}),
+    });
+}
+function safeFailure(response) {
+    if (response.status === 401 || response.status === 403)
+        return "auth_rejected";
+    if (response.status === 404)
+        return "agent_not_found";
+    if (response.status === 409)
+        return "enrollment_not_pending";
+    if (response.status === 410)
+        return "enrollment_expired";
+    return "control_plane_unavailable";
+}
+function validEnrollment(value) {
+    const item = value && typeof value === "object" ? value : {};
+    return item.version === "perkos.voice.a2a-enrollment/v1"
+        && typeof item.agentId === "string"
+        && typeof item.agentName === "string"
+        && (item.environment === "dev" || item.environment === "qa" || item.environment === "production")
+        && typeof item.credential === "string" && item.credential.startsWith("vgc_")
+        && item.audience === "perkos-voice-gateway-grant:v1"
+        && typeof item.expiresAt === "string" && Number.isFinite(Date.parse(item.expiresAt))
+        && [item.sessionControlEndpoint, item.grantEndpoint, item.capabilityPublishEndpoint]
+            .every((entry) => typeof entry === "string" && /^https?:\/\//u.test(entry));
+}
+/** Handle only exact fixed markers. Arbitrary natural-language prompts remain normal agent input. */
+export async function handleA2AVoiceMarker(message, options) {
+    const marker = message.trim();
+    if (marker !== PERKOS_VOICE_PROBE_MARKER && marker !== PERKOS_VOICE_ENROLL_MARKER)
+        return null;
+    if (marker === PERKOS_VOICE_PROBE_MARKER) {
+        const isSupported = supported(options);
+        const response = await post(options, "capability-report", isSupported
+            ? { state: "available", runtime: options.runtime }
+            : { state: "unsupported", runtime: options.runtime, reasonCode: "runtime_protocol_unsupported" });
+        if (!response.ok)
+            return `PERKOS_VOICE_FAILED:${safeFailure(response)}`;
+        return isSupported ? "PERKOS_VOICE_AVAILABLE" : "PERKOS_VOICE_UNSUPPORTED:runtime_protocol_unsupported";
+    }
+    if (!supported(options))
+        return "PERKOS_VOICE_FAILED:runtime_protocol_unsupported";
+    const response = await post(options, "claim-a2a");
+    if (!response.ok)
+        return `PERKOS_VOICE_FAILED:${safeFailure(response)}`;
+    const payload = await response.json().catch(() => null);
+    if (!validEnrollment(payload?.enrollment))
+        return "PERKOS_VOICE_FAILED:invalid_enrollment";
+    try {
+        const result = await options.configure(payload.enrollment);
+        if (result.ready)
+            return "PERKOS_VOICE_READY";
+        return `PERKOS_VOICE_ACTION_REQUIRED:${result.actionCode ?? "doctor_not_ready"}`;
+    }
+    catch {
+        return "PERKOS_VOICE_FAILED:local_configuration_failed";
+    }
+}

package/dist/acceptance.d.ts

@@ -0,0 +1,25 @@
+export interface AcceptanceResult {
+    schemaVersion: 1;
+    mode: "local" | "staging";
+    status: "passed" | "failed";
+    checks: {
+        turnsCompleted: number;
+        stallRecovered: boolean;
+        selfLoopSuppressed: boolean;
+        audioPublished: boolean;
+        closed: boolean;
+        rawFiles: number;
+    };
+    stages: {
+        stt: number;
+        runtime: number;
+        ttsFirstByte: number;
+        ttsCompleted: number;
+        audioStarted: number;
+        audioCompleted: number;
+    };
+    failure?: "configuration" | "timeout" | "pipeline";
+}
+export declare function runLocalAcceptance(): Promise<AcceptanceResult>;
+export declare function runStagingAcceptance(env: NodeJS.ProcessEnv): Promise<AcceptanceResult>;
+export declare function localEnvironmentIsSafe(env: NodeJS.ProcessEnv): boolean;

package/dist/acceptance.js

@@ -0,0 +1,147 @@
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VoiceGateway } from "./gateway.js";
+import { TtsError } from "./speechErrors.js";
+import { OpenAiTurnSpeechAdapter } from "./adapters/openaiSpeech.js";
+import { OpenClawChatCompletionsAdapter } from "./adapters/openclaw.js";
+import { EchoSuppressionGate } from "./echoSuppression.js";
+async function* chunks(value) { yield value; }
+class AcceptanceRoom {
+    turns;
+    audioStarted = 0;
+    audioCompleted = 0;
+    cancelled = 0;
+    closed = false;
+    constructor(audio = [new Uint8Array([1, 0]), new Uint8Array([2, 0])]) { this.turns = audio.map((value, index) => ({ turnId: `local-${index + 1}`, audio: chunks(value) })); }
+    async join(_grant) { }
+    async receiveTurn() { const turn = this.turns.shift(); if (!turn)
+        throw new Error("acceptance exhausted"); return turn; }
+    async publish(_turnId, audio) { let started = false; for await (const _ of audio) {
+        if (!started) {
+            started = true;
+            this.audioStarted += 1;
+        }
+    } if (started)
+        this.audioCompleted += 1; return "completed"; }
+    async cancelPublish(_turnId) { this.cancelled += 1; }
+    async close() { this.closed = true; }
+}
+class AcceptanceSpeech {
+    stt = 0;
+    firstByte = 0;
+    completed = 0;
+    cancelled = 0;
+    syntheses = 0;
+    async transcribe(_turnId, audio, _policy) { for await (const _ of audio) { /* transient */ } this.stt += 1; return "fixed-local-transcript"; }
+    async *synthesize(_turnId, _text, _mode) {
+        this.syntheses += 1;
+        this.firstByte += 1;
+        yield new Uint8Array([3, 0]);
+        if (this.syntheses === 1)
+            throw new TtsError("stream_stalled");
+        this.completed += 1;
+    }
+    async cancel(_turnId) { this.cancelled += 1; }
+}
+class AcceptanceRuntime {
+    calls = 0;
+    async respond(_turnId, _input, signal) { if (signal.aborted)
+        throw new Error("aborted"); this.calls += 1; return "fixed-local-response"; }
+    async cancel(_turnId) { }
+}
+export async function runLocalAcceptance() {
+    const scratch = await mkdtemp(join(tmpdir(), "perkos-voice-acceptance-"));
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async () => { throw new Error("local acceptance network denied"); };
+    const room = new AcceptanceRoom();
+    const speech = new AcceptanceSpeech();
+    const runtime = new AcceptanceRuntime();
+    let clock = 0;
+    let suppressed = 0;
+    const gate = new EchoSuppressionGate(() => clock, 10, () => { suppressed += 1; });
+    gate.beginOutput();
+    const loopbackEnqueued = gate.shouldSuppress() ? 0 : 1;
+    gate.endOutput();
+    clock = 11;
+    const intentionalAllowed = !gate.shouldSuppress();
+    const events = [];
+    const gateway = new VoiceGateway(room, speech, runtime, () => new Date("2026-08-15T12:00:00.000Z"), (event) => events.push(event), 100, () => { });
+    const grant = { meetingId: "local-meeting", roomName: "local-room", agentIdentity: "local-agent", expiresAt: "2026-08-15T12:05:00.000Z", token: "local-only" };
+    const request = { projectId: "local-project", meetingId: "local-meeting", agentId: "local-agent", initiatorId: "local", mode: "turn_based", transcriptPolicy: "off" };
+    const handshake = { protocolVersion: "1", capability: { agentId: "local-agent", availability: "available", supportedModes: ["turn_based"], ownership: "external_owner", supportsInterrupt: true, supportsEphemeralTranscript: true, supportsSavedTranscript: false, checkedAt: "2026-08-15T11:59:00.000Z", expiresAt: "2026-08-15T12:05:00.000Z" } };
+    try {
+        await gateway.start({ request, handshake, grant });
+        await gateway.runTurn();
+        await gateway.runTurn();
+        await gateway.close();
+        const rawFiles = (await readdir(scratch)).length;
+        const selfLoopSuppressed = loopbackEnqueued === 0 && intentionalAllowed && suppressed === 1;
+        const passed = speech.stt === 2 && runtime.calls === 2 && speech.firstByte === 2 && speech.completed === 1 && room.audioStarted === 2 && room.audioCompleted === 1 && room.cancelled === 1 && speech.cancelled === 1 && gateway.state.snapshot.state === "closed" && rawFiles === 0 && selfLoopSuppressed;
+        return { schemaVersion: 1, mode: "local", status: passed ? "passed" : "failed", checks: { turnsCompleted: 2, stallRecovered: room.cancelled === 1, selfLoopSuppressed, audioPublished: room.audioCompleted === 1, closed: room.closed, rawFiles }, stages: { stt: speech.stt, runtime: runtime.calls, ttsFirstByte: speech.firstByte, ttsCompleted: speech.completed, audioStarted: room.audioStarted, audioCompleted: room.audioCompleted }, ...(passed ? {} : { failure: "pipeline" }) };
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+export async function runStagingAcceptance(env) {
+    const failed = () => ({ schemaVersion: 1, mode: "staging", status: "failed", failure: "configuration", checks: { turnsCompleted: 0, stallRecovered: false, selfLoopSuppressed: false, audioPublished: false, closed: false, rawFiles: 0 }, stages: { stt: 0, runtime: 0, ttsFirstByte: 0, ttsCompleted: 0, audioStarted: 0, audioCompleted: 0 } });
+    if (env.PERKOS_VOICE_ACCEPTANCE_STAGING !== "1" || env.PERKOS_VOICE_ACCEPTANCE_CONFIRM !== "staging-only" || env.PERKOS_VOICE_ACCEPTANCE_EPHEMERAL !== "1")
+        return failed();
+    const openAiUrl = env.PERKOS_VOICE_ACCEPTANCE_OPENAI_BASE_URL;
+    const openClawUrl = env.PERKOS_VOICE_ACCEPTANCE_OPENCLAW_ENDPOINT;
+    const openAiKey = env.PERKOS_VOICE_ACCEPTANCE_OPENAI_API_KEY;
+    const openClawToken = env.PERKOS_VOICE_ACCEPTANCE_OPENCLAW_TOKEN;
+    const model = env.PERKOS_VOICE_ACCEPTANCE_OPENCLAW_MODEL;
+    const allowed = new Set((env.PERKOS_VOICE_ACCEPTANCE_ALLOWED_ORIGINS ?? "").split(",").map((value) => value.trim()).filter(Boolean));
+    const safeOrigin = (value) => { try {
+        if (!value)
+            return false;
+        const url = new URL(value);
+        const nonprod = url.hostname === "localhost" || /(^|[.-])(staging|stage|test|dev)([.-]|$)/.test(url.hostname);
+        return nonprod && allowed.has(url.origin);
+    }
+    catch {
+        return false;
+    } };
+    if (!openAiKey || !openClawToken || !model || !safeOrigin(openAiUrl) || !safeOrigin(openClawUrl))
+        return failed();
+    const seed = new OpenAiTurnSpeechAdapter({ apiKey: openAiKey, baseUrl: openAiUrl });
+    const seeded = [];
+    try {
+        for await (const chunk of seed.synthesize("staging-seed", "fixed staging acceptance phrase", "turn_based"))
+            seeded.push(chunk);
+        const size = seeded.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+        if (!size)
+            return failed();
+        const pcm = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of seeded) {
+            pcm.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const room = new AcceptanceRoom([pcm, pcm]);
+        const events = [];
+        const speech = new OpenAiTurnSpeechAdapter({ apiKey: openAiKey, baseUrl: openAiUrl, observe: (event) => events.push(event), logFailure: () => { } });
+        const runtime = new OpenClawChatCompletionsAdapter({ endpoint: openClawUrl, token: openClawToken, model });
+        const gateway = new VoiceGateway(room, speech, runtime, () => new Date("2026-08-15T12:00:00.000Z"), (event) => events.push(event), 60_000, () => { });
+        const grant = { meetingId: "staging-meeting", roomName: "staging-room", agentIdentity: "staging-agent", expiresAt: "2026-08-15T12:05:00.000Z", token: "staging-local-only" };
+        const request = { projectId: "staging-project", meetingId: "staging-meeting", agentId: "staging-agent", initiatorId: "acceptance", mode: "turn_based", transcriptPolicy: "off" };
+        const handshake = { protocolVersion: "1", capability: { agentId: "staging-agent", availability: "available", supportedModes: ["turn_based"], ownership: "external_owner", supportsInterrupt: true, supportsEphemeralTranscript: true, supportsSavedTranscript: false, checkedAt: "2026-08-15T11:59:00.000Z", expiresAt: "2026-08-15T12:05:00.000Z" } };
+        await gateway.start({ request, handshake, grant });
+        await gateway.runTurn();
+        await gateway.runTurn();
+        await gateway.close();
+        const stages = { stt: events.filter((value) => value === "stt_success").length, runtime: events.filter((value) => value === "openclaw_success").length, ttsFirstByte: events.filter((value) => value === "tts_first_byte").length, ttsCompleted: events.filter((value) => value === "tts_success").length, audioStarted: room.audioStarted, audioCompleted: room.audioCompleted };
+        const passed = stages.stt === 2 && stages.runtime === 2 && stages.ttsFirstByte === 2 && stages.ttsCompleted === 2 && room.closed;
+        return { schemaVersion: 1, mode: "staging", status: passed ? "passed" : "failed", checks: { turnsCompleted: 2, stallRecovered: false, selfLoopSuppressed: false, audioPublished: room.audioCompleted === 2, closed: room.closed, rawFiles: 0 }, stages, ...(passed ? {} : { failure: "pipeline" }) };
+    }
+    catch {
+        return { ...failed(), failure: "pipeline" };
+    }
+}
+export function localEnvironmentIsSafe(env) {
+    const forbidden = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENCLAW_ENDPOINT", "OPENCLAW_TOKEN", "LIVEKIT_URL", "LIVEKIT_API_KEY", "LIVEKIT_API_SECRET", "PERKOS_VOICE_ACCEPTANCE_OPENAI_API_KEY", "PERKOS_VOICE_ACCEPTANCE_OPENCLAW_TOKEN"];
+    return forbidden.every((key) => !env[key]);
+}

package/dist/acceptanceCli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/acceptanceCli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { localEnvironmentIsSafe, runLocalAcceptance, runStagingAcceptance } from "./acceptance.js";
+const staging = process.env.PERKOS_VOICE_ACCEPTANCE_STAGING === "1";
+const result = staging ? await runStagingAcceptance(process.env) : localEnvironmentIsSafe(process.env) ? await runLocalAcceptance() : { schemaVersion: 1, mode: "local", status: "failed", failure: "configuration", checks: { turnsCompleted: 0, stallRecovered: false, selfLoopSuppressed: false, audioPublished: false, closed: false, rawFiles: 0 }, stages: { stt: 0, runtime: 0, ttsFirstByte: 0, ttsCompleted: 0, audioStarted: 0, audioCompleted: 0 } };
+process.stdout.write(`${JSON.stringify(result)}\n`);
+process.exitCode = result.status === "passed" ? 0 : 1;

package/dist/adapters/livekit.d.ts

@@ -0,0 +1,15 @@
+import type { MediaRoom, MediaTurnInput } from "../ports.js";
+import type { VoiceGatewayGrant } from "../types.js";
+import type { MediaSuccessObserver } from "../mediaMetrics.js";
+export declare class LiveKitMediaRoom implements MediaRoom {
+    #private;
+    private readonly observe?;
+    constructor(observe?: MediaSuccessObserver | undefined);
+    join(grant: VoiceGatewayGrant): Promise<void>;
+    receiveTurn(): Promise<MediaTurnInput>;
+    setInputSuppressed(suppressed: boolean): void;
+    publish(turnId: string, audio: AsyncIterable<Uint8Array>): Promise<"completed" | "cancelled" | "stream_stalled">;
+    setBargeInHandler(handler: (turnId: string) => Promise<void>): void;
+    cancelPublish(turnId: string): Promise<void>;
+    close(): Promise<void>;
+}