mercury-agent 0.5.0 → 0.5.2

package/examples/extensions/tradestation/index.ts

@@ -1,153 +1,153 @@
-import {
-  runTradeStationTokenRefresh,
-  TRADESTATION_EXT,
-} from "./host/refresh.js";
-
-const API_BASE_DEFAULT = "https://api.tradestation.com/v3";
-
-function apiBaseFromHost(): string {
-  const raw = process.env.MERCURY_TS_API_BASE?.trim();
-  if (raw) return raw.replace(/\/$/, "");
-  const env = process.env.MERCURY_TS_ENVIRONMENT?.trim().toUpperCase();
-  if (env === "LIVE" || env === "SIM") {
-    return API_BASE_DEFAULT;
-  }
-  return API_BASE_DEFAULT;
-}
-
-type ConnectionStatus = "connected" | "needs-reauth" | "broken" | "unknown";
-
-type ConnectionStatusCtx = {
-  db: {
-    getExtState(e: string, k: string): string | null;
-  };
-};
-
-type ExtCtx = {
-  db: {
-    getExtState(e: string, k: string): string | null;
-    setExtState(e: string, k: string, v: string): void;
-    deleteExtState(e: string, k: string): boolean;
-  };
-  log: {
-    info(m: string): void;
-    warn(m: string): void;
-    error(m: string): void;
-  };
-};
-
-/** Structural match for `MercuryExtensionAPI` (avoid package subpath imports). */
-type MercuryExt = {
-  permission(opts: { defaultRoles: string[] }): void;
-  env(def: { from: string; as?: string }): void;
-  requires(
-    capabilities: (
-      | "tools"
-      | "vision"
-      | "audio_input"
-      | "audio_output"
-      | "extended_thinking"
-    )[],
-  ): void;
-  job(name: string, def: { interval: number; run: (ctx: ExtCtx) => Promise<void> }): void;
-  on(event: "startup", handler: (event: Record<string, never>, ctx: ExtCtx) => Promise<void>): void;
-  on(
-    event: "before_container",
-    handler: (
-      event: { spaceId: string; callerId: string },
-      ctx: ExtCtx & {
-        hasCallerPermission(spaceId: string, callerId: string, permission: string): boolean;
-      },
-    ) => Promise<{ env?: Record<string, string> } | undefined>,
-  ): void;
-  skill(relativePath: string): void;
-  connection(def: {
-    displayName: string;
-    iconUrl?: string;
-    category:
-      | "email"
-      | "drive"
-      | "calendar"
-      | "finance"
-      | "messaging"
-      | "docs"
-      | "workspace"
-      | "other";
-    authType:
-      | "oauth2"
-      | "apikey"
-      | "app-password"
-      | "credentials-file"
-      | "form"
-      | "custom";
-    credentialEnvVar?: string;
-    scopes?: string[];
-    statusCheck?: (ctx: ConnectionStatusCtx) => Promise<{ status: ConnectionStatus; detail?: string }>;
-  }): void;
-};
-
-export default function (mercury: MercuryExt) {
-  mercury.permission({ defaultRoles: [] });
-  mercury.requires(["tools"]);
-  mercury.env({ from: "MERCURY_TS_CLIENT_ID" });
-  mercury.env({ from: "MERCURY_TS_CLIENT_SECRET" });
-  mercury.env({ from: "MERCURY_TRADESTATION_REFRESH_TOKEN" });
-
-  mercury.connection({
-    displayName: "TradeStation",
-    category: "finance",
-    authType: "oauth2",
-    scopes: ["openid", "offline_access", "MarketData", "ReadAccount", "Trade"],
-    // No credentialEnvVar — credentials live in extension_state, not env.
-    statusCheck: async (ctx) => {
-      const authError = ctx.db.getExtState(TRADESTATION_EXT, "auth_error");
-      if (authError) {
-        return { status: "needs-reauth", detail: authError };
-      }
-      const token = ctx.db.getExtState(TRADESTATION_EXT, "access_token");
-      if (token) {
-        return { status: "connected" };
-      }
-      return { status: "unknown" };
-    },
-  });
-
-  mercury.on("startup", async (_, ctx) => {
-    await runTradeStationTokenRefresh(ctx.db, ctx.log);
-  });
-
-  mercury.job("ts-token-refresh", {
-    interval: 10 * 60 * 1000,
-    run: async (ctx) => {
-      await runTradeStationTokenRefresh(ctx.db, ctx.log);
-    },
-  });
-
-  mercury.on("before_container", async (event, ctx) => {
-    if (
-      !ctx.hasCallerPermission(event.spaceId, event.callerId, TRADESTATION_EXT)
-    ) {
-      return undefined;
-    }
-
-    const base = apiBaseFromHost();
-    const authError = ctx.db.getExtState(TRADESTATION_EXT, "auth_error");
-    const token = ctx.db.getExtState(TRADESTATION_EXT, "access_token");
-
-    const env: Record<string, string> = {
-      TRADESTATION_API_BASE: base,
-    };
-
-    if (authError) {
-      env.TRADESTATION_AUTH_ERROR = authError;
-    }
-
-    if (token) {
-      env.TRADESTATION_ACCESS_TOKEN = token;
-    }
-
-    return { env };
-  });
-
-  mercury.skill("./skill");
-}
+import {
+  runTradeStationTokenRefresh,
+  TRADESTATION_EXT,
+} from "./host/refresh.js";
+
+const API_BASE_DEFAULT = "https://api.tradestation.com/v3";
+
+function apiBaseFromHost(): string {
+  const raw = process.env.MERCURY_TS_API_BASE?.trim();
+  if (raw) return raw.replace(/\/$/, "");
+  const env = process.env.MERCURY_TS_ENVIRONMENT?.trim().toUpperCase();
+  if (env === "LIVE" || env === "SIM") {
+    return API_BASE_DEFAULT;
+  }
+  return API_BASE_DEFAULT;
+}
+
+type ConnectionStatus = "connected" | "needs-reauth" | "broken" | "unknown";
+
+type ConnectionStatusCtx = {
+  db: {
+    getExtState(e: string, k: string): string | null;
+  };
+};
+
+type ExtCtx = {
+  db: {
+    getExtState(e: string, k: string): string | null;
+    setExtState(e: string, k: string, v: string): void;
+    deleteExtState(e: string, k: string): boolean;
+  };
+  log: {
+    info(m: string): void;
+    warn(m: string): void;
+    error(m: string): void;
+  };
+};
+
+/** Structural match for `MercuryExtensionAPI` (avoid package subpath imports). */
+type MercuryExt = {
+  permission(opts: { defaultRoles: string[] }): void;
+  env(def: { from: string; as?: string }): void;
+  requires(
+    capabilities: (
+      | "tools"
+      | "vision"
+      | "audio_input"
+      | "audio_output"
+      | "extended_thinking"
+    )[],
+  ): void;
+  job(name: string, def: { interval: number; run: (ctx: ExtCtx) => Promise<void> }): void;
+  on(event: "startup", handler: (event: Record<string, never>, ctx: ExtCtx) => Promise<void>): void;
+  on(
+    event: "before_container",
+    handler: (
+      event: { spaceId: string; callerId: string },
+      ctx: ExtCtx & {
+        hasCallerPermission(spaceId: string, callerId: string, permission: string): boolean;
+      },
+    ) => Promise<{ env?: Record<string, string> } | undefined>,
+  ): void;
+  skill(relativePath: string): void;
+  connection(def: {
+    displayName: string;
+    iconUrl?: string;
+    category:
+      | "email"
+      | "drive"
+      | "calendar"
+      | "finance"
+      | "messaging"
+      | "docs"
+      | "workspace"
+      | "other";
+    authType:
+      | "oauth2"
+      | "apikey"
+      | "app-password"
+      | "credentials-file"
+      | "form"
+      | "custom";
+    credentialEnvVar?: string;
+    scopes?: string[];
+    statusCheck?: (ctx: ConnectionStatusCtx) => Promise<{ status: ConnectionStatus; detail?: string }>;
+  }): void;
+};
+
+export default function (mercury: MercuryExt) {
+  mercury.permission({ defaultRoles: [] });
+  mercury.requires(["tools"]);
+  mercury.env({ from: "MERCURY_TS_CLIENT_ID" });
+  mercury.env({ from: "MERCURY_TS_CLIENT_SECRET" });
+  mercury.env({ from: "MERCURY_TRADESTATION_REFRESH_TOKEN" });
+
+  mercury.connection({
+    displayName: "TradeStation",
+    category: "finance",
+    authType: "oauth2",
+    scopes: ["openid", "offline_access", "MarketData", "ReadAccount", "Trade"],
+    // No credentialEnvVar — credentials live in extension_state, not env.
+    statusCheck: async (ctx) => {
+      const authError = ctx.db.getExtState(TRADESTATION_EXT, "auth_error");
+      if (authError) {
+        return { status: "needs-reauth", detail: authError };
+      }
+      const token = ctx.db.getExtState(TRADESTATION_EXT, "access_token");
+      if (token) {
+        return { status: "connected" };
+      }
+      return { status: "unknown" };
+    },
+  });
+
+  mercury.on("startup", async (_, ctx) => {
+    await runTradeStationTokenRefresh(ctx.db, ctx.log);
+  });
+
+  mercury.job("ts-token-refresh", {
+    interval: 10 * 60 * 1000,
+    run: async (ctx) => {
+      await runTradeStationTokenRefresh(ctx.db, ctx.log);
+    },
+  });
+
+  mercury.on("before_container", async (event, ctx) => {
+    if (
+      !ctx.hasCallerPermission(event.spaceId, event.callerId, TRADESTATION_EXT)
+    ) {
+      return undefined;
+    }
+
+    const base = apiBaseFromHost();
+    const authError = ctx.db.getExtState(TRADESTATION_EXT, "auth_error");
+    const token = ctx.db.getExtState(TRADESTATION_EXT, "access_token");
+
+    const env: Record<string, string> = {
+      TRADESTATION_API_BASE: base,
+    };
+
+    if (authError) {
+      env.TRADESTATION_AUTH_ERROR = authError;
+    }
+
+    if (token) {
+      env.TRADESTATION_ACCESS_TOKEN = token;
+    }
+
+    return { env };
+  });
+
+  mercury.skill("./skill");
+}

package/examples/extensions/tradestation/skill/SKILL.md

@@ -1,67 +1,67 @@
----
-name: tradestation
-description: Call TradeStation REST API v3 from the agent (accounts, balances, positions, bars) and place orders via mrctl two-step confirmation. Admin-only; requires Mercury host OAuth setup and token refresh job.
-allowed-tools: Bash
----
-
-# TradeStation (Mercury extension)
-
-This skill is for **admin** callers only. Mercury injects `TRADESTATION_ACCESS_TOKEN` and `TRADESTATION_API_BASE` only when the user has the `tradestation` permission (default: admins only).
-
-## Host setup
-
-1. Register an OAuth app with TradeStation (same model as Tagula: `TS_CLIENT_ID`, `TS_CLIENT_SECRET`, redirect URI, scopes such as `openid profile offline_access MarketData ReadAccount`).
-   - **Orders**: add TradeStation scopes required for order placement (see [TradeStation scopes](https://api.tradestation.com/docs/fundamentals/authentication/scopes/)); re-authenticate after changing scopes.
-2. Complete OAuth once (e.g. Tagula `manage-auth` / your dashboard) and put the same credentials in the Mercury host `.env` as either the `MERCURY_*` names **or** the same Tagula names (`TS_CLIENT_ID`, `TS_CLIENT_SECRET`, `TS_REFRESH_TOKEN`, optional `TS_ACCESS_TOKEN`). The refresh job accepts both.
-   - Optional: `MERCURY_TS_TOKEN_URL`, `MERCURY_TS_API_BASE`, `MERCURY_TS_ENVIRONMENT` (`SIM` / `LIVE` — documented for parity; v3 base URL is unchanged)
-   - **Live orders**: by default, only **SIM** accounts (AccountID matching `SIM…`) may place orders via Mercury. To allow non-SIM accounts, set `MERCURY_TS_ALLOW_LIVE_ORDERS=true` on the host (real-money risk).
-3. Restart Mercury so the extension job runs (refresh every **10 minutes**).
-
-If refresh fails, the container may receive `TRADESTATION_AUTH_ERROR` with a short code (e.g. `refresh_failed:...`, `no_refresh_token`). Tell the user to re-authenticate and update host env / tokens.
-
-## CLI — reads (Bun)
-
-Scripts live next to this skill. In the agent container the skill is typically mounted under `/home/node/.pi/agent/skills/tradestation/`.
-
-```bash
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts accounts
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts balances ACCOUNT_KEY
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts positions ACCOUNT_KEY
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts bars SYMBOL [barsback]
-```
-
-Examples:
-
-```bash
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts accounts
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts balances SIM123456789
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts positions SIM123456789
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts bars AAPL 20
-bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts bars '%40ES' 10
-```
-
-Use a URL-encoded symbol for futures (e.g. `@ES` as `%40ES`) or pass `@ES` quoted so the shell does not expand it.
-
-## Orders — two-step confirmation (`mrctl`)
-
-Order placement runs on the **Mercury host** (not inside `ts-cli`) so the flow can be audited and gated. Use **`mrctl`** from the agent container (same headers as other `mrctl` commands).
-
-1. **Propose** (no `--confirm`): calls TradeStation `orderconfirm`, stores a pending id (~15 minutes), returns a summary and `pendingId`.
-2. **Human check**: show the summary on **any** chat platform. The user can confirm with plain text, e.g. `CONFIRM <pendingId>`, or tell you to run step 3.
-3. **Execute**: same flags as step 1 plus `--confirm --pending-id <pendingId>`.
-
-Example (SIM account):
-
-```bash
-mrctl tradestation order --account SIM123456789 --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY
-# … user approves …
-mrctl tradestation order --account SIM123456789 --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY --confirm --pending-id '<uuid-from-step-1>'
-```
-
-Optional: `--route Intelligent` (default), `--limit-price`, `--stop-price`, `--expiration-date` (for time-in-force), `--type` (default `Market`).
-
-**Rules**: Do not skip human confirmation. Do not place live orders unless the user explicitly wants that and `MERCURY_TS_ALLOW_LIVE_ORDERS` is enabled on the host.
-
-## Scope
-
-Read helpers: **accounts**, **balances**, **positions**, **bars**. Orders: **host-side** via `mrctl tradestation order` only. Not a full API mirror; no streaming in-container.
+---
+name: tradestation
+description: Call TradeStation REST API v3 from the agent (accounts, balances, positions, bars) and place orders via mrctl two-step confirmation. Admin-only; requires Mercury host OAuth setup and token refresh job.
+allowed-tools: Bash
+---
+
+# TradeStation (Mercury extension)
+
+This skill is for **admin** callers only. Mercury injects `TRADESTATION_ACCESS_TOKEN` and `TRADESTATION_API_BASE` only when the user has the `tradestation` permission (default: admins only).
+
+## Host setup
+
+1. Register an OAuth app with TradeStation (same model as Tagula: `TS_CLIENT_ID`, `TS_CLIENT_SECRET`, redirect URI, scopes such as `openid profile offline_access MarketData ReadAccount`).
+   - **Orders**: add TradeStation scopes required for order placement (see [TradeStation scopes](https://api.tradestation.com/docs/fundamentals/authentication/scopes/)); re-authenticate after changing scopes.
+2. Complete OAuth once (e.g. Tagula `manage-auth` / your dashboard) and put the same credentials in the Mercury host `.env` as either the `MERCURY_*` names **or** the same Tagula names (`TS_CLIENT_ID`, `TS_CLIENT_SECRET`, `TS_REFRESH_TOKEN`, optional `TS_ACCESS_TOKEN`). The refresh job accepts both.
+   - Optional: `MERCURY_TS_TOKEN_URL`, `MERCURY_TS_API_BASE`, `MERCURY_TS_ENVIRONMENT` (`SIM` / `LIVE` — documented for parity; v3 base URL is unchanged)
+   - **Live orders**: by default, only **SIM** accounts (AccountID matching `SIM…`) may place orders via Mercury. To allow non-SIM accounts, set `MERCURY_TS_ALLOW_LIVE_ORDERS=true` on the host (real-money risk).
+3. Restart Mercury so the extension job runs (refresh every **10 minutes**).
+
+If refresh fails, the container may receive `TRADESTATION_AUTH_ERROR` with a short code (e.g. `refresh_failed:...`, `no_refresh_token`). Tell the user to re-authenticate and update host env / tokens.
+
+## CLI — reads (Bun)
+
+Scripts live next to this skill. In the agent container the skill is typically mounted under `/home/node/.pi/agent/skills/tradestation/`.
+
+```bash
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts accounts
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts balances ACCOUNT_KEY
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts positions ACCOUNT_KEY
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts bars SYMBOL [barsback]
+```
+
+Examples:
+
+```bash
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts accounts
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts balances SIM123456789
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts positions SIM123456789
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts bars AAPL 20
+bun /home/node/.pi/agent/skills/tradestation/scripts/ts-cli.ts bars '%40ES' 10
+```
+
+Use a URL-encoded symbol for futures (e.g. `@ES` as `%40ES`) or pass `@ES` quoted so the shell does not expand it.
+
+## Orders — two-step confirmation (`mrctl`)
+
+Order placement runs on the **Mercury host** (not inside `ts-cli`) so the flow can be audited and gated. Use **`mrctl`** from the agent container (same headers as other `mrctl` commands).
+
+1. **Propose** (no `--confirm`): calls TradeStation `orderconfirm`, stores a pending id (~15 minutes), returns a summary and `pendingId`.
+2. **Human check**: show the summary on **any** chat platform. The user can confirm with plain text, e.g. `CONFIRM <pendingId>`, or tell you to run step 3.
+3. **Execute**: same flags as step 1 plus `--confirm --pending-id <pendingId>`.
+
+Example (SIM account):
+
+```bash
+mrctl tradestation order --account SIM123456789 --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY
+# … user approves …
+mrctl tradestation order --account SIM123456789 --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY --confirm --pending-id '<uuid-from-step-1>'
+```
+
+Optional: `--route Intelligent` (default), `--limit-price`, `--stop-price`, `--expiration-date` (for time-in-force), `--type` (default `Market`).
+
+**Rules**: Do not skip human confirmation. Do not place live orders unless the user explicitly wants that and `MERCURY_TS_ALLOW_LIVE_ORDERS` is enabled on the host.
+
+## Scope
+
+Read helpers: **accounts**, **balances**, **positions**, **bars**. Orders: **host-side** via `mrctl tradestation order` only. Not a full API mirror; no streaming in-container.

package/examples/extensions/voice-synth/index.ts

@@ -1,94 +1,94 @@
-import { mkdirSync, statSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import type {
-  MercuryExtensionAPI,
-  MercuryExtensionContext,
-} from "mercury-agent/extensions/types";
-import type { MercuryTtsConfig } from "mercury-agent/tts";
-import { synthesizeSpeech } from "mercury-agent/tts";
-import type { EgressFile } from "mercury-agent/types";
-
-const EXT = "voice-synth";
-
-/** Prefer `voice-synth.mode`; fall back to legacy `voice-synth.auto`. */
-function readVoiceSynthMode(
-  ctx: MercuryExtensionContext,
-  spaceId: string,
-): "on_demand" | "auto" {
-  const mode = ctx.db.getSpaceConfig(spaceId, `${EXT}.mode`);
-  if (mode === "auto" || mode === "on_demand") return mode;
-  const legacy = ctx.db.getSpaceConfig(spaceId, `${EXT}.auto`);
-  return legacy === "true" ? "auto" : "on_demand";
-}
-
-function toTtsConfig(ctx: MercuryExtensionContext): MercuryTtsConfig {
-  const c = ctx.config;
-  return {
-    ttsProvider: c.ttsProvider,
-    azureSpeechKey: c.azureSpeechKey,
-    azureSpeechRegion: c.azureSpeechRegion,
-    googleApplicationCredentials: c.googleApplicationCredentials,
-    ttsMaxChars: c.ttsMaxChars,
-  };
-}
-
-export default function setup(mercury: MercuryExtensionAPI) {
-  mercury.config("mode", {
-    description:
-      "on_demand: TTS only when the agent runs `mrctl tts synthesize` (default). auto: attach a TTS MP3 to every assistant reply.",
-    default: "on_demand",
-    validate: (v) => v === "on_demand" || v === "auto",
-  });
-
-  mercury.config("auto", {
-    description:
-      "Legacy: prefer voice-synth.mode. Used only when mode is unset; true equals mode=auto.",
-    default: "false",
-    validate: (v) => v === "true" || v === "false",
-  });
-
-  mercury.skill("./skill");
-
-  mercury.on("after_container", async (event, ctx) => {
-    if (readVoiceSynthMode(ctx, event.spaceId) !== "auto") return undefined;
-    if (!event.reply?.trim()) return undefined;
-    if (event.error) return undefined;
-
-    if (
-      !ctx.hasCallerPermission(event.spaceId, event.callerId, "tts.synthesize")
-    ) {
-      ctx.log.warn("voice-synth.auto skipped: caller lacks tts.synthesize", {
-        extension: EXT,
-        spaceId: event.spaceId,
-      });
-      return undefined;
-    }
-
-    const outDir = path.join(event.workspace, "outbox");
-    mkdirSync(outDir, { recursive: true });
-    const filename = `tts-${Date.now()}.mp3`;
-    const absPath = path.join(outDir, filename);
-
-    try {
-      const { buffer } = await synthesizeSpeech(toTtsConfig(ctx), {
-        text: event.reply,
-        language: "auto",
-      });
-      writeFileSync(absPath, buffer);
-      const st = statSync(absPath);
-      const file: EgressFile = {
-        path: absPath,
-        filename,
-        mimeType: "audio/mpeg",
-        sizeBytes: st.size,
-      };
-      return { files: [file] };
-    } catch (e) {
-      ctx.log.error("voice-synth TTS failed", {
-        extension: EXT,
-        error: e instanceof Error ? e.message : String(e),
-      });
-      return undefined;
-    }
-  });
-}
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import type {
+  MercuryExtensionAPI,
+  MercuryExtensionContext,
+} from "mercury-agent/extensions/types";
+import type { MercuryTtsConfig } from "mercury-agent/tts";
+import { synthesizeSpeech } from "mercury-agent/tts";
+import type { EgressFile } from "mercury-agent/types";
+
+const EXT = "voice-synth";
+
+/** Prefer `voice-synth.mode`; fall back to legacy `voice-synth.auto`. */
+function readVoiceSynthMode(
+  ctx: MercuryExtensionContext,
+  spaceId: string,
+): "on_demand" | "auto" {
+  const mode = ctx.db.getSpaceConfig(spaceId, `${EXT}.mode`);
+  if (mode === "auto" || mode === "on_demand") return mode;
+  const legacy = ctx.db.getSpaceConfig(spaceId, `${EXT}.auto`);
+  return legacy === "true" ? "auto" : "on_demand";
+}
+
+function toTtsConfig(ctx: MercuryExtensionContext): MercuryTtsConfig {
+  const c = ctx.config;
+  return {
+    ttsProvider: c.ttsProvider,
+    azureSpeechKey: c.azureSpeechKey,
+    azureSpeechRegion: c.azureSpeechRegion,
+    googleApplicationCredentials: c.googleApplicationCredentials,
+    ttsMaxChars: c.ttsMaxChars,
+  };
+}
+
+export default function setup(mercury: MercuryExtensionAPI) {
+  mercury.config("mode", {
+    description:
+      "on_demand: TTS only when the agent runs `mrctl tts synthesize` (default). auto: attach a TTS MP3 to every assistant reply.",
+    default: "on_demand",
+    validate: (v) => v === "on_demand" || v === "auto",
+  });
+
+  mercury.config("auto", {
+    description:
+      "Legacy: prefer voice-synth.mode. Used only when mode is unset; true equals mode=auto.",
+    default: "false",
+    validate: (v) => v === "true" || v === "false",
+  });
+
+  mercury.skill("./skill");
+
+  mercury.on("after_container", async (event, ctx) => {
+    if (readVoiceSynthMode(ctx, event.spaceId) !== "auto") return undefined;
+    if (!event.reply?.trim()) return undefined;
+    if (event.error) return undefined;
+
+    if (
+      !ctx.hasCallerPermission(event.spaceId, event.callerId, "tts.synthesize")
+    ) {
+      ctx.log.warn("voice-synth.auto skipped: caller lacks tts.synthesize", {
+        extension: EXT,
+        spaceId: event.spaceId,
+      });
+      return undefined;
+    }
+
+    const outDir = path.join(event.workspace, "outbox");
+    mkdirSync(outDir, { recursive: true });
+    const filename = `tts-${Date.now()}.mp3`;
+    const absPath = path.join(outDir, filename);
+
+    try {
+      const { buffer } = await synthesizeSpeech(toTtsConfig(ctx), {
+        text: event.reply,
+        language: "auto",
+      });
+      writeFileSync(absPath, buffer);
+      const st = statSync(absPath);
+      const file: EgressFile = {
+        path: absPath,
+        filename,
+        mimeType: "audio/mpeg",
+        sizeBytes: st.size,
+      };
+      return { files: [file] };
+    } catch (e) {
+      ctx.log.error("voice-synth TTS failed", {
+        extension: EXT,
+        error: e instanceof Error ? e.message : String(e),
+      });
+      return undefined;
+    }
+  });
+}