@rikcodes/teamclaude 1.1.13-rik.1

package/src/service.js

@@ -0,0 +1,241 @@
+// Run the proxy as a user service — `teamclaude service install`.
+//
+// npm has no equivalent of `brew services`, and a postinstall hook is the wrong
+// place for this (it is skipped under --ignore-scripts, surprises CI, and
+// installs system state nobody asked for). So the CLI does it explicitly, the
+// same way `teamclaude alias --install` handles the shell alias.
+//
+// macOS gets a LaunchAgent, Linux a systemd --user unit. Both are per-user: no
+// root, no system-wide daemon, and the proxy runs as the user whose accounts and
+// config it serves.
+
+import { writeFile, mkdir, rm, readFile } from 'node:fs/promises';
+import { existsSync, realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const LABEL = 'com.karpeleslab.teamclaude';
+export const UNIT_NAME = 'teamclaude.service';
+
+/** Which service manager to target, or null where we have nothing to offer. */
+export function serviceKind(platform = process.platform) {
+  if (platform === 'darwin') return 'launchd';
+  if (platform === 'linux') return 'systemd';
+  return null;
+}
+
+export function launchAgentPath(home = homedir()) {
+  return join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+
+export function systemdUnitPath(home = homedir(), xdgConfig = process.env.XDG_CONFIG_HOME) {
+  return join(xdgConfig || join(home, '.config'), 'systemd', 'user', UNIT_NAME);
+}
+
+export function logPath(home = homedir(), platform = process.platform) {
+  return platform === 'darwin'
+    ? join(home, 'Library', 'Logs', 'teamclaude.log')
+    : join(home, '.local', 'state', 'teamclaude.log');
+}
+
+/**
+ * The interpreter and script to bake into the unit.
+ *
+ * `process.execPath` is NOT usable as-is: on a Homebrew install it points into
+ * the versioned Cellar directory (…/Cellar/node/26.5.0_1/bin/node), which the
+ * next `brew upgrade node` deletes — the service would then fail to start with
+ * no obvious connection to the upgrade. Prefer a `node` on PATH that resolves to
+ * the same binary, since that is the stable symlink maintained across upgrades.
+ *
+ * The script is `argv[1]` unresolved for the same reason: the bin symlink
+ * survives a package reinstall, the versioned path inside node_modules may not.
+ */
+export function resolveExec({
+  execPath = process.execPath,
+  argv1 = process.argv[1],
+  pathEnv = process.env.PATH || '',
+  realpath = realpathSync,
+  exists = existsSync,
+} = {}) {
+  const same = (candidate) => {
+    try { return realpath(candidate) === realpath(execPath); } catch { return false; }
+  };
+  let node = execPath;
+  for (const dir of pathEnv.split(':')) {
+    if (!dir) continue;
+    const candidate = join(dir, 'node');
+    if (exists(candidate) && same(candidate)) { node = candidate; break; }
+  }
+  return { node, entry: argv1 };
+}
+
+/**
+ * PATH for the service. launchd starts with an empty environment, so without
+ * this the background self-update cannot find npm, and any child process the
+ * proxy spawns inherits nothing. Built from the directories that actually
+ * matter rather than copying the interactive shell's PATH, which is full of
+ * per-session entries that mean nothing to a daemon.
+ */
+export function servicePath({ node, entry }) {
+  const dirs = [dirname(node), dirname(entry), '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+  return [...new Set(dirs.filter(Boolean))].join(':');
+}
+
+const xmlEscape = (s) => String(s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+export function renderLaunchAgent({ node, entry, log, path, configPath = null }) {
+  const args = [node, entry, 'server', '--headless'];
+  const env = [`    <key>PATH</key>\n    <string>${xmlEscape(path)}</string>`];
+  if (configPath) env.push(`    <key>TEAMCLAUDE_CONFIG</key>\n    <string>${xmlEscape(configPath)}</string>`);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args.map(a => `    <string>${xmlEscape(a)}</string>`).join('\n')}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(log)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env.join('\n')}
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function renderSystemdUnit({ node, entry, path, configPath = null }) {
+  const environment = [`Environment=PATH=${path}`];
+  if (configPath) environment.push(`Environment=TEAMCLAUDE_CONFIG=${configPath}`);
+  return `[Unit]
+Description=TeamClaude multi-account Claude proxy
+Documentation=https://github.com/KarpelesLab/teamclaude
+After=network-online.target
+
+[Service]
+ExecStart=${node} ${entry} server --headless
+Restart=always
+RestartSec=5
+${environment.join('\n')}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** Run a command, returning { code, stdout, stderr }. Injected in tests. */
+function runCommand(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+  return { code: r.status ?? 1, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+/** `gui/<uid>` — the launchd domain a per-user agent lives in. */
+const guiDomain = (uid = process.getuid?.() ?? 0) => `gui/${uid}`;
+
+export async function installService({
+  kind = serviceKind(), home = homedir(), platform = process.platform,
+  exec = resolveExec(), run = runCommand, configPath = null, log = console.log,
+  xdgConfig = process.env.XDG_CONFIG_HOME,
+} = {}) {
+  if (!kind) return { ok: false, error: `No service integration for ${platform}` };
+  const logFile = logPath(home, platform);
+  const path = servicePath(exec);
+
+  if (kind === 'launchd') {
+    const plist = launchAgentPath(home);
+    await mkdir(dirname(plist), { recursive: true });
+    await mkdir(dirname(logFile), { recursive: true });
+    await writeFile(plist, renderLaunchAgent({ ...exec, log: logFile, path, configPath }), { mode: 0o644 });
+    // Replace any previous registration first: bootstrap fails outright when the
+    // label is already loaded, and an install that reports success while the old
+    // definition keeps running is worse than a loud failure.
+    run('launchctl', ['bootout', `${guiDomain()}/${LABEL}`]);
+    const boot = run('launchctl', ['bootstrap', guiDomain(), plist]);
+    if (boot.code !== 0) return { ok: false, error: boot.stderr.trim() || `launchctl bootstrap exited ${boot.code}`, file: plist };
+    log(`[TeamClaude] Service installed: ${plist}`);
+    log(`[TeamClaude] Logs: ${logFile}`);
+    return { ok: true, file: plist, logFile };
+  }
+
+  const unit = systemdUnitPath(home, xdgConfig);
+  await mkdir(dirname(unit), { recursive: true });
+  await writeFile(unit, renderSystemdUnit({ ...exec, path, configPath }), { mode: 0o644 });
+  run('systemctl', ['--user', 'daemon-reload']);
+  const enable = run('systemctl', ['--user', 'enable', '--now', UNIT_NAME]);
+  if (enable.code !== 0) return { ok: false, error: enable.stderr.trim() || `systemctl exited ${enable.code}`, file: unit };
+  log(`[TeamClaude] Service installed: ${unit}`);
+  log('[TeamClaude] Logs: journalctl --user --unit teamclaude.service --follow');
+  // Without lingering the unit dies with the last login session, which is not
+  // what "install a service" is expected to mean.
+  log('[TeamClaude] To keep it running with no session open: loginctl enable-linger $USER');
+  return { ok: true, file: unit, logFile: null };
+}
+
+export async function uninstallService({
+  kind = serviceKind(), home = homedir(), run = runCommand, log = console.log,
+  xdgConfig = process.env.XDG_CONFIG_HOME,
+} = {}) {
+  if (!kind) return { ok: false, error: 'No service integration for this platform' };
+  if (kind === 'launchd') {
+    const plist = launchAgentPath(home);
+    run('launchctl', ['bootout', `${guiDomain()}/${LABEL}`]);
+    await rm(plist, { force: true });
+    log(`[TeamClaude] Service removed: ${plist}`);
+    return { ok: true, file: plist };
+  }
+  const unit = systemdUnitPath(home, xdgConfig);
+  run('systemctl', ['--user', 'disable', '--now', UNIT_NAME]);
+  await rm(unit, { force: true });
+  run('systemctl', ['--user', 'daemon-reload']);
+  log(`[TeamClaude] Service removed: ${unit}`);
+  return { ok: true, file: unit };
+}
+
+export async function serviceStatus({
+  kind = serviceKind(), home = homedir(), run = runCommand,
+  xdgConfig = process.env.XDG_CONFIG_HOME,
+} = {}) {
+  if (!kind) return { installed: false, running: false, detail: 'unsupported platform' };
+  if (kind === 'launchd') {
+    const plist = launchAgentPath(home);
+    const installed = existsSync(plist);
+    const r = run('launchctl', ['print', `${guiDomain()}/${LABEL}`]);
+    const pid = /\bpid = (\d+)/.exec(r.stdout)?.[1] || null;
+    return { installed, running: r.code === 0 && !!pid, pid, file: plist, detail: r.code === 0 ? 'loaded' : 'not loaded' };
+  }
+  const unit = systemdUnitPath(home, xdgConfig);
+  const r = run('systemctl', ['--user', 'is-active', UNIT_NAME]);
+  return { installed: existsSync(unit), running: r.stdout.trim() === 'active', file: unit, detail: r.stdout.trim() || r.stderr.trim() };
+}
+
+/** The unit file contents, for `service print` — inspect before installing. */
+export function renderService({ kind = serviceKind(), home = homedir(), platform = process.platform, exec = resolveExec(), configPath = null } = {}) {
+  if (!kind) return null;
+  const path = servicePath(exec);
+  return kind === 'launchd'
+    ? renderLaunchAgent({ ...exec, log: logPath(home, platform), path, configPath })
+    : renderSystemdUnit({ ...exec, path, configPath });
+}
+
+/** Read back what is installed, for diffing against what we would write now. */
+export async function readInstalled({
+  kind = serviceKind(), home = homedir(), xdgConfig = process.env.XDG_CONFIG_HOME,
+} = {}) {
+  if (!kind) return null;
+  const file = kind === 'launchd' ? launchAgentPath(home) : systemdUnitPath(home, xdgConfig);
+  return readFile(file, 'utf8').catch(() => null);
+}

package/src/session-tracker.js

@@ -0,0 +1,133 @@
+// Tracks Claude Code sessions by their `x-claude-code-session-id` header so
+// teamclaude can (a) report how many sessions are running and (b) optionally
+// keep each session pinned to one account while spreading NEW sessions across
+// accounts (the opt-in fix for concurrency funnelling — issue #109).
+//
+// Two windows:
+//   - KNOWN: a session is remembered until it goes idle for this long, then
+//     forgotten. 1h matches the maximum prompt-cache extension window — past
+//     that there is no cache left to preserve, so the pin has no value.
+//   - ACTIVE: a session counts as "active" (and toward per-account load) if it
+//     made a request this recently. Short, so load-balancing reacts to what is
+//     actually running now rather than to sessions merely lingering in the hour.
+export const SESSION_KNOWN_TTL_MS = 60 * 60 * 1000; // 1h idle → forgotten
+export const SESSION_ACTIVE_TTL_MS = 2 * 60 * 1000; // 2min idle → no longer "active"
+
+const SWEEP_INTERVAL_MS = 60 * 1000; // bound growth without an external timer
+
+export class SessionTracker {
+  constructor({ knownTtlMs, activeTtlMs, now } = {}) {
+    // id -> { accountIndex, firstSeen, lastSeen, count, inFlight }
+    this.sessions = new Map();
+    this.knownTtlMs = knownTtlMs ?? SESSION_KNOWN_TTL_MS;
+    this.activeTtlMs = activeTtlMs ?? SESSION_ACTIVE_TTL_MS;
+    this._now = now || (() => Date.now());
+    this._lastSweep = 0;
+  }
+
+  // Record that `sessionId` made a request served by `accountIndex`. Refreshes
+  // lastSeen (keeping the session "active"/"known") and, when an account is
+  // given, (re)pins the session to it. Throttled sweep keeps the map bounded
+  // even in a headless server that never renders status.
+  touch(sessionId, accountIndex = null, now = this._now()) {
+    if (!sessionId) return null;
+    const s = this._ensure(sessionId, now);
+    s.lastSeen = now;
+    s.count += 1;
+    if (accountIndex != null) s.accountIndex = accountIndex;
+    if (now - this._lastSweep > SWEEP_INTERVAL_MS) this.sweep(now);
+    return s;
+  }
+
+  // Mark a request for this session as started. A session with any request in
+  // flight counts as active (and non-expirable) for the whole request, however
+  // long it streams — a 5-minute completion must not drop out of "active" or the
+  // load balancer would under-count that account. Paired with endRequest.
+  beginRequest(sessionId, now = this._now()) {
+    if (!sessionId) return null;
+    const s = this._ensure(sessionId, now);
+    s.inFlight += 1;
+    s.lastSeen = now;
+    return s;
+  }
+
+  // Mark a request as finished (refreshes recency; releases the in-flight hold).
+  endRequest(sessionId, now = this._now()) {
+    const s = sessionId && this.sessions.get(sessionId);
+    if (!s) return;
+    s.inFlight = Math.max(0, s.inFlight - 1);
+    s.lastSeen = now;
+  }
+
+  _ensure(sessionId, now) {
+    let s = this.sessions.get(sessionId);
+    if (!s) {
+      s = { accountIndex: null, firstSeen: now, lastSeen: now, count: 0, inFlight: 0 };
+      this.sessions.set(sessionId, s);
+    }
+    return s;
+  }
+
+  // Active = a request in flight now, or one seen within the active window.
+  _isActive(s, now) {
+    return s.inFlight > 0 || now - s.lastSeen <= this.activeTtlMs;
+  }
+
+  // Expired = idle past the known window AND nothing in flight (a long-running
+  // request keeps the session alive no matter how old lastSeen is).
+  _isExpired(s, now) {
+    return s.inFlight === 0 && now - s.lastSeen > this.knownTtlMs;
+  }
+
+  // The account a known (non-expired) session is pinned to, or null if the
+  // session is unknown/forgotten. Expired-on-read entries are dropped.
+  pinnedAccount(sessionId, now = this._now()) {
+    const s = sessionId && this.sessions.get(sessionId);
+    if (!s) return null;
+    if (this._isExpired(s, now)) {
+      this.sessions.delete(sessionId);
+      return null;
+    }
+    return s.accountIndex ?? null;
+  }
+
+  // Active sessions currently pinned to `accountIndex` — the load metric used to
+  // spread new sessions across accounts. Counts in-flight sessions regardless of
+  // how long their request has been streaming.
+  activeCountFor(accountIndex, now = this._now()) {
+    let n = 0;
+    for (const s of this.sessions.values()) {
+      if (s.accountIndex === accountIndex && this._isActive(s, now)) n += 1;
+    }
+    return n;
+  }
+
+  // Drop sessions idle longer than the known window (but never one still in flight).
+  sweep(now = this._now()) {
+    this._lastSweep = now;
+    for (const [id, s] of this.sessions) {
+      if (this._isExpired(s, now)) this.sessions.delete(id);
+    }
+  }
+
+  // { known, active, perAccount: { [index]: activeCount } } — for status/TUI.
+  // Sweeps as it goes so a long-lived headless server stays bounded.
+  stats(now = this._now()) {
+    this._lastSweep = now;
+    let known = 0;
+    let active = 0;
+    const perAccount = {};
+    for (const [id, s] of this.sessions) {
+      if (this._isExpired(s, now)) {
+        this.sessions.delete(id);
+        continue;
+      }
+      known += 1;
+      if (this._isActive(s, now)) {
+        active += 1;
+        if (s.accountIndex != null) perAccount[s.accountIndex] = (perAccount[s.accountIndex] || 0) + 1;
+      }
+    }
+    return { known, active, perAccount };
+  }
+}