@perkos/perkos-voice 0.1.0

package/dist/readiness.js

@@ -0,0 +1,68 @@
+import { validateByoConfig } from "./config.js";
+import { publicCapability } from "./service.js";
+export class GatewayReadiness {
+    config;
+    speech;
+    fetcher;
+    #snapshot = { ready: false, reasons: ["checks_pending"] };
+    constructor(config, speech, fetcher = fetch) {
+        this.config = config;
+        this.speech = speech;
+        this.fetcher = fetcher;
+    }
+    snapshot() { return { ...this.#snapshot, reasons: [...this.#snapshot.reasons] }; }
+    async check() {
+        const validation = validateByoConfig(this.config);
+        const reasons = [...validation.reasons];
+        if (validation.valid) {
+            try {
+                await this.speech?.probe();
+            }
+            catch {
+                reasons.push("speech_probe_failed");
+            }
+            try {
+                const response = await this.fetcher(`${this.config.sessionControlEndpoint.replace(/\/$/, "")}/readiness`, {
+                    headers: { "x-perkos-voice-credential": this.config.grantCredential },
+                    signal: AbortSignal.timeout(10_000),
+                });
+                const result = response.ok ? await response.json() : null;
+                if (result?.readiness?.ready !== true)
+                    reasons.push("control_plane_probe_failed");
+            }
+            catch {
+                reasons.push("control_plane_probe_failed");
+            }
+            try {
+                const runtimeEndpoint = this.config.runtimeEndpoint ?? this.config.openClawEndpoint;
+                const runtimeToken = this.config.runtimeToken ?? this.config.openClawToken;
+                const endpoint = new URL(runtimeEndpoint);
+                const probeUrl = this.config.runtimeProtocol === "zeroclaw_webhook" ? `${endpoint.origin}/health` : `${endpoint.origin}/v1/models`;
+                const response = await this.fetcher(probeUrl, { headers: { authorization: `Bearer ${runtimeToken}` }, signal: AbortSignal.timeout(10_000) });
+                if (!response.ok)
+                    reasons.push("openclaw_probe_failed");
+            }
+            catch {
+                reasons.push("openclaw_probe_failed");
+            }
+        }
+        this.#snapshot = { ready: reasons.length === 0, reasons, checkedAt: new Date().toISOString() };
+        return this.snapshot();
+    }
+    capability(now = new Date()) { return publicCapability(this.config, now, this.#snapshot.ready); }
+}
+export class CapabilityPublisher {
+    endpoint;
+    credential;
+    fetcher;
+    constructor(endpoint, credential, fetcher = fetch) {
+        this.endpoint = endpoint;
+        this.credential = credential;
+        this.fetcher = fetcher;
+    }
+    async publish(handshake) {
+        const response = await this.fetcher(this.endpoint, { method: "POST", headers: { "x-perkos-voice-credential": this.credential, "content-type": "application/json" }, body: JSON.stringify(handshake), signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw new Error(`capability publication failed (${response.status})`);
+    }
+}

package/dist/service.d.ts

@@ -0,0 +1,10 @@
+import { type Server } from "node:http";
+import type { GatewayConfig } from "./config.js";
+import type { VoiceCapabilityHandshake } from "./types.js";
+export declare function publicCapability(config: GatewayConfig, now?: Date, verifiedReady?: boolean): VoiceCapabilityHandshake;
+export declare function startHealthServer(config: GatewayConfig, readiness?: {
+    snapshot(): {
+        ready: boolean;
+        reasons: string[];
+    };
+}): Server;

package/dist/service.js

@@ -0,0 +1,42 @@
+import { createServer } from "node:http";
+import { validateByoConfig } from "./config.js";
+export function publicCapability(config, now = new Date(), verifiedReady = false) {
+    const ready = verifiedReady && validateByoConfig(config).valid;
+    const capabilityAgentId = config.canonicalAgentName || (config.capabilityPublishEndpoint ? "unconfigured" : config.agentId || "unconfigured");
+    return { protocolVersion: "1", capability: {
+            agentId: capabilityAgentId,
+            availability: ready ? "available" : "unavailable",
+            supportedModes: ready ? ["turn_based"] : [],
+            ownership: "external_owner",
+            supportsInterrupt: false,
+            supportsEphemeralTranscript: ready,
+            supportsSavedTranscript: false,
+            checkedAt: now.toISOString(),
+            expiresAt: new Date(now.getTime() + 60_000).toISOString(),
+        } };
+}
+export function startHealthServer(config, readiness) {
+    const server = createServer((request, response) => {
+        response.setHeader("content-type", "application/json");
+        if (request.url === "/health") {
+            response.statusCode = 200;
+            response.end(JSON.stringify({ status: "alive" }));
+            return;
+        }
+        if (request.url === "/ready") {
+            const validation = readiness?.snapshot() ?? { ready: false, reasons: ["checks_pending"] };
+            response.statusCode = validation.ready ? 200 : 503;
+            response.end(JSON.stringify({ status: validation.ready ? "ready" : "unavailable", reasons: validation.reasons }));
+            return;
+        }
+        if (request.url === "/capabilities") {
+            response.statusCode = 200;
+            response.end(JSON.stringify(publicCapability(config, new Date(), readiness?.snapshot().ready === true)));
+            return;
+        }
+        response.statusCode = 404;
+        response.end(JSON.stringify({ error: "not_found" }));
+    });
+    server.listen(config.port, "0.0.0.0");
+    return server;
+}

package/dist/sessionControl.d.ts

@@ -0,0 +1,55 @@
+export interface DynamicVoiceSession {
+    id: string;
+    projectId: string;
+    meetingId: string;
+    agentId: string;
+    enrollmentAgentId: string;
+    audience: "perkos-voice-session-v1";
+    voiceProcessingConsent: true;
+    status: "claimed";
+    expiresAt: string;
+    speechVoice: string;
+    chatCommit: {
+        policy: "none";
+    } | {
+        policy: "final_pair";
+        consent: true;
+        scope: {
+            kind: "direct" | "project";
+            conversationId: string;
+        };
+    };
+    /** Working Call only: bounded rolling brief from bound chat (API claim). */
+    workChatBrief?: string;
+}
+export type SessionTerminalStatus = "joined" | "completed" | "failed" | "cancelled";
+export declare class ChatCommitError extends Error {
+    readonly category: "terminal_conflict" | "retry_exhausted";
+    readonly code = "CHAT_COMMIT_FAILED";
+    constructor(category: "terminal_conflict" | "retry_exhausted");
+}
+export declare function createChatCommitSink(session: DynamicVoiceSession, client: SessionControlClient): ((turn: {
+    turnId: string;
+    transcript: string;
+    response: string;
+    outcome: "completed" | "chat_fallback";
+}) => Promise<void>) | undefined;
+export declare class SessionControlClient {
+    #private;
+    private readonly credential;
+    private readonly fetcher;
+    constructor(endpoint: string, credential: string, fetcher?: typeof fetch);
+    claim(): Promise<DynamicVoiceSession | null>;
+    state(sessionId: string): Promise<{
+        status: string;
+        expiresAt: string;
+    }>;
+    heartbeat(sessionId: string): Promise<{
+        expiresAt: string;
+    }>;
+    update(sessionId: string, status: SessionTerminalStatus, reason?: string, extras?: {
+        healthCodes?: string[];
+        stage?: string;
+    }): Promise<void>;
+    commitChatTurn(sessionId: string, turnId: string, userText: string, assistantText: string, outcome?: "completed" | "chat_fallback"): Promise<void>;
+}

package/dist/sessionControl.js

@@ -0,0 +1,118 @@
+export class ChatCommitError extends Error {
+    category;
+    code = "CHAT_COMMIT_FAILED";
+    constructor(category) {
+        super("Chat commit failed");
+        this.category = category;
+    }
+}
+export function createChatCommitSink(session, client) {
+    if (session.chatCommit.policy !== "final_pair")
+        return undefined;
+    return (turn) => client.commitChatTurn(session.id, turn.turnId, turn.transcript, turn.response, turn.outcome);
+}
+export class SessionControlClient {
+    credential;
+    fetcher;
+    #endpoint;
+    constructor(endpoint, credential, fetcher = fetch) {
+        this.credential = credential;
+        this.fetcher = fetcher;
+        this.#endpoint = endpoint.replace(/\/$/, "");
+    }
+    async claim() {
+        const response = await this.fetcher(`${this.#endpoint}/sessions/claim`, { method: "POST", headers: this.#headers(), signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw new Error(`session claim failed (${response.status})`);
+        const session = (await response.json()).session;
+        if (session === null || session === undefined)
+            return null;
+        return this.#parse(session);
+    }
+    async state(sessionId) {
+        const response = await this.fetcher(`${this.#endpoint}/sessions/${encodeURIComponent(sessionId)}`, { headers: this.#headers(), signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw new Error(`session state failed (${response.status})`);
+        const session = (await response.json()).session;
+        if (typeof session?.status !== "string" || typeof session.expiresAt !== "string")
+            throw new Error("invalid session state");
+        return { status: session.status, expiresAt: session.expiresAt };
+    }
+    async heartbeat(sessionId) {
+        const response = await this.fetcher(`${this.#endpoint}/sessions/${encodeURIComponent(sessionId)}/heartbeat`, { method: "POST", headers: this.#headers(), signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw new Error(`session heartbeat failed (${response.status})`);
+        const expiresAt = (await response.json()).expiresAt;
+        if (typeof expiresAt !== "string" || Date.parse(expiresAt) <= Date.now())
+            throw new Error("invalid renewed session lease");
+        return { expiresAt };
+    }
+    async update(sessionId, status, reason, extras) {
+        const response = await this.fetcher(`${this.#endpoint}/sessions/${encodeURIComponent(sessionId)}/status`, {
+            method: "POST",
+            headers: { ...this.#headers(), "content-type": "application/json" },
+            body: JSON.stringify({
+                status,
+                ...(reason ? { reason } : {}),
+                ...(extras?.healthCodes?.length ? { healthCodes: extras.healthCodes } : {}),
+                ...(extras?.stage ? { stage: extras.stage } : {}),
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            throw new Error(`session status failed (${response.status})`);
+    }
+    async commitChatTurn(sessionId, turnId, userText, assistantText, outcome = "completed") {
+        const url = `${this.#endpoint}/sessions/${encodeURIComponent(sessionId)}/turns/${encodeURIComponent(turnId)}/chat-commit`;
+        const body = JSON.stringify({ outcome, userText, assistantText });
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                const response = await this.fetcher(url, { method: "POST", headers: { ...this.#headers(), "content-type": "application/json" }, body, signal: AbortSignal.timeout(10_000) });
+                if (response.status === 200 || response.status === 201)
+                    return;
+                if (response.status === 409)
+                    throw new ChatCommitError("terminal_conflict");
+                if (response.status !== 502)
+                    throw new ChatCommitError("retry_exhausted");
+                if (attempt === 2)
+                    throw new ChatCommitError("retry_exhausted");
+            }
+            catch (error) {
+                if (error instanceof ChatCommitError)
+                    throw error;
+                if (attempt === 2)
+                    throw new ChatCommitError("retry_exhausted");
+            }
+        }
+    }
+    #headers() { return { "x-perkos-voice-credential": this.credential }; }
+    #parse(input) {
+        const value = input;
+        for (const key of ["id", "projectId", "meetingId", "agentId", "enrollmentAgentId", "expiresAt"])
+            if (typeof value?.[key] !== "string" || !value[key])
+                throw new Error(`session ${key} missing`);
+        if (value.audience !== "perkos-voice-session-v1" || value.voiceProcessingConsent !== true || value.status !== "claimed" || Date.parse(String(value.expiresAt)) <= Date.now())
+            throw new Error("invalid or expired claimed session");
+        const voices = new Set(["alloy", "ash", "ballad", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer", "verse", "marin", "cedar"]);
+        if (typeof value.speechVoice !== "string" || !voices.has(value.speechVoice))
+            throw new Error("invalid session speech voice");
+        const chatCommit = value.chatCommit;
+        if (chatCommit?.policy === "final_pair") {
+            const scope = chatCommit.scope;
+            if (chatCommit.consent !== true || !scope || !["direct", "project"].includes(String(scope.kind)) || typeof scope.conversationId !== "string" || !scope.conversationId)
+                throw new Error("invalid chat commit policy");
+        }
+        else if (chatCommit?.policy !== "none")
+            throw new Error("chat commit policy missing");
+        // workChatBrief only valid for Working Call; ignore otherwise.
+        if (chatCommit?.policy === "final_pair" && typeof value.workChatBrief === "string" && value.workChatBrief.trim()) {
+            const brief = value.workChatBrief.trim().slice(0, 2400);
+            if (brief && !/system prompt|tool_call|```/i.test(brief)) {
+                return { ...value, workChatBrief: brief };
+            }
+        }
+        const session = { ...value };
+        delete session.workChatBrief;
+        return session;
+    }
+}

package/dist/speechErrors.d.ts

@@ -0,0 +1,18 @@
+export type TranscriptionFailureCategory = "http_4xx" | "http_5xx" | "timeout_abort" | "network" | "other";
+export type TtsFailureCategory = "http_4xx" | "http_5xx" | "timeout_abort" | "network" | "malformed" | "stream_stalled" | "other";
+export declare class NoSpeechError extends Error {
+    readonly code = "NO_SPEECH";
+    constructor();
+}
+export declare class TranscriptionError extends Error {
+    readonly category: TranscriptionFailureCategory;
+    readonly code = "TRANSCRIPTION_FAILED";
+    constructor(category: TranscriptionFailureCategory);
+}
+export declare class TtsError extends Error {
+    readonly category: TtsFailureCategory;
+    readonly code = "TTS_FAILED";
+    constructor(category: TtsFailureCategory);
+}
+export declare function transcriptionFailureLog(error: unknown): string | undefined;
+export declare function ttsFailureLog(error: unknown): string | undefined;

package/dist/speechErrors.js

@@ -0,0 +1,26 @@
+export class NoSpeechError extends Error {
+    code = "NO_SPEECH";
+    constructor() { super("No speech detected"); }
+}
+export class TranscriptionError extends Error {
+    category;
+    code = "TRANSCRIPTION_FAILED";
+    constructor(category) {
+        super("Transcription failed");
+        this.category = category;
+    }
+}
+export class TtsError extends Error {
+    category;
+    code = "TTS_FAILED";
+    constructor(category) {
+        super("Speech synthesis failed");
+        this.category = category;
+    }
+}
+export function transcriptionFailureLog(error) {
+    return error instanceof TranscriptionError ? `voice transcription failed: ${error.category}` : undefined;
+}
+export function ttsFailureLog(error) {
+    return error instanceof TtsError ? `voice tts failed: ${error.category}` : undefined;
+}

package/dist/state-machine.d.ts

@@ -0,0 +1,55 @@
+import type { VoiceSessionState } from "./types.js";
+export type VoiceSessionEvent = {
+    type: "authorization_requested";
+} | {
+    type: "authorized";
+} | {
+    type: "join_started";
+} | {
+    type: "joined";
+} | {
+    type: "listening";
+} | {
+    type: "turn_committed";
+    turnId: string;
+} | {
+    type: "turn_skipped";
+    turnId: string;
+} | {
+    type: "response_started";
+    turnId: string;
+} | {
+    type: "response_completed";
+    turnId: string;
+} | {
+    type: "response_aborted";
+    turnId: string;
+} | {
+    type: "barge_in";
+    turnId: string;
+} | {
+    type: "close_requested";
+} | {
+    type: "closed";
+} | {
+    type: "failed";
+    reason: string;
+};
+export declare class InvalidVoiceTransitionError extends Error {
+    readonly code = "INVALID_VOICE_TRANSITION";
+    constructor(state: VoiceSessionState, event: VoiceSessionEvent["type"]);
+}
+export declare class VoiceTurnCorrelationError extends Error {
+    readonly code = "VOICE_TURN_CORRELATION_ERROR";
+}
+export interface VoiceSessionSnapshot {
+    state: VoiceSessionState;
+    activeTurnId?: string;
+    cancelledTurnIds: readonly string[];
+    failureReason?: string;
+}
+export declare class VoiceSessionStateMachine {
+    #private;
+    get snapshot(): VoiceSessionSnapshot;
+    transition(event: VoiceSessionEvent): VoiceSessionSnapshot;
+}

package/dist/state-machine.js

@@ -0,0 +1,107 @@
+export class InvalidVoiceTransitionError extends Error {
+    code = "INVALID_VOICE_TRANSITION";
+    constructor(state, event) {
+        super(`Cannot apply ${event} while voice session is ${state}`);
+    }
+}
+export class VoiceTurnCorrelationError extends Error {
+    code = "VOICE_TURN_CORRELATION_ERROR";
+}
+export class VoiceSessionStateMachine {
+    #state = "preparing";
+    #activeTurnId;
+    #cancelledTurnIds = [];
+    #failureReason;
+    get snapshot() {
+        return {
+            state: this.#state,
+            ...(this.#activeTurnId ? { activeTurnId: this.#activeTurnId } : {}),
+            cancelledTurnIds: [...this.#cancelledTurnIds],
+            ...(this.#failureReason ? { failureReason: this.#failureReason } : {}),
+        };
+    }
+    transition(event) {
+        if (event.type === "failed") {
+            if (this.#state === "closed" || this.#state === "failed")
+                throw new InvalidVoiceTransitionError(this.#state, event.type);
+            this.#state = "failed";
+            this.#failureReason = event.reason;
+            this.#activeTurnId = undefined;
+            return this.snapshot;
+        }
+        if (event.type === "close_requested") {
+            if (["preparing", "closed", "failed", "closing"].includes(this.#state))
+                throw new InvalidVoiceTransitionError(this.#state, event.type);
+            this.#state = "closing";
+            this.#activeTurnId = undefined;
+            return this.snapshot;
+        }
+        if (event.type === "closed") {
+            if (this.#state !== "closing")
+                throw new InvalidVoiceTransitionError(this.#state, event.type);
+            this.#state = "closed";
+            return this.snapshot;
+        }
+        const simple = {
+            authorization_requested: ["preparing", "awaiting_authorization"],
+            authorized: ["awaiting_authorization", "authorized"],
+            join_started: ["authorized", "joining"],
+            joined: ["joining", "connected"],
+            listening: ["connected", "listening"],
+        };
+        const pair = simple[event.type];
+        if (pair) {
+            if (this.#state !== pair[0])
+                throw new InvalidVoiceTransitionError(this.#state, event.type);
+            this.#state = pair[1];
+            return this.snapshot;
+        }
+        if (event.type === "turn_committed") {
+            if (this.#state !== "listening" || this.#activeTurnId)
+                throw new InvalidVoiceTransitionError(this.#state, event.type);
+            if (!event.turnId)
+                throw new VoiceTurnCorrelationError("Turn id is required");
+            this.#activeTurnId = event.turnId;
+            this.#state = "thinking";
+            return this.snapshot;
+        }
+        if (event.type === "response_started") {
+            this.#assertTurn("thinking", event.turnId, event.type);
+            this.#state = "speaking";
+            return this.snapshot;
+        }
+        if (event.type === "turn_skipped") {
+            this.#assertTurn("thinking", event.turnId, event.type);
+            this.#activeTurnId = undefined;
+            this.#state = "listening";
+            return this.snapshot;
+        }
+        if (event.type === "response_completed") {
+            this.#assertTurn("speaking", event.turnId, event.type);
+            this.#activeTurnId = undefined;
+            this.#state = "listening";
+            return this.snapshot;
+        }
+        if (event.type === "response_aborted") {
+            this.#assertTurn("speaking", event.turnId, event.type);
+            this.#activeTurnId = undefined;
+            this.#state = "listening";
+            return this.snapshot;
+        }
+        if (event.type === "barge_in") {
+            this.#assertTurn("speaking", event.turnId, event.type);
+            this.#cancelledTurnIds.push(event.turnId);
+            this.#activeTurnId = undefined;
+            this.#state = "listening";
+            return this.snapshot;
+        }
+        throw new InvalidVoiceTransitionError(this.#state, event.type);
+    }
+    #assertTurn(state, turnId, event) {
+        if (this.#state !== state)
+            throw new InvalidVoiceTransitionError(this.#state, event);
+        if (!turnId || turnId !== this.#activeTurnId) {
+            throw new VoiceTurnCorrelationError(`Event ${event} does not match the active turn`);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+export type VoiceProviderOwnership = "external_owner" | "perkos_managed" | "organization_byok";
+export type VoiceMode = "turn_based" | "realtime";
+export type VoiceAvailability = "available" | "unavailable" | "degraded";
+/**
+ * Public capability declaration. It deliberately excludes provider names,
+ * credentials, network addresses, and any runtime-private configuration.
+ */
+export interface VoiceCapability {
+    agentId: string;
+    availability: VoiceAvailability;
+    supportedModes: VoiceMode[];
+    ownership: VoiceProviderOwnership;
+    supportsInterrupt: boolean;
+    supportsEphemeralTranscript: boolean;
+    supportsSavedTranscript: boolean;
+    checkedAt: string;
+    expiresAt: string;
+}
+export interface VoiceCapabilityHandshake {
+    protocolVersion: "1";
+    capability?: VoiceCapability;
+}
+export type VoiceAvailabilityReason = "available" | "capability_absent" | "capability_invalid" | "agent_mismatch" | "expired" | "reported_unavailable" | "mode_unsupported" | "ownership_unsupported" | "interrupt_unsupported" | "transcript_policy_unsupported";
+export interface VoiceAvailabilityDecision {
+    available: boolean;
+    reason: VoiceAvailabilityReason;
+    capability?: VoiceCapability;
+}
+export type TranscriptPolicy = "off" | "ephemeral" | "saved";
+export interface VoiceSessionRequest {
+    projectId: string;
+    meetingId: string;
+    agentId: string;
+    initiatorId: string;
+    mode: VoiceMode;
+    transcriptPolicy: TranscriptPolicy;
+    /** Owner-selected provider voice, snapshotted by the control plane. */
+    speechVoice?: string;
+    /** Required only when transcriptPolicy is `saved`. */
+    transcriptConsent?: TranscriptConsent;
+}
+export interface TranscriptConsent {
+    granted: true;
+    subjectId: string;
+    grantedAt: string;
+}
+export interface VoiceGatewayGrant {
+    url?: string;
+    meetingId: string;
+    roomName: string;
+    agentIdentity: string;
+    expiresAt: string;
+    token: string;
+}
+export type VoiceSessionState = "preparing" | "awaiting_authorization" | "authorized" | "joining" | "waiting_for_gateway" | "connected" | "listening" | "thinking" | "speaking" | "reconnecting" | "closing" | "closed" | "ended" | "failed";
+export interface VoiceTurn {
+    turnId: string;
+    meetingId: string;
+    agentId: string;
+    state: "started" | "cancelled" | "completed" | "failed";
+    createdAt: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/voiceSubtask.d.ts

@@ -0,0 +1,12 @@
+export declare function languageOfUtterance(text: string): "es" | "en" | "unknown";
+/**
+ * Detach only when the caller asked for a long process (research, investigate,
+ * write a doc, implement). Normal conversation stays on the live turn even if
+ * the runtime is slow (OpenClaw/Hermes often exceed 4s on chat).
+ */
+export declare function looksLikeDetachedVoiceWork(text: string): boolean;
+/** Immediate spoken ack so the call never goes silent while work continues. */
+export declare function voiceSubtaskAck(input: string): string;
+export declare function voiceSubtaskTimedOut(input: string): string;
+/** First audible SLA. Runtime work may continue after this. */
+export declare const VOICE_SPEECH_SLA_MS = 4000;

package/dist/voiceSubtask.js

@@ -0,0 +1,46 @@
+const ES_WORDS = new Set(["el", "la", "los", "las", "de", "que", "qué", "y", "en", "para", "por", "con", "una", "un", "es", "cómo", "puedes", "puedo", "gracias", "hola", "análisis", "analiza", "proyecto"]);
+const EN_WORDS = new Set(["the", "a", "an", "of", "that", "what", "and", "in", "for", "with", "is", "how", "can", "please", "hello", "thanks", "analyze", "project"]);
+export function languageOfUtterance(text) {
+    const words = text.toLocaleLowerCase().match(/[\p{L}]+/gu) ?? [];
+    const es = words.filter((word) => ES_WORDS.has(word)).length;
+    const en = words.filter((word) => EN_WORDS.has(word)).length;
+    if (/[¿¡ñáéíóúü]/iu.test(text) || (es >= 1 && en === 0))
+        return "es";
+    if (en >= 2 && en > es)
+        return "en";
+    return "unknown";
+}
+/**
+ * Detach only when the caller asked for a long process (research, investigate,
+ * write a doc, implement). Normal conversation stays on the live turn even if
+ * the runtime is slow (OpenClaw/Hermes often exceed 4s on chat).
+ */
+export function looksLikeDetachedVoiceWork(text) {
+    const normalized = text.toLocaleLowerCase().replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return false;
+    if (/\b(recuerdas?|recordar|hablamos|conversamos|dijimos|mencionaste|qué te parece|que te parece|expl[ií]came|puedes o[ií]rme|me escuchas|hola|buenas)\b/iu.test(normalized)) {
+        return false;
+    }
+    return (/\b(research|investig(a|ar|ación|acion)|indaga|indagar)\b/iu.test(normalized)
+        || (/\b(busca|buscar|search|look up|google)\b/iu.test(normalized)
+            && /\b(web|internet|online|docs?|documentaci[oó]n|c[oó]digo|codigo|repo|github)\b/iu.test(normalized))
+        || (/\b(escribe|escribir|redacta|redactar|genera|generar|write|draft)\b/iu.test(normalized)
+            && /\b(reporte|informe|documento|spec|prd|plan|archivo|file|doc)\b/iu.test(normalized))
+        || /\b(implementa|implementar|codea|program(a|ar)|crea un pr|open a pr)\b/iu.test(normalized)
+        || (/\b(revisa|audita|analiza)\b/iu.test(normalized)
+            && /\b(c[oó]digo|codigo|repo|codebase|archivos?)\b/iu.test(normalized)));
+}
+/** Immediate spoken ack so the call never goes silent while work continues. */
+export function voiceSubtaskAck(input) {
+    return languageOfUtterance(input) === "es"
+        ? "De acuerdo, lo mandé como subtarea. Sigo aquí; te aviso cuando avance."
+        : "Got it. I sent that as a background task. I'm still here and will update you when it moves.";
+}
+export function voiceSubtaskTimedOut(input) {
+    return languageOfUtterance(input) === "es"
+        ? "Sigo con esa subtarea en segundo plano. Puedes seguir hablándome."
+        : "That task is still running in the background. You can keep talking.";
+}
+/** First audible SLA. Runtime work may continue after this. */
+export const VOICE_SPEECH_SLA_MS = 4_000;

package/dist/workCallContext.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Platform-owned Working Call continuity rules.
+ *
+ * Ownership:
+ * - PerkOS API claim attaches a bounded `workChatBrief` for final_pair sessions.
+ * - PerkOS Voice gateway MUST inject these rules whenever a brief is present.
+ * - Agent soul / A2A / full chat agents do NOT own this path. Media voice is thin
+ *   and must not depend on agent-specific policies that deny prior context.
+ *
+ * External owners implementing a custom runtime beside PerkOS Voice must apply
+ * the same rules when `session.workChatBrief` is present on claim.
+ */
+export declare const WORK_CALL_CONTEXT_RULES: string;
+export declare function formatWorkCallContextBlock(brief: string): string;