vellum 0.2.13 → 0.2.14

package/src/twitter/oauth-client.ts

@@ -0,0 +1,102 @@
+/**
+ * OAuth-backed Twitter API client.
+ *
+ * Uses stored OAuth2 Bearer tokens (via the token manager) to execute
+ * Twitter API v2 operations directly, without requiring a browser session.
+ * Currently supports post and reply; all other operations fall back to the
+ * browser-based CDP client.
+ */
+
+import { withValidToken } from '../security/token-manager.js';
+import { getSecureKey } from '../security/secure-keys.js';
+
+const TWITTER_API_BASE = 'https://api.x.com/2';
+const SERVICE = 'integration:twitter';
+
+/** Operations that the OAuth client can handle natively. */
+const SUPPORTED_OPERATIONS = new Set(['post', 'reply']);
+
+export interface OAuthPostResult {
+  tweetId: string;
+  text: string;
+  url?: string;
+}
+
+export interface OAuthOperationError {
+  message: string;
+  suggestFallback: boolean;
+  fallbackPath: 'browser';
+  operation: string;
+}
+
+export class UnsupportedOAuthOperationError extends Error {
+  public readonly suggestFallback = true;
+  public readonly fallbackPath = 'browser' as const;
+  public readonly operation: string;
+  constructor(operation: string) {
+    super(`The "${operation}" operation is not available via the OAuth API. Use the browser path instead.`);
+    this.name = 'UnsupportedOAuthOperationError';
+    this.operation = operation;
+  }
+}
+
+/**
+ * Post a tweet (or reply) using OAuth2 Bearer token authentication.
+ *
+ * The token manager handles refresh transparently — if the stored token
+ * is expired it will be refreshed before (or after a 401) calling the API.
+ */
+export async function oauthPostTweet(
+  text: string,
+  opts?: { inReplyToTweetId?: string },
+): Promise<OAuthPostResult> {
+  return withValidToken(SERVICE, async (token) => {
+    const body: Record<string, unknown> = { text };
+    if (opts?.inReplyToTweetId) {
+      body.reply = { in_reply_to_tweet_id: opts.inReplyToTweetId };
+    }
+
+    const res = await fetch(`${TWITTER_API_BASE}/tweets`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => '');
+      const err = new Error(
+        `Twitter API error (${res.status}): ${errorBody.slice(0, 500)}`,
+      );
+      // Attach status so the token manager's 401-retry logic can detect it.
+      (err as Error & { status: number }).status = res.status;
+      throw err;
+    }
+
+    const json = (await res.json()) as { data: { id: string; text: string } };
+    return {
+      tweetId: json.data.id,
+      text: json.data.text,
+    };
+  });
+}
+
+/**
+ * Check whether OAuth credentials are available for the Twitter integration.
+ * Returns true if an access token has been stored (the token manager will
+ * handle refresh if it's expired).
+ */
+export function oauthIsAvailable(): boolean {
+  return getSecureKey('credential:integration:twitter:access_token') !== undefined;
+}
+
+/**
+ * Check whether a given operation is supported via the OAuth API path.
+ * Only `post` and `reply` are currently supported; everything else
+ * (timeline, search, bookmarks, etc.) requires the browser path.
+ */
+export function oauthSupportsOperation(operation: string): boolean {
+  return SUPPORTED_OPERATIONS.has(operation);
+}

package/src/twitter/router.ts

@@ -0,0 +1,101 @@
+/**
+ * Strategy router for Twitter operations.
+ * Selects OAuth or browser path based on persisted preference and capability.
+ */
+
+import { loadRawConfig } from '../config/loader.js';
+import { oauthPostTweet, oauthIsAvailable, oauthSupportsOperation } from './oauth-client.js';
+import { postTweet as browserPostTweet, SessionExpiredError } from './client.js';
+import type { PostTweetResult } from './client.js';
+
+export type TwitterStrategy = 'oauth' | 'browser' | 'auto';
+
+export interface RoutedResult<T> {
+  result: T;
+  pathUsed: TwitterStrategy;
+}
+
+export interface RoutedError {
+  message: string;
+  pathUsed: TwitterStrategy;
+  suggestAlternative?: TwitterStrategy;
+  alternativeSetupHint?: string;
+}
+
+function getPreferredStrategy(): TwitterStrategy {
+  try {
+    const raw = loadRawConfig();
+    const strategy = raw.twitterOperationStrategy as string | undefined;
+    if (strategy === 'oauth' || strategy === 'browser') return strategy;
+  } catch { /* fall through */ }
+  return 'auto';
+}
+
+export async function routedPostTweet(
+  text: string,
+  opts?: { inReplyToTweetId?: string },
+): Promise<RoutedResult<PostTweetResult>> {
+  const strategy = getPreferredStrategy();
+  const operation = opts?.inReplyToTweetId ? 'reply' : 'post';
+
+  if (strategy === 'oauth') {
+    // User explicitly wants OAuth
+    if (!oauthIsAvailable()) {
+      throw Object.assign(new Error('OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy: `vellum x strategy set browser`.'), {
+        pathUsed: 'oauth' as const,
+        suggestAlternative: 'browser' as const,
+      });
+    }
+    const result = await oauthPostTweet(text, opts);
+    return { result: { tweetId: result.tweetId, text: result.text, url: result.url ?? `https://x.com/i/status/${result.tweetId}` }, pathUsed: 'oauth' };
+  }
+
+  if (strategy === 'browser') {
+    // User explicitly wants browser
+    try {
+      const result = await browserPostTweet(text, opts);
+      return { result, pathUsed: 'browser' };
+    } catch (err) {
+      if (err instanceof SessionExpiredError) {
+        throw Object.assign(err, {
+          pathUsed: 'browser' as const,
+          suggestAlternative: 'oauth' as const,
+        });
+      }
+      throw err;
+    }
+  }
+
+  // auto strategy: try OAuth first if available and supported, fallback to browser
+  let oauthError: Error | undefined;
+  if (oauthIsAvailable() && oauthSupportsOperation(operation)) {
+    try {
+      const result = await oauthPostTweet(text, opts);
+      return { result: { tweetId: result.tweetId, text: result.text, url: result.url ?? `https://x.com/i/status/${result.tweetId}` }, pathUsed: 'oauth' };
+    } catch (err) {
+      oauthError = err instanceof Error ? err : new Error(String(err));
+      // Fall through to browser
+    }
+  }
+
+  // Fallback to browser
+  try {
+    const result = await browserPostTweet(text, opts);
+    return { result, pathUsed: 'browser' };
+  } catch (err) {
+    if (err instanceof SessionExpiredError) {
+      throw Object.assign(err, {
+        pathUsed: 'auto' as const,
+        oauthError: oauthError?.message,
+      });
+    }
+    if (oauthError) {
+      const browserError = err instanceof Error ? err : new Error(String(err));
+      throw Object.assign(browserError, {
+        pathUsed: 'auto' as const,
+        oauthError: oauthError.message,
+      });
+    }
+    throw err;
+  }
+}

package/src/util/debounce.ts

@@ -0,0 +1,88 @@
+/**
+ * Single-key debouncer. Delays execution until no new calls arrive
+ * within the specified delay period.
+ */
+export class Debouncer {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly delayMs: number) {}
+
+  schedule(fn: () => void): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      fn();
+    }, this.delayMs);
+  }
+
+  cancel(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+/**
+ * Multi-key debouncer. Each key gets its own independent timer.
+ * Includes an optional entry limit with eviction of oldest non-protected entries.
+ */
+export class DebouncerMap {
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly defaultDelayMs: number;
+  private readonly maxEntries: number;
+  private readonly protectedKeyPrefix: string;
+
+  constructor(options: {
+    defaultDelayMs: number;
+    maxEntries?: number;
+    protectedKeyPrefix?: string;
+  }) {
+    this.defaultDelayMs = options.defaultDelayMs;
+    this.maxEntries = options.maxEntries ?? Infinity;
+    this.protectedKeyPrefix = options.protectedKeyPrefix ?? '';
+  }
+
+  schedule(key: string, fn: () => void, delayMs?: number): void {
+    const existing = this.timers.get(key);
+    if (existing) clearTimeout(existing);
+    const timer = setTimeout(() => {
+      this.timers.delete(key);
+      fn();
+    }, delayMs ?? this.defaultDelayMs);
+    this.timers.set(key, timer);
+    this.enforceLimit();
+  }
+
+  cancel(key: string): void {
+    const timer = this.timers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+  }
+
+  cancelAll(): void {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+  }
+
+  get size(): number {
+    return this.timers.size;
+  }
+
+  private enforceLimit(): void {
+    if (this.timers.size <= this.maxEntries) return;
+    const excess = this.timers.size - this.maxEntries;
+    let removed = 0;
+    for (const [key, timer] of this.timers) {
+      if (removed >= excess) break;
+      if (this.protectedKeyPrefix && key.startsWith(this.protectedKeyPrefix)) continue;
+      clearTimeout(timer);
+      this.timers.delete(key);
+      removed++;
+    }
+  }
+}

package/src/util/network-info.ts

@@ -0,0 +1,47 @@
+import { networkInterfaces } from 'node:os';
+
+/**
+ * Returns the local IPv4 address most likely to be reachable from other
+ * devices on the same LAN.
+ *
+ * Priority order:
+ *   1. en0 (Wi-Fi on macOS)
+ *   2. en1 (secondary network on macOS)
+ *   3. First non-loopback IPv4 on any interface
+ *
+ * Skips link-local addresses (169.254.x.x) and IPv6.
+ * Returns null if no suitable address is found (e.g. no network).
+ */
+export function getLocalIPv4(): string | null {
+  const ifaces = networkInterfaces();
+
+  // Priority interfaces in order
+  const priorityInterfaces = ['en0', 'en1'];
+
+  for (const ifName of priorityInterfaces) {
+    const addrs = ifaces[ifName];
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === 'IPv4' && !addr.internal && !isLinkLocal(addr.address)) {
+        return addr.address;
+      }
+    }
+  }
+
+  // Fallback: first non-loopback, non-link-local IPv4 on any interface
+  for (const [, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === 'IPv4' && !addr.internal && !isLinkLocal(addr.address)) {
+        return addr.address;
+      }
+    }
+  }
+
+  return null;
+}
+
+/** Returns true for IPv4 link-local addresses (169.254.x.x). */
+function isLinkLocal(address: string): boolean {
+  return address.startsWith('169.254.');
+}

package/src/util/platform.ts

@@ -135,12 +135,37 @@ export function isTCPEnabled(): boolean {
 
 /**
  * Returns the hostname/address for the TCP listener.
- * Reads VELLUM_DAEMON_TCP_HOST env var; defaults to '127.0.0.1' (localhost only).
- * Set VELLUM_DAEMON_TCP_HOST=0.0.0.0 to accept connections from all interfaces
- * (required for real iOS device connections over a local network).
+ * Resolution order (first match wins):
+ *   1. VELLUM_DAEMON_TCP_HOST env var (explicit override)
+ *   2. If iOS pairing is enabled: '0.0.0.0' (LAN-accessible)
+ *   3. Default: '127.0.0.1' (localhost only)
  */
 export function getTCPHost(): string {
-  return process.env.VELLUM_DAEMON_TCP_HOST?.trim() || '127.0.0.1';
+  const override = process.env.VELLUM_DAEMON_TCP_HOST?.trim();
+  if (override) return override;
+  if (isIOSPairingEnabled()) return '0.0.0.0';
+  return '127.0.0.1';
+}
+
+/**
+ * Returns whether iOS pairing mode is enabled.
+ * When enabled, the TCP listener binds to 0.0.0.0 (all interfaces)
+ * instead of 127.0.0.1 (localhost only), making the daemon reachable
+ * from iOS devices on the same local network.
+ *
+ * Resolution order (first match wins):
+ *   1. VELLUM_DAEMON_IOS_PAIRING env var ('true'/'1' → on, 'false'/'0' → off)
+ *   2. Presence of the flag file ~/.vellum/ios-pairing-enabled (exists → on)
+ *   3. Default: false
+ *
+ * This is separate from isTCPEnabled() — TCP can be enabled for localhost-only
+ * access without exposing the daemon to the LAN.
+ */
+export function isIOSPairingEnabled(): boolean {
+  const override = process.env.VELLUM_DAEMON_IOS_PAIRING?.trim();
+  if (override === 'true' || override === '1') return true;
+  if (override === 'false' || override === '0') return false;
+  return existsSync(join(getRootDir(), 'ios-pairing-enabled'));
 }
 
 export function getHttpTokenPath(): string {

package/src/util/promise-guard.ts

@@ -0,0 +1,37 @@
+/**
+ * Guards against concurrent execution of an async factory.
+ * Multiple concurrent callers share the same in-flight promise.
+ * On failure, the guard resets so subsequent calls can retry.
+ */
+export class PromiseGuard<T> {
+  private promise: Promise<T> | null = null;
+
+  /** Whether a promise is currently in-flight. */
+  get active(): boolean {
+    return this.promise !== null;
+  }
+
+  /**
+   * Execute the factory, deduplicating concurrent calls.
+   * If a call is already in-flight, returns the same promise.
+   * On failure, clears the cached promise to allow retry.
+   *
+   * @param factory - Creates the promise on first call.
+   * @param onError - Optional callback invoked when the factory rejects (before re-throwing).
+   */
+  run(factory: () => Promise<T>, onError?: (err: unknown) => void): Promise<T> {
+    if (this.promise) return this.promise;
+
+    this.promise = factory();
+    this.promise.catch((err) => {
+      this.promise = null;
+      onError?.(err);
+    });
+    return this.promise;
+  }
+
+  /** Reset the guard, allowing the next call to create a new promise. */
+  reset(): void {
+    this.promise = null;
+  }
+}

package/src/util/retry.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared retry utilities with exponential backoff + jitter.
+ *
+ * Used by both the provider retry layer (exception-based) and the
+ * web-search tool layer (HTTP response-based).
+ */
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default 3). */
+  maxRetries?: number;
+  /** Base delay in ms for exponential backoff (default 1000). */
+  baseDelayMs?: number;
+}
+
+/**
+ * Compute a retry delay with equal jitter: guaranteed floor of cap/2
+ * plus random in [0, cap/2]. Prevents retry storms while ensuring
+ * retries never collapse to 0ms.
+ */
+export function computeRetryDelay(attempt: number, baseDelayMs = DEFAULT_BASE_DELAY_MS): number {
+  const cap = baseDelayMs * Math.pow(2, attempt);
+  const half = cap / 2;
+  return half + Math.random() * half;
+}
+
+/**
+ * Parse a Retry-After header value into milliseconds.
+ * RFC 7231 allows either delta-seconds (e.g. "120") or an HTTP-date
+ * (e.g. "Tue, 17 Feb 2026 12:00:00 GMT"). Returns undefined if unparseable.
+ */
+export function parseRetryAfterMs(value: string): number | undefined {
+  const seconds = Number(value);
+  if (!isNaN(seconds)) {
+    return seconds * 1000;
+  }
+  // Try HTTP-date format — Date.parse handles RFC 2822 / IMF-fixdate
+  const dateMs = Date.parse(value);
+  if (!isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return undefined;
+}
+
+/**
+ * Determine the retry delay for an HTTP response. Uses the Retry-After
+ * header if present, otherwise falls back to exponential backoff with jitter.
+ */
+export function getHttpRetryDelay(
+  response: Response,
+  attempt: number,
+  baseDelayMs = DEFAULT_BASE_DELAY_MS,
+): number {
+  const retryAfter = response.headers.get('retry-after');
+  if (retryAfter) {
+    const parsed = parseRetryAfterMs(retryAfter);
+    if (parsed !== undefined) return parsed;
+  }
+  // Enforce a minimum floor of baseDelayMs when Retry-After is missing.
+  // computeRetryDelay uses equal jitter (cap/2 + random*cap/2) which can
+  // dip to ~500ms on attempt 0 — too aggressive for 429 rate limits.
+  return Math.max(baseDelayMs, computeRetryDelay(attempt, baseDelayMs));
+}
+
+/**
+ * Whether an HTTP status code is retryable (429 or 5xx).
+ */
+export function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+/**
+ * Whether an error is a retryable network error (ECONNRESET, ECONNREFUSED, etc.).
+ * Checks both the error itself and one level of `cause` chain.
+ */
+export function isRetryableNetworkError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+
+  const retryableCodes = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE']);
+
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code && retryableCodes.has(code)) return true;
+
+  if (error.cause instanceof Error) {
+    const causeCode = (error.cause as NodeJS.ErrnoException).code;
+    if (causeCode && retryableCodes.has(causeCode)) return true;
+  }
+
+  return false;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { DEFAULT_MAX_RETRIES, DEFAULT_BASE_DELAY_MS };

package/src/util/truncate.ts

@@ -1,6 +1,6 @@
 /** Truncate a string to `maxLen` characters, appending `suffix` if truncated. */
 export function truncate(str: string, maxLen: number, suffix = '...'): string {
   if (str.length <= maxLen) return str;
-  if (maxLen <= suffix.length) return str.slice(0, maxLen);
+  if (maxLen < suffix.length) return str.slice(0, maxLen);
   return str.slice(0, maxLen - suffix.length) + suffix;
 }