create-syrinx-agent 4.4.0

package/src/templates/agent-module.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: MIT
+//
+// Emits src/agent.ts for the node runtime — the module the CLI's --agent
+// seam points at (`tsx scripts/dev-server.ts --agent ./src/agent.ts#createAgent`,
+// `syrinx turn --agent ./src/agent.ts#createAgent`). Mirrors
+// examples/02-hello-voice-headless/src/hello-voice-agent.ts (cascade) and
+// scripts/run-realtime-oneturn-smoke.ts (realtime).
+
+import type { ResolvedOptions } from "../options.js";
+import { STT_STAGE_PROVIDERS } from "../providers/stt.js";
+import { TTS_STAGE_PROVIDERS } from "../providers/tts.js";
+import { REASONER_PROVIDERS, SYSTEM_PROMPT_CONST } from "../providers/reasoner.js";
+import { REALTIME_PROVIDERS } from "../providers/realtime.js";
+import { VAD_SIDECAR_PROVIDERS, ENDPOINTING_SIDECAR_PROVIDERS } from "../providers/vad-endpointing.js";
+import { CliError, EXIT_CODES } from "../exit-codes.js";
+import type { StageProvider } from "../providers/types.js";
+
+const SYSTEM_PROMPT = "You are a helpful voice assistant. Keep your replies short.";
+
+function nodeEnvRef(key: string): string {
+  return `process.env["${key}"] ?? ""`;
+}
+
+function requireStage(provider: StageProvider | undefined, flag: string, value: string): StageProvider {
+  if (provider === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--${flag} ${value} is not yet implemented by this generator`);
+  }
+  return provider;
+}
+
+function importLine(className: string, from: string): string {
+  return `import { ${className} } from "${from}";`;
+}
+
+/** Merge `import { A } from "x"; import { B } from "x";` pairs sharing one module into one line. */
+function mergeImports(lines: readonly string[]): string[] {
+  const IMPORT_RE = /^import \{ (.+) \} from "(.+)";$/;
+  const sourceOrder: string[] = [];
+  const namesBySource = new Map<string, string[]>();
+
+  for (const line of lines) {
+    const match = IMPORT_RE.exec(line);
+    const names = match?.[1];
+    const from = match?.[2];
+    if (names === undefined || from === undefined) continue; // every entry here is an import line
+    let bucket = namesBySource.get(from);
+    if (bucket === undefined) {
+      bucket = [];
+      namesBySource.set(from, bucket);
+      sourceOrder.push(from);
+    }
+    for (const name of names.split(",").map((n) => n.trim())) {
+      if (!bucket.includes(name)) bucket.push(name);
+    }
+  }
+
+  return sourceOrder.map((from) => `import { ${(namesBySource.get(from) ?? []).join(", ")} } from "${from}";`);
+}
+
+export function buildAgentModule(opts: ResolvedOptions): string {
+  if (opts.mode === "realtime") return buildRealtimeAgentModule(opts);
+  return buildCascadeAgentModule(opts);
+}
+
+function buildCascadeAgentModule(opts: Extract<ResolvedOptions, { mode: "cascade" }>): string {
+  const stt = requireStage(STT_STAGE_PROVIDERS[opts.stt], "stt", opts.stt);
+  const tts = requireStage(TTS_STAGE_PROVIDERS[opts.tts], "tts", opts.tts);
+  const reasoner = REASONER_PROVIDERS[opts.reasoner];
+  if (reasoner === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--reasoner ${opts.reasoner} is not yet implemented by this generator`);
+  }
+  const vad = opts.vad !== undefined ? VAD_SIDECAR_PROVIDERS[opts.vad] : undefined;
+  if (opts.vad !== undefined && vad === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--vad ${opts.vad} is not yet implemented by this generator`);
+  }
+  const eos = opts.endpointing !== undefined ? ENDPOINTING_SIDECAR_PROVIDERS[opts.endpointing] : undefined;
+  if (opts.endpointing !== undefined && eos === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--endpointing ${opts.endpointing} is not yet implemented by this generator`);
+  }
+  const endpointingOwner = eos !== undefined ? "smart_turn" : stt.ownsEndpointing ? "provider_stt" : undefined;
+  if (endpointingOwner === undefined) {
+    throw new CliError(
+      EXIT_CODES.USAGE,
+      `--stt ${opts.stt} cannot own endpointing on its own — pass --endpointing pipecat-smart-turn`,
+    );
+  }
+
+  const imports = [
+    `import { VoiceAgentSession, type VoicePlugin } from "@kuralle-syrinx/core";`,
+    `import { ReasoningBridge } from "@kuralle-syrinx/aisdk";`,
+    importLine(stt.className, stt.importFrom ?? stt.packageName),
+    importLine(tts.className, tts.importFrom ?? tts.packageName),
+    ...(vad !== undefined ? [importLine(vad.className, vad.packageName)] : []),
+    ...(eos !== undefined ? [importLine(eos.className, eos.packageName)] : []),
+    ...reasoner.importLines(nodeEnvRef),
+  ];
+
+  const pluginConfigLines: string[] = [
+    `      stt: {`,
+    ...stt.configFields(nodeEnvRef).map((f) => `        ${f},`),
+    `      },`,
+  ];
+  if (vad !== undefined) pluginConfigLines.push(`      vad: {},`);
+  if (eos !== undefined) pluginConfigLines.push(`      eos: {},`);
+  pluginConfigLines.push(
+    `      bridge: {},`,
+    `      tts: {`,
+    ...tts.configFields(nodeEnvRef).map((f) => `        ${f},`),
+    `      },`,
+  );
+
+  const pluginInstanceLines: string[] = [`    stt: new ${stt.className}(),`];
+  if (vad !== undefined) pluginInstanceLines.push(`    vad: new ${vad.className}(),`);
+  if (eos !== undefined) pluginInstanceLines.push(`    eos: new ${eos.className}(),`);
+  pluginInstanceLines.push(
+    `    bridge: new ReasoningBridge(${reasoner.reasonerExpr}),`,
+    `    tts: new ${tts.className}(),`,
+  );
+
+  return `// SPDX-License-Identifier: MIT
+//
+// Cascade voice agent: ${opts.stt} STT -> ${opts.reasoner} reasoner -> ${opts.tts} TTS.
+// Generated by create-syrinx-agent. Wired to the local dev server and to
+// \`syrinx turn\`/\`syrinx text\` through the --agent <module>#<export> seam
+// (examples/02-hello-voice-headless/scripts/dev-server.ts).
+
+${mergeImports(imports).join("\n")}
+
+const ${SYSTEM_PROMPT_CONST} = ${JSON.stringify(SYSTEM_PROMPT)};
+
+export function createAgent(): VoiceAgentSession {
+${reasoner.preludeLines(nodeEnvRef).map((l) => `  ${l}`).join("\n")}
+
+  const session = new VoiceAgentSession({
+    plugins: {
+${pluginConfigLines.join("\n")}
+    },
+    endpointingOwner: "${endpointingOwner}",
+  });
+
+  const plugins: Record<string, VoicePlugin> = {
+${pluginInstanceLines.join("\n")}
+  };
+  for (const [name, plugin] of Object.entries(plugins)) {
+    session.registerPlugin(name, plugin);
+  }
+
+  return session;
+}
+`;
+}
+
+function buildRealtimeAgentModule(opts: Extract<ResolvedOptions, { mode: "realtime" }>): string {
+  const realtime = REALTIME_PROVIDERS[opts.realtime];
+  if (realtime === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--realtime ${opts.realtime} is not yet implemented by this generator`);
+  }
+
+  const imports = [
+    `import { VoiceAgentSession } from "@kuralle-syrinx/core";`,
+    `import { RealtimeBridge } from "@kuralle-syrinx/realtime";`,
+    `import { createNodeWsSocket } from "@kuralle-syrinx/ws/node";`,
+    ...realtime.importLines,
+  ];
+
+  return `// SPDX-License-Identifier: MIT
+//
+// Speech-to-speech voice agent: ${opts.realtime} realtime. Generated by
+// create-syrinx-agent. Wired to the local dev server and to
+// \`syrinx turn\`/\`syrinx text\` through the --agent <module>#<export> seam
+// (examples/02-hello-voice-headless/scripts/dev-server.ts).
+
+${mergeImports(imports).join("\n")}
+
+export function createAgent(): VoiceAgentSession {
+  const adapter = ${realtime.adapterExpr(nodeEnvRef, "createNodeWsSocket")};
+  const bridge = new RealtimeBridge(adapter);
+
+  const session = new VoiceAgentSession({
+    plugins: { realtime: {} },
+    endpointingOwner: "timer",
+  });
+  session.registerPlugin("realtime", bridge);
+
+  return session;
+}
+`;
+}

package/src/templates/agents-md.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: MIT
+//
+// Builds AGENTS.md — must state plainly what a coding agent CANNOT verify
+// headlessly (LDT-21 requirement). An AGENTS.md implying headless
+// verification is complete is worse than shipping none.
+
+import type { ResolvedOptions } from "../options.js";
+
+export function buildAgentsMd(opts: ResolvedOptions): string {
+  const pipelineLine =
+    opts.mode === "cascade"
+      ? `${opts.stt} STT -> ${opts.reasoner} reasoner -> ${opts.tts} TTS (cascade)`
+      : `${opts.realtime} realtime (speech-to-speech, no separate STT/TTS stages)`;
+
+  return `# AGENTS.md
+
+This project was generated by \`create-syrinx-agent\`.
+
+Pipeline: ${pipelineLine}
+Transport: ${opts.transport} · Runtime: ${opts.runtime}
+
+## What a coding agent CAN verify here
+
+- \`pnpm check:typecheck\` (\`tsc --noEmit\`) — the agent module and dev server compile.
+- \`pnpm check:turn\` — runs \`syrinx turn --in test/fixtures/smoke.wav --agent ./src/agent.ts#createAgent --json\`.
+  Given a fixture **with** a recorded expected transcript (a \`.json\` sidecar produced by the
+  Studio's "Save as fixture"), this asserts the replayed transcript matches and **exits non-zero
+  on drift** — a real regression check, not just a smoke test. The bundled \`test/fixtures/smoke.wav\`
+  ships with no sidecar, so as generated this only proves the pipeline runs end-to-end and produces
+  *some* transcript/reply/audio; record your own fixture with the Studio for an assertion that
+  actually catches regressions.
+- Exit codes and JSON output from \`syrinx turn\` / \`syrinx text\` — parseable, deterministic,
+  scriptable.
+
+Both checks need real provider credentials in \`.env\` (see \`.env.example\`) — without them
+\`check:turn\` fails at the provider call, not at a code defect.
+
+## What a coding agent CANNOT verify here
+
+A coding agent can assert transcripts, exit codes, and latency numbers. It **cannot** judge:
+
+- Whether barge-in feels natural (the timing a human perceives as responsive vs. jarring).
+- Whether a pause reads as "thinking" or as a hang — same latency number, different human read.
+- Whether a synthesized voice sounds warm, robotic, or off — TTS quality is a perceptual judgment.
+
+Those need a human in the Syrinx Studio, listening. Do not treat a green \`check:turn\` as proof the
+agent is pleasant to talk to — it only proves the transcript matched (or that the pipeline ran, for
+the unsigned bundled fixture).
+
+## \`tsx\` vs plain \`node\`
+
+\`--agent\` pointed at a \`.ts\` module (as in the scripts above) needs \`tsx\` — Node's built-in type
+stripping does not do TypeScript's \`.js\`-import-resolves-to-\`.ts\` remapping that this project's
+imports rely on. Built JS (after a bundler step) runs fine under plain \`node\`. Every script this
+generator wrote already invokes \`tsx\`; if you write your own, do the same for a \`.ts\` --agent target.
+
+## Layout
+
+- \`src/agent.ts\` — \`createAgent()\`, the \`--agent\` seam's factory export.
+- \`scripts/dev-server.ts\` — local dev server (\`pnpm dev\`), wraps \`createAgent()\` in a
+  ${opts.transport} transport host.
+- \`test/fixtures/smoke.wav\` — bundled silence fixture for \`check:turn\`.
+- \`.env.example\` — exactly the provider keys this combination needs.
+`;
+}

package/src/templates/cloudflare-worker.ts

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: MIT
+//
+// Emits src/index.ts + wrangler.jsonc for --runtime cloudflare, mirroring
+// examples/03-cf-agent-voice/src/index.ts and packages/cf-agents/README.md's
+// `withVoice(Agent, { pipeline, reasoner, transport })` shape. VAD/endpointing
+// sidecars are not wired here yet (see the generator's report) — passing
+// --vad/--endpointing with --runtime cloudflare is refused upstream.
+
+import type { ResolvedOptions, Transport } from "../options.js";
+import { STT_STAGE_PROVIDERS } from "../providers/stt.js";
+import { TTS_STAGE_PROVIDERS } from "../providers/tts.js";
+import { REASONER_PROVIDERS, SYSTEM_PROMPT_CONST } from "../providers/reasoner.js";
+import { REALTIME_PROVIDERS } from "../providers/realtime.js";
+import { CliError, EXIT_CODES } from "../exit-codes.js";
+import type { EnvKeySpec, StageProvider } from "../providers/types.js";
+import { collectEnvKeys } from "./env-example.js";
+
+const SYSTEM_PROMPT = "You are a helpful voice assistant. Keep your replies short.";
+
+function envRef(key: string): string {
+  return `env.${key}`;
+}
+
+function importLine(className: string, from: string): string {
+  return `import { ${className} } from "${from}";`;
+}
+
+function requireStage(provider: StageProvider | undefined, flag: string, value: string): StageProvider {
+  if (provider === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--${flag} ${value} is not yet implemented by this generator`);
+  }
+  return provider;
+}
+
+/** `withVoice`'s documented `transport` option: "edge" | "twilio" | "telnyx" — no "smartpbx". */
+function cfTransport(transport: Transport): "edge" | "twilio" | "telnyx" {
+  if (transport === "browser") return "edge";
+  if (transport === "twilio" || transport === "telnyx") return transport;
+  throw new CliError(
+    EXIT_CODES.USAGE,
+    `--runtime cloudflare has no ${transport} transport binding in @kuralle-syrinx/cf-agents (only edge/twilio/telnyx) — use --transport browser, twilio, or telnyx`,
+  );
+}
+
+function envInterface(keys: readonly EnvKeySpec[]): string {
+  const lines = keys.map((k) => `  readonly ${k.key}: string;`);
+  return `interface Env extends Record<string, unknown> {\n${lines.join("\n")}\n}`;
+}
+
+export function buildCloudflareWorkerSource(opts: ResolvedOptions): string {
+  const transport = cfTransport(opts.transport);
+  const envKeys = collectEnvKeys(opts);
+
+  if (opts.mode === "cascade") {
+    if (opts.vad !== undefined || opts.endpointing !== undefined) {
+      throw new CliError(
+        EXIT_CODES.USAGE,
+        "--vad/--endpointing are not yet implemented for --runtime cloudflare by this generator",
+      );
+    }
+    const stt = requireStage(STT_STAGE_PROVIDERS[opts.stt], "stt", opts.stt);
+    const tts = requireStage(TTS_STAGE_PROVIDERS[opts.tts], "tts", opts.tts);
+    const reasoner = REASONER_PROVIDERS[opts.reasoner];
+    if (reasoner === undefined) {
+      throw new CliError(EXIT_CODES.USAGE, `--reasoner ${opts.reasoner} is not yet implemented by this generator`);
+    }
+
+    const sttNew = stt.usesSocketFactory ? `new ${stt.className}(createWorkersSocket)` : `new ${stt.className}()`;
+    const ttsNew = tts.usesSocketFactory ? `new ${tts.className}(createWorkersSocket)` : `new ${tts.className}()`;
+    const needsWorkersSocket = stt.usesSocketFactory || tts.usesSocketFactory;
+
+    const imports = [
+      `import { Agent, routeAgentRequest } from "agents";`,
+      `import { withVoice } from "@kuralle-syrinx/cf-agents";`,
+      importLine(stt.className, stt.importFrom ?? stt.packageName),
+      importLine(tts.className, tts.importFrom ?? tts.packageName),
+      ...(needsWorkersSocket ? [`import { createWorkersSocket } from "@kuralle-syrinx/ws/workers";`] : []),
+      ...reasoner.importLines(envRef),
+    ];
+
+    return `// SPDX-License-Identifier: MIT
+//
+// Cascade voice agent on Cloudflare Workers: ${opts.stt} STT -> ${opts.reasoner} reasoner -> ${opts.tts} TTS.
+// Generated by create-syrinx-agent. Mirrors examples/03-cf-agent-voice and
+// packages/cf-agents/README.md.
+
+${imports.join("\n")}
+
+${envInterface(envKeys)}
+
+const ${SYSTEM_PROMPT_CONST} = ${JSON.stringify(SYSTEM_PROMPT)};
+
+export class VoiceAgent extends withVoice<Env, typeof Agent<Env>>(Agent<Env>, {
+  transport: "${transport}",
+  pipeline: {
+    kind: "cascaded",
+    stt: (env) => ({
+      plugin: ${sttNew},
+      config: {
+${stt.configFields(envRef).map((f) => `        ${f},`).join("\n")}
+      },
+    }),
+    tts: (env) => ({
+      plugin: ${ttsNew},
+      config: {
+${tts.configFields(envRef).map((f) => `        ${f},`).join("\n")}
+      },
+    }),
+  },
+  reasoner: (env) => {
+${reasoner.preludeLines(envRef).map((l) => `    ${l}`).join("\n")}
+    return ${reasoner.reasonerExpr};
+  },
+}) {}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return (await routeAgentRequest(request, env)) ?? new Response("Not found", { status: 404 });
+  },
+};
+`;
+  }
+
+  const realtime = REALTIME_PROVIDERS[opts.realtime];
+  if (realtime === undefined) {
+    throw new CliError(EXIT_CODES.USAGE, `--realtime ${opts.realtime} is not yet implemented by this generator`);
+  }
+  const imports = [
+    `import { Agent, routeAgentRequest } from "agents";`,
+    `import { withVoice } from "@kuralle-syrinx/cf-agents";`,
+    `import { createWorkersSocket } from "@kuralle-syrinx/ws/workers";`,
+    ...realtime.importLines,
+  ];
+
+  return `// SPDX-License-Identifier: MIT
+//
+// Speech-to-speech voice agent on Cloudflare Workers: ${opts.realtime} realtime.
+// Generated by create-syrinx-agent. Mirrors examples/03-cf-agent-voice and
+// packages/cf-agents/README.md.
+
+${imports.join("\n")}
+
+${envInterface(envKeys)}
+
+export class VoiceAgent extends withVoice<Env, typeof Agent<Env>>(Agent<Env>, {
+  transport: "${transport}",
+  pipeline: {
+    kind: "realtime",
+    front: (env) => ${realtime.adapterExpr(envRef, "createWorkersSocket")},
+  },
+}) {}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return (await routeAgentRequest(request, env)) ?? new Response("Not found", { status: 404 });
+  },
+};
+`;
+}
+
+export function buildWranglerJsonc(opts: ResolvedOptions): string {
+  const wrangler = {
+    $schema: "node_modules/wrangler/config-schema.json",
+    name: opts.name,
+    main: "src/index.ts",
+    compatibility_date: "2026-06-01",
+    compatibility_flags: ["nodejs_compat"],
+    durable_objects: { bindings: [{ name: "VoiceAgent", class_name: "VoiceAgent" }] },
+    migrations: [{ tag: "v1", new_sqlite_classes: ["VoiceAgent"] }],
+  };
+  return `${JSON.stringify(wrangler, null, 2)}\n`;
+}

package/src/templates/dev-server.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+//
+// Emits scripts/dev-server.ts for the node runtime — a transport host that
+// resolves --agent <module>[#export] exactly like
+// examples/02-hello-voice-headless/scripts/dev-server.ts, minus that example's
+// Studio-asset serving (this is a standalone project, not inside the monorepo;
+// bring your own browser client, e.g. @kuralle-syrinx/browser-client).
+
+import type { Transport } from "../options.js";
+
+interface TransportServerBinding {
+  readonly factoryName: string;
+  readonly extraOptions: readonly string[];
+  readonly urlPath: string;
+}
+
+const TRANSPORT_SERVERS: Readonly<Record<Transport, TransportServerBinding>> = {
+  browser: { factoryName: "createVoiceWebSocketServer", extraOptions: [`path: "/ws"`], urlPath: "/ws" },
+  twilio: { factoryName: "createTwilioMediaStreamServer", extraOptions: [], urlPath: "/" },
+  telnyx: { factoryName: "createTelnyxMediaStreamServer", extraOptions: [], urlPath: "/" },
+  smartpbx: { factoryName: "createSmartPbxMediaStreamServer", extraOptions: [], urlPath: "/" },
+};
+
+export function buildDevServer(transport: Transport): string {
+  const binding = TRANSPORT_SERVERS[transport];
+  const optionsLines = [`    port,`, `    host,`, ...binding.extraOptions.map((l) => `    ${l},`), `    createSession: () => factory(),`];
+
+  return `// SPDX-License-Identifier: MIT
+//
+// Local dev server — wires YOUR agent module to a ${transport} transport host.
+//
+//   pnpm dev -- --agent ./src/agent.ts#createAgent
+//
+// --agent is <module>[#namedExport]; the export is a zero-arg factory
+// returning a VoiceAgentSession. Same seam as
+// examples/02-hello-voice-headless/scripts/dev-server.ts.
+
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { ${binding.factoryName}, installGracefulShutdown } from "@kuralle-syrinx/server-websocket";
+import type { VoiceAgentSession } from "@kuralle-syrinx/core";
+
+export type SessionFactory = () => VoiceAgentSession | Promise<VoiceAgentSession>;
+
+/**
+ * Resolve \`--agent <module>[#export]\` to a factory. Fails loudly and
+ * specifically — a dev server that silently falls back to a different agent
+ * than the one you asked for is worse than one that refuses to start.
+ */
+async function resolveAgentFactory(spec: string | undefined): Promise<{ factory: SessionFactory; label: string }> {
+  if (!spec) throw new Error("--agent <module>[#export] is required, e.g. --agent ./src/agent.ts#createAgent");
+  const [modulePath, exportName] = spec.split("#");
+  if (!modulePath) throw new Error(\`--agent needs a module path, got: \${spec}\`);
+  const abs = isAbsolute(modulePath) ? modulePath : resolve(process.cwd(), modulePath);
+  const mod = (await import(pathToFileURL(abs).href)) as Record<string, unknown>;
+
+  const picked = exportName ? mod[exportName] : (mod["default"] ?? mod["createAgent"] ?? mod["createSession"]);
+  if (typeof picked !== "function") {
+    const available = Object.keys(mod).filter((k) => typeof mod[k] === "function");
+    throw new Error(
+      \`\${abs} has no callable export \${exportName ? \`"\${exportName}"\` : "(default, createAgent, or createSession)"}. \` +
+        \`Callable exports: \${available.length > 0 ? available.join(", ") : "(none)"}\`,
+    );
+  }
+  return { factory: picked as SessionFactory, label: \`\${modulePath}\${exportName ? \`#\${exportName}\` : ""}\` };
+}
+
+function flag(argv: readonly string[], name: string): string | undefined {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function readPort(): number {
+  const raw = process.env["SYRINX_DEV_PORT"]?.trim();
+  if (!raw) return 4173;
+  const port = Number.parseInt(raw, 10);
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) throw new Error(\`invalid SYRINX_DEV_PORT: \${raw}\`);
+  return port;
+}
+
+async function main(): Promise<void> {
+  const { factory, label } = await resolveAgentFactory(flag(process.argv.slice(2), "--agent"));
+  const port = readPort();
+  const host = process.env["SYRINX_DEV_HOST"]?.trim() || "127.0.0.1";
+
+  const server = await ${binding.factoryName}({
+${optionsLines.join("\n")}
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("expected TCP server address");
+  console.log(\`Syrinx dev server (${transport}): ws://\${host}:\${String(address.port)}${binding.urlPath}\`);
+  console.log(\`Agent: \${label}\`);
+
+  installGracefulShutdown(server, { drainDeadlineMs: 10_000, onClosed: () => process.exit(0) });
+}
+
+void main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});
+`;
+}

package/src/templates/env-example.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+//
+// Builds .env.example naming exactly the keys the chosen combination needs
+// (LDT-21 requirement) — not a union of every provider's keys.
+
+import type { ResolvedOptions } from "../options.js";
+import { STT_STAGE_PROVIDERS } from "../providers/stt.js";
+import { TTS_STAGE_PROVIDERS } from "../providers/tts.js";
+import { REASONER_PROVIDERS } from "../providers/reasoner.js";
+import { REALTIME_PROVIDERS } from "../providers/realtime.js";
+import { VAD_SIDECAR_PROVIDERS, ENDPOINTING_SIDECAR_PROVIDERS } from "../providers/vad-endpointing.js";
+import type { EnvKeySpec } from "../providers/types.js";
+
+export function collectEnvKeys(opts: ResolvedOptions): readonly EnvKeySpec[] {
+  const keys: EnvKeySpec[] = [];
+  const seen = new Set<string>();
+  const add = (specs: readonly EnvKeySpec[]) => {
+    for (const spec of specs) {
+      if (seen.has(spec.key)) continue;
+      seen.add(spec.key);
+      keys.push(spec);
+    }
+  };
+
+  if (opts.mode === "cascade") {
+    const stt = STT_STAGE_PROVIDERS[opts.stt];
+    const tts = TTS_STAGE_PROVIDERS[opts.tts];
+    const reasoner = REASONER_PROVIDERS[opts.reasoner];
+    if (stt) add(stt.envKeys);
+    if (tts) add(tts.envKeys);
+    if (reasoner) add(reasoner.envKeys);
+    const vad = opts.vad !== undefined ? VAD_SIDECAR_PROVIDERS[opts.vad] : undefined;
+    if (vad) add(vad.envKeys);
+    const eos = opts.endpointing !== undefined ? ENDPOINTING_SIDECAR_PROVIDERS[opts.endpointing] : undefined;
+    if (eos) add(eos.envKeys);
+  } else {
+    const realtime = REALTIME_PROVIDERS[opts.realtime];
+    if (realtime) add(realtime.envKeys);
+  }
+
+  return keys;
+}
+
+export function buildEnvExample(opts: ResolvedOptions): string {
+  const keys = collectEnvKeys(opts);
+  const lines = [
+    "# Generated by create-syrinx-agent — exactly the keys this combination needs.",
+    "# Copy to .env and fill in.",
+    "",
+    ...keys.map((k) => `${k.key}=`),
+    "",
+    "# Optional — local dev server bind (defaults: 127.0.0.1:4173)",
+    "SYRINX_DEV_PORT=",
+    "SYRINX_DEV_HOST=",
+    "",
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/templates/fixture.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+//
+// A minimal, self-contained mono 16 kHz PCM16 WAV fixture (0.5s of silence)
+// so `check:turn` (syrinx turn --in test/fixtures/smoke.wav) has something to
+// replay without depending on any file outside the generated project. It
+// carries no expected-transcript sidecar — see AGENTS.md for what that means.
+
+const SAMPLE_RATE = 16_000;
+const DURATION_SECONDS = 0.5;
+const CHANNELS = 1;
+const BITS_PER_SAMPLE = 16;
+
+export function buildSmokeWav(): Buffer {
+  const numSamples = Math.floor(SAMPLE_RATE * DURATION_SECONDS);
+  const dataBytes = numSamples * CHANNELS * (BITS_PER_SAMPLE / 8);
+  const buffer = Buffer.alloc(44 + dataBytes);
+
+  buffer.write("RIFF", 0, "ascii");
+  buffer.writeUInt32LE(36 + dataBytes, 4);
+  buffer.write("WAVE", 8, "ascii");
+  buffer.write("fmt ", 12, "ascii");
+  buffer.writeUInt32LE(16, 16); // fmt chunk size
+  buffer.writeUInt16LE(1, 20); // PCM
+  buffer.writeUInt16LE(CHANNELS, 22);
+  buffer.writeUInt32LE(SAMPLE_RATE, 24);
+  buffer.writeUInt32LE(SAMPLE_RATE * CHANNELS * (BITS_PER_SAMPLE / 8), 28); // byte rate
+  buffer.writeUInt16LE(CHANNELS * (BITS_PER_SAMPLE / 8), 32); // block align
+  buffer.writeUInt16LE(BITS_PER_SAMPLE, 34);
+  buffer.write("data", 36, "ascii");
+  buffer.writeUInt32LE(dataBytes, 40);
+  // PCM16 silence: the buffer is already zero-filled by Buffer.alloc.
+
+  return buffer;
+}