mercury-agent 0.4.5

package/examples/extensions/tradestation/index.ts

@@ -0,0 +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");
+}

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

@@ -0,0 +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.

package/examples/extensions/tradestation/skill/scripts/ts-cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env bun
+/**
+ * Minimal TradeStation v3 CLI for the Mercury agent container.
+ * Uses TRADESTATION_ACCESS_TOKEN and TRADESTATION_API_BASE from the host hook.
+ */
+
+const token = process.env.TRADESTATION_ACCESS_TOKEN;
+const authErr = process.env.TRADESTATION_AUTH_ERROR;
+const base = (
+  process.env.TRADESTATION_API_BASE || "https://api.tradestation.com/v3"
+).replace(/\/$/, "");
+
+function usage(): never {
+  console.error(`Usage:
+  ts-cli.ts accounts
+  ts-cli.ts balances <accountKey>
+  ts-cli.ts positions <accountKey>
+  ts-cli.ts bars <symbol> [barsback]
+
+Environment: TRADESTATION_ACCESS_TOKEN (and optional TRADESTATION_API_BASE)`);
+  process.exit(1);
+}
+
+async function apiGet(
+  path: string,
+  query?: Record<string, string>,
+): Promise<unknown> {
+  const url = new URL(path.replace(/^\//, ""), `${base}/`);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== "") url.searchParams.set(k, v);
+    }
+  }
+  const res = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+    },
+  });
+  const text = await res.text();
+  let body: unknown;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = text;
+  }
+  if (!res.ok) {
+    console.error(res.status, body);
+    process.exit(1);
+  }
+  return body;
+}
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv;
+  if (!cmd) usage();
+
+  if (authErr) {
+    console.error("TradeStation auth error:", authErr);
+    process.exit(1);
+  }
+  if (!token) {
+    console.error(
+      "Missing TRADESTATION_ACCESS_TOKEN. This TradeStation integration is admin-only; check Mercury host configuration.",
+    );
+    process.exit(1);
+  }
+
+  switch (cmd) {
+    case "accounts": {
+      const data = await apiGet("/brokerage/accounts");
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    case "balances": {
+      const accountKey = rest[0];
+      if (!accountKey) usage();
+      const data = await apiGet(
+        `/brokerage/accounts/${encodeURIComponent(accountKey)}/balances`,
+      );
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    case "positions": {
+      const accountKey = rest[0];
+      if (!accountKey) usage();
+      const data = await apiGet(
+        `/brokerage/accounts/${encodeURIComponent(accountKey)}/positions`,
+      );
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    case "bars": {
+      const symbol = rest[0];
+      if (!symbol) usage();
+      const barsback = rest[1] ?? "20";
+      const data = await apiGet(
+        `/marketdata/barcharts/${encodeURIComponent(symbol)}`,
+        {
+          barsback,
+        },
+      );
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    default:
+      usage();
+  }
+}
+
+await main();

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

@@ -0,0 +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;
+    }
+  });
+}

package/examples/extensions/voice-synth/skill/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: voice-synth
+description: Cloud text-to-speech (Google or Azure) for English and Hebrew — on-demand via mrctl or optional auto voice attachments per space.
+---
+
+# Voice synthesis (TTS)
+
+**`mrctl tts synthesize` is available in this environment.** When the user asks for a voice message, audio reply, or TTS, you MUST run the command below. Do not assume it is unavailable — always try it and report any error verbatim.
+
+**Do not paste** `mrctl`, shell snippets, or JSON tool-call blobs into your **visible** reply — use the **bash tool** only for the command. The user sees normal text plus the audio attachment.
+
+## How to send a voice message
+
+```bash
+mrctl tts synthesize --text "Your spoken reply here" --out outbox/reply.mp3
+```
+
+This writes an MP3 file to `outbox/` which Mercury automatically attaches to your reply. Do **not** create `.txt` files or use misleading names — chat apps decide how to render attachments from the file extension and MIME type.
+
+Optional flags:
+
+- `--language` — `auto` (default), `he-IL`, or `en-US`. `auto` picks Hebrew if the text contains Hebrew script.
+- `--provider` — `google`, `azure`, or `auto` (host default).
+
+Requires the caller to have **`tts.synthesize`** permission (admins have it by default).
+
+### Telegram / WhatsApp delivery
+
+**Telegram** uses `sendAudio` for MP3 (in-chat player) and `sendVoice` for OGG voice notes. **WhatsApp** treats audio as a voice note when the filename matches **`voice-*.ogg`** (case-insensitive); otherwise it sends as normal audio (`ptt: false`).
+
+## Automatic mode (optional)
+
+| Setting | Behavior |
+|--------|----------|
+| **`voice-synth.mode=on_demand`** (default) | TTS runs only when you call `mrctl tts synthesize`. |
+| **`voice-synth.mode=auto`** | The host attaches a TTS MP3 to every assistant reply automatically. |
+
+Set with `mrctl config set voice-synth.mode on_demand` or `auto`.