spexcode 0.4.3 → 0.5.0

package/spec-cli/src/pi-headless.ts

@@ -0,0 +1,195 @@
+import { createConnection, createServer, type Server, type Socket } from 'node:net'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { DispatchResult, HarnessDeliveryRecord } from './harness.js'
+
+type ControlRequest = { type: 'deliver'; text: string }
+type ChildTurn = { process: ChildProcess; exited: Promise<number | null> }
+
+const PKG = fileURLToPath(new URL('..', import.meta.url))
+const SPEX = join(PKG, 'bin', 'spex.mjs')
+const CONTROL_TIMEOUT_MS = 30_000
+const START_TIMEOUT_MS = 30_000
+
+const shQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+/** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
+export const piHeadlessSock = (id: string) => join(tmpdir(), `spexcode-ph-${id}.sock`)
+
+export function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: string): string {
+  return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].join(' ')
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms)
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value) },
+      (error) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+function controlRequest(id: string, request: ControlRequest): Promise<DispatchResult> {
+  return new Promise((resolve) => {
+    let socket: Socket | undefined
+    let settled = false
+    let buffer = ''
+    const finish = (result: DispatchResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      socket?.destroy()
+      resolve(result)
+    }
+    const timer = setTimeout(() => finish({ ok: false, error: `pi-headless control timed out for session ${id}` }), CONTROL_TIMEOUT_MS)
+    try { socket = createConnection(piHeadlessSock(id)) } catch (error) {
+      finish({ ok: false, error: `pi-headless controller connect failed for session ${id}: ${(error as Error).message}` })
+      return
+    }
+    socket.setEncoding('utf8')
+    socket.on('connect', () => socket!.write(`${JSON.stringify(request)}\n`))
+    socket.on('data', (chunk) => {
+      buffer += chunk
+      const nl = buffer.indexOf('\n')
+      if (nl < 0) return
+      try {
+        const response = JSON.parse(buffer.slice(0, nl)) as DispatchResult
+        finish(response.ok ? { ok: true } : { ok: false, error: response.error || 'pi-headless controller rejected the request' })
+      } catch (error) {
+        finish({ ok: false, error: `pi-headless returned an invalid control response: ${(error as Error).message}` })
+      }
+    })
+    socket.on('error', (error) => finish({ ok: false, error: `pi-headless controller unreachable for session ${id}: ${error.message}` }))
+    socket.on('close', () => finish({ ok: false, error: `pi-headless controller closed before confirming session ${id}` }))
+  })
+}
+
+export const deliverViaPiHeadless = (rec: HarnessDeliveryRecord, text: string) =>
+  controlRequest(rec.session, { type: 'deliver', text })
+
+export class PiHeadlessController {
+  private server: Server | null = null
+  private child: ChildTurn | null = null
+  private controlQueue: Promise<void> = Promise.resolve()
+  private closing = false
+  private readonly socketPath: string
+
+  constructor(
+    private readonly id: string,
+    _runtimeDir: string,
+    private readonly piCmd: string,
+    private readonly cwd = process.cwd(),
+  ) {
+    this.socketPath = piHeadlessSock(id)
+  }
+
+  async start(initialPrompt?: string): Promise<void> {
+    try { rmSync(this.socketPath, { force: true }) } catch { /* stale control socket is replaced at startup */ }
+    this.server = createServer((socket) => this.accept(socket))
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error) => { this.server?.off('listening', onListening); reject(error) }
+      const onListening = () => { this.server?.off('error', onError); resolve() }
+      this.server!.once('error', onError)
+      this.server!.once('listening', onListening)
+      this.server!.listen(this.socketPath)
+    })
+    if (initialPrompt) void this.spawnTurn(initialPrompt, false).catch((error) => {
+      console.error(`[spex pi-headless] initial turn failed: ${(error as Error).message}`)
+    })
+  }
+
+  async close(): Promise<void> {
+    if (this.closing) return
+    this.closing = true
+    const child = this.child
+    if (child && child.process.exitCode === null) child.process.kill('SIGTERM')
+    await new Promise<void>((resolve) => {
+      if (!this.server) return resolve()
+      this.server.close(() => resolve())
+    })
+    try { rmSync(this.socketPath, { force: true }) } catch { /* best-effort cleanup after close */ }
+    const { rvSock } = await import('./harness.js')
+    try { rmSync(rvSock(this.id), { force: true }) } catch { /* pi may already have removed it */ }
+  }
+
+  private accept(socket: Socket): void {
+    socket.setEncoding('utf8')
+    let buffer = ''
+    let handled = false
+    socket.on('data', (chunk) => {
+      if (handled) return
+      buffer += chunk
+      const nl = buffer.indexOf('\n')
+      if (nl < 0) return
+      handled = true
+      let request: ControlRequest
+      try { request = JSON.parse(buffer.slice(0, nl)) as ControlRequest } catch (error) {
+        socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${(error as Error).message}` })}\n`)
+        return
+      }
+      this.controlQueue = this.controlQueue.then(async () => {
+        const result = await this.handle(request).catch((error) => ({ ok: false, error: (error as Error).message }))
+        socket.end(`${JSON.stringify(result)}\n`)
+      })
+    })
+  }
+
+  private async handle(request: ControlRequest): Promise<DispatchResult> {
+    if (request.type !== 'deliver') return { ok: false, error: 'unknown pi-headless control request' }
+    if (!request.text) return { ok: false, error: 'empty prompt - nothing to deliver' }
+
+    // A live extension listener is an in-flight pi turn. The native steer path is parse-confirmed by the
+    // shared rendezvous protocol. Only a proven absent listener may cold-wake a saved session.
+    const { deliverViaRendezvous, rendezvousListening } = await import('./harness.js')
+    const listener = await rendezvousListening(this.id)
+    if (listener === 'live') return deliverViaRendezvous(this.id, request.text)
+    if (listener === 'unproven') return { ok: false, error: `could not determine whether pi turn ${this.id} is live — prompt NOT delivered` }
+
+    if (this.child) await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`)
+    await this.spawnTurn(request.text, true)
+    return { ok: true }
+  }
+
+  private async spawnTurn(text: string, resume: boolean): Promise<void> {
+    if (this.closing) throw new Error('pi-headless controller is closing')
+    const mode = resume ? ['--session', this.id] : ['--session-id', this.id]
+    // Keep pi's default text mode. `--mode json` is intentionally omitted: it can hang in this runtime.
+    const args = ['-p', ...mode, text]
+    const command = `exec ${this.piCmd} ${args.map(shQuote).join(' ')}`
+    const childProcess = spawn('/bin/sh', ['-lc', command], { cwd: this.cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })
+    let resolveExit!: (code: number | null) => void
+    const exited = new Promise<number | null>((resolve) => { resolveExit = resolve })
+    const turn: ChildTurn = { process: childProcess, exited }
+    this.child = turn
+    childProcess.stdout?.pipe(process.stdout)
+    childProcess.stderr?.pipe(process.stderr)
+    childProcess.once('error', (error) => console.error(`[spex pi-headless] child spawn failed: ${error.message}`))
+    childProcess.once('close', (code) => {
+      if (this.child === turn) this.child = null
+      resolveExit(code)
+    })
+    await withTimeout(new Promise<void>((resolve, reject) => {
+      childProcess.once('spawn', () => resolve())
+      childProcess.once('error', reject)
+    }), START_TIMEOUT_MS, `pi-headless child did not start for session ${this.id}`)
+  }
+}
+
+export async function runPiHeadlessController(id: string, runtimeDir: string, piCmd: string, tail: string[]): Promise<void> {
+  // runtimeDir is retained in the command shape for parity with claude-headless and future per-session output.
+  mkdirSync(join(runtimeDir, 'sessions', id), { recursive: true })
+  const controller = new PiHeadlessController(id, runtimeDir, piCmd)
+  const resume = tail[0] === '--session'
+  const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ')
+  await controller.start(prompt)
+  await new Promise<void>((resolve) => {
+    const stop = () => void controller.close().finally(resolve)
+    process.once('SIGINT', stop)
+    process.once('SIGTERM', stop)
+    process.once('SIGHUP', stop)
+  })
+}

package/spec-cli/src/sessions.ts

@@ -117,6 +117,7 @@ export type Session = {
   raw: { name: string | null; title: string | null }   // the bare parts, for explicit consumers only (rename prefill)
   parent: string | null   // the SPAWNING session's id ([[session-nesting]]) — set once at creation when `spex session new` ran inside another session, else null; the frontend folds a child under it at read time
   harness: string   // which harness (claude|codex) runs this session — carried so liveness/occupancy route through its adapter
+  capabilities: { headless: boolean; messageStream: boolean }   // stable adapter projection; console surfaces consume data, never harness ids
   launcher: string | null   // the launcher profile this session launched under ([[launcher-select]]); null only for old records predating launchers
   lifecycle: Lifecycle; proposal: Proposal | null; merges: number; status: DisplayStatus; liveness: Liveness; note: string | null
   prompt: string | null; promptPreview: string | null; created: number; activity: string | null
@@ -565,13 +566,13 @@ const LAUNCH_FAST_FAIL_S = 12 // launchScript retries the agent command when it
 // for the grace window; only past it (still not online) is it genuinely 'offline'.
 export function liveness(rec: SessRec, snap: LiveSnap): Liveness {
   if (!rec.session) return 'offline'
-  if (snap.probeFailed) return 'unknown'   // the probe failed — we can't tell, and MUST NOT guess offline
   // Ask the resolved ADAPTER ([[harness-adapter]]): claude/pi/opencode prove their rendezvous listener;
   // codex proves its launch-registered pid (with the legacy descendant-tree fallback). The 'starting' grace
   // stays here: a just-launched agent whose online signal has not appeared yet reads 'starting', only past it
   // 'offline'.
   const h = harnessById(rec.harness || defaultHarness.id)
   if (h.liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online') return 'online'
+  if (snap.probeFailed) return 'unknown'   // the probe failed — we can't tell, and MUST NOT guess offline
   // not provably online — but if this session's LISTENER probe couldn't conclude (timeout under load / EAGAIN
   // off a full-but-alive backlog), death is UNPROVEN: `unknown`, never a false `offline` a supervisor would
   // act on (issue #40 — a wedged-but-alive worker must not read as an actionable corpse).
@@ -611,7 +612,8 @@ export function toSession(rec: SessRec, status: DisplayStatus, lv: Liveness, act
   const act = showActivity ? activity : null
   const pp = prompt ? promptPreview(prompt) : null
   const parts = { id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch, activity: act, promptPreview: pp }
-  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), headline: deriveHeadline(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: rec.harness, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
+  const harness = harnessById(rec.harness || defaultHarness.id)
+  return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), headline: deriveHeadline(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: harness.id, capabilities: { headless: harness.headless, messageStream: harness.messageStream }, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey }
 }
 
 // @@@ renameSession - set (or clear) a session's human display NAME: the user-chosen override that wins
@@ -1341,9 +1343,12 @@ export async function newSession(prompt: string, parent: string | null = null, l
   writeLaunchFile(id, launchPrompt)     // park the exact launch prompt for the drainer (consumed at launch)
   await drainQueue()                    // launch now if under the cap, else leave it queued for a free slot
   const after = readRecord(id) ?? rec   // 'active' if the drain launched it, else still 'queued'
-  // queued → no process yet (offline liveness); just-launched → its socket is still booting (starting).
+  // Every adapter answers from its own truth. Asking with no process facts distinguishes a record-backed
+  // adapter (online immediately) from process-backed queued/booting adapters (offline/starting) without an
+  // extra whole-box tmux snapshot on the creation hot path.
+  const recordOnline = h.liveness(after, false, runtimeRoot()) === 'online'
   const queued = after.status === 'queued'
-  return toSession(after, queued ? 'queued' : 'working', queued ? 'offline' : 'starting')
+  return toSession(after, queued ? 'queued' : 'working', recordOnline ? 'online' : queued ? 'offline' : 'starting')
 }
 
 // @@@ bootstrapMaterialize - the creation-time materialize is BOOTSTRAP, not best-effort: it is what writes
@@ -1645,14 +1650,13 @@ export async function mergeSession(id: string): Promise<{ dispatched: boolean; r
 
 // @@@ stopAgentProcess - the shared teardown both stop and close begin with, so there is ONE kill path, not
 // two: kill the agent's tmux client, drop its boot-window stamp (else a just-launched id lingers in the grace
-// window reading `starting` instead of `offline`), and sweep its rendezvous socket. The socket lives in the OS
-// tmpdir (NOT the worktree), so worktree removal alone would leave it behind — closing many sessions over time
-// would accumulate stale `spexcode-rv-*.sock` files; we unlink it here (force = no error if claude/OS already
-// removed it). Deliberately does NOT drainQueue — the caller drains once, after it has settled the worktree.
+// window reading `starting` instead of `offline`), and ask the resolved adapter to sweep its ephemeral runtime
+// transport. Deliberately does NOT drainQueue — the caller drains once, after it has settled the worktree.
 async function stopAgentProcess(id: string): Promise<void> {
+  const rec = readRecord(id)
   await tmuxOk(['kill-session', '-t', id])
   launchedAt.delete(id)
-  try { rmSync(rvSock(id), { force: true }) } catch { /* best-effort sweep; tmpdir socket, claude/OS may already be gone */ }
+  harnessById(rec?.harness || defaultHarness.id).cleanupRuntime(rec ?? { session: id })
 }
 
 // @@@ stopSession - the SOFT stop (vs closeSession's removal): stops the agent process but LEAVES the durable
@@ -2008,6 +2012,16 @@ export async function sendText(id: string, text: string, from?: string, opts: {
   return r
 }
 
+// Hard interrupt is adapter-native control, distinct from stop's process teardown. A harness without a
+// confirmed native primitive refuses loudly; there is no signal/PTY fallback that could target the wrong turn.
+export async function interruptSession(id: string): Promise<DispatchResult> {
+  const rec = readRecord(id)
+  if (!rec) return { ok: false, error: `no session record for ${id} - nothing to interrupt` }
+  const h = harnessById(rec.harness || defaultHarness.id)
+  if (!h.interrupt) return { ok: false, error: `harness ${h.id} has no native hard-interrupt control` }
+  return h.interrupt({ ...rec, runtimeDir: runtimeRoot() })
+}
+
 // @@@ rawKey - the RAW-KEYSTROKE nav path, kept DELIBERATELY on `tmux send-keys` and NEVER the rendezvous
 // socket. Two channels, two jobs: the socket INJECTS a whole prompt (text + submit), which can drive the
 // agent's normal prompt but CANNOT navigate an interactive TUI select menu (e.g. `/model`'s list — ↑/↓ to

package/spec-cli/templates/spexcode.json

@@ -2,12 +2,18 @@
   "lint": {
     "governedRoots": ["."]
   },
+  "dashboard": {
+    "showHeadlessLaunchers": false
+  },
   "sessions": {
     "launchers": {
       "claude": { "harness": "claude", "cmd": "claude" },
+      "claude-headless": { "harness": "claude-headless", "cmd": "claude" },
       "codex": { "harness": "codex", "cmd": "codex" },
       "opencode": { "harness": "opencode", "cmd": "opencode" },
-      "pi": { "harness": "pi", "cmd": "pi" }
+      "opencode-headless": { "harness": "opencode-headless", "cmd": "opencode --auto" },
+      "pi": { "harness": "pi", "cmd": "pi" },
+      "pi-headless": { "harness": "pi-headless", "cmd": "pi" }
     },
     "defaultLauncher": "claude"
   }