Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import type { ParsedFileLinkLocation } from '../../../src/shared/file-link-location'
import type {
RuntimeNativeChatFileContext,
RuntimeTerminalPathResolution
} from '../../../src/shared/runtime-types'
import { filesystemPathToFileUri } from '../../../src/shared/file-uri-path'
import { createMobileFilePreviewHref } from '../files/mobile-file-preview-route'
import { classifyMobileArtifact } from './mobile-artifact-kind'
import { fileTapOpenRun, fileTapPathResolve } from './mobile-session-launch-operations'
import { mapWithConcurrency } from '../../../src/shared/map-with-concurrency'
import { shouldActivateOpenedMobileSessionTab } from './opened-mobile-session-tab'
import { isRendererUnavailableReply } from '../transport/renderer-unavailable-reply'
import type { RpcOperationSender } from '../transport/rpc-operation-sender'
import type { RpcResponse } from '../transport/types'
// Hard-wrap guesses can number in the hundreds; stay far below the page bridge's 64 pending requests.
const FILE_TAP_RESOLVE_CONCURRENCY = 8
export type FileTapSessionTab = {
id: string
relativePath?: string
}
export type OpenMobileFileTapOptions<T extends FileTapSessionTab> = {
client: RpcOperationSender
hostId: string
worktreeId: string
worktreeName?: string
terminalHandle?: string | null
cwd?: string | null
nativeChatContext?: RuntimeNativeChatFileContext | null
// Every reading of the tapped text; like desktop, the longest that exists opens.
candidates: readonly ParsedFileLinkLocation[]
pushPreviewRoute: (href: ReturnType<typeof createMobileFilePreviewHref>) => void
openBrowser: (url: string) => void
triggerOpenFeedback: () => void
fetchSessionTabs: () => Promise<void>
getSessionTabs: () => readonly T[]
getActiveSessionTabId: () => string | null
getActivationState: (activated: boolean) => {
activated: boolean
activationSeq: number
latestActivationSeq: number
sourceTerminalHandle: string | null
activeTerminalHandle: string | null
sourceSessionTabId?: string | null
activeSessionTabId?: string | null
activeTabType: string | null
}
switchSessionTab: (tab: T) => void
scheduleDelayedAction: (callback: () => void, delayMs: number) => unknown
// Optional feedback; callers without it retain silent best-effort misses.
onOpenFailed?: () => void
}
export function openMobileFileTap<T extends FileTapSessionTab>(
options: OpenMobileFileTapOptions<T>
): void {
void openMobileFileTapAsync(options).catch(() => {
// File taps are best-effort: a failed host resolution should leave terminal
// focus/input untouched. Surfaces that want feedback pass onOpenFailed.
reportOpenFailure(options)
})
}
function requestFileTapResolution<T extends FileTapSessionTab>(
options: OpenMobileFileTapOptions<T>,
pathText: string
) {
return fileTapPathResolve.request(
options.client,
{
worktree: `id:${options.worktreeId}`,
pathText,
// Why: opts into sibling-workspace resolutions; this caller honors resolved.worktree.
crossWorkspace: true,
...(options.terminalHandle && options.terminalHandle.trim().length > 0
? { terminal: options.terminalHandle }
: {}),
...(options.cwd && options.cwd.trim().length > 0 ? { cwd: options.cwd } : {}),
...(options.nativeChatContext ? { nativeChatContext: options.nativeChatContext } : {})
},
{ timeoutMs: 10_000 }
)
}
function existingFileTapResolution(
response: RpcResponse | null
): RuntimeTerminalPathResolution | null {
const accepted = response ? fileTapPathResolve.interpret(response) : null
if (!accepted?.accepted) {
return null
}
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: Preserve the established response shape at this boundary.
const resolved = accepted.value as RuntimeTerminalPathResolution
return resolved.exists && !resolved.isDirectory ? resolved : null
}
function reportOpenFailure<T extends FileTapSessionTab>(
options: OpenMobileFileTapOptions<T>
): void {
if (
options.onOpenFailed &&
shouldActivateOpenedMobileSessionTab(options.getActivationState(false))
) {
options.onOpenFailed()
}
}
async function openMobileFileTapAsync<T extends FileTapSessionTab>(
options: OpenMobileFileTapOptions<T>
): Promise<void> {
const readings = await mapWithConcurrency(
options.candidates,
FILE_TAP_RESOLVE_CONCURRENCY,
async (target) => ({
target,
// Why: a reading the host cannot answer must not hide a sibling.
resolved: existingFileTapResolution(
await requestFileTapResolution(options, target.pathText).catch(() => null)
)
})
)
const found = readings.reduce<(typeof readings)[number] | undefined>(
(best, reading) =>
reading.resolved && (!best || reading.target.pathText.length > best.target.pathText.length)
? reading
: best,
undefined
)
if (!found?.resolved) {
reportOpenFailure(options)
return
}
const { target } = found
const resolved = found.resolved
// Not a failure: the user moved off the source tab mid-resolve.
if (!shouldActivateOpenedMobileSessionTab(options.getActivationState(false))) {
return
}
const resolvedWorktreeId = resolved.worktree?.trim() || options.worktreeId
const resolvedWorktree = `id:${resolvedWorktreeId}`
const resolvedWorktreeName =
resolvedWorktreeId === options.worktreeId ? options.worktreeName : undefined
if (resolved.openTarget?.kind === 'absolute-file') {
options.triggerOpenFeedback()
options.pushPreviewRoute(
createMobileFilePreviewHref({
hostId: options.hostId,
worktreeId: resolvedWorktreeId,
source: 'terminalArtifact',
absolutePath: resolved.openTarget.absolutePath,
grantId: resolved.openTarget.grantId,
pathText: target.pathText,
...(options.cwd && options.cwd.trim().length > 0 ? { cwd: options.cwd } : {}),
...(options.terminalHandle && options.terminalHandle.trim().length > 0
? { terminal: options.terminalHandle }
: {}),
...(options.nativeChatContext
? {
nativeChatTab: options.nativeChatContext.tabId,
nativeChatSession: options.nativeChatContext.sessionId
}
: {}),
name: displayNameFromPath(resolved.openTarget.absolutePath),
...(target.line !== null ? { line: String(target.line) } : {}),
...(target.column !== null ? { column: String(target.column) } : {}),
...(resolvedWorktreeName ? { worktreeName: resolvedWorktreeName } : {})
})
)
return
}
const openedPath =
resolved.openTarget?.kind === 'worktree-file'
? resolved.openTarget.relativePath
: resolved.relativePath
if (!openedPath) {
reportOpenFailure(options)
return
}
options.triggerOpenFeedback()
const pushWorktreePreview = (): void =>
options.pushPreviewRoute(
createMobileFilePreviewHref({
hostId: options.hostId,
worktreeId: resolvedWorktreeId,
source: 'worktree',
relativePath: openedPath,
name: displayNameFromPath(openedPath),
...(target.line !== null ? { line: String(target.line) } : {}),
...(target.column !== null ? { column: String(target.column) } : {}),
...(resolvedWorktreeName ? { worktreeName: resolvedWorktreeName } : {})
})
)
if (resolvedWorktreeId !== options.worktreeId || target.line !== null || target.column !== null) {
pushWorktreePreview()
return
}
if (
classifyMobileArtifact(openedPath) === 'html' &&
resolved.openTarget?.kind === 'worktree-file' &&
resolved.openTarget.provider === 'local'
) {
options.openBrowser(filesystemPathToFileUri(resolved.openTarget.absolutePath))
return
}
const openResponse = await fileTapOpenRun.request(
options.client,
{ worktree: resolvedWorktree, relativePath: openedPath },
{ timeoutMs: 15_000 }
)
// Why: a host with no desktop window opens no editor tabs; the preview route reads the file through files.read.
if (isRendererUnavailableReply(openResponse)) {
// Not a failure: the user moved off the source tab during the call.
if (!shouldActivateOpenedMobileSessionTab(options.getActivationState(false))) {
return
}
pushWorktreePreview()
return
}
const opened = fileTapOpenRun.interpret(openResponse)
if (!opened.accepted) {
reportOpenFailure(options)
return
}
if (!opened.value.opened) {
reportOpenFailure(options)
return
}
scheduleOpenedWorktreeTabActivation(options, openedPath)
}
function scheduleOpenedWorktreeTabActivation<T extends FileTapSessionTab>(
options: OpenMobileFileTapOptions<T>,
openedPath: string
): void {
let activated = false
const activateOpenedTab = async (): Promise<void> => {
if (!shouldActivateOpenedMobileSessionTab(options.getActivationState(activated))) {
return
}
await options.fetchSessionTabs()
if (!shouldActivateOpenedMobileSessionTab(options.getActivationState(activated))) {
return
}
const opened = options.getSessionTabs().find((tab) => tab.relativePath === openedPath)
if (!opened) {
return
}
if (options.getActiveSessionTabId() !== opened.id) {
options.switchSessionTab(opened)
}
activated = true
}
options.scheduleDelayedAction(() => void activateOpenedTab(), 300)
options.scheduleDelayedAction(() => void activateOpenedTab(), 900)
options.scheduleDelayedAction(() => void activateOpenedTab(), 1800)
}
function displayNameFromPath(path: string): string | undefined {
return path.split(/[\\/]/).findLast(Boolean)
}