codex-ringside 0.0.0-stage → 0.1.0

package/native/bridge.swift

@@ -0,0 +1,212 @@
+// Small AppKit helper for the startup handoff. Every command prints one JSON line.
+//
+//   bridge snapshot <app>
+//   bridge watch    <app>
+//   bridge quit     <app> <pid> <key> <stamp>
+//   bridge launch   <app> <port>
+//   bridge show     <app> <pid> <key> <stamp> <frontmostPid>
+//   bridge wallpaper <app>
+//
+// It only reads input event counters and timestamps, never what was typed, and it only
+// ever calls terminate(): a refused quit stays refused.
+import AppKit
+import CoreGraphics
+import Foundation
+
+let inputEvents: [CGEventType] = [.keyDown, .leftMouseDown, .rightMouseDown, .otherMouseDown, .scrollWheel]
+
+func emit(_ value: Any) {
+    guard let data = try? JSONSerialization.data(withJSONObject: value),
+          let line = String(data: data, encoding: .utf8) else { exit(1) }
+    print(line)
+    fflush(stdout)
+}
+
+func fail(_ message: String) -> Never {
+    FileHandle.standardError.write(Data("\(message)\n".utf8))
+    exit(2)
+}
+
+func inputStamp() -> Int {
+    inputEvents.reduce(0) { $0 + Int(CGEventSource.counterForEventType(.combinedSessionState, eventType: $1)) }
+}
+
+// Mouse movement is left out on purpose: moving away from the Dock is not "using" the app.
+func inputIdleMs() -> Double {
+    let seconds = inputEvents
+        .map { CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: $0) }
+        .min() ?? .infinity
+    return seconds.isFinite ? seconds * 1000 : 1e12
+}
+
+func canonical(_ path: String) -> String {
+    URL(fileURLWithPath: path).resolvingSymlinksInPath().path
+}
+
+func runningApps(_ appPath: String) -> [NSRunningApplication] {
+    NSWorkspace.shared.runningApplications.filter {
+        guard let url = $0.bundleURL else { return false }
+        return canonical(url.path) == appPath && !$0.isTerminated
+    }
+}
+
+func launchMs(_ app: NSRunningApplication) -> Int {
+    Int((app.launchDate?.timeIntervalSince1970 ?? 0) * 1000)
+}
+
+func processKey(_ app: NSRunningApplication) -> String {
+    "\(app.processIdentifier):\(launchMs(app))"
+}
+
+func commandLine(_ pid: pid_t) -> String? {
+    let process = Process()
+    let pipe = Pipe()
+    process.executableURL = URL(fileURLWithPath: "/bin/ps")
+    process.arguments = ["-ww", "-o", "command=", "-p", String(pid)]
+    process.standardOutput = pipe
+    process.standardError = FileHandle.nullDevice
+    do { try process.run() } catch { return nil }
+    let data = pipe.fileHandleForReading.readDataToEndOfFile()
+    process.waitUntilExit()
+    guard process.terminationStatus == 0, let text = String(data: data, encoding: .utf8) else { return nil }
+    return text.isEmpty ? nil : text
+}
+
+func debugPort(_ command: String) -> Int? {
+    guard let range = command.range(of: #"--remote-debugging-port=\d+"#, options: .regularExpression) else { return nil }
+    return Int(command[range].split(separator: "=").last ?? "")
+}
+
+func describe(_ app: NSRunningApplication) -> [String: Any] {
+    let command = commandLine(app.processIdentifier)
+    return [
+        "pid": Int(app.processIdentifier),
+        "key": processKey(app),
+        "launchedAt": launchMs(app),
+        "finishedLaunching": app.isFinishedLaunching,
+        "argumentsKnown": command != nil,
+        "debugPort": command.flatMap(debugPort) as Any? ?? NSNull()
+    ]
+}
+
+func snapshot(_ appPath: String) -> [String: Any] {
+    [
+        "apps": runningApps(appPath).map(describe),
+        "frontmostPid": NSWorkspace.shared.frontmostApplication.map { Int($0.processIdentifier) } as Any? ?? NSNull(),
+        "inputIdleMs": inputIdleMs(),
+        "inputStamp": inputStamp()
+    ]
+}
+
+func find(_ appPath: String, pid: String, key: String) -> NSRunningApplication? {
+    guard let pid = pid_t(pid) else { return nil }
+    return runningApps(appPath).first { $0.processIdentifier == pid && processKey($0) == key }
+}
+
+// openApplication is asynchronous and needs the main run loop to deliver its completion.
+func open(_ appPath: String, _ configuration: NSWorkspace.OpenConfiguration, timeout: TimeInterval) -> NSRunningApplication? {
+    var opened: NSRunningApplication?
+    var done = false
+    NSWorkspace.shared.openApplication(at: URL(fileURLWithPath: appPath), configuration: configuration) { app, _ in
+        DispatchQueue.main.async {
+            opened = app
+            done = true
+        }
+    }
+    let deadline = Date(timeIntervalSinceNow: timeout)
+    while !done && Date() < deadline {
+        RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.05))
+    }
+    return opened
+}
+
+func watch(_ appPath: String) -> Never {
+    let center = NSWorkspace.shared.notificationCenter
+    let names: [NSNotification.Name] = [
+        NSWorkspace.didLaunchApplicationNotification,
+        NSWorkspace.didTerminateApplicationNotification,
+        NSWorkspace.didActivateApplicationNotification
+    ]
+    let tokens = names.map { name in
+        center.addObserver(forName: name, object: nil, queue: .main) { note in
+            guard let app = note.userInfo?[NSWorkspace.applicationUserInfoKey] as? NSRunningApplication,
+                  let url = app.bundleURL, canonical(url.path) == appPath else { return }
+            emit(["event": name.rawValue, "pid": Int(app.processIdentifier)])
+        }
+    }
+    emit(["event": "watching"])
+    withExtendedLifetime(tokens) { RunLoop.main.run() }
+    exit(0)
+}
+
+// Cocoa measures from the bottom of the primary screen, the renderer from its top.
+func wallpaper() -> [String: Any] {
+    let primaryHeight = NSScreen.screens.first?.frame.height ?? 0
+    return ["screens": NSScreen.screens.map { screen -> [String: Any] in
+        let frame = screen.frame
+        return [
+            "x": frame.minX,
+            "y": primaryHeight - frame.maxY,
+            "width": frame.width,
+            "height": frame.height,
+            "image": NSWorkspace.shared.desktopImageURL(for: screen)?.path as Any? ?? NSNull()
+        ]
+    }]
+}
+
+let args = CommandLine.arguments
+guard args.count >= 3 else { fail("usage: bridge <command> <app> [...]") }
+let command = args[1]
+let appPath = canonical(args[2])
+
+switch command {
+case "snapshot":
+    emit(snapshot(appPath))
+
+case "watch":
+    watch(appPath)
+
+case "quit":
+    guard args.count == 6 else { fail("usage: bridge quit <app> <pid> <key> <stamp>") }
+    // The user started working between the decision and now: leave the app alone.
+    guard String(inputStamp()) == args[5], let app = find(appPath, pid: args[3], key: args[4]) else {
+        emit(["accepted": false])
+        break
+    }
+    emit(["accepted": app.terminate()])
+
+case "launch":
+    guard args.count == 4 else { fail("usage: bridge launch <app> <port>") }
+    guard runningApps(appPath).isEmpty else {
+        emit(["launched": false])
+        break
+    }
+    let configuration = NSWorkspace.OpenConfiguration()
+    configuration.arguments = ["--remote-debugging-port=\(args[3])", "--remote-debugging-address=127.0.0.1"]
+    configuration.activates = false
+    configuration.addsToRecentItems = false
+    configuration.createsNewApplicationInstance = false
+    guard let app = open(appPath, configuration, timeout: 20) else {
+        emit(["launched": false])
+        break
+    }
+    emit(["launched": true, "pid": Int(app.processIdentifier), "key": processKey(app)])
+
+case "show":
+    guard args.count == 7 else { fail("usage: bridge show <app> <pid> <key> <stamp> <frontmostPid>") }
+    let frontmost = NSWorkspace.shared.frontmostApplication.map { String($0.processIdentifier) } ?? ""
+    guard String(inputStamp()) == args[5], frontmost == args[6], find(appPath, pid: args[3], key: args[4]) != nil else {
+        emit(["shown": false])
+        break
+    }
+    let configuration = NSWorkspace.OpenConfiguration()
+    configuration.activates = true
+    configuration.addsToRecentItems = false
+    emit(["shown": open(appPath, configuration, timeout: 10) != nil])
+
+case "wallpaper":
+    emit(wallpaper())
+
+default:
+    fail("unknown command: \(command)")
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "codex-ringside",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Usage rings and customizable backgrounds for the Codex desktop app. Unofficial macOS add-on.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "codex-ringside": "bin/codex-ringside.cjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "install-agent": "node bin/codex-ringside.cjs install",
+    "uninstall-agent": "node bin/codex-ringside.cjs uninstall",
+    "status": "node bin/codex-ringside.cjs status",
+    "check": "node scripts/check.cjs",
+    "check:package": "node scripts/check-package.cjs",
+    "verify": "npm run check && npm test && npm run check:package"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tccpc/codex-ringside.git"
+  },
+  "homepage": "https://github.com/tccpc/codex-ringside#readme",
+  "bugs": {
+    "url": "https://github.com/tccpc/codex-ringside/issues"
+  },
+  "author": "tccpc",
+  "keywords": [
+    "codex",
+    "macos",
+    "usage",
+    "sidebar",
+    "background"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin/*.cjs",
+    "src/**/*.cjs",
+    "src/**/*.js",
+    "native/bridge.swift",
+    "README*.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ]
+}

package/src/agent.cjs

@@ -0,0 +1,179 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { AppServerClient } = require('./app-server.cjs');
+const { BackgroundStore, readScreens } = require('./background.cjs');
+const { CDP_PORT, RendererInjector } = require('./cdp.cjs');
+const { formatUsage, unavailable } = require('./limits.cjs');
+const { authFile, resolveCodexBin } = require('./resolve.cjs');
+const { version } = require('../package.json');
+
+const SCAN_MS = 5000;
+const POLL_MS = 60000;
+
+const log = message => process.stdout.write(`[${new Date().toISOString()}] ${message}\n`);
+
+// Only the timestamp is read. Account switchers such as Cockpit Tools rewrite this file.
+function authStamp() {
+  try {
+    return fs.statSync(authFile()).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+async function runAgent({ appPath, root, signal }) {
+  const injector = new RendererInjector({ port: CDP_PORT });
+  injector.currentValue = { rings: [], message: '正在读取 Codex 剩余额度' };
+  const background = new BackgroundStore({ root, readScreens: () => readScreens(root, appPath) });
+  let backgroundWork = Promise.resolve();
+  let client = null;
+  let reading = false;
+  let nextRead = 0;
+  let failures = 0;
+  let connected = false;
+  let seenAuth = authStamp();
+  let ticking = false;
+
+  const dropClient = () => {
+    const old = client;
+    client = null;
+    old?.stop();
+  };
+  const showUnavailable = () => injector.update(unavailable(injector.currentValue)).catch(() => {});
+
+  async function scan() {
+    try {
+      await injector.scan();
+      if (!connected && injector.sessions.size > 0) log('connected to Codex window');
+      connected = injector.sessions.size > 0;
+    } catch {
+      connected = false;
+      injector.clearSessions();
+    }
+    // No window to draw on means nothing to read: stop the app-server until Codex is back.
+    if (injector.sessions.size === 0) {
+      dropClient();
+      nextRead = 0;
+      injector.currentValue = unavailable(injector.currentValue);
+    }
+  }
+
+  function checkAccount() {
+    const stamp = authStamp();
+    if (stamp === seenAuth) return;
+    seenAuth = stamp;
+    log('account file changed, reconnecting');
+    dropClient();
+    nextRead = 0;
+  }
+
+  function createClient() {
+    const current = new AppServerClient({ command: resolveCodexBin(appPath), version });
+    current.on('rate-limits', data => {
+      if (client !== current) return;
+      injector.update({ ...formatUsage(data), updatedAt: Date.now(), stale: false }).catch(() => {});
+    });
+    current.on('server-exit', () => {
+      if (client !== current) return;
+      client = null;
+      nextRead = Date.now() + 10000;
+      showUnavailable();
+    });
+    return current;
+  }
+
+  async function readUsage() {
+    if (reading || Date.now() < nextRead || injector.sessions.size === 0) return;
+    reading = true;
+    try {
+      if (client) {
+        await client.refresh();
+      } else {
+        client = createClient();
+        await client.start();
+      }
+      failures = 0;
+      if (client) nextRead = Date.now() + POLL_MS;
+    } catch {
+      dropClient();
+      failures++;
+      nextRead = Date.now() + Math.min(POLL_MS, 10000 * failures);
+      await showUnavailable();
+    } finally {
+      reading = false;
+    }
+  }
+
+  // One job at a time: a panel change and a scan must not convert or prune images together.
+  function queueBackground(job) {
+    backgroundWork = backgroundWork
+      .then(job)
+      .then(next => next && injector.setBackground(next))
+      .catch(error => log(`background: ${error.message}`));
+  }
+
+  injector.onPanelMessage = text => queueBackground(async () => {
+    try {
+      await background.commit(JSON.parse(text));
+    } catch (error) {
+      await injector.notifyBackground(error.message);
+      return null;
+    }
+    return background.rebuild();
+  });
+
+  async function tick() {
+    if (ticking || signal.aborted) return;
+    ticking = true;
+    try {
+      await scan();
+      checkAccount();
+      readUsage().catch(() => {});
+      if (injector.sessions.size > 0) queueBackground(() => background.refresh());
+    } finally {
+      ticking = false;
+    }
+  }
+
+  const timer = setInterval(() => tick().catch(() => {}), SCAN_MS);
+  signal.addEventListener('abort', () => {
+    clearInterval(timer);
+    dropClient();
+    injector.stop();
+  }, { once: true });
+  await tick();
+}
+
+function loadSettings(root) {
+  return JSON.parse(fs.readFileSync(path.join(root, 'settings.json'), 'utf8'));
+}
+
+async function main() {
+  const { startWatcher } = require('./startup/watch.cjs');
+  const root = path.resolve(__dirname, '..');
+  const settings = loadSettings(root);
+  const abort = new AbortController();
+  log(`codex-ringside ${version} started`);
+
+  const watcher = startWatcher({ root, settings, log });
+  const shutdown = () => {
+    abort.abort();
+    watcher.stop();
+    process.exit(0);
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+
+  await runAgent({ appPath: settings.app, root, signal: abort.signal });
+  await watcher.exited;
+}
+
+module.exports = { loadSettings, runAgent };
+
+if (require.main === module) {
+  main().catch(error => {
+    log(`fatal: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/src/app-server.cjs

@@ -0,0 +1,96 @@
+'use strict';
+const { EventEmitter } = require('node:events');
+const { spawn } = require('node:child_process');
+const readline = require('node:readline');
+const { mergeResponse } = require('./limits.cjs');
+
+// Minimal JSON-RPC client for `codex app-server` over stdio. Only ever asks for rate limits.
+class AppServerClient extends EventEmitter {
+  constructor({ command, args = ['app-server'], version = '0', requestTimeoutMs = 15000 }) {
+    super();
+    Object.assign(this, { command, args, version, requestTimeoutMs });
+    this.child = null;
+    this.lines = null;
+    this.pending = new Map();
+    this.serial = 0;
+    this.rateLimits = null;
+  }
+
+  async start() {
+    if (this.child) return;
+    const child = spawn(this.command, this.args, { stdio: ['pipe', 'pipe', 'pipe'], env: process.env });
+    this.child = child;
+    const fail = error => {
+      if (this.child !== child) return;
+      this.stop();
+      this.emit('server-exit', error);
+    };
+    child.once('error', fail);
+    child.once('exit', code => fail(new Error(`App Server exited (${code})`)));
+    child.stdin.on('error', fail);
+    child.stderr.resume(); // Drain it: the stream can carry account details, so it is never logged.
+    this.lines = readline.createInterface({ input: child.stdout });
+    this.lines.on('line', line => this.handleLine(line));
+    await this.request('initialize', {
+      clientInfo: { name: 'codex_ringside', title: 'Codex Ringside', version: this.version }
+    });
+    this.child?.stdin.write(`${JSON.stringify({ method: 'initialized', params: {} })}\n`);
+    await this.refresh();
+  }
+
+  handleLine(line) {
+    let message;
+    try { message = JSON.parse(line); } catch { return; }
+    if (!message || typeof message !== 'object') return;
+    const request = this.pending.get(message.id);
+    if (request) {
+      this.pending.delete(message.id);
+      clearTimeout(request.timer);
+      if (message.error) request.reject(new Error(message.error.message || 'App Server request failed'));
+      else request.resolve(message.result);
+    } else if (message.method === 'account/rateLimits/updated') {
+      this.rateLimits = mergeResponse(this.rateLimits, message.params);
+      this.emit('rate-limits', this.rateLimits);
+    }
+  }
+
+  request(method, params) {
+    if (!this.child?.stdin.writable) return Promise.reject(new Error('App Server is not running'));
+    const id = ++this.serial;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out`));
+      }, this.requestTimeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      const body = JSON.stringify({ id, method, ...(params === undefined ? {} : { params }) });
+      this.child.stdin.write(`${body}\n`, error => {
+        if (error && this.pending.delete(id)) {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  async refresh() {
+    this.rateLimits = mergeResponse(null, await this.request('account/rateLimits/read'));
+    this.emit('rate-limits', this.rateLimits);
+    return this.rateLimits;
+  }
+
+  stop() {
+    const child = this.child;
+    this.child = null;
+    this.lines?.close();
+    this.lines = null;
+    if (child && !child.killed) child.kill();
+    for (const item of this.pending.values()) {
+      clearTimeout(item.timer);
+      item.reject(new Error('App Server stopped'));
+    }
+    this.pending.clear();
+  }
+}
+
+module.exports = { AppServerClient };