Files
orca/src/shared/runtime-file-contracts.ts
T
Neil 6aaf0e683d fix(terminal): a paired-server file link opens in the workspace it was clicked in (#38072)
* fix(terminal): a paired-server file link opens in the workspace it was clicked in

Clicking a server terminal link to a file another workspace holds switched to
that workspace: the client asked the host for the holding workspace
(crossWorkspace), and the editor loader moved any absolute-path tab -
including one already holding a grant - to that workspace. Anyone who can
open a tab can already run anything on the host, so the holding workspace
guards nothing. On hosts that save granted files, the link now opens through
a grant in the clicked workspace, and restored tabs re-grant in place. Hosts
that can't (older hosts, their own SSH workspaces) and folders keep opening in
the holding workspace.

* fix(runtime): a desktop client reads and saves a granted file as large as a workspace one

Hosts advertise files.resolve-terminal-path.in-place-files.v1, give desktop
clients a 2 MB grant budget (phones keep 512 KB), and report a grant's size,
so the clicked workspace opens a file another workspace holds in place and
falls back to the holding workspace only where a grant can't serve it.

* fix(terminal): open in place only what a grant can read and save

Review: a grant save must fit one request frame and grants serve no bytes
editors, so the 2 MB budget would open files that can't be saved. Hosts now
report a grant's size and binary content instead, the client opens in place
only text within 512 KB, and only the SSH-workspace refusal moves a restored
tab; other host errors stay retryable.

* docs(terminal): describe the in-place files probe

* fix(terminal): ask the holder first and keep downloads, HTML and missing paths unchanged

Review: the holder answers first, as before, so missing paths, folders, this
computer's files, downloads and HTML previews resolve exactly as they did; only
an existing text file another workspace holds asks again for a grant here.
In-place opens are capped at 256 KB so edits stay within the grant's save limit.

* test(editor): mark the placement test's store stub as a sound cast
2026-11-04 01:35:57 -08:00

122 lines
3.6 KiB
TypeScript

import type { RasterImageDimensions } from './raster-image-dimensions'
import type { RuntimeNavigationTarget } from './runtime-navigation'
export type RuntimeFileListEntry = {
relativePath: string
basename: string
kind: 'text' | 'binary'
}
export type RuntimeFileListResult = {
worktree: string
rootPath: string
files: RuntimeFileListEntry[]
totalCount: number
truncated: boolean
quickOpenSearchVersion?: number
}
export type RuntimeFileOpenResult = {
worktree: string
relativePath: string
kind: 'markdown' | 'text' | 'binary' | 'image'
opened: boolean
}
export type RuntimeFileOpenPosition = {
line: number
column?: number
}
/** A file main opened itself, which a window shows: layout-owner builds, local window only. */
export type RuntimeEditorFileOpen = {
worktreeId: string
filePath: string
relativePath: string
runtimeEnvironmentId?: string | null
navigation?: RuntimeNavigationTarget
position?: RuntimeFileOpenPosition
}
/** `frameSeq`: the layout stream position whose frame draws the tab. */
export type RuntimeEditorTabReveal = RuntimeEditorFileOpen & { tabId: string; frameSeq?: number }
export type RuntimeFileReadResult = {
worktree: string
relativePath: string
content: string
truncated: boolean
byteLength: number
}
export type RuntimeTerminalPathOpenTarget =
| {
kind: 'worktree-file'
provider: 'local' | 'ssh'
relativePath: string
absolutePath: string
}
| {
kind: 'absolute-file'
provider: 'local' | 'ssh'
absolutePath: string
grantId: string
readOnly?: true
/** The file's size when granted; hosts with in-place files report it. */
byteLength?: number
/** Hosts with in-place files mark a file a grant can't serve as text. */
binary?: true
}
| { kind: 'unsupported'; reason: string }
export type RuntimeNativeChatFileContext = {
tabId: string
sessionId: string
}
// Why: older hosts ignore crossWorkspace, so their refusal is no proof that no host workspace holds the path.
export const TERMINAL_PATH_CROSS_WORKSPACE_RUNTIME_CAPABILITY =
'files.resolve-terminal-path.cross-workspace.v1' as const
// Why: older hosts grant a path outside their workspaces only to the terminal that printed it.
export const TERMINAL_PATH_ABSOLUTE_FILES_RUNTIME_CAPABILITY =
'files.resolve-terminal-path.absolute-files.v1' as const
// Why: older hosts report neither a grant's size nor binary content, so their grant can't be
// proven to read and save; a file another workspace holds opens there, as before.
export const TERMINAL_PATH_IN_PLACE_FILES_RUNTIME_CAPABILITY =
'files.resolve-terminal-path.in-place-files.v1' as const
/**
* The largest file opened in place through a grant. Hosts cap grant reads and saves at 512 KB and a save
* must fit one request frame; half that leaves room to edit before a save outgrows the grant.
*/
export const TERMINAL_ARTIFACT_IN_PLACE_MAX_BYTES = 256 * 1024
/** SSH workspaces on a server grant no file outside them; the one refusal that means "open it where it lives". */
export const SSH_OUTSIDE_WORKSPACE_UNSUPPORTED_MESSAGE =
"Files outside an SSH workspace can't be opened from another device yet."
export type RuntimeTerminalPathResolution = {
worktree: string
relativePath: string | null
absolutePath: string | null
exists: boolean
isDirectory: boolean
openTarget?: RuntimeTerminalPathOpenTarget
}
export type RuntimeFilePreviewResult = {
content: string
isBinary: boolean
isImage?: boolean
mimeType?: string
imageDimensions?: RasterImageDimensions
}
export type RuntimeFileReadChunkResult = {
contentBase64: string
bytesRead: number
eof: boolean
}