Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

11.7 KB
Raw Blame
import { clearEnvironmentShareSearch } from '../utils/environmentShareUrl.js';
import { clearLibraryShareSearch } from '../utils/libraryShareUrl.js';
import {
  clearScheduleShareSearch,
  readScheduleShareSearch,
  writeScheduleShareSearch,
} from '../utils/scheduleShareUrl.js';
import {
  readSessionShareSearch,
  SHARED_SESSION_VIEW_VALUE,
  writeSessionShareSearch,
} from '../utils/sessionShareUrl.js';
import type { ResolvedRoutes, RoutePlace, RoutesConfig } from './types.js';

const DEFAULTS = {
  root: '/',
  settings: '/settings',
  library: '/library',
  libraryAgent: '/library/:agentId',
  schedules: '/schedules',
  environments: '/environments',
  buildAgent: '/build-agent',
  agent: '/agents/:agentName',
  session: '/sessions/:sessionId',
  sharedSession: '/sessions/share/:sessionId',
  sessionsBrowser: '/sessions',
} as const;

function normalizePath(path: string): string {
  const trimmed = path.trim();
  const withLead = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
  // Drop a trailing slash except for the root itself.
  return withLead.length > 1 && withLead.endsWith('/') ? withLead.slice(0, -1) : withLead;
}

function resolveOptional(value: string | false | undefined, fallback: string): string | null {
  if (value === false) return null;
  return normalizePath(value ?? fallback);
}

export function resolveRoutesConfig(routes?: RoutesConfig): ResolvedRoutes {
  const paths = routes?.paths;
  return {
    basename: routes?.basename ?? '',
    root: normalizePath(paths?.root ?? DEFAULTS.root),
    settings: resolveOptional(paths?.settings, DEFAULTS.settings),
    library: resolveOptional(paths?.library, DEFAULTS.library),
    libraryAgent: resolveOptional(paths?.libraryAgent, DEFAULTS.libraryAgent),
    schedules: resolveOptional(paths?.schedules, DEFAULTS.schedules),
    environments: resolveOptional(paths?.environments, DEFAULTS.environments),
    buildAgent: resolveOptional(paths?.buildAgent, DEFAULTS.buildAgent),
    agent: resolveOptional(paths?.agent, DEFAULTS.agent),
    session: resolveOptional(paths?.session, DEFAULTS.session),
    sharedSession: resolveOptional(paths?.sharedSession, DEFAULTS.sharedSession),
    sessionsBrowser: resolveOptional(paths?.sessionsBrowser, DEFAULTS.sessionsBrowser),
  };
}

function splitSegments(path: string): string[] {
  return path.split('/').filter(segment => segment.length > 0);
}

/** Fill a single-param template (`/agents/:agentName`) with an encoded value. */
function fillTemplate(template: string, value: string): string {
  return (
    '/' +
    splitSegments(template)
      .map(segment => (segment.startsWith(':') ? encodeURIComponent(value) : segment))
      .join('/')
  );
}

/** Build the URL path for a place, or `null` when that place has no configured route. */
export function buildPath(place: RoutePlace, routes: ResolvedRoutes): string | null {
  switch (place.type) {
    case 'root':
      return routes.root;
    case 'settings':
      return routes.settings;
    case 'library':
      return routes.library;
    case 'libraryAgent':
      return routes.libraryAgent == null ? null : fillTemplate(routes.libraryAgent, place.agentId);
    case 'schedules':
      return routes.schedules;
    case 'environments':
      return routes.environments;
    case 'buildAgent':
      return routes.buildAgent;
    case 'agent':
      return routes.agent == null ? null : fillTemplate(routes.agent, place.agentName);
    case 'session':
      return routes.session == null ? null : fillTemplate(routes.session, place.sessionId);
    case 'sharedSession':
      return routes.sharedSession == null ? null : fillTemplate(routes.sharedSession, place.sessionId);
    case 'sessionsBrowser':
      return routes.sessionsBrowser;
  }
}

/**
 * Absolute href that boots the shell on a history session (`/sessions/:id`).
 * Includes `routes.basename` and clears place-owned share query keys.
 */
export function buildSessionResumeHref({
  sessionId,
  routes,
  href = typeof window === 'undefined' ? 'http://localhost/' : window.location.href,
}: {
  sessionId: string;
  routes: ResolvedRoutes;
  href?: string;
}): string | null {
  const sessionPath = buildPath({ type: 'session', sessionId }, routes);
  if (sessionPath == null) return null;
  const url = new URL(href);
  const basename = routes.basename.endsWith('/') ? routes.basename.slice(0, -1) : routes.basename;
  url.pathname = `${basename}${sessionPath}` || '/';
  url.search = sanitizeSearchForPlace({ type: 'session', sessionId }, url.search);
  url.hash = '';
  return url.toString();
}

/** Absolute detail-only share URL, with a query fallback when SDK routing is unavailable. */
export function buildSharedSessionHref({
  sessionId,
  routes,
  href = typeof window === 'undefined' ? 'http://localhost/' : window.location.href,
}: {
  sessionId: string;
  routes: ResolvedRoutes | null;
  href?: string;
}): string {
  const place: RoutePlace = { type: 'sharedSession', sessionId };
  const sessionPath = routes == null ? null : buildPath(place, routes);
  const url = new URL(href);
  if (routes != null && sessionPath != null) {
    const basename = routes.basename.endsWith('/') ? routes.basename.slice(0, -1) : routes.basename;
    url.pathname = `${basename}${sessionPath}` || '/';
    url.search = sanitizeSearchForPlace(place, url.search);
    url.hash = '';
    return url.toString();
  }
  writeSessionShareSearch(url.searchParams, {
    sessionId,
    agentId: null,
    tab: null,
    view: SHARED_SESSION_VIEW_VALUE,
    timeRange: null,
  });
  return url.toString();
}

/**
 * Remove query state owned by a different shell place while preserving host
 * parameters. Settings is an overlay, so it retains the underlying place state.
 */
export function sanitizeSearchForPlace(place: RoutePlace, search: string): string {
  if (place.type === 'settings') return search;

  const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
  if (place.type === 'sessionsBrowser') {
    writeSessionShareSearch(params, { tab: null });
    clearScheduleShareSearch(params);
    clearEnvironmentShareSearch(params);
    clearLibraryShareSearch(params);
  } else if (place.type === 'library') {
    writeSessionShareSearch(params, {
      sessionId: null,
      agentId: null,
      tab: null,
      view: null,
      timeRange: null,
    });
    clearScheduleShareSearch(params);
    clearEnvironmentShareSearch(params);
    // Keep `agent_name` — owned by the library place.
  } else if (place.type === 'libraryAgent') {
    const share = readSessionShareSearch(search);
    const scheduleShare = readScheduleShareSearch(search);
    writeSessionShareSearch(params, {
      view: null,
      timeRange: null,
      ...(share.sessionId != null && share.agentId !== place.agentId ? { sessionId: null, agentId: null } : {}),
    });
    clearScheduleShareSearch(params);
    clearEnvironmentShareSearch(params);
    clearLibraryShareSearch(params);
    if (share.tab === 'schedules') {
      writeScheduleShareSearch(params, {
        status: scheduleShare.status,
        q: scheduleShare.q,
        isNew: scheduleShare.isNew,
      });
    }
  } else if (place.type === 'schedules') {
    writeSessionShareSearch(params, {
      sessionId: null,
      agentId: null,
      tab: null,
      view: null,
      timeRange: null,
    });
    clearEnvironmentShareSearch(params);
    clearLibraryShareSearch(params);
    // Keep `agent` / `status` / `q` — owned by the schedules place.
  } else if (place.type === 'environments') {
    writeSessionShareSearch(params, {
      sessionId: null,
      agentId: null,
      tab: null,
      view: null,
      timeRange: null,
    });
    clearScheduleShareSearch(params);
    clearLibraryShareSearch(params);
    // Keep `envQ` / `envIsNew` — owned by the environments place.
  } else {
    writeSessionShareSearch(params, {
      sessionId: null,
      agentId: null,
      tab: null,
      view: null,
      timeRange: null,
    });
    clearScheduleShareSearch(params);
    clearEnvironmentShareSearch(params);
    clearLibraryShareSearch(params);
  }
  const next = params.toString();
  return next.length > 0 ? `?${next}` : '';
}

/** Percent-decode a segment; `null` when the URL carries a malformed escape. */
function decodeSegment(segment: string): string | null {
  try {
    return decodeURIComponent(segment);
  } catch {
    return null;
  }
}

/** Match a single-param template against concrete segments; returns the decoded param or null. */
function matchTemplate(template: string, segments: string[]): string | null {
  const templateSegments = splitSegments(template);
  if (templateSegments.length !== segments.length) return null;
  let param: string | null = null;
  for (const [i, tpl] of templateSegments.entries()) {
    const seg = segments[i];
    if (seg === undefined) return null;
    if (tpl.startsWith(':')) {
      // A malformed escape is an unusable id, so the path simply does not match.
      const decoded = decodeSegment(seg);
      if (decoded == null) return null;
      param = decoded;
    } else if (tpl !== seg) {
      return null;
    }
  }
  return param;
}

/** Parse a (basename-relative) pathname into a place, or `null` when unrecognized. */
export function matchPath(pathname: string, routes: ResolvedRoutes): RoutePlace | null {
  const normalized = normalizePath(pathname);
  const segments = splitSegments(normalized);

  if (routes.settings != null && normalized === routes.settings) {
    return { type: 'settings' };
  }
  if (routes.library != null && normalized === routes.library) {
    return { type: 'library' };
  }
  if (routes.sessionsBrowser != null && normalized === routes.sessionsBrowser) {
    return { type: 'sessionsBrowser' };
  }
  if (routes.libraryAgent != null) {
    const agentId = matchTemplate(routes.libraryAgent, segments);
    if (agentId != null) return { type: 'libraryAgent', agentId };
  }
  if (routes.schedules != null && normalized === routes.schedules) {
    return { type: 'schedules' };
  }
  if (routes.environments != null && normalized === routes.environments) {
    return { type: 'environments' };
  }
  if (routes.buildAgent != null && normalized === routes.buildAgent) {
    return { type: 'buildAgent' };
  }
  if (routes.agent != null) {
    const agentName = matchTemplate(routes.agent, segments);
    if (agentName != null) return { type: 'agent', agentName };
  }
  if (routes.session != null) {
    const sessionId = matchTemplate(routes.session, segments);
    if (sessionId != null) return { type: 'session', sessionId };
  }
  if (routes.sharedSession != null) {
    const sessionId = matchTemplate(routes.sharedSession, segments);
    if (sessionId != null) return { type: 'sharedSession', sessionId };
  }
  if (normalized === routes.root) {
    return { type: 'root' };
  }
  return null;
}

/** Pathname place, or library agent from `?agentId=` when the path is root. */
export function matchLocation({
  pathname,
  search,
  routes,
}: {
  pathname: string;
  search: string;
  routes: ResolvedRoutes;
}): RoutePlace | null {
  const matched = matchPath(pathname, routes);
  if (matched == null || matched.type !== 'root') return matched;
  const { agentId, sessionId, view } = readSessionShareSearch(search);
  if (view === SHARED_SESSION_VIEW_VALUE && sessionId != null) return { type: 'sharedSession', sessionId };
  return agentId != null ? { type: 'libraryAgent', agentId } : matched;
}

export function placesEqual(a: RoutePlace, b: RoutePlace): boolean {
  if (a.type !== b.type) return false;
  if (a.type === 'agent' && b.type === 'agent') return a.agentName === b.agentName;
  if (a.type === 'libraryAgent' && b.type === 'libraryAgent') return a.agentId === b.agentId;
  if (a.type === 'session' && b.type === 'session') return a.sessionId === b.sessionId;
  if (a.type === 'sharedSession' && b.type === 'sharedSession') return a.sessionId === b.sessionId;
  return true;
}