@perkos/perkos-voice 0.1.0

package/dist/workCallContext.js

@@ -0,0 +1,26 @@
+/**
+ * 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 const WORK_CALL_CONTEXT_RULES = "This is a Working Call bound to the user's work chat. " +
+    "If Work-chat context appears below, it is real prior context from earlier final turns in this same chat — " +
+    "use it when the user refers to prior discussion, plans, or projects. " +
+    "Never claim you have no prior context when Work-chat context is present. " +
+    "You do not browse the full chat UI or tools; you only have this brief. " +
+    "Prefer the live user message when it conflicts. " +
+    "Do not invent facts absent from the brief or the live turn. " +
+    "Do not read the brief aloud unless asked.";
+export function formatWorkCallContextBlock(brief) {
+    const cleaned = brief.trim();
+    if (!cleaned)
+        return "";
+    return `${WORK_CALL_CONTEXT_RULES}\n\nWork-chat context:\n${cleaned}`;
+}

package/docs/external-agent-onboarding.md

@@ -0,0 +1,152 @@
+# External-agent onboarding contract
+
+This contract standardizes installation of PerkOS Voice beside an external
+agent runtime when PerkOS cannot inspect or operate the agent's chat surface.
+The only required runtime integration is a private, authenticated,
+non-streaming request/response endpoint. Tools and identity remain inside the
+agent runtime.
+
+## Required contract
+
+`external-agent-contract.schema.json` is the machine-readable source of truth.
+`ExternalAgentOnboardingContract` and `runExternalAgentPreflight` provide the
+same contract for installers and tests.
+
+- The runtime must return one bounded non-streaming response, support
+  cancellation, answer its health probe within 10 seconds, and complete a **spoken**
+  turn within a declared budget no greater than 60 seconds. A deployment should use
+  the smallest budget the runtime can meet consistently.
+- If the runtime starts longer work (research, investigate, write a doc,
+  implement) **and** the caller asked for that process, the gateway speaks
+  within `VOICE_SPEECH_SLA_MS` (default 4s): it tells the caller a **subtask**
+  was launched and keeps the call listening. Normal conversation
+  (“¿recuerdas?”, “de qué hablamos”) stays on the live turn even if the
+  runtime is slow. Do not rely on the agent soul to decide this.
+- If a live turn is still thinking after `VOICE_PRESENCE_MS` (default 1.5s),
+  the gateway plays a local non-verbal presence tone (soft ticks) so the
+  caller knows the line is alive. The tone stops the moment the runtime
+  answers or the subtask ack speaks. `VOICE_PRESENCE_MS=0` disables it.
+  Do not use OpenAI TTS for this cue.
+- The gateway must connect outbound to LiveKit, receive and publish audio,
+  support barge-in, and have working STT and TTS adapters. Raw audio and
+  transcripts are never part of the preflight result; transcript persistence
+  is `off`.
+- Control requires dynamic short-lived sessions, encrypted one-use M2M
+  delivery/discovery, and allow-listed capability publication. Agent, project,
+  audience and expiry bindings remain API-enforced.
+- Health means the process is alive. Readiness means runtime, media, speech,
+  M2M/control and capability publication probes all passed. Capability must be
+  unavailable or expired whenever readiness is false.
+
+The preflight emits only fixed stage codes. It accepts injected probe ports, so
+CI uses fakes and production can test private dependencies without logging
+addresses, credentials, request content, transcripts, audio, or upstream error
+bodies. There is intentionally no `chat` probe.
+
+## Idempotent install and rollback
+
+An installer records only an immutable image revision and a non-secret config
+revision. `evaluateExternalAgentInstall` returns:
+
+- `noop` when image, config and mode-0600 secret permissions already match;
+- `reconfigure` for config drift or unsafe secret permissions;
+- `replace_release` when the immutable image revision changes.
+
+Before either mutation, retain the current immutable image reference and a
+root-only configuration snapshot. Apply one component change, restart only the
+gateway, and require `/health` before checking `/ready`. If health or preflight
+fails, restore both references, restart the gateway, and publish unavailable.
+Never mutate the agent runtime, chat, relay, firewall or provider account as an
+implicit install step.
+
+## Acceptance harness
+
+An external owner can implement every `ExternalAgentProbePorts` method locally.
+The harness proves the integration without PerkOS chat access:
+
+1. validate the versioned contract and install decision;
+2. probe liveness and readiness;
+3. submit a synthetic, non-secret bounded runtime turn and verify a non-empty
+   result within the declared budget;
+4. probe LiveKit media, STT/TTS, M2M session control and capability publisher;
+5. expose only `ready`, `checkedAt` and fixed failure codes;
+6. publish ready capability only after the complete result is green.
+
+Provider calls are replaced with fakes in unit tests. A production smoke test
+is separate, consent-bound and limited to one short session. It verifies media,
+runtime response, playback, cancellation/end, absence of raw persistence and
+continued agent health.
+
+## Voice doctor and control-plane health (external agents)
+
+External owners (and their ops agents) **self-heal** without PerkOS reading
+their chat. The product split is:
+
+| Layer | Who | What |
+|---|---|---|
+| `perkos-voice-doctor` | Owner host | Runs fixed probes against runtime, speech, control plane; prints JSON codes + playbooks; exit 1 if not ready |
+| `perkos-voice-doctor --report` | Owner host | Same, then `POST .../voice-control/health` with codes only |
+| Gateway readiness loop | Gateway process | Publishes capability + health snapshot ~every 30s |
+| Failed call | Gateway + API | Session `failed` + optional `stage` / `healthCodes` → `voiceHealth` history |
+| `GET /agents/:id/voice-health` | PerkOS owner UI | Last codes, recent events, repair playbooks (no chat/audio/secrets) |
+
+### Owner commands
+
+```bash
+# Same env + VOICE_SECRET_FILE as the running gateway
+npx perkos-voice-doctor
+npx perkos-voice-doctor --report
+```
+
+Stdout is JSON only:
+
+```json
+{
+  "schemaVersion": 1,
+  "ready": false,
+  "codes": ["runtime_not_ready", "speech_unavailable"],
+  "checkedAt": "...",
+  "source": "doctor",
+  "playbooks": [{ "code": "runtime_not_ready", "title": "...", "ownerActions": ["..."], "platformNotes": ["..."] }]
+}
+```
+
+### Fixed codes (allow-listed)
+
+Preflight/install: `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 outcomes: `session_grant_failed`, `session_media_failed`,
+`session_runtime_failed`, `session_stage_failed`.
+
+Never log or store: transcripts, audio, secrets, runtime URLs, upstream error
+bodies, or agent chat content.
+
+### Installer recommendation
+
+On failure of `/ready` or doctor:
+
+1. Map codes → playbook actions (restart runtime, rotate M2M, fix speech key).
+2. Restart **only** the voice gateway (not the agent soul/chat unless the code
+   is runtime_*).
+3. Re-run doctor until `ready: true`, then confirm capability available in the app.
+
+PerkOS will not SSH into external hosts or open the agent’s chat surface.
+
+## Working Call context (required for all agents)
+
+PerkOS Voice media path is thin: it does **not** load the agent’s full A2A/chat
+stack. Continuity across Working Calls is provided by the control plane:
+
+- Claim may include `session.workChatBrief` for `final_pair` sessions only.
+- If present, your runtime (or the PerkOS thin chat-completions adapter) **must**
+  treat that brief as real prior work-chat context for the live call.
+- Do not answer “I have no access to previous conversations” when a brief is
+  present. You still must not invent facts outside the brief + live turn.
+- Private Call (`chatCommit.policy = none`) has no brief and must not persist
+  turns to chat.
+
+Installers should not put this rule only in agent soul/A2A prompts. The gateway
+claim path is the source of truth so every external runtime behaves the same.

package/external-agent-contract.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://perkos.xyz/schemas/voice/external-agent-v1.json",
+  "title": "PerkOS Voice external-agent onboarding contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "runtime", "media", "speech", "control", "install"],
+  "properties": {
+    "version": { "const": "perkos.voice.external-agent/v1" },
+    "runtime": {
+      "type": "object", "additionalProperties": false,
+      "required": ["mode", "nonStreaming", "cancellation", "responseTimeoutMs", "healthTimeoutMs"],
+      "properties": {
+        "mode": { "enum": ["responses", "chat_completions", "zeroclaw_webhook"] },
+        "nonStreaming": { "const": true },
+        "cancellation": { "const": true },
+        "responseTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 },
+        "healthTimeoutMs": { "type": "integer", "minimum": 250, "maximum": 10000 }
+      }
+    },
+    "media": {
+      "type": "object", "additionalProperties": false,
+      "required": ["livekit", "inboundAudio", "outboundAudio", "bargeIn"],
+      "properties": { "livekit": { "const": true }, "inboundAudio": { "const": true }, "outboundAudio": { "const": true }, "bargeIn": { "const": true } }
+    },
+    "speech": {
+      "type": "object", "additionalProperties": false,
+      "required": ["stt", "tts", "transcriptPersistence"],
+      "properties": { "stt": { "const": true }, "tts": { "const": true }, "transcriptPersistence": { "const": "off" } }
+    },
+    "control": {
+      "type": "object", "additionalProperties": false,
+      "required": ["dynamicSessions", "encryptedM2mDelivery", "oneTimeDiscovery", "capabilityHandshake"],
+      "properties": { "dynamicSessions": { "const": true }, "encryptedM2mDelivery": { "const": true }, "oneTimeDiscovery": { "const": true }, "capabilityHandshake": { "const": "allow_listed" } }
+    },
+    "install": {
+      "type": "object", "additionalProperties": false,
+      "required": ["immutableRelease", "secretFileMode", "healthPath", "readinessPath", "capabilityPath", "configRevision"],
+      "properties": {
+        "immutableRelease": { "const": true }, "secretFileMode": { "const": "0600" },
+        "healthPath": { "const": "/health" }, "readinessPath": { "const": "/ready" }, "capabilityPath": { "const": "/capabilities" },
+        "configRevision": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "perkos-voice",
+  "name": "PerkOS Voice",
+  "version": "0.1.0",
+  "description": "Installs and supervises the PerkOS Voice gateway beside OpenClaw",
+  "author": "PerkOS",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["agentId", "agentName", "environment", "secretFile", "sessionControlEndpoint", "grantEndpoint", "capabilityPublishEndpoint"],
+    "properties": {
+      "agentId": { "type": "string", "minLength": 3 },
+      "agentName": { "type": "string", "minLength": 1 },
+      "environment": { "enum": ["dev", "qa", "production"] },
+      "secretFile": { "type": "string", "minLength": 1 },
+      "runtimeEndpoint": { "type": "string", "default": "http://127.0.0.1:18789/v1/responses" },
+      "runtimeProtocol": { "enum": ["responses", "chat_completions"], "default": "responses" },
+      "runtimeModel": { "type": "string" },
+      "sessionControlEndpoint": { "type": "string", "format": "uri" },
+      "grantEndpoint": { "type": "string", "format": "uri" },
+      "capabilityPublishEndpoint": { "type": "string", "format": "uri" },
+      "port": { "type": "number", "default": 18081 }
+    }
+  },
+  "activation": { "onStartup": true }
+}
+

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@perkos/perkos-voice",
+  "version": "0.1.0",
+  "description": "Voice gateway contracts and runtime adapters for PerkOS agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "perkos-voice": "dist/cli.js",
+    "perkos-voice-doctor": "dist/doctorCli.js",
+    "perkos-voice-bragi-delivery": "dist/bragiDeliveryCli.js",
+    "perkos-voice-acceptance": "dist/acceptanceCli.js",
+    "perkos-voice-install-hermes": "scripts/hermes/install.mjs",
+    "perkos-voice-install-zeroclaw": "scripts/zeroclaw/install.mjs"
+  },
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./openclaw": {
+      "types": "./dist/openclaw-plugin.d.ts",
+      "default": "./dist/openclaw-plugin.js"
+    },
+    "./a2a": {
+      "types": "./dist/a2aEnrollment.d.ts",
+      "default": "./dist/a2aEnrollment.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "external-agent-contract.schema.json",
+    "docs/external-agent-onboarding.md",
+    "README.md",
+    "openclaw.plugin.json",
+    "scripts/hermes/install.mjs",
+    "scripts/zeroclaw/install.mjs",
+    "scripts/run-with-env.mjs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test .test-dist/*.test.js .test-dist/adapters/*.test.js",
+    "acceptance:local": "node dist/acceptanceCli.js"
+  },
+  "keywords": [
+    "perkos",
+    "voice",
+    "livekit",
+    "openclaw",
+    "hermes",
+    "agent"
+  ],
+  "author": "PerkOS <julio.cruz@eb-ms.net>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerkOS-xyz/PerkOS-Voice.git"
+  },
+  "openclaw": {
+    "extensions": ["./dist/openclaw-plugin.js"],
+    "install": {
+      "npmSpec": "@perkos/perkos-voice",
+      "localPath": "extensions/perkos-voice",
+      "defaultChoice": "npm"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": { "@livekit/rtc-node": "0.13.33" }
+}

package/scripts/hermes/install.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function value(flag) {
+  const index = process.argv.indexOf(flag);
+  return index < 0 ? undefined : process.argv[index + 1];
+}
+function fail(message) { process.stderr.write(`perkos-voice-install-hermes: ${message}\n`); process.exit(2); }
+function xml(value) { return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;"); }
+
+if (process.argv.includes("--help")) {
+  process.stdout.write(`Usage: perkos-voice-install-hermes --emit --agent-id ID --agent-name NAME --environment dev|qa|production --voice-env-file PATH --secret-file PATH\n`);
+  process.exit(0);
+}
+if (!process.argv.includes("--emit")) fail("only the reviewable --emit mode is supported in v1");
+const agentId = value("--agent-id");
+const agentName = value("--agent-name");
+const environment = value("--environment");
+const envFile = value("--voice-env-file");
+const secretFile = value("--secret-file");
+if (!agentId || !agentName || !envFile || !secretFile) fail("agent, environment, env-file and secret-file are required");
+if (!["dev", "qa", "production"].includes(environment)) fail("environment must be dev, qa or production");
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const cli = resolve(root, "dist", "cli.js");
+const envLauncher = resolve(root, "scripts", "run-with-env.mjs");
+const label = `xyz.perkos.voice.${agentName.toLowerCase().replace(/[^a-z0-9]+/g, "-")}.${environment}`;
+const common = {
+  VOICE_AGENT_ID: agentId,
+  VOICE_CANONICAL_AGENT_NAME: agentName,
+  VOICE_SECRET_FILE: secretFile,
+  PERKOS_VOICE_RUNTIME: "hermes",
+};
+
+if (platform() === "darwin") {
+  const pairs = Object.entries(common).map(([key, entry]) => `    <key>${key}</key>\n    <string>${xml(entry)}</string>`).join("\n");
+  process.stdout.write(`<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(envLauncher)}</string><string>--voice-env-file</string><string>${xml(envFile)}</string></array>
+  <key>EnvironmentVariables</key><dict>${pairs}</dict>
+  <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xml(`${homedir()}/Library/Logs/${label}.log`)}</string>
+  <key>StandardErrorPath</key><string>${xml(`${homedir()}/Library/Logs/${label}.err.log`)}</string>
+</dict></plist>\n`);
+} else {
+  process.stdout.write(`[Unit]
+Description=PerkOS Voice gateway for ${agentName} (${environment})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${userInfo().username}
+EnvironmentFile=${envFile}
+Environment=VOICE_AGENT_ID=${agentId}
+Environment=VOICE_CANONICAL_AGENT_NAME=${agentName}
+Environment=VOICE_SECRET_FILE=${secretFile}
+Environment=PERKOS_VOICE_RUNTIME=hermes
+ExecStart=${process.execPath} ${cli}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`);
+}

package/scripts/run-with-env.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const index = process.argv.indexOf("--voice-env-file");
+if (index < 0 || !process.argv[index + 1]) throw new Error("--voice-env-file is required");
+const allowed = /^(VOICE_|PERKOS_VOICE_|OPENAI_|OPENCLAW_)[A-Z0-9_]+$/;
+const loaded = {};
+for (const raw of readFileSync(process.argv[index + 1], "utf8").split(/\r?\n/)) {
+  const line = raw.trim();
+  if (!line || line.startsWith("#")) continue;
+  const separator = line.indexOf("=");
+  if (separator < 1) throw new Error("invalid environment line");
+  const key = line.slice(0, separator).trim();
+  if (!allowed.test(key) || key.includes("SECRET") || key.includes("CREDENTIAL") || key.includes("API_KEY")) throw new Error(`unsafe environment key: ${key}`);
+  loaded[key] = line.slice(separator + 1).trim();
+}
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const child = spawn(process.execPath, [resolve(root, "dist", "cli.js")], { env: { ...process.env, ...loaded }, stdio: "inherit" });
+for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => child.kill(signal));
+child.once("exit", (code, signal) => process.exitCode = signal ? 1 : code ?? 1);

package/scripts/zeroclaw/install.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function value(flag) { const index = process.argv.indexOf(flag); return index < 0 ? undefined : process.argv[index + 1]; }
+function fail(message) { process.stderr.write(`perkos-voice-install-zeroclaw: ${message}\n`); process.exit(2); }
+function xml(input) { return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;"); }
+function loopbackWebhook(input) {
+  let url;
+  try { url = new URL(input); } catch { fail("--zeroclaw-url must be a valid URL"); }
+  if (!new Set(["127.0.0.1", "localhost", "::1"]).has(url.hostname)) fail("--zeroclaw-url must stay on loopback");
+  if (url.pathname !== "/webhook" || url.search || url.hash || url.username || url.password) fail("--zeroclaw-url must be the clean /webhook endpoint");
+  return url.toString();
+}
+
+if (process.argv.includes("--help")) {
+  process.stdout.write("Usage: perkos-voice-install-zeroclaw --emit --agent-id ID --agent-name NAME --environment dev|qa|production --voice-env-file PATH --secret-file PATH [--zeroclaw-url http://127.0.0.1:42617/webhook]\n");
+  process.exit(0);
+}
+if (!process.argv.includes("--emit")) fail("only the reviewable --emit mode is supported in v1");
+const agentId = value("--agent-id");
+const agentName = value("--agent-name");
+const environment = value("--environment");
+const envFile = value("--voice-env-file");
+const secretFile = value("--secret-file");
+if (!agentId || !agentName || !envFile || !secretFile) fail("agent, environment, env-file and secret-file are required");
+if (!["dev", "qa", "production"].includes(environment)) fail("environment must be dev, qa or production");
+const endpoint = loopbackWebhook(value("--zeroclaw-url") || "http://127.0.0.1:42617/webhook");
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const cli = resolve(root, "dist", "cli.js");
+const envLauncher = resolve(root, "scripts", "run-with-env.mjs");
+const slug = agentName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+const label = `xyz.perkos.voice.${slug}.${environment}`;
+const common = {
+  VOICE_AGENT_ID: agentId,
+  VOICE_CANONICAL_AGENT_NAME: agentName,
+  VOICE_SECRET_FILE: secretFile,
+  PERKOS_VOICE_RUNTIME: "zeroclaw",
+  PERKOS_VOICE_RUNTIME_PROTOCOL: "zeroclaw_webhook",
+  PERKOS_VOICE_RUNTIME_ENDPOINT: endpoint,
+};
+
+if (platform() === "darwin") {
+  const pairs = Object.entries(common).map(([key, entry]) => `    <key>${key}</key>\n    <string>${xml(entry)}</string>`).join("\n");
+  process.stdout.write(`<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key><array><string>${xml(process.execPath)}</string><string>${xml(envLauncher)}</string><string>--voice-env-file</string><string>${xml(envFile)}</string></array>
+  <key>EnvironmentVariables</key><dict>${pairs}</dict>
+  <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xml(`${homedir()}/Library/Logs/${label}.log`)}</string>
+  <key>StandardErrorPath</key><string>${xml(`${homedir()}/Library/Logs/${label}.err.log`)}</string>
+</dict></plist>\n`);
+} else {
+  const environmentLines = Object.entries(common).map(([key, entry]) => `Environment=${key}=${entry}`).join("\n");
+  process.stdout.write(`[Unit]
+Description=PerkOS Voice gateway for ZeroClaw ${agentName} (${environment})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${userInfo().username}
+EnvironmentFile=${envFile}
+${environmentLines}
+ExecStart=${process.execPath} ${cli}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`);
+}