mercury-agent 0.4.5

package/src/storage/memory.ts

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const PI_SUBDIRS = [".pi", ".pi/extensions", ".pi/skills", ".pi/prompts"];
+
+/**
+ * Ensure a pi resource directory exists with standard structure.
+ * Used for global, main, and shared groups root.
+ */
+export function ensurePiResourceDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+  for (const sub of PI_SUBDIRS) {
+    fs.mkdirSync(path.join(dir, sub), { recursive: true });
+  }
+
+  // Create empty AGENTS.md so pi discovers and loads from this directory
+  const agentsPath = path.join(dir, "AGENTS.md");
+  if (!fs.existsSync(agentsPath)) {
+    fs.writeFileSync(agentsPath, "", "utf8");
+  }
+}
+
+/**
+ * Ensure a per-space workspace exists with the pi resource structure.
+ * Vault structure is handled by extensions via workspace_init hooks.
+ */
+export function ensureSpaceWorkspace(
+  spacesDir: string,
+  spaceId: string,
+): string {
+  const dir = path.join(spacesDir, spaceId);
+
+  ensurePiResourceDir(dir);
+
+  return dir;
+}
+
+/**
+ * Remove a space's workspace directory from disk.
+ * Safe to call if the directory doesn't exist (no-op).
+ */
+export function removeSpaceWorkspace(spacesDir: string, spaceId: string): void {
+  const dir = path.join(spacesDir, spaceId);
+  fs.rmSync(dir, { recursive: true, force: true });
+}

package/src/storage/pi-auth.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  getOAuthApiKey,
+  type OAuthCredentials,
+  type OAuthProviderId,
+} from "@mariozechner/pi-ai/oauth";
+import { logger } from "../logger.js";
+
+type AuthEntry =
+  | ({ type: "oauth" } & OAuthCredentials)
+  | { type: "api_key"; key: string }
+  | Record<string, unknown>;
+
+type AuthFile = Record<string, AuthEntry>;
+
+function readAuthFile(authPath: string): AuthFile {
+  if (!fs.existsSync(authPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(authPath, "utf8")) as AuthFile;
+  } catch (err) {
+    logger.warn(
+      `pi-auth: auth file at ${authPath} is malformed, ignoring`,
+      err instanceof Error ? err : undefined,
+    );
+    return {};
+  }
+}
+
+function writeAuthFile(authPath: string, auth: AuthFile): void {
+  fs.mkdirSync(path.dirname(authPath), { recursive: true });
+  fs.writeFileSync(authPath, JSON.stringify(auth, null, 2), "utf8");
+  fs.chmodSync(authPath, 0o600);
+}
+
+export async function getApiKeyFromPiAuthFile(options: {
+  provider: string;
+  authPath: string;
+}): Promise<string | undefined> {
+  if (
+    process.env.MERCURY_ANTHROPIC_API_KEY ||
+    process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN
+  ) {
+    return undefined;
+  }
+
+  if (options.provider !== "anthropic") {
+    return undefined;
+  }
+
+  const authPath = options.authPath;
+  const auth = readAuthFile(authPath);
+
+  const entry = auth.anthropic;
+  if (!entry || typeof entry !== "object" || entry.type !== "oauth") {
+    return undefined;
+  }
+
+  const access = typeof entry.access === "string" ? entry.access : undefined;
+  const refresh = typeof entry.refresh === "string" ? entry.refresh : undefined;
+  const expires = typeof entry.expires === "number" ? entry.expires : undefined;
+  if (!access || !refresh || typeof expires !== "number") return undefined;
+
+  try {
+    const result = await getOAuthApiKey("anthropic" satisfies OAuthProviderId, {
+      anthropic: {
+        access,
+        refresh,
+        expires,
+      },
+    });
+
+    if (!result) return undefined;
+
+    const nextAuth = {
+      ...auth,
+      anthropic: {
+        type: "oauth" as const,
+        ...result.newCredentials,
+      },
+    };
+
+    writeAuthFile(authPath, nextAuth);
+    logger.debug("Loaded anthropic oauth token from pi auth.json", {
+      authPath,
+    });
+    return result.apiKey;
+  } catch (error) {
+    logger.warn(
+      "Failed to load anthropic oauth token from pi auth.json",
+      error instanceof Error ? error : undefined,
+    );
+    return undefined;
+  }
+}

package/src/text/markdown.ts

@@ -0,0 +1,117 @@
+// Outbound markdown normalization for chat platforms (WhatsApp + Telegram plain
+// text). WhatsApp and Telegram-without-rich-formatting render only a restricted
+// lightweight markup — GitHub-flavored markdown tables, horizontal rules, and
+// `**double-star bold**` all leak through as literal characters and look broken
+// on mobile. The space `AGENTS.md` bans these in prose, but a prose rule relies
+// on the model complying; this turns the ban into a deterministic send-side gate
+// (same pattern as `applyRtlDirection`). Apply BEFORE `applyRtlDirection` — this
+// rewrites line structure (tables expand to several bullet lines, rules collapse
+// to blank lines), and the RLM prefixing must run on the final lines.
+//
+// Send-side only. Do NOT call from inbound parsing, storage, the console UI, or
+// the Telegram rich-HTML path (`markdownToTelegramHtml` owns formatting there;
+// normalizing `**`→`*` before it would turn bold into italic).
+
+// A horizontal rule: a line of only `-`, `*`, or `_` (3+), optionally space-
+// separated (`---`, `***`, `___`, `- - -`). Table separator rows contain `|` so
+// they never match here.
+const HR_LINE = /^\s*(?:-\s*){3,}$|^\s*(?:\*\s*){3,}$|^\s*(?:_\s*){3,}$/;
+
+// A markdown table separator row: only `|`, `-`, `:`, and whitespace, and it must
+// contain both a pipe and a dash (e.g. `|---|---|`, `| :-- | --: |`).
+const TABLE_SEPARATOR = /^\s*\|?[\s:|-]*-[\s:|-]*\|[\s:|-]*$/;
+
+// A line that participates in a table: contains at least one pipe.
+const TABLE_ROW = /\|/;
+
+const FENCE = /^\s*```/;
+
+/** Split a markdown table row into trimmed, non-empty cell strings. */
+function tableCells(line: string): string[] {
+  return line
+    .split("|")
+    .map((c) => c.trim())
+    .filter((c) => c.length > 0);
+}
+
+// Normalize markdown bold/bold-italic delimiters to WhatsApp's single-asterisk
+// `*bold*`. Matches runs of 2–3 markers (`**x**`, `***x***`, `__x__`, `___x___`)
+// so triple-star bold-italic collapses cleanly rather than leaving a stray `**`.
+// The capture forbids the marker char so a match can't span across a separate
+// emphasis pair. Single `*x*` / `_x_` (WhatsApp bold / italic) are left intact.
+// Note: a `__identifier__` in plain prose (outside a code fence) is also rewritten
+// — an acceptable trade-off, as chat replies rarely contain bare code tokens.
+function normalizeBold(line: string): string {
+  return line
+    .replace(/\*{2,3}([^*\n]+?)\*{2,3}/g, "*$1*")
+    .replace(/_{2,3}([^_\n]+?)_{2,3}/g, "*$1*");
+}
+
+/**
+ * Rewrite markdown that does not render on WhatsApp / plain Telegram into the
+ * supported lightweight markup:
+ * - GFM tables → `•` bullet lines (one per row, cells joined with ` — `)
+ * - horizontal rules (`---` / `***` / `___`) → a blank line
+ * - `**bold**` / `__bold__` → `*bold*`
+ *
+ * Fenced code blocks (```` ``` ````) are passed through untouched — WhatsApp
+ * renders them as monospace, and their contents are not markdown.
+ *
+ * No-op on empty input.
+ */
+export function normalizeChatMarkdown(text: string): string {
+  if (!text) return text;
+
+  const lines = text.split("\n");
+  const out: string[] = [];
+  let inFence = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+
+    // Table block: a row with a pipe immediately followed by a separator row.
+    // Requiring the separator row keeps us from mangling prose/code that merely
+    // contains a `|` (GFM requires a separator row for a real table).
+    if (
+      TABLE_ROW.test(line) &&
+      i + 1 < lines.length &&
+      TABLE_SEPARATOR.test(lines[i + 1])
+    ) {
+      // Header row → bullet.
+      const header = tableCells(line);
+      if (header.length > 0) out.push(`• ${header.join(" — ")}`);
+      // Skip the separator row, then consume contiguous data rows.
+      let j = i + 2;
+      while (
+        j < lines.length &&
+        TABLE_ROW.test(lines[j]) &&
+        !TABLE_SEPARATOR.test(lines[j])
+      ) {
+        const cells = tableCells(lines[j]);
+        if (cells.length > 0) out.push(`• ${cells.join(" — ")}`);
+        j++;
+      }
+      i = j - 1;
+      continue;
+    }
+
+    if (HR_LINE.test(line)) {
+      out.push("");
+      continue;
+    }
+
+    out.push(normalizeBold(line));
+  }
+
+  return out.join("\n");
+}

package/src/text/rtl.ts

@@ -0,0 +1,38 @@
+// U+200F RIGHT-TO-LEFT MARK. Invisible bidi control that forces RTL paragraph
+// direction in WhatsApp, Telegram, and any client implementing the Unicode Bidi
+// Algorithm. Per-line application matches the empirically-proven n8n/Telegram
+// pattern: each newline-separated line is treated as its own bidi paragraph.
+const RLM = "‏";
+
+// `\p{Bidi_Class=R/AL}` is NOT supported by V8 (Bun 1.3.10 throws SyntaxError at
+// parse time). `\p{Script=...}` is supported and covers every commonly-used RTL
+// script including all of Arabic's extension/supplement/presentation-form blocks
+// via the Unicode Script property.
+const HAS_RTL =
+  /[\p{Script=Hebrew}\p{Script=Arabic}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}\p{Script=Mandaic}\p{Script=Samaritan}]/u;
+
+// Strip leading RLM (U+200F), LRE (U+202A), and RLE (U+202B). The existing
+// `whatsapp-formatting` skill prepends RLE; leaving it in place under our RLM
+// would nest two bidi controls and behave unpredictably on older Android clients.
+const LEADING_BIDI_CTRL = /^[‏‪‫]+/;
+
+/**
+ * Force correct RTL paragraph alignment for outbound chat messages.
+ *
+ * If `text` contains any RTL strong character (Hebrew, Arabic and all its blocks,
+ * Syriac, Thaana, N'Ko, Mandaic, Samaritan), prefix every line with exactly one
+ * U+200F. Idempotent: any pre-existing leading run of bidi controls on a line is
+ * stripped first.
+ *
+ * No-op on purely LTR input — returned byte-identical.
+ *
+ * Send-side only. Do NOT call from inbound message parsing, storage, or any
+ * console UI render path.
+ */
+export function applyRtlDirection(text: string): string {
+  if (!text || !HAS_RTL.test(text)) return text;
+  return text
+    .split("\n")
+    .map((line) => RLM + line.replace(LEADING_BIDI_CTRL, ""))
+    .join("\n");
+}

package/src/tradestation/host-api.ts

@@ -0,0 +1,77 @@
+/**
+ * Host-side TradeStation REST v3 calls using tokens in extension_state.
+ * Used by core API routes; keeps order placement off the agent container.
+ */
+
+import type { Db } from "../storage/db.js";
+
+export const TRADESTATION_EXT = "tradestation";
+
+export function tradeStationApiBase(): string {
+  const raw = process.env.MERCURY_TS_API_BASE?.trim();
+  if (raw) return raw.replace(/\/$/, "");
+  return "https://api.tradestation.com/v3";
+}
+
+export type TradeStationFetch = typeof fetch;
+
+export async function tradeStationAuthorizedJson(
+  db: Db,
+  init: {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: unknown;
+  },
+  fetchImpl: TradeStationFetch = fetch,
+): Promise<{ ok: boolean; status: number; data: unknown }> {
+  const token = db.getExtState(TRADESTATION_EXT, "access_token");
+  const authErr = db.getExtState(TRADESTATION_EXT, "auth_error");
+  if (authErr) {
+    return {
+      ok: false,
+      status: 401,
+      data: { error: "TradeStation auth error", code: authErr },
+    };
+  }
+  if (!token) {
+    return {
+      ok: false,
+      status: 401,
+      data: {
+        error:
+          "TradeStation access token missing — configure OAuth on the Mercury host",
+      },
+    };
+  }
+
+  const base = tradeStationApiBase();
+  const url = new URL(init.path.replace(/^\//, ""), `${base}/`);
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/json",
+  };
+  let body: string | undefined;
+  if (init.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(init.body);
+  }
+
+  const res = await fetchImpl(url.toString(), {
+    method: init.method,
+    headers,
+    body,
+  });
+  const text = await res.text();
+  let data: unknown;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { raw: text };
+  }
+  return { ok: res.ok, status: res.status, data };
+}
+
+/** TradeStation SIM accounts use an AccountID prefix convention (see TS docs). */
+export function isLikelySimAccount(accountId: string): boolean {
+  return /^SIM/i.test(accountId.trim());
+}

package/src/tradestation/pending-orders.ts

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import type { Db } from "../storage/db.js";
+import { TRADESTATION_EXT } from "./host-api.js";
+
+export const PENDING_ORDER_PREFIX = "pending_order:";
+export const PENDING_ORDER_TTL_MS = 15 * 60 * 1000;
+
+/** Exact JSON body sent to TradeStation confirm/place. */
+export type TradeStationOrderRequestJson = Record<string, unknown>;
+
+export interface PendingOrderRecord {
+  v: 1;
+  spaceId: string;
+  callerId: string;
+  createdAt: number;
+  expiresAt: number;
+  orderRequest: TradeStationOrderRequestJson;
+  /** Short text for user-facing summary */
+  summary: string;
+}
+
+export function cleanupExpiredTradestationPending(db: Db): void {
+  const rows = db.listExtState(TRADESTATION_EXT);
+  const now = Date.now();
+  for (const { key, value } of rows) {
+    if (!key.startsWith(PENDING_ORDER_PREFIX)) continue;
+    try {
+      const rec = JSON.parse(value) as PendingOrderRecord;
+      if (rec.expiresAt < now) {
+        db.deleteExtState(TRADESTATION_EXT, key);
+      }
+    } catch {
+      db.deleteExtState(TRADESTATION_EXT, key);
+    }
+  }
+}
+
+export function createPendingOrderId(): string {
+  return randomUUID();
+}
+
+export function pendingOrderKey(id: string): string {
+  return `${PENDING_ORDER_PREFIX}${id}`;
+}
+
+export function savePendingOrder(
+  db: Db,
+  id: string,
+  record: PendingOrderRecord,
+): void {
+  db.setExtState(TRADESTATION_EXT, pendingOrderKey(id), JSON.stringify(record));
+}
+
+export function loadPendingOrder(
+  db: Db,
+  id: string,
+): PendingOrderRecord | null {
+  const raw = db.getExtState(TRADESTATION_EXT, pendingOrderKey(id));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as PendingOrderRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function deletePendingOrder(db: Db, id: string): void {
+  db.deleteExtState(TRADESTATION_EXT, pendingOrderKey(id));
+}

package/src/tts/azure.ts

@@ -0,0 +1,52 @@
+import type { TtsLanguage } from "./language.js";
+
+const AZURE_VOICES: Record<TtsLanguage, string> = {
+  "he-IL": "he-IL-HilaNeural",
+  "en-US": "en-US-JennyNeural",
+};
+
+/** MP3 128 kbps mono 16 kHz — widely compatible for chat attachments. */
+const OUTPUT_FORMAT = "audio-16khz-128kbitrate-mono-mp3";
+
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export async function synthesizeAzure(opts: {
+  key: string;
+  region: string;
+  text: string;
+  language: TtsLanguage;
+}): Promise<Buffer> {
+  const voiceName = AZURE_VOICES[opts.language];
+  const ssml = `<?xml version="1.0" encoding="UTF-8"?>
+<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="${opts.language}">
+  <voice name="${voiceName}">${escapeXml(opts.text)}</voice>
+</speak>`;
+
+  const url = `https://${opts.region.trim()}.tts.speech.microsoft.com/cognitiveservices/v1`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/ssml+xml",
+      "X-Microsoft-OutputFormat": OUTPUT_FORMAT,
+      "Ocp-Apim-Subscription-Key": opts.key.trim(),
+      "User-Agent": "mercury-agent-tts",
+    },
+    body: ssml,
+  });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => "");
+    throw new Error(
+      `Azure TTS HTTP ${res.status}: ${errText.slice(0, 500) || res.statusText}`,
+    );
+  }
+
+  return Buffer.from(await res.arrayBuffer());
+}

package/src/tts/google.ts

@@ -0,0 +1,128 @@
+import { createSign, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { TtsLanguage } from "./language.js";
+
+const GOOGLE_VOICES: Record<TtsLanguage, string> = {
+  "he-IL": "he-IL-Standard-A",
+  "en-US": "en-US-Neural2-C",
+};
+
+interface ServiceAccountJson {
+  client_email?: string;
+  private_key?: string;
+}
+
+function base64url(data: string | Buffer): string {
+  const buf = typeof data === "string" ? Buffer.from(data) : data;
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/u, "");
+}
+
+async function fetchGoogleAccessToken(credsPath: string): Promise<string> {
+  let raw: ServiceAccountJson;
+  try {
+    raw = JSON.parse(readFileSync(credsPath, "utf-8")) as ServiceAccountJson;
+  } catch (e) {
+    throw new Error(
+      `Invalid Google service account JSON: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+  const email = raw.client_email?.trim();
+  const privateKey = raw.private_key?.trim();
+  if (!email || !privateKey) {
+    throw new Error(
+      "Google service account JSON missing client_email or private_key",
+    );
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64url(
+    JSON.stringify({
+      iss: email,
+      scope: "https://www.googleapis.com/auth/cloud-platform",
+      aud: "https://oauth2.googleapis.com/token",
+      iat: now,
+      exp: now + 3600,
+      jti: base64url(randomBytes(16)),
+    }),
+  );
+  const signInput = `${header}.${payload}`;
+  const sign = createSign("RSA-SHA256");
+  sign.update(signInput);
+  sign.end();
+  const sig = base64url(sign.sign(privateKey));
+  const jwt = `${signInput}.${sig}`;
+
+  const tokenRes = await fetch("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: jwt,
+    }),
+  });
+
+  const tokenJson = (await tokenRes.json()) as {
+    access_token?: string;
+    error?: string;
+    error_description?: string;
+  };
+
+  if (!tokenRes.ok || !tokenJson.access_token) {
+    const msg =
+      tokenJson.error_description ||
+      tokenJson.error ||
+      `HTTP ${tokenRes.status}`;
+    throw new Error(`Google OAuth token failed: ${msg}`);
+  }
+
+  return tokenJson.access_token;
+}
+
+export async function synthesizeGoogle(opts: {
+  credentialsPath: string;
+  text: string;
+  language: TtsLanguage;
+}): Promise<Buffer> {
+  const accessToken = await fetchGoogleAccessToken(opts.credentialsPath);
+  const voiceName = GOOGLE_VOICES[opts.language];
+
+  const body = {
+    input: { text: opts.text },
+    voice: {
+      languageCode: opts.language,
+      name: voiceName,
+    },
+    audioConfig: {
+      audioEncoding: "MP3",
+    },
+  };
+
+  const res = await fetch(
+    "https://texttospeech.googleapis.com/v1/text:synthesize",
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    },
+  );
+
+  const data = (await res.json()) as {
+    audioContent?: string;
+    error?: { message?: string; code?: number };
+  };
+
+  if (!res.ok || !data.audioContent) {
+    const msg = data.error?.message || `HTTP ${res.status}`;
+    throw new Error(`Google TTS failed: ${msg}`);
+  }
+
+  return Buffer.from(data.audioContent, "base64");
+}

package/src/tts/index.ts

@@ -0,0 +1,8 @@
+export type { TtsLanguage, TtsLanguageInput } from "./language.js";
+export {
+  type MercuryTtsConfig,
+  synthesizeSpeech,
+  TtsConfigError,
+  type TtsSynthesizeOptions,
+  type TtsSynthesizeResult,
+} from "./synthesize.js";

package/src/tts/language.ts

@@ -0,0 +1,20 @@
+/** BCP-47 locales supported for default voices. */
+export type TtsLanguage = "he-IL" | "en-US";
+
+export type TtsLanguageInput = "auto" | TtsLanguage;
+
+const HEBREW_RE = /\p{Script=Hebrew}/u;
+
+/**
+ * Resolve `auto` using Hebrew script detection; otherwise pass through.
+ */
+export function resolveTtsLanguageFromText(
+  text: string,
+  input: TtsLanguageInput | undefined,
+): TtsLanguage {
+  const mode = input ?? "auto";
+  if (mode === "auto") {
+    return HEBREW_RE.test(text) ? "he-IL" : "en-US";
+  }
+  return mode;
+}