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 { describe, expect, it, vi } from 'vitest'
import type { RpcFailure, RpcResponse, RpcSuccess } from '../transport/types'
import {
formatPreviewByteLength,
loadMobileFilePreview,
saveMobileTerminalArtifactPreview
} from './mobile-file-preview-request'
import {
normalizeMobileFilePreviewResult,
previewErrorFromRefusal
} from './mobile-file-preview-response'
import { RPC_INCOMPATIBLE_REPLY_CODE } from '../transport/rpc-incompatible-reply-error'
function ok(result: unknown): RpcSuccess {
return { id: '1', ok: true, result, _meta: { runtimeId: 'runtime-1' } }
}
function fail(message: string, code = 'error'): RpcFailure {
return { id: '1', ok: false, error: { code, message }, _meta: { runtimeId: 'runtime-1' } }
}
function clientWith(response: RpcResponse) {
return {
sendRequest: vi.fn(async () => response)
}
}
function clientWithResponses(responses: RpcResponse[]) {
return {
sendRequest: vi.fn(async () => responses.shift()!)
}
}
describe('mobile-file-preview-request', () => {
it('prepares a media descriptor without asking the host to buffer a whole file', async () => {
const client = clientWith(fail('Unexpected whole-file read'))
await expect(loadMobileFilePreview(client, 'folder-project', 'movie.mp4')).resolves.toEqual({
status: 'ready',
kind: 'media',
media: { worktreeId: 'folder-project', relativePath: 'movie.mp4', mimeType: 'video/mp4' }
})
expect(client.sendRequest).not.toHaveBeenCalled()
})
it.each([
{
relativePath: 'assets/logo.png',
method: 'files.readPreview',
payload: { content: 'aW1hZ2U=', isBinary: true, isImage: true, mimeType: 'image/png' },
expected: { status: 'ready', kind: 'image', dataUri: 'data:image/png;base64,aW1hZ2U=' }
},
{
relativePath: 'docs/readme.md',
method: 'files.read',
payload: { content: '# Notes', truncated: false, byteLength: 7 },
expected: {
status: 'ready',
kind: 'markdown',
content: '# Notes',
truncated: false,
byteLength: 7
}
},
{
relativePath: 'public/index.html',
method: 'files.read',
payload: { content: '<h1>hi</h1>', truncated: false, byteLength: 11 },
expected: {
status: 'ready',
kind: 'html',
content: '<h1>hi</h1>',
truncated: false,
byteLength: 11
}
}
])(
'loads $relativePath through the matching read without opening a desktop tab',
async ({ relativePath, method, payload, expected }) => {
const client = clientWith(ok(payload))
await expect(loadMobileFilePreview(client, 'wt-1', relativePath)).resolves.toEqual(expected)
expect(client.sendRequest).toHaveBeenCalledExactlyOnceWith(method, {
worktree: 'id:wt-1',
relativePath
})
}
)
it('loads terminal artifacts through grant-scoped artifact RPCs', async () => {
const client = clientWith(ok({ content: '{"ok":true}', truncated: false, byteLength: 11 }))
await expect(
loadMobileFilePreview(client, {
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1'
})
).resolves.toMatchObject({ status: 'ready', kind: 'text', content: '{"ok":true}' })
expect(client.sendRequest).toHaveBeenCalledWith('files.readTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1'
})
expect(client.sendRequest).not.toHaveBeenCalledWith('files.read', expect.anything())
})
it('refreshes an expired terminal artifact grant and retries the read once', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_expired'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/result.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
}
}),
ok({ content: '{"ok":true}', truncated: false, byteLength: 11 })
])
const onTerminalArtifactSourceRefreshed = vi.fn()
await expect(
loadMobileFilePreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1',
pathText: 'result.json',
cwd: '/tmp/run'
},
undefined,
{ onTerminalArtifactSourceRefreshed, isCurrent: () => true }
)
).resolves.toMatchObject({ status: 'ready', kind: 'text', content: '{"ok":true}' })
expect(client.sendRequest).toHaveBeenNthCalledWith(1, 'files.readTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1'
})
expect(client.sendRequest).toHaveBeenNthCalledWith(2, 'files.resolveTerminalPath', {
worktree: 'id:wt-1',
pathText: 'result.json',
cwd: '/tmp/run',
terminal: 'term-1'
})
expect(client.sendRequest).toHaveBeenNthCalledWith(3, 'files.readTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
})
expect(client.sendRequest).toHaveBeenCalledTimes(3)
expect(onTerminalArtifactSourceRefreshed).toHaveBeenCalledWith({
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2',
terminalHandle: 'term-1',
pathText: 'result.json',
cwd: '/tmp/run'
})
})
it('refreshes a stale terminal artifact grant and retries the read once', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_stale'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/result.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
}
}),
ok({ content: '{"ok":true}', truncated: false, byteLength: 11 })
])
await expect(
loadMobileFilePreview(client, {
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1'
})
).resolves.toMatchObject({ status: 'ready', kind: 'text', content: '{"ok":true}' })
expect(client.sendRequest).toHaveBeenNthCalledWith(2, 'files.resolveTerminalPath', {
worktree: 'id:wt-1',
pathText: '/tmp/result.json',
terminal: 'term-1'
})
})
it('refreshes a native-chat artifact grant with the same transcript provenance', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_expired'),
ok({
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/Users/ada/orca-plans/result.html',
grantId: 'grant-2',
readOnly: true
}
}),
ok({ content: '<h1>Result</h1>', truncated: false, byteLength: 15 })
])
const onTerminalArtifactSourceRefreshed = vi.fn()
await loadMobileFilePreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/Users/ada/orca-plans/result.html',
grantId: 'grant-1',
pathText: '~/orca-plans/result.html',
nativeChatContext: { tabId: 'tab-1', sessionId: 'session-1' }
},
undefined,
{ onTerminalArtifactSourceRefreshed }
)
expect(client.sendRequest).toHaveBeenNthCalledWith(2, 'files.resolveTerminalPath', {
worktree: 'id:wt-1',
pathText: '~/orca-plans/result.html',
nativeChatContext: { tabId: 'tab-1', sessionId: 'session-1' }
})
expect(onTerminalArtifactSourceRefreshed).toHaveBeenCalledWith(
expect.objectContaining({ grantId: 'grant-2', readOnly: true })
)
})
it.each([
['terminal_file_grant_expired'],
['terminal_file_grant_mismatch'],
['terminal_file_grant_stale']
])(
'does not refresh a %s terminal artifact grant when disabled for a dirty editor',
async (error) => {
const client = clientWithResponses([fail(error)])
await expect(
loadMobileFilePreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1'
},
undefined,
{ refreshGrant: false }
)
).resolves.toEqual({
status: 'error',
message: 'Reload preview before saving',
reconnect: false
})
expect(client.sendRequest).toHaveBeenCalledTimes(1)
expect(client.sendRequest).toHaveBeenCalledWith('files.readTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1'
})
}
)
it('saves terminal artifacts through the same exact-path grant', async () => {
const client = clientWith(ok({ ok: true }))
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1',
pathText: 'result.json',
cwd: '/tmp/run'
},
'{"ok":false}'
)
).resolves.toEqual({ status: 'saved' })
expect(client.sendRequest).toHaveBeenCalledWith('files.writeTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
content: '{"ok":false}'
})
})
it('does not send writes for read-only native-chat artifacts', async () => {
const client = clientWith(ok({ ok: true }))
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/Users/ada/orca-plans/result.html',
grantId: 'grant-1',
readOnly: true
},
'<h1>Changed</h1>'
)
).resolves.toMatchObject({ status: 'error' })
expect(client.sendRequest).not.toHaveBeenCalled()
})
it('does not refresh and retry a failed terminal artifact save without a base content check', async () => {
const client = clientWithResponses([fail('terminal_file_grant_mismatch')])
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1',
pathText: 'result.json',
cwd: '/tmp/run'
},
'{"ok":false}'
)
).resolves.toEqual({
status: 'error',
message: 'Reload preview before saving',
reconnect: false
})
expect(client.sendRequest).toHaveBeenCalledTimes(1)
expect(client.sendRequest).toHaveBeenCalledWith('files.writeTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
content: '{"ok":false}'
})
})
it('refreshes an expired terminal artifact grant and retries save when the file still matches the base content', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_expired'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/result.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
}
}),
ok({ content: '{"ok":true}', truncated: false, byteLength: 11 }),
ok({ ok: true })
])
const onTerminalArtifactSourceRefreshed = vi.fn()
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1',
pathText: 'result.json',
cwd: '/tmp/run'
},
'{"ok":false}',
{ baseContent: '{"ok":true}', onTerminalArtifactSourceRefreshed }
)
).resolves.toEqual({ status: 'saved' })
expect(client.sendRequest).toHaveBeenNthCalledWith(1, 'files.readTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1'
})
expect(client.sendRequest).toHaveBeenNthCalledWith(2, 'files.resolveTerminalPath', {
worktree: 'id:wt-1',
pathText: 'result.json',
cwd: '/tmp/run',
terminal: 'term-1'
})
expect(client.sendRequest).toHaveBeenNthCalledWith(3, 'files.readTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
})
expect(client.sendRequest).toHaveBeenNthCalledWith(4, 'files.writeTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2',
content: '{"ok":false}'
})
expect(onTerminalArtifactSourceRefreshed).toHaveBeenCalledWith({
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2',
terminalHandle: 'term-1',
pathText: 'result.json',
cwd: '/tmp/run'
})
})
it('keeps the dirty draft when a refreshed terminal artifact save finds changed remote content', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_stale'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/result.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
}
}),
ok({ content: '{"ok":"changed"}', truncated: false, byteLength: 16 })
])
const onTerminalArtifactSourceRefreshed = vi.fn()
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1'
},
'{"ok":false}',
{ baseContent: '{"ok":true}', onTerminalArtifactSourceRefreshed }
)
).resolves.toEqual({
status: 'error',
message: 'File changed on desktop. Reload preview before saving',
reconnect: false
})
expect(client.sendRequest).toHaveBeenCalledTimes(3)
expect(client.sendRequest).not.toHaveBeenCalledWith('files.writeTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2',
content: '{"ok":false}'
})
expect(onTerminalArtifactSourceRefreshed).not.toHaveBeenCalled()
})
it('reports a failed refreshed artifact read instead of treating it as changed desktop content', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_stale'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/result.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
}
}),
fail('provider unavailable')
])
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1'
},
'{"ok":false}',
{ baseContent: '{"ok":true}' }
)
).resolves.toEqual({
status: 'error',
message: 'Unable to reach the desktop filesystem',
reconnect: true
})
expect(client.sendRequest).toHaveBeenCalledTimes(3)
expect(client.sendRequest).not.toHaveBeenCalledWith('files.writeTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2',
content: '{"ok":false}'
})
})
it('names the unreadable reply on a refreshed artifact read instead of treating it as changed desktop content', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_stale'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/result.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/result.json',
grantId: 'grant-2'
}
}),
ok({ truncated: false, byteLength: 11 })
])
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-1',
terminalHandle: 'term-1'
},
'{"ok":false}',
{ baseContent: '{"ok":true}' }
)
).rejects.toMatchObject({
code: RPC_INCOMPATIBLE_REPLY_CODE,
method: 'files.readTerminalArtifact'
})
expect(client.sendRequest).toHaveBeenCalledTimes(3)
expect(client.sendRequest).not.toHaveBeenCalledWith('files.writeTerminalArtifact', {
worktree: 'id:wt-1',
absolutePath: '/tmp/result.json',
grantId: 'grant-2',
content: '{"ok":false}'
})
})
it('does not retry a dirty save when grant refresh resolves to a different artifact', async () => {
const client = clientWithResponses([
fail('terminal_file_grant_expired'),
ok({
worktree: 'wt-1',
relativePath: null,
absolutePath: '/tmp/b.json',
exists: true,
isDirectory: false,
openTarget: {
kind: 'absolute-file',
absolutePath: '/tmp/b.json',
grantId: 'grant-2'
}
})
])
const onTerminalArtifactSourceRefreshed = vi.fn()
await expect(
saveMobileTerminalArtifactPreview(
client,
{
source: 'terminalArtifact',
worktreeId: 'wt-1',
absolutePath: '/tmp/a.json',
grantId: 'grant-1',
terminalHandle: 'term-1',
pathText: '/tmp/link.json'
},
'{"ok":false}',
{ baseContent: '{"ok":true}', onTerminalArtifactSourceRefreshed }
)
).resolves.toEqual({
status: 'error',
message: 'Reload preview before saving',
reconnect: false
})
expect(client.sendRequest).toHaveBeenCalledTimes(2)
expect(onTerminalArtifactSourceRefreshed).not.toHaveBeenCalled()
})
it.each([
['missing isBinary', { content: 'aW1hZ2U=', isImage: true, mimeType: 'image/png' }],
['missing isImage', { content: 'aW1hZ2U=', isBinary: true, mimeType: 'image/png' }],
['missing mimeType', { content: 'aW1hZ2U=', isBinary: true, isImage: true }],
['empty content', { content: '', isBinary: true, isImage: true, mimeType: 'image/png' }]
])('rejects invalid image preview results: %s', (_label, result) => {
expect(normalizeMobileFilePreviewResult('assets/logo.png', result)).toEqual({
status: 'error',
message: 'Binary preview unavailable',
reconnect: false
})
})
it('normalizes markdown, html, text, empty, and truncated reads', () => {
expect(
normalizeMobileFilePreviewResult('README.md', {
content: '# Hi',
truncated: false,
byteLength: 4
})
).toEqual({
status: 'ready',
kind: 'markdown',
content: '# Hi',
truncated: false,
byteLength: 4
})
expect(
normalizeMobileFilePreviewResult('index.html', {
content: '<h1>Hi</h1>',
truncated: false,
byteLength: 11
})
).toMatchObject({ status: 'ready', kind: 'html' })
expect(
normalizeMobileFilePreviewResult('src/app.ts', {
content: 'const a = 1',
truncated: true,
byteLength: 700_000
})
).toEqual({
status: 'ready',
kind: 'text',
content: 'const a = 1',
truncated: true,
byteLength: 700_000
})
expect(
normalizeMobileFilePreviewResult('empty.txt', {
content: '',
truncated: false,
byteLength: 0
})
).toEqual({ status: 'empty', kind: 'text' })
})
it.each([
['binary_file', 'Binary preview unavailable', false],
['file_too_large', 'File too large for mobile preview', false],
['ENOENT: no such file or directory', 'File not found', false],
[
'Remote connection dropped. Click Reconnect on the SSH target before retrying.',
'Unable to reach the desktop filesystem',
true
],
['provider unavailable', 'Unable to reach the desktop filesystem', true],
['terminal_file_grant_stale', 'Reload preview before saving', false],
['permission denied', 'Unable to load preview', false]
])('maps preview failure %s', (message, expected, reconnect) => {
expect(previewErrorFromRefusal(fail(message).error)).toEqual({
status: 'error',
message: expected,
reconnect
})
})
it('formats truncation byte counts for the UI note', () => {
expect(formatPreviewByteLength(512)).toBe('512 B')
expect(formatPreviewByteLength(4096)).toBe('4 KB')
expect(formatPreviewByteLength(1_572_864)).toBe('1.5 MB')
})
})