@perkos/perkos-a2a 0.12.59 → 0.12.61

package/dist/voice-capability.d.ts

@@ -0,0 +1,19 @@
+import type { A2APluginConfig } from "./types.js";
+export declare const PERKOS_VOICE_PROBE_MARKER: "PERKOS_VOICE_PROBE";
+export declare const PERKOS_VOICE_ENROLL_MARKER: "PERKOS_VOICE_ENROLL";
+type VoiceModule = {
+    handleA2AVoiceMarker: (message: string, options: Record<string, unknown>) => Promise<string | null>;
+    configureA2AVoiceEnrollment: (enrollment: unknown) => Promise<{
+        ready: boolean;
+        actionCode?: string;
+    }>;
+};
+type VoiceModuleLoader = () => Promise<VoiceModule>;
+/**
+ * Optional bridge: exact Voice markers are consumed before the model sees
+ * them. A2A supplies identity/transport only; the separately installed Voice
+ * package owns support detection, credential storage and runtime activation.
+ */
+export declare function tryHandleInstalledVoiceMarker(message: string, config: A2APluginConfig, loadVoice?: VoiceModuleLoader): Promise<string | null>;
+export {};
+//# sourceMappingURL=voice-capability.d.ts.map

package/dist/voice-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-capability.d.ts","sourceRoot":"","sources":["../src/voice-capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,YAAY,CAAC;AAE/D,eAAO,MAAM,yBAAyB,EAAG,oBAA6B,CAAC;AACvE,eAAO,MAAM,0BAA0B,EAAG,qBAA8B,CAAC;AAEzE,KAAK,WAAW,GAAG;IACjB,oBAAoB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpG,2BAA2B,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxG,CAAC;AAEF,KAAK,iBAAiB,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;AAsCpD;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,EACvB,SAAS,GAAE,iBAAiC,GAC3C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB"}

package/dist/voice-capability.js

@@ -0,0 +1,78 @@
+export const PERKOS_VOICE_PROBE_MARKER = "PERKOS_VOICE_PROBE";
+export const PERKOS_VOICE_ENROLL_MARKER = "PERKOS_VOICE_ENROLL";
+function runtime(runtimeKind) {
+    if (runtimeKind === "hermes" || runtimeKind === "hermes-api")
+        return "hermes";
+    if (runtimeKind === "openclaw")
+        return "openclaw";
+    if (runtimeKind === "zeroclaw")
+        return "zeroclaw";
+    return null;
+}
+function controlPlane(config) {
+    const heartbeat = config.platform?.heartbeatUrl;
+    const relayApiKey = config.relay?.apiKey || config.chat?.apiKey;
+    if (!heartbeat || !relayApiKey)
+        return null;
+    let url;
+    try {
+        url = new URL(heartbeat);
+    }
+    catch {
+        return null;
+    }
+    const match = url.pathname.match(/^(.*)\/agents\/([^/]+)\/heartbeat\/?$/u);
+    const agentId = config.platform?.agentId || (match ? decodeURIComponent(match[2]) : "");
+    if (!match || !agentId)
+        return null;
+    return { apiBaseUrl: `${url.origin}${match[1]}`, agentId, relayApiKey };
+}
+async function reportPluginMissing(message, config) {
+    if (message !== PERKOS_VOICE_PROBE_MARKER)
+        return "PERKOS_VOICE_FAILED:voice_plugin_missing";
+    const target = controlPlane(config);
+    if (!target)
+        return "PERKOS_VOICE_FAILED:a2a_identity_unavailable";
+    const response = await fetch(`${target.apiBaseUrl}/agents/${encodeURIComponent(target.agentId)}/voice-credential/capability-report`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${target.relayApiKey}`, "content-type": "application/json" },
+        body: JSON.stringify({ state: "unsupported", reasonCode: "voice_plugin_missing" }),
+    }).catch(() => null);
+    return response?.ok ? "PERKOS_VOICE_UNSUPPORTED:voice_plugin_missing" : "PERKOS_VOICE_FAILED:control_plane_unavailable";
+}
+async function defaultLoader() {
+    const specifier = "@perkos/perkos-voice/a2a";
+    return import(specifier);
+}
+/**
+ * Optional bridge: exact Voice markers are consumed before the model sees
+ * them. A2A supplies identity/transport only; the separately installed Voice
+ * package owns support detection, credential storage and runtime activation.
+ */
+export async function tryHandleInstalledVoiceMarker(message, config, loadVoice = defaultLoader) {
+    const marker = message.trim();
+    if (marker !== PERKOS_VOICE_PROBE_MARKER && marker !== PERKOS_VOICE_ENROLL_MARKER)
+        return null;
+    const target = controlPlane(config);
+    if (!target)
+        return "PERKOS_VOICE_FAILED:a2a_identity_unavailable";
+    const runtimeKind = runtime(config.runtime?.kind);
+    if (!runtimeKind)
+        return reportPluginMissing(marker, config);
+    let voice;
+    try {
+        voice = await loadVoice();
+    }
+    catch {
+        return reportPluginMissing(marker, config);
+    }
+    if (typeof voice.handleA2AVoiceMarker !== "function" || typeof voice.configureA2AVoiceEnrollment !== "function") {
+        return reportPluginMissing(marker, config);
+    }
+    return voice.handleA2AVoiceMarker(marker, {
+        ...target,
+        runtime: runtimeKind,
+        configure: voice.configureA2AVoiceEnrollment,
+    });
+}
+//# sourceMappingURL=voice-capability.js.map

package/dist/voice-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-capability.js","sourceRoot":"","sources":["../src/voice-capability.ts"],"names":[],"mappings":"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"}

package/dist/voice-capability.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=voice-capability.test.d.ts.map

package/dist/voice-capability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-capability.test.d.ts","sourceRoot":"","sources":["../src/voice-capability.test.ts"],"names":[],"mappings":""}

package/dist/voice-capability.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { tryHandleInstalledVoiceMarker } from "./voice-capability.js";
+const config = {
+    agentName: "Athena", port: 5060, skills: [], peers: {},
+    runtime: { kind: "hermes-api" },
+    relay: { url: "wss://transport.perkos.xyz/a2a", apiKey: "rk_private", enabled: true },
+    platform: { agentId: "athena-id", heartbeatUrl: "https://dev.api.perkos.xyz/agents/athena-id/heartbeat" },
+};
+describe("optional Voice capability bridge", () => {
+    it("delegates exact Voice markers with the existing scoped identity", async () => {
+        let options;
+        const result = await tryHandleInstalledVoiceMarker("PERKOS_VOICE_ENROLL", config, async () => ({
+            handleA2AVoiceMarker: async (_message, value) => { options = value; return "PERKOS_VOICE_READY"; },
+            configureA2AVoiceEnrollment: async () => ({ ready: true }),
+        }));
+        expect(result).toBe("PERKOS_VOICE_READY");
+        expect(options?.apiBaseUrl).toBe("https://dev.api.perkos.xyz");
+        expect(options?.agentId).toBe("athena-id");
+        expect(options?.relayApiKey).toBe("rk_private");
+        expect(options?.runtime).toBe("hermes");
+    });
+    it("ignores natural language and keeps Voice parallel", async () => {
+        let loaded = false;
+        const result = await tryHandleInstalledVoiceMarker("please enable calls", config, async () => {
+            loaded = true;
+            throw new Error("not used");
+        });
+        expect(result).toBeNull();
+        expect(loaded).toBe(false);
+    });
+});
+//# sourceMappingURL=voice-capability.test.js.map

package/dist/voice-capability.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-capability.test.js","sourceRoot":"","sources":["../src/voice-capability.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAGtE,MAAM,MAAM,GAAoB;IAC9B,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE;IACtD,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE;IAC/B,KAAK,EAAE,EAAE,GAAG,EAAE,gCAAgC,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE;IACrF,QAAQ,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,uDAAuD,EAAE;CAC1G,CAAC;AAEF,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAClD,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;QAC/E,IAAI,OAA4C,CAAC;QACjD,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAAC,qBAAqB,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YAC7F,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC;YAClG,2BAA2B,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SAC3D,CAAC,CAAC,CAAC;QACJ,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC1C,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAC/D,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3C,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;QACjE,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAAC,qBAAqB,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;YAC3F,MAAM,GAAG,IAAI,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACH,CAAC,CAAC,CAAC"}

package/docs/plans/2026-09-01-optional-voice-package-resolution-design.md

@@ -0,0 +1,24 @@
+# Optional Voice package resolution
+
+## Decision
+
+PerkOS Voice remains a capability parallel to A2A, but A2A declares
+`@perkos/perkos-voice` as an `optionalDependency`. This places the package next
+to A2A in npm-managed private runtime installations, where the existing dynamic
+`import("@perkos/perkos-voice/a2a")` can resolve it normally. Unsupported
+runtimes still report their runtime/model limitation and never enable calls.
+
+The alternatives were an optional peer dependency, which would require every
+runtime installer to perform a second correctly scoped install, or resolving a
+global package path, which is host-specific and bypasses normal Node package
+resolution. The optional dependency is preferred because npm may omit or fail
+it without making A2A installation fail, while a successful installation is
+discoverable without secrets, custom paths, or model involvement.
+
+## Verification
+
+Release validation must prove manifest and lockfile agreement, the existing
+missing-package fallback, successful dynamic delegation, the full A2A suite,
+and a clean external install that imports both package subpaths. The package
+remains absent from A2A responses and no Voice credential crosses the A2A
+boundary.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "perkos-a2a",
   "name": "PerkOS A2A",
-  "version": "0.12.59",
+  "version": "0.12.61",
   "description": "Agent-to-Agent (A2A) protocol communication for OpenClaw agents",
   "author": "PerkOS",
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/perkos-a2a",
-  "version": "0.12.59",
+  "version": "0.12.61",
   "description": "A2A Protocol communication plugin for OpenClaw — Agent-to-Agent protocol implementation",
   "type": "module",
   "main": "dist/index.js",
@@ -78,6 +78,9 @@
     "express": "^4.22.2",
     "ws": "^8.20.1"
   },
+  "optionalDependencies": {
+    "@perkos/perkos-voice": "^0.1.0"
+  },
   "overrides": {
     "qs": "^6.15.2"
   },