@lucas_zaia/agent-voice 1.0.0 → 1.1.0

package/README.md

@@ -75,7 +75,7 @@ agent-voice output add <alexa|local|command> [name]
 agent-voice output list | remove | enable | disable | test [name]
 agent-voice wrap [--name <label>] -- <command...>
 agent-voice status
-agent-voice config get [key] | set <key> <value>
+agent-voice config get [key] | set <key> <value> | reset <key>
 agent-voice test
 ```
 
@@ -122,6 +122,30 @@ agent-voice config set cooldownSeconds 300
 | `cooldownSeconds` | 120 | `AV_COOLDOWN_SECONDS` |
 | `maxSpeechChars` | 90 | `AV_MAX_SPEECH_CHARS` |
 
+## Changing what it says
+
+Each sentence is a template you can reword. `{name}` is a variable; a
+`[section]` is spoken only when every variable inside it has a value, so an
+empty request drops its whole clause.
+
+| Key | Variables | Default |
+|---|---|---|
+| `phrases.taskDone` | `{agent}` `{where}` `{duration}` `{request}` | `{agent} terminou {where}, depois de {duration}.[ Você tinha pedido: {request}.]` |
+| `phrases.backgroundDone` | `{agent}` `{where}` `{text}` | `{agent} terminou um trabalho em segundo plano {where}.[ Era: {text}.]` |
+| `phrases.needsInput` | `{agent}` `{where}` `{notice}` | `{agent} precisa de você {where}{notice}.` |
+
+```bash
+agent-voice config set phrases.taskDone "{agent} acabou {where}, levou {duration}.[ Pedido: {request}.]"
+agent-voice config get phrases.taskDone
+agent-voice config reset phrases.taskDone     # back to the default
+```
+
+`{where}` is "na sessão <name>" (or a colour plus the project when there is no
+name), `{duration}` is "cerca de 4 minutos", and `{notice}` is the agent's
+notice translated — ", para usar o Bash" — or empty. A template with an
+unknown variable or unbalanced brackets is refused, so the speaker never reads
+out broken text.
+
 ## Where things live
 
 | | Config | State and `events.log` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucas_zaia/agent-voice",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Make your coding agent talk to you: a smart speaker says when a long task finishes or when the agent needs you.",
   "type": "module",
   "bin": { "agent-voice": "bin/agent-voice.js" },

package/src/cli/config.js

@@ -1,24 +1,56 @@
-import { loadConfig, saveConfig, NUMERIC_KEYS } from '../config.js';
+import { loadConfig, readStoredConfig, saveConfig, writeStoredConfig, NUMERIC_KEYS, DEFAULTS } from '../config.js';
+import { DEFAULT_PHRASES, validateTemplate } from '../core/phrases.js';
 
-const USAGE = `usage: agent-voice config get [key] | set <key> <value>   (keys: ${Object.keys(NUMERIC_KEYS).join(', ')})`;
+const PHRASE_KEYS = Object.keys(DEFAULT_PHRASES).map((n) => `phrases.${n}`);
+const KEYS = [...Object.keys(NUMERIC_KEYS), ...PHRASE_KEYS];
+const USAGE = `usage: agent-voice config get [key] | set <key> <value> | reset <key>   (keys: ${KEYS.join(', ')})`;
+
+const phraseName = (key) => (typeof key === 'string' && key.startsWith('phrases.') ? key.slice('phrases.'.length) : null);
+
+function checkKey(key) {
+  const name = phraseName(key);
+  if (name !== null) {
+    if (!Object.hasOwn(DEFAULT_PHRASES, name)) throw new Error(validateTemplate(name, ''));
+    return;
+  }
+  if (!Object.hasOwn(NUMERIC_KEYS, key ?? '')) {
+    throw new Error(`unknown key "${key}" (settable: ${KEYS.join(', ')}; outputs are managed with "agent-voice output enable|disable")`);
+  }
+}
+
+const storedPhrases = (env) => {
+  const p = readStoredConfig(env).phrases;
+  return p && typeof p === 'object' && !Array.isArray(p) ? p : {};
+};
 
 export function runConfig(args, { env, out }) {
   const [sub, key, value] = args;
   if (sub === 'get') {
     const cfg = loadConfig(env);
+    const phrase = (name) => cfg.phrases[name] ?? DEFAULT_PHRASES[name];
     if (!key) {
       for (const k of Object.keys(NUMERIC_KEYS)) out(`${k}=${cfg[k]}`);
       out(`outputs=${cfg.outputs.join(' ')}`);
+      for (const name of Object.keys(DEFAULT_PHRASES)) out(`phrases.${name}=${phrase(name)}`);
       return 0;
     }
-    if (key === 'outputs') out(cfg.outputs.join(' '));
-    else if (Object.hasOwn(NUMERIC_KEYS, key)) out(String(cfg[key]));
-    else throw new Error(`unknown key "${key}". ${USAGE}`);
+    if (key === 'outputs') {
+      out(cfg.outputs.join(' '));
+      return 0;
+    }
+    checkKey(key);
+    out(String(phraseName(key) !== null ? phrase(phraseName(key)) : cfg[key]));
     return 0;
   }
   if (sub === 'set') {
-    if (!Object.hasOwn(NUMERIC_KEYS, key ?? '')) {
-      throw new Error(`unknown key "${key}" (settable: ${Object.keys(NUMERIC_KEYS).join(', ')}; outputs are managed with "agent-voice output enable|disable")`);
+    checkKey(key);
+    const name = phraseName(key);
+    if (name !== null) {
+      const problem = validateTemplate(name, value);
+      if (problem) throw new Error(problem);
+      saveConfig({ phrases: { ...storedPhrases(env), [name]: value } }, env);
+      out(`${key}=${value}`);
+      return 0;
     }
     if (!/^[0-9]+$/.test(value ?? '')) {
       throw new Error(`${key} must be a whole number of ${key === 'maxSpeechChars' ? 'characters' : 'seconds'}`);
@@ -29,5 +61,19 @@ export function runConfig(args, { env, out }) {
     if (env[envName] !== undefined) out(`Note: ${envName}=${env[envName]} overrides it in this environment.`);
     return 0;
   }
+  if (sub === 'reset') {
+    checkKey(key);
+    const name = phraseName(key);
+    if (name !== null) {
+      const { [name]: _dropped, ...rest } = storedPhrases(env);
+      saveConfig({ phrases: rest }, env);
+      out(`${key}=${DEFAULT_PHRASES[name]}`);
+    } else {
+      const { [key]: _dropped, ...rest } = readStoredConfig(env);
+      writeStoredConfig(rest, env);
+      out(`${key}=${DEFAULTS[key]}`);
+    }
+    return 0;
+  }
   throw new Error(USAGE);
 }

package/src/cli/main.js

@@ -17,8 +17,9 @@ const HELP = `Usage: agent-voice <command>
   wrap [--name <label>] -- <command> [args...]
                                     announce when any command finishes
   status                            agents, outputs, settings and the latest log lines
-  config get [key] | set <key> <value>
-                                    keys: minSeconds, cooldownSeconds, maxSpeechChars
+  config get [key] | set <key> <value> | reset <key>
+                                    keys: minSeconds, cooldownSeconds, maxSpeechChars,
+                                    phrases.taskDone, phrases.backgroundDone, phrases.needsInput
   test                              speak a test sentence on every active output
   notify <agent> <subcommand>       hook entry point (called by your agent, not by you)`;
 

package/src/config.js

@@ -3,8 +3,9 @@
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, chmodSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { configDir, stateDir } from './platform.js';
+import { validateTemplate } from './core/phrases.js';
 
-export const DEFAULTS = Object.freeze({ minSeconds: 30, cooldownSeconds: 120, maxSpeechChars: 90, outputs: [] });
+export const DEFAULTS = Object.freeze({ minSeconds: 30, cooldownSeconds: 120, maxSpeechChars: 90, outputs: [], phrases: {} });
 
 export const NUMERIC_KEYS = Object.freeze({
   minSeconds: 'AV_MIN_SECONDS',
@@ -58,13 +59,20 @@ export function loadConfig(env = process.env) {
   }
   if (env.AV_OUTPUTS !== undefined) cfg.outputs = env.AV_OUTPUTS.split(/\s+/).filter(Boolean);
   cfg.outputs = Array.isArray(cfg.outputs) ? cfg.outputs.filter((n) => typeof n === 'string') : [];
+  // A hand-edited template that would speak broken text is dropped; the default speaks instead.
+  const phrases = cfg.phrases && typeof cfg.phrases === 'object' && !Array.isArray(cfg.phrases) ? cfg.phrases : {};
+  cfg.phrases = Object.fromEntries(Object.entries(phrases).filter(([name, tpl]) => validateTemplate(name, tpl) === null));
   return { ...cfg, configDir: configDir(env), stateDir: stateDir(env) };
 }
 
 export function saveConfig(patch, env = process.env) {
-  const next = { ...readStoredConfig(env), ...patch };
-  writeJson(configFile(env), next);
-  return next;
+  return writeStoredConfig({ ...readStoredConfig(env), ...patch }, env);
+}
+
+// Replaces config.json wholesale — the way to remove a key.
+export function writeStoredConfig(value, env = process.env) {
+  writeJson(configFile(env), value);
+  return value;
 }
 
 export function readOutputInstance(name, env = process.env) {

package/src/core/handle.js

@@ -64,7 +64,7 @@ export async function handle(event, ctx) {
         ctx.log(agent, session, `silent (turn ${elapsed}s < ${ctx.config.minSeconds}s)`);
         return;
       }
-      sentence = phraseTaskDone(who, place, durationPhrase(elapsed), clean(asked));
+      sentence = phraseTaskDone(who, place, durationPhrase(elapsed), clean(asked), ctx.config.phrases);
       break;
     }
 
@@ -78,11 +78,11 @@ export async function handle(event, ctx) {
         ctx.log(agent, session, 'silent (background_done with no content)');
         return;
       }
-      sentence = phraseBackgroundDone(who, place, clean(text));
+      sentence = phraseBackgroundDone(who, place, clean(text), ctx.config.phrases);
       break;
 
     case 'needs_input':
-      sentence = phraseNeedsInput(who, place, clean(text));
+      sentence = phraseNeedsInput(who, place, clean(text), ctx.config.phrases);
       break;
 
     default:

package/src/core/phrases.js

@@ -1,5 +1,6 @@
 // Everything spoken lives here, and it is the only file in Portuguese. Adding a
-// language, or changing what the speaker says, touches this file and nothing else.
+// language touches this file and nothing else; users reword the sentences
+// through config.json "phrases" (see DEFAULT_PHRASES).
 import { cksum } from './hash.js';
 import { stripTrailingPunct } from './speech.js';
 
@@ -26,14 +27,57 @@ export function durationPhrase(seconds) {
   return minutes <= 1 ? 'cerca de um minuto' : `cerca de ${minutes} minutos`;
 }
 
-export function phraseTaskDone(agent, place, duration, text) {
-  const s = `${agent} terminou ${place}, depois de ${duration}.`;
-  return text ? `${s} Você tinha pedido: ${stripTrailingPunct(text)}.` : s;
+// The spoken sentences, as templates the user can override (config.json
+// "phrases"). {name} is a variable; a [section] is spoken only when every
+// variable inside it has a value, so "[ Era: {text}.]" vanishes with no text.
+export const DEFAULT_PHRASES = Object.freeze({
+  taskDone: '{agent} terminou {where}, depois de {duration}.[ Você tinha pedido: {request}.]',
+  backgroundDone: '{agent} terminou um trabalho em segundo plano {where}.[ Era: {text}.]',
+  needsInput: '{agent} precisa de você {where}{notice}.',
+});
+
+export const PHRASE_VARS = Object.freeze({
+  taskDone: ['agent', 'where', 'duration', 'request'],
+  backgroundDone: ['agent', 'where', 'text'],
+  needsInput: ['agent', 'where', 'notice'],
+});
+
+const MAX_TEMPLATE_CHARS = 300;
+const VAR_RE = /\{([^{}]*)\}/g;
+
+// null when the template is usable, otherwise the reason it is not.
+export function validateTemplate(name, template) {
+  if (!Object.hasOwn(PHRASE_VARS, name)) return `unknown phrase "${name}" (phrases: ${Object.keys(PHRASE_VARS).join(', ')})`;
+  if (typeof template !== 'string' || !template.trim()) return `phrases.${name} is empty`;
+  if (template.length > MAX_TEMPLATE_CHARS) return `phrases.${name} is too long (max ${MAX_TEMPLATE_CHARS} characters)`;
+  let depth = 0;
+  for (const ch of template) {
+    if (ch === '[') depth += 1;
+    if (ch === ']') depth -= 1;
+    if (depth < 0 || depth > 1) return `phrases.${name}: brackets must be balanced and not nested`;
+  }
+  if (depth !== 0) return `phrases.${name}: brackets must be balanced and not nested`;
+  for (const [, v] of template.matchAll(VAR_RE)) {
+    if (!PHRASE_VARS[name].includes(v)) return `phrases.${name}: unknown variable {${v}} (use: ${PHRASE_VARS[name].join(', ')})`;
+  }
+  return null;
+}
+
+function render(name, templates, vars) {
+  const custom = templates?.[name];
+  const template = custom !== undefined && validateTemplate(name, custom) === null ? custom : DEFAULT_PHRASES[name];
+  const fill = (part) => part.replace(VAR_RE, (_, v) => vars[v] ?? '');
+  return template
+    .replace(/\[([^\]]*)\]/g, (_, inner) => ([...inner.matchAll(VAR_RE)].every(([, v]) => vars[v]) ? fill(inner) : ''))
+    .replace(VAR_RE, (_, v) => vars[v] ?? '');
+}
+
+export function phraseTaskDone(agent, place, duration, text, templates) {
+  return render('taskDone', templates, { agent, where: place, duration, request: text ? stripTrailingPunct(text) : '' });
 }
 
-export function phraseBackgroundDone(agent, place, text) {
-  const s = `${agent} terminou um trabalho em segundo plano ${place}.`;
-  return text ? `${s} Era: ${stripTrailingPunct(text)}.` : s;
+export function phraseBackgroundDone(agent, place, text, templates) {
+  return render('backgroundDone', templates, { agent, where: place, text: text ? stripTrailingPunct(text) : '' });
 }
 
 // Agent notices arrive in English. Speaking one verbatim after a Portuguese
@@ -48,7 +92,6 @@ export function translateNotice(text) {
   return `. ${text}`;
 }
 
-export function phraseNeedsInput(agent, place, text) {
-  const s = `${agent} precisa de você ${place}`;
-  return text ? `${s}${translateNotice(stripTrailingPunct(text))}.` : `${s}.`;
+export function phraseNeedsInput(agent, place, text, templates) {
+  return render('needsInput', templates, { agent, where: place, notice: text ? translateNotice(stripTrailingPunct(text)) : '' });
 }