mirror of
http://10.0.2.1:3031/sauer/claude-code.git
synced 2026-06-30 21:36:57 +10:00
3000 lines
113 KiB
TypeScript
3000 lines
113 KiB
TypeScript
|
import { feature } from 'bun:bundle'
|
|||
|
|
import { randomUUID } from 'crypto'
|
|||
|
|
import { hostname, tmpdir } from 'os'
|
|||
|
|
import { basename, join, resolve } from 'path'
|
|||
|
|
import { getRemoteSessionUrl } from '../constants/product.js'
|
|||
|
|
import { shutdownDatadog } from '../services/analytics/datadog.js'
|
|||
|
|
import { shutdown1PEventLogging } from '../services/analytics/firstPartyEventLogger.js'
|
|||
|
|
import { checkGate_CACHED_OR_BLOCKING } from '../services/analytics/growthbook.js'
|
|||
|
|
import {
|
|||
|
|
type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
logEvent,
|
|||
|
|
logEventAsync,
|
|||
|
|
} from '../services/analytics/index.js'
|
|||
|
|
import { isInBundledMode } from '../utils/bundledMode.js'
|
|||
|
|
import { logForDebugging } from '../utils/debug.js'
|
|||
|
|
import { logForDiagnosticsNoPII } from '../utils/diagLogs.js'
|
|||
|
|
import { isEnvTruthy, isInProtectedNamespace } from '../utils/envUtils.js'
|
|||
|
|
import { errorMessage } from '../utils/errors.js'
|
|||
|
|
import { truncateToWidth } from '../utils/format.js'
|
|||
|
|
import { logError } from '../utils/log.js'
|
|||
|
|
import { sleep } from '../utils/sleep.js'
|
|||
|
|
import { createAgentWorktree, removeAgentWorktree } from '../utils/worktree.js'
|
|||
|
|
import {
|
|||
|
|
BridgeFatalError,
|
|||
|
|
createBridgeApiClient,
|
|||
|
|
isExpiredErrorType,
|
|||
|
|
isSuppressible403,
|
|||
|
|
validateBridgeId,
|
|||
|
|
} from './bridgeApi.js'
|
|||
|
|
import { formatDuration } from './bridgeStatusUtil.js'
|
|||
|
|
import { createBridgeLogger } from './bridgeUI.js'
|
|||
|
|
import { createCapacityWake } from './capacityWake.js'
|
|||
|
|
import { describeAxiosError } from './debugUtils.js'
|
|||
|
|
import { createTokenRefreshScheduler } from './jwtUtils.js'
|
|||
|
|
import { getPollIntervalConfig } from './pollConfig.js'
|
|||
|
|
import { toCompatSessionId, toInfraSessionId } from './sessionIdCompat.js'
|
|||
|
|
import { createSessionSpawner, safeFilenameId } from './sessionRunner.js'
|
|||
|
|
import { getTrustedDeviceToken } from './trustedDevice.js'
|
|||
|
|
import {
|
|||
|
|
BRIDGE_LOGIN_ERROR,
|
|||
|
|
type BridgeApiClient,
|
|||
|
|
type BridgeConfig,
|
|||
|
|
type BridgeLogger,
|
|||
|
|
DEFAULT_SESSION_TIMEOUT_MS,
|
|||
|
|
type SessionDoneStatus,
|
|||
|
|
type SessionHandle,
|
|||
|
|
type SessionSpawner,
|
|||
|
|
type SessionSpawnOpts,
|
|||
|
|
type SpawnMode,
|
|||
|
|
} from './types.js'
|
|||
|
|
import {
|
|||
|
|
buildCCRv2SdkUrl,
|
|||
|
|
buildSdkUrl,
|
|||
|
|
decodeWorkSecret,
|
|||
|
|
registerWorker,
|
|||
|
|
sameSessionId,
|
|||
|
|
} from './workSecret.js'
|
|||
|
|
|
|||
|
|
export type BackoffConfig = {
|
|||
|
|
connInitialMs: number
|
|||
|
|
connCapMs: number
|
|||
|
|
connGiveUpMs: number
|
|||
|
|
generalInitialMs: number
|
|||
|
|
generalCapMs: number
|
|||
|
|
generalGiveUpMs: number
|
|||
|
|
/** SIGTERM→SIGKILL grace period on shutdown. Default 30s. */
|
|||
|
|
shutdownGraceMs?: number
|
|||
|
|
/** stopWorkWithRetry base delay (1s/2s/4s backoff). Default 1000ms. */
|
|||
|
|
stopWorkBaseDelayMs?: number
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const DEFAULT_BACKOFF: BackoffConfig = {
|
|||
|
|
connInitialMs: 2_000,
|
|||
|
|
connCapMs: 120_000, // 2 minutes
|
|||
|
|
connGiveUpMs: 600_000, // 10 minutes
|
|||
|
|
generalInitialMs: 500,
|
|||
|
|
generalCapMs: 30_000,
|
|||
|
|
generalGiveUpMs: 600_000, // 10 minutes
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Status update interval for the live display (ms). */
|
|||
|
|
const STATUS_UPDATE_INTERVAL_MS = 1_000
|
|||
|
|
const SPAWN_SESSIONS_DEFAULT = 32
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* GrowthBook gate for multi-session spawn modes (--spawn / --capacity / --create-session-in-dir).
|
|||
|
|
* Sibling of tengu_ccr_bridge_multi_environment (multiple envs per host:dir) —
|
|||
|
|
* this one enables multiple sessions per environment.
|
|||
|
|
* Rollout staged via targeting rules: ants first, then gradual external.
|
|||
|
|
*
|
|||
|
|
* Uses the blocking gate check so a stale disk-cache miss doesn't unfairly
|
|||
|
|
* deny access. The fast path (cache has true) is still instant; only the
|
|||
|
|
* cold-start path awaits the server fetch, and that fetch also seeds the
|
|||
|
|
* disk cache for next time.
|
|||
|
|
*/
|
|||
|
|
async function isMultiSessionSpawnEnabled(): Promise<boolean> {
|
|||
|
|
return checkGate_CACHED_OR_BLOCKING('tengu_ccr_bridge_multi_session')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Returns the threshold for detecting system sleep/wake in the poll loop.
|
|||
|
|
* Must exceed the max backoff cap — otherwise normal backoff delays trigger
|
|||
|
|
* false sleep detection (resetting the error budget indefinitely). Using
|
|||
|
|
* 2× the connection backoff cap, matching the pattern in WebSocketTransport
|
|||
|
|
* and replBridge.
|
|||
|
|
*/
|
|||
|
|
function pollSleepDetectionThresholdMs(backoff: BackoffConfig): number {
|
|||
|
|
return backoff.connCapMs * 2
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Returns the args that must precede CLI flags when spawning a child claude
|
|||
|
|
* process. In compiled binaries, process.execPath is the claude binary itself
|
|||
|
|
* and args go directly to it. In npm installs (node running cli.js),
|
|||
|
|
* process.execPath is the node runtime — the child spawn must pass the script
|
|||
|
|
* path as the first arg, otherwise node interprets --sdk-url as a node option
|
|||
|
|
* and exits with "bad option: --sdk-url". See anthropics/claude-code#28334.
|
|||
|
|
*/
|
|||
|
|
function spawnScriptArgs(): string[] {
|
|||
|
|
if (isInBundledMode() || !process.argv[1]) {
|
|||
|
|
return []
|
|||
|
|
}
|
|||
|
|
return [process.argv[1]]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Attempt to spawn a session; returns error string if spawn throws. */
|
|||
|
|
function safeSpawn(
|
|||
|
|
spawner: SessionSpawner,
|
|||
|
|
opts: SessionSpawnOpts,
|
|||
|
|
dir: string,
|
|||
|
|
): SessionHandle | string {
|
|||
|
|
try {
|
|||
|
|
return spawner.spawn(opts, dir)
|
|||
|
|
} catch (err) {
|
|||
|
|
const errMsg = errorMessage(err)
|
|||
|
|
logError(new Error(`Session spawn failed: ${errMsg}`))
|
|||
|
|
return errMsg
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export async function runBridgeLoop(
|
|||
|
|
config: BridgeConfig,
|
|||
|
|
environmentId: string,
|
|||
|
|
environmentSecret: string,
|
|||
|
|
api: BridgeApiClient,
|
|||
|
|
spawner: SessionSpawner,
|
|||
|
|
logger: BridgeLogger,
|
|||
|
|
signal: AbortSignal,
|
|||
|
|
backoffConfig: BackoffConfig = DEFAULT_BACKOFF,
|
|||
|
|
initialSessionId?: string,
|
|||
|
|
getAccessToken?: () => string | undefined | Promise<string | undefined>,
|
|||
|
|
): Promise<void> {
|
|||
|
|
// Local abort controller so that onSessionDone can stop the poll loop.
|
|||
|
|
// Linked to the incoming signal so external aborts also work.
|
|||
|
|
const controller = new AbortController()
|
|||
|
|
if (signal.aborted) {
|
|||
|
|
controller.abort()
|
|||
|
|
} else {
|
|||
|
|
signal.addEventListener('abort', () => controller.abort(), { once: true })
|
|||
|
|
}
|
|||
|
|
const loopSignal = controller.signal
|
|||
|
|
|
|||
|
|
const activeSessions = new Map<string, SessionHandle>()
|
|||
|
|
const sessionStartTimes = new Map<string, number>()
|
|||
|
|
const sessionWorkIds = new Map<string, string>()
|
|||
|
|
// Compat-surface ID (session_*) computed once at spawn and cached so
|
|||
|
|
// cleanup and status-update ticks use the same key regardless of whether
|
|||
|
|
// the tengu_bridge_repl_v2_cse_shim_enabled gate flips mid-session.
|
|||
|
|
const sessionCompatIds = new Map<string, string>()
|
|||
|
|
// Session ingress JWTs for heartbeat auth, keyed by sessionId.
|
|||
|
|
// Stored separately from handle.accessToken because the token refresh
|
|||
|
|
// scheduler overwrites that field with the OAuth token (~3h55m in).
|
|||
|
|
const sessionIngressTokens = new Map<string, string>()
|
|||
|
|
const sessionTimers = new Map<string, ReturnType<typeof setTimeout>>()
|
|||
|
|
const completedWorkIds = new Set<string>()
|
|||
|
|
const sessionWorktrees = new Map<
|
|||
|
|
string,
|
|||
|
|
{
|
|||
|
|
worktreePath: string
|
|||
|
|
worktreeBranch?: string
|
|||
|
|
gitRoot?: string
|
|||
|
|
hookBased?: boolean
|
|||
|
|
}
|
|||
|
|
>()
|
|||
|
|
// Track sessions killed by the timeout watchdog so onSessionDone can
|
|||
|
|
// distinguish them from server-initiated or shutdown interrupts.
|
|||
|
|
const timedOutSessions = new Set<string>()
|
|||
|
|
// Sessions that already have a title (server-set or bridge-derived) so
|
|||
|
|
// onFirstUserMessage doesn't clobber a user-assigned --name / web rename.
|
|||
|
|
// Keyed by compatSessionId to match logger.setSessionTitle's key.
|
|||
|
|
const titledSessions = new Set<string>()
|
|||
|
|
// Signal to wake the at-capacity sleep early when a session completes,
|
|||
|
|
// so the bridge can immediately accept new work.
|
|||
|
|
const capacityWake = createCapacityWake(loopSignal)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Heartbeat all active work items.
|
|||
|
|
* Returns 'ok' if at least one heartbeat succeeded, 'auth_failed' if any
|
|||
|
|
* got a 401/403 (JWT expired — re-queued via reconnectSession so the next
|
|||
|
|
* poll delivers fresh work), or 'failed' if all failed for other reasons.
|
|||
|
|
*/
|
|||
|
|
async function heartbeatActiveWorkItems(): Promise<
|
|||
|
|
'ok' | 'auth_failed' | 'fatal' | 'failed'
|
|||
|
|
> {
|
|||
|
|
let anySuccess = false
|
|||
|
|
let anyFatal = false
|
|||
|
|
const authFailedSessions: string[] = []
|
|||
|
|
for (const [sessionId] of activeSessions) {
|
|||
|
|
const workId = sessionWorkIds.get(sessionId)
|
|||
|
|
const ingressToken = sessionIngressTokens.get(sessionId)
|
|||
|
|
if (!workId || !ingressToken) {
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
try {
|
|||
|
|
await api.heartbeatWork(environmentId, workId, ingressToken)
|
|||
|
|
anySuccess = true
|
|||
|
|
} catch (err) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:heartbeat] Failed for sessionId=${sessionId} workId=${workId}: ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
if (err instanceof BridgeFatalError) {
|
|||
|
|
logEvent('tengu_bridge_heartbeat_error', {
|
|||
|
|
status:
|
|||
|
|
err.status as unknown as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
error_type: (err.status === 401 || err.status === 403
|
|||
|
|
? 'auth_failed'
|
|||
|
|
: 'fatal') as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
})
|
|||
|
|
if (err.status === 401 || err.status === 403) {
|
|||
|
|
authFailedSessions.push(sessionId)
|
|||
|
|
} else {
|
|||
|
|
// 404/410 = environment expired or deleted — no point retrying
|
|||
|
|
anyFatal = true
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
// JWT expired → trigger server-side re-dispatch. Without this, work stays
|
|||
|
|
// ACK'd out of the Redis PEL and poll returns empty forever (CC-1263).
|
|||
|
|
// The existingHandle path below delivers the fresh token to the child.
|
|||
|
|
// sessionId is already in the format /bridge/reconnect expects: it comes
|
|||
|
|
// from work.data.id, which matches the server's EnvironmentInstance store
|
|||
|
|
// (cse_* under the compat gate, session_* otherwise).
|
|||
|
|
for (const sessionId of authFailedSessions) {
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Session ${sessionId} token expired — re-queuing via bridge/reconnect`,
|
|||
|
|
)
|
|||
|
|
try {
|
|||
|
|
await api.reconnectSession(environmentId, sessionId)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:heartbeat] Re-queued sessionId=${sessionId} via bridge/reconnect`,
|
|||
|
|
)
|
|||
|
|
} catch (err) {
|
|||
|
|
logger.logError(
|
|||
|
|
`Failed to refresh session ${sessionId} token: ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:heartbeat] reconnectSession(${sessionId}) failed: ${errorMessage(err)}`,
|
|||
|
|
{ level: 'error' },
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
if (anyFatal) {
|
|||
|
|
return 'fatal'
|
|||
|
|
}
|
|||
|
|
if (authFailedSessions.length > 0) {
|
|||
|
|
return 'auth_failed'
|
|||
|
|
}
|
|||
|
|
return anySuccess ? 'ok' : 'failed'
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Sessions spawned with CCR v2 env vars. v2 children cannot use OAuth
|
|||
|
|
// tokens (CCR worker endpoints validate the JWT's session_id claim,
|
|||
|
|
// register_worker.go:32), so onRefresh triggers server re-dispatch
|
|||
|
|
// instead — the next poll delivers fresh work with a new JWT via the
|
|||
|
|
// existingHandle path below.
|
|||
|
|
const v2Sessions = new Set<string>()
|
|||
|
|
|
|||
|
|
// Proactive token refresh: schedules a timer 5min before the session
|
|||
|
|
// ingress JWT expires. v1 delivers OAuth directly; v2 calls
|
|||
|
|
// reconnectSession to trigger server re-dispatch (CC-1263: without
|
|||
|
|
// this, v2 daemon sessions silently die at ~5h since the server does
|
|||
|
|
// not auto-re-dispatch ACK'd work on lease expiry).
|
|||
|
|
const tokenRefresh = getAccessToken
|
|||
|
|
? createTokenRefreshScheduler({
|
|||
|
|
getAccessToken,
|
|||
|
|
onRefresh: (sessionId, oauthToken) => {
|
|||
|
|
const handle = activeSessions.get(sessionId)
|
|||
|
|
if (!handle) {
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
if (v2Sessions.has(sessionId)) {
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Refreshing session ${sessionId} token via bridge/reconnect`,
|
|||
|
|
)
|
|||
|
|
void api
|
|||
|
|
.reconnectSession(environmentId, sessionId)
|
|||
|
|
.catch((err: unknown) => {
|
|||
|
|
logger.logError(
|
|||
|
|
`Failed to refresh session ${sessionId} token: ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:token] reconnectSession(${sessionId}) failed: ${errorMessage(err)}`,
|
|||
|
|
{ level: 'error' },
|
|||
|
|
)
|
|||
|
|
})
|
|||
|
|
} else {
|
|||
|
|
handle.updateAccessToken(oauthToken)
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
label: 'bridge',
|
|||
|
|
})
|
|||
|
|
: null
|
|||
|
|
const loopStartTime = Date.now()
|
|||
|
|
// Track all in-flight cleanup promises (stopWork, worktree removal) so
|
|||
|
|
// the shutdown sequence can await them before process.exit().
|
|||
|
|
const pendingCleanups = new Set<Promise<unknown>>()
|
|||
|
|
function trackCleanup(p: Promise<unknown>): void {
|
|||
|
|
pendingCleanups.add(p)
|
|||
|
|
void p.finally(() => pendingCleanups.delete(p))
|
|||
|
|
}
|
|||
|
|
let connBackoff = 0
|
|||
|
|
let generalBackoff = 0
|
|||
|
|
let connErrorStart: number | null = null
|
|||
|
|
let generalErrorStart: number | null = null
|
|||
|
|
let lastPollErrorTime: number | null = null
|
|||
|
|
let statusUpdateTimer: ReturnType<typeof setInterval> | null = null
|
|||
|
|
// Set by BridgeFatalError and give-up paths so the shutdown block can
|
|||
|
|
// skip the resume message (resume is impossible after env expiry/auth
|
|||
|
|
// failure/sustained connection errors).
|
|||
|
|
let fatalExit = false
|
|||
|
|
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Starting poll loop spawnMode=${config.spawnMode} maxSessions=${config.maxSessions} environmentId=${environmentId}`,
|
|||
|
|
)
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_loop_started', {
|
|||
|
|
max_sessions: config.maxSessions,
|
|||
|
|
spawn_mode: config.spawnMode,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// For ant users, show where session debug logs will land so they can tail them.
|
|||
|
|
// sessionRunner.ts uses the same base path. File appears once a session spawns.
|
|||
|
|
if (process.env.USER_TYPE === 'ant') {
|
|||
|
|
let debugGlob: string
|
|||
|
|
if (config.debugFile) {
|
|||
|
|
const ext = config.debugFile.lastIndexOf('.')
|
|||
|
|
debugGlob =
|
|||
|
|
ext > 0
|
|||
|
|
? `${config.debugFile.slice(0, ext)}-*${config.debugFile.slice(ext)}`
|
|||
|
|
: `${config.debugFile}-*`
|
|||
|
|
} else {
|
|||
|
|
debugGlob = join(tmpdir(), 'claude', 'bridge-session-*.log')
|
|||
|
|
}
|
|||
|
|
logger.setDebugLogPath(debugGlob)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
logger.printBanner(config, environmentId)
|
|||
|
|
|
|||
|
|
// Seed the logger's session count + spawn mode before any render. Without
|
|||
|
|
// this, setAttached() below renders with the logger's default sessionMax=1,
|
|||
|
|
// showing "Capacity: 0/1" until the status ticker kicks in (which is gated
|
|||
|
|
// by !initialSessionId and only starts after the poll loop picks up work).
|
|||
|
|
logger.updateSessionCount(0, config.maxSessions, config.spawnMode)
|
|||
|
|
|
|||
|
|
// If an initial session was pre-created, show its URL from the start so
|
|||
|
|
// the user can click through immediately (matching /remote-control behavior).
|
|||
|
|
if (initialSessionId) {
|
|||
|
|
logger.setAttached(initialSessionId)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Refresh the inline status display. Shows idle or active depending on state. */
|
|||
|
|
function updateStatusDisplay(): void {
|
|||
|
|
// Push the session count (no-op when maxSessions === 1) so the
|
|||
|
|
// next renderStatusLine tick shows the current count.
|
|||
|
|
logger.updateSessionCount(
|
|||
|
|
activeSessions.size,
|
|||
|
|
config.maxSessions,
|
|||
|
|
config.spawnMode,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Push per-session activity into the multi-session display.
|
|||
|
|
for (const [sid, handle] of activeSessions) {
|
|||
|
|
const act = handle.currentActivity
|
|||
|
|
if (act) {
|
|||
|
|
logger.updateSessionActivity(sessionCompatIds.get(sid) ?? sid, act)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (activeSessions.size === 0) {
|
|||
|
|
logger.updateIdleStatus()
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Show the most recently started session that is still actively working.
|
|||
|
|
// Sessions whose current activity is 'result' or 'error' are between
|
|||
|
|
// turns — the CLI emitted its result but the process stays alive waiting
|
|||
|
|
// for the next user message. Skip updating so the status line keeps
|
|||
|
|
// whatever state it had (Attached / session title).
|
|||
|
|
const [sessionId, handle] = [...activeSessions.entries()].pop()!
|
|||
|
|
const startTime = sessionStartTimes.get(sessionId)
|
|||
|
|
if (!startTime) return
|
|||
|
|
|
|||
|
|
const activity = handle.currentActivity
|
|||
|
|
if (!activity || activity.type === 'result' || activity.type === 'error') {
|
|||
|
|
// Session is between turns — keep current status (Attached/titled).
|
|||
|
|
// In multi-session mode, still refresh so bullet-list activities stay current.
|
|||
|
|
if (config.maxSessions > 1) logger.refreshDisplay()
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const elapsed = formatDuration(Date.now() - startTime)
|
|||
|
|
|
|||
|
|
// Build trail from recent tool activities (last 5)
|
|||
|
|
const trail = handle.activities
|
|||
|
|
.filter(a => a.type === 'tool_start')
|
|||
|
|
.slice(-5)
|
|||
|
|
.map(a => a.summary)
|
|||
|
|
|
|||
|
|
logger.updateSessionStatus(sessionId, elapsed, activity, trail)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Start the status display update ticker. */
|
|||
|
|
function startStatusUpdates(): void {
|
|||
|
|
stopStatusUpdates()
|
|||
|
|
// Call immediately so the first transition (e.g. Connecting → Ready)
|
|||
|
|
// happens without delay, avoiding concurrent timer races.
|
|||
|
|
updateStatusDisplay()
|
|||
|
|
statusUpdateTimer = setInterval(
|
|||
|
|
updateStatusDisplay,
|
|||
|
|
STATUS_UPDATE_INTERVAL_MS,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Stop the status display update ticker. */
|
|||
|
|
function stopStatusUpdates(): void {
|
|||
|
|
if (statusUpdateTimer) {
|
|||
|
|
clearInterval(statusUpdateTimer)
|
|||
|
|
statusUpdateTimer = null
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function onSessionDone(
|
|||
|
|
sessionId: string,
|
|||
|
|
startTime: number,
|
|||
|
|
handle: SessionHandle,
|
|||
|
|
): (status: SessionDoneStatus) => void {
|
|||
|
|
return (rawStatus: SessionDoneStatus): void => {
|
|||
|
|
const workId = sessionWorkIds.get(sessionId)
|
|||
|
|
activeSessions.delete(sessionId)
|
|||
|
|
sessionStartTimes.delete(sessionId)
|
|||
|
|
sessionWorkIds.delete(sessionId)
|
|||
|
|
sessionIngressTokens.delete(sessionId)
|
|||
|
|
const compatId = sessionCompatIds.get(sessionId) ?? sessionId
|
|||
|
|
sessionCompatIds.delete(sessionId)
|
|||
|
|
logger.removeSession(compatId)
|
|||
|
|
titledSessions.delete(compatId)
|
|||
|
|
v2Sessions.delete(sessionId)
|
|||
|
|
// Clear per-session timeout timer
|
|||
|
|
const timer = sessionTimers.get(sessionId)
|
|||
|
|
if (timer) {
|
|||
|
|
clearTimeout(timer)
|
|||
|
|
sessionTimers.delete(sessionId)
|
|||
|
|
}
|
|||
|
|
// Clear token refresh timer
|
|||
|
|
tokenRefresh?.cancel(sessionId)
|
|||
|
|
// Wake the at-capacity sleep so the bridge can accept new work immediately
|
|||
|
|
capacityWake.wake()
|
|||
|
|
|
|||
|
|
// If the session was killed by the timeout watchdog, treat it as a
|
|||
|
|
// failed session (not a server/shutdown interrupt) so we still call
|
|||
|
|
// stopWork and archiveSession below.
|
|||
|
|
const wasTimedOut = timedOutSessions.delete(sessionId)
|
|||
|
|
const status: SessionDoneStatus =
|
|||
|
|
wasTimedOut && rawStatus === 'interrupted' ? 'failed' : rawStatus
|
|||
|
|
const durationMs = Date.now() - startTime
|
|||
|
|
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] sessionId=${sessionId} workId=${workId ?? 'unknown'} exited status=${status} duration=${formatDuration(durationMs)}`,
|
|||
|
|
)
|
|||
|
|
logEvent('tengu_bridge_session_done', {
|
|||
|
|
status:
|
|||
|
|
status as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
duration_ms: durationMs,
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_session_done', {
|
|||
|
|
status,
|
|||
|
|
duration_ms: durationMs,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// Clear the status display before printing final log
|
|||
|
|
logger.clearStatus()
|
|||
|
|
stopStatusUpdates()
|
|||
|
|
|
|||
|
|
// Build error message from stderr if available
|
|||
|
|
const stderrSummary =
|
|||
|
|
handle.lastStderr.length > 0 ? handle.lastStderr.join('\n') : undefined
|
|||
|
|
let failureMessage: string | undefined
|
|||
|
|
|
|||
|
|
switch (status) {
|
|||
|
|
case 'completed':
|
|||
|
|
logger.logSessionComplete(sessionId, durationMs)
|
|||
|
|
break
|
|||
|
|
case 'failed':
|
|||
|
|
// Skip failure log during shutdown — the child exits non-zero when
|
|||
|
|
// killed, which is expected and not a real failure.
|
|||
|
|
// Also skip for timeout-killed sessions — the timeout watchdog
|
|||
|
|
// already logged a clear timeout message.
|
|||
|
|
if (!wasTimedOut && !loopSignal.aborted) {
|
|||
|
|
failureMessage = stderrSummary ?? 'Process exited with error'
|
|||
|
|
logger.logSessionFailed(sessionId, failureMessage)
|
|||
|
|
logError(new Error(`Bridge session failed: ${failureMessage}`))
|
|||
|
|
}
|
|||
|
|
break
|
|||
|
|
case 'interrupted':
|
|||
|
|
logger.logVerbose(`Session ${sessionId} interrupted`)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Notify the server that this work item is done. Skip for interrupted
|
|||
|
|
// sessions — interrupts are either server-initiated (the server already
|
|||
|
|
// knows) or caused by bridge shutdown (which calls stopWork() separately).
|
|||
|
|
if (status !== 'interrupted' && workId) {
|
|||
|
|
trackCleanup(
|
|||
|
|
stopWorkWithRetry(
|
|||
|
|
api,
|
|||
|
|
environmentId,
|
|||
|
|
workId,
|
|||
|
|
logger,
|
|||
|
|
backoffConfig.stopWorkBaseDelayMs,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
completedWorkIds.add(workId)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Clean up worktree if one was created for this session
|
|||
|
|
const wt = sessionWorktrees.get(sessionId)
|
|||
|
|
if (wt) {
|
|||
|
|
sessionWorktrees.delete(sessionId)
|
|||
|
|
trackCleanup(
|
|||
|
|
removeAgentWorktree(
|
|||
|
|
wt.worktreePath,
|
|||
|
|
wt.worktreeBranch,
|
|||
|
|
wt.gitRoot,
|
|||
|
|
wt.hookBased,
|
|||
|
|
).catch((err: unknown) =>
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Failed to remove worktree ${wt.worktreePath}: ${errorMessage(err)}`,
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Lifecycle decision: in multi-session mode, keep the bridge running
|
|||
|
|
// after a session completes. In single-session mode, abort the poll
|
|||
|
|
// loop so the bridge exits cleanly.
|
|||
|
|
if (status !== 'interrupted' && !loopSignal.aborted) {
|
|||
|
|
if (config.spawnMode !== 'single-session') {
|
|||
|
|
// Multi-session: archive the completed session so it doesn't linger
|
|||
|
|
// as stale in the web UI. archiveSession is idempotent (409 if already
|
|||
|
|
// archived), so double-archiving at shutdown is safe.
|
|||
|
|
// sessionId arrived as cse_* from the work poll (infrastructure-layer
|
|||
|
|
// tag). archiveSession hits /v1/sessions/{id}/archive which is the
|
|||
|
|
// compat surface and validates TagSession (session_*). Re-tag — same
|
|||
|
|
// UUID underneath.
|
|||
|
|
trackCleanup(
|
|||
|
|
api
|
|||
|
|
.archiveSession(compatId)
|
|||
|
|
.catch((err: unknown) =>
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Failed to archive session ${sessionId}: ${errorMessage(err)}`,
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] Session ${status}, returning to idle (multi-session mode)`,
|
|||
|
|
)
|
|||
|
|
} else {
|
|||
|
|
// Single-session: coupled lifecycle — tear down environment
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] Session ${status}, aborting poll loop to tear down environment`,
|
|||
|
|
)
|
|||
|
|
controller.abort()
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (!loopSignal.aborted) {
|
|||
|
|
startStatusUpdates()
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Start the idle status display immediately — unless we have a pre-created
|
|||
|
|
// session, in which case setAttached() already set up the display and the
|
|||
|
|
// poll loop will start status updates when it picks up the session.
|
|||
|
|
if (!initialSessionId) {
|
|||
|
|
startStatusUpdates()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
while (!loopSignal.aborted) {
|
|||
|
|
// Fetched once per iteration — the GrowthBook cache refreshes every
|
|||
|
|
// 5 min, so a loop running at the at-capacity rate picks up config
|
|||
|
|
// changes within one sleep cycle.
|
|||
|
|
const pollConfig = getPollIntervalConfig()
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
const work = await api.pollForWork(
|
|||
|
|
environmentId,
|
|||
|
|
environmentSecret,
|
|||
|
|
loopSignal,
|
|||
|
|
pollConfig.reclaim_older_than_ms,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Log reconnection if we were previously disconnected
|
|||
|
|
const wasDisconnected =
|
|||
|
|
connErrorStart !== null || generalErrorStart !== null
|
|||
|
|
if (wasDisconnected) {
|
|||
|
|
const disconnectedMs =
|
|||
|
|
Date.now() - (connErrorStart ?? generalErrorStart ?? Date.now())
|
|||
|
|
logger.logReconnected(disconnectedMs)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:poll] Reconnected after ${formatDuration(disconnectedMs)}`,
|
|||
|
|
)
|
|||
|
|
logEvent('tengu_bridge_reconnected', {
|
|||
|
|
disconnected_ms: disconnectedMs,
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
connBackoff = 0
|
|||
|
|
generalBackoff = 0
|
|||
|
|
connErrorStart = null
|
|||
|
|
generalErrorStart = null
|
|||
|
|
lastPollErrorTime = null
|
|||
|
|
|
|||
|
|
// Null response = no work available in the queue.
|
|||
|
|
// Add a minimum delay to avoid hammering the server.
|
|||
|
|
if (!work) {
|
|||
|
|
// Use live check (not a snapshot) since sessions can end during poll.
|
|||
|
|
const atCap = activeSessions.size >= config.maxSessions
|
|||
|
|
if (atCap) {
|
|||
|
|
const atCapMs = pollConfig.multisession_poll_interval_ms_at_capacity
|
|||
|
|
// Heartbeat loops WITHOUT polling. When at-capacity polling is also
|
|||
|
|
// enabled (atCapMs > 0), the loop tracks a deadline and breaks out
|
|||
|
|
// to poll at that interval — heartbeat and poll compose instead of
|
|||
|
|
// one suppressing the other. We break out to poll when:
|
|||
|
|
// - Poll deadline reached (atCapMs > 0 only)
|
|||
|
|
// - Auth fails (JWT expired → poll refreshes tokens)
|
|||
|
|
// - Capacity wake fires (session ended → poll for new work)
|
|||
|
|
// - Loop aborted (shutdown)
|
|||
|
|
if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) {
|
|||
|
|
logEvent('tengu_bridge_heartbeat_mode_entered', {
|
|||
|
|
active_sessions: activeSessions.size,
|
|||
|
|
heartbeat_interval_ms:
|
|||
|
|
pollConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
})
|
|||
|
|
// Deadline computed once at entry — GB updates to atCapMs don't
|
|||
|
|
// shift an in-flight deadline (next entry picks up the new value).
|
|||
|
|
const pollDeadline = atCapMs > 0 ? Date.now() + atCapMs : null
|
|||
|
|
let hbResult: 'ok' | 'auth_failed' | 'fatal' | 'failed' = 'ok'
|
|||
|
|
let hbCycles = 0
|
|||
|
|
while (
|
|||
|
|
!loopSignal.aborted &&
|
|||
|
|
activeSessions.size >= config.maxSessions &&
|
|||
|
|
(pollDeadline === null || Date.now() < pollDeadline)
|
|||
|
|
) {
|
|||
|
|
// Re-read config each cycle so GrowthBook updates take effect
|
|||
|
|
const hbConfig = getPollIntervalConfig()
|
|||
|
|
if (hbConfig.non_exclusive_heartbeat_interval_ms <= 0) break
|
|||
|
|
|
|||
|
|
// Capture capacity signal BEFORE the async heartbeat call so
|
|||
|
|
// a session ending during the HTTP request is caught by the
|
|||
|
|
// subsequent sleep (instead of being lost to a replaced controller).
|
|||
|
|
const cap = capacityWake.signal()
|
|||
|
|
|
|||
|
|
hbResult = await heartbeatActiveWorkItems()
|
|||
|
|
if (hbResult === 'auth_failed' || hbResult === 'fatal') {
|
|||
|
|
cap.cleanup()
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
hbCycles++
|
|||
|
|
await sleep(
|
|||
|
|
hbConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
cap.cleanup()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Determine exit reason for telemetry
|
|||
|
|
const exitReason =
|
|||
|
|
hbResult === 'auth_failed' || hbResult === 'fatal'
|
|||
|
|
? hbResult
|
|||
|
|
: loopSignal.aborted
|
|||
|
|
? 'shutdown'
|
|||
|
|
: activeSessions.size < config.maxSessions
|
|||
|
|
? 'capacity_changed'
|
|||
|
|
: pollDeadline !== null && Date.now() >= pollDeadline
|
|||
|
|
? 'poll_due'
|
|||
|
|
: 'config_disabled'
|
|||
|
|
logEvent('tengu_bridge_heartbeat_mode_exited', {
|
|||
|
|
reason:
|
|||
|
|
exitReason as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
heartbeat_cycles: hbCycles,
|
|||
|
|
active_sessions: activeSessions.size,
|
|||
|
|
})
|
|||
|
|
if (exitReason === 'poll_due') {
|
|||
|
|
// bridgeApi throttles empty-poll logs (EMPTY_POLL_LOG_INTERVAL=100)
|
|||
|
|
// so the once-per-10min poll_due poll is invisible at counter=2.
|
|||
|
|
// Log it here so verification runs see both endpoints in the debug log.
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:poll] Heartbeat poll_due after ${hbCycles} cycles — falling through to pollForWork`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// On auth_failed or fatal, sleep before polling to avoid a tight
|
|||
|
|
// poll+heartbeat loop. Auth_failed: heartbeatActiveWorkItems
|
|||
|
|
// already called reconnectSession — the sleep gives the server
|
|||
|
|
// time to propagate the re-queue. Fatal (404/410): may be a
|
|||
|
|
// single work item GCd while the environment is still valid.
|
|||
|
|
// Use atCapMs if enabled, else the heartbeat interval as a floor
|
|||
|
|
// (guaranteed > 0 here) so heartbeat-only configs don't tight-loop.
|
|||
|
|
if (hbResult === 'auth_failed' || hbResult === 'fatal') {
|
|||
|
|
const cap = capacityWake.signal()
|
|||
|
|
await sleep(
|
|||
|
|
atCapMs > 0
|
|||
|
|
? atCapMs
|
|||
|
|
: pollConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
cap.cleanup()
|
|||
|
|
}
|
|||
|
|
} else if (atCapMs > 0) {
|
|||
|
|
// Heartbeat disabled: slow poll as liveness signal.
|
|||
|
|
const cap = capacityWake.signal()
|
|||
|
|
await sleep(atCapMs, cap.signal)
|
|||
|
|
cap.cleanup()
|
|||
|
|
}
|
|||
|
|
} else {
|
|||
|
|
const interval =
|
|||
|
|
activeSessions.size > 0
|
|||
|
|
? pollConfig.multisession_poll_interval_ms_partial_capacity
|
|||
|
|
: pollConfig.multisession_poll_interval_ms_not_at_capacity
|
|||
|
|
await sleep(interval, loopSignal)
|
|||
|
|
}
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// At capacity — we polled to keep the heartbeat alive, but cannot
|
|||
|
|
// accept new work right now. We still enter the switch below so that
|
|||
|
|
// token refreshes for existing sessions are processed (the case
|
|||
|
|
// 'session' handler checks for existing sessions before the inner
|
|||
|
|
// capacity guard).
|
|||
|
|
const atCapacityBeforeSwitch = activeSessions.size >= config.maxSessions
|
|||
|
|
|
|||
|
|
// Skip work items that have already been completed and stopped.
|
|||
|
|
// The server may re-deliver stale work before processing our stop
|
|||
|
|
// request, which would otherwise cause a duplicate session spawn.
|
|||
|
|
if (completedWorkIds.has(work.id)) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Skipping already-completed workId=${work.id}`,
|
|||
|
|
)
|
|||
|
|
// Respect capacity throttle — without a sleep here, persistent stale
|
|||
|
|
// redeliveries would tight-loop at poll-request speed (the !work
|
|||
|
|
// branch above is the only sleep, and work != null skips it).
|
|||
|
|
if (atCapacityBeforeSwitch) {
|
|||
|
|
const cap = capacityWake.signal()
|
|||
|
|
if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) {
|
|||
|
|
await heartbeatActiveWorkItems()
|
|||
|
|
await sleep(
|
|||
|
|
pollConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
} else if (pollConfig.multisession_poll_interval_ms_at_capacity > 0) {
|
|||
|
|
await sleep(
|
|||
|
|
pollConfig.multisession_poll_interval_ms_at_capacity,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
cap.cleanup()
|
|||
|
|
} else {
|
|||
|
|
await sleep(1000, loopSignal)
|
|||
|
|
}
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Decode the work secret for session spawning and to extract the JWT
|
|||
|
|
// used for the ack call below.
|
|||
|
|
let secret
|
|||
|
|
try {
|
|||
|
|
secret = decodeWorkSecret(work.secret)
|
|||
|
|
} catch (err) {
|
|||
|
|
const errMsg = errorMessage(err)
|
|||
|
|
logger.logError(
|
|||
|
|
`Failed to decode work secret for workId=${work.id}: ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
logEvent('tengu_bridge_work_secret_failed', {})
|
|||
|
|
// Can't ack (needs the JWT we failed to decode). stopWork uses OAuth,
|
|||
|
|
// so it's callable here — prevents XAUTOCLAIM from re-delivering this
|
|||
|
|
// poisoned item every reclaim_older_than_ms cycle.
|
|||
|
|
completedWorkIds.add(work.id)
|
|||
|
|
trackCleanup(
|
|||
|
|
stopWorkWithRetry(
|
|||
|
|
api,
|
|||
|
|
environmentId,
|
|||
|
|
work.id,
|
|||
|
|
logger,
|
|||
|
|
backoffConfig.stopWorkBaseDelayMs,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
// Respect capacity throttle before retrying — without a sleep here,
|
|||
|
|
// repeated decode failures at capacity would tight-loop at
|
|||
|
|
// poll-request speed (work != null skips the !work sleep above).
|
|||
|
|
if (atCapacityBeforeSwitch) {
|
|||
|
|
const cap = capacityWake.signal()
|
|||
|
|
if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) {
|
|||
|
|
await heartbeatActiveWorkItems()
|
|||
|
|
await sleep(
|
|||
|
|
pollConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
} else if (pollConfig.multisession_poll_interval_ms_at_capacity > 0) {
|
|||
|
|
await sleep(
|
|||
|
|
pollConfig.multisession_poll_interval_ms_at_capacity,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
cap.cleanup()
|
|||
|
|
}
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Explicitly acknowledge after committing to handle the work — NOT
|
|||
|
|
// before. The at-capacity guard inside case 'session' can break
|
|||
|
|
// without spawning; acking there would permanently lose the work.
|
|||
|
|
// Ack failures are non-fatal: server re-delivers, and existingHandle
|
|||
|
|
// / completedWorkIds paths handle the dedup.
|
|||
|
|
const ackWork = async (): Promise<void> => {
|
|||
|
|
logForDebugging(`[bridge:work] Acknowledging workId=${work.id}`)
|
|||
|
|
try {
|
|||
|
|
await api.acknowledgeWork(
|
|||
|
|
environmentId,
|
|||
|
|
work.id,
|
|||
|
|
secret.session_ingress_token,
|
|||
|
|
)
|
|||
|
|
} catch (err) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Acknowledge failed workId=${work.id}: ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const workType: string = work.data.type
|
|||
|
|
switch (work.data.type) {
|
|||
|
|
case 'healthcheck':
|
|||
|
|
await ackWork()
|
|||
|
|
logForDebugging('[bridge:work] Healthcheck received')
|
|||
|
|
logger.logVerbose('Healthcheck received')
|
|||
|
|
break
|
|||
|
|
case 'session': {
|
|||
|
|
const sessionId = work.data.id
|
|||
|
|
try {
|
|||
|
|
validateBridgeId(sessionId, 'session_id')
|
|||
|
|
} catch {
|
|||
|
|
await ackWork()
|
|||
|
|
logger.logError(`Invalid session_id received: ${sessionId}`)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// If the session is already running, deliver the fresh token so
|
|||
|
|
// the child process can reconnect its WebSocket with the new
|
|||
|
|
// session ingress token. This handles the case where the server
|
|||
|
|
// re-dispatches work for an existing session after the WS drops.
|
|||
|
|
const existingHandle = activeSessions.get(sessionId)
|
|||
|
|
if (existingHandle) {
|
|||
|
|
existingHandle.updateAccessToken(secret.session_ingress_token)
|
|||
|
|
sessionIngressTokens.set(sessionId, secret.session_ingress_token)
|
|||
|
|
sessionWorkIds.set(sessionId, work.id)
|
|||
|
|
// Re-schedule next refresh from the fresh JWT's expiry. onRefresh
|
|||
|
|
// branches on v2Sessions so both v1 and v2 are safe here.
|
|||
|
|
tokenRefresh?.schedule(sessionId, secret.session_ingress_token)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Updated access token for existing sessionId=${sessionId} workId=${work.id}`,
|
|||
|
|
)
|
|||
|
|
await ackWork()
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// At capacity — token refresh for existing sessions is handled
|
|||
|
|
// above, but we cannot spawn new ones. The post-switch capacity
|
|||
|
|
// sleep will throttle the loop; just break here.
|
|||
|
|
if (activeSessions.size >= config.maxSessions) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] At capacity (${activeSessions.size}/${config.maxSessions}), cannot spawn new session for workId=${work.id}`,
|
|||
|
|
)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
await ackWork()
|
|||
|
|
const spawnStartTime = Date.now()
|
|||
|
|
|
|||
|
|
// CCR v2 path: register this bridge as the session worker, get the
|
|||
|
|
// epoch, and point the child at /v1/code/sessions/{id}. The child
|
|||
|
|
// already has the full v2 client (SSETransport + CCRClient) — same
|
|||
|
|
// code path environment-manager launches in containers.
|
|||
|
|
//
|
|||
|
|
// v1 path: Session-Ingress WebSocket. Uses config.sessionIngressUrl
|
|||
|
|
// (not secret.api_base_url, which may point to a remote proxy tunnel
|
|||
|
|
// that doesn't know about locally-created sessions).
|
|||
|
|
let sdkUrl: string
|
|||
|
|
let useCcrV2 = false
|
|||
|
|
let workerEpoch: number | undefined
|
|||
|
|
// Server decides per-session via the work secret; env var is the
|
|||
|
|
// ant-dev override (e.g. forcing v2 before the server flag is on).
|
|||
|
|
if (
|
|||
|
|
secret.use_code_sessions === true ||
|
|||
|
|
isEnvTruthy(process.env.CLAUDE_BRIDGE_USE_CCR_V2)
|
|||
|
|
) {
|
|||
|
|
sdkUrl = buildCCRv2SdkUrl(config.apiBaseUrl, sessionId)
|
|||
|
|
// Retry once on transient failure (network blip, 500) before
|
|||
|
|
// permanently giving up and killing the session.
|
|||
|
|
for (let attempt = 1; attempt <= 2; attempt++) {
|
|||
|
|
try {
|
|||
|
|
workerEpoch = await registerWorker(
|
|||
|
|
sdkUrl,
|
|||
|
|
secret.session_ingress_token,
|
|||
|
|
)
|
|||
|
|
useCcrV2 = true
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] CCR v2: registered worker sessionId=${sessionId} epoch=${workerEpoch} attempt=${attempt}`,
|
|||
|
|
)
|
|||
|
|
break
|
|||
|
|
} catch (err) {
|
|||
|
|
const errMsg = errorMessage(err)
|
|||
|
|
if (attempt < 2) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] CCR v2: registerWorker attempt ${attempt} failed, retrying: ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
await sleep(2_000, loopSignal)
|
|||
|
|
if (loopSignal.aborted) break
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
logger.logError(
|
|||
|
|
`CCR v2 worker registration failed for session ${sessionId}: ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
logError(new Error(`registerWorker failed: ${errMsg}`))
|
|||
|
|
completedWorkIds.add(work.id)
|
|||
|
|
trackCleanup(
|
|||
|
|
stopWorkWithRetry(
|
|||
|
|
api,
|
|||
|
|
environmentId,
|
|||
|
|
work.id,
|
|||
|
|
logger,
|
|||
|
|
backoffConfig.stopWorkBaseDelayMs,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
if (!useCcrV2) break
|
|||
|
|
} else {
|
|||
|
|
sdkUrl = buildSdkUrl(config.sessionIngressUrl, sessionId)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// In worktree mode, on-demand sessions get an isolated git worktree
|
|||
|
|
// so concurrent sessions don't interfere with each other's file
|
|||
|
|
// changes. The pre-created initial session (if any) runs in
|
|||
|
|
// config.dir so the user's first session lands in the directory they
|
|||
|
|
// invoked `rc` from — matching the old single-session UX.
|
|||
|
|
// In same-dir and single-session modes, all sessions share config.dir.
|
|||
|
|
// Capture spawnMode before the await below — the `w` key handler
|
|||
|
|
// mutates config.spawnMode directly, and createAgentWorktree can
|
|||
|
|
// take 1-2s, so reading config.spawnMode after the await can
|
|||
|
|
// produce contradictory analytics (spawn_mode:'same-dir', in_worktree:true).
|
|||
|
|
const spawnModeAtDecision = config.spawnMode
|
|||
|
|
let sessionDir = config.dir
|
|||
|
|
let worktreeCreateMs = 0
|
|||
|
|
if (
|
|||
|
|
spawnModeAtDecision === 'worktree' &&
|
|||
|
|
(initialSessionId === undefined ||
|
|||
|
|
!sameSessionId(sessionId, initialSessionId))
|
|||
|
|
) {
|
|||
|
|
const wtStart = Date.now()
|
|||
|
|
try {
|
|||
|
|
const wt = await createAgentWorktree(
|
|||
|
|
`bridge-${safeFilenameId(sessionId)}`,
|
|||
|
|
)
|
|||
|
|
worktreeCreateMs = Date.now() - wtStart
|
|||
|
|
sessionWorktrees.set(sessionId, {
|
|||
|
|
worktreePath: wt.worktreePath,
|
|||
|
|
worktreeBranch: wt.worktreeBranch,
|
|||
|
|
gitRoot: wt.gitRoot,
|
|||
|
|
hookBased: wt.hookBased,
|
|||
|
|
})
|
|||
|
|
sessionDir = wt.worktreePath
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] Created worktree for sessionId=${sessionId} at ${wt.worktreePath}`,
|
|||
|
|
)
|
|||
|
|
} catch (err) {
|
|||
|
|
const errMsg = errorMessage(err)
|
|||
|
|
logger.logError(
|
|||
|
|
`Failed to create worktree for session ${sessionId}: ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
logError(new Error(`Worktree creation failed: ${errMsg}`))
|
|||
|
|
completedWorkIds.add(work.id)
|
|||
|
|
trackCleanup(
|
|||
|
|
stopWorkWithRetry(
|
|||
|
|
api,
|
|||
|
|
environmentId,
|
|||
|
|
work.id,
|
|||
|
|
logger,
|
|||
|
|
backoffConfig.stopWorkBaseDelayMs,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] Spawning sessionId=${sessionId} sdkUrl=${sdkUrl}`,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// compat-surface session_* form for logger/Sessions-API calls.
|
|||
|
|
// Work poll returns cse_* under v2 compat; convert before spawn so
|
|||
|
|
// the onFirstUserMessage callback can close over it.
|
|||
|
|
const compatSessionId = toCompatSessionId(sessionId)
|
|||
|
|
|
|||
|
|
const spawnResult = safeSpawn(
|
|||
|
|
spawner,
|
|||
|
|
{
|
|||
|
|
sessionId,
|
|||
|
|
sdkUrl,
|
|||
|
|
accessToken: secret.session_ingress_token,
|
|||
|
|
useCcrV2,
|
|||
|
|
workerEpoch,
|
|||
|
|
onFirstUserMessage: text => {
|
|||
|
|
// Server-set titles (--name, web rename) win. fetchSessionTitle
|
|||
|
|
// runs concurrently; if it already populated titledSessions,
|
|||
|
|
// skip. If it hasn't resolved yet, the derived title sticks —
|
|||
|
|
// acceptable since the server had no title at spawn time.
|
|||
|
|
if (titledSessions.has(compatSessionId)) return
|
|||
|
|
titledSessions.add(compatSessionId)
|
|||
|
|
const title = deriveSessionTitle(text)
|
|||
|
|
logger.setSessionTitle(compatSessionId, title)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:title] derived title for ${compatSessionId}: ${title}`,
|
|||
|
|
)
|
|||
|
|
void import('./createSession.js')
|
|||
|
|
.then(({ updateBridgeSessionTitle }) =>
|
|||
|
|
updateBridgeSessionTitle(compatSessionId, title, {
|
|||
|
|
baseUrl: config.apiBaseUrl,
|
|||
|
|
}),
|
|||
|
|
)
|
|||
|
|
.catch(err =>
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:title] failed to update title for ${compatSessionId}: ${err}`,
|
|||
|
|
{ level: 'error' },
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
},
|
|||
|
|
},
|
|||
|
|
sessionDir,
|
|||
|
|
)
|
|||
|
|
if (typeof spawnResult === 'string') {
|
|||
|
|
logger.logError(
|
|||
|
|
`Failed to spawn session ${sessionId}: ${spawnResult}`,
|
|||
|
|
)
|
|||
|
|
// Clean up worktree if one was created for this session
|
|||
|
|
const wt = sessionWorktrees.get(sessionId)
|
|||
|
|
if (wt) {
|
|||
|
|
sessionWorktrees.delete(sessionId)
|
|||
|
|
trackCleanup(
|
|||
|
|
removeAgentWorktree(
|
|||
|
|
wt.worktreePath,
|
|||
|
|
wt.worktreeBranch,
|
|||
|
|
wt.gitRoot,
|
|||
|
|
wt.hookBased,
|
|||
|
|
).catch((err: unknown) =>
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Failed to remove worktree ${wt.worktreePath}: ${errorMessage(err)}`,
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
completedWorkIds.add(work.id)
|
|||
|
|
trackCleanup(
|
|||
|
|
stopWorkWithRetry(
|
|||
|
|
api,
|
|||
|
|
environmentId,
|
|||
|
|
work.id,
|
|||
|
|
logger,
|
|||
|
|
backoffConfig.stopWorkBaseDelayMs,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
const handle = spawnResult
|
|||
|
|
|
|||
|
|
const spawnDurationMs = Date.now() - spawnStartTime
|
|||
|
|
logEvent('tengu_bridge_session_started', {
|
|||
|
|
active_sessions: activeSessions.size,
|
|||
|
|
spawn_mode:
|
|||
|
|
spawnModeAtDecision as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
in_worktree: sessionWorktrees.has(sessionId),
|
|||
|
|
spawn_duration_ms: spawnDurationMs,
|
|||
|
|
worktree_create_ms: worktreeCreateMs,
|
|||
|
|
inProtectedNamespace: isInProtectedNamespace(),
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_session_started', {
|
|||
|
|
spawn_mode: spawnModeAtDecision,
|
|||
|
|
in_worktree: sessionWorktrees.has(sessionId),
|
|||
|
|
spawn_duration_ms: spawnDurationMs,
|
|||
|
|
worktree_create_ms: worktreeCreateMs,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
activeSessions.set(sessionId, handle)
|
|||
|
|
sessionWorkIds.set(sessionId, work.id)
|
|||
|
|
sessionIngressTokens.set(sessionId, secret.session_ingress_token)
|
|||
|
|
sessionCompatIds.set(sessionId, compatSessionId)
|
|||
|
|
|
|||
|
|
const startTime = Date.now()
|
|||
|
|
sessionStartTimes.set(sessionId, startTime)
|
|||
|
|
|
|||
|
|
// Use a generic prompt description since we no longer get startup_context
|
|||
|
|
logger.logSessionStart(sessionId, `Session ${sessionId}`)
|
|||
|
|
|
|||
|
|
// Compute the actual debug file path (mirrors sessionRunner.ts logic)
|
|||
|
|
const safeId = safeFilenameId(sessionId)
|
|||
|
|
let sessionDebugFile: string | undefined
|
|||
|
|
if (config.debugFile) {
|
|||
|
|
const ext = config.debugFile.lastIndexOf('.')
|
|||
|
|
if (ext > 0) {
|
|||
|
|
sessionDebugFile = `${config.debugFile.slice(0, ext)}-${safeId}${config.debugFile.slice(ext)}`
|
|||
|
|
} else {
|
|||
|
|
sessionDebugFile = `${config.debugFile}-${safeId}`
|
|||
|
|
}
|
|||
|
|
} else if (config.verbose || process.env.USER_TYPE === 'ant') {
|
|||
|
|
sessionDebugFile = join(
|
|||
|
|
tmpdir(),
|
|||
|
|
'claude',
|
|||
|
|
`bridge-session-${safeId}.log`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (sessionDebugFile) {
|
|||
|
|
logger.logVerbose(`Debug log: ${sessionDebugFile}`)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Register in the sessions Map before starting status updates so the
|
|||
|
|
// first render tick shows the correct count and bullet list in sync.
|
|||
|
|
logger.addSession(
|
|||
|
|
compatSessionId,
|
|||
|
|
getRemoteSessionUrl(compatSessionId, config.sessionIngressUrl),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Start live status updates and transition to "Attached" state.
|
|||
|
|
startStatusUpdates()
|
|||
|
|
logger.setAttached(compatSessionId)
|
|||
|
|
|
|||
|
|
// One-shot title fetch. If the session already has a title (set via
|
|||
|
|
// --name, web rename, or /remote-control), display it and mark as
|
|||
|
|
// titled so the first-user-message fallback doesn't overwrite it.
|
|||
|
|
// Otherwise onFirstUserMessage derives one from the first prompt.
|
|||
|
|
void fetchSessionTitle(compatSessionId, config.apiBaseUrl)
|
|||
|
|
.then(title => {
|
|||
|
|
if (title && activeSessions.has(sessionId)) {
|
|||
|
|
titledSessions.add(compatSessionId)
|
|||
|
|
logger.setSessionTitle(compatSessionId, title)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:title] server title for ${compatSessionId}: ${title}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
})
|
|||
|
|
.catch(err =>
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:title] failed to fetch title for ${compatSessionId}: ${err}`,
|
|||
|
|
{ level: 'error' },
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Start per-session timeout watchdog
|
|||
|
|
const timeoutMs =
|
|||
|
|
config.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS
|
|||
|
|
if (timeoutMs > 0) {
|
|||
|
|
const timer = setTimeout(
|
|||
|
|
onSessionTimeout,
|
|||
|
|
timeoutMs,
|
|||
|
|
sessionId,
|
|||
|
|
timeoutMs,
|
|||
|
|
logger,
|
|||
|
|
timedOutSessions,
|
|||
|
|
handle,
|
|||
|
|
)
|
|||
|
|
sessionTimers.set(sessionId, timer)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Schedule proactive token refresh before the JWT expires.
|
|||
|
|
// onRefresh branches on v2Sessions: v1 delivers OAuth to the
|
|||
|
|
// child, v2 triggers server re-dispatch via reconnectSession.
|
|||
|
|
if (useCcrV2) {
|
|||
|
|
v2Sessions.add(sessionId)
|
|||
|
|
}
|
|||
|
|
tokenRefresh?.schedule(sessionId, secret.session_ingress_token)
|
|||
|
|
|
|||
|
|
void handle.done.then(onSessionDone(sessionId, startTime, handle))
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
default:
|
|||
|
|
await ackWork()
|
|||
|
|
// Gracefully ignore unknown work types. The backend may send new
|
|||
|
|
// types before the bridge client is updated.
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Unknown work type: ${workType}, skipping`,
|
|||
|
|
)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// When at capacity, throttle the loop. The switch above still runs so
|
|||
|
|
// existing-session token refreshes are processed, but we sleep here
|
|||
|
|
// to avoid busy-looping. Include the capacity wake signal so the
|
|||
|
|
// sleep is interrupted immediately when a session completes.
|
|||
|
|
if (atCapacityBeforeSwitch) {
|
|||
|
|
const cap = capacityWake.signal()
|
|||
|
|
if (pollConfig.non_exclusive_heartbeat_interval_ms > 0) {
|
|||
|
|
await heartbeatActiveWorkItems()
|
|||
|
|
await sleep(
|
|||
|
|
pollConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
} else if (pollConfig.multisession_poll_interval_ms_at_capacity > 0) {
|
|||
|
|
await sleep(
|
|||
|
|
pollConfig.multisession_poll_interval_ms_at_capacity,
|
|||
|
|
cap.signal,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
cap.cleanup()
|
|||
|
|
}
|
|||
|
|
} catch (err) {
|
|||
|
|
if (loopSignal.aborted) {
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Fatal errors (401/403) — no point retrying, auth won't fix itself
|
|||
|
|
if (err instanceof BridgeFatalError) {
|
|||
|
|
fatalExit = true
|
|||
|
|
// Server-enforced expiry gets a clean status message, not an error
|
|||
|
|
if (isExpiredErrorType(err.errorType)) {
|
|||
|
|
logger.logStatus(err.message)
|
|||
|
|
} else if (isSuppressible403(err)) {
|
|||
|
|
// Cosmetic 403 errors (e.g., external_poll_sessions scope,
|
|||
|
|
// environments:manage permission) — don't show to user
|
|||
|
|
logForDebugging(`[bridge:work] Suppressed 403 error: ${err.message}`)
|
|||
|
|
} else {
|
|||
|
|
logger.logError(err.message)
|
|||
|
|
logError(err)
|
|||
|
|
}
|
|||
|
|
logEvent('tengu_bridge_fatal_error', {
|
|||
|
|
status: err.status,
|
|||
|
|
error_type:
|
|||
|
|
err.errorType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII(
|
|||
|
|
isExpiredErrorType(err.errorType) ? 'info' : 'error',
|
|||
|
|
'bridge_fatal_error',
|
|||
|
|
{ status: err.status, error_type: err.errorType },
|
|||
|
|
)
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const errMsg = describeAxiosError(err)
|
|||
|
|
|
|||
|
|
if (isConnectionError(err) || isServerError(err)) {
|
|||
|
|
const now = Date.now()
|
|||
|
|
|
|||
|
|
// Detect system sleep/wake: if the gap since the last poll error
|
|||
|
|
// greatly exceeds the expected backoff, the machine likely slept.
|
|||
|
|
// Reset error tracking so the bridge retries with a fresh budget.
|
|||
|
|
if (
|
|||
|
|
lastPollErrorTime !== null &&
|
|||
|
|
now - lastPollErrorTime > pollSleepDetectionThresholdMs(backoffConfig)
|
|||
|
|
) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Detected system sleep (${Math.round((now - lastPollErrorTime) / 1000)}s gap), resetting error budget`,
|
|||
|
|
)
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_poll_sleep_detected', {
|
|||
|
|
gapMs: now - lastPollErrorTime,
|
|||
|
|
})
|
|||
|
|
connErrorStart = null
|
|||
|
|
connBackoff = 0
|
|||
|
|
generalErrorStart = null
|
|||
|
|
generalBackoff = 0
|
|||
|
|
}
|
|||
|
|
lastPollErrorTime = now
|
|||
|
|
|
|||
|
|
if (!connErrorStart) {
|
|||
|
|
connErrorStart = now
|
|||
|
|
}
|
|||
|
|
const elapsed = now - connErrorStart
|
|||
|
|
if (elapsed >= backoffConfig.connGiveUpMs) {
|
|||
|
|
logger.logError(
|
|||
|
|
`Server unreachable for ${Math.round(elapsed / 60_000)} minutes, giving up.`,
|
|||
|
|
)
|
|||
|
|
logEvent('tengu_bridge_poll_give_up', {
|
|||
|
|
error_type:
|
|||
|
|
'connection' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
elapsed_ms: elapsed,
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII('error', 'bridge_poll_give_up', {
|
|||
|
|
error_type: 'connection',
|
|||
|
|
elapsed_ms: elapsed,
|
|||
|
|
})
|
|||
|
|
fatalExit = true
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Reset the other track when switching error types
|
|||
|
|
generalErrorStart = null
|
|||
|
|
generalBackoff = 0
|
|||
|
|
|
|||
|
|
connBackoff = connBackoff
|
|||
|
|
? Math.min(connBackoff * 2, backoffConfig.connCapMs)
|
|||
|
|
: backoffConfig.connInitialMs
|
|||
|
|
const delay = addJitter(connBackoff)
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Connection error, retrying in ${formatDelay(delay)} (${Math.round(elapsed / 1000)}s elapsed): ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
logger.updateReconnectingStatus(
|
|||
|
|
formatDelay(delay),
|
|||
|
|
formatDuration(elapsed),
|
|||
|
|
)
|
|||
|
|
// The poll_due heartbeat-loop exit leaves a healthy lease exposed to
|
|||
|
|
// this backoff path. Heartbeat before each sleep so /poll outages
|
|||
|
|
// (the VerifyEnvironmentSecretAuth DB path heartbeat was introduced
|
|||
|
|
// to avoid) don't kill the 300s lease TTL. No-op when activeSessions
|
|||
|
|
// is empty or heartbeat is disabled.
|
|||
|
|
if (getPollIntervalConfig().non_exclusive_heartbeat_interval_ms > 0) {
|
|||
|
|
await heartbeatActiveWorkItems()
|
|||
|
|
}
|
|||
|
|
await sleep(delay, loopSignal)
|
|||
|
|
} else {
|
|||
|
|
const now = Date.now()
|
|||
|
|
|
|||
|
|
// Sleep detection for general errors (same logic as connection errors)
|
|||
|
|
if (
|
|||
|
|
lastPollErrorTime !== null &&
|
|||
|
|
now - lastPollErrorTime > pollSleepDetectionThresholdMs(backoffConfig)
|
|||
|
|
) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Detected system sleep (${Math.round((now - lastPollErrorTime) / 1000)}s gap), resetting error budget`,
|
|||
|
|
)
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_poll_sleep_detected', {
|
|||
|
|
gapMs: now - lastPollErrorTime,
|
|||
|
|
})
|
|||
|
|
connErrorStart = null
|
|||
|
|
connBackoff = 0
|
|||
|
|
generalErrorStart = null
|
|||
|
|
generalBackoff = 0
|
|||
|
|
}
|
|||
|
|
lastPollErrorTime = now
|
|||
|
|
|
|||
|
|
if (!generalErrorStart) {
|
|||
|
|
generalErrorStart = now
|
|||
|
|
}
|
|||
|
|
const elapsed = now - generalErrorStart
|
|||
|
|
if (elapsed >= backoffConfig.generalGiveUpMs) {
|
|||
|
|
logger.logError(
|
|||
|
|
`Persistent errors for ${Math.round(elapsed / 60_000)} minutes, giving up.`,
|
|||
|
|
)
|
|||
|
|
logEvent('tengu_bridge_poll_give_up', {
|
|||
|
|
error_type:
|
|||
|
|
'general' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
elapsed_ms: elapsed,
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII('error', 'bridge_poll_give_up', {
|
|||
|
|
error_type: 'general',
|
|||
|
|
elapsed_ms: elapsed,
|
|||
|
|
})
|
|||
|
|
fatalExit = true
|
|||
|
|
break
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Reset the other track when switching error types
|
|||
|
|
connErrorStart = null
|
|||
|
|
connBackoff = 0
|
|||
|
|
|
|||
|
|
generalBackoff = generalBackoff
|
|||
|
|
? Math.min(generalBackoff * 2, backoffConfig.generalCapMs)
|
|||
|
|
: backoffConfig.generalInitialMs
|
|||
|
|
const delay = addJitter(generalBackoff)
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Poll failed, retrying in ${formatDelay(delay)} (${Math.round(elapsed / 1000)}s elapsed): ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
logger.updateReconnectingStatus(
|
|||
|
|
formatDelay(delay),
|
|||
|
|
formatDuration(elapsed),
|
|||
|
|
)
|
|||
|
|
if (getPollIntervalConfig().non_exclusive_heartbeat_interval_ms > 0) {
|
|||
|
|
await heartbeatActiveWorkItems()
|
|||
|
|
}
|
|||
|
|
await sleep(delay, loopSignal)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Clean up
|
|||
|
|
stopStatusUpdates()
|
|||
|
|
logger.clearStatus()
|
|||
|
|
|
|||
|
|
const loopDurationMs = Date.now() - loopStartTime
|
|||
|
|
logEvent('tengu_bridge_shutdown', {
|
|||
|
|
active_sessions: activeSessions.size,
|
|||
|
|
loop_duration_ms: loopDurationMs,
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_shutdown', {
|
|||
|
|
active_sessions: activeSessions.size,
|
|||
|
|
loop_duration_ms: loopDurationMs,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// Graceful shutdown: kill active sessions, report them as interrupted,
|
|||
|
|
// archive sessions, then deregister the environment so the web UI shows
|
|||
|
|
// the bridge as offline.
|
|||
|
|
|
|||
|
|
// Collect all session IDs to archive on exit. This includes:
|
|||
|
|
// 1. Active sessions (snapshot before killing — onSessionDone clears maps)
|
|||
|
|
// 2. The initial auto-created session (may never have had work dispatched)
|
|||
|
|
// api.archiveSession is idempotent (409 if already archived), so
|
|||
|
|
// double-archiving is safe.
|
|||
|
|
const sessionsToArchive = new Set(activeSessions.keys())
|
|||
|
|
if (initialSessionId) {
|
|||
|
|
sessionsToArchive.add(initialSessionId)
|
|||
|
|
}
|
|||
|
|
// Snapshot before killing — onSessionDone clears sessionCompatIds.
|
|||
|
|
const compatIdSnapshot = new Map(sessionCompatIds)
|
|||
|
|
|
|||
|
|
if (activeSessions.size > 0) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:shutdown] Shutting down ${activeSessions.size} active session(s)`,
|
|||
|
|
)
|
|||
|
|
logger.logStatus(
|
|||
|
|
`Shutting down ${activeSessions.size} active session(s)\u2026`,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Snapshot work IDs before killing — onSessionDone clears the maps when
|
|||
|
|
// each child exits, so we need a copy for the stopWork calls below.
|
|||
|
|
const shutdownWorkIds = new Map(sessionWorkIds)
|
|||
|
|
|
|||
|
|
for (const [sessionId, handle] of activeSessions.entries()) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:shutdown] Sending SIGTERM to sessionId=${sessionId}`,
|
|||
|
|
)
|
|||
|
|
handle.kill()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const timeout = new AbortController()
|
|||
|
|
await Promise.race([
|
|||
|
|
Promise.allSettled([...activeSessions.values()].map(h => h.done)),
|
|||
|
|
sleep(backoffConfig.shutdownGraceMs ?? 30_000, timeout.signal),
|
|||
|
|
])
|
|||
|
|
timeout.abort()
|
|||
|
|
|
|||
|
|
// SIGKILL any processes that didn't respond to SIGTERM within the grace window
|
|||
|
|
for (const [sid, handle] of activeSessions.entries()) {
|
|||
|
|
logForDebugging(`[bridge:shutdown] Force-killing stuck sessionId=${sid}`)
|
|||
|
|
handle.forceKill()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Clear any remaining session timeout and refresh timers
|
|||
|
|
for (const timer of sessionTimers.values()) {
|
|||
|
|
clearTimeout(timer)
|
|||
|
|
}
|
|||
|
|
sessionTimers.clear()
|
|||
|
|
tokenRefresh?.cancelAll()
|
|||
|
|
|
|||
|
|
// Clean up any remaining worktrees from active sessions.
|
|||
|
|
// Snapshot and clear the map first so onSessionDone (which may fire
|
|||
|
|
// during the await below when handle.done resolves) won't try to
|
|||
|
|
// remove the same worktrees again.
|
|||
|
|
if (sessionWorktrees.size > 0) {
|
|||
|
|
const remainingWorktrees = [...sessionWorktrees.values()]
|
|||
|
|
sessionWorktrees.clear()
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:shutdown] Cleaning up ${remainingWorktrees.length} worktree(s)`,
|
|||
|
|
)
|
|||
|
|
await Promise.allSettled(
|
|||
|
|
remainingWorktrees.map(wt =>
|
|||
|
|
removeAgentWorktree(
|
|||
|
|
wt.worktreePath,
|
|||
|
|
wt.worktreeBranch,
|
|||
|
|
wt.gitRoot,
|
|||
|
|
wt.hookBased,
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Stop all active work items so the server knows they're done
|
|||
|
|
await Promise.allSettled(
|
|||
|
|
[...shutdownWorkIds.entries()].map(([sessionId, workId]) => {
|
|||
|
|
return api
|
|||
|
|
.stopWork(environmentId, workId, true)
|
|||
|
|
.catch(err =>
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Failed to stop work ${workId} for session ${sessionId}: ${errorMessage(err)}`,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
}),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Ensure all in-flight cleanup (stopWork, worktree removal) from
|
|||
|
|
// onSessionDone completes before deregistering — otherwise
|
|||
|
|
// process.exit() can kill them mid-flight.
|
|||
|
|
if (pendingCleanups.size > 0) {
|
|||
|
|
await Promise.allSettled([...pendingCleanups])
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// In single-session mode with a known session, leave the session and
|
|||
|
|
// environment alive so `claude remote-control --session-id=<id>` can resume.
|
|||
|
|
// The backend GCs stale environments via a 4h TTL (BRIDGE_LAST_POLL_TTL).
|
|||
|
|
// Archiving the session or deregistering the environment would make the
|
|||
|
|
// printed resume command a lie — deregister deletes Firestore + Redis stream.
|
|||
|
|
// Skip when the loop exited fatally (env expired, auth failed, give-up) —
|
|||
|
|
// resume is impossible in those cases and the message would contradict the
|
|||
|
|
// error already printed.
|
|||
|
|
// feature('KAIROS') gate: --session-id is ant-only; without the gate,
|
|||
|
|
// revert to the pre-PR behavior (archive + deregister on every shutdown).
|
|||
|
|
if (
|
|||
|
|
feature('KAIROS') &&
|
|||
|
|
config.spawnMode === 'single-session' &&
|
|||
|
|
initialSessionId &&
|
|||
|
|
!fatalExit
|
|||
|
|
) {
|
|||
|
|
logger.logStatus(
|
|||
|
|
`Resume this session by running \`claude remote-control --continue\``,
|
|||
|
|
)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:shutdown] Skipping archive+deregister to allow resume of session ${initialSessionId}`,
|
|||
|
|
)
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Archive all known sessions so they don't linger as idle/running on the
|
|||
|
|
// server after the bridge goes offline.
|
|||
|
|
if (sessionsToArchive.size > 0) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:shutdown] Archiving ${sessionsToArchive.size} session(s)`,
|
|||
|
|
)
|
|||
|
|
await Promise.allSettled(
|
|||
|
|
[...sessionsToArchive].map(sessionId =>
|
|||
|
|
api
|
|||
|
|
.archiveSession(
|
|||
|
|
compatIdSnapshot.get(sessionId) ?? toCompatSessionId(sessionId),
|
|||
|
|
)
|
|||
|
|
.catch(err =>
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Failed to archive session ${sessionId}: ${errorMessage(err)}`,
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Deregister the environment so the web UI shows the bridge as offline
|
|||
|
|
// and the Redis stream is cleaned up.
|
|||
|
|
try {
|
|||
|
|
await api.deregisterEnvironment(environmentId)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:shutdown] Environment deregistered, bridge offline`,
|
|||
|
|
)
|
|||
|
|
logger.logVerbose('Environment deregistered.')
|
|||
|
|
} catch (err) {
|
|||
|
|
logger.logVerbose(`Failed to deregister environment: ${errorMessage(err)}`)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Clear the crash-recovery pointer — the env is gone, pointer would be
|
|||
|
|
// stale. The early return above (resumable SIGINT shutdown) skips this,
|
|||
|
|
// leaving the pointer as a backup for the printed --session-id hint.
|
|||
|
|
const { clearBridgePointer } = await import('./bridgePointer.js')
|
|||
|
|
await clearBridgePointer(config.dir)
|
|||
|
|
|
|||
|
|
logger.logVerbose('Environment offline.')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const CONNECTION_ERROR_CODES = new Set([
|
|||
|
|
'ECONNREFUSED',
|
|||
|
|
'ECONNRESET',
|
|||
|
|
'ETIMEDOUT',
|
|||
|
|
'ENETUNREACH',
|
|||
|
|
'EHOSTUNREACH',
|
|||
|
|
])
|
|||
|
|
|
|||
|
|
export function isConnectionError(err: unknown): boolean {
|
|||
|
|
if (
|
|||
|
|
err &&
|
|||
|
|
typeof err === 'object' &&
|
|||
|
|
'code' in err &&
|
|||
|
|
typeof err.code === 'string' &&
|
|||
|
|
CONNECTION_ERROR_CODES.has(err.code)
|
|||
|
|
) {
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Detect HTTP 5xx errors from axios (code: 'ERR_BAD_RESPONSE'). */
|
|||
|
|
export function isServerError(err: unknown): boolean {
|
|||
|
|
return (
|
|||
|
|
!!err &&
|
|||
|
|
typeof err === 'object' &&
|
|||
|
|
'code' in err &&
|
|||
|
|
typeof err.code === 'string' &&
|
|||
|
|
err.code === 'ERR_BAD_RESPONSE'
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** Add ±25% jitter to a delay value. */
|
|||
|
|
function addJitter(ms: number): number {
|
|||
|
|
return Math.max(0, ms + ms * 0.25 * (2 * Math.random() - 1))
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function formatDelay(ms: number): string {
|
|||
|
|
return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Retry stopWork with exponential backoff (3 attempts, 1s/2s/4s).
|
|||
|
|
* Ensures the server learns the work item ended, preventing server-side zombies.
|
|||
|
|
*/
|
|||
|
|
async function stopWorkWithRetry(
|
|||
|
|
api: BridgeApiClient,
|
|||
|
|
environmentId: string,
|
|||
|
|
workId: string,
|
|||
|
|
logger: BridgeLogger,
|
|||
|
|
baseDelayMs = 1000,
|
|||
|
|
): Promise<void> {
|
|||
|
|
const MAX_ATTEMPTS = 3
|
|||
|
|
|
|||
|
|
for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
|
|||
|
|
try {
|
|||
|
|
await api.stopWork(environmentId, workId, false)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] stopWork succeeded for workId=${workId} on attempt ${attempt}/${MAX_ATTEMPTS}`,
|
|||
|
|
)
|
|||
|
|
return
|
|||
|
|
} catch (err) {
|
|||
|
|
// Auth/permission errors won't be fixed by retrying
|
|||
|
|
if (err instanceof BridgeFatalError) {
|
|||
|
|
if (isSuppressible403(err)) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:work] Suppressed stopWork 403 for ${workId}: ${err.message}`,
|
|||
|
|
)
|
|||
|
|
} else {
|
|||
|
|
logger.logError(`Failed to stop work ${workId}: ${err.message}`)
|
|||
|
|
}
|
|||
|
|
logForDiagnosticsNoPII('error', 'bridge_stop_work_failed', {
|
|||
|
|
attempts: attempt,
|
|||
|
|
fatal: true,
|
|||
|
|
})
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
const errMsg = errorMessage(err)
|
|||
|
|
if (attempt < MAX_ATTEMPTS) {
|
|||
|
|
const delay = addJitter(baseDelayMs * Math.pow(2, attempt - 1))
|
|||
|
|
logger.logVerbose(
|
|||
|
|
`Failed to stop work ${workId} (attempt ${attempt}/${MAX_ATTEMPTS}), retrying in ${formatDelay(delay)}: ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
await sleep(delay)
|
|||
|
|
} else {
|
|||
|
|
logger.logError(
|
|||
|
|
`Failed to stop work ${workId} after ${MAX_ATTEMPTS} attempts: ${errMsg}`,
|
|||
|
|
)
|
|||
|
|
logForDiagnosticsNoPII('error', 'bridge_stop_work_failed', {
|
|||
|
|
attempts: MAX_ATTEMPTS,
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function onSessionTimeout(
|
|||
|
|
sessionId: string,
|
|||
|
|
timeoutMs: number,
|
|||
|
|
logger: BridgeLogger,
|
|||
|
|
timedOutSessions: Set<string>,
|
|||
|
|
handle: SessionHandle,
|
|||
|
|
): void {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:session] sessionId=${sessionId} timed out after ${formatDuration(timeoutMs)}`,
|
|||
|
|
)
|
|||
|
|
logEvent('tengu_bridge_session_timeout', {
|
|||
|
|
timeout_ms: timeoutMs,
|
|||
|
|
})
|
|||
|
|
logger.logSessionFailed(
|
|||
|
|
sessionId,
|
|||
|
|
`Session timed out after ${formatDuration(timeoutMs)}`,
|
|||
|
|
)
|
|||
|
|
timedOutSessions.add(sessionId)
|
|||
|
|
handle.kill()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export type ParsedArgs = {
|
|||
|
|
verbose: boolean
|
|||
|
|
sandbox: boolean
|
|||
|
|
debugFile?: string
|
|||
|
|
sessionTimeoutMs?: number
|
|||
|
|
permissionMode?: string
|
|||
|
|
name?: string
|
|||
|
|
/** Value passed to --spawn (if any); undefined if no --spawn flag was given. */
|
|||
|
|
spawnMode: SpawnMode | undefined
|
|||
|
|
/** Value passed to --capacity (if any); undefined if no --capacity flag was given. */
|
|||
|
|
capacity: number | undefined
|
|||
|
|
/** --[no-]create-session-in-dir override; undefined = use default (on). */
|
|||
|
|
createSessionInDir: boolean | undefined
|
|||
|
|
/** Resume an existing session instead of creating a new one. */
|
|||
|
|
sessionId?: string
|
|||
|
|
/** Resume the last session in this directory (reads bridge-pointer.json). */
|
|||
|
|
continueSession: boolean
|
|||
|
|
help: boolean
|
|||
|
|
error?: string
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const SPAWN_FLAG_VALUES = ['session', 'same-dir', 'worktree'] as const
|
|||
|
|
|
|||
|
|
function parseSpawnValue(raw: string | undefined): SpawnMode | string {
|
|||
|
|
if (raw === 'session') return 'single-session'
|
|||
|
|
if (raw === 'same-dir') return 'same-dir'
|
|||
|
|
if (raw === 'worktree') return 'worktree'
|
|||
|
|
return `--spawn requires one of: ${SPAWN_FLAG_VALUES.join(', ')} (got: ${raw ?? '<missing>'})`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function parseCapacityValue(raw: string | undefined): number | string {
|
|||
|
|
const n = raw === undefined ? NaN : parseInt(raw, 10)
|
|||
|
|
if (isNaN(n) || n < 1) {
|
|||
|
|
return `--capacity requires a positive integer (got: ${raw ?? '<missing>'})`
|
|||
|
|
}
|
|||
|
|
return n
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export function parseArgs(args: string[]): ParsedArgs {
|
|||
|
|
let verbose = false
|
|||
|
|
let sandbox = false
|
|||
|
|
let debugFile: string | undefined
|
|||
|
|
let sessionTimeoutMs: number | undefined
|
|||
|
|
let permissionMode: string | undefined
|
|||
|
|
let name: string | undefined
|
|||
|
|
let help = false
|
|||
|
|
let spawnMode: SpawnMode | undefined
|
|||
|
|
let capacity: number | undefined
|
|||
|
|
let createSessionInDir: boolean | undefined
|
|||
|
|
let sessionId: string | undefined
|
|||
|
|
let continueSession = false
|
|||
|
|
|
|||
|
|
for (let i = 0; i < args.length; i++) {
|
|||
|
|
const arg = args[i]!
|
|||
|
|
if (arg === '--help' || arg === '-h') {
|
|||
|
|
help = true
|
|||
|
|
} else if (arg === '--verbose' || arg === '-v') {
|
|||
|
|
verbose = true
|
|||
|
|
} else if (arg === '--sandbox') {
|
|||
|
|
sandbox = true
|
|||
|
|
} else if (arg === '--no-sandbox') {
|
|||
|
|
sandbox = false
|
|||
|
|
} else if (arg === '--debug-file' && i + 1 < args.length) {
|
|||
|
|
debugFile = resolve(args[++i]!)
|
|||
|
|
} else if (arg.startsWith('--debug-file=')) {
|
|||
|
|
debugFile = resolve(arg.slice('--debug-file='.length))
|
|||
|
|
} else if (arg === '--session-timeout' && i + 1 < args.length) {
|
|||
|
|
sessionTimeoutMs = parseInt(args[++i]!, 10) * 1000
|
|||
|
|
} else if (arg.startsWith('--session-timeout=')) {
|
|||
|
|
sessionTimeoutMs =
|
|||
|
|
parseInt(arg.slice('--session-timeout='.length), 10) * 1000
|
|||
|
|
} else if (arg === '--permission-mode' && i + 1 < args.length) {
|
|||
|
|
permissionMode = args[++i]!
|
|||
|
|
} else if (arg.startsWith('--permission-mode=')) {
|
|||
|
|
permissionMode = arg.slice('--permission-mode='.length)
|
|||
|
|
} else if (arg === '--name' && i + 1 < args.length) {
|
|||
|
|
name = args[++i]!
|
|||
|
|
} else if (arg.startsWith('--name=')) {
|
|||
|
|
name = arg.slice('--name='.length)
|
|||
|
|
} else if (
|
|||
|
|
feature('KAIROS') &&
|
|||
|
|
arg === '--session-id' &&
|
|||
|
|
i + 1 < args.length
|
|||
|
|
) {
|
|||
|
|
sessionId = args[++i]!
|
|||
|
|
if (!sessionId) {
|
|||
|
|
return makeError('--session-id requires a value')
|
|||
|
|
}
|
|||
|
|
} else if (feature('KAIROS') && arg.startsWith('--session-id=')) {
|
|||
|
|
sessionId = arg.slice('--session-id='.length)
|
|||
|
|
if (!sessionId) {
|
|||
|
|
return makeError('--session-id requires a value')
|
|||
|
|
}
|
|||
|
|
} else if (feature('KAIROS') && (arg === '--continue' || arg === '-c')) {
|
|||
|
|
continueSession = true
|
|||
|
|
} else if (arg === '--spawn' || arg.startsWith('--spawn=')) {
|
|||
|
|
if (spawnMode !== undefined) {
|
|||
|
|
return makeError('--spawn may only be specified once')
|
|||
|
|
}
|
|||
|
|
const raw = arg.startsWith('--spawn=')
|
|||
|
|
? arg.slice('--spawn='.length)
|
|||
|
|
: args[++i]
|
|||
|
|
const v = parseSpawnValue(raw)
|
|||
|
|
if (v === 'single-session' || v === 'same-dir' || v === 'worktree') {
|
|||
|
|
spawnMode = v
|
|||
|
|
} else {
|
|||
|
|
return makeError(v)
|
|||
|
|
}
|
|||
|
|
} else if (arg === '--capacity' || arg.startsWith('--capacity=')) {
|
|||
|
|
if (capacity !== undefined) {
|
|||
|
|
return makeError('--capacity may only be specified once')
|
|||
|
|
}
|
|||
|
|
const raw = arg.startsWith('--capacity=')
|
|||
|
|
? arg.slice('--capacity='.length)
|
|||
|
|
: args[++i]
|
|||
|
|
const v = parseCapacityValue(raw)
|
|||
|
|
if (typeof v === 'number') capacity = v
|
|||
|
|
else return makeError(v)
|
|||
|
|
} else if (arg === '--create-session-in-dir') {
|
|||
|
|
createSessionInDir = true
|
|||
|
|
} else if (arg === '--no-create-session-in-dir') {
|
|||
|
|
createSessionInDir = false
|
|||
|
|
} else {
|
|||
|
|
return makeError(
|
|||
|
|
`Unknown argument: ${arg}\nRun 'claude remote-control --help' for usage.`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Note: gate check for --spawn/--capacity/--create-session-in-dir is in bridgeMain
|
|||
|
|
// (gate-aware error). Flag cross-validation happens here.
|
|||
|
|
|
|||
|
|
// --capacity only makes sense for multi-session modes.
|
|||
|
|
if (spawnMode === 'single-session' && capacity !== undefined) {
|
|||
|
|
return makeError(
|
|||
|
|
`--capacity cannot be used with --spawn=session (single-session mode has fixed capacity 1).`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// --session-id / --continue resume a specific session on its original
|
|||
|
|
// environment; incompatible with spawn-related flags (which configure
|
|||
|
|
// fresh session creation), and mutually exclusive with each other.
|
|||
|
|
if (
|
|||
|
|
(sessionId || continueSession) &&
|
|||
|
|
(spawnMode !== undefined ||
|
|||
|
|
capacity !== undefined ||
|
|||
|
|
createSessionInDir !== undefined)
|
|||
|
|
) {
|
|||
|
|
return makeError(
|
|||
|
|
`--session-id and --continue cannot be used with --spawn, --capacity, or --create-session-in-dir.`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
if (sessionId && continueSession) {
|
|||
|
|
return makeError(`--session-id and --continue cannot be used together.`)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
verbose,
|
|||
|
|
sandbox,
|
|||
|
|
debugFile,
|
|||
|
|
sessionTimeoutMs,
|
|||
|
|
permissionMode,
|
|||
|
|
name,
|
|||
|
|
spawnMode,
|
|||
|
|
capacity,
|
|||
|
|
createSessionInDir,
|
|||
|
|
sessionId,
|
|||
|
|
continueSession,
|
|||
|
|
help,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function makeError(error: string): ParsedArgs {
|
|||
|
|
return {
|
|||
|
|
verbose,
|
|||
|
|
sandbox,
|
|||
|
|
debugFile,
|
|||
|
|
sessionTimeoutMs,
|
|||
|
|
permissionMode,
|
|||
|
|
name,
|
|||
|
|
spawnMode,
|
|||
|
|
capacity,
|
|||
|
|
createSessionInDir,
|
|||
|
|
sessionId,
|
|||
|
|
continueSession,
|
|||
|
|
help,
|
|||
|
|
error,
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async function printHelp(): Promise<void> {
|
|||
|
|
// Use EXTERNAL_PERMISSION_MODES for help text — internal modes (bubble)
|
|||
|
|
// are ant-only and auto is feature-gated; they're still accepted by validation.
|
|||
|
|
const { EXTERNAL_PERMISSION_MODES } = await import('../types/permissions.js')
|
|||
|
|
const modes = EXTERNAL_PERMISSION_MODES.join(', ')
|
|||
|
|
const showServer = await isMultiSessionSpawnEnabled()
|
|||
|
|
const serverOptions = showServer
|
|||
|
|
? ` --spawn <mode> Spawn mode: same-dir, worktree, session
|
|||
|
|
(default: same-dir)
|
|||
|
|
--capacity <N> Max concurrent sessions in worktree or
|
|||
|
|
same-dir mode (default: ${SPAWN_SESSIONS_DEFAULT})
|
|||
|
|
--[no-]create-session-in-dir Pre-create a session in the current
|
|||
|
|
directory; in worktree mode this session
|
|||
|
|
stays in cwd while on-demand sessions get
|
|||
|
|
isolated worktrees (default: on)
|
|||
|
|
`
|
|||
|
|
: ''
|
|||
|
|
const serverDescription = showServer
|
|||
|
|
? `
|
|||
|
|
Remote Control runs as a persistent server that accepts multiple concurrent
|
|||
|
|
sessions in the current directory. One session is pre-created on start so
|
|||
|
|
you have somewhere to type immediately. Use --spawn=worktree to isolate
|
|||
|
|
each on-demand session in its own git worktree, or --spawn=session for
|
|||
|
|
the classic single-session mode (exits when that session ends). Press 'w'
|
|||
|
|
during runtime to toggle between same-dir and worktree.
|
|||
|
|
`
|
|||
|
|
: ''
|
|||
|
|
const serverNote = showServer
|
|||
|
|
? ` - Worktree mode requires a git repository or WorktreeCreate/WorktreeRemove hooks
|
|||
|
|
`
|
|||
|
|
: ''
|
|||
|
|
const help = `
|
|||
|
|
Remote Control - Connect your local environment to claude.ai/code
|
|||
|
|
|
|||
|
|
USAGE
|
|||
|
|
claude remote-control [options]
|
|||
|
|
OPTIONS
|
|||
|
|
--name <name> Name for the session (shown in claude.ai/code)
|
|||
|
|
${
|
|||
|
|
feature('KAIROS')
|
|||
|
|
? ` -c, --continue Resume the last session in this directory
|
|||
|
|
--session-id <id> Resume a specific session by ID (cannot be
|
|||
|
|
used with spawn flags or --continue)
|
|||
|
|
`
|
|||
|
|
: ''
|
|||
|
|
} --permission-mode <mode> Permission mode for spawned sessions
|
|||
|
|
(${modes})
|
|||
|
|
--debug-file <path> Write debug logs to file
|
|||
|
|
-v, --verbose Enable verbose output
|
|||
|
|
-h, --help Show this help
|
|||
|
|
${serverOptions}
|
|||
|
|
DESCRIPTION
|
|||
|
|
Remote Control allows you to control sessions on your local device from
|
|||
|
|
claude.ai/code (https://claude.ai/code). Run this command in the
|
|||
|
|
directory you want to work in, then connect from the Claude app or web.
|
|||
|
|
${serverDescription}
|
|||
|
|
NOTES
|
|||
|
|
- You must be logged in with a Claude account that has a subscription
|
|||
|
|
- Run \`claude\` first in the directory to accept the workspace trust dialog
|
|||
|
|
${serverNote}`
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional help output
|
|||
|
|
console.log(help)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const TITLE_MAX_LEN = 80
|
|||
|
|
|
|||
|
|
/** Derive a session title from a user message: first line, truncated. */
|
|||
|
|
function deriveSessionTitle(text: string): string {
|
|||
|
|
// Collapse whitespace — newlines/tabs would break the single-line status display.
|
|||
|
|
const flat = text.replace(/\s+/g, ' ').trim()
|
|||
|
|
return truncateToWidth(flat, TITLE_MAX_LEN)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* One-shot fetch of a session's title via GET /v1/sessions/{id}.
|
|||
|
|
*
|
|||
|
|
* Uses `getBridgeSession` from createSession.ts (ccr-byoc headers + org UUID)
|
|||
|
|
* rather than the environments-level bridgeApi client, whose headers make the
|
|||
|
|
* Sessions API return 404. Returns undefined if the session has no title yet
|
|||
|
|
* or the fetch fails — the caller falls back to deriving a title from the
|
|||
|
|
* first user message.
|
|||
|
|
*/
|
|||
|
|
async function fetchSessionTitle(
|
|||
|
|
compatSessionId: string,
|
|||
|
|
baseUrl: string,
|
|||
|
|
): Promise<string | undefined> {
|
|||
|
|
const { getBridgeSession } = await import('./createSession.js')
|
|||
|
|
const session = await getBridgeSession(compatSessionId, { baseUrl })
|
|||
|
|
return session?.title || undefined
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export async function bridgeMain(args: string[]): Promise<void> {
|
|||
|
|
const parsed = parseArgs(args)
|
|||
|
|
|
|||
|
|
if (parsed.help) {
|
|||
|
|
await printHelp()
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
if (parsed.error) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(`Error: ${parsed.error}`)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const {
|
|||
|
|
verbose,
|
|||
|
|
sandbox,
|
|||
|
|
debugFile,
|
|||
|
|
sessionTimeoutMs,
|
|||
|
|
permissionMode,
|
|||
|
|
name,
|
|||
|
|
spawnMode: parsedSpawnMode,
|
|||
|
|
capacity: parsedCapacity,
|
|||
|
|
createSessionInDir: parsedCreateSessionInDir,
|
|||
|
|
sessionId: parsedSessionId,
|
|||
|
|
continueSession,
|
|||
|
|
} = parsed
|
|||
|
|
// Mutable so --continue can set it from the pointer file. The #20460
|
|||
|
|
// resume flow below then treats it the same as an explicit --session-id.
|
|||
|
|
let resumeSessionId = parsedSessionId
|
|||
|
|
// When --continue found a pointer, this is the directory it came from
|
|||
|
|
// (may be a worktree sibling, not `dir`). On resume-flow deterministic
|
|||
|
|
// failure, clear THIS file so --continue doesn't keep hitting the same
|
|||
|
|
// dead session. Undefined for explicit --session-id (leaves pointer alone).
|
|||
|
|
let resumePointerDir: string | undefined
|
|||
|
|
|
|||
|
|
const usedMultiSessionFeature =
|
|||
|
|
parsedSpawnMode !== undefined ||
|
|||
|
|
parsedCapacity !== undefined ||
|
|||
|
|
parsedCreateSessionInDir !== undefined
|
|||
|
|
|
|||
|
|
// Validate permission mode early so the user gets an error before
|
|||
|
|
// the bridge starts polling for work.
|
|||
|
|
if (permissionMode !== undefined) {
|
|||
|
|
const { PERMISSION_MODES } = await import('../types/permissions.js')
|
|||
|
|
const valid: readonly string[] = PERMISSION_MODES
|
|||
|
|
if (!valid.includes(permissionMode)) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
`Error: Invalid permission mode '${permissionMode}'. Valid modes: ${valid.join(', ')}`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const dir = resolve('.')
|
|||
|
|
|
|||
|
|
// The bridge fast-path bypasses init.ts, so we must enable config reading
|
|||
|
|
// before any code that transitively calls getGlobalConfig()
|
|||
|
|
const { enableConfigs, checkHasTrustDialogAccepted } = await import(
|
|||
|
|
'../utils/config.js'
|
|||
|
|
)
|
|||
|
|
enableConfigs()
|
|||
|
|
|
|||
|
|
// Initialize analytics and error reporting sinks. The bridge bypasses the
|
|||
|
|
// setup() init flow, so we call initSinks() directly to attach sinks here.
|
|||
|
|
const { initSinks } = await import('../utils/sinks.js')
|
|||
|
|
initSinks()
|
|||
|
|
|
|||
|
|
// Gate-aware validation: --spawn / --capacity / --create-session-in-dir require
|
|||
|
|
// the multi-session gate. parseArgs has already validated flag combinations;
|
|||
|
|
// here we only check the gate since that requires an async GrowthBook call.
|
|||
|
|
// Runs after enableConfigs() (GrowthBook cache reads global config) and after
|
|||
|
|
// initSinks() so the denial event can be enqueued.
|
|||
|
|
const multiSessionEnabled = await isMultiSessionSpawnEnabled()
|
|||
|
|
if (usedMultiSessionFeature && !multiSessionEnabled) {
|
|||
|
|
await logEventAsync('tengu_bridge_multi_session_denied', {
|
|||
|
|
used_spawn: parsedSpawnMode !== undefined,
|
|||
|
|
used_capacity: parsedCapacity !== undefined,
|
|||
|
|
used_create_session_in_dir: parsedCreateSessionInDir !== undefined,
|
|||
|
|
})
|
|||
|
|
// logEventAsync only enqueues — process.exit() discards buffered events.
|
|||
|
|
// Flush explicitly, capped at 500ms to match gracefulShutdown.ts.
|
|||
|
|
// (sleep() doesn't unref its timer, but process.exit() follows immediately
|
|||
|
|
// so the ref'd timer can't delay shutdown.)
|
|||
|
|
await Promise.race([
|
|||
|
|
Promise.all([shutdown1PEventLogging(), shutdownDatadog()]),
|
|||
|
|
sleep(500, undefined, { unref: true }),
|
|||
|
|
]).catch(() => {})
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
'Error: Multi-session Remote Control is not enabled for your account yet.',
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Set the bootstrap CWD so that trust checks, project config lookups, and
|
|||
|
|
// git utilities (getBranch, getRemoteUrl) resolve against the correct path.
|
|||
|
|
const { setOriginalCwd, setCwdState } = await import('../bootstrap/state.js')
|
|||
|
|
setOriginalCwd(dir)
|
|||
|
|
setCwdState(dir)
|
|||
|
|
|
|||
|
|
// The bridge bypasses main.tsx (which renders the interactive TrustDialog via showSetupScreens),
|
|||
|
|
// so we must verify trust was previously established by a normal `claude` session.
|
|||
|
|
if (!checkHasTrustDialogAccepted()) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole:: intentional console output
|
|||
|
|
console.error(
|
|||
|
|
`Error: Workspace not trusted. Please run \`claude\` in ${dir} first to review and accept the workspace trust dialog.`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Resolve auth
|
|||
|
|
const { clearOAuthTokenCache, checkAndRefreshOAuthTokenIfNeeded } =
|
|||
|
|
await import('../utils/auth.js')
|
|||
|
|
const { getBridgeAccessToken, getBridgeBaseUrl } = await import(
|
|||
|
|
'./bridgeConfig.js'
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
const bridgeToken = getBridgeAccessToken()
|
|||
|
|
if (!bridgeToken) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole:: intentional console output
|
|||
|
|
console.error(BRIDGE_LOGIN_ERROR)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// First-time remote dialog — explain what bridge does and get consent
|
|||
|
|
const {
|
|||
|
|
getGlobalConfig,
|
|||
|
|
saveGlobalConfig,
|
|||
|
|
getCurrentProjectConfig,
|
|||
|
|
saveCurrentProjectConfig,
|
|||
|
|
} = await import('../utils/config.js')
|
|||
|
|
if (!getGlobalConfig().remoteDialogSeen) {
|
|||
|
|
const readline = await import('readline')
|
|||
|
|
const rl = readline.createInterface({
|
|||
|
|
input: process.stdin,
|
|||
|
|
output: process.stdout,
|
|||
|
|
})
|
|||
|
|
// biome-ignore lint/suspicious/noConsole:: intentional console output
|
|||
|
|
console.log(
|
|||
|
|
'\nRemote Control lets you access this CLI session from the web (claude.ai/code)\nor the Claude app, so you can pick up where you left off on any device.\n\nYou can disconnect remote access anytime by running /remote-control again.\n',
|
|||
|
|
)
|
|||
|
|
const answer = await new Promise<string>(resolve => {
|
|||
|
|
rl.question('Enable Remote Control? (y/n) ', resolve)
|
|||
|
|
})
|
|||
|
|
rl.close()
|
|||
|
|
saveGlobalConfig(current => {
|
|||
|
|
if (current.remoteDialogSeen) return current
|
|||
|
|
return { ...current, remoteDialogSeen: true }
|
|||
|
|
})
|
|||
|
|
if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(0)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// --continue: resolve the most recent session from the crash-recovery
|
|||
|
|
// pointer and chain into the #20460 --session-id flow. Worktree-aware:
|
|||
|
|
// checks current dir first (fast path, zero exec), then fans out to git
|
|||
|
|
// worktree siblings if that misses — the REPL bridge writes to
|
|||
|
|
// getOriginalCwd() which EnterWorktreeTool/activeWorktreeSession can
|
|||
|
|
// point at a worktree while the user's shell is at the repo root.
|
|||
|
|
// KAIROS-gated at parseArgs — continueSession is always false in external
|
|||
|
|
// builds, so this block tree-shakes.
|
|||
|
|
if (feature('KAIROS') && continueSession) {
|
|||
|
|
const { readBridgePointerAcrossWorktrees } = await import(
|
|||
|
|
'./bridgePointer.js'
|
|||
|
|
)
|
|||
|
|
const found = await readBridgePointerAcrossWorktrees(dir)
|
|||
|
|
if (!found) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
`Error: No recent session found in this directory or its worktrees. Run \`claude remote-control\` to start a new one.`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
const { pointer, dir: pointerDir } = found
|
|||
|
|
const ageMin = Math.round(pointer.ageMs / 60_000)
|
|||
|
|
const ageStr = ageMin < 60 ? `${ageMin}m` : `${Math.round(ageMin / 60)}h`
|
|||
|
|
const fromWt = pointerDir !== dir ? ` from worktree ${pointerDir}` : ''
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional info output
|
|||
|
|
console.error(
|
|||
|
|
`Resuming session ${pointer.sessionId} (${ageStr} ago)${fromWt}\u2026`,
|
|||
|
|
)
|
|||
|
|
resumeSessionId = pointer.sessionId
|
|||
|
|
// Track where the pointer came from so the #20460 exit(1) paths below
|
|||
|
|
// clear the RIGHT file on deterministic failure — otherwise --continue
|
|||
|
|
// would keep hitting the same dead session. May be a worktree sibling.
|
|||
|
|
resumePointerDir = pointerDir
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// In production, baseUrl is the Anthropic API (from OAuth config).
|
|||
|
|
// CLAUDE_BRIDGE_BASE_URL overrides this for ant local dev only.
|
|||
|
|
const baseUrl = getBridgeBaseUrl()
|
|||
|
|
|
|||
|
|
// For non-localhost targets, require HTTPS to protect credentials.
|
|||
|
|
if (
|
|||
|
|
baseUrl.startsWith('http://') &&
|
|||
|
|
!baseUrl.includes('localhost') &&
|
|||
|
|
!baseUrl.includes('127.0.0.1')
|
|||
|
|
) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole:: intentional console output
|
|||
|
|
console.error(
|
|||
|
|
'Error: Remote Control base URL uses HTTP. Only HTTPS or localhost HTTP is allowed.',
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Session ingress URL for WebSocket connections. In production this is the
|
|||
|
|
// same as baseUrl (Envoy routes /v1/session_ingress/* to session-ingress).
|
|||
|
|
// Locally, session-ingress runs on a different port (9413) than the
|
|||
|
|
// contain-provide-api (8211), so CLAUDE_BRIDGE_SESSION_INGRESS_URL must be
|
|||
|
|
// set explicitly. Ant-only, matching CLAUDE_BRIDGE_BASE_URL.
|
|||
|
|
const sessionIngressUrl =
|
|||
|
|
process.env.USER_TYPE === 'ant' &&
|
|||
|
|
process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL
|
|||
|
|
? process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL
|
|||
|
|
: baseUrl
|
|||
|
|
|
|||
|
|
const { getBranch, getRemoteUrl, findGitRoot } = await import(
|
|||
|
|
'../utils/git.js'
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Precheck worktree availability for the first-run dialog and the `w`
|
|||
|
|
// toggle. Unconditional so we know upfront whether worktree is an option.
|
|||
|
|
const { hasWorktreeCreateHook } = await import('../utils/hooks.js')
|
|||
|
|
const worktreeAvailable = hasWorktreeCreateHook() || findGitRoot(dir) !== null
|
|||
|
|
|
|||
|
|
// Load saved per-project spawn-mode preference. Gated by multiSessionEnabled
|
|||
|
|
// so a GrowthBook rollback cleanly reverts users to single-session —
|
|||
|
|
// otherwise a saved pref would silently re-enable multi-session behavior
|
|||
|
|
// (worktree isolation, 32 max sessions, w toggle) despite the gate being off.
|
|||
|
|
// Also guard against a stale worktree pref left over from when this dir WAS
|
|||
|
|
// a git repo (or the user copied config) — clear it on disk so the warning
|
|||
|
|
// doesn't repeat on every launch.
|
|||
|
|
let savedSpawnMode = multiSessionEnabled
|
|||
|
|
? getCurrentProjectConfig().remoteControlSpawnMode
|
|||
|
|
: undefined
|
|||
|
|
if (savedSpawnMode === 'worktree' && !worktreeAvailable) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional warning output
|
|||
|
|
console.error(
|
|||
|
|
'Warning: Saved spawn mode is worktree but this directory is not a git repository. Falling back to same-dir.',
|
|||
|
|
)
|
|||
|
|
savedSpawnMode = undefined
|
|||
|
|
saveCurrentProjectConfig(current => {
|
|||
|
|
if (current.remoteControlSpawnMode === undefined) return current
|
|||
|
|
return { ...current, remoteControlSpawnMode: undefined }
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// First-run spawn-mode choice: ask once per project when the choice is
|
|||
|
|
// meaningful (gate on, both modes available, no explicit override, not
|
|||
|
|
// resuming). Saves to ProjectConfig so subsequent runs skip this.
|
|||
|
|
if (
|
|||
|
|
multiSessionEnabled &&
|
|||
|
|
!savedSpawnMode &&
|
|||
|
|
worktreeAvailable &&
|
|||
|
|
parsedSpawnMode === undefined &&
|
|||
|
|
!resumeSessionId &&
|
|||
|
|
process.stdin.isTTY
|
|||
|
|
) {
|
|||
|
|
const readline = await import('readline')
|
|||
|
|
const rl = readline.createInterface({
|
|||
|
|
input: process.stdin,
|
|||
|
|
output: process.stdout,
|
|||
|
|
})
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional dialog output
|
|||
|
|
console.log(
|
|||
|
|
`\nClaude Remote Control is launching in spawn mode which lets you create new sessions in this project from Claude Code on Web or your Mobile app. Learn more here: https://code.claude.com/docs/en/remote-control\n\n` +
|
|||
|
|
`Spawn mode for this project:\n` +
|
|||
|
|
` [1] same-dir \u2014 sessions share the current directory (default)\n` +
|
|||
|
|
` [2] worktree \u2014 each session gets an isolated git worktree\n\n` +
|
|||
|
|
`This can be changed later or explicitly set with --spawn=same-dir or --spawn=worktree.\n`,
|
|||
|
|
)
|
|||
|
|
const answer = await new Promise<string>(resolve => {
|
|||
|
|
rl.question('Choose [1/2] (default: 1): ', resolve)
|
|||
|
|
})
|
|||
|
|
rl.close()
|
|||
|
|
const chosen: 'same-dir' | 'worktree' =
|
|||
|
|
answer.trim() === '2' ? 'worktree' : 'same-dir'
|
|||
|
|
savedSpawnMode = chosen
|
|||
|
|
logEvent('tengu_bridge_spawn_mode_chosen', {
|
|||
|
|
spawn_mode:
|
|||
|
|
chosen as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
})
|
|||
|
|
saveCurrentProjectConfig(current => {
|
|||
|
|
if (current.remoteControlSpawnMode === chosen) return current
|
|||
|
|
return { ...current, remoteControlSpawnMode: chosen }
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Determine effective spawn mode.
|
|||
|
|
// Precedence: resume > explicit --spawn > saved project pref > gate default
|
|||
|
|
// - resuming via --continue / --session-id: always single-session (resume
|
|||
|
|
// targets one specific session in its original directory)
|
|||
|
|
// - explicit --spawn flag: use that value directly (does not persist)
|
|||
|
|
// - saved ProjectConfig.remoteControlSpawnMode: set by first-run dialog or `w`
|
|||
|
|
// - default with gate on: same-dir (persistent multi-session, shared cwd)
|
|||
|
|
// - default with gate off: single-session (unchanged legacy behavior)
|
|||
|
|
// Track how spawn mode was determined, for rollout analytics.
|
|||
|
|
type SpawnModeSource = 'resume' | 'flag' | 'saved' | 'gate_default'
|
|||
|
|
let spawnModeSource: SpawnModeSource
|
|||
|
|
let spawnMode: SpawnMode
|
|||
|
|
if (resumeSessionId) {
|
|||
|
|
spawnMode = 'single-session'
|
|||
|
|
spawnModeSource = 'resume'
|
|||
|
|
} else if (parsedSpawnMode !== undefined) {
|
|||
|
|
spawnMode = parsedSpawnMode
|
|||
|
|
spawnModeSource = 'flag'
|
|||
|
|
} else if (savedSpawnMode !== undefined) {
|
|||
|
|
spawnMode = savedSpawnMode
|
|||
|
|
spawnModeSource = 'saved'
|
|||
|
|
} else {
|
|||
|
|
spawnMode = multiSessionEnabled ? 'same-dir' : 'single-session'
|
|||
|
|
spawnModeSource = 'gate_default'
|
|||
|
|
}
|
|||
|
|
const maxSessions =
|
|||
|
|
spawnMode === 'single-session'
|
|||
|
|
? 1
|
|||
|
|
: (parsedCapacity ?? SPAWN_SESSIONS_DEFAULT)
|
|||
|
|
// Pre-create an empty session on start so the user has somewhere to type
|
|||
|
|
// immediately, running in the current directory (exempted from worktree
|
|||
|
|
// creation in the spawn loop). On by default; --no-create-session-in-dir
|
|||
|
|
// opts out for a pure on-demand server where every session is isolated.
|
|||
|
|
// The effectiveResumeSessionId guard at the creation site handles the
|
|||
|
|
// resume case (skip creation when resume succeeded; fall through to
|
|||
|
|
// fresh creation on env-mismatch fallback).
|
|||
|
|
const preCreateSession = parsedCreateSessionInDir ?? true
|
|||
|
|
|
|||
|
|
// Without --continue: a leftover pointer means the previous run didn't
|
|||
|
|
// shut down cleanly (crash, kill -9, terminal closed). Clear it so the
|
|||
|
|
// stale env doesn't linger past its relevance. Runs in all modes
|
|||
|
|
// (clearBridgePointer is a no-op when no file exists) — covers the
|
|||
|
|
// gate-transition case where a user crashed in single-session mode then
|
|||
|
|
// starts fresh in worktree mode. Only single-session mode writes new
|
|||
|
|
// pointers.
|
|||
|
|
if (!resumeSessionId) {
|
|||
|
|
const { clearBridgePointer } = await import('./bridgePointer.js')
|
|||
|
|
await clearBridgePointer(dir)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Worktree mode requires either git or WorktreeCreate/WorktreeRemove hooks.
|
|||
|
|
// Only reachable via explicit --spawn=worktree (default is same-dir);
|
|||
|
|
// saved worktree pref was already guarded above.
|
|||
|
|
if (spawnMode === 'worktree' && !worktreeAvailable) {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
`Error: Worktree mode requires a git repository or WorktreeCreate hooks configured. Use --spawn=session for single-session mode.`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const branch = await getBranch()
|
|||
|
|
const gitRepoUrl = await getRemoteUrl()
|
|||
|
|
const machineName = hostname()
|
|||
|
|
const bridgeId = randomUUID()
|
|||
|
|
|
|||
|
|
const { handleOAuth401Error } = await import('../utils/auth.js')
|
|||
|
|
const api = createBridgeApiClient({
|
|||
|
|
baseUrl,
|
|||
|
|
getAccessToken: getBridgeAccessToken,
|
|||
|
|
runnerVersion: MACRO.VERSION,
|
|||
|
|
onDebug: logForDebugging,
|
|||
|
|
onAuth401: handleOAuth401Error,
|
|||
|
|
getTrustedDeviceToken,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// When resuming a session via --session-id, fetch it to learn its
|
|||
|
|
// environment_id and reuse that for registration (idempotent on the
|
|||
|
|
// backend). Left undefined otherwise — the backend rejects
|
|||
|
|
// client-generated UUIDs and will allocate a fresh environment.
|
|||
|
|
// feature('KAIROS') gate: --session-id is ant-only; parseArgs already
|
|||
|
|
// rejects the flag when the gate is off, so resumeSessionId is always
|
|||
|
|
// undefined here in external builds — this guard is for tree-shaking.
|
|||
|
|
let reuseEnvironmentId: string | undefined
|
|||
|
|
if (feature('KAIROS') && resumeSessionId) {
|
|||
|
|
try {
|
|||
|
|
validateBridgeId(resumeSessionId, 'sessionId')
|
|||
|
|
} catch {
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
`Error: Invalid session ID "${resumeSessionId}". Session IDs must not contain unsafe characters.`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
// Proactively refresh the OAuth token — getBridgeSession uses raw axios
|
|||
|
|
// without the withOAuthRetry 401-refresh logic. An expired-but-present
|
|||
|
|
// token would otherwise produce a misleading "not found" error.
|
|||
|
|
await checkAndRefreshOAuthTokenIfNeeded()
|
|||
|
|
clearOAuthTokenCache()
|
|||
|
|
const { getBridgeSession } = await import('./createSession.js')
|
|||
|
|
const session = await getBridgeSession(resumeSessionId, {
|
|||
|
|
baseUrl,
|
|||
|
|
getAccessToken: getBridgeAccessToken,
|
|||
|
|
})
|
|||
|
|
if (!session) {
|
|||
|
|
// Session gone on server → pointer is stale. Clear it so the user
|
|||
|
|
// isn't re-prompted next launch. (Explicit --session-id leaves the
|
|||
|
|
// pointer alone — it's an independent file they may not even have.)
|
|||
|
|
// resumePointerDir may be a worktree sibling — clear THAT file.
|
|||
|
|
if (resumePointerDir) {
|
|||
|
|
const { clearBridgePointer } = await import('./bridgePointer.js')
|
|||
|
|
await clearBridgePointer(resumePointerDir)
|
|||
|
|
}
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
`Error: Session ${resumeSessionId} not found. It may have been archived or expired, or your login may have lapsed (run \`claude /login\`).`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
if (!session.environment_id) {
|
|||
|
|
if (resumePointerDir) {
|
|||
|
|
const { clearBridgePointer } = await import('./bridgePointer.js')
|
|||
|
|
await clearBridgePointer(resumePointerDir)
|
|||
|
|
}
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
`Error: Session ${resumeSessionId} has no environment_id. It may never have been attached to a bridge.`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
reuseEnvironmentId = session.environment_id
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] Resuming session ${resumeSessionId} on environment ${reuseEnvironmentId}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const config: BridgeConfig = {
|
|||
|
|
dir,
|
|||
|
|
machineName,
|
|||
|
|
branch,
|
|||
|
|
gitRepoUrl,
|
|||
|
|
maxSessions,
|
|||
|
|
spawnMode,
|
|||
|
|
verbose,
|
|||
|
|
sandbox,
|
|||
|
|
bridgeId,
|
|||
|
|
workerType: 'claude_code',
|
|||
|
|
environmentId: randomUUID(),
|
|||
|
|
reuseEnvironmentId,
|
|||
|
|
apiBaseUrl: baseUrl,
|
|||
|
|
sessionIngressUrl,
|
|||
|
|
debugFile,
|
|||
|
|
sessionTimeoutMs,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] bridgeId=${bridgeId}${reuseEnvironmentId ? ` reuseEnvironmentId=${reuseEnvironmentId}` : ''} dir=${dir} branch=${branch} gitRepoUrl=${gitRepoUrl} machine=${machineName}`,
|
|||
|
|
)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] apiBaseUrl=${baseUrl} sessionIngressUrl=${sessionIngressUrl}`,
|
|||
|
|
)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] sandbox=${sandbox}${debugFile ? ` debugFile=${debugFile}` : ''}`,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Register the bridge environment before entering the poll loop.
|
|||
|
|
let environmentId: string
|
|||
|
|
let environmentSecret: string
|
|||
|
|
try {
|
|||
|
|
const reg = await api.registerBridgeEnvironment(config)
|
|||
|
|
environmentId = reg.environment_id
|
|||
|
|
environmentSecret = reg.environment_secret
|
|||
|
|
} catch (err) {
|
|||
|
|
logEvent('tengu_bridge_registration_failed', {
|
|||
|
|
status: err instanceof BridgeFatalError ? err.status : undefined,
|
|||
|
|
})
|
|||
|
|
// Registration failures are fatal — print a clean message instead of a stack trace.
|
|||
|
|
// biome-ignore lint/suspicious/noConsole:: intentional console output
|
|||
|
|
console.error(
|
|||
|
|
err instanceof BridgeFatalError && err.status === 404
|
|||
|
|
? 'Remote Control environments are not available for your account.'
|
|||
|
|
: `Error: ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Tracks whether the --session-id resume flow completed successfully.
|
|||
|
|
// Used below to skip fresh session creation and seed initialSessionId.
|
|||
|
|
// Cleared on env mismatch so we gracefully fall back to a new session.
|
|||
|
|
let effectiveResumeSessionId: string | undefined
|
|||
|
|
if (feature('KAIROS') && resumeSessionId) {
|
|||
|
|
if (reuseEnvironmentId && environmentId !== reuseEnvironmentId) {
|
|||
|
|
// Backend returned a different environment_id — the original env
|
|||
|
|
// expired or was reaped. Reconnect won't work against the new env
|
|||
|
|
// (session is bound to the old one). Log to sentry for visibility
|
|||
|
|
// and fall through to fresh session creation on the new env.
|
|||
|
|
logError(
|
|||
|
|
new Error(
|
|||
|
|
`Bridge resume env mismatch: requested ${reuseEnvironmentId}, backend returned ${environmentId}. Falling back to fresh session.`,
|
|||
|
|
),
|
|||
|
|
)
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional warning output
|
|||
|
|
console.warn(
|
|||
|
|
`Warning: Could not resume session ${resumeSessionId} — its environment has expired. Creating a fresh session instead.`,
|
|||
|
|
)
|
|||
|
|
// Don't deregister — we're going to use this new environment.
|
|||
|
|
// effectiveResumeSessionId stays undefined → fresh session path below.
|
|||
|
|
} else {
|
|||
|
|
// Force-stop any stale worker instances for this session and re-queue
|
|||
|
|
// it so our poll loop picks it up. Must happen after registration so
|
|||
|
|
// the backend knows a live worker exists for the environment.
|
|||
|
|
//
|
|||
|
|
// The pointer stores a session_* ID but /bridge/reconnect looks
|
|||
|
|
// sessions up by their infra tag (cse_*) when ccr_v2_compat_enabled
|
|||
|
|
// is on. Try both; the conversion is a no-op if already cse_*.
|
|||
|
|
const infraResumeId = toInfraSessionId(resumeSessionId)
|
|||
|
|
const reconnectCandidates =
|
|||
|
|
infraResumeId === resumeSessionId
|
|||
|
|
? [resumeSessionId]
|
|||
|
|
: [resumeSessionId, infraResumeId]
|
|||
|
|
let reconnected = false
|
|||
|
|
let lastReconnectErr: unknown
|
|||
|
|
for (const candidateId of reconnectCandidates) {
|
|||
|
|
try {
|
|||
|
|
await api.reconnectSession(environmentId, candidateId)
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] Session ${candidateId} re-queued via bridge/reconnect`,
|
|||
|
|
)
|
|||
|
|
effectiveResumeSessionId = resumeSessionId
|
|||
|
|
reconnected = true
|
|||
|
|
break
|
|||
|
|
} catch (err) {
|
|||
|
|
lastReconnectErr = err
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] reconnectSession(${candidateId}) failed: ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
if (!reconnected) {
|
|||
|
|
const err = lastReconnectErr
|
|||
|
|
|
|||
|
|
// Do NOT deregister on transient reconnect failure — at this point
|
|||
|
|
// environmentId IS the session's own environment. Deregistering
|
|||
|
|
// would make retry impossible. The backend's 4h TTL cleans up.
|
|||
|
|
const isFatal = err instanceof BridgeFatalError
|
|||
|
|
// Clear pointer only on fatal reconnect failure. Transient failures
|
|||
|
|
// ("try running the same command again") should keep the pointer so
|
|||
|
|
// next launch re-prompts — that IS the retry mechanism.
|
|||
|
|
if (resumePointerDir && isFatal) {
|
|||
|
|
const { clearBridgePointer } = await import('./bridgePointer.js')
|
|||
|
|
await clearBridgePointer(resumePointerDir)
|
|||
|
|
}
|
|||
|
|
// biome-ignore lint/suspicious/noConsole: intentional error output
|
|||
|
|
console.error(
|
|||
|
|
isFatal
|
|||
|
|
? `Error: ${errorMessage(err)}`
|
|||
|
|
: `Error: Failed to reconnect session ${resumeSessionId}: ${errorMessage(err)}\nThe session may still be resumable — try running the same command again.`,
|
|||
|
|
)
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(1)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] Registered, server environmentId=${environmentId}`,
|
|||
|
|
)
|
|||
|
|
const startupPollConfig = getPollIntervalConfig()
|
|||
|
|
logEvent('tengu_bridge_started', {
|
|||
|
|
max_sessions: config.maxSessions,
|
|||
|
|
has_debug_file: !!config.debugFile,
|
|||
|
|
sandbox: config.sandbox,
|
|||
|
|
verbose: config.verbose,
|
|||
|
|
heartbeat_interval_ms:
|
|||
|
|
startupPollConfig.non_exclusive_heartbeat_interval_ms,
|
|||
|
|
spawn_mode:
|
|||
|
|
config.spawnMode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
spawn_mode_source:
|
|||
|
|
spawnModeSource as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
multi_session_gate: multiSessionEnabled,
|
|||
|
|
pre_create_session: preCreateSession,
|
|||
|
|
worktree_available: worktreeAvailable,
|
|||
|
|
})
|
|||
|
|
logForDiagnosticsNoPII('info', 'bridge_started', {
|
|||
|
|
max_sessions: config.maxSessions,
|
|||
|
|
sandbox: config.sandbox,
|
|||
|
|
spawn_mode: config.spawnMode,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const spawner = createSessionSpawner({
|
|||
|
|
execPath: process.execPath,
|
|||
|
|
scriptArgs: spawnScriptArgs(),
|
|||
|
|
env: process.env,
|
|||
|
|
verbose,
|
|||
|
|
sandbox,
|
|||
|
|
debugFile,
|
|||
|
|
permissionMode,
|
|||
|
|
onDebug: logForDebugging,
|
|||
|
|
onActivity: (sessionId, activity) => {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:activity] sessionId=${sessionId} ${activity.type} ${activity.summary}`,
|
|||
|
|
)
|
|||
|
|
},
|
|||
|
|
onPermissionRequest: (sessionId, request, _accessToken) => {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:perm] sessionId=${sessionId} tool=${request.request.tool_name} request_id=${request.request_id} (not auto-approving)`,
|
|||
|
|
)
|
|||
|
|
},
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const logger = createBridgeLogger({ verbose })
|
|||
|
|
const { parseGitHubRepository } = await import('../utils/detectRepository.js')
|
|||
|
|
const ownerRepo = gitRepoUrl ? parseGitHubRepository(gitRepoUrl) : null
|
|||
|
|
// Use the repo name from the parsed owner/repo, or fall back to the dir basename
|
|||
|
|
const repoName = ownerRepo ? ownerRepo.split('/').pop()! : basename(dir)
|
|||
|
|
logger.setRepoInfo(repoName, branch)
|
|||
|
|
|
|||
|
|
// `w` toggle is available iff we're in a multi-session mode AND worktree
|
|||
|
|
// is a valid option. When unavailable, the mode suffix and hint are hidden.
|
|||
|
|
const toggleAvailable = spawnMode !== 'single-session' && worktreeAvailable
|
|||
|
|
if (toggleAvailable) {
|
|||
|
|
// Safe cast: spawnMode is not single-session (checked above), and the
|
|||
|
|
// saved-worktree-in-non-git guard + exit check above ensure worktree
|
|||
|
|
// is only reached when available.
|
|||
|
|
logger.setSpawnModeDisplay(spawnMode as 'same-dir' | 'worktree')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Listen for keys: space toggles QR code, w toggles spawn mode
|
|||
|
|
const onStdinData = (data: Buffer): void => {
|
|||
|
|
if (data[0] === 0x03 || data[0] === 0x04) {
|
|||
|
|
// Ctrl+C / Ctrl+D — trigger graceful shutdown
|
|||
|
|
process.emit('SIGINT')
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
if (data[0] === 0x20 /* space */) {
|
|||
|
|
logger.toggleQr()
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
if (data[0] === 0x77 /* 'w' */) {
|
|||
|
|
if (!toggleAvailable) return
|
|||
|
|
const newMode: 'same-dir' | 'worktree' =
|
|||
|
|
config.spawnMode === 'same-dir' ? 'worktree' : 'same-dir'
|
|||
|
|
config.spawnMode = newMode
|
|||
|
|
logEvent('tengu_bridge_spawn_mode_toggled', {
|
|||
|
|
spawn_mode:
|
|||
|
|
newMode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
|||
|
|
})
|
|||
|
|
logger.logStatus(
|
|||
|
|
newMode === 'worktree'
|
|||
|
|
? 'Spawn mode: worktree (new sessions get isolated git worktrees)'
|
|||
|
|
: 'Spawn mode: same-dir (new sessions share the current directory)',
|
|||
|
|
)
|
|||
|
|
logger.setSpawnModeDisplay(newMode)
|
|||
|
|
logger.refreshDisplay()
|
|||
|
|
saveCurrentProjectConfig(current => {
|
|||
|
|
if (current.remoteControlSpawnMode === newMode) return current
|
|||
|
|
return { ...current, remoteControlSpawnMode: newMode }
|
|||
|
|
})
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
if (process.stdin.isTTY) {
|
|||
|
|
process.stdin.setRawMode(true)
|
|||
|
|
process.stdin.resume()
|
|||
|
|
process.stdin.on('data', onStdinData)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const controller = new AbortController()
|
|||
|
|
const onSigint = (): void => {
|
|||
|
|
logForDebugging('[bridge:shutdown] SIGINT received, shutting down')
|
|||
|
|
controller.abort()
|
|||
|
|
}
|
|||
|
|
const onSigterm = (): void => {
|
|||
|
|
logForDebugging('[bridge:shutdown] SIGTERM received, shutting down')
|
|||
|
|
controller.abort()
|
|||
|
|
}
|
|||
|
|
process.on('SIGINT', onSigint)
|
|||
|
|
process.on('SIGTERM', onSigterm)
|
|||
|
|
|
|||
|
|
// Auto-create an empty session so the user has somewhere to type
|
|||
|
|
// immediately (matching /remote-control behavior). Controlled by
|
|||
|
|
// preCreateSession: on by default; --no-create-session-in-dir opts out.
|
|||
|
|
// When a --session-id resume succeeded, skip creation entirely — the
|
|||
|
|
// session already exists and bridge/reconnect has re-queued it.
|
|||
|
|
// When resume was requested but failed on env mismatch, effectiveResumeSessionId
|
|||
|
|
// is undefined, so we fall through to fresh session creation (honoring the
|
|||
|
|
// "Creating a fresh session instead" warning printed above).
|
|||
|
|
let initialSessionId: string | null =
|
|||
|
|
feature('KAIROS') && effectiveResumeSessionId
|
|||
|
|
? effectiveResumeSessionId
|
|||
|
|
: null
|
|||
|
|
if (preCreateSession && !(feature('KAIROS') && effectiveResumeSessionId)) {
|
|||
|
|
const { createBridgeSession } = await import('./createSession.js')
|
|||
|
|
try {
|
|||
|
|
initialSessionId = await createBridgeSession({
|
|||
|
|
environmentId,
|
|||
|
|
title: name,
|
|||
|
|
events: [],
|
|||
|
|
gitRepoUrl,
|
|||
|
|
branch,
|
|||
|
|
signal: controller.signal,
|
|||
|
|
baseUrl,
|
|||
|
|
getAccessToken: getBridgeAccessToken,
|
|||
|
|
permissionMode,
|
|||
|
|
})
|
|||
|
|
if (initialSessionId) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] Created initial session ${initialSessionId}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
} catch (err) {
|
|||
|
|
logForDebugging(
|
|||
|
|
`[bridge:init] Session creation failed (non-fatal): ${errorMessage(err)}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// Crash-recovery pointer: write immediately so kill -9 at any point
|
|||
|
|
// after this leaves a recoverable trail. Covers both fresh sessions and
|
|||
|
|
// resumed ones (so a second crash after resume is still recoverable).
|
|||
|
|
// Cleared when runBridgeLoop falls through to archive+deregister; left in
|
|||
|
|
// place on the SIGINT resumable-shutdown return (backup for when the user
|
|||
|
|
// closes the terminal before copying the printed --session-id hint).
|
|||
|
|
// Refreshed hourly so a 5h+ session that crashes still has a fresh
|
|||
|
|
// pointer (staleness checks file mtime, backend TTL is rolling-from-poll).
|
|||
|
|
let pointerRefreshTimer: ReturnType<typeof setInterval> | null = null
|
|||
|
|
// Single-session only: --continue forces single-session mode on resume,
|
|||
|
|
// so a pointer written in multi-session mode would contradict the user's
|
|||
|
|
// config when they try to resume. The resumable-shutdown path is also
|
|||
|
|
// gated to single-session (line ~1254) so the pointer would be orphaned.
|
|||
|
|
if (initialSessionId && spawnMode === 'single-session') {
|
|||
|
|
const { writeBridgePointer } = await import('./bridgePointer.js')
|
|||
|
|
const pointerPayload = {
|
|||
|
|
sessionId: initialSessionId,
|
|||
|
|
environmentId,
|
|||
|
|
source: 'standalone' as const,
|
|||
|
|
}
|
|||
|
|
await writeBridgePointer(config.dir, pointerPayload)
|
|||
|
|
pointerRefreshTimer = setInterval(
|
|||
|
|
writeBridgePointer,
|
|||
|
|
60 * 60 * 1000,
|
|||
|
|
config.dir,
|
|||
|
|
pointerPayload,
|
|||
|
|
)
|
|||
|
|
// Don't let the interval keep the process alive on its own.
|
|||
|
|
pointerRefreshTimer.unref?.()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
await runBridgeLoop(
|
|||
|
|
config,
|
|||
|
|
environmentId,
|
|||
|
|
environmentSecret,
|
|||
|
|
api,
|
|||
|
|
spawner,
|
|||
|
|
logger,
|
|||
|
|
controller.signal,
|
|||
|
|
undefined,
|
|||
|
|
initialSessionId ?? undefined,
|
|||
|
|
async () => {
|
|||
|
|
// Clear the memoized OAuth token cache so we re-read from secure
|
|||
|
|
// storage, picking up tokens refreshed by child processes.
|
|||
|
|
clearOAuthTokenCache()
|
|||
|
|
// Proactively refresh the token if it's expired on disk too.
|
|||
|
|
await checkAndRefreshOAuthTokenIfNeeded()
|
|||
|
|
return getBridgeAccessToken()
|
|||
|
|
},
|
|||
|
|
)
|
|||
|
|
} finally {
|
|||
|
|
if (pointerRefreshTimer !== null) {
|
|||
|
|
clearInterval(pointerRefreshTimer)
|
|||
|
|
}
|
|||
|
|
process.off('SIGINT', onSigint)
|
|||
|
|
process.off('SIGTERM', onSigterm)
|
|||
|
|
process.stdin.off('data', onStdinData)
|
|||
|
|
if (process.stdin.isTTY) {
|
|||
|
|
process.stdin.setRawMode(false)
|
|||
|
|
}
|
|||
|
|
process.stdin.pause()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// The bridge bypasses init.ts (and its graceful shutdown handler), so we
|
|||
|
|
// must exit explicitly.
|
|||
|
|
// eslint-disable-next-line custom-rules/no-process-exit
|
|||
|
|
process.exit(0)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// ─── Headless bridge (daemon worker) ────────────────────────────────────────
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Thrown by runBridgeHeadless for configuration issues the supervisor should
|
|||
|
|
* NOT retry (trust not accepted, worktree unavailable, http-not-https). The
|
|||
|
|
* daemon worker catches this and exits with EXIT_CODE_PERMANENT so the
|
|||
|
|
* supervisor parks the worker instead of respawning it on backoff.
|
|||
|
|
*/
|
|||
|
|
export class BridgeHeadlessPermanentError extends Error {
|
|||
|
|
constructor(message: string) {
|
|||
|
|
super(message)
|
|||
|
|
this.name = 'BridgeHeadlessPermanentError'
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export type HeadlessBridgeOpts = {
|
|||
|
|
dir: string
|
|||
|
|
name?: string
|
|||
|
|
spawnMode: 'same-dir' | 'worktree'
|
|||
|
|
capacity: number
|
|||
|
|
permissionMode?: string
|
|||
|
|
sandbox: boolean
|
|||
|
|
sessionTimeoutMs?: number
|
|||
|
|
createSessionOnStart: boolean
|
|||
|
|
getAccessToken: () => string | undefined
|
|||
|
|
onAuth401: (failedToken: string) => Promise<boolean>
|
|||
|
|
log: (s: string) => void
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Non-interactive bridge entrypoint for the `remoteControl` daemon worker.
|
|||
|
|
*
|
|||
|
|
* Linear subset of bridgeMain(): no readline dialogs, no stdin key handlers,
|
|||
|
|
* no TUI, no process.exit(). Config comes from the caller (daemon.json), auth
|
|||
|
|
* comes via IPC (supervisor's AuthManager), logs go to the worker's stdout
|
|||
|
|
* pipe. Throws on fatal errors — the worker catches and maps permanent vs
|
|||
|
|
* transient to the right exit code.
|
|||
|
|
*
|
|||
|
|
* Resolves cleanly when `signal` aborts and the poll loop tears down.
|
|||
|
|
*/
|
|||
|
|
export async function runBridgeHeadless(
|
|||
|
|
opts: HeadlessBridgeOpts,
|
|||
|
|
signal: AbortSignal,
|
|||
|
|
): Promise<void> {
|
|||
|
|
const { dir, log } = opts
|
|||
|
|
|
|||
|
|
// Worker inherits the supervisor's CWD. chdir first so git utilities
|
|||
|
|
// (getBranch/getRemoteUrl) — which read from bootstrap CWD state set
|
|||
|
|
// below — resolve against the right repo.
|
|||
|
|
process.chdir(dir)
|
|||
|
|
const { setOriginalCwd, setCwdState } = await import('../bootstrap/state.js')
|
|||
|
|
setOriginalCwd(dir)
|
|||
|
|
setCwdState(dir)
|
|||
|
|
|
|||
|
|
const { enableConfigs, checkHasTrustDialogAccepted } = await import(
|
|||
|
|
'../utils/config.js'
|
|||
|
|
)
|
|||
|
|
enableConfigs()
|
|||
|
|
const { initSinks } = await import('../utils/sinks.js')
|
|||
|
|
initSinks()
|
|||
|
|
|
|||
|
|
if (!checkHasTrustDialogAccepted()) {
|
|||
|
|
throw new BridgeHeadlessPermanentError(
|
|||
|
|
`Workspace not trusted: ${dir}. Run \`claude\` in that directory first to accept the trust dialog.`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (!opts.getAccessToken()) {
|
|||
|
|
// Transient — supervisor's AuthManager may pick up a token on next cycle.
|
|||
|
|
throw new Error(BRIDGE_LOGIN_ERROR)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const { getBridgeBaseUrl } = await import('./bridgeConfig.js')
|
|||
|
|
const baseUrl = getBridgeBaseUrl()
|
|||
|
|
if (
|
|||
|
|
baseUrl.startsWith('http://') &&
|
|||
|
|
!baseUrl.includes('localhost') &&
|
|||
|
|
!baseUrl.includes('127.0.0.1')
|
|||
|
|
) {
|
|||
|
|
throw new BridgeHeadlessPermanentError(
|
|||
|
|
'Remote Control base URL uses HTTP. Only HTTPS or localhost HTTP is allowed.',
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
const sessionIngressUrl =
|
|||
|
|
process.env.USER_TYPE === 'ant' &&
|
|||
|
|
process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL
|
|||
|
|
? process.env.CLAUDE_BRIDGE_SESSION_INGRESS_URL
|
|||
|
|
: baseUrl
|
|||
|
|
|
|||
|
|
const { getBranch, getRemoteUrl, findGitRoot } = await import(
|
|||
|
|
'../utils/git.js'
|
|||
|
|
)
|
|||
|
|
const { hasWorktreeCreateHook } = await import('../utils/hooks.js')
|
|||
|
|
|
|||
|
|
if (opts.spawnMode === 'worktree') {
|
|||
|
|
const worktreeAvailable =
|
|||
|
|
hasWorktreeCreateHook() || findGitRoot(dir) !== null
|
|||
|
|
if (!worktreeAvailable) {
|
|||
|
|
throw new BridgeHeadlessPermanentError(
|
|||
|
|
`Worktree mode requires a git repository or WorktreeCreate hooks. Directory ${dir} has neither.`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const branch = await getBranch()
|
|||
|
|
const gitRepoUrl = await getRemoteUrl()
|
|||
|
|
const machineName = hostname()
|
|||
|
|
const bridgeId = randomUUID()
|
|||
|
|
|
|||
|
|
const config: BridgeConfig = {
|
|||
|
|
dir,
|
|||
|
|
machineName,
|
|||
|
|
branch,
|
|||
|
|
gitRepoUrl,
|
|||
|
|
maxSessions: opts.capacity,
|
|||
|
|
spawnMode: opts.spawnMode,
|
|||
|
|
verbose: false,
|
|||
|
|
sandbox: opts.sandbox,
|
|||
|
|
bridgeId,
|
|||
|
|
workerType: 'claude_code',
|
|||
|
|
environmentId: randomUUID(),
|
|||
|
|
apiBaseUrl: baseUrl,
|
|||
|
|
sessionIngressUrl,
|
|||
|
|
sessionTimeoutMs: opts.sessionTimeoutMs,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const api = createBridgeApiClient({
|
|||
|
|
baseUrl,
|
|||
|
|
getAccessToken: opts.getAccessToken,
|
|||
|
|
runnerVersion: MACRO.VERSION,
|
|||
|
|
onDebug: log,
|
|||
|
|
onAuth401: opts.onAuth401,
|
|||
|
|
getTrustedDeviceToken,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
let environmentId: string
|
|||
|
|
let environmentSecret: string
|
|||
|
|
try {
|
|||
|
|
const reg = await api.registerBridgeEnvironment(config)
|
|||
|
|
environmentId = reg.environment_id
|
|||
|
|
environmentSecret = reg.environment_secret
|
|||
|
|
} catch (err) {
|
|||
|
|
// Transient — let supervisor backoff-retry.
|
|||
|
|
throw new Error(`Bridge registration failed: ${errorMessage(err)}`)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const spawner = createSessionSpawner({
|
|||
|
|
execPath: process.execPath,
|
|||
|
|
scriptArgs: spawnScriptArgs(),
|
|||
|
|
env: process.env,
|
|||
|
|
verbose: false,
|
|||
|
|
sandbox: opts.sandbox,
|
|||
|
|
permissionMode: opts.permissionMode,
|
|||
|
|
onDebug: log,
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const logger = createHeadlessBridgeLogger(log)
|
|||
|
|
logger.printBanner(config, environmentId)
|
|||
|
|
|
|||
|
|
let initialSessionId: string | undefined
|
|||
|
|
if (opts.createSessionOnStart) {
|
|||
|
|
const { createBridgeSession } = await import('./createSession.js')
|
|||
|
|
try {
|
|||
|
|
const sid = await createBridgeSession({
|
|||
|
|
environmentId,
|
|||
|
|
title: opts.name,
|
|||
|
|
events: [],
|
|||
|
|
gitRepoUrl,
|
|||
|
|
branch,
|
|||
|
|
signal,
|
|||
|
|
baseUrl,
|
|||
|
|
getAccessToken: opts.getAccessToken,
|
|||
|
|
permissionMode: opts.permissionMode,
|
|||
|
|
})
|
|||
|
|
if (sid) {
|
|||
|
|
initialSessionId = sid
|
|||
|
|
log(`created initial session ${sid}`)
|
|||
|
|
}
|
|||
|
|
} catch (err) {
|
|||
|
|
log(`session pre-creation failed (non-fatal): ${errorMessage(err)}`)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
await runBridgeLoop(
|
|||
|
|
config,
|
|||
|
|
environmentId,
|
|||
|
|
environmentSecret,
|
|||
|
|
api,
|
|||
|
|
spawner,
|
|||
|
|
logger,
|
|||
|
|
signal,
|
|||
|
|
undefined,
|
|||
|
|
initialSessionId,
|
|||
|
|
async () => opts.getAccessToken(),
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/** BridgeLogger adapter that routes everything to a single line-log fn. */
|
|||
|
|
function createHeadlessBridgeLogger(log: (s: string) => void): BridgeLogger {
|
|||
|
|
const noop = (): void => {}
|
|||
|
|
return {
|
|||
|
|
printBanner: (cfg, envId) =>
|
|||
|
|
log(
|
|||
|
|
`registered environmentId=${envId} dir=${cfg.dir} spawnMode=${cfg.spawnMode} capacity=${cfg.maxSessions}`,
|
|||
|
|
),
|
|||
|
|
logSessionStart: (id, _prompt) => log(`session start ${id}`),
|
|||
|
|
logSessionComplete: (id, ms) => log(`session complete ${id} (${ms}ms)`),
|
|||
|
|
logSessionFailed: (id, err) => log(`session failed ${id}: ${err}`),
|
|||
|
|
logStatus: log,
|
|||
|
|
logVerbose: log,
|
|||
|
|
logError: s => log(`error: ${s}`),
|
|||
|
|
logReconnected: ms => log(`reconnected after ${ms}ms`),
|
|||
|
|
addSession: (id, _url) => log(`session attached ${id}`),
|
|||
|
|
removeSession: id => log(`session detached ${id}`),
|
|||
|
|
updateIdleStatus: noop,
|
|||
|
|
updateReconnectingStatus: noop,
|
|||
|
|
updateSessionStatus: noop,
|
|||
|
|
updateSessionActivity: noop,
|
|||
|
|
updateSessionCount: noop,
|
|||
|
|
updateFailedStatus: noop,
|
|||
|
|
setSpawnModeDisplay: noop,
|
|||
|
|
setRepoInfo: noop,
|
|||
|
|
setDebugLogPath: noop,
|
|||
|
|
setAttached: noop,
|
|||
|
|
setSessionTitle: noop,
|
|||
|
|
clearStatus: noop,
|
|||
|
|
toggleQr: noop,
|
|||
|
|
refreshDisplay: noop,
|
|||
|
|
}
|
|||
|
|
}
|