The open-source agent harness - the runtime layer that turns an LLM into a working agent.
'use client';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { useLocation, useNavigate } from 'react-router-dom';
import { sessionIsCreateAgent } from '../atoms/lib/sessionCreateAgent.js';
import { findAgentByName } from '../atoms/lib/useSearchAgentsList.js';
import {
useOptionalAgentSessionsServer,
useOptionalCatalogServer,
useOptionalPermissionsServer,
useOptionalSandboxEnvironmentServer,
useOptionalScheduleServer,
useOptionalServer,
useServerCapabilities,
useServerCapabilitiesSettled,
} from '../server/ServerContext.js';
import { libraryAgentId, useShellMode } from '../server/ShellModeContext.js';
import { toEffectiveRoutes } from '../server/serverChrome.js';
import { getErrorMessage } from '../utils/getErrorMessage.js';
import {
readHistoryAgentSearch,
updateHistoryAgentSearch,
type HistoryAgentSearch,
} from '../utils/historyAgentSearch.js';
import { deriveChatPlace, derivePlace } from './derivePlace.js';
import { buildPath, matchLocation, placesEqual, sanitizeSearchForPlace } from './paths.js';
import type { ResolvedRoutes, RoutePlace, ShellSnapshot } from './types.js';
// Filter intent follows chat history across chat/session URLs, but must not leak into unrelated surfaces.
function placeOwnsHistoryAgentSearch(place: RoutePlace): boolean {
return place.type === 'root' || place.type === 'agent' || place.type === 'session';
}
function isSessionsPlace(place: RoutePlace): boolean {
return place.type === 'sessionsBrowser' || place.type === 'sharedSession';
}
/**
* Single bidirectional bridge between shell state and the URL. Mounted under
* `ShellModeProvider` but outside the keyed chat runtime so boot applies once.
*/
export function ShellRouteSync({
routes,
activeRemoteId,
initialSettingsOpen,
}: {
routes: ResolvedRoutes;
activeRemoteId: string | undefined;
initialSettingsOpen: boolean;
}) {
const shell = useShellMode();
const server = useOptionalServer();
const catalog = useOptionalCatalogServer();
const sessions = useOptionalAgentSessionsServer();
const permissions = useOptionalPermissionsServer();
const schedules = useOptionalScheduleServer();
const sandboxEnvironments = useOptionalSandboxEnvironmentServer();
const capabilities = useServerCapabilities();
const capabilitiesSettled = useServerCapabilitiesSettled();
const navigate = useNavigate();
const location = useLocation();
// Same gates as sidebar chrome: missing optional ports unregister their paths.
const effectiveRoutes = useMemo(
() => toEffectiveRoutes({ routes, catalog, capabilities, sessions, schedules, sandboxEnvironments }),
[routes, catalog, capabilities, sessions, schedules, sandboxEnvironments],
);
const settingsChromeEnabled = effectiveRoutes.settings != null;
// Gate identity only — avoid re-syncing when capabilities object identity churns
// without changing which paths are registered (would clobber window share query).
const routeGatesKey = [
effectiveRoutes.settings,
effectiveRoutes.sessionsBrowser,
effectiveRoutes.sharedSession,
effectiveRoutes.libraryAgent,
effectiveRoutes.schedules,
effectiveRoutes.environments,
].join('\0');
const snapshot: ShellSnapshot = {
settingsOpen: shell.settingsOpen,
libraryOpen: shell.libraryOpen,
sessionsOpen: shell.sessionsOpen,
sharedSessionId: shell.sharedSessionId,
libraryAgentId: shell.libraryAgentId,
schedulesOpen: shell.schedulesOpen,
environmentsOpen: shell.environmentsOpen,
pendingSessionId: shell.pendingSessionId,
activeRemoteId,
sessionAccessError: shell.sessionAccessError,
mode: shell.mode,
agentConfigMode: shell.agentConfigMode,
};
const place = derivePlace(snapshot);
const placeKey = JSON.stringify(place);
// Guards. `selfNavPathRef` marks a path we navigated to ourselves so the
// URL->shell effect does not re-apply it. `prevPlaceRef` powers push/replace.
const selfNavPathRef = useRef<string | null>(null);
const prevPlaceRef = useRef<RoutePlace | null>(null);
const appliedUrlPlaceRef = useRef<RoutePlace | null>(null);
const bootedRef = useRef(false);
const bootPlaceRef = useRef<RoutePlace | null>(null);
// Bumped when a boot session load is abandoned, so shell->URL sync runs again.
const [shellSyncNonce, setShellSyncNonce] = useState(0);
const bootHistoryAgentRef = useRef<HistoryAgentSearch | null>(null);
// Latest session id the URL asked for, so slower lookups cannot bind over it.
const requestedSessionRef = useRef<string | null>(null);
// Changes when the user starts a new chat/agent or opens another session.
const chatIdentity = `${shell.runtimeKey}\0${shell.pendingSessionEpoch}`;
const chatIdentityRef = useRef(chatIdentity);
chatIdentityRef.current = chatIdentity;
const requestedHistoryAgentRef = useRef<string | null>(null);
// Boot owns the first URL; the ongoing effects skip their initial commit so
// they do not fight boot with the stale first-render place.
const shellSyncStartedRef = useRef(false);
const urlSyncStartedRef = useRef(false);
/**
* A URL carries only the id, so ask the server whether it names a mutable
* draft or an agent chat; guessing "mutable" opens an agent session as a
* blank draft. `requestedSessionRef` drops replies a later place superseded.
* Access denied / missing session: keep the URL and show a full-pane error.
*/
const goToRoot = useCallback(() => {
shell.setSettingsOpen(false);
shell.setLibraryOpen(false);
shell.setSchedulesOpen(false);
shell.setEnvironmentsOpen(false);
switch (shell.agentConfigMode) {
case 'AgentLibrary':
shell.openLibraryHome();
return;
case 'AgentComposer':
case 'AgentLibraryWithComposer':
shell.openDraft();
return;
case 'SingleAgent':
shell.clearChat();
return;
}
}, [shell]);
const releaseAbandonedBootSession = useCallback((sessionId: string) => {
// Boot waits until the derived place matches the deep link. If that load is
// superseded or abandoned, clear the wait so later shell→URL updates can run.
const bootPlace = bootPlaceRef.current;
if (bootPlace?.type === 'session' && bootPlace.sessionId === sessionId) {
bootPlaceRef.current = null;
setShellSyncNonce(nonce => nonce + 1);
}
}, []);
const openSession = useCallback(
(sessionId: string) => {
requestedSessionRef.current = sessionId;
if (server == null) {
shell.openHistorySession({ sessionId });
return;
}
const requestedChatIdentity = chatIdentityRef.current;
// Shared viewers can read a session but cannot subscribe/send. Prefer the
// read-only share surface when MANAGE is missing and that route exists.
const canManagePromise =
permissions == null || sessions == null
? Promise.resolve(true)
: permissions
.listPermissions({ resourceType: 'session', resourceIds: [sessionId] })
.then(response => (response.data.permissions[sessionId] ?? []).includes('MANAGE'))
.catch(() => true);
void Promise.all([server.getSession({ sessionId }), canManagePromise])
.then(([session, canManage]) => {
if (requestedSessionRef.current !== sessionId) {
releaseAbandonedBootSession(sessionId);
return;
}
if (!canManage) {
// Leave the /sessions/:id boot wait so shell→URL can rewrite to share.
releaseAbandonedBootSession(sessionId);
shell.openSharedSession(sessionId);
return;
}
shell.openHistorySession({
sessionId,
isMutable: session.isMutable,
isCreateAgent: sessionIsCreateAgent(session),
...(session.agentName != null ? { agentName: session.agentName } : {}),
});
})
.catch((error: unknown) => {
if (requestedSessionRef.current !== sessionId) {
releaseAbandonedBootSession(sessionId);
return;
}
// The user already left (New Chat, agent, another session): do not pull them back.
if (chatIdentityRef.current !== requestedChatIdentity) {
releaseAbandonedBootSession(sessionId);
return;
}
shell.openInaccessibleSession({
sessionId,
message: getErrorMessage(error, 'This session could not be loaded.'),
});
});
},
[permissions, releaseAbandonedBootSession, server, sessions, shell],
);
const applyHistoryAgentSearch = useCallback(
(next: HistoryAgentSearch | null) => {
if (next == null) {
requestedHistoryAgentRef.current = null;
bootHistoryAgentRef.current = null;
shell.setHistoryAgentFilter(null);
return;
}
const requestKey = `${next.intent}\0${next.agentName}`;
const current = shell.historyAgentFilter;
if (current?.intent === next.intent && current.agentName === next.agentName && current.agentId != null) {
requestedHistoryAgentRef.current = null;
return;
}
requestedHistoryAgentRef.current = requestKey;
shell.setHistoryAgentFilter(next);
if (server == null) return;
void findAgentByName({ server, agentName: next.agentName })
.then(agent => {
if (requestedHistoryAgentRef.current !== requestKey) return;
if (agent == null) {
requestedHistoryAgentRef.current = null;
bootHistoryAgentRef.current = null;
shell.setHistoryAgentFilter(null);
return;
}
requestedHistoryAgentRef.current = null;
shell.setHistoryAgentFilter({
agentId: libraryAgentId(agent),
agentName: agent.name,
intent: next.intent,
});
})
.catch(() => {
if (requestedHistoryAgentRef.current !== requestKey) return;
requestedHistoryAgentRef.current = null;
bootHistoryAgentRef.current = null;
shell.setHistoryAgentFilter(null);
});
},
[server, shell],
);
const openAgent = useCallback(
(agentName: string) => {
shell.selectLibraryAgent({ isMutable: false, agentName });
applyHistoryAgentSearch({ intent: 'try-agent', agentName });
},
[applyHistoryAgentSearch, shell],
);
const applyPlace = useCallback(
(target: RoutePlace) => {
switch (target.type) {
case 'settings':
shell.setSettingsOpen(true);
return;
case 'library':
shell.setLibraryOpen(true);
return;
case 'sessionsBrowser':
shell.setSessionsOpen(true);
return;
case 'sharedSession':
shell.openSharedSession(target.sessionId);
return;
case 'libraryAgent':
shell.openLibraryAgent(target.agentId);
return;
case 'schedules':
shell.setSchedulesOpen(true);
return;
case 'environments':
shell.setEnvironmentsOpen(true);
return;
case 'buildAgent':
shell.openAgentBuilder();
return;
case 'session':
shell.setLibraryOpen(false);
if (shell.pendingSessionId === target.sessionId || activeRemoteId === target.sessionId) return;
openSession(target.sessionId);
return;
case 'agent':
shell.setLibraryOpen(false);
openAgent(target.agentName);
return;
case 'root':
goToRoot();
return;
}
},
[shell, activeRemoteId, goToRoot, openAgent, openSession],
);
// Boot: URL wins, except an explicit `initialSettingsOpen` overlay. Boot is the
// sole authority for the first commit and sets the final URL + `prevPlaceRef`.
useEffect(() => {
if (bootedRef.current) return;
const configuredUrlPlace = matchLocation({
pathname: location.pathname,
search: location.search,
routes,
});
if (!capabilitiesSettled && configuredUrlPlace?.type === 'settings') return;
bootedRef.current = true;
const urlPlace = matchLocation({
pathname: location.pathname,
search: location.search,
routes: effectiveRoutes,
}) ?? { type: 'root' };
const historyAgentSearch: HistoryAgentSearch | null =
urlPlace.type === 'agent'
? { intent: 'try-agent', agentName: urlPlace.agentName }
: placeOwnsHistoryAgentSearch(urlPlace)
? readHistoryAgentSearch(location.search)
: null;
bootHistoryAgentRef.current = historyAgentSearch;
appliedUrlPlaceRef.current = urlPlace;
const settingsOnBoot = settingsChromeEnabled && (initialSettingsOpen || urlPlace.type === 'settings');
if (urlPlace.type === 'settings') {
if (settingsChromeEnabled) shell.setSettingsOpen(true);
} else if (urlPlace.type === 'library') {
shell.setLibraryOpen(true);
} else if (urlPlace.type === 'sessionsBrowser') {
shell.setSessionsOpen(true);
} else if (urlPlace.type === 'libraryAgent') {
shell.openLibraryAgent(urlPlace.agentId);
} else if (urlPlace.type === 'schedules') {
shell.setSchedulesOpen(true);
} else if (urlPlace.type === 'environments') {
shell.setEnvironmentsOpen(true);
} else {
const chatPlace = deriveChatPlace(snapshot);
if (!placesEqual(chatPlace, urlPlace)) applyPlace(urlPlace);
if (settingsOnBoot) shell.setSettingsOpen(true);
}
if (urlPlace.type !== 'agent' && historyAgentSearch != null) {
applyHistoryAgentSearch(historyAgentSearch);
} else if (!placeOwnsHistoryAgentSearch(urlPlace)) {
applyHistoryAgentSearch(null);
}
const desiredPlace: RoutePlace = settingsOnBoot ? { type: 'settings' } : urlPlace;
bootPlaceRef.current = placesEqual(place, desiredPlace) ? null : desiredPlace;
const desiredPath = buildPath(desiredPlace, effectiveRoutes);
const desiredSearch = updateHistoryAgentSearch(
sanitizeSearchForPlace(desiredPlace, location.search),
historyAgentSearch,
);
prevPlaceRef.current = desiredPlace;
if (desiredPath != null && (desiredPath !== location.pathname || desiredSearch !== location.search)) {
selfNavPathRef.current = desiredPath !== location.pathname ? desiredPath : null;
navigate({ pathname: desiredPath, search: desiredSearch, hash: location.hash }, { replace: true });
}
// Boot runs once after any capability-dependent Settings destination resolves.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [capabilitiesSettled]);
// Shell -> URL: mirror the derived place. Skip the first commit (boot owns it).
useEffect(() => {
if (!bootedRef.current) return;
if (!shellSyncStartedRef.current) {
shellSyncStartedRef.current = true;
return;
}
const bootPlace = bootPlaceRef.current;
if (bootPlace != null) {
if (!placesEqual(place, bootPlace)) return;
bootPlaceRef.current = null;
}
const target = buildPath(place, effectiveRoutes);
if (target == null) return; // place has no configured URL (e.g. settings disabled)
const basename = effectiveRoutes.basename.endsWith('/')
? effectiveRoutes.basename.slice(0, -1)
: effectiveRoutes.basename;
const browserPathname = `${basename}${location.pathname}` || '/';
const latestSearch = window.location.pathname === browserPathname ? window.location.search : location.search;
const ownsHistoryAgentSearch = placeOwnsHistoryAgentSearch(place);
const historyAgentSearch = ownsHistoryAgentSearch
? shell.historyAgentFilter == null
? bootHistoryAgentRef.current
: {
intent: shell.historyAgentFilter.intent,
agentName: shell.historyAgentFilter.agentName,
}
: null;
if (!ownsHistoryAgentSearch && shell.historyAgentFilter != null) {
requestedHistoryAgentRef.current = null;
shell.setHistoryAgentFilter(null);
}
if (shell.historyAgentFilter != null) bootHistoryAgentRef.current = null;
const targetSearch = updateHistoryAgentSearch(sanitizeSearchForPlace(place, latestSearch), historyAgentSearch);
const prev = prevPlaceRef.current;
prevPlaceRef.current = place;
if (target === location.pathname && targetSearch === location.search) return;
// Replace when a fresh chat just acquired its session id (same place, new id).
const replace =
place.type === 'session' && shell.pendingSessionId == null && prev != null && prev.type !== 'session';
selfNavPathRef.current = target !== location.pathname ? target : null;
// Query keys owned by other shell places are removed; host keys and hash survive.
navigate({ pathname: target, search: targetSearch, hash: location.hash }, { replace });
// location.pathname intentionally excluded: only react to shell-derived place changes.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [placeKey, routeGatesKey, shellSyncNonce, shell.historyAgentFilter?.agentName, shell.historyAgentFilter?.intent]);
// URL -> shell: apply on genuine location changes (Back/Forward, manual edits).
useEffect(() => {
if (!bootedRef.current) return;
if (!urlSyncStartedRef.current) {
urlSyncStartedRef.current = true;
return;
}
if (selfNavPathRef.current === location.pathname) {
selfNavPathRef.current = null;
appliedUrlPlaceRef.current = place;
return;
}
const urlPlace = matchLocation({
pathname: location.pathname,
search: location.search,
routes: effectiveRoutes,
});
if (urlPlace == null) {
// Unknown path: normalize to root.
const rootPath = effectiveRoutes.root;
const rootSearch = sanitizeSearchForPlace({ type: 'root' }, location.search);
selfNavPathRef.current = rootPath;
navigate({ pathname: rootPath, search: rootSearch, hash: location.hash }, { replace: true });
applyPlace({ type: 'root' });
applyHistoryAgentSearch(readHistoryAgentSearch(rootSearch));
return;
}
const previousUrlPlace = appliedUrlPlaceRef.current;
appliedUrlPlaceRef.current = urlPlace;
if (previousUrlPlace == null || !placesEqual(previousUrlPlace, urlPlace)) {
if (urlPlace.type !== 'settings' && shell.settingsOpen) {
// Leaving settings via Back to a chat place.
shell.setSettingsOpen(false);
}
if (urlPlace.type !== 'library' && urlPlace.type !== 'libraryAgent' && shell.libraryOpen) {
shell.setLibraryOpen(false);
}
if (!isSessionsPlace(urlPlace) && shell.sessionsOpen) {
shell.setSessionsOpen(false);
}
if (urlPlace.type !== 'schedules' && shell.schedulesOpen) {
// Leaving schedules via Back to a chat place.
shell.setSchedulesOpen(false);
}
if (urlPlace.type !== 'environments' && shell.environmentsOpen) {
shell.setEnvironmentsOpen(false);
}
applyPlace(urlPlace);
}
if (urlPlace.type !== 'agent' && placeOwnsHistoryAgentSearch(urlPlace)) {
applyHistoryAgentSearch(readHistoryAgentSearch(location.search));
} else if (!placeOwnsHistoryAgentSearch(urlPlace)) {
applyHistoryAgentSearch(null);
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [location.pathname, location.search]);
return null;
}