@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/attach/socket-discovery.ts

@@ -0,0 +1,230 @@
+/**
+ * Socket Discovery - Utilities for socket path management
+ *
+ * Socket locations are allocated by socket-paths.js under a short, per-user
+ * runtime directory so long HOME paths cannot exceed Unix socket limits.
+ */
+
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+
+import socketPaths from './socket-paths';
+
+interface ClustersRegistryModule {
+  readClustersFileSync(storageDir: string): unknown;
+}
+
+function isClustersRegistryModule(value: unknown): value is ClustersRegistryModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'readClustersFileSync' in value &&
+    typeof value.readClustersFileSync === 'function'
+  );
+}
+
+const clustersRegistryModule: unknown = require('../../lib/clusters-registry');
+if (!isClustersRegistryModule(clustersRegistryModule)) {
+  throw new TypeError('clusters registry must export readClustersFileSync');
+}
+const { readClustersFileSync } = clustersRegistryModule;
+
+const ZEROSHOT_DIR = path.join(socketPaths.resolveHomeDir(), '.zeroshot');
+const SOCKET_DIR = socketPaths.getSocketDir();
+
+/** Check if an ID is a known cluster by looking up clusters.json. */
+function isKnownCluster(id: string): boolean {
+  try {
+    const clusters = readClustersFileSync(ZEROSHOT_DIR);
+    return typeof clusters === 'object' && clusters !== null && id in clusters;
+  } catch {
+    return false;
+  }
+}
+
+/** Ensure socket directory exists. */
+function ensureSocketDir(): void {
+  socketPaths.ensureSocketDir();
+}
+
+/** Get socket path for a task. */
+function getTaskSocketPath(taskId: string): string {
+  return socketPaths.getTaskSocketPath(taskId);
+}
+
+/** Get socket path for a cluster agent. */
+function getAgentSocketPath(clusterId: string, agentId: string): string {
+  return socketPaths.getAgentSocketPath(clusterId, agentId);
+}
+
+/** Get socket path for any ID, auto-detecting task versus cluster. */
+function getSocketPath(id: string, agentId: string | null = null): string {
+  if (id.startsWith('task-')) {
+    return getTaskSocketPath(id);
+  }
+  // Check for explicit 'cluster-' prefix OR known cluster in registry
+  // Cluster IDs are generated without prefix (e.g., 'steady-pulse-42')
+  if (id.startsWith('cluster-') || isKnownCluster(id)) {
+    if (agentId) {
+      return getAgentSocketPath(id, agentId);
+    }
+    // Cluster-level socket (future use)
+    return socketPaths.getClusterSocketPath(id);
+  }
+  // Unknown format, treat as task
+  return getTaskSocketPath(id);
+}
+
+/** Check if a socket exists and is connectable. */
+function isSocketAlive(socketPath: string): Promise<boolean> {
+  if (!fs.existsSync(socketPath)) {
+    return Promise.resolve(false);
+  }
+
+  return new Promise((resolve) => {
+    const socket = net.createConnection(socketPath);
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, 1000);
+
+    socket.on('connect', () => {
+      clearTimeout(timeout);
+      socket.end();
+      resolve(true);
+    });
+
+    socket.on('error', () => {
+      clearTimeout(timeout);
+      resolve(false);
+    });
+  });
+}
+
+/** Remove a stale socket file if it is not connectable. */
+async function cleanupStaleSocket(socketPath: string): Promise<boolean> {
+  if (!fs.existsSync(socketPath)) {
+    return false;
+  }
+
+  const alive = await isSocketAlive(socketPath);
+  if (!alive) {
+    try {
+      fs.unlinkSync(socketPath);
+      return true;
+    } catch {
+      // Ignore errors (file may have been removed already)
+    }
+  }
+  return false;
+}
+
+/** List task IDs with live sockets. */
+async function listAttachableTasks(): Promise<string[]> {
+  ensureSocketDir();
+  const entries = fs.readdirSync(SOCKET_DIR, { withFileTypes: true });
+  const tasks: string[] = [];
+
+  for (const entry of entries) {
+    // Check socket files (Unix sockets report isSocket(), not isFile())
+    // Also accept regular files for compatibility
+    const isSocketFile = (entry.isSocket() || entry.isFile()) && entry.name.endsWith('.sock');
+    if (isSocketFile && !entry.isDirectory()) {
+      const id = entry.name.slice(0, -5); // Remove .sock
+
+      // Skip cluster-level sockets (cluster-xxx.sock)
+      if (id.startsWith('cluster-')) {
+        continue;
+      }
+
+      const socketPath = path.join(SOCKET_DIR, entry.name);
+      if (await isSocketAlive(socketPath)) {
+        tasks.push(id);
+      }
+    }
+  }
+
+  return tasks;
+}
+
+/** List agent IDs with live sockets for a cluster. */
+async function listAttachableAgents(clusterId: string): Promise<string[]> {
+  const clusterDir = path.join(SOCKET_DIR, clusterId);
+  if (!fs.existsSync(clusterDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(clusterDir);
+  const agents: string[] = [];
+
+  for (const file of files) {
+    if (file.endsWith('.sock')) {
+      const agentId = file.slice(0, -5); // Remove .sock
+      const socketPath = path.join(clusterDir, file);
+      if (await isSocketAlive(socketPath)) {
+        agents.push(agentId);
+      }
+    }
+  }
+
+  return agents;
+}
+
+/** List cluster IDs with at least one live agent socket. */
+async function listAttachableClusters(): Promise<string[]> {
+  ensureSocketDir();
+  const entries = fs.readdirSync(SOCKET_DIR, { withFileTypes: true });
+  const clusters: string[] = [];
+
+  // Check socket directories (both 'cluster-' prefix and plain cluster IDs)
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // Accept directories with 'cluster-' prefix OR that are known clusters
+      if (entry.name.startsWith('cluster-') || isKnownCluster(entry.name)) {
+        const agents = await listAttachableAgents(entry.name);
+        if (agents.length > 0) {
+          clusters.push(entry.name);
+        }
+      }
+    }
+  }
+
+  return clusters;
+}
+
+/** Cleanup all sockets for a cluster when it stops. */
+function cleanupClusterSockets(clusterId: string): void {
+  const clusterDir = path.join(SOCKET_DIR, clusterId);
+  if (fs.existsSync(clusterDir)) {
+    const files = fs.readdirSync(clusterDir);
+    for (const file of files) {
+      try {
+        fs.unlinkSync(path.join(clusterDir, file));
+      } catch {
+        // Ignore
+      }
+    }
+    try {
+      fs.rmdirSync(clusterDir);
+    } catch {
+      // Ignore
+    }
+  }
+}
+
+export = {
+  ZEROSHOT_DIR,
+  SOCKET_DIR,
+  ensureSocketDir,
+  getTaskSocketPath,
+  getAgentSocketPath,
+  getSocketPath,
+  isSocketAlive,
+  cleanupStaleSocket,
+  listAttachableTasks,
+  listAttachableAgents,
+  listAttachableClusters,
+  cleanupClusterSockets,
+  isKnownCluster,
+};

package/src/attach/socket-paths.js

@@ -1,85 +1,66 @@
-/**
- * Deterministic attach socket paths.
- *
- * Unix-domain sockets have a small path budget (104 bytes on macOS). Keep the
- * live socket namespace independent from HOME while retaining one namespace
- * per OS user and Zeroshot home.
- */
-
-const crypto = require('crypto');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
+"use strict";
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 const SOCKET_ROOT = process.platform === 'win32' ? null : '/tmp';
 const SOCKET_DIR_MODE = 0o700;
-
 function shortHash(value) {
-  return crypto.createHash('sha256').update(value).digest('hex').slice(0, 16);
+    return crypto.createHash('sha256').update(value).digest('hex').slice(0, 16);
 }
-
 function userNamespace() {
-  if (typeof process.getuid === 'function') {
-    return String(process.getuid());
-  }
-  return shortHash(os.userInfo().username);
+    if (typeof process.getuid === 'function') {
+        return String(process.getuid());
+    }
+    return shortHash(os.userInfo().username);
 }
-
 function resolveHomeDir(env = process.env) {
-  return env.ZEROSHOT_HOME || env.HOME || env.USERPROFILE || os.homedir();
+    return env.ZEROSHOT_HOME || env.HOME || env.USERPROFILE || os.homedir();
 }
-
 function getSocketDir(homeDir = resolveHomeDir()) {
-  if (process.platform === 'win32') {
-    return path.join(homeDir, '.zeroshot', 'sockets');
-  }
-  return path.join(SOCKET_ROOT, `zeroshot-${userNamespace()}-${shortHash(homeDir)}`);
+    if (SOCKET_ROOT === null) {
+        return path.join(homeDir, '.zeroshot', 'sockets');
+    }
+    return path.join(SOCKET_ROOT, `zeroshot-${userNamespace()}-${shortHash(homeDir)}`);
 }
-
 function assertSafeSocketDir(socketDir) {
-  const stat = fs.lstatSync(socketDir);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) {
-    throw new Error(`Attach socket path is not a directory: ${socketDir}`);
-  }
-  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
-    throw new Error(`Attach socket directory is not owned by the current user: ${socketDir}`);
-  }
+    const stat = fs.lstatSync(socketDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Attach socket path is not a directory: ${socketDir}`);
+    }
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+        throw new Error(`Attach socket directory is not owned by the current user: ${socketDir}`);
+    }
 }
-
 function ensureOwnedDirectory(socketDir) {
-  fs.mkdirSync(socketDir, { recursive: true, mode: SOCKET_DIR_MODE });
-  assertSafeSocketDir(socketDir);
-  if (process.platform !== 'win32') {
-    fs.chmodSync(socketDir, SOCKET_DIR_MODE);
-  }
-  return socketDir;
+    fs.mkdirSync(socketDir, { recursive: true, mode: SOCKET_DIR_MODE });
+    assertSafeSocketDir(socketDir);
+    if (process.platform !== 'win32') {
+        fs.chmodSync(socketDir, SOCKET_DIR_MODE);
+    }
+    return socketDir;
 }
-
 function ensureSocketDir(homeDir = resolveHomeDir()) {
-  const socketDir = getSocketDir(homeDir);
-  return ensureOwnedDirectory(socketDir);
+    const socketDir = getSocketDir(homeDir);
+    return ensureOwnedDirectory(socketDir);
 }
-
 function getTaskSocketPath(taskId, homeDir = resolveHomeDir()) {
-  return path.join(ensureSocketDir(homeDir), `${taskId}.sock`);
+    return path.join(ensureSocketDir(homeDir), `${taskId}.sock`);
 }
-
 function getAgentSocketPath(clusterId, agentId, homeDir = resolveHomeDir()) {
-  const clusterDir = path.join(ensureSocketDir(homeDir), clusterId);
-  ensureOwnedDirectory(clusterDir);
-  return path.join(clusterDir, `${agentId}.sock`);
+    const clusterDir = path.join(ensureSocketDir(homeDir), clusterId);
+    ensureOwnedDirectory(clusterDir);
+    return path.join(clusterDir, `${agentId}.sock`);
 }
-
 function getClusterSocketPath(clusterId, homeDir = resolveHomeDir()) {
-  return path.join(ensureSocketDir(homeDir), `${clusterId}.sock`);
+    return path.join(ensureSocketDir(homeDir), `${clusterId}.sock`);
 }
-
 module.exports = {
-  SOCKET_DIR_MODE,
-  resolveHomeDir,
-  getSocketDir,
-  ensureSocketDir,
-  getTaskSocketPath,
-  getAgentSocketPath,
-  getClusterSocketPath,
+    SOCKET_DIR_MODE,
+    resolveHomeDir,
+    getSocketDir,
+    ensureSocketDir,
+    getTaskSocketPath,
+    getAgentSocketPath,
+    getClusterSocketPath,
 };

package/src/attach/socket-paths.ts

@@ -0,0 +1,81 @@
+import crypto = require('crypto');
+import fs = require('fs');
+import os = require('os');
+import path = require('path');
+
+const SOCKET_ROOT = process.platform === 'win32' ? null : '/tmp';
+const SOCKET_DIR_MODE = 0o700;
+
+function shortHash(value: string): string {
+  return crypto.createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+
+function userNamespace(): string {
+  if (typeof process.getuid === 'function') {
+    return String(process.getuid());
+  }
+  return shortHash(os.userInfo().username);
+}
+
+function resolveHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.ZEROSHOT_HOME || env.HOME || env.USERPROFILE || os.homedir();
+}
+
+function getSocketDir(homeDir = resolveHomeDir()): string {
+  if (SOCKET_ROOT === null) {
+    return path.join(homeDir, '.zeroshot', 'sockets');
+  }
+  return path.join(SOCKET_ROOT, `zeroshot-${userNamespace()}-${shortHash(homeDir)}`);
+}
+
+function assertSafeSocketDir(socketDir: string): void {
+  const stat = fs.lstatSync(socketDir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`Attach socket path is not a directory: ${socketDir}`);
+  }
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw new Error(`Attach socket directory is not owned by the current user: ${socketDir}`);
+  }
+}
+
+function ensureOwnedDirectory(socketDir: string): string {
+  fs.mkdirSync(socketDir, { recursive: true, mode: SOCKET_DIR_MODE });
+  assertSafeSocketDir(socketDir);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(socketDir, SOCKET_DIR_MODE);
+  }
+  return socketDir;
+}
+
+function ensureSocketDir(homeDir = resolveHomeDir()): string {
+  const socketDir = getSocketDir(homeDir);
+  return ensureOwnedDirectory(socketDir);
+}
+
+function getTaskSocketPath(taskId: string, homeDir = resolveHomeDir()): string {
+  return path.join(ensureSocketDir(homeDir), `${taskId}.sock`);
+}
+
+function getAgentSocketPath(
+  clusterId: string,
+  agentId: string,
+  homeDir = resolveHomeDir()
+): string {
+  const clusterDir = path.join(ensureSocketDir(homeDir), clusterId);
+  ensureOwnedDirectory(clusterDir);
+  return path.join(clusterDir, `${agentId}.sock`);
+}
+
+function getClusterSocketPath(clusterId: string, homeDir = resolveHomeDir()): string {
+  return path.join(ensureSocketDir(homeDir), `${clusterId}.sock`);
+}
+
+export = {
+  SOCKET_DIR_MODE,
+  resolveHomeDir,
+  getSocketDir,
+  ensureSocketDir,
+  getTaskSocketPath,
+  getAgentSocketPath,
+  getClusterSocketPath,
+};

package/src/claude-credentials.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Provisions Claude Code credentials into an isolated CLAUDE_CONFIG_DIR.
  *
@@ -6,70 +7,66 @@
  * a Keychain-only (OAuth subscription) login must be materialized to a file or
  * every isolated agent fails auth even though the host is logged in.
  */
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { execSync } = require('./lib/safe-exec');
-
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+function isSafeExecModule(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'execSync' in value &&
+        typeof value.execSync === 'function');
+}
+const safeExecModule = require('./lib/safe-exec');
+if (!isSafeExecModule(safeExecModule)) {
+    throw new TypeError('safe-exec must export execSync');
+}
+const { execSync } = safeExecModule;
 const CREDENTIALS_BASENAME = '.credentials.json';
 const KEYCHAIN_SERVICE = 'Claude Code-credentials';
-
-/**
- * Read the Claude Code OAuth credentials JSON from the macOS Keychain.
- * @returns {string|null} Raw credentials JSON, or null if unavailable/invalid/non-darwin.
- */
+/** Read the Claude Code OAuth credentials JSON from the macOS Keychain. */
 function readKeychainCredentials() {
-  if (os.platform() !== 'darwin') {
-    return null;
-  }
-
-  try {
-    const output = execSync(`security find-generic-password -s "${KEYCHAIN_SERVICE}" -w`, {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 2000,
-    });
-    const trimmed = output.trim();
-    if (!trimmed) {
-      return null;
+    if (os.platform() !== 'darwin') {
+        return null;
+    }
+    try {
+        const output = execSync(`security find-generic-password -s "${KEYCHAIN_SERVICE}" -w`, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        });
+        const trimmed = output.trim();
+        if (!trimmed) {
+            return null;
+        }
+        JSON.parse(trimmed); // reject garbage output that isn't real credentials
+        return trimmed;
+    }
+    catch {
+        return null;
     }
-    JSON.parse(trimmed); // reject garbage output that isn't real credentials
-    return trimmed;
-  } catch {
-    return null;
-  }
 }
-
 /**
  * Copy an existing credentials file into an isolated config dir, or materialize
  * one from the macOS Keychain when no source file exists. Resynced on every call
  * so an expired-then-refreshed OAuth token in the Keychain is picked up per run.
- * @param {{ sourceDir: string, destDir: string }} options
- * @returns {boolean} true if a credentials file was written into destDir
  */
-function provisionClaudeCredentials({ sourceDir, destDir }) {
-  fs.mkdirSync(destDir, { recursive: true });
-
-  const destPath = path.join(destDir, CREDENTIALS_BASENAME);
-  const sourcePath = path.join(sourceDir, CREDENTIALS_BASENAME);
-
-  if (fs.existsSync(sourcePath)) {
-    fs.copyFileSync(sourcePath, destPath);
-    fs.chmodSync(destPath, 0o600);
-    return true;
-  }
-
-  const keychainCredentials = readKeychainCredentials();
-  if (keychainCredentials) {
-    fs.writeFileSync(destPath, keychainCredentials, { mode: 0o600 });
-    return true;
-  }
-
-  return false;
+function provisionClaudeCredentials({ sourceDir, destDir, }) {
+    fs.mkdirSync(destDir, { recursive: true });
+    const destPath = path.join(destDir, CREDENTIALS_BASENAME);
+    const sourcePath = path.join(sourceDir, CREDENTIALS_BASENAME);
+    if (fs.existsSync(sourcePath)) {
+        fs.copyFileSync(sourcePath, destPath);
+        fs.chmodSync(destPath, 0o600);
+        return true;
+    }
+    const keychainCredentials = readKeychainCredentials();
+    if (keychainCredentials) {
+        fs.writeFileSync(destPath, keychainCredentials, { mode: 0o600 });
+        return true;
+    }
+    return false;
 }
-
 module.exports = {
-  readKeychainCredentials,
-  provisionClaudeCredentials,
+    readKeychainCredentials,
+    provisionClaudeCredentials,
 };

package/src/claude-credentials.ts

@@ -0,0 +1,89 @@
+/**
+ * Provisions Claude Code credentials into an isolated CLAUDE_CONFIG_DIR.
+ *
+ * Claude Code only reads the macOS Keychain when using the DEFAULT config dir.
+ * Isolated agent runs (--worktree, --docker) use a custom CLAUDE_CONFIG_DIR, so
+ * a Keychain-only (OAuth subscription) login must be materialized to a file or
+ * every isolated agent fails auth even though the host is logged in.
+ */
+import fs = require('fs');
+import os = require('os');
+import path = require('path');
+interface SafeExecModule {
+  execSync(
+    command: string,
+    options: {
+      encoding: 'utf8';
+      stdio: ['ignore', 'pipe', 'ignore'];
+      timeout: number;
+    }
+  ): string;
+}
+interface ProvisionClaudeCredentialsOptions {
+  sourceDir: string;
+  destDir: string;
+}
+function isSafeExecModule(value: unknown): value is SafeExecModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'execSync' in value &&
+    typeof value.execSync === 'function'
+  );
+}
+const safeExecModule: unknown = require('./lib/safe-exec');
+if (!isSafeExecModule(safeExecModule)) {
+  throw new TypeError('safe-exec must export execSync');
+}
+const { execSync } = safeExecModule;
+const CREDENTIALS_BASENAME = '.credentials.json';
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+/** Read the Claude Code OAuth credentials JSON from the macOS Keychain. */
+function readKeychainCredentials(): string | null {
+  if (os.platform() !== 'darwin') {
+    return null;
+  }
+  try {
+    const output = execSync(`security find-generic-password -s "${KEYCHAIN_SERVICE}" -w`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+    });
+    const trimmed = output.trim();
+    if (!trimmed) {
+      return null;
+    }
+    JSON.parse(trimmed); // reject garbage output that isn't real credentials
+    return trimmed;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Copy an existing credentials file into an isolated config dir, or materialize
+ * one from the macOS Keychain when no source file exists. Resynced on every call
+ * so an expired-then-refreshed OAuth token in the Keychain is picked up per run.
+ */
+function provisionClaudeCredentials({
+  sourceDir,
+  destDir,
+}: ProvisionClaudeCredentialsOptions): boolean {
+  fs.mkdirSync(destDir, { recursive: true });
+  const destPath = path.join(destDir, CREDENTIALS_BASENAME);
+  const sourcePath = path.join(sourceDir, CREDENTIALS_BASENAME);
+  if (fs.existsSync(sourcePath)) {
+    fs.copyFileSync(sourcePath, destPath);
+    fs.chmodSync(destPath, 0o600);
+    return true;
+  }
+  const keychainCredentials = readKeychainCredentials();
+  if (keychainCredentials) {
+    fs.writeFileSync(destPath, keychainCredentials, { mode: 0o600 });
+    return true;
+  }
+  return false;
+}
+export = {
+  readKeychainCredentials,
+  provisionClaudeCredentials,
+};