From 52f1dedc5dee7e88f44e82dd8316c57555df1227 Mon Sep 17 00:00:00 2001 From: Mark McKeen Date: Mon, 6 Apr 2026 08:13:04 -0600 Subject: [PATCH] feat: add truthful operator terminal readiness page --- app/components/SandboxList.tsx | 28 +--- app/operator-terminal/page.tsx | 233 ++++++++++++++++++++++++++++++++ operator-terminal.checkpoint.md | 24 ++++ 3 files changed, 264 insertions(+), 21 deletions(-) create mode 100644 app/operator-terminal/page.tsx create mode 100644 operator-terminal.checkpoint.md diff --git a/app/components/SandboxList.tsx b/app/components/SandboxList.tsx index ea76755..79b3bd2 100644 --- a/app/components/SandboxList.tsx +++ b/app/components/SandboxList.tsx @@ -1,5 +1,6 @@ "use client" import { useState, useEffect } from 'react' +import { useRouter } from 'next/navigation' import ConfigurationPanel from './ConfigurationPanel' interface Sandbox { @@ -32,7 +33,7 @@ export default function SandboxList({ onSandboxSelect, isDestroyMode }: SandboxListProps) { - const [terminalMessage, setTerminalMessage] = useState('') + const router = useRouter() const [dashboardMessage, setDashboardMessage] = useState('') const [sandboxes, setSandboxes] = useState([]) const [telemetry, setTelemetry] = useState({ @@ -197,26 +198,12 @@ export default function SandboxList({ Start OpenClaw Gateway Dashboard LIVE @@ -224,10 +211,9 @@ export default function SandboxList({ - {(dashboardMessage || terminalMessage) && ( + {dashboardMessage && (
- {dashboardMessage &&
{dashboardMessage}
} - {terminalMessage &&
{terminalMessage}
} +
{dashboardMessage}
)} diff --git a/app/operator-terminal/page.tsx b/app/operator-terminal/page.tsx new file mode 100644 index 0000000..5868cc1 --- /dev/null +++ b/app/operator-terminal/page.tsx @@ -0,0 +1,233 @@ +"use client" + +import Link from 'next/link' +import { useSearchParams } from 'next/navigation' +import { useCallback, useEffect, useMemo, useState } from 'react' + +interface IntrospectResponse { + ok: boolean + sandboxId?: string + containers?: string[] + images?: string[] + runningStatuses?: string[] + stderr?: string + note?: string + error?: string +} + +type LoadState = 'idle' | 'loading' | 'ready' | 'error' + +const SSH_ALIAS = 'ssh openshell-my-assistant' +const SSH_FALLBACK = 'ssh -i ~/.ssh/id_ed25519_openclaw_labmac openshell-my-assistant' + +export default function OperatorTerminalPage() { + const searchParams = useSearchParams() + const sandboxId = searchParams.get('sandboxId') + const [state, setState] = useState(sandboxId ? 'loading' : 'idle') + const [data, setData] = useState(null) + const [lastCheckedAt, setLastCheckedAt] = useState(null) + const [copyMessage, setCopyMessage] = useState('') + + const refreshReadiness = useCallback(async () => { + if (!sandboxId) { + setState('idle') + setData(null) + return + } + + setState('loading') + setCopyMessage('') + + try { + const response = await fetch(`/api/openshell/terminal/introspect?sandboxId=${encodeURIComponent(sandboxId)}`, { + cache: 'no-store', + }) + const result: IntrospectResponse = await response.json() + setData(result) + setState(response.ok && result.ok ? 'ready' : 'error') + setLastCheckedAt(new Date().toLocaleTimeString()) + } catch (error) { + setData({ + ok: false, + error: error instanceof Error ? error.message : 'Failed to inspect sandbox readiness.', + }) + setState('error') + setLastCheckedAt(new Date().toLocaleTimeString()) + } + }, [sandboxId]) + + useEffect(() => { + refreshReadiness() + }, [refreshReadiness]) + + const readiness = useMemo(() => { + if (!sandboxId) { + return { + tone: 'border-[var(--status-pending)] text-[var(--status-pending)]', + label: 'NO SANDBOX SELECTED', + detail: 'Return to the dashboard and choose a sandbox before opening Operator Terminal.', + } + } + + if (state === 'loading') { + return { + tone: 'border-[var(--status-pending)] text-[var(--status-pending)]', + label: 'CHECKING READINESS', + detail: 'Verifying pod metadata so the page can show a truthful operator handoff.', + } + } + + if (state === 'ready' && data?.ok) { + return { + tone: 'border-[var(--status-running)] text-[var(--status-running)]', + label: 'READY FOR LOCAL SSH ATTACH', + detail: 'This page confirms the sandbox exists. Interactive PTY embedding is not wired up yet, so attach from your local terminal.', + } + } + + return { + tone: 'border-[var(--status-stopped)] text-[var(--status-stopped)]', + label: 'READINESS CHECK FAILED', + detail: 'The dashboard could not confirm pod metadata. Use the recovery commands below, then retry.', + } + }, [sandboxId, state, data]) + + const copyCommand = useCallback(async (command: string) => { + try { + await navigator.clipboard.writeText(command) + setCopyMessage(`Copied: ${command}`) + } catch { + setCopyMessage(`Copy failed. Use: ${command}`) + } + }, []) + + return ( +
+
+
+
+

Operator path

+

Operator Terminal

+

+ Truthful first render for the current terminal path. This page does not pretend to host an embedded shell; it verifies readiness and tells the operator exactly how to attach. +

+
+ + Back to Dashboard + +
+ +
+
+
+

Sandbox

+

{sandboxId || 'UNSELECTED'}

+
+
+

Status

+

{readiness.label}

+ {lastCheckedAt &&

Last checked {lastCheckedAt}

} +
+
+

{readiness.detail}

+
+ +
+
+
+
+

Attach Instructions

+

+ Preferred path is the SSH alias. If your shell environment is missing the alias or key wiring, use the explicit fallback. +

+
+ +
+ +
+
+

Preferred attach command

+ {SSH_ALIAS} + +
+ +
+

Fallback if alias or agent config is missing

+ {SSH_FALLBACK} +

+ If your non-interactive shell misses Homebrew tooling, retry from a login shell or prepend PATH=/opt/homebrew/bin:$PATH before related helper commands. +

+ +
+
+ + {copyMessage && ( +
+ {copyMessage} +
+ )} +
+ +
+
+

Readiness Evidence

+

+ Live pod introspection from the dashboard backend. This is the page’s truth source until persistent PTY transport exists. +

+
+ +
+
+

Containers

+

{data?.containers?.length ? data.containers.join(', ') : 'Unavailable'}

+
+
+

Images

+

{data?.images?.length ? data.images.join(', ') : 'Unavailable'}

+
+
+

Running statuses

+

{data?.runningStatuses?.length ? data.runningStatuses.join(', ') : 'Unavailable'}

+
+
+ +
+

Recovery notes

+
    +
  • If readiness fails but SSH still works, use the local attach command and treat the dashboard as degraded, not authoritative.
  • +
  • If SSH fails, verify the host alias and key path on the Mac first.
  • +
  • If both fail, restart the dashboard/backend side and rerun the readiness check.
  • +
+
+ + {(data?.note || data?.error || data?.stderr) && ( +
+ {data?.note &&

Note: {data.note}

} + {data?.error &&

Error: {data.error}

} + {data?.stderr &&

stderr: {data.stderr}

} +
+ )} +
+
+
+
+ ) +} diff --git a/operator-terminal.checkpoint.md b/operator-terminal.checkpoint.md new file mode 100644 index 0000000..eabaea8 --- /dev/null +++ b/operator-terminal.checkpoint.md @@ -0,0 +1,24 @@ +# DML Checkpoint — 2026-04-06 — operator-terminal + +- milestone: truthful first-render / readiness / recovery UX +- status: shipped bounded UI slice without PTY embedding +- sandbox target: `my-assistant` + +## Delta +- Added `/operator-terminal` page. +- Dashboard CTA now routes to `/operator-terminal?sandboxId=...`. +- Page fetches `/api/openshell/terminal/introspect` and shows: + - explicit non-embedded status + - readiness state + - exact SSH attach commands + - retry + copy actions + - live introspection evidence + recovery notes + +## Validation +- `npm install` succeeded. +- `eslint app/operator-terminal/page.tsx app/components/SandboxList.tsx` passed. +- Full `tsc --noEmit` still fails on pre-existing unrelated type errors outside this slice. +- Linux-side direct `ssh openshell-my-assistant` validation blocked because alias is Mac-local here. + +## Next milestone +- Add a backend operator-readiness contract that can distinguish pod existence, SSH reachability, and dashboard degradation, then optionally layer in streamed attach transport afterward.