gib/spoon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Workspace Terminal tab: xterm front end + short-lived token route

Browse Source 
- New Terminal tab in the workspace shell, backed by xterm.js, that connects
  to the worker's PTY WebSocket using a short-lived token minted by
  /api/agent-jobs/:id/terminal-token (owner-auth'd, never exposes the worker
  secret to the browser)
- Site-matched xterm theme (light/dark, live theme switching), Victor Mono,
  binary stdin + JSON resize protocol, reconnect, graceful 'not configured'
  state when NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL is unset
- env: NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL (client), SPOON_AGENT_TERMINAL_SECRET
This commit is contained in:
Gabriel Brown
2026-06-24 08:23:58 -04:00
parent c1263b2e69
commit 15407e7e9c
7 changed files with 335 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/next/package.json
+3
View File
@@ -27,6 +27,9 @@
"@spoon/backend": "workspace:*",
"@spoon/ui": "workspace:*",
"@t3-oss/env-nextjs": "^0.13.11",
"@xterm/addon-fit": "^0.11.0",
"@xterm/addon-web-links": "^0.12.0",
"@xterm/xterm": "^6.0.0",
"convex": "catalog:convex",
"monaco-editor": "latest",
"monaco-vim": "latest",
apps/next/src/app/api/agent-jobs/[jobId]/terminal-token/route.ts
+18
View File
@@ -0,0 +1,18 @@
import { NextResponse } from 'next/server';
import { mintTerminalToken, withOwnedJob } from '@/lib/agent-worker-proxy';
export const GET = async (
_request: Request,
context: { params: Promise<{ jobId: string }> },
) =>
await withOwnedJob(context, (jobId) => {
const minted = mintTerminalToken(jobId);
return Promise.resolve(
minted
? NextResponse.json(minted)
: NextResponse.json(
{ error: 'Terminal is not configured on this deployment.' },
{ status: 503 },
),
);
});
apps/next/src/components/agent-workspace/agent-workspace-shell.tsx
+29 -5
View File
@@ -3,7 +3,13 @@
import type { CSSProperties, PointerEvent as ReactPointerEvent } from 'react';
import { useCallback, useEffect, useState } from 'react';
import { useMutation, useQuery } from 'convex/react';
import { FileCode, GitCompare, Loader2, MessagesSquare } from 'lucide-react';
import {
FileCode,
GitCompare,
Loader2,
MessagesSquare,
SquareTerminal,
} from 'lucide-react';
import { toast } from 'sonner';
import type { Id } from '@spoon/backend/convex/_generated/dataModel.js';
@@ -34,6 +40,9 @@ import { FileTabs } from './file-tabs';
import { FileTree } from './file-tree';
import { JobStatusBar } from './job-status-bar';
import { WorkspaceActions } from './workspace-actions';
import { WorkspaceTerminal } from './workspace-terminal';
type WorkspaceTab = 'editor' | 'diff' | 'thread' | 'terminal';
type OpenFileState = {
path: string;
@@ -81,9 +90,8 @@ export const AgentWorkspaceShell = ({ jobId }: { jobId: Id<'agentJobs'> }) => {
const [focusedDiffPath, setFocusedDiffPath] = useState<string>();
const [workspaceError, setWorkspaceError] = useState<string>();
const [agentTurnActive, setAgentTurnActive] = useState(false);
const [activeWorkspaceTab, setActiveWorkspaceTab] = useState<
'editor' | 'diff' | 'thread'
>('editor');
const [activeWorkspaceTab, setActiveWorkspaceTab] =
useState<WorkspaceTab>('editor');
const [pendingOverwrite, setPendingOverwrite] = useState<PendingOverwrite>();
const [pendingClosePath, setPendingClosePath] = useState<string>();
@@ -575,7 +583,7 @@ export const AgentWorkspaceShell = ({ jobId }: { jobId: Id<'agentJobs'> }) => {
<Tabs
value={activeWorkspaceTab}
onValueChange={(value) =>
setActiveWorkspaceTab(value as 'editor' | 'diff' | 'thread')
setActiveWorkspaceTab(value as WorkspaceTab)
}
className='flex min-h-0 flex-1 flex-col'
>
@@ -594,6 +602,13 @@ export const AgentWorkspaceShell = ({ jobId }: { jobId: Id<'agentJobs'> }) => {
<GitCompare className='size-4' />
Diff viewer
</TabsTrigger>
<TabsTrigger
value='terminal'
className='data-active:bg-background data-active:text-foreground data-active:shadow-sm'
>
<SquareTerminal className='size-4' />
Terminal
</TabsTrigger>
<TabsTrigger
value='thread'
className='data-active:bg-background data-active:text-foreground data-active:shadow-sm 2xl:hidden'
@@ -642,6 +657,15 @@ export const AgentWorkspaceShell = ({ jobId }: { jobId: Id<'agentJobs'> }) => {
}}
/>
</TabsContent>
<TabsContent
value='terminal'
className='m-0 min-h-0 flex-1 overflow-hidden'
>
<WorkspaceTerminal
jobId={jobId}
active={activeWorkspaceTab === 'terminal' && workspaceReady}
/>
</TabsContent>
<TabsContent value='diff' className='m-0 min-h-0 flex-1'>
<DiffViewer
diff={diff}
apps/next/src/components/agent-workspace/workspace-terminal.tsx
+245
View File
@@ -0,0 +1,245 @@
'use client';
import type { ITheme, Terminal } from '@xterm/xterm';
import { useEffect, useRef, useState } from 'react';
import { useTheme } from 'next-themes';
import { Button } from '@spoon/ui';
import '@xterm/xterm/css/xterm.css';
const TERMINAL_FONT =
"var(--font-victor-mono), 'Geist Mono', ui-monospace, monospace";
type Status = 'connecting' | 'connected' | 'closed' | 'error' | 'unconfigured';
const darkTheme: ITheme = {
background: '#080e14',
foreground: '#eef3f5',
cursor: '#1fb895',
cursorAccent: '#080e14',
selectionBackground: '#1fb89544',
black: '#10171e',
red: '#f3625d',
green: '#8fd6b4',
yellow: '#e3b341',
blue: '#6aa6ff',
magenta: '#b692e8',
cyan: '#5fd0e0',
white: '#cdd6dc',
brightBlack: '#93a1a9',
brightRed: '#f3625d',
brightGreen: '#8fd6b4',
brightYellow: '#e3b341',
brightBlue: '#6aa6ff',
brightMagenta: '#b692e8',
brightCyan: '#5fd0e0',
brightWhite: '#eef3f5',
};
const lightTheme: ITheme = {
background: '#f7fbfa',
foreground: '#0d1218',
cursor: '#007560',
cursorAccent: '#f7fbfa',
selectionBackground: '#00756033',
black: '#0d1218',
red: '#d73337',
green: '#2f8f6e',
yellow: '#9a6b00',
blue: '#2f6bd8',
magenta: '#7c4dd1',
cyan: '#0f7d92',
white: '#26323c',
brightBlack: '#555f68',
brightRed: '#d73337',
brightGreen: '#2f8f6e',
brightYellow: '#9a6b00',
brightBlue: '#2f6bd8',
brightMagenta: '#7c4dd1',
brightCyan: '#0f7d92',
brightWhite: '#0d1218',
};
export const WorkspaceTerminal = ({
jobId,
active,
}: {
jobId: string;
active: boolean;
}) => {
const containerRef = useRef<HTMLDivElement>(null);
const termRef = useRef<Terminal | null>(null);
const { resolvedTheme } = useTheme();
const themeIsLight = resolvedTheme === 'light';
const [status, setStatus] = useState<Status>('connecting');
const [errorText, setErrorText] = useState<string>();
const [reconnectKey, setReconnectKey] = useState(0);
// Update the live terminal's theme without tearing down the session.
useEffect(() => {
if (termRef.current) {
termRef.current.options.theme = themeIsLight ? lightTheme : darkTheme;
}
}, [themeIsLight]);
useEffect(() => {
if (!active) return;
const container = containerRef.current;
if (!container) return;
const abortController = new AbortController();
const signal = abortController.signal;
// Read through a function so TS doesn't narrow `aborted` to a constant after
// the first guard (it changes asynchronously, on cleanup).
const isAborted = () => signal.aborted;
let ws: WebSocket | undefined;
let resizeObserver: ResizeObserver | undefined;
const encoder = new TextEncoder();
const start = async () => {
const [{ Terminal }, { FitAddon }, { WebLinksAddon }] = await Promise.all(
[
import('@xterm/xterm'),
import('@xterm/addon-fit'),
import('@xterm/addon-web-links'),
],
);
if (isAborted()) return;
setStatus('connecting');
setErrorText(undefined);
let response: Response;
try {
response = await fetch(`/api/agent-jobs/${jobId}/terminal-token`, {
signal,
});
} catch {
if (!isAborted()) setStatus('error');
return;
}
if (isAborted()) return;
if (response.status === 503) {
setStatus('unconfigured');
return;
}
if (!response.ok) {
setStatus('error');
setErrorText(await response.text().catch(() => undefined));
return;
}
const { url } = (await response.json()) as { url: string };
const term = new Terminal({
fontFamily: TERMINAL_FONT,
fontSize: 13,
lineHeight: 1.2,
cursorBlink: true,
theme: themeIsLight ? lightTheme : darkTheme,
allowProposedApi: true,
scrollback: 5000,
});
const fit = new FitAddon();
term.loadAddon(fit);
term.loadAddon(new WebLinksAddon());
term.open(container);
fit.fit();
termRef.current = term;
const sendResize = () => {
if (ws?.readyState !== WebSocket.OPEN) return;
ws.send(
JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }),
);
};
ws = new WebSocket(url);
ws.binaryType = 'arraybuffer';
ws.onopen = () => {
if (isAborted()) return;
setStatus('connected');
sendResize();
term.focus();
};
ws.onmessage = (event: MessageEvent<ArrayBuffer | string>) => {
if (typeof event.data === 'string') term.write(event.data);
else term.write(new Uint8Array(event.data));
};
ws.onclose = () => {
if (!isAborted()) setStatus('closed');
};
ws.onerror = () => {
if (!isAborted()) setStatus('error');
};
term.onData((data) => {
if (ws?.readyState === WebSocket.OPEN) ws.send(encoder.encode(data));
});
term.onResize(() => sendResize());
resizeObserver = new ResizeObserver(() => {
try {
fit.fit();
} catch {
// ignore transient layout errors
}
});
resizeObserver.observe(container);
};
void start();
return () => {
abortController.abort();
resizeObserver?.disconnect();
ws?.close();
termRef.current?.dispose();
termRef.current = null;
};
// resolvedTheme intentionally excluded: handled by the theme effect above.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [active, jobId, reconnectKey]);
return (
<div className='relative flex h-full min-h-0 flex-col'>
<div className='border-border flex h-10 flex-none items-center justify-between gap-3 border-b px-3'>
<p className='text-muted-foreground text-xs'>
{status === 'connected'
? 'Connected · workspace shell'
: status === 'connecting'
? 'Connecting…'
: status === 'closed'
? 'Session ended'
: status === 'unconfigured'
? 'Terminal not configured'
: 'Connection error'}
</p>
{status === 'closed' || status === 'error' ? (
<Button
type='button'
variant='outline'
size='sm'
onClick={() => setReconnectKey((key) => key + 1)}
>
Reconnect
</Button>
) : null}
</div>
{status === 'unconfigured' ? (
<div className='text-muted-foreground flex flex-1 items-center justify-center p-6 text-center text-sm'>
The terminal is not enabled on this deployment.
<br />
Set NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL to enable it.
</div>
) : (
<div className='min-h-0 flex-1 overflow-hidden bg-[#080e14] p-2'>
<div ref={containerRef} className='h-full w-full' />
{errorText ? (
<p className='text-destructive mt-2 px-1 text-xs break-all'>
{errorText}
</p>
) : null}
</div>
)}
</div>
);
};
apps/next/src/env.ts
+10
View File
@@ -22,6 +22,9 @@ export const env = createEnv({
SPOON_AGENT_WORKER_URL: z.url().default('http://localhost:3921'),
SPOON_AGENT_WORKER_INTERNAL_TOKEN: z.string().optional(),
SPOON_WORKER_TOKEN: z.string().optional(),
// Secret shared with the worker for signing short-lived terminal tokens.
// Falls back (in code) to the worker internal token.
SPOON_AGENT_TERMINAL_SECRET: z.string().optional(),
},
/**
@@ -36,6 +39,10 @@ export const env = createEnv({
NEXT_PUBLIC_SENTRY_URL: z.string(),
NEXT_PUBLIC_SENTRY_ORG: z.string(),
NEXT_PUBLIC_SENTRY_PROJECT_NAME: z.string(),
// Browser-facing WebSocket base URL of the agent worker, e.g.
// `wss://worker.spoon.gbrown.org` (prod) or `ws://localhost:3921` (dev).
// When unset, the workspace Terminal tab is disabled.
NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL: z.string().optional(),
},
/**
* Destructure all variables from `process.env` to make sure they aren't tree-shaken away.
@@ -59,6 +66,9 @@ export const env = createEnv({
SPOON_AGENT_WORKER_INTERNAL_TOKEN:
process.env.SPOON_AGENT_WORKER_INTERNAL_TOKEN,
SPOON_WORKER_TOKEN: process.env.SPOON_WORKER_TOKEN,
SPOON_AGENT_TERMINAL_SECRET: process.env.SPOON_AGENT_TERMINAL_SECRET,
NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL:
process.env.NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL,
NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
NEXT_PUBLIC_CONVEX_URL: process.env.NEXT_PUBLIC_CONVEX_URL,
NEXT_PUBLIC_PLAUSIBLE_URL: process.env.NEXT_PUBLIC_PLAUSIBLE_URL,
apps/next/src/lib/agent-worker-proxy.ts
+21
View File
@@ -1,5 +1,6 @@
import 'server-only';
import { createHmac } from 'node:crypto';
import { NextResponse } from 'next/server';
import { env } from '@/env';
import { convexAuthNextjsToken } from '@convex-dev/auth/nextjs/server';
@@ -8,6 +9,26 @@ import { fetchQuery } from 'convex/nextjs';
import type { Id } from '@spoon/backend/convex/_generated/dataModel.js';
import { api } from '@spoon/backend/convex/_generated/api.js';
const terminalSecret = () =>
env.SPOON_AGENT_TERMINAL_SECRET ??
env.SPOON_AGENT_WORKER_INTERNAL_TOKEN ??
env.SPOON_WORKER_TOKEN;
// Mints a short-lived, job-scoped terminal token + the worker WS URL. Returns
// null when the terminal feature is not configured. The 2-minute expiry is a
// connect window only; an established PTY session persists past it.
export const mintTerminalToken = (jobId: Id<'agentJobs'>) => {
const secret = terminalSecret();
const base = env.NEXT_PUBLIC_SPOON_AGENT_WORKER_WS_URL;
if (!secret || !base) return null;
const expiresAt = Date.now() + 2 * 60 * 1000;
const payload = `${expiresAt}.${jobId}`;
const signature = createHmac('sha256', secret).update(payload).digest('hex');
const token = `${payload}.${signature}`;
const url = `${base.replace(/\/$/, '')}/jobs/${encodeURIComponent(jobId)}/terminal?token=${encodeURIComponent(token)}`;
return { url, expiresAt };
};
type RouteContext = {
params: Promise<{ jobId: string }> | { jobId: string };
};
bun.lock
+9
View File
@@ -107,6 +107,9 @@
"@spoon/backend": "workspace:*",
"@spoon/ui": "workspace:*",
"@t3-oss/env-nextjs": "^0.13.11",
"@xterm/addon-fit": "^0.11.0",
"@xterm/addon-web-links": "^0.12.0",
"@xterm/xterm": "^6.0.0",
"convex": "catalog:convex",
"monaco-editor": "latest",
"monaco-vim": "latest",
@@ -1689,6 +1692,12 @@
"@xmldom/xmldom": ["@xmldom/xmldom@0.8.11", "", {}, "sha512-cQzWCtO6C8TQiYl1ruKNn2U6Ao4o4WBBcbL61yJl84x+j5sOWWFU9X7DpND8XZG3daDppSsigMdfAIl2upQBRw=="],
"@xterm/addon-fit": ["@xterm/addon-fit@0.11.0", "", {}, "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g=="],
"@xterm/addon-web-links": ["@xterm/addon-web-links@0.12.0", "", {}, "sha512-4Smom3RPyVp7ZMYOYDoC/9eGJJJqYhnPLGGqJ6wOBfB8VxPViJNSKdgRYb8NpaM6YSelEKbA2SStD7lGyqaobw=="],
"@xterm/xterm": ["@xterm/xterm@6.0.0", "", {}, "sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg=="],
"@xtuc/ieee754": ["@xtuc/ieee754@1.2.0", "", {}, "sha512-DX8nKgqcGwsc0eJSqYt5lwP4DH5FlHnmuWWBRy7X0NcaGR0ZtuyeESgMwTYVEtxmsNGY+qit4QYT/MIYTOTPeA=="],
"@xtuc/long": ["@xtuc/long@4.2.2", "", {}, "sha512-NuHqBY1PB/D8xU6s/thBgOAiAP7HOYDQ32+BFZILJ8ivkUkAHQnWfn6WhL79Owj1qmUnoN/YPhktdIoucipkAQ=="],