@perkos/perkos-voice 0.1.0

package/dist/config.js

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+export function validateByoConfig(config) {
+    const reasons = [];
+    const runtimeEndpoint = config.runtimeEndpoint ?? config.openClawEndpoint;
+    const runtimeToken = config.runtimeToken ?? config.openClawToken;
+    const runtimeModel = config.runtimeModel ?? config.openClawChatModel;
+    if (!config.agentId)
+        reasons.push("agent_id_missing");
+    if (!(config.grantEndpoint && config.grantCredential))
+        reasons.push("grant_delivery_missing");
+    if (!config.sessionControlEndpoint || !config.grantCredential)
+        reasons.push("session_control_missing");
+    if (config.speechMode === "openai_turn") {
+        if (!config.openAiApiKey)
+            reasons.push("openai_speech_missing");
+    }
+    else if (!config.speechEndpoint || !config.speechCredential)
+        reasons.push("byo_speech_missing");
+    if (!runtimeEndpoint || !runtimeToken)
+        reasons.push("openclaw_runtime_missing");
+    if ((config.runtimeProtocol ?? config.openClawApiMode) === "chat_completions" && !runtimeModel)
+        reasons.push("openclaw_chat_model_missing");
+    if (config.openClawVoiceModelOverride) {
+        if (config.openClawApiMode !== "chat_completions")
+            reasons.push("openclaw_voice_model_override_unsupported");
+        if (!(config.openClawVoiceModelAllowlist ?? []).includes(config.openClawVoiceModelOverride))
+            reasons.push("openclaw_voice_model_not_allowed");
+    }
+    if (Boolean(config.capabilityPublishEndpoint) !== Boolean(config.capabilityPublishCredential))
+        reasons.push("capability_publication_incomplete");
+    if (config.capabilityPublishEndpoint && !config.canonicalAgentName)
+        reasons.push("capability_agent_name_missing");
+    for (const [name, value] of [["speech", config.speechEndpoint], ["openclaw", runtimeEndpoint], ["grant", config.grantEndpoint], ["capability", config.capabilityPublishEndpoint], ["session", config.sessionControlEndpoint]]) {
+        if (value) {
+            try {
+                const url = new URL(value);
+                if (url.protocol !== "https:" && !["localhost", "127.0.0.1", "::1"].includes(url.hostname))
+                    reasons.push(`${name}_endpoint_insecure`);
+            }
+            catch {
+                reasons.push(`${name}_endpoint_invalid`);
+            }
+        }
+    }
+    if (config.speechMode === "openai_turn") {
+        try {
+            const url = new URL(config.openAiBaseUrl ?? "https://api.openai.com/v1");
+            if (url.protocol !== "https:" && !["localhost", "127.0.0.1", "::1"].includes(url.hostname))
+                reasons.push("openai_endpoint_insecure");
+        }
+        catch {
+            reasons.push("openai_endpoint_invalid");
+        }
+    }
+    return { valid: reasons.length === 0, reasons };
+}
+export async function loadGatewayConfig(env = process.env) {
+    const secretFile = env.VOICE_SECRET_FILE?.trim();
+    let secrets = {};
+    if (secretFile)
+        secrets = JSON.parse(await readFile(secretFile, "utf8"));
+    return {
+        agentId: env.VOICE_AGENT_ID?.trim() ?? "",
+        canonicalAgentName: env.VOICE_CANONICAL_AGENT_NAME?.trim() || undefined,
+        port: Number(env.VOICE_PORT ?? 8080),
+        transcriptPolicy: env.VOICE_TRANSCRIPT_POLICY === "ephemeral" ? "ephemeral" : "off",
+        projectId: env.VOICE_PROJECT_ID?.trim() || undefined,
+        meetingId: env.VOICE_MEETING_ID?.trim() || undefined,
+        sessionControlEndpoint: env.VOICE_SESSION_CONTROL_ENDPOINT?.trim() || undefined,
+        grantFile: env.VOICE_GRANT_FILE?.trim() || undefined,
+        grantEndpoint: env.VOICE_GRANT_ENDPOINT?.trim() || undefined,
+        grantCredential: secrets.grantCredential,
+        speechEndpoint: env.VOICE_SPEECH_ENDPOINT?.trim() || undefined,
+        speechCredential: secrets.speechCredential,
+        speechMode: env.VOICE_SPEECH_MODE === "openai_turn" ? "openai_turn" : "byo_http",
+        openAiApiKey: secrets.openAiApiKey,
+        openAiBaseUrl: env.OPENAI_BASE_URL?.trim() || "https://api.openai.com/v1",
+        openAiTranscriptionModel: env.OPENAI_TRANSCRIPTION_MODEL?.trim() || "gpt-4o-mini-transcribe",
+        openAiSpeechModel: env.OPENAI_SPEECH_MODEL?.trim() || "gpt-4o-mini-tts",
+        openAiVoice: env.OPENAI_SPEECH_VOICE?.trim() || "alloy",
+        openAiVoiceOverride: env.OPENAI_SPEECH_VOICE_OVERRIDE?.trim() || undefined,
+        openClawEndpoint: env.OPENCLAW_ENDPOINT?.trim() || env.OPENCLAW_RESPONSES_ENDPOINT?.trim() || undefined,
+        openClawToken: secrets.openClawToken,
+        openClawApiMode: env.OPENCLAW_API_MODE === "chat_completions" ? "chat_completions" : "responses",
+        runtimeKind: ["hermes", "openclaw", "zeroclaw"].includes(env.PERKOS_VOICE_RUNTIME ?? "") ? env.PERKOS_VOICE_RUNTIME : "openclaw",
+        runtimeProtocol: env.PERKOS_VOICE_RUNTIME_PROTOCOL === "zeroclaw_webhook"
+            ? "zeroclaw_webhook"
+            : env.PERKOS_VOICE_RUNTIME_PROTOCOL === "chat_completions"
+                ? "chat_completions"
+                : env.PERKOS_VOICE_RUNTIME_PROTOCOL === "responses"
+                    ? "responses"
+                    : undefined,
+        runtimeEndpoint: env.PERKOS_VOICE_RUNTIME_ENDPOINT?.trim() || undefined,
+        runtimeToken: secrets.runtimeToken,
+        runtimeModel: env.PERKOS_VOICE_RUNTIME_MODEL?.trim() || undefined,
+        openClawChatModel: env.OPENCLAW_CHAT_MODEL?.trim() || undefined,
+        openClawVoiceModelOverride: env.OPENCLAW_VOICE_MODEL?.trim() || undefined,
+        openClawVoiceModelAllowlist: (env.OPENCLAW_VOICE_MODEL_ALLOWLIST ?? "").split(",").map((value) => value.trim()).filter(Boolean),
+        openClawSpokenName: env.OPENCLAW_SPOKEN_NAME?.trim() || env.VOICE_CANONICAL_AGENT_NAME?.trim() || undefined,
+        openClawMaxTokens: env.OPENCLAW_MAX_TOKENS ? Number(env.OPENCLAW_MAX_TOKENS) : 80,
+        runtimeTimeoutMs: Number(env.VOICE_RUNTIME_TIMEOUT_MS ?? 12_000),
+        speechSlaMs: Number(env.VOICE_SPEECH_SLA_MS ?? 4_000),
+        presenceMs: env.VOICE_PRESENCE_MS === undefined ? 1_500 : Number(env.VOICE_PRESENCE_MS),
+        capabilityPublishEndpoint: env.VOICE_CAPABILITY_PUBLISH_ENDPOINT?.trim() || undefined,
+        capabilityPublishCredential: secrets.capabilityPublishCredential,
+    };
+}

package/dist/doctor.d.ts

@@ -0,0 +1,55 @@
+import type { GatewayConfig } from "./config.js";
+import { type ExternalAgentOnboardingContract, type ExternalAgentPreflightCode, type ExternalAgentProbePorts } from "./onboarding.js";
+import type { VoiceSessionStage } from "./mediaStages.js";
+/**
+ * Fixed, allow-listed health codes shared by owner-side doctor, gateway
+ * readiness, and the PerkOS control plane. Never include secrets, URLs,
+ * transcripts, chat content, or upstream error bodies.
+ */
+export declare const VOICE_HEALTH_CODES: readonly ["contract_invalid", "config_invalid", "runtime_unhealthy", "runtime_not_ready", "runtime_response_failed", "runtime_response_too_slow", "media_unavailable", "speech_unavailable", "control_plane_unavailable", "capability_publish_unavailable", "session_grant_failed", "session_media_failed", "session_runtime_failed", "session_stage_failed"];
+export type VoiceHealthCode = (typeof VOICE_HEALTH_CODES)[number];
+export type VoiceHealthSource = "doctor" | "gateway_readiness" | "session_outcome";
+export interface VoiceHealthReport {
+    schemaVersion: 1;
+    ready: boolean;
+    codes: VoiceHealthCode[];
+    checkedAt: string;
+    source: VoiceHealthSource;
+    /** Optional allow-listed session stage when source is session_outcome. */
+    stage?: VoiceSessionStage;
+}
+export interface VoiceHealthPlaybook {
+    code: VoiceHealthCode;
+    title: string;
+    /** What the agent owner / their ops agent should do on their side. */
+    ownerActions: string[];
+    /** What PerkOS platform already does / will surface. */
+    platformNotes: string[];
+}
+export declare function isVoiceHealthCode(value: unknown): value is VoiceHealthCode;
+export declare function sanitizeVoiceHealthCodes(codes: readonly unknown[]): VoiceHealthCode[];
+/** Map gateway readiness reason strings → fixed health codes. */
+export declare function mapReadinessReasonsToCodes(reasons: readonly string[]): VoiceHealthCode[];
+export declare function mapSessionStageToCodes(stage: VoiceSessionStage | string): VoiceHealthCode[];
+export declare function playbookForCode(code: VoiceHealthCode): VoiceHealthPlaybook;
+export declare function playbooksForCodes(codes: readonly VoiceHealthCode[]): VoiceHealthPlaybook[];
+export declare function defaultDoctorContract(config: GatewayConfig): ExternalAgentOnboardingContract;
+export declare function buildDoctorProbePorts(config: GatewayConfig, fetcher?: typeof fetch): ExternalAgentProbePorts;
+export interface DoctorRunResult extends VoiceHealthReport {
+    playbooks: VoiceHealthPlaybook[];
+    preflightCodes: ExternalAgentPreflightCode[];
+}
+export declare function runConfiguredVoiceDoctor(config: GatewayConfig, options?: {
+    fetcher?: typeof fetch;
+    now?: () => Date;
+    source?: VoiceHealthSource;
+}): Promise<DoctorRunResult>;
+export declare function healthReportFromReadiness(snapshot: {
+    ready: boolean;
+    reasons: string[];
+    checkedAt?: string;
+}): VoiceHealthReport;
+export declare function healthReportFromSessionFailure(stage: VoiceSessionStage | string): VoiceHealthReport;
+export declare function reportVoiceHealthToControlPlane(endpoint: string, credential: string, report: VoiceHealthReport, fetcher?: typeof fetch): Promise<void>;
+/** Derive POST .../voice-control/health from session control base endpoint. */
+export declare function voiceHealthReportEndpoint(sessionControlEndpoint: string): string;

package/dist/doctor.js

@@ -0,0 +1,423 @@
+import { validateByoConfig } from "./config.js";
+import { EXTERNAL_AGENT_CONTRACT_VERSION, runExternalAgentPreflight, } from "./onboarding.js";
+/**
+ * Fixed, allow-listed health codes shared by owner-side doctor, gateway
+ * readiness, and the PerkOS control plane. Never include secrets, URLs,
+ * transcripts, chat content, or upstream error bodies.
+ */
+export const VOICE_HEALTH_CODES = [
+    "contract_invalid",
+    "config_invalid",
+    "runtime_unhealthy",
+    "runtime_not_ready",
+    "runtime_response_failed",
+    "runtime_response_too_slow",
+    "media_unavailable",
+    "speech_unavailable",
+    "control_plane_unavailable",
+    "capability_publish_unavailable",
+    "session_grant_failed",
+    "session_media_failed",
+    "session_runtime_failed",
+    "session_stage_failed",
+];
+const HEALTH_CODE_SET = new Set(VOICE_HEALTH_CODES);
+export function isVoiceHealthCode(value) {
+    return typeof value === "string" && HEALTH_CODE_SET.has(value);
+}
+export function sanitizeVoiceHealthCodes(codes) {
+    const out = [];
+    for (const code of codes) {
+        if (isVoiceHealthCode(code) && !out.includes(code))
+            out.push(code);
+    }
+    return out;
+}
+/** Map gateway readiness reason strings → fixed health codes. */
+export function mapReadinessReasonsToCodes(reasons) {
+    const codes = new Set();
+    for (const reason of reasons) {
+        if (reason === "checks_pending") {
+            codes.add("runtime_not_ready");
+            continue;
+        }
+        if (reason === "speech_probe_failed" || reason.includes("speech") || reason.includes("openai")) {
+            codes.add("speech_unavailable");
+            continue;
+        }
+        if (reason === "control_plane_probe_failed" || reason.includes("session_control") || reason.includes("grant")) {
+            codes.add("control_plane_unavailable");
+            continue;
+        }
+        if (reason === "openclaw_probe_failed" || reason.includes("openclaw") || reason.includes("runtime")) {
+            codes.add("runtime_not_ready");
+            continue;
+        }
+        if (reason.includes("capability")) {
+            codes.add("capability_publish_unavailable");
+            continue;
+        }
+        if (reason.includes("agent_id") ||
+            reason.includes("missing") ||
+            reason.includes("invalid") ||
+            reason.includes("insecure") ||
+            reason.includes("incomplete") ||
+            reason.includes("not_allowed") ||
+            reason.includes("unsupported")) {
+            codes.add("config_invalid");
+            continue;
+        }
+        codes.add("config_invalid");
+    }
+    return [...codes];
+}
+export function mapSessionStageToCodes(stage) {
+    switch (stage) {
+        case "grant_obtain":
+            return ["session_grant_failed", "control_plane_unavailable"];
+        case "livekit_connect":
+        case "audio_source_create":
+        case "track_create":
+        case "track_publish":
+            return ["session_media_failed", "media_unavailable"];
+        case "gateway_start":
+            return ["session_stage_failed"];
+        case "status_joined":
+            return ["control_plane_unavailable", "session_stage_failed"];
+        case "turn_loop":
+            return ["session_runtime_failed", "runtime_response_failed"];
+        default:
+            return ["session_stage_failed"];
+    }
+}
+export function playbookForCode(code) {
+    const books = {
+        contract_invalid: {
+            title: "External-agent contract invalid",
+            ownerActions: [
+                "Re-read docs/external-agent-onboarding.md and external-agent-contract.schema.json.",
+                "Ensure non-streaming runtime, health/ready/capabilities paths, and secret mode 0600.",
+            ],
+            platformNotes: ["PerkOS will keep capability unavailable until a valid doctor/preflight passes."],
+        },
+        config_invalid: {
+            title: "Gateway configuration incomplete",
+            ownerActions: [
+                "Check VOICE_* env and secret file (grant, capability, OpenClaw/runtime token, speech keys).",
+                "Confirm endpoints use https (or localhost) and VOICE_AGENT_ID / VOICE_CANONICAL_AGENT_NAME match registry.",
+                "Restart only the voice gateway process after fixing config.",
+            ],
+            platformNotes: ["Capability publish is rejected or expires when the gateway is misconfigured."],
+        },
+        runtime_unhealthy: {
+            title: "Agent runtime process not alive",
+            ownerActions: [
+                "Start/restart your agent runtime (OpenClaw, thin OpenAI-compatible API, etc.).",
+                "Verify the runtime process manager (launchd/systemd/docker) KeepAlive policy.",
+            ],
+            platformNotes: ["PerkOS never SSHes into your runtime; only readiness/capability signals."],
+        },
+        runtime_not_ready: {
+            title: "Agent runtime not ready for voice turns",
+            ownerActions: [
+                "Confirm OPENCLAW_ENDPOINT answers authenticated /v1/models (or your health probe).",
+                "If you changed models, pick one that responds within the declared budget (prefer thin chat-completions).",
+                "Do not point voice at a full tool-heavy agent stack if turn latency exceeds ~12–15s.",
+            ],
+            platformNotes: ["Public Call button stays Voice unavailable while readiness is false."],
+        },
+        runtime_response_failed: {
+            title: "Synthetic runtime turn failed",
+            ownerActions: [
+                "Test a short non-streaming chat completion with the same token/model as voice.",
+                "Fix auth, model name, or API mode (chat_completions vs responses).",
+            ],
+            platformNotes: ["Doctor and session outcomes report only fixed codes—no response bodies."],
+        },
+        runtime_response_too_slow: {
+            title: "Runtime turn exceeded budget",
+            ownerActions: [
+                "Switch to a thinner/faster model for voice, or raise only within contract max (≤60s) if your SLA allows.",
+                "Remove multi-k system/tool dumps from the voice path (use thin adapter).",
+            ],
+            platformNotes: ["Slow runtimes cause mid-call turn_loop failures even when /ready looked green."],
+        },
+        media_unavailable: {
+            title: "LiveKit / media path unavailable",
+            ownerActions: [
+                "Confirm outbound network to LiveKit from the gateway host.",
+                "Re-run doctor after network/firewall changes; do not paste LiveKit secrets into chat.",
+            ],
+            platformNotes: ["API readiness requires LiveKit provider config on PerkOS side."],
+        },
+        speech_unavailable: {
+            title: "STT/TTS speech provider unavailable",
+            ownerActions: [
+                "Verify OpenAI (or BYO speech) API key in the gateway secret file.",
+                "Probe speech provider health; rotate key if unauthorized.",
+            ],
+            platformNotes: ["Speech failures surface as speech_unavailable without logging audio."],
+        },
+        control_plane_unavailable: {
+            title: "PerkOS voice control plane unreachable or unauthorized",
+            ownerActions: [
+                "Confirm VOICE_SESSION_CONTROL_ENDPOINT and grant endpoint reach api.perkos.xyz.",
+                "Rotate voice gateway M2M credential if 401; deliver only via secure file (never print full secret).",
+            ],
+            platformNotes: ["M2M audience is perkos-voice-gateway-grant:v1; invalid credentials fail closed."],
+        },
+        capability_publish_unavailable: {
+            title: "Capability publication failed",
+            ownerActions: [
+                "Ensure capability publish endpoint + credential match the grant credential.",
+                "Keep the gateway process up so short leases renew (~30–60s).",
+            ],
+            platformNotes: ["Expired or unpublished capability → Call UI shows Voice unavailable."],
+        },
+        session_grant_failed: {
+            title: "Live session grant failed",
+            ownerActions: [
+                "Verify M2M credential still valid and agent is active in the project meeting.",
+                "Restart gateway; re-test one short call after doctor is green.",
+            ],
+            platformNotes: ["Grants require a claimed session; credential alone cannot mint arbitrary meetings."],
+        },
+        session_media_failed: {
+            title: "In-call media stage failed",
+            ownerActions: [
+                "Check LiveKit connectivity and local audio publish permissions on the gateway host.",
+                "Inspect gateway metrics logs for voice_session_stage_failed:livekit_* (no audio content).",
+            ],
+            platformNotes: ["Session status reason media_failed is stored without transcripts."],
+        },
+        session_runtime_failed: {
+            title: "In-call runtime / turn loop failed",
+            ownerActions: [
+                "Run perkos-voice-doctor; fix runtime_response_* codes first.",
+                "Watch for model timeouts after config/model changes.",
+            ],
+            platformNotes: ["Failed sessions update voice health history for the owner panel."],
+        },
+        session_stage_failed: {
+            title: "Unspecified voice session stage failed",
+            ownerActions: [
+                "Run perkos-voice-doctor and restart the gateway if ready=false.",
+                "Retry one short Private Call after doctor is green.",
+            ],
+            platformNotes: ["Stage name may be attached when reported; content is never stored."],
+        },
+    };
+    return { code, ...books[code] };
+}
+export function playbooksForCodes(codes) {
+    return codes.map(playbookForCode);
+}
+export function defaultDoctorContract(config) {
+    return {
+        version: EXTERNAL_AGENT_CONTRACT_VERSION,
+        runtime: {
+            mode: config.runtimeProtocol ?? (config.openClawApiMode === "chat_completions" ? "chat_completions" : "responses"),
+            nonStreaming: true,
+            cancellation: true,
+            responseTimeoutMs: Math.min(60_000, Math.max(1_000, config.runtimeTimeoutMs ?? 12_000)),
+            healthTimeoutMs: 5_000,
+        },
+        media: { livekit: true, inboundAudio: true, outboundAudio: true, bargeIn: true },
+        speech: { stt: true, tts: true, transcriptPersistence: "off" },
+        control: {
+            dynamicSessions: true,
+            encryptedM2mDelivery: true,
+            oneTimeDiscovery: true,
+            capabilityHandshake: "allow_listed",
+        },
+        install: {
+            immutableRelease: true,
+            secretFileMode: "0600",
+            healthPath: "/health",
+            readinessPath: "/ready",
+            capabilityPath: "/capabilities",
+            configRevision: process.env.VOICE_CONFIG_REVISION?.trim() || "local",
+        },
+    };
+}
+export function buildDoctorProbePorts(config, fetcher = fetch) {
+    const timeout = (ms) => AbortSignal.timeout(ms);
+    return {
+        health: async () => true,
+        readiness: async (signal) => {
+            if (!config.sessionControlEndpoint || !config.grantCredential)
+                return false;
+            const response = await fetcher(`${config.sessionControlEndpoint.replace(/\/$/, "")}/readiness`, {
+                headers: { "x-perkos-voice-credential": config.grantCredential },
+                signal,
+            });
+            if (!response.ok)
+                return false;
+            const body = (await response.json());
+            return body.readiness?.ready === true;
+        },
+        runtimeTurn: async (signal) => {
+            const runtimeEndpoint = config.runtimeEndpoint ?? config.openClawEndpoint;
+            const runtimeToken = config.runtimeToken ?? config.openClawToken;
+            const runtimeModel = config.runtimeModel ?? config.openClawChatModel;
+            const runtimeProtocol = config.runtimeProtocol ?? config.openClawApiMode;
+            if (!runtimeEndpoint || !runtimeToken)
+                return false;
+            if (runtimeProtocol === "zeroclaw_webhook") {
+                const response = await fetcher(runtimeEndpoint, {
+                    method: "POST",
+                    headers: { authorization: `Bearer ${runtimeToken}`, "content-type": "application/json" },
+                    body: JSON.stringify({ message: "Reply with one short word only: ping" }),
+                    signal,
+                });
+                if (!response.ok)
+                    return false;
+                const body = await response.json();
+                return typeof body.response === "string" && body.response.trim().length > 0;
+            }
+            if (runtimeProtocol === "chat_completions") {
+                const response = await fetcher(runtimeEndpoint, {
+                    method: "POST",
+                    headers: {
+                        authorization: `Bearer ${runtimeToken}`,
+                        "content-type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        model: runtimeModel,
+                        messages: [
+                            { role: "system", content: "Reply with one short word only." },
+                            { role: "user", content: "ping" },
+                        ],
+                        max_tokens: 8,
+                        temperature: 0,
+                    }),
+                    signal,
+                });
+                if (!response.ok)
+                    return false;
+                const body = (await response.json());
+                const text = body.choices?.[0]?.message?.content;
+                return typeof text === "string" && text.trim().length > 0;
+            }
+            const origin = new URL(runtimeEndpoint).origin;
+            const response = await fetcher(`${origin}/v1/models`, {
+                headers: { authorization: `Bearer ${runtimeToken}` },
+                signal,
+            });
+            return response.ok;
+        },
+        media: async () => true,
+        speech: async (signal) => {
+            if (config.speechMode === "openai_turn") {
+                if (!config.openAiApiKey)
+                    return false;
+                const base = (config.openAiBaseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+                const response = await fetcher(`${base}/models`, {
+                    headers: { authorization: `Bearer ${config.openAiApiKey}` },
+                    signal,
+                });
+                return response.ok;
+            }
+            if (!config.speechEndpoint || !config.speechCredential)
+                return false;
+            const response = await fetcher(`${config.speechEndpoint.replace(/\/$/, "")}/health`, {
+                headers: { authorization: `Bearer ${config.speechCredential}` },
+                signal,
+            });
+            return response.ok;
+        },
+        controlPlane: async (signal) => {
+            if (!config.sessionControlEndpoint || !config.grantCredential)
+                return false;
+            const response = await fetcher(`${config.sessionControlEndpoint.replace(/\/$/, "")}/readiness`, {
+                headers: { "x-perkos-voice-credential": config.grantCredential },
+                signal,
+            });
+            return response.ok;
+        },
+        capabilityPublisher: async (signal) => {
+            if (!config.capabilityPublishEndpoint || !config.capabilityPublishCredential)
+                return false;
+            // OPTIONS-like: a GET is not defined; treat endpoint shape + credential presence as configured.
+            // Real publish is exercised by the running gateway; doctor avoids posting fake capability.
+            void signal;
+            return true;
+        },
+    };
+}
+export async function runConfiguredVoiceDoctor(config, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const fetcher = options.fetcher ?? fetch;
+    const validation = validateByoConfig(config);
+    if (!validation.valid) {
+        const codes = mapReadinessReasonsToCodes(validation.reasons);
+        const finalCodes = codes.length > 0 ? codes : ["config_invalid"];
+        return {
+            schemaVersion: 1,
+            ready: false,
+            codes: finalCodes,
+            checkedAt: now().toISOString(),
+            source: options.source ?? "doctor",
+            playbooks: playbooksForCodes(finalCodes),
+            preflightCodes: ["contract_invalid"],
+        };
+    }
+    const contract = defaultDoctorContract(config);
+    const preflight = await runExternalAgentPreflight(contract, buildDoctorProbePorts(config, fetcher), now);
+    const codes = sanitizeVoiceHealthCodes(preflight.codes);
+    return {
+        schemaVersion: 1,
+        ready: preflight.ready && codes.length === 0,
+        codes,
+        checkedAt: preflight.checkedAt,
+        source: options.source ?? "doctor",
+        playbooks: playbooksForCodes(codes),
+        preflightCodes: preflight.codes,
+    };
+}
+export function healthReportFromReadiness(snapshot) {
+    const codes = snapshot.ready ? [] : mapReadinessReasonsToCodes(snapshot.reasons);
+    return {
+        schemaVersion: 1,
+        ready: snapshot.ready && codes.length === 0,
+        codes,
+        checkedAt: snapshot.checkedAt ?? new Date().toISOString(),
+        source: "gateway_readiness",
+    };
+}
+export function healthReportFromSessionFailure(stage) {
+    const codes = mapSessionStageToCodes(stage);
+    return {
+        schemaVersion: 1,
+        ready: false,
+        codes,
+        checkedAt: new Date().toISOString(),
+        source: "session_outcome",
+        stage: (typeof stage === "string" ? stage : "gateway_start"),
+    };
+}
+export async function reportVoiceHealthToControlPlane(endpoint, credential, report, fetcher = fetch) {
+    const body = {
+        schemaVersion: 1,
+        ready: report.ready,
+        codes: sanitizeVoiceHealthCodes(report.codes),
+        checkedAt: report.checkedAt,
+        source: report.source,
+        ...(report.stage ? { stage: report.stage } : {}),
+    };
+    const response = await fetcher(endpoint, {
+        method: "POST",
+        headers: {
+            "x-perkos-voice-credential": credential,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok)
+        throw new Error(`voice_health_report_failed:${response.status}`);
+}
+/** Derive POST .../voice-control/health from session control base endpoint. */
+export function voiceHealthReportEndpoint(sessionControlEndpoint) {
+    return `${sessionControlEndpoint.replace(/\/$/, "")}/health`;
+}

package/dist/doctorCli.d.ts

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

package/dist/doctorCli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Owner-side Voice doctor for external (and internal) agents.
+ *
+ * Usage (same env + VOICE_SECRET_FILE as the gateway):
+ *   perkos-voice-doctor
+ *   perkos-voice-doctor --report   # also POST codes to PerkOS control plane
+ *
+ * Exit 0 when ready; 1 when not. stdout is JSON only (no secrets).
+ */
+import { loadGatewayConfig } from "./config.js";
+import { reportVoiceHealthToControlPlane, runConfiguredVoiceDoctor, voiceHealthReportEndpoint, } from "./doctor.js";
+const report = process.argv.includes("--report");
+const config = await loadGatewayConfig();
+const result = await runConfiguredVoiceDoctor(config);
+let reported = false;
+let reportError;
+if (report && config.sessionControlEndpoint && config.grantCredential) {
+    try {
+        await reportVoiceHealthToControlPlane(voiceHealthReportEndpoint(config.sessionControlEndpoint), config.grantCredential, result);
+        reported = true;
+    }
+    catch {
+        reportError = "report_failed";
+    }
+}
+process.stdout.write(`${JSON.stringify({
+    schemaVersion: result.schemaVersion,
+    ready: result.ready,
+    codes: result.codes,
+    checkedAt: result.checkedAt,
+    source: result.source,
+    playbooks: result.playbooks,
+    ...(report ? { reported, ...(reportError ? { reportError } : {}) } : {}),
+})}\n`);
+process.exitCode = result.ready ? 0 : 1;

package/dist/echoSuppression.d.ts

@@ -0,0 +1,13 @@
+export declare class EchoSuppressionGate {
+    #private;
+    private readonly now;
+    private readonly cooldownMs;
+    private readonly onSuppressed;
+    constructor(now?: () => number, cooldownMs?: number, onSuppressed?: () => void);
+    start(barrier: Promise<void>): void;
+    beginOutput(): void;
+    endOutput(): void;
+    shouldSuppress(): boolean;
+    waitForBarrier(): Promise<void>;
+}
+export declare function acceptRemoteMicrophone(source: unknown, microphoneSource: unknown, remoteIdentity: string, localIdentity?: string, agentIdentity?: string): boolean;