Skip to content

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

6.4 KB
Raw Blame
export const SESSION_ID_QUERY = 'sessionId';
export const AGENT_ID_QUERY = 'agentId';
export const AGENT_TAB_QUERY = 'tab';
export const SESSIONS_VIEW_QUERY = 'view';
export const SESSIONS_VIEW_VALUE = 'sessions';
export const SHARED_SESSION_VIEW_VALUE = 'shared-session';
export const SESSION_START_TIME_QUERY = 's_sts';
export const SESSION_END_TIME_QUERY = 's_ets';
export const SESSION_TIME_WINDOW_QUERY = 's_tw';
export const SESSION_TIME_BUFFER_MS = 5 * 60 * 1000;
export const SESSION_CUSTOM_RANGE_MAX_DAYS = 70;
export const DEFAULT_SESSION_TIME_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
export const DEFAULT_METRICS_TIME_WINDOW_MS = 24 * 60 * 60 * 1000;

export type LibraryAgentTab = 'overview' | 'sessions' | 'schedules' | 'code' | 'metrics';
export type SessionShareView = typeof SESSIONS_VIEW_VALUE | typeof SHARED_SESSION_VIEW_VALUE;

export type SessionTimeRange = {
  startTs: number;
  endTs: number;
  timeWindowMs?: number;
};

export type SessionShareSearch = {
  sessionId: string | null;
  agentId: string | null;
  tab: LibraryAgentTab | null;
  view: SessionShareView | null;
  timeRange: SessionTimeRange | null;
};

export type SessionShareWrite = {
  sessionId?: string | null;
  agentId?: string | null;
  tab?: LibraryAgentTab | null;
  view?: SessionShareView | null;
  timeRange?: SessionTimeRange | null;
};

function parseLibraryAgentTab(value: string | null): LibraryAgentTab | null {
  if (
    value === 'overview' ||
    value === 'sessions' ||
    value === 'schedules' ||
    value === 'code' ||
    value === 'metrics'
  ) {
    return value;
  }
  return null;
}

function nonEmpty(value: string | null): string | null {
  return value != null && value.length > 0 ? value : null;
}

function parseMs(value: string | null): number | null {
  if (value == null || value.length === 0) return null;
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : null;
}

export function defaultSessionTimeRange(now = Date.now()): SessionTimeRange {
  return {
    startTs: now - DEFAULT_SESSION_TIME_WINDOW_MS,
    endTs: now,
    timeWindowMs: DEFAULT_SESSION_TIME_WINDOW_MS,
  };
}

export function defaultMetricsTimeRange(now = Date.now()): SessionTimeRange {
  return {
    startTs: now - DEFAULT_METRICS_TIME_WINDOW_MS,
    endTs: now,
    timeWindowMs: DEFAULT_METRICS_TIME_WINDOW_MS,
  };
}

export function sessionTimeRangeFromCreatedAt(createdAt: string): SessionTimeRange | null {
  const createdAtMs = new Date(createdAt).getTime();
  if (Number.isNaN(createdAtMs)) return null;
  return {
    startTs: createdAtMs - SESSION_TIME_BUFFER_MS,
    endTs: createdAtMs + SESSION_TIME_BUFFER_MS,
  };
}

export function resolveSessionTimeRange(range: SessionTimeRange, now = Date.now()): { startTs: number; endTs: number } {
  if (range.timeWindowMs != null) {
    return { startTs: now - range.timeWindowMs, endTs: now };
  }
  return { startTs: range.startTs, endTs: range.endTs };
}

export function readSessionShareSearch(search: string): SessionShareSearch {
  const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
  const startTs = parseMs(params.get(SESSION_START_TIME_QUERY));
  const endTs = parseMs(params.get(SESSION_END_TIME_QUERY));
  const timeWindowMs = parseMs(params.get(SESSION_TIME_WINDOW_QUERY));
  const view = params.get(SESSIONS_VIEW_QUERY);
  const now = Date.now();
  return {
    sessionId: nonEmpty(params.get(SESSION_ID_QUERY)),
    agentId: nonEmpty(params.get(AGENT_ID_QUERY)),
    tab: parseLibraryAgentTab(params.get(AGENT_TAB_QUERY)),
    view: view === SESSIONS_VIEW_VALUE || view === SHARED_SESSION_VIEW_VALUE ? view : null,
    timeRange:
      startTs != null && endTs != null
        ? { startTs, endTs }
        : timeWindowMs != null
          ? { startTs: now - timeWindowMs, endTs: now, timeWindowMs }
          : null,
  };
}

/** Library details tab: `tab=` wins; a matching share `sessionId` still opens Sessions. */
export function libraryAgentTabFromSearch(share: SessionShareSearch, agentId: string): LibraryAgentTab {
  if (share.tab != null) return share.tab;
  return share.sessionId != null && share.agentId === agentId ? 'sessions' : 'overview';
}

export function writeSessionShareSearch(params: URLSearchParams, next: SessionShareWrite): void {
  if (next.sessionId === null) params.delete(SESSION_ID_QUERY);
  else if (next.sessionId != null) params.set(SESSION_ID_QUERY, next.sessionId);
  if (next.agentId === null) params.delete(AGENT_ID_QUERY);
  else if (next.agentId != null) params.set(AGENT_ID_QUERY, next.agentId);
  if (next.tab === null) params.delete(AGENT_TAB_QUERY);
  else if (next.tab != null) params.set(AGENT_TAB_QUERY, next.tab);
  if (next.view === null) params.delete(SESSIONS_VIEW_QUERY);
  else if (next.view != null) params.set(SESSIONS_VIEW_QUERY, next.view);
  if (next.timeRange === null) {
    params.delete(SESSION_START_TIME_QUERY);
    params.delete(SESSION_END_TIME_QUERY);
    params.delete(SESSION_TIME_WINDOW_QUERY);
  } else if (next.timeRange != null) {
    if (next.timeRange.timeWindowMs != null) {
      params.set(SESSION_TIME_WINDOW_QUERY, String(next.timeRange.timeWindowMs));
      params.delete(SESSION_START_TIME_QUERY);
      params.delete(SESSION_END_TIME_QUERY);
    } else {
      params.set(SESSION_START_TIME_QUERY, String(next.timeRange.startTs));
      params.set(SESSION_END_TIME_QUERY, String(next.timeRange.endTs));
      params.delete(SESSION_TIME_WINDOW_QUERY);
    }
  }
}

/** Share link for a library or global session. Works with or without `withRouter`. */
export function buildAgentSessionShareUrl({
  sessionId,
  agentId,
  createdAt,
  view,
  href = typeof window === 'undefined' ? '' : window.location.href,
}: {
  sessionId: string;
  agentId?: string;
  createdAt?: string;
  view?: typeof SESSIONS_VIEW_VALUE | null;
  href?: string;
}): string {
  const url = new URL(href);
  writeSessionShareSearch(url.searchParams, {
    sessionId,
    agentId: agentId == null || agentId.length === 0 ? null : agentId,
    ...(view === undefined ? {} : { view }),
    timeRange: createdAt == null ? undefined : sessionTimeRangeFromCreatedAt(createdAt),
  });
  return url.toString();
}

export const SESSION_SHARE_CHANGE_EVENT = 'trueforge-session-share';

export function replaceSessionShareSearch(next: SessionShareWrite): string {
  const url = new URL(window.location.href);
  writeSessionShareSearch(url.searchParams, next);
  window.history.replaceState(window.history.state, '', url);
  window.dispatchEvent(new Event(SESSION_SHARE_CHANGE_EVENT));
  return url.search;
}