AgentsCant

AgentsCant is a small TypeScript SDK for a synthetic agent sound protocol. It encodes short tokens or message IDs into generated WAV audio that sounds unlike mainstream human languages, then decodes that audio back into the same token.

It now supports two payload modes:

• lookup: encode a token or messageId and let the host app recover the full text
• direct-text: embed short full text directly in the Agent Cant payload and decode it back without a lookup

The first version is intentionally not a natural-language training project. It is a deterministic protocol layer for agent systems:

• applications keep the canonical text on the server
• AgentsCant audio carries only a short token or message ID
• decoders validate the protocol version and checksum/HMAC
• humans can hear a distinctive agent voice while software gets a reliable ID

Install

Local development:

npm install
npm run build
npm test

As a dependency before publishing:

pnpm add file:E:/VP/agentscant

After pushing to GitHub:

pnpm add github:UncleK/agentscant#v0.2.0

If published to npm:

pnpm add agentscant

API

import { decodeAgentCant, encodeAgentCant } from "agentscant";

const audio = encodeAgentCant({
  messageId: "dm-message-123",
  secret: process.env.AGENT_CANT_SECRET,
  minDurationMs: 3000,
});

const decoded = decodeAgentCant({
  wavBytes: audio.wavBytes,
  secret: process.env.AGENT_CANT_SECRET,
});

Direct-text mode embeds the text in the sound itself. By default it uses the version 2 dense protocol so the decoder can restore the full text without a server lookup:

const audio = encodeAgentCant({
  text: "我有一个美丽的愿望",
  payloadMode: "direct-text",
  secret: process.env.AGENT_CANT_SECRET,
});

const decoded = decodeAgentCant({
  wavBytes: audio.wavBytes,
  secret: process.env.AGENT_CANT_SECRET,
});

console.log(decoded.text);

encodeAgentCant returns:

{
  wavBytes: Uint8Array;
  mimeType: "audio/wav";
  durationMs: number;
  protocolVersion: number;
  payloadMode: "lookup" | "direct-text";
  token: string;
  messageId?: string;
  text?: string;
  checksum: string;
}

decodeAgentCant returns:

{
  ok: boolean;
  payloadMode?: "lookup" | "direct-text";
  token?: string;
  messageId?: string;
  text?: string;
  checksumValid: boolean;
  protocolVersion?: number;
  error?: string;
}

CLI

npm run build
node dist/cli/agentscant.js encode --message-id demo-001 --secret demo --out demo.wav
node dist/cli/agentscant.js encode --payload-mode direct-text --text "hello agent" --secret demo --out demo.wav
node dist/cli/agentscant.js decode --in demo.wav --secret demo

Robustness Harness

To generate the current robustness report and deterministic degraded fixtures:

npm run robustness

This writes:

• reports/robustness/latest.json
• reports/robustness/latest.md
• generated WAV fixtures under fixtures/pristine/ and fixtures/degraded/

Support notes and recorded-fixture status live in docs/support.md. The current v0.2 report passes every generated degradation case and keeps real recorded playback-rerecord samples measured as known unsupported inputs on this workstation.

Speech Roundtrip Check

To sanity-check a host-style flow of speech recognition into Agent Cant token audio and back to a recovered message lookup:

npm run voice:roundtrip

This writes:

• reports/voice/latest.json
• reports/voice/latest.md
• generated Agent Cant WAV samples under reports/voice/audio/

The current helper uses local faster-whisper transcription to produce the canonical text, then encodes a messageId with AgentsCant and restores the same recognized text via that messageId.

Use --payload-mode direct-text to validate the full direct-text chain instead:

npm run voice:roundtrip -- --payload-mode direct-text

Voice Demo Page

To launch the local demo page with:

• example Chinese and English source clips
• generated Agent Cant special audio for each example
• upload a clip up to 10 seconds
• local speech recognition and Agent Cant audio generation

run:

npm run voice:demo

Then open:

http://localhost:4173/voice/

The current local demo expects Python with faster-whisper available for the upload-to-transcription step, which is the same dependency used by the roundtrip check.

Protocol Shape

Version 1 uses a simple, inspectable sound codec:

• 44.1 kHz mono PCM WAV
• fixed preamble tones to identify Agent Cant audio
• hexadecimal symbols encoded as short musical tones
• URL-encoded payload with magic, version, payload mode, token, optional message ID, optional direct text, checksum
• checksum is SHA-256 by default or HMAC-SHA-256 when secret is provided

Version 2 is the default for new audio and uses a dense binary ACN2 payload over the byte transport.

The demo keeps two lanes:

• lookup / short mode: recommended for Agents Chat product traffic. The audio carries a compact token or message ID, and the host app restores canonical text from its own storage.
• direct-text / full mode: self-contained mode. The audio carries checksum, optional message ID/custom token, and raw or deflate-compressed UTF-8 text.

The byte transport emits one byte per symbol by carrying the low and high nibbles on two simultaneous tone bands. minDurationMs can add non-data hum padding for product feel; the local demo uses 3000 ms so very short messages still feel like a spoken turn.

Pass version: 1 only when you need legacy audio.

Agents Chat Integration Boundary

AgentsCant only handles the sound protocol. A host application such as Agents Chat should own:

• microphone recording
• human speech-to-text
• message creation
• asset storage
• agent runtime delivery
• caption display

This keeps AgentsCant reusable for OpenClaw plugins, other agent runtimes, and future chat systems.

Roadmap

The repository currently ships the v0.2 robustness release in this repository, with v0.3 next for packaging and ecosystem work.

For the full release path, scope boundaries, and current milestone links, see ROADMAP.md.

License

MIT