@cloudcli-ai/cloudcli 1.36.3 → 1.37.0

package/server/modules/providers/services/provider-token-usage.service.ts

@@ -0,0 +1,357 @@
+import fsSync, { type Dirent } from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import Database from 'better-sqlite3';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import type { AnyRecord } from '@/shared/types.js';
+import { AppError, getOpenCodeDatabasePath } from '@/shared/utils.js';
+
+type SessionRow = NonNullable<ReturnType<typeof sessionsDb.getSessionById>>;
+
+type ProviderTokenUsageServiceDependencies = {
+  getSessionById: (sessionId: string) => SessionRow | null | undefined;
+  getHomeDirectory: () => string;
+  getOpenCodeDatabasePath: () => string;
+  fileExists: (filePath: string) => boolean;
+  readDirectory: (directoryPath: string) => Promise<Dirent[]>;
+  readTextFile: (filePath: string) => Promise<string>;
+  getClaudeContextWindow: () => string | undefined;
+};
+
+type TokenUsageResult = {
+  used: number;
+  total?: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
+  cacheTokens?: number;
+  breakdown: {
+    input: number;
+    output: number;
+  };
+  unsupported?: boolean;
+  message?: string;
+};
+
+type OpenCodeTokenRow = {
+  inputTokens: number | null;
+  outputTokens: number | null;
+  reasoningTokens: number | null;
+  cacheReadTokens: number | null;
+  cacheWriteTokens: number | null;
+};
+
+const defaultDependencies: ProviderTokenUsageServiceDependencies = {
+  getSessionById: (sessionId) => sessionsDb.getSessionById(sessionId),
+  getHomeDirectory: () => os.homedir(),
+  getOpenCodeDatabasePath,
+  fileExists: (filePath) => fsSync.existsSync(filePath),
+  readDirectory: (directoryPath) => fsp.readdir(directoryPath, { withFileTypes: true }),
+  readTextFile: (filePath) => fsp.readFile(filePath, 'utf8'),
+  getClaudeContextWindow: () => process.env.CONTEXT_WINDOW,
+};
+
+function readUsageNumber(value: unknown): number {
+  const parsedValue = Number(value);
+  return Number.isFinite(parsedValue) ? parsedValue : 0;
+}
+
+async function findCodexSessionFile(
+  directoryPath: string,
+  providerSessionId: string,
+  dependencies: ProviderTokenUsageServiceDependencies,
+): Promise<string | null> {
+  let entries: Dirent[];
+  try {
+    entries = await dependencies.readDirectory(directoryPath);
+  } catch {
+    // Codex session folders are date-partitioned and can disappear while a
+    // cleanup is running. An unreadable branch is simply not a match.
+    return null;
+  }
+
+  for (const entry of entries) {
+    const entryPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      const nestedMatch = await findCodexSessionFile(entryPath, providerSessionId, dependencies);
+      if (nestedMatch) {
+        return nestedMatch;
+      }
+      continue;
+    }
+
+    if (entry.name.includes(providerSessionId) && entry.name.endsWith('.jsonl')) {
+      return entryPath;
+    }
+  }
+
+  return null;
+}
+
+function readCodexTokenUsage(fileContent: string): TokenUsageResult {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let totalTokens = 0;
+  let contextWindow = 200_000;
+  const lines = fileContent.trim().split('\n');
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    try {
+      const entry = JSON.parse(lines[index]) as AnyRecord;
+      const tokenInfo = entry.type === 'event_msg' && entry.payload?.type === 'token_count'
+        ? entry.payload.info
+        : null;
+      if (!tokenInfo) {
+        continue;
+      }
+
+      if (tokenInfo.total_token_usage) {
+        inputTokens = readUsageNumber(tokenInfo.total_token_usage.input_tokens);
+        outputTokens = readUsageNumber(tokenInfo.total_token_usage.output_tokens);
+        totalTokens = readUsageNumber(tokenInfo.total_token_usage.total_tokens)
+          || inputTokens + outputTokens;
+      }
+      contextWindow = readUsageNumber(tokenInfo.model_context_window) || contextWindow;
+      break;
+    } catch {
+      // A provider may be writing the last JSONL line while this read happens.
+    }
+  }
+
+  return {
+    used: totalTokens,
+    total: contextWindow,
+    inputTokens,
+    outputTokens,
+    breakdown: { input: inputTokens, output: outputTokens },
+  };
+}
+
+function readClaudeTokenUsage(fileContent: string, configuredContextWindow: string | undefined): TokenUsageResult {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheCreationTokens = 0;
+  const lines = fileContent.trim().split('\n');
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    try {
+      const entry = JSON.parse(lines[index]) as AnyRecord;
+      const usage = entry.type === 'assistant' ? entry.message?.usage : null;
+      if (!usage) {
+        continue;
+      }
+
+      const directInputTokens = readUsageNumber(usage.input_tokens ?? usage.inputTokens);
+      cacheReadTokens = readUsageNumber(
+        usage.cache_read_input_tokens ?? usage.cacheReadInputTokens ?? usage.cacheReadTokens,
+      );
+      cacheCreationTokens = readUsageNumber(
+        usage.cache_creation_input_tokens
+          ?? usage.cacheCreationInputTokens
+          ?? usage.cacheCreationTokens,
+      );
+      inputTokens = directInputTokens + cacheReadTokens + cacheCreationTokens;
+      outputTokens = readUsageNumber(usage.output_tokens ?? usage.outputTokens);
+      break;
+    } catch {
+      // Skip malformed lines without discarding usage from earlier messages.
+    }
+  }
+
+  const parsedContextWindow = Number.parseInt(configuredContextWindow ?? '', 10);
+  const contextWindow = Number.isFinite(parsedContextWindow) ? parsedContextWindow : 160_000;
+  const cacheTokens = cacheReadTokens + cacheCreationTokens;
+
+  return {
+    used: inputTokens + outputTokens,
+    total: contextWindow,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheCreationTokens,
+    cacheTokens,
+    breakdown: { input: inputTokens, output: outputTokens },
+  };
+}
+
+function readOpenCodeTokenUsage(databasePath: string, providerSessionId: string): TokenUsageResult {
+  const database = new Database(databasePath, { readonly: true, fileMustExist: true });
+  try {
+    const columns = database.prepare('PRAGMA table_info(session)').all() as Array<{ name: string }>;
+    const columnNames = new Set(columns.map((column) => column.name));
+    const requiredColumns = [
+      'tokens_input',
+      'tokens_output',
+      'tokens_reasoning',
+      'tokens_cache_read',
+      'tokens_cache_write',
+    ];
+
+    if (!requiredColumns.every((column) => columnNames.has(column))) {
+      return {
+        used: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        breakdown: { input: 0, output: 0 },
+        unsupported: true,
+        message: 'Token usage tracking is not available in this OpenCode database schema',
+      };
+    }
+
+    const row = database.prepare(`
+      SELECT
+        tokens_input AS inputTokens,
+        tokens_output AS outputTokens,
+        tokens_reasoning AS reasoningTokens,
+        tokens_cache_read AS cacheReadTokens,
+        tokens_cache_write AS cacheWriteTokens
+      FROM session
+      WHERE id = ?
+    `).get(providerSessionId) as OpenCodeTokenRow | undefined;
+
+    if (!row) {
+      throw new AppError('OpenCode session was not found.', {
+        code: 'OPENCODE_SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    const inputTokens = readUsageNumber(row.inputTokens) + readUsageNumber(row.cacheReadTokens);
+    const outputTokens = readUsageNumber(row.outputTokens);
+    const used = readUsageNumber(row.inputTokens)
+      + outputTokens
+      + readUsageNumber(row.reasoningTokens)
+      + readUsageNumber(row.cacheReadTokens)
+      + readUsageNumber(row.cacheWriteTokens);
+
+    return {
+      used,
+      inputTokens,
+      outputTokens,
+      breakdown: { input: inputTokens, output: outputTokens },
+    };
+  } finally {
+    database.close();
+  }
+}
+
+/**
+ * Creates the provider token-usage service used by the provider routes. The
+ * provider test suite supplies isolated filesystem and session dependencies so
+ * every calculator can be exercised without touching a developer's real data.
+ */
+export function createProviderTokenUsageService(
+  dependencyOverrides: Partial<ProviderTokenUsageServiceDependencies> = {},
+) {
+  const dependencies = { ...defaultDependencies, ...dependencyOverrides };
+
+  return {
+    /**
+     * Resolves all provider-specific storage details from one app-facing
+     * session id, then returns the latest usage snapshot for that provider.
+     */
+    async getSessionTokenUsage(sessionId: string): Promise<TokenUsageResult> {
+      const session = dependencies.getSessionById(sessionId);
+      if (!session) {
+        throw new AppError(`Session "${sessionId}" was not found.`, {
+          code: 'SESSION_NOT_FOUND',
+          statusCode: 404,
+        });
+      }
+
+      const providerSessionId = session.provider_session_id || sessionId;
+
+      if (session.provider === 'cursor') {
+        return {
+          used: 0,
+          total: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          breakdown: { input: 0, output: 0 },
+          unsupported: true,
+          message: 'Token usage tracking not available for Cursor sessions',
+        };
+      }
+
+      if (session.provider === 'opencode') {
+        const databasePath = dependencies.getOpenCodeDatabasePath();
+        if (!dependencies.fileExists(databasePath)) {
+          throw new AppError('OpenCode database was not found.', {
+            code: 'OPENCODE_DATABASE_NOT_FOUND',
+            statusCode: 404,
+          });
+        }
+
+        return readOpenCodeTokenUsage(databasePath, providerSessionId);
+      }
+
+      if (session.provider === 'codex') {
+        const indexedFilePath = session.jsonl_path && dependencies.fileExists(session.jsonl_path)
+          ? session.jsonl_path
+          : null;
+        const sessionFilePath = indexedFilePath ?? await findCodexSessionFile(
+          path.join(dependencies.getHomeDirectory(), '.codex', 'sessions'),
+          providerSessionId,
+          dependencies,
+        );
+
+        if (!sessionFilePath) {
+          throw new AppError(`Codex session file for "${sessionId}" was not found.`, {
+            code: 'CODEX_SESSION_FILE_NOT_FOUND',
+            statusCode: 404,
+          });
+        }
+
+        const fileContent = await dependencies.readTextFile(sessionFilePath);
+        return readCodexTokenUsage(fileContent);
+      }
+
+      let sessionFilePath = session.jsonl_path;
+      if (!sessionFilePath) {
+        if (!session.project_path) {
+          throw new AppError(`Session file for "${sessionId}" was not found.`, {
+            code: 'SESSION_FILE_NOT_FOUND',
+            statusCode: 404,
+          });
+        }
+
+        const encodedProjectPath = session.project_path.replace(/[^a-zA-Z0-9-]/g, '-');
+        const projectDirectory = path.join(
+          dependencies.getHomeDirectory(),
+          '.claude',
+          'projects',
+          encodedProjectPath,
+        );
+        sessionFilePath = path.join(projectDirectory, `${providerSessionId}.jsonl`);
+
+        const relativePath = path.relative(path.resolve(projectDirectory), path.resolve(sessionFilePath));
+        if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+          throw new AppError('Resolved session path is invalid.', {
+            code: 'INVALID_SESSION_PATH',
+            statusCode: 400,
+          });
+        }
+      }
+
+      if (!dependencies.fileExists(sessionFilePath)) {
+        throw new AppError(`Session file for "${sessionId}" was not found.`, {
+          code: 'SESSION_FILE_NOT_FOUND',
+          statusCode: 404,
+        });
+      }
+
+      const fileContent = await dependencies.readTextFile(sessionFilePath);
+      return readClaudeTokenUsage(fileContent, dependencies.getClaudeContextWindow());
+    },
+  };
+}
+
+/**
+ * Used by the provider routes to serve token usage from only an app session id.
+ */
+export const providerTokenUsageService = createProviderTokenUsageService();

package/server/modules/providers/services/sessions-watcher.service.ts

@@ -36,6 +36,8 @@ const WATCHER_IGNORED_PATTERNS = [
   '**/.git/**',
   '**/dist/**',
   '**/build/**',
+  '**/subagents/**',
+  '**/tool-results/**',
   '**/*.tmp',
   '**/*.swp',
   '**/.DS_Store',

package/server/modules/providers/services/sessions.service.ts

@@ -32,6 +32,25 @@ type ArchivedSessionListItem = {
   isProjectArchived: boolean;
 };
 
+type SessionDetails = {
+  /** Canonical app-facing session id (may differ from the looked-up id when a provider-native id was given). */
+  sessionId: string;
+  provider: LLMProvider;
+  summary: string;
+  createdAt: string | null;
+  updatedAt: string | null;
+  lastActivity: string | null;
+  isArchived: boolean;
+  project: {
+    projectId: string;
+    path: string;
+    fullPath: string;
+    displayName: string;
+    isStarred: boolean;
+    isArchived: boolean;
+  } | null;
+};
+
 /**
  * Removes one file if it exists.
  */
@@ -100,6 +119,23 @@ export const sessionsService = {
     return chatRunRegistry.listRunningRuns();
   },
 
+  /**
+   * Resolves the provider-native session id a runtime needs for resume.
+   *
+   * Callers hand provider runtimes the stable app session id; the provider
+   * CLIs/SDKs only understand their own native id, which lives on the session
+   * row. Ids without a row are assumed to be provider-native already (direct
+   * API callers that reference sessions the watcher has not indexed yet).
+   */
+  resolveProviderSessionId(sessionId: string | null | undefined): string | null {
+    if (!sessionId) {
+      return null;
+    }
+
+    const session = sessionsDb.getSessionById(sessionId);
+    return session ? session.provider_session_id : sessionId;
+  },
+
   /**
    * Normalizes one provider-native event into frontend session message events.
    */
@@ -189,6 +225,49 @@ export const sessionsService = {
     };
   },
 
+  /**
+   * Resolves one session (by app id, falling back to the provider-native id)
+   * to its metadata plus the owning project.
+   *
+   * This backs deep links like `/session/:sessionId`: the frontend's paginated
+   * project payloads only carry each project's first session page, so a
+   * session opened directly by URL may not be present client-side at all —
+   * this lookup is the authoritative way to learn which project owns it.
+   */
+  getSessionDetailsById(sessionId: string): SessionDetails {
+    const session =
+      sessionsDb.getSessionById(sessionId) ?? sessionsDb.getSessionByProviderSessionId(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    const projectPath = session.project_path?.trim() ? session.project_path : null;
+    const project = projectPath ? projectsDb.getProjectPath(projectPath) : null;
+
+    return {
+      sessionId: session.session_id,
+      provider: session.provider as LLMProvider,
+      summary: session.custom_name?.trim() || '',
+      createdAt: session.created_at ?? null,
+      updatedAt: session.updated_at ?? null,
+      lastActivity: session.updated_at ?? session.created_at ?? null,
+      isArchived: Boolean(session.isArchived),
+      project: project && projectPath
+        ? {
+            projectId: project.project_id,
+            path: projectPath,
+            fullPath: projectPath,
+            displayName: resolveProjectDisplayName(projectPath, project.custom_project_name),
+            isStarred: Boolean(project.isStarred),
+            isArchived: Boolean(project.isArchived),
+          }
+        : null,
+    };
+  },
+
   /**
    * Returns archived sessions with enough project metadata for the sidebar to
    * group, filter, open, and restore them without a per-row follow-up query.

package/server/modules/providers/shared/base/abstract.provider.ts

@@ -3,6 +3,7 @@ import type {
   IProviderAuth,
   IProviderMcp,
   IProviderModels,
+  IProviderRuntime,
   IProviderSessionSynchronizer,
   IProviderSkills,
   IProviderSessions,
@@ -12,12 +13,12 @@ import type { LLMProvider } from '@/shared/types.js';
 /**
  * Shared provider base.
  *
- * Concrete providers must expose auth/MCP handlers and implement message
- * normalization/history loading because those behaviors depend on native
- * SDK/CLI formats.
+ * Concrete providers expose their live runtime plus model, auth, MCP, skill,
+ * session, and synchronization facets behind one registry-owned object.
  */
 export abstract class AbstractProvider implements IProvider {
   readonly id: LLMProvider;
+  abstract readonly runtime: IProviderRuntime;
   abstract readonly models: IProviderModels;
   abstract readonly mcp: IProviderMcp;
   abstract readonly auth: IProviderAuth;

package/server/modules/providers/tests/claude-auth.test.ts

@@ -0,0 +1,150 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { ClaudeProviderAuth } from '@/modules/providers/list/claude/claude-auth.provider.js';
+
+// checkCredentials() is private, but unlike getStatus() it never shells out to the
+// `claude` CLI — it only reads env vars and ~/.claude files. Calling it directly
+// (TypeScript's `private` has no runtime effect) tests the priority order without
+// depending on `claude` being installed in the test environment.
+type CheckCredentialsResult = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+const checkCredentials = (auth: ClaudeProviderAuth): Promise<CheckCredentialsResult> =>
+  (auth as unknown as { checkCredentials: () => Promise<CheckCredentialsResult> }).checkCredentials();
+
+const ENV_KEYS = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN'] as const;
+
+const withEnv = async (
+  overrides: Partial<Record<(typeof ENV_KEYS)[number], string>>,
+  fn: () => Promise<void>,
+) => {
+  const original: Partial<Record<(typeof ENV_KEYS)[number], string>> = {};
+  for (const key of ENV_KEYS) {
+    original[key] = process.env[key];
+    const value = overrides[key];
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+  try {
+    await fn();
+  } finally {
+    for (const key of ENV_KEYS) {
+      if (original[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = original[key];
+      }
+    }
+  }
+};
+
+const withTempHome = async (fn: (homeDir: string) => Promise<void>) => {
+  const homeDir = await mkdtemp(path.join(os.tmpdir(), 'claude-auth-test-'));
+  const originalHome = process.env.HOME;
+  process.env.HOME = homeDir;
+  try {
+    await fn(homeDir);
+  } finally {
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+    await rm(homeDir, { recursive: true, force: true });
+  }
+};
+
+const writeCredentialsFile = async (homeDir: string, body: unknown) => {
+  const claudeDir = path.join(homeDir, '.claude');
+  await mkdir(claudeDir, { recursive: true });
+  await writeFile(path.join(claudeDir, '.credentials.json'), JSON.stringify(body));
+};
+
+const writeSettingsFile = async (homeDir: string, env: Record<string, string>) => {
+  const claudeDir = path.join(homeDir, '.claude');
+  await mkdir(claudeDir, { recursive: true });
+  await writeFile(path.join(claudeDir, 'settings.json'), JSON.stringify({ env }));
+};
+
+test('checkCredentials: CLAUDE_CODE_OAUTH_TOKEN set is authenticated via environment, even with a stale credentials file', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'stale-token', expiresAt: 1_000_000_000_000 }, // long expired
+    });
+
+    await withEnv({ CLAUDE_CODE_OAUTH_TOKEN: 'test-oauth-token' }, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'environment');
+    });
+  });
+});
+
+test('checkCredentials: CLAUDE_CODE_OAUTH_TOKEN configured via settings.json env block is authenticated via environment', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeSettingsFile(homeDir, { CLAUDE_CODE_OAUTH_TOKEN: 'test-oauth-token-from-settings' });
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'stale-token', expiresAt: 1_000_000_000_000 }, // long expired
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'environment');
+    });
+  });
+});
+
+test('checkCredentials: no CLAUDE_CODE_OAUTH_TOKEN, valid credentials file falls back to credentials_file', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'valid-token', expiresAt: Date.now() + 60 * 60 * 1000 },
+      email: 'someone@example.com',
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, true);
+      assert.equal(status.method, 'credentials_file');
+      assert.equal(status.email, 'someone@example.com');
+    });
+  });
+});
+
+test('checkCredentials: no CLAUDE_CODE_OAUTH_TOKEN, expired credentials file reports not authenticated', async () => {
+  await withTempHome(async (homeDir) => {
+    await writeCredentialsFile(homeDir, {
+      claudeAiOauth: { accessToken: 'stale-token', expiresAt: 1_000_000_000_000 },
+    });
+
+    await withEnv({}, async () => {
+      const status = await checkCredentials(new ClaudeProviderAuth());
+      assert.equal(status.authenticated, false);
+      assert.match(status.error ?? '', /expired/i);
+    });
+  });
+});
+
+test('checkCredentials: ANTHROPIC_API_KEY takes precedence over CLAUDE_CODE_OAUTH_TOKEN', async () => {
+  await withTempHome(async () => {
+    await withEnv(
+      { ANTHROPIC_API_KEY: 'test-api-key', CLAUDE_CODE_OAUTH_TOKEN: 'test-oauth-token' },
+      async () => {
+        const status = await checkCredentials(new ClaudeProviderAuth());
+        assert.equal(status.authenticated, true);
+        assert.equal(status.method, 'api_key');
+      },
+    );
+  });
+});

package/server/modules/providers/tests/claude-sessions.test.ts

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { ClaudeSessionsProvider } from '@/modules/providers/list/claude/claude-sessions.provider.js';
+
+const SESSION_ID = 'session-1';
+
+const SKILL_BODY = [
+  'Base directory for this skill: /tmp/claude/bundled-skills/2.1.220/abc123/claude-api',
+  '',
+  '# Building LLM-Powered Applications with Claude',
+  '',
+  'This skill helps you build LLM-powered applications with Claude.',
+].join('\n');
+
+test('claude: injected skill bodies are hidden even without the isMeta flag', () => {
+  const provider = new ClaudeSessionsProvider();
+
+  // The live SDK stream omits `isMeta`, so the payload has to be recognised by
+  // its content or it renders as a giant user bubble mid-run.
+  const live = provider.normalizeMessage(
+    {
+      uuid: 'u1',
+      timestamp: '2026-07-28T10:00:00.000Z',
+      message: { role: 'user', content: [{ type: 'text', text: SKILL_BODY }] },
+    },
+    SESSION_ID,
+  );
+  assert.deepEqual(live, []);
+
+  const persisted = provider.normalizeMessage(
+    {
+      uuid: 'u2',
+      timestamp: '2026-07-28T10:00:00.000Z',
+      isMeta: true,
+      message: { role: 'user', content: [{ type: 'text', text: SKILL_BODY }] },
+    },
+    SESSION_ID,
+  );
+  assert.deepEqual(persisted, []);
+});
+
+test('claude: the Skill tool result itself still reaches the UI', () => {
+  const provider = new ClaudeSessionsProvider();
+
+  const messages = provider.normalizeMessage(
+    {
+      uuid: 'u3',
+      timestamp: '2026-07-28T10:00:00.000Z',
+      message: {
+        role: 'user',
+        content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: 'Launching skill: claude-api' }],
+      },
+    },
+    SESSION_ID,
+  );
+
+  assert.equal(messages.length, 1);
+  assert.equal(messages[0].kind, 'tool_result');
+  assert.equal(messages[0].toolId, 'toolu_1');
+});