opensteer 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+- Breaking: CLI runtime routing now uses `--session`/`OPENSTEER_SESSION` instead
+  of `--name`/cwd/active-session fallback.
+- Breaking: non-interactive CLI calls now require explicit runtime identity via
+  `--session`, `OPENSTEER_SESSION`, or `OPENSTEER_CLIENT_ID`.
+- Added `OPENSTEER_CLIENT_ID` support for stable client-scoped default session
+  binding.
+- CLI `--name` is now selector-cache namespace only and no longer controls
+  daemon/browser routing.
+- Added per-session daemon startup locking + stale-lock recovery and ping-based
+  health checks to remove startup races across concurrent commands.
+- Added strict in-daemon request serialization for session commands, while
+  keeping `ping` out of the queue for reliable liveness checks.
 - Breaking: removed legacy `ai` config from `OpensteerConfig`; use top-level `model` instead.
 - Breaking: `OPENSTEER_AI_MODEL` is no longer supported; use `OPENSTEER_MODEL`.
 - Breaking: `OPENSTEER_RUNTIME` is no longer supported; use `OPENSTEER_MODE`.

package/README.md

@@ -20,6 +20,31 @@ npm install opensteer playwright
 pnpm add opensteer playwright
 ```
 
+## CLI Session Routing
+
+OpenSteer CLI now separates runtime routing from selector caching:
+
+- Runtime routing: `--session` or `OPENSTEER_SESSION`
+- Selector cache namespace: `--name` or `OPENSTEER_NAME` (used on `open`)
+
+If neither `--session` nor `OPENSTEER_SESSION` is set:
+
+- In an interactive terminal, OpenSteer creates/reuses a terminal-scoped default session.
+- In non-interactive environments (agents/CI), it fails fast unless you set
+  `OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
+
+Example:
+
+```bash
+export OPENSTEER_SESSION=agent-a
+opensteer open https://example.com --name product-scraper
+opensteer snapshot
+opensteer click 3
+opensteer status
+```
+
+`opensteer status` reports `resolvedSession`, `sessionSource`, `resolvedName`, and `nameSource`.
+
 ## Quickstart
 
 ```ts

package/bin/opensteer.mjs

@@ -2,10 +2,18 @@
 
 import { createHash } from 'crypto'
 import { spawn } from 'child_process'
-import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'fs'
+import {
+    closeSync,
+    existsSync,
+    openSync,
+    readFileSync,
+    readdirSync,
+    unlinkSync,
+    writeFileSync,
+} from 'fs'
 import { connect } from 'net'
 import { tmpdir } from 'os'
-import { basename, dirname, join } from 'path'
+import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -14,10 +22,16 @@ const SERVER_SCRIPT = join(__dirname, '..', 'dist', 'cli', 'server.js')
 const CONNECT_TIMEOUT = 15000
 const POLL_INTERVAL = 100
 const RESPONSE_TIMEOUT = 120000
+const HEALTH_TIMEOUT = 1500
 const RUNTIME_PREFIX = 'opensteer-'
 const SOCKET_SUFFIX = '.sock'
 const PID_SUFFIX = '.pid'
+const LOCK_SUFFIX = '.lock'
+const CLIENT_BINDING_PREFIX = `${RUNTIME_PREFIX}client-`
+const CLIENT_BINDING_SUFFIX = '.session'
 const CLOSE_ALL_REQUEST = { id: 1, command: 'close', args: {} }
+const PING_REQUEST = { id: 1, command: 'ping', args: {} }
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/
 
 function getVersion() {
     try {
@@ -84,59 +98,162 @@ function sanitizeNamespace(value) {
     return bounded || 'default'
 }
 
-function getActiveNamespacePath() {
-    const hash = createHash('md5').update(process.cwd()).digest('hex').slice(0, 16)
-    return join(tmpdir(), `${RUNTIME_PREFIX}active-${hash}`)
+function isValidSessionId(value) {
+    return SESSION_ID_PATTERN.test(value)
 }
 
-function readActiveNamespace() {
+function validateSessionId(rawValue, label) {
+    const value = String(rawValue ?? '').trim()
+    if (!value) {
+        throw new Error(`${label} cannot be empty.`)
+    }
+    if (!isValidSessionId(value)) {
+        throw new Error(
+            `${label} "${value}" is invalid. Use only letters, numbers, underscores, and hyphens.`
+        )
+    }
+    return value
+}
+
+function resolveName(flags, session) {
+    if (flags.name !== undefined) {
+        if (flags.name === true) {
+            throw new Error('--name requires a namespace value.')
+        }
+        const raw = String(flags.name).trim()
+        if (raw.length > 0) {
+            return { name: sanitizeNamespace(raw), source: 'flag' }
+        }
+    }
+
+    if (
+        typeof process.env.OPENSTEER_NAME === 'string' &&
+        process.env.OPENSTEER_NAME.trim().length > 0
+    ) {
+        return {
+            name: sanitizeNamespace(process.env.OPENSTEER_NAME),
+            source: 'env',
+        }
+    }
+
+    return { name: sanitizeNamespace(session), source: 'session' }
+}
+
+function hashKey(value) {
+    return createHash('sha256').update(value).digest('hex')
+}
+
+function getClientBindingPath(clientKey) {
+    return join(
+        tmpdir(),
+        `${CLIENT_BINDING_PREFIX}${hashKey(clientKey).slice(0, 24)}${CLIENT_BINDING_SUFFIX}`
+    )
+}
+
+function readClientBinding(clientKey) {
+    const bindingPath = getClientBindingPath(clientKey)
+    if (!existsSync(bindingPath)) {
+        return null
+    }
+
     try {
-        const filePath = getActiveNamespacePath()
-        if (!existsSync(filePath)) return null
-        const ns = readFileSync(filePath, 'utf-8').trim()
-        return ns || null
+        const rawSession = readFileSync(bindingPath, 'utf-8').trim()
+        if (!rawSession) {
+            unlinkSync(bindingPath)
+            return null
+        }
+        if (!isValidSessionId(rawSession)) {
+            unlinkSync(bindingPath)
+            return null
+        }
+        return rawSession
     } catch {
         return null
     }
 }
 
-function writeActiveNamespace(namespace) {
+function writeClientBinding(clientKey, session) {
     try {
-        writeFileSync(getActiveNamespacePath(), namespace)
+        writeFileSync(getClientBindingPath(clientKey), session)
     } catch { /* best-effort */ }
 }
 
-function resolveNamespace(flags) {
-    if (flags.name !== undefined && String(flags.name).trim().length > 0) {
-        return { namespace: sanitizeNamespace(String(flags.name)), source: 'flag' }
+function createDefaultSessionId(prefix, clientKey) {
+    return `${prefix}-${hashKey(clientKey).slice(0, 12)}`
+}
+
+function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+function resolveSession(flags) {
+    if (flags.session !== undefined) {
+        if (flags.session === true) {
+            throw new Error('--session requires a session id value.')
+        }
+
+        return {
+            session: validateSessionId(flags.session, 'Session id'),
+            source: 'flag',
+        }
     }
 
     if (
-        typeof process.env.OPENSTEER_NAME === 'string' &&
-        process.env.OPENSTEER_NAME.trim().length > 0
+        typeof process.env.OPENSTEER_SESSION === 'string' &&
+        process.env.OPENSTEER_SESSION.trim().length > 0
     ) {
-        return { namespace: sanitizeNamespace(process.env.OPENSTEER_NAME), source: 'env' }
+        return {
+            session: validateSessionId(
+                process.env.OPENSTEER_SESSION,
+                'OPENSTEER_SESSION'
+            ),
+            source: 'env',
+        }
     }
 
-    const active = readActiveNamespace()
-    if (active && isServerRunning(active)) {
-        return { namespace: active, source: 'active' }
+    if (
+        typeof process.env.OPENSTEER_CLIENT_ID === 'string' &&
+        process.env.OPENSTEER_CLIENT_ID.trim().length > 0
+    ) {
+        const clientId = process.env.OPENSTEER_CLIENT_ID.trim()
+        const clientKey = `client:${process.cwd()}:${clientId}`
+        const bound = readClientBinding(clientKey)
+        if (bound) {
+            return { session: bound, source: 'client_binding' }
+        }
+
+        const created = createDefaultSessionId('client', clientKey)
+        writeClientBinding(clientKey, created)
+        return { session: created, source: 'client_binding' }
     }
 
-    const cwdBase = basename(process.cwd())
-    if (cwdBase && cwdBase !== '.' && cwdBase !== '/') {
-        return { namespace: sanitizeNamespace(cwdBase), source: 'cwd' }
+    if (isInteractiveTerminal()) {
+        const ttyKey = `tty:${process.cwd()}:${process.ppid}`
+        const bound = readClientBinding(ttyKey)
+        if (bound) {
+            return { session: bound, source: 'tty_default' }
+        }
+
+        const created = createDefaultSessionId('tty', ttyKey)
+        writeClientBinding(ttyKey, created)
+        return { session: created, source: 'tty_default' }
     }
 
-    return { namespace: 'default', source: 'default' }
+    throw new Error(
+        'No session resolved for this non-interactive command. Set OPENSTEER_SESSION or OPENSTEER_CLIENT_ID, or pass --session <id>.'
+    )
 }
 
-function getSocketPath(namespace) {
-    return join(tmpdir(), `${RUNTIME_PREFIX}${namespace}${SOCKET_SUFFIX}`)
+function getSocketPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${SOCKET_SUFFIX}`)
 }
 
-function getPidPath(namespace) {
-    return join(tmpdir(), `${RUNTIME_PREFIX}${namespace}${PID_SUFFIX}`)
+function getPidPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${PID_SUFFIX}`)
+}
+
+function getLockPath(session) {
+    return join(tmpdir(), `${RUNTIME_PREFIX}${session}${LOCK_SUFFIX}`)
 }
 
 function buildRequest(command, flags, positional) {
@@ -270,66 +387,36 @@ function isPidAlive(pid) {
     }
 }
 
-function cleanStaleFiles(namespace) {
-    try {
-        unlinkSync(getSocketPath(namespace))
-    } catch { }
-    try {
-        unlinkSync(getPidPath(namespace))
-    } catch { }
-}
+function cleanStaleFiles(session, options = {}) {
+    const removeSocket = options.removeSocket !== false
+    const removePid = options.removePid !== false
 
-function isServerRunning(namespace) {
-    const pidPath = getPidPath(namespace)
-    const pid = readPid(pidPath)
-    if (!pid) {
-        cleanStaleFiles(namespace)
-        return false
+    if (removeSocket) {
+        try {
+            unlinkSync(getSocketPath(session))
+        } catch { }
     }
 
-    if (!isPidAlive(pid)) {
-        cleanStaleFiles(namespace)
-        return false
+    if (removePid) {
+        try {
+            unlinkSync(getPidPath(session))
+        } catch { }
     }
-
-    return existsSync(getSocketPath(namespace))
 }
 
-function startServer(namespace) {
+function startServer(session) {
     const child = spawn('node', [SERVER_SCRIPT], {
         detached: true,
         stdio: ['ignore', 'ignore', 'ignore'],
         env: {
             ...process.env,
-            OPENSTEER_NAME: namespace,
+            OPENSTEER_SESSION: session,
         },
     })
     child.unref()
 }
 
-function waitForSocket(socketPath, timeout) {
-    return new Promise((resolve, reject) => {
-        const start = Date.now()
-
-        function poll() {
-            if (Date.now() - start > timeout) {
-                reject(new Error('Timed out waiting for server to start'))
-                return
-            }
-
-            if (existsSync(socketPath)) {
-                resolve()
-                return
-            }
-
-            setTimeout(poll, POLL_INTERVAL)
-        }
-
-        poll()
-    })
-}
-
-function sendCommand(socketPath, request) {
+function sendCommand(socketPath, request, timeoutMs = RESPONSE_TIMEOUT) {
     return new Promise((resolve, reject) => {
         const socket = connect(socketPath)
         let buffer = ''
@@ -341,7 +428,7 @@ function sendCommand(socketPath, request) {
                 socket.destroy()
                 reject(new Error('Response timeout'))
             }
-        }, RESPONSE_TIMEOUT)
+        }, timeoutMs)
 
         socket.on('connect', () => {
             socket.write(JSON.stringify(request) + '\n')
@@ -381,6 +468,166 @@ function sendCommand(socketPath, request) {
     })
 }
 
+async function pingServer(session) {
+    const socketPath = getSocketPath(session)
+    if (!existsSync(socketPath)) return false
+
+    try {
+        const response = await sendCommand(socketPath, PING_REQUEST, HEALTH_TIMEOUT)
+        return Boolean(response?.ok && response?.result?.pong)
+    } catch {
+        return false
+    }
+}
+
+async function isServerHealthy(session) {
+    const pid = readPid(getPidPath(session))
+    const pidAlive = pid ? isPidAlive(pid) : false
+    const socketExists = existsSync(getSocketPath(session))
+
+    if (pid && !pidAlive) {
+        cleanStaleFiles(session)
+        return false
+    }
+
+    if (!socketExists) {
+        return false
+    }
+
+    const healthy = await pingServer(session)
+    if (healthy) {
+        return true
+    }
+
+    if (!pid) {
+        cleanStaleFiles(session, { removeSocket: true, removePid: false })
+    }
+
+    return false
+}
+
+function acquireStartLock(session) {
+    const lockPath = getLockPath(session)
+
+    try {
+        const fd = openSync(lockPath, 'wx')
+        writeFileSync(
+            fd,
+            JSON.stringify({
+                pid: process.pid,
+                createdAt: Date.now(),
+            })
+        )
+        closeSync(fd)
+        return true
+    } catch {
+        return false
+    }
+}
+
+function releaseStartLock(session) {
+    try {
+        unlinkSync(getLockPath(session))
+    } catch { /* best-effort */ }
+}
+
+function recoverStaleStartLock(session) {
+    const lockPath = getLockPath(session)
+    if (!existsSync(lockPath)) {
+        return false
+    }
+
+    try {
+        const raw = readFileSync(lockPath, 'utf-8')
+        const parsed = JSON.parse(raw)
+        const pid =
+            parsed && Number.isInteger(parsed.pid) && parsed.pid > 0
+                ? parsed.pid
+                : null
+
+        if (!pid || !isPidAlive(pid)) {
+            unlinkSync(lockPath)
+            return true
+        }
+
+        return false
+    } catch {
+        try {
+            unlinkSync(lockPath)
+            return true
+        } catch {
+            return false
+        }
+    }
+}
+
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function waitForServerReady(session, timeout) {
+    const start = Date.now()
+
+    while (Date.now() - start <= timeout) {
+        if (await isServerHealthy(session)) {
+            return
+        }
+        await sleep(POLL_INTERVAL)
+    }
+
+    throw new Error(`Timed out waiting for server '${session}' to become healthy.`)
+}
+
+async function ensureServer(session) {
+    if (await isServerHealthy(session)) {
+        return
+    }
+
+    if (!existsSync(SERVER_SCRIPT)) {
+        throw new Error(
+            `Server script not found: ${SERVER_SCRIPT}. Run the build script first.`
+        )
+    }
+
+    const deadline = Date.now() + CONNECT_TIMEOUT
+
+    while (Date.now() < deadline) {
+        if (await isServerHealthy(session)) {
+            return
+        }
+
+        const existingPid = readPid(getPidPath(session))
+        if (existingPid && isPidAlive(existingPid)) {
+            await sleep(POLL_INTERVAL)
+            continue
+        }
+
+        recoverStaleStartLock(session)
+
+        if (acquireStartLock(session)) {
+            try {
+                if (!(await isServerHealthy(session))) {
+                    startServer(session)
+                }
+
+                await waitForServerReady(
+                    session,
+                    Math.max(500, deadline - Date.now())
+                )
+                return
+            } finally {
+                releaseStartLock(session)
+            }
+        }
+
+        await sleep(POLL_INTERVAL)
+    }
+
+    throw new Error(
+        `Failed to start server for session '${session}'. Check that the build is complete.`
+    )
+}
+
 function listSessions() {
     const sessions = []
     const entries = readdirSync(tmpdir())
@@ -465,11 +712,11 @@ Navigation:
   forward                   Go forward
   reload                    Reload page
   close                     Close browser and server
-  close --all               Close all active namespace-scoped servers
+  close --all               Close all active session-scoped servers
 
 Sessions:
-  sessions                  List active namespace-scoped sessions
-  status                    Show resolved namespace and session state
+  sessions                  List active session-scoped daemons
+  status                    Show resolved session/name and session state
 
 Observation:
   snapshot [--mode action]  Get page snapshot
@@ -515,7 +762,8 @@ Utility:
   extract <schema-json>     Extract structured data
 
 Global Flags:
-  --name <namespace>        Session namespace (default: CWD basename or OPENSTEER_NAME)
+  --session <id>            Runtime session id for daemon/browser routing
+  --name <namespace>        Selector namespace for cache storage on 'open'
   --headless                Launch browser in headless mode
   --connect-url <url>       Connect to a running browser (e.g. http://localhost:9222)
   --channel <browser>       Use installed browser (chrome, chrome-beta, msedge)
@@ -527,7 +775,9 @@ Global Flags:
   --version, -v             Show version
 
 Environment:
-  OPENSTEER_NAME            Default session namespace when --name is omitted
+  OPENSTEER_SESSION         Runtime session id (equivalent to --session)
+  OPENSTEER_CLIENT_ID       Stable client identity for default session binding
+  OPENSTEER_NAME            Default selector namespace for 'open' when --name is omitted
   OPENSTEER_MODE            Runtime mode: "local" (default) or "remote"
   OPENSTEER_API_KEY         Required when remote mode is selected
   OPENSTEER_BASE_URL        Override remote control-plane base URL
@@ -536,26 +786,12 @@ Environment:
 
 async function main() {
     const { command, flags, positional } = parseArgs(process.argv)
-    const { namespace, source: namespaceSource } = resolveNamespace(flags)
-    const socketPath = getSocketPath(namespace)
 
     if (command === 'sessions') {
         output({ ok: true, sessions: listSessions() })
         return
     }
 
-    if (command === 'status') {
-        output({
-            ok: true,
-            namespace,
-            namespaceSource,
-            serverRunning: isServerRunning(namespace),
-            socketPath,
-            sessions: listSessions(),
-        })
-        return
-    }
-
     if (command === 'close' && flags.all === true) {
         try {
             const closed = await closeAllSessions()
@@ -566,36 +802,66 @@ async function main() {
         return
     }
 
+    let resolvedSession
+    let resolvedName
+    try {
+        resolvedSession = resolveSession(flags)
+        resolvedName = resolveName(flags, resolvedSession.session)
+    } catch (err) {
+        error(err instanceof Error ? err.message : 'Failed to resolve session')
+    }
+
+    const session = resolvedSession.session
+    const sessionSource = resolvedSession.source
+    const name = resolvedName.name
+    const nameSource = resolvedName.source
+    const socketPath = getSocketPath(session)
+
+    if (command === 'status') {
+        output({
+            ok: true,
+            resolvedSession: session,
+            sessionSource,
+            resolvedName: name,
+            nameSource,
+            serverRunning: await isServerHealthy(session),
+            socketPath,
+            sessions: listSessions(),
+        })
+        return
+    }
+
     delete flags.name
+    delete flags.session
     delete flags.all
+
     const request = buildRequest(command, flags, positional)
+    if (command === 'open') {
+        request.args.name = name
+    }
 
-    if (!isServerRunning(namespace)) {
+    if (!(await isServerHealthy(session))) {
         if (command !== 'open') {
             error(
-                `No server running for namespace '${namespace}' (resolved from ${namespaceSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
+                `No server running for session '${session}' (resolved from ${sessionSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
             )
         }
-        if (!existsSync(SERVER_SCRIPT)) {
+
+        try {
+            await ensureServer(session)
+        } catch (err) {
             error(
-                `Server script not found: ${SERVER_SCRIPT}. Run the build script first.`
+                err instanceof Error
+                    ? err.message
+                    : 'Failed to start server. Check that the build is complete.'
             )
         }
-        startServer(namespace)
-        try {
-            await waitForSocket(socketPath, CONNECT_TIMEOUT)
-        } catch {
-            error('Failed to start server. Check that the build is complete.')
-        }
     }
 
     try {
         const response = await sendCommand(socketPath, request)
 
         if (response.ok) {
-            if (command === 'open') {
-                writeActiveNamespace(namespace)
-            }
             output({ ok: true, ...response.result })
         } else {
             process.stderr.write(