Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/site/content/docs/cli/reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ List every machine the current Orca host can target and the selector for each on
orca host list --json
```

The result includes this machine, its registered [SSH targets](/docs/ssh), and paired [Remote Orca Servers](/docs/remote-servers). Use `--host local` for this machine, `--host ssh:<target-id>` for an SSH target, and `--environment <server-name>` for a paired server. SSH labels and paired-server names also resolve when they are unique; use the IDs from `host list` when names collide. If you put a machine name on the wrong selector, Orca reports the matching machine and the flag to use instead of returning an empty result.
The result includes this machine, its registered [SSH targets](/docs/ssh), and paired [Remote Orca Servers](/docs/remote-servers). Use `--host local` for this machine, `--host ssh:<target-id>` for an SSH target, and `--environment <server-name>` for a paired server. SSH rows include the detected remote platform (`linux`, `darwin`, or `win32`) after the target connects; older or disconnected targets report `platform unknown`. They also include `connected` and, when known, the SSH lifecycle `connectionStatus`. SSH labels and paired-server names also resolve when they are unique; use the IDs from `host list` when names collide. If you put a machine name on the wrong selector, Orca reports the matching machine and the flag to use instead of returning an empty result.

## Runtime commands

Expand Down
20 changes: 19 additions & 1 deletion src/cli/format.ts
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,9 @@ export type HostListEntry = {
name: string
id: string
selector: string
platform?: string
connected?: boolean
connectionStatus?: string
}

// Why: the selector column is the point of this command — the name alone is what callers already
Expand All @@ -231,10 +234,25 @@ export function formatHostList(result: { hosts: HostListEntry[] }): string {
environment: 'orca server'
}
return result.hosts
.map((host) => `${kindLabel[host.kind].padEnd(11)} ${host.name} -> ${host.selector}`)
.map(
(host) =>
`${kindLabel[host.kind].padEnd(11)} ${host.name} ${host.platform ?? 'platform unknown'} ${formatHostConnection(host)} -> ${host.selector}`
)
.join('\n')
}

function formatHostConnection(host: HostListEntry): string {
if (host.kind !== 'ssh') {
return ''
}
if (host.connected === undefined) {
return `connection unknown${host.connectionStatus ? ` (${host.connectionStatus})` : ''}`
}
return host.connected
? `connected${host.connectionStatus ? ` (${host.connectionStatus})` : ''}`
: `not connected${host.connectionStatus ? ` (${host.connectionStatus})` : ''}`
}

export function formatCliStatus(status: CliStatusResult): string {
return [
...(status.target && status.target.kind === 'environment'
Expand Down
13 changes: 11 additions & 2 deletions src/cli/handlers/environment.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,19 @@ export const ENVIRONMENT_HANDLERS: Record<string, CommandHandler> = {
kind: 'ssh' as const,
name: target.label,
id: target.id,
selector: `--host ssh:${target.id}`
selector: `--host ssh:${target.id}`,
...(target.connected === undefined ? {} : { connected: target.connected }),
...(target.connectionStatus ? { connectionStatus: target.connectionStatus } : {}),
...(target.remotePlatform ? { platform: target.remotePlatform } : {})
}))
const hosts = [
{ kind: 'local' as const, name: 'this machine', id: 'local', selector: '--host local' },
{
kind: 'local' as const,
name: 'this machine',
id: 'local',
selector: '--host local',
platform: process.platform
},
...sshTargets,
...environments
]
Expand Down
18 changes: 18 additions & 0 deletions src/cli/host-selector-alternatives.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,24 @@ describe('listSshTargets', () => {
expect(call).toHaveBeenCalledWith('ssh.listTargets')
})

it('enriches legacy target rows from host-owned connection state', async () => {
const { RuntimeClientError } = await import('./runtime/types.js')
const call = vi.fn(async (method: string) => {
if (method === 'ssh.listTargetSummaries') {
throw new RuntimeClientError('method_not_found', 'Unknown method')
}
if (method === 'ssh.getState') {
return { result: { state: { status: 'connected', remotePlatform: 'win32' } } }
}
return { result: { targets: SSH_TARGETS } }
})

await expect(listSshTargets({ call } as unknown as RuntimeClient)).resolves.toEqual([
{ ...SSH_TARGETS[0], connected: true, connectionStatus: 'connected', remotePlatform: 'win32' }
])
expect(call).toHaveBeenCalledWith('ssh.getState', { targetId: SSH_TARGETS[0].id })
})

// Why: this only ever runs to enrich an error we are already reporting; a failure here must
// not replace that error with a confusing one about SSH enumeration.
it('returns nothing rather than masking the error it was enriching', async () => {
Expand Down
38 changes: 36 additions & 2 deletions src/cli/host-selector-alternatives.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
import type { RuntimeClient } from './runtime-client'

export type SshTargetSummary = { id: string; label: string }
export type SshTargetSummary = {
id: string
label: string
remotePlatform?: 'linux' | 'darwin' | 'win32'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The inline 'linux' | 'darwin' | 'win32' duplicates SshRemotePlatform from shared/ssh-types.ts. Importing the shared type keeps this CLI-local copy from drifting when the platform set changes.

connected?: boolean
connectionStatus?: string
}
export type EnvironmentSummary = { id: string; name: string }

export type HostAlternatives = {
Expand Down Expand Up @@ -106,7 +112,7 @@ export async function listSshTargets(client: RuntimeClient): Promise<SshTargetSu
if (error instanceof Error && 'code' in error && error.code === 'method_not_found') {
try {
const legacy = await client.call<{ targets: SshTargetSummary[] }>('ssh.listTargets')
return legacy.result.targets
return await enrichLegacySshTargetStates(client, legacy.result.targets)
} catch {
return []
}
Expand All @@ -115,6 +121,34 @@ export async function listSshTargets(client: RuntimeClient): Promise<SshTargetSu
}
}

async function enrichLegacySshTargetStates(
client: RuntimeClient,
targets: SshTargetSummary[]
): Promise<SshTargetSummary[]> {
return Promise.all(
targets.map(async (target) => {
try {
const response = await client.call<{
state: {
status?: string
remotePlatform?: 'linux' | 'darwin' | 'win32'
} | null
}>('ssh.getState', { targetId: target.id })
const state = response.result.state
return {
...target,
...(state?.status === undefined
? {}
: { connected: state.status === 'connected', connectionStatus: state.status }),
...(state?.remotePlatform === undefined ? {} : { remotePlatform: state.remotePlatform })
}
} catch {
return target
}
})
)
}

// Why: `--host ssh:<id>` was never validated, so an unknown target answered ok:true with an
// empty list — the same silent wrong-machine answer that `runtime:` ids used to give. And since
// target ids are machine-generated (`ssh-<timestamp>-<random>`), the label a caller actually
Expand Down
5 changes: 4 additions & 1 deletion src/cli/index-local-command-routing-flags.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ import { main } from './index'
import { okFixture, queueFixtures } from './test-fixtures'
import { pairRuntimeEnvironment, useWorktreeAwarenessEnvironment } from './index-test-harness'

const SSH_TARGET = { id: 'ssh-1777360569033-yvz2mp', label: 'openclaw' }
const SSH_TARGET = { id: 'ssh-1777360569033-yvz2mp', label: 'openclaw', remotePlatform: 'win32' }

/** Every SSH-target lookup answers with the one target only this machine's runtime knows about. */
function queueSshTargetLookups(count: number): void {
Expand Down Expand Up @@ -82,6 +82,9 @@ describe('runtime-selector flags on locally pinned CLI commands', () => {
SSH_TARGET.id,
'env-m4air'
])
expect(
printed.result.hosts.find((host: { id: string }) => host.id === SSH_TARGET.id).platform
).toBe('win32')
// The tell: `runtimeId: local` is only honest if no routed client was ever built.
expect(runtimeClientConstructorMock).toHaveBeenCalledWith(null, null)
})
Expand Down
2 changes: 2 additions & 0 deletions src/cli/specs/environment.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ export const ENVIRONMENT_COMMAND_SPECS: CommandSpec[] = [
notes: [
'Answers "what can I target and what do I pass" in one place: this machine, the SSH targets registered on it, and the Orca servers paired with it.',
'The three kinds are reached differently. A paired Orca server is a connection, selected with --environment <name>. An SSH target is a machine the connected Orca host reaches, selected with --host ssh:<id>. Passing one where the other belongs is the most common way to get an empty or missing-host answer.',
'SSH rows include the detected remote platform after that target has connected (linux, darwin, or win32); disconnected or older targets report platform unknown.',
'SSH rows also include whether the target is currently connected and its lifecycle status when known.',
"SSH targets are read from this machine's own Orca runtime, so this lists that machine's targets and not another server's. Run `orca host list` on the other machine to see the targets registered there.",
'--environment and --pairing-code are rejected rather than ignored: paired servers come from this machine\u2019s pairing store, so a routed answer would describe two machines at once.'
],
Expand Down
44 changes: 43 additions & 1 deletion src/main/runtime/rpc/methods/ssh.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -116,20 +116,62 @@ describe('ssh RPC methods', () => {
}
]
listRegisteredSshTargetsMock.mockReturnValueOnce(targets)
getRegisteredSshStateMock.mockReturnValueOnce({ status: 'connected', remotePlatform: 'win32' })
const runtime = { getRuntimeId: () => 'test-runtime' } as unknown as OrcaRuntimeService
const dispatcher = new RpcDispatcher({ runtime, methods: SSH_METHODS })

const response = await dispatcher.dispatch(makeRequest('ssh.listTargetSummaries'))

expect(response).toMatchObject({
ok: true,
result: { targets: [{ id: 'ssh-1', label: 'Dev box' }] }
result: {
targets: [
{
id: 'ssh-1',
label: 'Dev box',
connected: true,
connectionStatus: 'connected',
remotePlatform: 'win32'
}
]
}
})
expect(JSON.stringify(response)).not.toContain('dev.internal')
expect(JSON.stringify(response)).not.toContain('/secret/key')
expect(JSON.stringify(response)).not.toContain('bastion')
})

it('does not invent a platform before the SSH host has been detected', async () => {
listRegisteredSshTargetsMock.mockReturnValueOnce([{ id: 'ssh-1', label: 'Dev box' }])
getRegisteredSshStateMock.mockReturnValueOnce(undefined)
const runtime = { getRuntimeId: () => 'test-runtime' } as unknown as OrcaRuntimeService
const dispatcher = new RpcDispatcher({ runtime, methods: SSH_METHODS })

const response = await dispatcher.dispatch(makeRequest('ssh.listTargetSummaries'))

expect(response).toMatchObject({
ok: true,
result: { targets: [{ id: 'ssh-1', label: 'Dev box' }] }
})
expect(JSON.stringify(response)).not.toContain('remotePlatform')
})

it('reports disconnected lifecycle states without calling them connected', async () => {
listRegisteredSshTargetsMock.mockReturnValueOnce([{ id: 'ssh-1', label: 'Dev box' }])
getRegisteredSshStateMock.mockReturnValueOnce({ status: 'reconnecting' })
const runtime = { getRuntimeId: () => 'test-runtime' } as unknown as OrcaRuntimeService
const dispatcher = new RpcDispatcher({ runtime, methods: SSH_METHODS })

const response = await dispatcher.dispatch(makeRequest('ssh.listTargetSummaries'))

expect(response).toMatchObject({
ok: true,
result: {
targets: [{ id: 'ssh-1', connected: false, connectionStatus: 'reconnecting' }]
}
})
})

it('redacts the legacy target response for older clients', async () => {
const targets = [
{
Expand Down
17 changes: 12 additions & 5 deletions src/main/runtime/rpc/methods/ssh.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,18 @@ const SshTarget = z.object({

// Why: `generation` stays optional on the wire — an old server simply omits it and its rows key on target id alone.
function listRegisteredSshTargetSummaries(): SshTargetSummary[] {
return listRegisteredSshTargets().map(({ id, label, generation }) => ({
id,
label,
...(generation === undefined ? {} : { generation })
}))
return listRegisteredSshTargets().map(({ id, label, generation }) => {
const state = getRegisteredSshState(id)
const remotePlatform = state?.remotePlatform
return {
id,
label,
...(generation === undefined ? {} : { generation }),
connected: state?.status === 'connected',
...(state?.status === undefined ? {} : { connectionStatus: state.status }),
...(remotePlatform === undefined ? {} : { remotePlatform })
}
})
}

export const SSH_METHODS: RpcMethod[] = [
Expand Down
11 changes: 9 additions & 2 deletions src/shared/ssh-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,15 @@ export type SshTarget = {
export type SshTargetCreateInput = Omit<SshTarget, 'id' | 'generation'>
export type SshTargetUpdateInput = Partial<SshTargetCreateInput>

/** Public target identity safe to mirror to a paired client. */
export type SshTargetSummary = Pick<SshTarget, 'id' | 'label' | 'generation'>
/** Public target identity and observed host metadata safe to mirror to a paired client. */
export type SshTargetSummary = Pick<SshTarget, 'id' | 'label' | 'generation'> & {
/** The SSH host's OS, when it has connected and the relay has detected it. */
remotePlatform?: SshRemotePlatform
/** Whether the target currently has a host-owned connected SSH lifecycle. */
connected?: boolean
/** Current SSH lifecycle state, when the desktop has one for this target. */
connectionStatus?: SshConnectionStatus
}

/** Identity of a removed SSH target, recorded so that re-adding the same host
* can re-point orphaned repos/worktrees from the old (deleted) target id to
Expand Down
Loading