@saifymatteo/pi-extensions 0.0.0-stage → 0.1.1

package/packages/pi-tts/README.md

@@ -0,0 +1,37 @@
+# @saifymatteo/pi-tts
+
+## Purpose and registrations
+
+Registers `text_to_speech` when the registry has a `type: "tts"` model; no slash commands or playback. Sends narration to a service and saves a new WAV, never overwriting an existing output. Uses standard fetch/streams and Pi tool registration; requires filesystem hard-link support for atomic publication.
+
+## Configuration and service
+
+Reads the shared `<agent-dir>/extensions/service-models.json` registry and uses every model with `type: "tts"` and `api: "openai-audio-speech"`. A missing registry or no TTS model leaves the tool absent; no automatic config creation. A model may set default `voice` and `language` (requests can override them) and an optional one-line `description`, shown to the agent as a strength hint in the `model` parameter. Opt in by manually creating the registry from `examples/service-models.example.json`.
+
+Requires an OpenAI-compatible speech server (POST `audio/speech` relative to the versioned base URL), not an installed CLI. Keys accept `$ENV` / `${ENV}`; omission falls back to agent `auth.json`, explicit `""` permits keyless TTS. Use environment references rather than embedded credentials.
+
+## Security and limits
+
+All narration is transmitted to the selected service. Do not send secrets. 120s timeout, no retries/fallback, redirects rejected, 20000 characters/100 MiB maximum. Requires a new `.wav` path with an existing parent; writes private staging files beside output and hard-links atomically. Parent symlinks are not prohibited by the inherited implementation; only request trusted output paths. Output is local and never played automatically.
+
+## Tests
+
+From the monorepo root with its existing test dependencies available:
+
+```sh
+node --test packages/pi-tts/test/*.test.mjs
+```
+
+Tests use the shared test-only TypeScript/VM loader, fixtures, and host/service stubs. They do not prove compatibility with a live host, CLI, or model service.
+
+## Running locally
+
+From the monorepo root:
+
+```sh
+pi -e ./packages/pi-tts
+```
+
+Node >=24; host imports are peers, not bundled dependencies. Load only one copy: for an isolated session use `--no-extensions` with explicit `-e` paths so the original live extension is not also discovered. Set `PI_CODING_AGENT_DIR` to a disposable agent directory before launch; unset means the normal `~/.pi/agent` fallback. Extension config continues to resolve there, never relative to this package.
+
+Examples are manually authored, sanitized reference documents, not runtime defaults. Review and manually create only the needed files in the isolated agent directory; do not copy live credentials or endpoints. No example is automatically loaded or copied. Loading an extension grants Pi-process OS permissions. Licensed AGPL-3.0-only; see [NOTICE.md](NOTICE.md).

package/packages/pi-tts/examples/service-models.example.json

@@ -0,0 +1,27 @@
+{
+  "providers": {
+    "example-services": {
+      "baseUrl": "http://localhost:8000/v1",
+      "apiKey": "$PI_SERVICE_API_KEY",
+      "models": [
+        {
+          "id": "example-classifier",
+          "type": "classifier",
+          "api": "openai-decisions",
+          "contextWindow": 8192,
+          "input": [
+            "text",
+            "image"
+          ],
+          "description": "Example strength hint shown to the agent."
+        },
+        {
+          "id": "example-tts",
+          "type": "tts",
+          "api": "openai-audio-speech",
+          "description": "Example strength hint shown to the agent."
+        }
+      ]
+    }
+  }
+}

package/packages/pi-tts/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@saifymatteo/pi-tts",
+  "version": "0.1.1",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "description": "Generate WAV files through an OpenAI-compatible speech endpoint.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
+    "directory": "packages/pi-tts"
+  }
+}

package/packages/pi-tts/src/index.ts

@@ -0,0 +1,135 @@
+/** Generate WAV files through an OpenAI-compatible speech endpoint; never play audio. */
+import { loadServiceConfig, serviceApiKey, modelOptions } from './lib/service-models'
+import { link, lstat, mkdtemp, open, rm, stat } from 'node:fs/promises'
+import { dirname, extname, join, resolve } from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+
+const MAX_AUDIO_BYTES = 100 * 1024 * 1024
+const MAX_TEXT_LENGTH = 20_000
+
+async function readAudio(response: Response, signal: AbortSignal): Promise<Buffer> {
+  if (Number(response.headers.get('content-length')) > MAX_AUDIO_BYTES) {
+    await response.body?.cancel().catch(() => {})
+    throw new Error('TTS audio exceeds 100 MiB')
+  }
+  if (!response.body) throw new Error('TTS API returned no audio')
+  const reader = response.body.getReader()
+  // Also interrupt non-fetch/custom streams that do not observe the request signal.
+  const abort = () => { void reader.cancel(signal.reason).catch(() => {}) }
+  signal.addEventListener('abort', abort, { once: true })
+  const chunks: Uint8Array[] = []
+  let size = 0
+  try {
+    while (true) {
+      signal.throwIfAborted()
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > MAX_AUDIO_BYTES) throw new Error('TTS audio exceeds 100 MiB')
+      chunks.push(value)
+    }
+  } finally {
+    signal.removeEventListener('abort', abort)
+    await reader.cancel().catch(() => {})
+    reader.releaseLock()
+  }
+  signal.throwIfAborted()
+  const audio = Buffer.concat(chunks, size)
+  if (audio.length < 44 || audio.toString('ascii', 0, 4) !== 'RIFF' || audio.toString('ascii', 8, 12) !== 'WAVE' || audio.readUInt32LE(4) !== audio.length - 8) {
+    throw new Error('TTS API did not return a WAV file')
+  }
+  return audio
+}
+
+export default function ttsExtension(pi: ExtensionAPI) {
+  const piDir = process.env.PI_CODING_AGENT_DIR || join(process.env.HOME || process.env.USERPROFILE || '', '.pi', 'agent')
+  const config = loadServiceConfig(piDir, 'tts')
+  if (!config) return
+  const models = Object.entries(config.providers).flatMap(([provider, cfg]) =>
+    cfg.models.map(model => ({ spec: `${provider}/${model.id}`, provider, config: cfg, model })))
+
+  pi.registerTool({
+    name: 'text_to_speech',
+    label: 'Text to speech',
+    description: 'Generate a local WAV audio file from narration using a configured OpenAI-compatible TTS server. Sends the supplied text to that server. Never plays audio or overwrites files. 120-second timeout; no retries or fallback. Maximum 20,000 characters and 100 MiB output.',
+    promptSnippet: 'Generate spoken narration as a WAV file with a configured TTS model',
+    promptGuidelines: [
+      'Use text_to_speech when the user requests spoken narration or an audio file; do not generate or play audio automatically.',
+      'Write listener-friendly narration rather than reading Markdown syntax or code verbatim, unless the user requests exact text. Return the saved file path.',
+      'Use only models configured in service-models.json (type tts). Do not send secrets or silently switch providers after a failure.',
+    ],
+    parameters: Type.Object({
+      text: Type.String({ minLength: 1, maxLength: MAX_TEXT_LENGTH, description: 'Narration to synthesize.' }),
+      output_file: Type.String({ minLength: 1, description: 'New .wav file, relative to cwd or absolute. Parent directory must exist. Existing files are never overwritten.' }),
+      model: Type.Optional(Type.String({ description: `Configured provider/model-id; required when several are configured. Pick by strength:${modelOptions(config)}` })),
+      voice: Type.Optional(Type.String({ minLength: 1, description: 'Voice supported by the selected model; otherwise uses the configured/server default.' })),
+      language: Type.Optional(Type.String({ minLength: 1, description: 'Language supported by the selected model; otherwise uses the configured/server default.' })),
+    }, { additionalProperties: false }),
+    outputSchema: Type.Object({ provider: Type.String(), model: Type.String(), output_file: Type.String(), bytes: Type.Number(), format: Type.Literal('wav') }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted()
+      if (typeof params.text !== 'string' || !params.text.trim() || params.text.length > MAX_TEXT_LENGTH) throw new Error('Narration must contain 1..20000 characters')
+      if (typeof params.output_file !== 'string' || !params.output_file.trim() || params.output_file.includes('\0') || extname(params.output_file).toLowerCase() !== '.wav') throw new Error('output_file must be a new .wav file')
+      for (const value of [params.voice, params.language]) {
+        if (value !== undefined && (typeof value !== 'string' || !value.trim())) throw new Error('voice and language must be non-empty strings')
+      }
+      const spec = params.model ?? (models.length === 1 ? models[0].spec : undefined)
+      const selected = models.find(m => m.spec === spec)
+      if (!selected) throw new Error(`Specify a model configured in service-models.json (type tts). Options:${modelOptions(config)}`)
+      const output = resolve(ctx.cwd, params.output_file.startsWith('~/') ? join(process.env.HOME || process.env.USERPROFILE || '', params.output_file.slice(2)) : params.output_file)
+      try {
+        await lstat(output)
+        throw new Error('output_file already exists; choose a new path')
+      } catch (error: any) {
+        if (error.code !== 'ENOENT') throw error
+      }
+      // Fail before a potentially expensive synthesis request if the parent is absent.
+      const parent = await stat(dirname(output))
+      if (!parent.isDirectory()) throw new Error('output_file parent must be a directory')
+      const key = serviceApiKey(piDir, selected.provider, selected.config.apiKey)
+      const requestSignal = AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(120_000)])
+      try {
+        const response = await fetch(new URL('audio/speech', `${selected.config.baseUrl.replace(/\/+$/, '')}/`), {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', ...(key ? { Authorization: `Bearer ${key}` } : {}) },
+          body: JSON.stringify({
+            model: selected.model.id,
+            input: params.text,
+            response_format: 'wav',
+            voice: params.voice ?? selected.model.voice,
+            language: params.language ?? selected.model.language,
+          }),
+          signal: requestSignal,
+          redirect: 'error',
+        })
+        // Do not echo server response bodies: they may contain credentials or narration.
+        if (!response.ok) {
+          await response.body?.cancel().catch(() => {})
+          throw new Error(`TTS API returned HTTP ${response.status}`)
+        }
+        const audio = await readAudio(response, requestSignal)
+        requestSignal.throwIfAborted()
+        // Stage privately on the same filesystem, then publish atomically without replacing anything.
+        // Cleanup never touches output: it may have been replaced by another process.
+        const staging = await mkdtemp(join(dirname(output), '.pi-tts-'))
+        try {
+          const staged = join(staging, 'audio.wav')
+          const file = await open(staged, 'wx', 0o600)
+          try { await file.writeFile(audio, { signal: requestSignal }) } finally { await file.close() }
+          requestSignal.throwIfAborted()
+          await link(staged, output)
+        } finally {
+          await rm(staging, { recursive: true, force: true }).catch(() => {})
+        }
+        const result = { provider: selected.provider, model: selected.model.id, output_file: output, bytes: audio.length, format: 'wav' as const }
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], details: result, structuredContent: result }
+      } catch (error: any) {
+        if (signal?.aborted) throw new Error('TTS generation aborted')
+        if (requestSignal.aborted && requestSignal.reason?.name === 'TimeoutError') throw new Error('TTS request timed out after 120000ms')
+        const message = error.message || String(error)
+        throw new Error((key ? message.replaceAll(key, '<redacted>') : message).slice(0, 1100))
+      }
+    },
+  })
+}

package/packages/pi-tts/src/lib/service-models.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface ServiceModel {
+  id: string
+  type: 'classifier' | 'tts'
+  api: 'openai-decisions' | 'openai-audio-speech'
+  name?: string
+  /** One-line strength hint shown in the tool's model options. */
+  description?: string
+  contextWindow?: number
+  input?: ('text' | 'image')[]
+  cost?: { input: number; output: number; cacheRead?: number; cacheWrite?: number }
+  voice?: string
+  language?: string
+}
+export interface ServiceProvider {
+  baseUrl: string
+  apiKey?: string
+  models: ServiceModel[]
+}
+const object = (value: any): value is Record<string, any> => !!value && typeof value === 'object' && !Array.isArray(value)
+const text = (value: any): value is string => typeof value === 'string' && !!value.trim()
+
+/** Each extension uses every registry model of its `type`; a missing registry or no matching models disables the tool. */
+export function loadServiceConfig(piDir: string, type: ServiceModel['type']): { providers: Record<string, ServiceProvider> } | undefined {
+  const path = join(piDir, 'extensions', 'service-models.json')
+  if (!existsSync(path)) return undefined
+  try {
+    let registry: any
+    try { registry = JSON.parse(readFileSync(path, 'utf8')) }
+    catch { throw new Error('Malformed JSON') }
+    if (!object(registry) || !object(registry.providers)) throw new Error('requires a providers object')
+    const providers: Record<string, ServiceProvider> = Object.create(null)
+    for (const [id, provider] of Object.entries(registry.providers)) {
+      if (!text(id) || id.includes('/') || !object(provider) || !text(provider.baseUrl) ||
+          (provider.apiKey !== undefined && typeof provider.apiKey !== 'string') || !Array.isArray(provider.models)) {
+        throw new Error(`Invalid provider: ${id}`)
+      }
+      let url: URL
+      try { url = new URL(provider.baseUrl) } catch { throw new Error(`Invalid baseUrl for provider: ${id}`) }
+      if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error(`Invalid baseUrl for provider: ${id}`)
+      const ids = new Set<string>()
+      for (const model of provider.models) {
+        if (!object(model) || !text(model.id) || ids.has(model.id) ||
+            !['tts', 'classifier'].includes(model.type) || model.api !== (model.type === 'tts' ? 'openai-audio-speech' : 'openai-decisions') ||
+            (model.name !== undefined && !text(model.name)) ||
+            (model.description !== undefined && !text(model.description)) ||
+            ['voice', 'language'].some(key => model[key] !== undefined && (model.type !== 'tts' || !text(model[key]))) ||
+            (model.type === 'classifier' && (model.contextWindow === undefined || model.input === undefined)) ||
+            (model.contextWindow !== undefined && (!Number.isInteger(model.contextWindow) || model.contextWindow <= 0)) ||
+            (model.input !== undefined && (!Array.isArray(model.input) || !model.input.length ||
+              new Set(model.input).size !== model.input.length || model.input.some((input: any) => !['text', 'image'].includes(input)))) ||
+            (model.cost !== undefined && (!object(model.cost) || !['input', 'output'].every(key => typeof model.cost[key] === 'number') ||
+              Object.entries(model.cost).some(([key, value]) => !['input', 'output', 'cacheRead', 'cacheWrite'].includes(key) || typeof value !== 'number' || !Number.isFinite(value) || value < 0)))) {
+          throw new Error(`Invalid or duplicate model in provider: ${id}`)
+        }
+        ids.add(model.id)
+        if (model.type !== type) continue
+        providers[id] ??= { baseUrl: provider.baseUrl, ...(provider.apiKey !== undefined ? { apiKey: provider.apiKey } : {}), models: [] }
+        providers[id].models.push({ ...model } as ServiceModel)
+      }
+    }
+    return Object.keys(providers).length ? { providers } : undefined
+  } catch (error: any) {
+    // Never echo JSON parser messages, URLs or credential values from configuration.
+    throw new Error(`Failed to load service-models.json: ${error.message}`)
+  }
+}
+
+/** Lists each `provider/model-id` with its description, for a tool's model parameter. */
+export function modelOptions(config: { providers: Record<string, ServiceProvider> }): string {
+  return Object.entries(config.providers).flatMap(([provider, cfg]) =>
+    cfg.models.map(model => `\n- ${provider}/${model.id}${model.description ? `: ${model.description}` : ''}`)).join('')
+}
+
+export function configuredApiKey(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const envName = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value)?.[1]
+    ?? /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(value)?.[1]
+  return envName ? process.env[envName] : value
+}
+
+export function serviceApiKey(piDir: string, id: string, configured: string | undefined): string {
+  if (configured !== undefined) {
+    const key = configuredApiKey(configured)
+    if (key === undefined || (configured !== '' && !key)) throw new Error('No API key: Missing API key environment variable for configured service provider')
+    return key
+  }
+  let auth: any
+  try { auth = JSON.parse(readFileSync(join(piDir, 'auth.json'), 'utf8')) } catch {}
+  const key = auth?.[id]?.key ?? auth?.[id]?.access
+  if (typeof key !== 'string' || !key) throw new Error(`No API key configured for provider "${id}"; use auth.json or service-models.json apiKey ("" for keyless access)`)
+  return key
+}

package/packages/pi-tts/test/tts-output.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+test('TTS saves mock WAV atomically and does not replace existing output', async t => {
+  const dir = mkdtempSync(join(tmpdir(), 'pi-tts-output-test-'));
+  mkdirSync(join(dir, 'extensions'));
+  const old = process.env.PI_CODING_AGENT_DIR;
+  process.env.PI_CODING_AGENT_DIR = dir;
+  t.after(() => {
+    if (old === undefined) delete process.env.PI_CODING_AGENT_DIR; else process.env.PI_CODING_AGENT_DIR = old;
+    rmSync(dir, { recursive: true, force: true });
+  });
+  writeFileSync(join(dir, 'extensions', 'service-models.json'), JSON.stringify({ providers: { local: {
+    baseUrl: 'http://localhost:8000/v1', apiKey: '', models: [{ id: 'voice', type: 'tts', api: 'openai-audio-speech' }],
+  } } }));
+  const wav = Buffer.alloc(44);
+  wav.write('RIFF'); wav.writeUInt32LE(36, 4); wav.write('WAVE', 8);
+  let requests = 0;
+  const fetchStub = async (url, options) => {
+    requests++;
+    assert.equal(String(url), 'http://localhost:8000/v1/audio/speech');
+    assert.equal(options.redirect, 'error');
+    assert.equal(options.headers.Authorization, undefined);
+    assert.equal(JSON.parse(options.body).input, 'fixture narration');
+    let sent = false;
+    return { ok: true, headers: { get: () => '44' }, body: { getReader: () => ({
+      read: async () => { if (sent) return { done: true }; sent = true; return { done: false, value: wav }; },
+      cancel: async () => {}, releaseLock() {},
+    }) } };
+  };
+  const Type = new Proxy({}, { get: () => () => ({}) });
+  const { default: extension } = loadExtension(fileURLToPath(new URL('../src/index.ts', import.meta.url)), { typebox: { Type } }, { fetch: fetchStub });
+  let tool;
+  extension({ registerTool: value => { tool = value; } });
+  const params = { text: 'fixture narration', output_file: 'result.wav' };
+  const run = () => tool.execute('fixture', params, undefined, undefined, { cwd: dir });
+  const result = await run();
+  assert.equal(result.structuredContent.bytes, 44);
+  assert.equal(readFileSync(join(dir, 'result.wav')).equals(wav), true);
+  await assert.rejects(run(), /already exists/);
+  assert.equal(requests, 1);
+});

package/packages/pi-tts/test/tts.test.mjs

@@ -0,0 +1,57 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+const schema = new Proxy({}, { get: () => (..._args) => ({}) });
+function setup(t) {
+  const dir = mkdtempSync(join(tmpdir(), 'pi-tts-test-'));
+  mkdirSync(join(dir, 'extensions'));
+  const old = process.env.PI_CODING_AGENT_DIR;
+  process.env.PI_CODING_AGENT_DIR = dir;
+  t.after(() => {
+    if (old === undefined) delete process.env.PI_CODING_AGENT_DIR; else process.env.PI_CODING_AGENT_DIR = old;
+    rmSync(dir, { recursive: true, force: true });
+  });
+  const save = (name, data) => writeFileSync(join(dir, 'extensions', name), JSON.stringify(data));
+  save('service-models.json', { providers: { local: { baseUrl: 'http://localhost:8000/v1', apiKey: '', models: [
+    { id: 'voice', type: 'tts', api: 'openai-audio-speech' },
+  ] } } });
+  return { dir, save };
+}
+
+const registry = (model = {}) => ({ providers: { local: { baseUrl: 'http://localhost:8000/v1', apiKey: '', models: [
+  { id: 'voice', type: 'tts', api: 'openai-audio-speech', ...model },
+] } } });
+
+test('TTS registry model carries voice/language defaults; empty values are rejected', t => {
+  const { dir, save } = setup(t);
+  const { loadServiceConfig } = loadExtension(fileURLToPath(new URL('../src/lib/service-models.ts', import.meta.url)));
+  save('service-models.json', registry({ voice: 'example', language: 'en' }));
+  const model = loadServiceConfig(dir, 'tts').providers.local.models[0];
+  assert.equal(model.voice, 'example');
+  assert.equal(model.language, 'en');
+  save('service-models.json', registry({ voice: '' }));
+  assert.throws(() => loadServiceConfig(dir, 'tts'), /Invalid or duplicate model/);
+});
+
+test('TTS tool stays absent without a tts registry model; validation rejects invalid and existing outputs before request', async t => {
+  const { dir, save } = setup(t);
+  const tools = [];
+  const { default: extension } = loadExtension(fileURLToPath(new URL('../src/index.ts', import.meta.url)), { typebox: { Type: schema } });
+  save('service-models.json', { providers: {} });
+  extension({ registerTool: tool => tools.push(tool) });
+  assert.equal(tools.length, 0);
+  save('service-models.json', registry());
+  extension({ registerTool: tool => tools.push(tool) });
+  assert.equal(tools[0].name, 'text_to_speech');
+  const run = params => tools[0].execute('test', params, undefined, undefined, { cwd: dir });
+  await assert.rejects(run({ text: '', output_file: 'out.wav' }), /Narration/);
+  await assert.rejects(run({ text: 'hello', output_file: 'out.mp3' }), /new .wav/);
+  await assert.rejects(run({ text: 'hello', output_file: 'out.wav', model: 'other/voice' }), /Specify a model/);
+  writeFileSync(join(dir, 'exists.wav'), 'unchanged');
+  await assert.rejects(run({ text: 'hello', output_file: 'exists.wav' }), /already exists/);
+});