github-issue-tower-defence-management 1.95.0 → 1.97.0

package/src/adapter/repositories/NodeTmuxSessionRepository.ts

@@ -0,0 +1,53 @@
+import { LocalCommandRunner } from '../../domain/usecases/adapter-interfaces/LocalCommandRunner';
+import { TmuxSessionRepository } from '../../domain/usecases/adapter-interfaces/TmuxSessionRepository';
+
+export class NodeTmuxSessionRepository implements TmuxSessionRepository {
+  constructor(private readonly localCommandRunner: LocalCommandRunner) {}
+
+  listLiveSessionNames = async (): Promise<string[]> => {
+    const { stdout, exitCode } = await this.localCommandRunner.runCommand(
+      'tmux',
+      ['list-sessions', '-F', '#{session_name}'],
+    );
+    if (exitCode !== 0) {
+      return [];
+    }
+    return stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  };
+
+  listInteractiveProcessCommandLines = async (): Promise<string[]> => {
+    const { stdout, exitCode } = await this.localCommandRunner.runCommand(
+      'ps',
+      ['-eo', 'args='],
+    );
+    if (exitCode !== 0) {
+      return [];
+    }
+    return stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  };
+
+  launchDetachedSession = async (
+    sessionName: string,
+    launcherCommand: string,
+    issueUrl: string,
+  ): Promise<void> => {
+    await this.localCommandRunner.runCommand('tmux', [
+      'new-session',
+      '-d',
+      '-s',
+      sessionName,
+      'sh',
+      '-lc',
+      `exec "$1" "$2"`,
+      'sh',
+      launcherCommand,
+      issueUrl,
+    ]);
+  };
+}

package/src/adapter/repositories/ProcClaudeLiveSessionRepository.test.ts

@@ -0,0 +1,146 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ProcClaudeLiveSessionRepository } from './ProcClaudeLiveSessionRepository';
+
+type FakeProcess = {
+  pid: number;
+  cmdline: string;
+  environ: Record<string, string>;
+};
+
+describe('ProcClaudeLiveSessionRepository', () => {
+  let procDirectory: string;
+
+  beforeEach(() => {
+    procDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-proc-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(procDirectory, { recursive: true, force: true });
+  });
+
+  const writeProcess = (fakeProcess: FakeProcess): void => {
+    const processDirectory = path.join(procDirectory, String(fakeProcess.pid));
+    fs.mkdirSync(processDirectory, { recursive: true });
+    fs.writeFileSync(
+      path.join(processDirectory, 'cmdline'),
+      fakeProcess.cmdline,
+    );
+    const environBuffer = Object.entries(fakeProcess.environ)
+      .map(([key, value]) => `${key}=${value}\0`)
+      .join('');
+    fs.writeFileSync(path.join(processDirectory, 'environ'), environBuffer);
+  };
+
+  const writeNonNumericEntry = (name: string): void => {
+    fs.mkdirSync(path.join(procDirectory, name), { recursive: true });
+  };
+
+  it('reads token and session id from a claude process environ', () => {
+    writeProcess({
+      pid: 101,
+      cmdline: '/home/user/.local/share/claude/cli.js\0--print\0',
+      environ: {
+        CLAUDE_CODE_OAUTH_TOKEN: 'token-a',
+        CLAUDE_CODE_SESSION_ID: 'session-a',
+      },
+    });
+
+    const repository = new ProcClaudeLiveSessionRepository(procDirectory);
+
+    expect(repository.listLiveSessions()).toEqual([
+      { token: 'token-a', sessionId: 'session-a' },
+    ]);
+  });
+
+  it('identifies a claude process by the claude executable name', () => {
+    writeProcess({
+      pid: 102,
+      cmdline: '/usr/local/bin/claude\0',
+      environ: {
+        CLAUDE_CODE_OAUTH_TOKEN: 'token-b',
+        CLAUDE_CODE_SESSION_ID: 'session-b',
+      },
+    });
+
+    const repository = new ProcClaudeLiveSessionRepository(procDirectory);
+
+    expect(repository.listLiveSessions()).toEqual([
+      { token: 'token-b', sessionId: 'session-b' },
+    ]);
+  });
+
+  it('ignores a process without an oauth token (for example an api-key session)', () => {
+    writeProcess({
+      pid: 103,
+      cmdline: '/usr/local/bin/claude\0',
+      environ: {
+        CLAUDE_CODE_SESSION_ID: 'session-c',
+        ANTHROPIC_API_KEY: 'api-key',
+      },
+    });
+
+    const repository = new ProcClaudeLiveSessionRepository(procDirectory);
+
+    expect(repository.listLiveSessions()).toEqual([]);
+  });
+
+  it('ignores a non-claude process that happens to carry the token', () => {
+    writeProcess({
+      pid: 104,
+      cmdline: '/usr/bin/bash\0',
+      environ: {
+        CLAUDE_CODE_OAUTH_TOKEN: 'token-d',
+        CLAUDE_CODE_SESSION_ID: 'session-d',
+      },
+    });
+
+    const repository = new ProcClaudeLiveSessionRepository(procDirectory);
+
+    expect(repository.listLiveSessions()).toEqual([]);
+  });
+
+  it('returns one entry per child process so the use case can dedupe by session id', () => {
+    writeProcess({
+      pid: 105,
+      cmdline: '/home/user/.local/share/claude/cli.js\0',
+      environ: {
+        CLAUDE_CODE_OAUTH_TOKEN: 'token-e',
+        CLAUDE_CODE_SESSION_ID: 'session-e',
+      },
+    });
+    writeProcess({
+      pid: 106,
+      cmdline: '/home/user/.local/share/claude/cli.js\0',
+      environ: {
+        CLAUDE_CODE_OAUTH_TOKEN: 'token-e',
+        CLAUDE_CODE_SESSION_ID: 'session-e',
+      },
+    });
+
+    const repository = new ProcClaudeLiveSessionRepository(procDirectory);
+
+    expect(repository.listLiveSessions()).toEqual([
+      { token: 'token-e', sessionId: 'session-e' },
+      { token: 'token-e', sessionId: 'session-e' },
+    ]);
+  });
+
+  it('skips non-numeric proc entries and unreadable processes', () => {
+    writeNonNumericEntry('cpuinfo');
+    fs.mkdirSync(path.join(procDirectory, '107'), { recursive: true });
+
+    const repository = new ProcClaudeLiveSessionRepository(procDirectory);
+
+    expect(repository.listLiveSessions()).toEqual([]);
+  });
+
+  it('returns an empty list when the proc directory does not exist', () => {
+    const repository = new ProcClaudeLiveSessionRepository(
+      path.join(procDirectory, 'missing'),
+    );
+
+    expect(repository.listLiveSessions()).toEqual([]);
+  });
+});

package/src/adapter/repositories/ProcClaudeLiveSessionRepository.ts

@@ -0,0 +1,119 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  ClaudeLiveSession,
+  ClaudeLiveSessionRepository,
+} from '../../domain/usecases/adapter-interfaces/ClaudeLiveSessionRepository';
+
+const DEFAULT_PROC_DIRECTORY = '/proc';
+const OAUTH_TOKEN_ENVIRON_KEY = 'CLAUDE_CODE_OAUTH_TOKEN';
+const SESSION_ID_ENVIRON_KEY = 'CLAUDE_CODE_SESSION_ID';
+
+const isClaudeProcessCommand = (command: string): boolean => {
+  if (command.length === 0) {
+    return false;
+  }
+  if (command.includes('.local/share/claude')) {
+    return true;
+  }
+  const executableName = path.basename(command.split('\0')[0] ?? '');
+  return executableName === 'claude';
+};
+
+export class ProcClaudeLiveSessionRepository implements ClaudeLiveSessionRepository {
+  constructor(
+    private readonly procDirectory: string = DEFAULT_PROC_DIRECTORY,
+  ) {}
+
+  listLiveSessions = (): ClaudeLiveSession[] => {
+    const liveSessions: ClaudeLiveSession[] = [];
+    for (const pidDirectory of this.listProcessIdDirectories()) {
+      const liveSession = this.readLiveSession(pidDirectory);
+      if (liveSession !== null) {
+        liveSessions.push(liveSession);
+      }
+    }
+    return liveSessions;
+  };
+
+  private listProcessIdDirectories = (): string[] => {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(this.procDirectory);
+    } catch {
+      return [];
+    }
+    return entries.filter((entry) => /^\d+$/.test(entry));
+  };
+
+  private readLiveSession = (
+    processIdDirectory: string,
+  ): ClaudeLiveSession | null => {
+    const environ = this.readEnviron(processIdDirectory);
+    if (environ === null) {
+      return null;
+    }
+    const token = environ.get(OAUTH_TOKEN_ENVIRON_KEY);
+    const sessionId = environ.get(SESSION_ID_ENVIRON_KEY);
+    if (
+      token === undefined ||
+      token.length === 0 ||
+      sessionId === undefined ||
+      sessionId.length === 0
+    ) {
+      return null;
+    }
+    if (!this.isClaudeProcess(processIdDirectory)) {
+      return null;
+    }
+    return { token, sessionId };
+  };
+
+  private isClaudeProcess = (processIdDirectory: string): boolean => {
+    const basePath = path.join(this.procDirectory, processIdDirectory);
+    try {
+      const cmdline = fs.readFileSync(path.join(basePath, 'cmdline'), 'utf8');
+      if (isClaudeProcessCommand(cmdline)) {
+        return true;
+      }
+    } catch {
+      return false;
+    }
+    try {
+      const exe = fs.readlinkSync(path.join(basePath, 'exe'));
+      return isClaudeProcessCommand(exe);
+    } catch {
+      return false;
+    }
+  };
+
+  private readEnviron = (
+    processIdDirectory: string,
+  ): Map<string, string> | null => {
+    const environPath = path.join(
+      this.procDirectory,
+      processIdDirectory,
+      'environ',
+    );
+    let raw: string;
+    try {
+      raw = fs.readFileSync(environPath, 'utf8');
+    } catch {
+      return null;
+    }
+    const environ = new Map<string, string>();
+    for (const entry of raw.split('\0')) {
+      if (entry.length === 0) {
+        continue;
+      }
+      const separatorIndex = entry.indexOf('=');
+      if (separatorIndex <= 0) {
+        continue;
+      }
+      const key = entry.slice(0, separatorIndex);
+      const value = entry.slice(separatorIndex + 1);
+      environ.set(key, value);
+    }
+    return environ;
+  };
+}

package/src/domain/usecases/LiveSessionOauthTokenSelectUseCase.test.ts

@@ -0,0 +1,147 @@
+import { ClaudeLiveSession } from './adapter-interfaces/ClaudeLiveSessionRepository';
+import { LiveSessionOauthTokenSelectUseCase } from './LiveSessionOauthTokenSelectUseCase';
+import {
+  OauthTokenCandidate,
+  OauthTokenWindowSnapshot,
+} from './OauthTokenSelectUseCase';
+
+const NOW = 1_000_000;
+const HOUR = 3600;
+const DAY = 86400;
+
+const snapshot = (
+  overrides: Partial<OauthTokenWindowSnapshot>,
+): OauthTokenWindowSnapshot => ({
+  fiveHourUtilization: 0,
+  fiveHourReset: NOW + HOUR,
+  sevenDayUtilization: 0,
+  sevenDayReset: NOW + DAY,
+  ...overrides,
+});
+
+const candidate = (
+  name: string,
+  snapshotValue: OauthTokenWindowSnapshot | null,
+): OauthTokenCandidate => ({
+  name,
+  token: `fake-token-${name}`,
+  snapshot: snapshotValue,
+});
+
+const session = (name: string, sessionId: string): ClaudeLiveSession => ({
+  token: `fake-token-${name}`,
+  sessionId,
+});
+
+describe('LiveSessionOauthTokenSelectUseCase', () => {
+  const useCase = new LiveSessionOauthTokenSelectUseCase();
+
+  it('prefers the eligible token with zero live sessions', () => {
+    const result = useCase.run(
+      [candidate('busy', snapshot({})), candidate('idle', snapshot({}))],
+      [session('busy', 'session-a')],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('idle');
+    expect(result.selected?.token).toBe('fake-token-idle');
+    const idle = result.metrics.find((m) => m.name === 'idle');
+    expect(idle?.liveSessionCount).toBe(0);
+  });
+
+  it('breaks an occupancy tie by the soonest 7d reset', () => {
+    const result = useCase.run(
+      [
+        candidate('far', snapshot({ sevenDayReset: NOW + 6 * DAY })),
+        candidate('soon', snapshot({ sevenDayReset: NOW + 2 * DAY })),
+      ],
+      [session('far', 'session-a'), session('soon', 'session-b')],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('soon');
+  });
+
+  it('prefers fewer live sessions over a sooner 7d reset', () => {
+    const result = useCase.run(
+      [
+        candidate('soonButBusy', snapshot({ sevenDayReset: NOW + 2 * DAY })),
+        candidate('farButIdle', snapshot({ sevenDayReset: NOW + 6 * DAY })),
+      ],
+      [
+        session('soonButBusy', 'session-a'),
+        session('soonButBusy', 'session-b'),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('farButIdle');
+  });
+
+  it('excludes a rate-limit-ineligible token even when it has no live sessions', () => {
+    const result = useCase.run(
+      [
+        candidate('idleButBlocked', snapshot({ fiveHourUtilization: 0.9 })),
+        candidate('busyButFree', snapshot({})),
+      ],
+      [session('busyButFree', 'session-a')],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('busyButFree');
+    const blocked = result.metrics.find((m) => m.name === 'idleButBlocked');
+    expect(blocked?.eligible).toBe(false);
+    expect(blocked?.liveSessionCount).toBe(0);
+  });
+
+  it('counts distinct session ids and dedupes child processes sharing one session', () => {
+    const result = useCase.run(
+      [
+        candidate('oneSession', snapshot({ sevenDayReset: NOW + 2 * DAY })),
+        candidate('twoSessions', snapshot({ sevenDayReset: NOW + 6 * DAY })),
+      ],
+      [
+        session('oneSession', 'session-a'),
+        session('oneSession', 'session-a'),
+        session('oneSession', 'session-a'),
+        session('twoSessions', 'session-b'),
+        session('twoSessions', 'session-c'),
+      ],
+      NOW,
+    );
+
+    expect(result.selected?.name).toBe('oneSession');
+    const oneSession = result.metrics.find((m) => m.name === 'oneSession');
+    const twoSessions = result.metrics.find((m) => m.name === 'twoSessions');
+    expect(oneSession?.liveSessionCount).toBe(1);
+    expect(twoSessions?.liveSessionCount).toBe(2);
+  });
+
+  it('returns null selection when no token passes the rate-limit filter', () => {
+    const result = useCase.run(
+      [candidate('blocked', snapshot({ fiveHourUtilization: 0.9 }))],
+      [],
+      NOW,
+    );
+
+    expect(result.selected).toBeNull();
+  });
+
+  it('returns null selection for an empty candidate list', () => {
+    const result = useCase.run([], [], NOW);
+
+    expect(result.selected).toBeNull();
+    expect(result.metrics).toEqual([]);
+  });
+
+  it('reports a zero live session count for tokens with no matching process', () => {
+    const result = useCase.run(
+      [candidate('lonely', snapshot({}))],
+      [session('other', 'session-x')],
+      NOW,
+    );
+
+    const lonely = result.metrics.find((m) => m.name === 'lonely');
+    expect(lonely?.liveSessionCount).toBe(0);
+  });
+});

package/src/domain/usecases/LiveSessionOauthTokenSelectUseCase.ts

@@ -0,0 +1,100 @@
+import { ClaudeLiveSession } from './adapter-interfaces/ClaudeLiveSessionRepository';
+import {
+  OauthTokenCandidate,
+  OauthTokenSelectUseCase,
+} from './OauthTokenSelectUseCase';
+
+export type LiveSessionOauthTokenCandidateMetrics = {
+  name: string;
+  fiveHourFreeRatio: number;
+  sevenDayFreeRatio: number;
+  sevenDayEndEpoch: number;
+  liveSessionCount: number;
+  eligible: boolean;
+  exclusionReason: string | null;
+};
+
+export type LiveSessionOauthTokenSelectResult = {
+  selected: OauthTokenCandidate | null;
+  metrics: LiveSessionOauthTokenCandidateMetrics[];
+};
+
+export class LiveSessionOauthTokenSelectUseCase {
+  constructor(
+    private readonly rateLimitSelectUseCase: OauthTokenSelectUseCase = new OauthTokenSelectUseCase(),
+  ) {}
+
+  run = (
+    candidates: OauthTokenCandidate[],
+    liveSessions: ClaudeLiveSession[],
+    nowEpochSeconds: number,
+  ): LiveSessionOauthTokenSelectResult => {
+    const rateLimitResult = this.rateLimitSelectUseCase.run(
+      candidates,
+      nowEpochSeconds,
+    );
+    const liveSessionCountByToken = this.liveSessionCountByToken(liveSessions);
+
+    const evaluated = candidates.map((candidate, index) => {
+      const rateLimitMetric = rateLimitResult.metrics[index];
+      const liveSessionCount =
+        liveSessionCountByToken.get(candidate.token) ?? 0;
+      return {
+        candidate,
+        metric: {
+          name: rateLimitMetric.name,
+          fiveHourFreeRatio: rateLimitMetric.fiveHourFreeRatio,
+          sevenDayFreeRatio: rateLimitMetric.sevenDayFreeRatio,
+          sevenDayEndEpoch: rateLimitMetric.sevenDayEndEpoch,
+          liveSessionCount,
+          eligible: rateLimitMetric.eligible,
+          exclusionReason: rateLimitMetric.exclusionReason,
+        },
+      };
+    });
+
+    const metrics = evaluated.map((entry) => entry.metric);
+    const eligible = evaluated.filter((entry) => entry.metric.eligible);
+
+    if (eligible.length === 0) {
+      return { selected: null, metrics };
+    }
+
+    const best = eligible.reduce((bestEntry, currentEntry) =>
+      this.preferred(currentEntry.metric, bestEntry.metric)
+        ? currentEntry
+        : bestEntry,
+    );
+
+    return { selected: best.candidate, metrics };
+  };
+
+  private preferred = (
+    candidateMetric: LiveSessionOauthTokenCandidateMetrics,
+    incumbentMetric: LiveSessionOauthTokenCandidateMetrics,
+  ): boolean => {
+    if (candidateMetric.liveSessionCount !== incumbentMetric.liveSessionCount) {
+      return (
+        candidateMetric.liveSessionCount < incumbentMetric.liveSessionCount
+      );
+    }
+    return candidateMetric.sevenDayEndEpoch < incumbentMetric.sevenDayEndEpoch;
+  };
+
+  private liveSessionCountByToken = (
+    liveSessions: ClaudeLiveSession[],
+  ): Map<string, number> => {
+    const sessionIdsByToken = new Map<string, Set<string>>();
+    for (const liveSession of liveSessions) {
+      const sessionIds =
+        sessionIdsByToken.get(liveSession.token) ?? new Set<string>();
+      sessionIds.add(liveSession.sessionId);
+      sessionIdsByToken.set(liveSession.token, sessionIds);
+    }
+    const countByToken = new Map<string, number>();
+    for (const [token, sessionIds] of sessionIdsByToken.entries()) {
+      countByToken.set(token, sessionIds.size);
+    }
+    return countByToken;
+  };
+}

package/src/domain/usecases/adapter-interfaces/ClaudeLiveSessionRepository.ts

@@ -0,0 +1,8 @@
+export type ClaudeLiveSession = {
+  token: string;
+  sessionId: string;
+};
+
+export interface ClaudeLiveSessionRepository {
+  listLiveSessions: () => ClaudeLiveSession[];
+}

package/src/domain/usecases/adapter-interfaces/TmuxSessionRepository.ts

@@ -0,0 +1,9 @@
+export interface TmuxSessionRepository {
+  listLiveSessionNames: () => Promise<string[]>;
+  listInteractiveProcessCommandLines: () => Promise<string[]>;
+  launchDetachedSession: (
+    sessionName: string,
+    launcherCommand: string,
+    issueUrl: string,
+  ) => Promise<void>;
+}