@oar-sh/oar 0.9.0

package/server/services/claude-context-usage.mjs

@@ -0,0 +1,240 @@
+'use strict';
+
+/**
+ * Maps the Claude Agent SDK's context-usage control response onto the relay's
+ * existing context-snapshot contract.
+ *
+ * Claude sessions have no Copilot `events.jsonl` to tail, so this is the only
+ * source of context data for them. The SDK hands back the same breakdown that
+ * powers `/context` in Claude Code — see `SDKControlGetContextUsageResponse` in
+ * `@anthropic-ai/claude-agent-sdk`.
+ */
+
+// Category names as the SDK reports them, mapped onto the snapshot's coarser
+// system/tools/messages buckets. Matched case-insensitively; unknown categories
+// are still carried in the view payload, they just don't fold into a bucket.
+const SYSTEM_CATEGORY_NAMES = new Set(['system prompt', 'memory files', 'custom agents']);
+const TOOLS_CATEGORY_NAMES = new Set(['system tools', 'tools', 'mcp tools', 'skills', 'slash commands']);
+const MESSAGES_CATEGORY_NAMES = new Set(['messages', 'conversation']);
+const FREE_CATEGORY_NAMES = new Set(['free space', 'free', 'autocompact buffer']);
+
+function toNullableInt(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return Math.round(n);
+}
+
+function toNullablePercent(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return Math.round(n * 100) / 100;
+}
+
+function normalizeText(value) {
+  return String(value || '').trim();
+}
+
+export function isFreeSpaceCategoryName(name) {
+  return FREE_CATEGORY_NAMES.has(normalizeText(name).toLowerCase());
+}
+
+/**
+ * Validate and normalize a raw SDK context-usage response. Returns null for
+ * anything that isn't usable, so callers never have to guard field-by-field.
+ */
+export function normalizeClaudeContextUsage(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const totalTokens = toNullableInt(raw.totalTokens);
+  const maxTokens = toNullableInt(raw.maxTokens) ?? toNullableInt(raw.rawMaxTokens);
+  if (totalTokens === null && maxTokens === null) return null;
+
+  const categories = (Array.isArray(raw.categories) ? raw.categories : [])
+    .map((entry) => {
+      const name = normalizeText(entry?.name);
+      const tokens = toNullableInt(entry?.tokens);
+      if (!name || tokens === null) return null;
+      return {
+        name,
+        tokens,
+        color: normalizeText(entry?.color) || null,
+        isDeferred: entry?.isDeferred === true,
+      };
+    })
+    .filter(Boolean)
+    // The SDK sometimes includes free space as a category; the view layer
+    // derives that from the total instead, so drop it here to avoid double
+    // counting it in the bar.
+    .filter((entry) => !isFreeSpaceCategoryName(entry.name));
+
+  const apiUsage = raw.apiUsage && typeof raw.apiUsage === 'object' ? raw.apiUsage : null;
+
+  return {
+    model: normalizeText(raw.model) || null,
+    totalTokens,
+    maxTokens,
+    percentage: toNullablePercent(raw.percentage),
+    // Set by the Cursor worker when occupancy is derived rather than measured
+    // (e.g. 'cursor-per-call-average'); absent from Claude SDK payloads.
+    estimateKind: normalizeText(raw.estimateKind) || null,
+    categories,
+    skills: raw.skills && typeof raw.skills === 'object'
+      ? {
+        totalSkills: toNullableInt(raw.skills.totalSkills),
+        includedSkills: toNullableInt(raw.skills.includedSkills),
+        tokens: toNullableInt(raw.skills.tokens),
+      }
+      : null,
+    // NOT the model's own limit: probed on claude-opus-5[1m], it follows the
+    // ACTIVE auto-compact window (no setting → 1000000, setting 100000 →
+    // 100000). Recorded because the SDK reports it, and used as the fallback
+    // for a missing maxTokens above — never to say what a model can hold. The
+    // modal annotated slider stops from it until 2026-08-21 and so told users
+    // who had just narrowed the window that widening it again was pointless.
+    rawMaxTokens: toNullableInt(raw.rawMaxTokens),
+    // A TOKEN COUNT, not a percent: the CLI compacts once the conversation
+    // crosses it (measured: 967000 on a 1M-window model). It was run through a
+    // percent normalizer here until 2026-08-20, which is why the derived
+    // buffer below was always 0.
+    autoCompactThreshold: toNullableInt(raw.autoCompactThreshold),
+    // Where that threshold came from: 'auto' | 'model-default' | 'settings' |
+    // 'env' | 'clientdata' (the CLI's own vocabulary). The modal renders it so
+    // a user can tell a default from their own setting.
+    autocompactSource: normalizeText(raw.autocompactSource) || null,
+    isAutoCompactEnabled: raw.isAutoCompactEnabled === true,
+    apiUsage: apiUsage
+      ? {
+        inputTokens: toNullableInt(apiUsage.input_tokens),
+        outputTokens: toNullableInt(apiUsage.output_tokens),
+        cacheReadTokens: toNullableInt(apiUsage.cache_read_input_tokens),
+        cacheWriteTokens: toNullableInt(apiUsage.cache_creation_input_tokens),
+      }
+      : null,
+  };
+}
+
+/**
+ * `modelUsage` is keyed by the raw model string. Prefer the requested model,
+ * fall back to the only entry when there is exactly one (the common case), so a
+ * model-id spelling mismatch doesn't lose the context window.
+ */
+export function resolveModelUsageEntry(modelUsage, model) {
+  if (!modelUsage || typeof modelUsage !== 'object') return null;
+  const wanted = normalizeText(model).toLowerCase();
+  const entries = Object.entries(modelUsage).filter(([, value]) => value && typeof value === 'object');
+  if (!entries.length) return null;
+  if (wanted) {
+    const match = entries.find(([key]) => normalizeText(key).toLowerCase() === wanted);
+    if (match) return match[1];
+  }
+  return entries.length === 1 ? entries[0][1] : null;
+}
+
+function sumCategories(categories, names) {
+  let total = null;
+  for (const entry of categories) {
+    if (!names.has(entry.name.toLowerCase())) continue;
+    total = (total || 0) + entry.tokens;
+  }
+  return total;
+}
+
+/**
+ * Build a snapshot in the same shape `context-snapshot-service` produces for
+ * Copilot, so the indicator line and the existing text renderer work unchanged.
+ */
+export function buildClaudeContextSnapshot({
+  contextUsage,
+  modelUsage = null,
+  model = '',
+  runtimeSessionId = null,
+  sdkSessionId = null,
+  capturedAt = null,
+} = {}) {
+  const usage = normalizeClaudeContextUsage(contextUsage);
+  const modelUsageEntry = resolveModelUsageEntry(modelUsage, model || usage?.model);
+  const contextWindow = toNullableInt(modelUsageEntry?.contextWindow);
+
+  const maxContextTokens = usage?.maxTokens ?? contextWindow;
+  const usedTotalTokens = usage?.totalTokens ?? null;
+  if (usedTotalTokens === null && maxContextTokens === null) return null;
+
+  const usedPercent = usage?.percentage
+    ?? ((usedTotalTokens !== null && maxContextTokens !== null && maxContextTokens > 0)
+      ? Math.round((usedTotalTokens / maxContextTokens) * 10000) / 100
+      : null);
+  const freeTokens = (usedTotalTokens !== null && maxContextTokens !== null)
+    ? Math.max(0, maxContextTokens - usedTotalTokens)
+    : null;
+
+  const categories = usage?.categories || [];
+  const systemTokens = sumCategories(categories, SYSTEM_CATEGORY_NAMES);
+  const toolsTokens = sumCategories(categories, TOOLS_CATEGORY_NAMES);
+  const messagesTokens = sumCategories(categories, MESSAGES_CATEGORY_NAMES);
+  const systemToolsTokens = (systemTokens !== null || toolsTokens !== null)
+    ? Number(systemTokens || 0) + Number(toolsTokens || 0)
+    : null;
+
+  return {
+    runtime_session_id: runtimeSessionId || null,
+    copilot_session_id: sdkSessionId || null,
+    model: usage?.model || normalizeText(model) || null,
+    used_total_tokens: usedTotalTokens,
+    max_context_tokens: maxContextTokens,
+    used_percent: usedPercent,
+    free_tokens: freeTokens,
+    // Derived from `max - used`, so it still spans the buffer below; the view
+    // layer splits the two before rendering them side by side.
+    free_tokens_includes_buffer: freeTokens !== null,
+    // Everything above the auto-compact threshold is context Claude will never
+    // let the conversation occupy, so it is the closest analogue to Copilot's
+    // buffer. Both values are token counts.
+    buffer_tokens: (usage?.isAutoCompactEnabled && usage?.autoCompactThreshold != null
+      && maxContextTokens !== null)
+      ? Math.max(0, maxContextTokens - usage.autoCompactThreshold)
+      : null,
+    system_tokens: systemTokens,
+    messages_tokens: messagesTokens,
+    tools_tokens: toolsTokens,
+    system_tools_tokens: systemToolsTokens,
+    used_prompt_tokens: usage?.apiUsage?.inputTokens ?? null,
+    used_completion_tokens: usage?.apiUsage?.outputTokens ?? null,
+    reasoning_tokens: null,
+    cache_read_tokens: usage?.apiUsage?.cacheReadTokens ?? null,
+    cache_write_tokens: usage?.apiUsage?.cacheWriteTokens ?? null,
+    captured_at: normalizeText(capturedAt) || null,
+    estimate_kind: usage?.estimateKind ?? null,
+  };
+}
+
+/**
+ * Parse the JSON blob persisted on `runtime_sessions` and rebuild both the
+ * snapshot and the normalized usage the view layer renders.
+ */
+export function readStoredClaudeContextUsage(row) {
+  const rawJson = normalizeText(row?.context_usage_json);
+  if (!rawJson) return { snapshot: null, contextUsage: null };
+
+  let parsed = null;
+  try {
+    parsed = JSON.parse(rawJson);
+  } catch {
+    return { snapshot: null, contextUsage: null };
+  }
+
+  const capturedAt = normalizeText(row?.context_usage_captured_at) || null;
+  const snapshot = buildClaudeContextSnapshot({
+    contextUsage: parsed?.contextUsage,
+    modelUsage: parsed?.modelUsage,
+    model: parsed?.model || row?.provider_model || row?.model || '',
+    runtimeSessionId: row?.id || null,
+    sdkSessionId: row?.sdk_session_id || null,
+    capturedAt,
+  });
+  return {
+    snapshot,
+    contextUsage: normalizeClaudeContextUsage(parsed?.contextUsage),
+  };
+}

package/server/services/claude-session-root-service.mjs

@@ -0,0 +1,228 @@
+'use strict';
+
+import nodeFs from 'fs';
+import nodePath from 'path';
+import os from 'os';
+
+// Resolve the on-disk folder the Claude Agent SDK keeps for one session, so the
+// file explorer's Session root works on `claude`-provider conversations.
+//
+// The Copilot CLI creates `~/.copilot/session-state/<sdkSessionId>/` as a side
+// effect of running; the Claude worker never touches that path, which is why the
+// Session button was permanently disabled for Claude conversations. The SDK's
+// own equivalent is:
+//
+//   <configRoot>/projects/<slug(cwd)>/<nativeSessionId>/
+//
+// with the sibling `<nativeSessionId>.jsonl` transcript one level up. Only the
+// per-session directory is exposed — the project directory holds every session
+// for that workspace plus `memory/`, so pointing the browser at it would leak
+// unrelated conversations into a "Session" view.
+//
+// The transcript, not the directory, is what anchors a session here. The SDK
+// writes the `.jsonl` from the first turn but creates the directory lazily, only
+// once the session produces `subagents/` or `tool-results/` files — so requiring
+// the directory left the Session button dark for every conversation that had not
+// yet spawned a subagent. `sessionRootPath` is therefore returned for a
+// transcript-only session too, with `sessionRootExists: false` so the caller can
+// serve it as an empty folder rather than a 404.
+
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const PROJECT_SLUG_MAX_LENGTH = 200;
+const DEFAULT_MISS_TTL_MS = 5_000;
+const DEFAULT_MAX_PROJECT_DIRS_SCANNED = 500;
+const DEFAULT_MAX_CACHE_ENTRIES = 256;
+
+function normalizeText(value) {
+  const text = String(value || '').trim();
+  return text || '';
+}
+
+function slugHashSuffix(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * Mirrors the directory-name sanitizer the Agent SDK applies to a session's cwd.
+ * Reimplemented rather than imported: `claude-sdk-adapter.mjs` is deliberately
+ * the only module in this repo that pulls in `@anthropic-ai/claude-agent-sdk`,
+ * and the relay server must not load it.
+ */
+export function claudeProjectDirSlug(cwd) {
+  const value = String(cwd || '');
+  const sanitized = value.replace(/[^a-zA-Z0-9]/g, '-');
+  if (sanitized.length <= PROJECT_SLUG_MAX_LENGTH) return sanitized;
+  return `${sanitized.slice(0, PROJECT_SLUG_MAX_LENGTH)}-${slugHashSuffix(value)}`;
+}
+
+/**
+ * Candidate `<configRoot>/projects` directories, most specific first.
+ *
+ * Both `$CLAUDE_CONFIG_DIR` and `~/.claude` are probed because a session may
+ * predate the override: the tmux launch path now forwards CLAUDE_CONFIG_DIR in
+ * its env allowlist (matching the detached spawn path, which inherits the full
+ * environment), but transcripts written before that fix still live under
+ * `~/.claude`.
+ */
+export function resolveClaudeProjectsRoots({ env = process.env, homedir = os.homedir, path = nodePath } = {}) {
+  const roots = [];
+  const configDirOverride = normalizeText(env?.CLAUDE_CONFIG_DIR);
+  if (configDirOverride) roots.push(path.join(configDirOverride, 'projects'));
+  let home = '';
+  try {
+    home = normalizeText(typeof homedir === 'function' ? homedir() : homedir);
+  } catch {
+    home = '';
+  }
+  if (!home) home = normalizeText(env?.HOME) || normalizeText(env?.USERPROFILE);
+  if (home) roots.push(path.join(home, '.claude', 'projects'));
+  return [...new Set(roots.map((root) => root.normalize('NFC')))];
+}
+
+export function createClaudeSessionRootResolver({
+  fs = nodeFs,
+  path = nodePath,
+  env = process.env,
+  homedir = os.homedir,
+  now = () => Date.now(),
+  missTtlMs = DEFAULT_MISS_TTL_MS,
+  maxProjectDirsScanned = DEFAULT_MAX_PROJECT_DIRS_SCANNED,
+  maxCacheEntries = DEFAULT_MAX_CACHE_ENTRIES,
+} = {}) {
+  // nativeSessionId -> the project directory that contains it.
+  const projectDirCache = new Map();
+  // nativeSessionId -> timestamp after which it is worth scanning again.
+  const missCache = new Map();
+
+  function isDirectory(candidate) {
+    try {
+      return fs.statSync(candidate).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  function isFile(candidate) {
+    try {
+      return fs.statSync(candidate).isFile();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * The session's on-disk footprint inside one project directory, or null when
+   * the session does not live there at all.
+   *
+   * @returns {{ sessionRootPath: string, transcriptPath: string, sessionRootExists: boolean } | null}
+   */
+  function sessionAnchorsIn(projectDir, nativeSessionId) {
+    const sessionRootPath = path.join(projectDir, nativeSessionId);
+    const transcriptPath = path.join(projectDir, `${nativeSessionId}.jsonl`);
+    const sessionRootExists = isDirectory(sessionRootPath);
+    const transcriptExists = isFile(transcriptPath);
+    if (!sessionRootExists && !transcriptExists) return null;
+    return {
+      sessionRootPath,
+      transcriptPath: transcriptExists ? transcriptPath : '',
+      sessionRootExists,
+    };
+  }
+
+  function findProjectDir(nativeSessionId, workspaceRootPath) {
+    const roots = resolveClaudeProjectsRoots({ env, homedir, path });
+    const workspaceRoot = normalizeText(workspaceRootPath);
+
+    // Fast path: derive the project dir straight from the session's workspace.
+    if (workspaceRoot) {
+      const slug = claudeProjectDirSlug(workspaceRoot);
+      for (const root of roots) {
+        const projectDir = path.join(root, slug);
+        if (sessionAnchorsIn(projectDir, nativeSessionId)) return projectDir;
+      }
+    }
+
+    // Fallback: the slug can miss (symlinked or since-changed workspace root, a
+    // git worktree, an SDK sanitizer change), so scan the project dirs. Bounded
+    // and never recursive — one readdir per root plus two stats per project.
+    for (const root of roots) {
+      let entries = [];
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      let scanned = 0;
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (scanned >= maxProjectDirsScanned) break;
+        scanned += 1;
+        const projectDir = path.join(root, entry.name);
+        if (sessionAnchorsIn(projectDir, nativeSessionId)) return projectDir;
+      }
+    }
+    return '';
+  }
+
+  function rememberProjectDir(nativeSessionId, projectDir) {
+    if (projectDirCache.size >= maxCacheEntries) projectDirCache.clear();
+    projectDirCache.set(nativeSessionId, projectDir);
+  }
+
+  /**
+   * @returns {{
+   *   sessionRootPath: string,
+   *   sessionRootName: string,
+   *   projectDirPath: string,
+   *   transcriptPath: string,
+   *   sessionRootExists: boolean,
+   * } | null}
+   */
+  function resolveClaudeSessionRoot({ claudeNativeSessionId = '', workspaceRootPath = '' } = {}) {
+    const nativeSessionId = normalizeText(claudeNativeSessionId);
+    // The id is joined into a filesystem path, so it is validated before any
+    // syscall rather than trusted the way the Copilot branch trusts its own.
+    if (!SESSION_ID_PATTERN.test(nativeSessionId)) return null;
+
+    const cachedProjectDir = projectDirCache.get(nativeSessionId);
+    if (cachedProjectDir) {
+      // Re-probed rather than assumed: the directory appears partway through a
+      // session's life, so a cache hit must still report the current state.
+      const anchors = sessionAnchorsIn(cachedProjectDir, nativeSessionId);
+      if (anchors) {
+        return { ...anchors, sessionRootName: 'Session', projectDirPath: cachedProjectDir };
+      }
+      projectDirCache.delete(nativeSessionId);
+    }
+
+    // The client re-polls conversation detail roughly every second while a turn
+    // runs, so a miss must not mean a directory scan every time.
+    const missUntil = missCache.get(nativeSessionId);
+    if (missUntil !== undefined && missUntil > now()) return null;
+
+    const projectDir = findProjectDir(nativeSessionId, workspaceRootPath);
+    if (!projectDir) {
+      if (missCache.size >= maxCacheEntries) missCache.clear();
+      missCache.set(nativeSessionId, now() + missTtlMs);
+      return null;
+    }
+    // Re-read rather than reuse what the scan matched on: the session can be
+    // deleted between the two, and a partial result would be worse than a miss.
+    const anchors = sessionAnchorsIn(projectDir, nativeSessionId);
+    if (!anchors) return null;
+    missCache.delete(nativeSessionId);
+    rememberProjectDir(nativeSessionId, projectDir);
+    return { ...anchors, sessionRootName: 'Session', projectDirPath: projectDir };
+  }
+
+  function clearCache() {
+    projectDirCache.clear();
+    missCache.clear();
+  }
+
+  return { resolveClaudeSessionRoot, clearCache };
+}