yzcode-cli 1.0.1 → 1.0.3

package/bridge/envLessBridgeConfig.ts

@@ -0,0 +1,165 @@
+import { z } from 'zod/v4'
+import { getFeatureValue_DEPRECATED } from '../services/analytics/growthbook.js'
+import { lazySchema } from '../utils/lazySchema.js'
+import { lt } from '../utils/semver.js'
+import { isEnvLessBridgeEnabled } from './bridgeEnabled.js'
+
+export type EnvLessBridgeConfig = {
+  // withRetry — init-phase backoff (createSession, POST /bridge, recovery /bridge)
+  init_retry_max_attempts: number
+  init_retry_base_delay_ms: number
+  init_retry_jitter_fraction: number
+  init_retry_max_delay_ms: number
+  // axios timeout for POST /sessions, POST /bridge, POST /archive
+  http_timeout_ms: number
+  // BoundedUUIDSet ring size (echo + re-delivery dedup)
+  uuid_dedup_buffer_size: number
+  // CCRClient worker heartbeat cadence. Server TTL is 60s — 20s gives 3× margin.
+  heartbeat_interval_ms: number
+  // ±fraction of interval — per-beat jitter to spread fleet load.
+  heartbeat_jitter_fraction: number
+  // Fire proactive JWT refresh this long before expires_in. Larger buffer =
+  // more frequent refresh (refresh cadence ≈ expires_in - buffer).
+  token_refresh_buffer_ms: number
+  // Archive POST timeout in teardown(). Distinct from http_timeout_ms because
+  // gracefulShutdown races runCleanupFunctions() against a 2s cap — a 10s
+  // axios timeout on a slow/stalled archive burns the whole budget on a
+  // request that forceExit will kill anyway.
+  teardown_archive_timeout_ms: number
+  // Deadline for onConnect after transport.connect(). If neither onConnect
+  // nor onClose fires before this, emit tengu_bridge_repl_connect_timeout
+  // — the only telemetry for the ~1% of sessions that emit `started` then
+  // go silent (no error, no event, just nothing).
+  connect_timeout_ms: number
+  // Semver floor for the env-less bridge path. Separate from the v1
+  // tengu_bridge_min_version config so a v2-specific bug can force upgrades
+  // without blocking v1 (env-based) clients, and vice versa.
+  min_version: string
+  // When true, tell users their claude.ai app may be too old to see v2
+  // sessions — lets us roll the v2 bridge before the app ships the new
+  // session-list query.
+  should_show_app_upgrade_message: boolean
+}
+
+export const DEFAULT_ENV_LESS_BRIDGE_CONFIG: EnvLessBridgeConfig = {
+  init_retry_max_attempts: 3,
+  init_retry_base_delay_ms: 500,
+  init_retry_jitter_fraction: 0.25,
+  init_retry_max_delay_ms: 4000,
+  http_timeout_ms: 10_000,
+  uuid_dedup_buffer_size: 2000,
+  heartbeat_interval_ms: 20_000,
+  heartbeat_jitter_fraction: 0.1,
+  token_refresh_buffer_ms: 300_000,
+  teardown_archive_timeout_ms: 1500,
+  connect_timeout_ms: 15_000,
+  min_version: '0.0.0',
+  should_show_app_upgrade_message: false,
+}
+
+// Floors reject the whole object on violation (fall back to DEFAULT) rather
+// than partially trusting — same defense-in-depth as pollConfig.ts.
+const envLessBridgeConfigSchema = lazySchema(() =>
+  z.object({
+    init_retry_max_attempts: z.number().int().min(1).max(10).default(3),
+    init_retry_base_delay_ms: z.number().int().min(100).default(500),
+    init_retry_jitter_fraction: z.number().min(0).max(1).default(0.25),
+    init_retry_max_delay_ms: z.number().int().min(500).default(4000),
+    http_timeout_ms: z.number().int().min(2000).default(10_000),
+    uuid_dedup_buffer_size: z.number().int().min(100).max(50_000).default(2000),
+    // Server TTL is 60s. Floor 5s prevents thrash; cap 30s keeps ≥2× margin.
+    heartbeat_interval_ms: z
+      .number()
+      .int()
+      .min(5000)
+      .max(30_000)
+      .default(20_000),
+    // ±fraction per beat. Cap 0.5: at max interval (30s) × 1.5 = 45s worst case,
+    // still under the 60s TTL.
+    heartbeat_jitter_fraction: z.number().min(0).max(0.5).default(0.1),
+    // Floor 30s prevents tight-looping. Cap 30min rejects buffer-vs-delay
+    // semantic inversion: ops entering expires_in-5min (the *delay until
+    // refresh*) instead of 5min (the *buffer before expiry*) yields
+    // delayMs = expires_in - buffer ≈ 5min instead of ≈4h. Both are positive
+    // durations so .min() alone can't distinguish; .max() catches the
+    // inverted value since buffer ≥ 30min is nonsensical for a multi-hour JWT.
+    token_refresh_buffer_ms: z
+      .number()
+      .int()
+      .min(30_000)
+      .max(1_800_000)
+      .default(300_000),
+    // Cap 2000 keeps this under gracefulShutdown's 2s cleanup race — a higher
+    // timeout just lies to axios since forceExit kills the socket regardless.
+    teardown_archive_timeout_ms: z
+      .number()
+      .int()
+      .min(500)
+      .max(2000)
+      .default(1500),
+    // Observed p99 connect is ~2-3s; 15s is ~5× headroom. Floor 5s bounds
+    // false-positive rate under transient slowness; cap 60s bounds how long
+    // a truly-stalled session stays dark.
+    connect_timeout_ms: z.number().int().min(5_000).max(60_000).default(15_000),
+    min_version: z
+      .string()
+      .refine(v => {
+        try {
+          lt(v, '0.0.0')
+          return true
+        } catch {
+          return false
+        }
+      })
+      .default('0.0.0'),
+    should_show_app_upgrade_message: z.boolean().default(false),
+  }),
+)
+
+/**
+ * Fetch the env-less bridge timing config from GrowthBook. Read once per
+ * initEnvLessBridgeCore call — config is fixed for the lifetime of a bridge
+ * session.
+ *
+ * Uses the blocking getter (not _CACHED_MAY_BE_STALE) because /remote-control
+ * runs well after GrowthBook init — initializeGrowthBook() resolves instantly,
+ * so there's no startup penalty, and we get the fresh in-memory remoteEval
+ * value instead of the stale-on-first-read disk cache. The _DEPRECATED suffix
+ * warns against startup-path usage, which this isn't.
+ */
+export async function getEnvLessBridgeConfig(): Promise<EnvLessBridgeConfig> {
+  const raw = await getFeatureValue_DEPRECATED<unknown>(
+    'tengu_bridge_repl_v2_config',
+    DEFAULT_ENV_LESS_BRIDGE_CONFIG,
+  )
+  const parsed = envLessBridgeConfigSchema().safeParse(raw)
+  return parsed.success ? parsed.data : DEFAULT_ENV_LESS_BRIDGE_CONFIG
+}
+
+/**
+ * Returns an error message if the current CLI version is below the minimum
+ * required for the env-less (v2) bridge path, or null if the version is fine.
+ *
+ * v2 analogue of checkBridgeMinVersion() — reads from tengu_bridge_repl_v2_config
+ * instead of tengu_bridge_min_version so the two implementations can enforce
+ * independent floors.
+ */
+export async function checkEnvLessBridgeMinVersion(): Promise<string | null> {
+  const cfg = await getEnvLessBridgeConfig()
+  if (cfg.min_version && lt(MACRO.VERSION, cfg.min_version)) {
+    return `Your version of Claude Code (${MACRO.VERSION}) is too old for Remote Control.\nVersion ${cfg.min_version} or higher is required. Run \`claude update\` to update.`
+  }
+  return null
+}
+
+/**
+ * Whether to nudge users toward upgrading their claude.ai app when a
+ * Remote Control session starts. True only when the v2 bridge is active
+ * AND the should_show_app_upgrade_message config bit is set — lets us
+ * roll the v2 bridge before the app ships the new session-list query.
+ */
+export async function shouldShowAppUpgradeMessage(): Promise<boolean> {
+  if (!isEnvLessBridgeEnabled()) return false
+  const cfg = await getEnvLessBridgeConfig()
+  return cfg.should_show_app_upgrade_message
+}

package/bridge/flushGate.ts

@@ -0,0 +1,71 @@
+/**
+ * State machine for gating message writes during an initial flush.
+ *
+ * When a bridge session starts, historical messages are flushed to the
+ * server via a single HTTP POST. During that flush, new messages must
+ * be queued to prevent them from arriving at the server interleaved
+ * with the historical messages.
+ *
+ * Lifecycle:
+ *   start() → enqueue() returns true, items are queued
+ *   end()   → returns queued items for draining, enqueue() returns false
+ *   drop()  → discards queued items (permanent transport close)
+ *   deactivate() → clears active flag without dropping items
+ *                   (transport replacement — new transport will drain)
+ */
+export class FlushGate<T> {
+  private _active = false
+  private _pending: T[] = []
+
+  get active(): boolean {
+    return this._active
+  }
+
+  get pendingCount(): number {
+    return this._pending.length
+  }
+
+  /** Mark flush as in-progress. enqueue() will start queuing items. */
+  start(): void {
+    this._active = true
+  }
+
+  /**
+   * End the flush and return any queued items for draining.
+   * Caller is responsible for sending the returned items.
+   */
+  end(): T[] {
+    this._active = false
+    return this._pending.splice(0)
+  }
+
+  /**
+   * If flush is active, queue the items and return true.
+   * If flush is not active, return false (caller should send directly).
+   */
+  enqueue(...items: T[]): boolean {
+    if (!this._active) return false
+    this._pending.push(...items)
+    return true
+  }
+
+  /**
+   * Discard all queued items (permanent transport close).
+   * Returns the number of items dropped.
+   */
+  drop(): number {
+    this._active = false
+    const count = this._pending.length
+    this._pending.length = 0
+    return count
+  }
+
+  /**
+   * Clear the active flag without dropping queued items.
+   * Used when the transport is replaced (onWorkReceived) — the new
+   * transport's flush will drain the pending items.
+   */
+  deactivate(): void {
+    this._active = false
+  }
+}

package/bridge/inboundAttachments.ts

@@ -0,0 +1,175 @@
+/**
+ * Resolve file_uuid attachments on inbound bridge user messages.
+ *
+ * Web composer uploads via cookie-authed /api/{org}/upload, sends file_uuid
+ * alongside the message. Here we fetch each via GET /api/oauth/files/{uuid}/content
+ * (oauth-authed, same store), write to ~/.claude/uploads/{sessionId}/, and
+ * return @path refs to prepend. Claude's Read tool takes it from there.
+ *
+ * Best-effort: any failure (no token, network, non-2xx, disk) logs debug and
+ * skips that attachment. The message still reaches Claude, just without @path.
+ */
+
+import type { ContentBlockParam } from '@anthropic-ai/sdk/resources/messages.mjs'
+import axios from 'axios'
+import { randomUUID } from 'crypto'
+import { mkdir, writeFile } from 'fs/promises'
+import { basename, join } from 'path'
+import { z } from 'zod/v4'
+import { getSessionId } from '../bootstrap/state.js'
+import { logForDebugging } from '../utils/debug.js'
+import { getClaudeConfigHomeDir } from '../utils/envUtils.js'
+import { lazySchema } from '../utils/lazySchema.js'
+import { getBridgeAccessToken, getBridgeBaseUrl } from './bridgeConfig.js'
+
+const DOWNLOAD_TIMEOUT_MS = 30_000
+
+function debug(msg: string): void {
+  logForDebugging(`[bridge:inbound-attach] ${msg}`)
+}
+
+const attachmentSchema = lazySchema(() =>
+  z.object({
+    file_uuid: z.string(),
+    file_name: z.string(),
+  }),
+)
+const attachmentsArraySchema = lazySchema(() => z.array(attachmentSchema()))
+
+export type InboundAttachment = z.infer<ReturnType<typeof attachmentSchema>>
+
+/** Pull file_attachments off a loosely-typed inbound message. */
+export function extractInboundAttachments(msg: unknown): InboundAttachment[] {
+  if (typeof msg !== 'object' || msg === null || !('file_attachments' in msg)) {
+    return []
+  }
+  const parsed = attachmentsArraySchema().safeParse(msg.file_attachments)
+  return parsed.success ? parsed.data : []
+}
+
+/**
+ * Strip path components and keep only filename-safe chars. file_name comes
+ * from the network (web composer), so treat it as untrusted even though the
+ * composer controls it.
+ */
+function sanitizeFileName(name: string): string {
+  const base = basename(name).replace(/[^a-zA-Z0-9._-]/g, '_')
+  return base || 'attachment'
+}
+
+function uploadsDir(): string {
+  return join(getClaudeConfigHomeDir(), 'uploads', getSessionId())
+}
+
+/**
+ * Fetch + write one attachment. Returns the absolute path on success,
+ * undefined on any failure.
+ */
+async function resolveOne(att: InboundAttachment): Promise<string | undefined> {
+  const token = getBridgeAccessToken()
+  if (!token) {
+    debug('skip: no oauth token')
+    return undefined
+  }
+
+  let data: Buffer
+  try {
+    // getOauthConfig() (via getBridgeBaseUrl) throws on a non-allowlisted
+    // CLAUDE_CODE_CUSTOM_OAUTH_URL — keep it inside the try so a bad
+    // FedStart URL degrades to "no @path" instead of crashing print.ts's
+    // reader loop (which has no catch around the await).
+    const url = `${getBridgeBaseUrl()}/api/oauth/files/${encodeURIComponent(att.file_uuid)}/content`
+    const response = await axios.get(url, {
+      headers: { Authorization: `Bearer ${token}` },
+      responseType: 'arraybuffer',
+      timeout: DOWNLOAD_TIMEOUT_MS,
+      validateStatus: () => true,
+    })
+    if (response.status !== 200) {
+      debug(`fetch ${att.file_uuid} failed: status=${response.status}`)
+      return undefined
+    }
+    data = Buffer.from(response.data)
+  } catch (e) {
+    debug(`fetch ${att.file_uuid} threw: ${e}`)
+    return undefined
+  }
+
+  // uuid-prefix makes collisions impossible across messages and within one
+  // (same filename, different files). 8 chars is enough — this isn't security.
+  const safeName = sanitizeFileName(att.file_name)
+  const prefix = (
+    att.file_uuid.slice(0, 8) || randomUUID().slice(0, 8)
+  ).replace(/[^a-zA-Z0-9_-]/g, '_')
+  const dir = uploadsDir()
+  const outPath = join(dir, `${prefix}-${safeName}`)
+
+  try {
+    await mkdir(dir, { recursive: true })
+    await writeFile(outPath, data)
+  } catch (e) {
+    debug(`write ${outPath} failed: ${e}`)
+    return undefined
+  }
+
+  debug(`resolved ${att.file_uuid} → ${outPath} (${data.length} bytes)`)
+  return outPath
+}
+
+/**
+ * Resolve all attachments on an inbound message to a prefix string of
+ * @path refs. Empty string if none resolved.
+ */
+export async function resolveInboundAttachments(
+  attachments: InboundAttachment[],
+): Promise<string> {
+  if (attachments.length === 0) return ''
+  debug(`resolving ${attachments.length} attachment(s)`)
+  const paths = await Promise.all(attachments.map(resolveOne))
+  const ok = paths.filter((p): p is string => p !== undefined)
+  if (ok.length === 0) return ''
+  // Quoted form — extractAtMentionedFiles truncates unquoted @refs at the
+  // first space, which breaks any home dir with spaces (/Users/John Smith/).
+  return ok.map(p => `@"${p}"`).join(' ') + ' '
+}
+
+/**
+ * Prepend @path refs to content, whichever form it's in.
+ * Targets the LAST text block — processUserInputBase reads inputString
+ * from processedBlocks[processedBlocks.length - 1], so putting refs in
+ * block[0] means they're silently ignored for [text, image] content.
+ */
+export function prependPathRefs(
+  content: string | Array<ContentBlockParam>,
+  prefix: string,
+): string | Array<ContentBlockParam> {
+  if (!prefix) return content
+  if (typeof content === 'string') return prefix + content
+  const i = content.findLastIndex(b => b.type === 'text')
+  if (i !== -1) {
+    const b = content[i]!
+    if (b.type === 'text') {
+      return [
+        ...content.slice(0, i),
+        { ...b, text: prefix + b.text },
+        ...content.slice(i + 1),
+      ]
+    }
+  }
+  // No text block — append one at the end so it's last.
+  return [...content, { type: 'text', text: prefix.trimEnd() }]
+}
+
+/**
+ * Convenience: extract + resolve + prepend. No-op when the message has no
+ * file_attachments field (fast path — no network, returns same reference).
+ */
+export async function resolveAndPrepend(
+  msg: unknown,
+  content: string | Array<ContentBlockParam>,
+): Promise<string | Array<ContentBlockParam>> {
+  const attachments = extractInboundAttachments(msg)
+  if (attachments.length === 0) return content
+  const prefix = await resolveInboundAttachments(attachments)
+  return prependPathRefs(content, prefix)
+}

package/bridge/inboundMessages.ts

@@ -0,0 +1,80 @@
+import type {
+  Base64ImageSource,
+  ContentBlockParam,
+  ImageBlockParam,
+} from '@anthropic-ai/sdk/resources/messages.mjs'
+import type { UUID } from 'crypto'
+import type { SDKMessage } from '../entrypoints/agentSdkTypes.js'
+import { detectImageFormatFromBase64 } from '../utils/imageResizer.js'
+
+/**
+ * Process an inbound user message from the bridge, extracting content
+ * and UUID for enqueueing. Supports both string content and
+ * ContentBlockParam[] (e.g. messages containing images).
+ *
+ * Normalizes image blocks from bridge clients that may use camelCase
+ * `mediaType` instead of snake_case `media_type` (mobile-apps#5825).
+ *
+ * Returns the extracted fields, or undefined if the message should be
+ * skipped (non-user type, missing/empty content).
+ */
+export function extractInboundMessageFields(
+  msg: SDKMessage,
+):
+  | { content: string | Array<ContentBlockParam>; uuid: UUID | undefined }
+  | undefined {
+  if (msg.type !== 'user') return undefined
+  const content = msg.message?.content
+  if (!content) return undefined
+  if (Array.isArray(content) && content.length === 0) return undefined
+
+  const uuid =
+    'uuid' in msg && typeof msg.uuid === 'string'
+      ? (msg.uuid as UUID)
+      : undefined
+
+  return {
+    content: Array.isArray(content) ? normalizeImageBlocks(content) : content,
+    uuid,
+  }
+}
+
+/**
+ * Normalize image content blocks from bridge clients. iOS/web clients may
+ * send `mediaType` (camelCase) instead of `media_type` (snake_case), or
+ * omit the field entirely. Without normalization, the bad block poisons
+ * the session — every subsequent API call fails with
+ * "media_type: Field required".
+ *
+ * Fast-path scan returns the original array reference when no
+ * normalization is needed (zero allocation on the happy path).
+ */
+export function normalizeImageBlocks(
+  blocks: Array<ContentBlockParam>,
+): Array<ContentBlockParam> {
+  if (!blocks.some(isMalformedBase64Image)) return blocks
+
+  return blocks.map(block => {
+    if (!isMalformedBase64Image(block)) return block
+    const src = block.source as unknown as Record<string, unknown>
+    const mediaType =
+      typeof src.mediaType === 'string' && src.mediaType
+        ? src.mediaType
+        : detectImageFormatFromBase64(block.source.data)
+    return {
+      ...block,
+      source: {
+        type: 'base64' as const,
+        media_type: mediaType as Base64ImageSource['media_type'],
+        data: block.source.data,
+      },
+    }
+  })
+}
+
+function isMalformedBase64Image(
+  block: ContentBlockParam,
+): block is ImageBlockParam & { source: Base64ImageSource } {
+  if (block.type !== 'image' || block.source?.type !== 'base64') return false
+  return !(block.source as unknown as Record<string, unknown>).media_type
+}