pi-braid-telegram 0.0.0-stage → 0.1.4

package/src/lib/poller-lock.ts

@@ -0,0 +1,127 @@
+/**
+ * Machine-wide poller ownership lock.
+ *
+ * Telegram's getUpdates is a per-bot singleton: only one consumer may long-
+ * poll at a time. A module-local flag cannot provide this guarantee — it is
+ * per-process state, so two pi processes could each "own" the poller and
+ * 409-fight over the stream. This lock file is the machine-wide half: every
+ * start path acquires it first and refuses while a LIVE foreign pid holds
+ * it; a stale lock (dead pid, corrupt, or unreadable file) is taken over
+ * silently. A crashed holder therefore never locks the channel out, and a
+ * same-pid re-acquire (session reload cycles) always succeeds.
+ */
+
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { braidDir } from "./state-paths.js";
+
+/** Default lock location: beside the other braid-owned telegram state
+ *  (~/.pi/agent/braid, BRAID_HOME-overridable). Null when no absolute braid
+ *  root resolves: the poller refuses to start rather than lock beside the cwd. */
+export function defaultPollerLockPath(): string | null {
+  const root = braidDir();
+  return root === null ? null : join(root, "telegram-poller.lock");
+}
+
+/** Who holds the lock: the pid is the liveness key; startedAt/role/startedBy
+ *  make a refusal message name the holder. */
+export interface PollerLockInfo {
+  pid: number;
+  startedAt: number;
+  role?: string;
+  startedBy?: string;
+}
+
+export type AcquirePollerLockResult =
+  | { ok: true; tookOver: boolean }
+  | { ok: false; holder: PollerLockInfo };
+
+/** Read the lock file; absent/corrupt/unreadable reads as "no holder". */
+export function readPollerLock(path: string): PollerLockInfo | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as PollerLockInfo;
+    if (Number.isFinite(parsed?.pid)) return parsed;
+  } catch {
+    // fall through to undefined
+  }
+  return undefined;
+}
+
+/**
+ * Live-pid probe. Signal-0 errors with EPERM when the pid exists but is not
+ * ours to signal (still alive); ESRCH means the pid is gone.
+ */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+// Best-effort release at process exit: the exit hook removes the lock this
+// process last acquired. A hook that never runs (kill -9, crash) leaves the
+// file behind — harmless, because the next acquirer sees a dead pid and
+// takes the lock over.
+let exitHookInstalled = false;
+let heldLockPath: string | undefined;
+
+function installExitRelease(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on("exit", () => {
+    if (!heldLockPath) return;
+    try {
+      unlinkSync(heldLockPath);
+    } catch {
+      // best effort — the live-pid check covers a surviving file
+    }
+  });
+}
+
+/**
+ * Take the lock. A live FOREIGN holder refuses (the caller reports it); our
+ * own pid, a dead pid, or an unreadable file is taken over silently.
+ */
+export function acquirePollerLock(
+  path: string,
+  info: PollerLockInfo,
+  pidAlive: (pid: number) => boolean = isPidAlive,
+): AcquirePollerLockResult {
+  const existing = readPollerLock(path);
+  if (existing && existing.pid !== info.pid && pidAlive(existing.pid)) {
+    return { ok: false, holder: existing };
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(info));
+  heldLockPath = path;
+  installExitRelease();
+  return { ok: true, tookOver: existing !== undefined };
+}
+
+/**
+ * Release the lock — only when this process holds it; a foreign lock is
+ * never touched. Best-effort: reports whether the file was removed.
+ */
+export function releasePollerLock(path: string): boolean {
+  const existing = readPollerLock(path);
+  if (!existing || existing.pid !== process.pid) return false;
+  try {
+    unlinkSync(path);
+  } catch {
+    // already gone — treat as released
+  }
+  if (heldLockPath === path) heldLockPath = undefined;
+  return true;
+}
+
+/** Human-readable holder description for refusal messages. */
+export function describeLockHolder(holder: PollerLockInfo): string {
+  const since = Number.isFinite(holder.startedAt)
+    ? new Date(holder.startedAt).toISOString()
+    : "unknown time";
+  const role = holder.role ?? "unknown role";
+  const by = holder.startedBy ? `, started by ${holder.startedBy}` : "";
+  return `pid ${holder.pid} since ${since} (${role}${by})`;
+}

package/src/lib/session-role.ts

@@ -0,0 +1,32 @@
+/**
+ * Session role marker: which seat this pi session occupies in the braid
+ * topology. The orchestrator seat exports BRAID_SESSION_ROLE=worker into a
+ * worker's pane before pi starts; the telegram extension reads it at
+ * registration time and keeps the poller-ownership surfaces seat-only —
+ * Telegram's getUpdates is a per-bot singleton the orchestrator seat owns,
+ * so a worker session never registers the poller control or the pull-inbox
+ * tool and never starts the poller (telegram_send stays available).
+ */
+
+export const ENV_SESSION_ROLE = "BRAID_SESSION_ROLE";
+
+export type SessionRole = "seat" | "worker";
+
+/**
+ * Resolve the role from the given env (defaults to the process env). Only
+ * the exact value "worker" selects the worker role; unset, "seat", or any
+ * other value keeps the seat default, so deployments without the marker are
+ * unchanged.
+ */
+export function resolveSessionRole(
+  env: Record<string, string | undefined> = process.env,
+): SessionRole {
+  return env[ENV_SESSION_ROLE]?.trim().toLowerCase() === "worker"
+    ? "worker"
+    : "seat";
+}
+
+/** Worker-role predicate the extension factory gates on. */
+export function isWorkerRole(): boolean {
+  return resolveSessionRole() === "worker";
+}

package/src/lib/state-paths.ts

@@ -0,0 +1,164 @@
+/**
+ * Canonical state locations for the Telegram extension.
+ *
+ * Contract: braid-owned state lives under the braid home
+ * (~/.pi/agent/braid, overridable per call via BRAID_HOME), never under the
+ * session's working directory — a cwd-relative state file pollutes every
+ * project a session runs in (and forks one offset state per cwd).
+ * Explicit BRAID_TG_STATE_FILE / BRAID_TG_LIVE_UPDATE_STATE_FILE overrides
+ * still win at the call sites.
+ *
+ * Downloaded media and the inline-keyboard pause state moved from pi's agent
+ * directory into `<braidDir>/telegram/`. Both are read-compatible with their
+ * pre-move location: a read falls back to the old copy when the new one is
+ * absent (`resolveMediaReadPath`, `legacyPauseStateFile`), a write never
+ * touches it.
+ *
+ * Refusal contract: `braidDir()` returns null when no absolute root can be
+ * derived - BRAID_HOME is unset and `os.homedir()` does not resolve an
+ * absolute path (a relative or blank HOME would otherwise put the whole tree
+ * beside the cwd), or BRAID_HOME is set to a path that is not absolute (a
+ * relative override resolves against whatever cwd the process has, which is
+ * the same hazard). Every derived accessor returns null with it; callers
+ * refuse instead of writing somewhere unowned, and `warnUnderivableRoot`
+ * reports the refusal once per process through the extension's TUI-safe log
+ * sink (never console.*).
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+
+/**
+ * Braid home root; BRAID_HOME wins. Read on every call so tests can pin the
+ * whole tree into a tmpdir (mirrors pi-braid core's braidDir()). Null when no
+ * absolute root can be derived: see the refusal contract above.
+ */
+export function braidDir(): string | null {
+  const override = process.env.BRAID_HOME;
+  if (override && override.trim()) {
+    if (!path.isAbsolute(override)) return null;
+    return path.resolve(override);
+  }
+  let home: string;
+  try {
+    home = os.homedir();
+  } catch {
+    return null;
+  }
+  if (!home || !path.isAbsolute(home)) return null;
+  return path.join(home, ".pi", "agent", "braid");
+}
+
+/** Warn sink for a refused default path. The extension factory binds it to
+ *  the TUI-safe log; unset it is silent, exactly like log() itself. */
+let refusalSink: ((message: string) => void) | undefined;
+
+/** Bind (or clear) the sink a path refusal is reported through. */
+export function setPathRefusalSink(
+  sink: ((message: string) => void) | undefined,
+): void {
+  refusalSink = sink;
+}
+
+let warnedRefusal = false;
+
+/**
+ * Report one refused default path, once per process: a request loop must not
+ * repeat the line, and the caller still refuses. Silent with no sink bound
+ * (headless/print runs), so the TUI input line never sees it.
+ */
+export function warnUnderivableRoot(what: string): void {
+  if (warnedRefusal) return;
+  warnedRefusal = true;
+  refusalSink?.(
+    `${what}: BRAID_HOME is unset and no absolute home resolves, so braid's ` +
+      `state directory cannot be derived without writing beside the cwd. ` +
+      `Set BRAID_HOME (or HOME) to an absolute directory.`,
+  );
+}
+
+/** Telegram state dir under the braid root: media, pause state, future
+ *  sinks. The offset/live-update files predate it and stay at the root. */
+export function telegramStateDir(): string | null {
+  const root = braidDir();
+  return root === null ? null : path.join(root, "telegram");
+}
+
+/** Default inbound offset/lock state file. */
+export function defaultStateFilePath(): string | null {
+  const root = braidDir();
+  return root === null ? null : path.join(root, "telegram-state.json");
+}
+
+/** Default live-update tracker state file (beside the offset state). */
+export function defaultLiveUpdateFilePath(): string | null {
+  const root = braidDir();
+  return root === null ? null : path.join(root, "telegram-live-update.json");
+}
+
+/** Media dir for downloaded photo/voice/document bytes. */
+export function defaultMediaDir(): string | null {
+  const dir = telegramStateDir();
+  return dir === null ? null : path.join(dir, "media");
+}
+
+/**
+ * Pre-move media dir directly under pi's agent directory. Read-only fallback
+ * for files recorded before the relocation; never a write target. Null when
+ * no absolute home resolves (a relative fallback would read the cwd).
+ *
+ * This accessor and `resolveMediaReadPath` ship with no production caller:
+ * they are the documented read seam for pre-move media, kept for the
+ * compatibility contract and exercised by the package's tests.
+ */
+export function legacyMediaDir(): string | null {
+  let home: string;
+  try {
+    home = os.homedir();
+  } catch {
+    return null;
+  }
+  if (!home || !path.isAbsolute(home)) return null;
+  return path.join(home, ".pi", "agent", "telegram-media");
+}
+
+/**
+ * Read-side resolution for one stored media file: the braid-root copy when it
+ * exists, else the pre-move copy of the same name when that exists, else the
+ * current-root path (so a caller reports the miss against the write target).
+ * Writes always go to `defaultMediaDir()`. Null when neither root resolves.
+ */
+export function resolveMediaReadPath(fileName: string): string | null {
+  const current = path.isAbsolute(fileName)
+    ? fileName
+    : (() => {
+        const dir = defaultMediaDir();
+        return dir === null ? null : path.join(dir, fileName);
+      })();
+  if (current !== null && existsSync(current)) return current;
+  const legacyDir = legacyMediaDir();
+  const legacy =
+    legacyDir === null ? null : path.join(legacyDir, path.basename(fileName));
+  if (legacy !== null && existsSync(legacy)) return legacy;
+  return current;
+}
+
+/** Pause-state file under the braid root (the write target). */
+export function defaultPauseStateFile(): string | null {
+  const dir = telegramStateDir();
+  return dir === null ? null : path.join(dir, "pause-state.json");
+}
+
+/** Pre-move pause-state file directly under pi's agent directory. Read-only
+ *  fallback; never a write target. Null when no absolute home resolves. */
+export function legacyPauseStateFile(): string | null {
+  let home: string;
+  try {
+    home = os.homedir();
+  } catch {
+    return null;
+  }
+  if (!home || !path.isAbsolute(home)) return null;
+  return path.join(home, ".pi", "agent", "telegram-pause-state.json");
+}

package/src/lib/stt-keys.ts

@@ -0,0 +1,211 @@
+/**
+ * stt-keys.ts — the STT key pool: candidate resolution, failover memory,
+ * and runtime counters for voice-transcription reliability.
+ *
+ * Resolution order (first hit wins, deduped by key value):
+ *   1. explicit  — the caller-resolved BRAID_TG_STT_API_KEY (alias included)
+ *   2. list      — BRAID_TG_STT_KEYS, comma/whitespace separated
+ *   3. keyring   — macOS `security find-generic-password -s <service> -w`
+ *                  (darwin-only; absent/failed item tolerated silently)
+ *   4. env       — vars matching /^AGENT_ZERO_API_KEY(_[A-Z0-9]+)?$/ in
+ *                  lexicographic order (deterministic across runs)
+ *
+ * Only candidate INDEX and SOURCE KIND ever leave this module — never key
+ * material. The failure line and counters name `key N/source`, not the key.
+ */
+
+/** Where a candidate came from (logged/counted; never the key itself). */
+export type SttKeySource = "explicit" | "list" | "keyring" | "env";
+
+/** One key candidate: the pool entry transcribe failover advances through. */
+export interface SttKeyCandidate {
+  /** The key material (consumer-internal only). */
+  key: string;
+  /** Source kind (observability-safe: this is what gets logged). */
+  source: SttKeySource;
+  /** Position in the resolved pool (stable for the process lifetime). */
+  index: number;
+}
+
+/** Injectable keyring exec: returns null/throws when the item is absent. */
+export type SttKeyringExec = (
+  cmd: string,
+  args: string[],
+) => Promise<{ stdout: string } | null>;
+
+/** Input for resolveSttKeyCandidates (pure + injectable, no real exec in tests). */
+export interface ResolveSttKeyCandidatesInput {
+  /** The caller-resolved explicit key (BRAID_TG_STT_API_KEY incl. alias). */
+  explicit?: string;
+  /** Raw env record (defaults to process.env). */
+  env?: Record<string, string | undefined>;
+  /** Keyring exec seam (defaults to the real `security` invocation). */
+  exec?: SttKeyringExec;
+  /** Platform override (default process.platform; keyring is darwin-only). */
+  platform?: string;
+  /** Keyring service name (default BRAID_TG_STT_KEYRING_SERVICE or "braid-stt"). */
+  keyringService?: string;
+  /** Include the AGENT_ZERO_API_KEY* env candidates (default true). The agent-zero
+   *  key family belongs to the Venice chat endpoint; enabling them against
+   *  any other provider base URL would leak the key across providers, so
+   *  transcriptions-mode callers turn this off. */
+  includeAgentZeroEnv?: boolean;
+}
+
+/** Default macOS keyring service for the STT key. */
+export const DEFAULT_STT_KEYRING_SERVICE = "braid-stt";
+
+/** agent-zero key env-var pattern: base name plus optional _SUFFIX (A-Z0-9). */
+const AGENT_ZERO_KEY_PATTERN = /^AGENT_ZERO_API_KEY(_[A-Z0-9]+)?$/;
+
+function defaultKeyringExec(): SttKeyringExec {
+  return async (cmd, args) => {
+    const { execFile } = await import("node:child_process");
+    return await new Promise((resolveExec) => {
+      execFile(cmd, args, { timeout: 3000 }, (error, stdout) => {
+        if (error)
+          resolveExec(null); // absent item / lock — tolerated
+        else resolveExec({ stdout: String(stdout) });
+      });
+    });
+  };
+}
+
+/**
+ * Resolve the STT key candidate pool in the documented order. Absent sources
+ * contribute nothing; duplicate key values keep only their FIRST position.
+ * Never throws — a failed keyring probe just yields no candidate.
+ */
+export async function resolveSttKeyCandidates(
+  input: ResolveSttKeyCandidatesInput = {},
+): Promise<SttKeyCandidate[]> {
+  const envRecord =
+    input.env ?? (process.env as Record<string, string | undefined>);
+  const platform = input.platform ?? process.platform;
+  const out: SttKeyCandidate[] = [];
+  const seen = new Set<string>();
+  const push = (key: string | undefined, source: SttKeySource): void => {
+    const trimmed = key?.trim();
+    if (!trimmed || seen.has(trimmed)) return;
+    seen.add(trimmed);
+    out.push({ key: trimmed, source, index: out.length });
+  };
+
+  push(input.explicit, "explicit");
+
+  const list = envRecord["BRAID_TG_STT_KEYS"];
+  if (list) {
+    for (const part of list.split(/[,\s]+/)) push(part, "list");
+  }
+
+  if (platform === "darwin") {
+    const service =
+      input.keyringService ??
+      envRecord["BRAID_TG_STT_KEYRING_SERVICE"] ??
+      DEFAULT_STT_KEYRING_SERVICE;
+    try {
+      const exec = input.exec ?? defaultKeyringExec();
+      const result = await exec("security", [
+        "find-generic-password",
+        "-s",
+        service,
+        "-w",
+      ]);
+      push(result?.stdout, "keyring");
+    } catch {
+      // keyring unavailable — tolerated, pool continues with env candidates
+    }
+  }
+
+  if (input.includeAgentZeroEnv ?? true) {
+    for (const name of Object.keys(envRecord)
+      .filter((n) => AGENT_ZERO_KEY_PATTERN.test(n))
+      .sort()) {
+      push(envRecord[name], "env");
+    }
+  }
+
+  return out;
+}
+
+// Process-lifetime state: winner memory + counters
+
+let preferred: SttKeyCandidate | null = null;
+let counterState = freshCounters();
+
+function freshCounters(): SttCounters {
+  return {
+    attempts: 0,
+    successesByCandidateIndex: {},
+    normalizationsApplied: 0,
+    failuresByClass: {},
+    transportRetries: 0,
+    transportRetrySuccesses: 0,
+  };
+}
+
+/** STT runtime counters (observability snapshot for callers/tests). */
+export interface SttCounters {
+  /** Transcription requests issued (each candidate hit counts). */
+  attempts: number;
+  /** Successful transcriptions keyed by winning candidate index. */
+  successesByCandidateIndex: Record<number, number>;
+  /** Normalization rounds whose output was actually retried with. */
+  normalizationsApplied: number;
+  /** Final failures keyed by error class (auth/quota/rate/other/empty/no-key). */
+  failuresByClass: Record<string, number>;
+  /** Transport-class retries issued (a thrown request retried once, per round). */
+  transportRetries: number;
+  /** Transport-class retries whose retry then returned a transcript. */
+  transportRetrySuccesses: number;
+}
+
+/** Remember the winning candidate so later calls try it FIRST. */
+export function rememberSttKeyWinner(candidate: SttKeyCandidate): void {
+  preferred = candidate;
+}
+
+/** The last remembered winner (null until the first success). */
+export function getPreferredSttKey(): SttKeyCandidate | null {
+  return preferred;
+}
+
+/** Current counters snapshot (fresh objects — safe to hand to tests/logs). */
+export function getSttCounters(): SttCounters {
+  return {
+    ...counterState,
+    successesByCandidateIndex: { ...counterState.successesByCandidateIndex },
+    failuresByClass: { ...counterState.failuresByClass },
+  };
+}
+
+/** Test seam: clear winner memory and counters. */
+export function resetSttState(): void {
+  preferred = null;
+  counterState = freshCounters();
+}
+
+/** @internal counter mutation helpers (used by transcribe.ts failover). */
+export function countSttAttempt(): void {
+  counterState.attempts += 1;
+}
+export function countSttSuccess(candidate: SttKeyCandidate): void {
+  const map = counterState.successesByCandidateIndex;
+  map[candidate.index] = (map[candidate.index] ?? 0) + 1;
+}
+export function countSttNormalizationApplied(): void {
+  counterState.normalizationsApplied += 1;
+}
+export function countSttFailure(errorClass: string): void {
+  const map = counterState.failuresByClass;
+  map[errorClass] = (map[errorClass] ?? 0) + 1;
+}
+/** @internal A transport-class retry was issued (counted apart from attempts,
+ *  which counts key-pool hits). */
+export function countSttTransportRetry(): void {
+  counterState.transportRetries += 1;
+}
+/** @internal A transport-class retry then transcribed successfully. */
+export function countSttTransportRetrySuccess(): void {
+  counterState.transportRetrySuccesses += 1;
+}