conductor-remote 0.0.0-development

package/src/sidecar.ts

@@ -0,0 +1,194 @@
+import { randomUUID } from 'node:crypto'
+import fs from 'node:fs'
+import net from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * Client for Conductor's sidecar IPC — the `conductor-runtime sidecar` process
+ * that owns every live `claude`/`codex` agent. The desktop app drives it over a
+ * unix socket speaking newline-delimited JSON-RPC 2.0; we speak the same
+ * protocol as an additional local client.
+ *
+ * This is by far the most precise write path: prompts are addressed by
+ * `sessionId`, so there is no window focus or AppleScript involved and the app's
+ * UI updates correctly because it's the real dispatch path. It is also the most
+ * update-fragile surface (a private, versioned IPC), which is why it lives
+ * behind the Actuator interface and falls back to AppleScript when the socket
+ * can't be reached (see writes.ts).
+ *
+ * Reverse-engineered from conductor-runtime (Conductor 0.76):
+ *   - socket:      `$TMPDIR/conductor-sidecar-v2-<sidecarPid>.sock`
+ *   - transport:   newline-delimited JSON-RPC 2.0 (`{jsonrpc,id,method,params}`)
+ *   - local auth:  the literal `{ userId: 'local', auth: 'local' }`
+ *   - send prompt: method `query`, params `{ type: 'sendUserMessageRequest', … }`
+ *   - safe read:   method `contextUsage`, params `{ sessionId, …auth }`
+ *
+ * Stale socket files from exited sidecars linger in `$TMPDIR`, so discovery is
+ * connectivity-based: we try candidates newest-first and use the first that
+ * actually accepts a connection.
+ */
+
+const SOCKET_PREFIX = 'conductor-sidecar-v2-'
+const LOCAL_AUTH = { userId: 'local', auth: 'local' } as const
+
+/** Candidate sidecar socket paths in `$TMPDIR`, newest mtime first. */
+function listSidecarSockets(): string[] {
+	const dir = os.tmpdir()
+	let names: string[]
+	try {
+		names = fs.readdirSync(dir)
+	} catch {
+		return []
+	}
+	const found: { p: string; m: number }[] = []
+	for (const name of names) {
+		if (!(name.startsWith(SOCKET_PREFIX) && name.endsWith('.sock'))) continue
+		const p = path.join(dir, name)
+		try {
+			const st = fs.statSync(p)
+			if (st.isSocket()) found.push({ p, m: st.mtimeMs })
+		} catch {
+			// vanished between readdir and stat — skip
+		}
+	}
+	return found.sort((a, b) => b.m - a.m).map(x => x.p)
+}
+
+function isConnRefused(err: unknown): boolean {
+	const code = (err as { code?: string })?.code
+	return code === 'ECONNREFUSED' || code === 'ENOENT'
+}
+
+interface RpcMessage {
+	id?: unknown
+	result?: unknown
+	error?: { code: number; message: string }
+}
+
+/** One JSON-RPC request/response over a fresh connection to a specific socket. */
+function rpcOnSocket(
+	socketPath: string,
+	method: string,
+	params: Record<string, unknown>,
+	timeoutMs: number
+): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		const sock = net.connect(socketPath)
+		const id = 1
+		let buf = ''
+		let settled = false
+		const finish = (err: Error | null, val?: unknown): void => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			sock.destroy()
+			if (err) reject(err)
+			else resolve(val)
+		}
+		const timer = setTimeout(() => finish(new Error(`sidecar RPC "${method}" timed out`)), timeoutMs)
+
+		sock.on('connect', () => {
+			sock.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
+		})
+		sock.on('data', chunk => {
+			buf += chunk.toString('utf8')
+			// The sidecar also pushes unsolicited notifications — ignore anything
+			// that isn't the response to our id.
+			let nl = buf.indexOf('\n')
+			while (nl >= 0) {
+				const line = buf.slice(0, nl).trim()
+				buf = buf.slice(nl + 1)
+				nl = buf.indexOf('\n')
+				if (!line) continue
+				let msg: RpcMessage
+				try {
+					msg = JSON.parse(line) as RpcMessage
+				} catch {
+					continue
+				}
+				if (msg.id === id && ('result' in msg || 'error' in msg)) {
+					if (msg.error) return finish(new Error(msg.error.message || `sidecar RPC error ${msg.error.code}`))
+					return finish(null, msg.result)
+				}
+			}
+		})
+		sock.on('error', e => finish(e instanceof Error ? e : new Error(String(e))))
+		sock.on('close', () => finish(new Error('sidecar closed the connection before responding')))
+	})
+}
+
+/** Try each candidate socket, skipping stale ones (connection refused). */
+async function rpc(method: string, params: Record<string, unknown>, timeoutMs = 8000): Promise<unknown> {
+	const candidates = listSidecarSockets()
+	if (!candidates.length) throw new Error('no Conductor sidecar socket found — is Conductor running?')
+	let lastErr: unknown
+	for (const socketPath of candidates) {
+		try {
+			return await rpcOnSocket(socketPath, method, params, timeoutMs)
+		} catch (err) {
+			lastErr = err
+			if (isConnRefused(err)) continue // stale socket file, try the next
+			throw err // a real RPC/protocol error — surface it, don't mask
+		}
+	}
+	throw lastErr instanceof Error ? lastErr : new Error('sidecar unreachable')
+}
+
+/** Resolve a connectable sidecar socket, or null. Used to decide write strategy. */
+export function sidecarSocket(timeoutMs = 800): Promise<string | null> {
+	const candidates = listSidecarSockets()
+	return (async () => {
+		for (const p of candidates) {
+			const ok = await canConnect(p, timeoutMs)
+			if (ok) return p
+		}
+		return null
+	})()
+}
+
+function canConnect(socketPath: string, timeoutMs: number): Promise<boolean> {
+	return new Promise(resolve => {
+		const sock = net.connect(socketPath)
+		let done = false
+		const finish = (ok: boolean): void => {
+			if (done) return
+			done = true
+			clearTimeout(t)
+			sock.destroy()
+			resolve(ok)
+		}
+		const t = setTimeout(() => finish(false), timeoutMs)
+		sock.on('connect', () => finish(true))
+		sock.on('error', () => finish(false))
+	})
+}
+
+/** True when a precise (sidecar) send path is currently reachable. */
+export async function sidecarAvailable(): Promise<boolean> {
+	return (await sidecarSocket()) !== null
+}
+
+/**
+ * Deliver a prompt to a specific session — the real send path, precisely
+ * targeted. Resolves once the sidecar has accepted (queued/sent) the message.
+ */
+export async function sidecarSendUserMessage(sessionId: string, text: string): Promise<void> {
+	await rpc('query', {
+		type: 'sendUserMessageRequest',
+		...LOCAL_AUTH,
+		sessionId,
+		id: randomUUID(),
+		message: text,
+		agentMessage: text,
+		deliveryMode: 'default'
+	})
+}
+
+/**
+ * Read a session's context usage. Pure read — no turn is triggered — so it's the
+ * safe way to prove the socket + auth + framing work end to end.
+ */
+export function sidecarContextUsage(sessionId: string): Promise<unknown> {
+	return rpc('contextUsage', { ...LOCAL_AUTH, sessionId }, 5000)
+}

package/src/transcript.ts

@@ -0,0 +1,111 @@
+/**
+ * Conductor stores each turn's raw Claude Code SDK stream JSON in
+ * `session_messages.content`. User-typed prompts are stored as plain text.
+ * This turns a row into a compact, phone-renderable entry.
+ */
+
+export interface TranscriptEntry {
+	id: string
+	rowid: number
+	/** Display role: user | assistant | tool | thinking | system */
+	role: 'user' | 'assistant' | 'tool' | 'thinking' | 'system'
+	/** Human-readable text (may be empty for pure tool rows). */
+	text: string
+	/** Tool name when role === 'tool'. */
+	tool?: string
+	ts: string
+	/** True when the message is queued but not yet sent (queue_order set, sent_at null). */
+	queued: boolean
+}
+
+interface RawRow {
+	rowid: number
+	id: string
+	role: string | null
+	content: string | null
+	full_message: string | null
+	created_at: string
+	sent_at: string | null
+	queue_order: number | null
+}
+
+interface SdkBlock {
+	type: string
+	text?: string
+	name?: string
+	input?: unknown
+	content?: unknown
+}
+
+function textFromBlocks(blocks: SdkBlock[]): { text: string; tool?: string } {
+	const parts: string[] = []
+	let tool: string | undefined
+	for (const b of blocks) {
+		if (b.type === 'text' && b.text) parts.push(b.text)
+		else if (b.type === 'thinking' && typeof b.text === 'string') parts.push(b.text)
+		else if (b.type === 'tool_use') {
+			tool = b.name
+			const inputStr = summarizeToolInput(b.input)
+			parts.push(inputStr ? `▸ ${b.name}: ${inputStr}` : `▸ ${b.name}`)
+		} else if (b.type === 'tool_result') {
+			parts.push(summarizeToolResult(b.content))
+		}
+	}
+	return { text: parts.join('\n').trim(), tool }
+}
+
+function summarizeToolInput(input: unknown): string {
+	if (!input || typeof input !== 'object') return ''
+	const o = input as Record<string, unknown>
+	const key = o.command ?? o.file_path ?? o.path ?? o.pattern ?? o.description ?? o.prompt
+	const s = typeof key === 'string' ? key : JSON.stringify(o)
+	return s.length > 140 ? `${s.slice(0, 140)}…` : s
+}
+
+function summarizeToolResult(content: unknown): string {
+	let s = ''
+	if (typeof content === 'string') s = content
+	else if (Array.isArray(content)) {
+		s = content
+			.map(c => (c && typeof c === 'object' && 'text' in c ? String((c as { text: unknown }).text) : ''))
+			.join('')
+	}
+	s = s.trim()
+	if (!s) return '↳ (result)'
+	return `↳ ${s.length > 200 ? `${s.slice(0, 200)}…` : s}`
+}
+
+export function parseMessage(row: RawRow): TranscriptEntry | null {
+	const queued = row.queue_order !== null && row.sent_at === null
+	const base = { id: row.id, rowid: row.rowid, ts: row.created_at, queued }
+	const content = row.content ?? ''
+
+	// Plain user prompt (not SDK JSON).
+	if (!content.startsWith('{')) {
+		if (!content.trim()) return null
+		return { ...base, role: 'user', text: content }
+	}
+
+	let parsed: { type?: string; subtype?: string; message?: { content?: SdkBlock[] } }
+	try {
+		parsed = JSON.parse(content)
+	} catch {
+		return { ...base, role: 'system', text: content.slice(0, 200) }
+	}
+
+	// Skip pure bookkeeping frames (token accounting, etc.).
+	if (parsed.type === 'system' && parsed.subtype === 'thinking_tokens') return null
+	if (parsed.type === 'result') return null
+
+	const blocks = parsed.message?.content
+	if (Array.isArray(blocks)) {
+		const { text, tool } = textFromBlocks(blocks)
+		if (!text) return null
+		if (tool) return { ...base, role: 'tool', text, tool }
+		if (parsed.type === 'user') return { ...base, role: 'user', text }
+		return { ...base, role: 'assistant', text }
+	}
+
+	if (parsed.type === 'system') return null
+	return { ...base, role: 'system', text: content.slice(0, 200) }
+}

package/src/writes.ts

@@ -0,0 +1,133 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { Workspace } from './reads.ts'
+import { sidecarAvailable, sidecarSendUserMessage } from './sidecar.ts'
+
+const exec = promisify(execFile)
+
+export interface SendResult {
+	ok: boolean
+	strategy: string
+	warning?: string
+	error?: string
+}
+
+/** Who to deliver a prompt to. `sessionId` is the precise target; `workspace` carries the worktree + focus context. */
+export interface SendTarget {
+	workspace: Workspace
+	sessionId: string | null
+}
+
+export interface Actuator {
+	readonly name: string
+	/** Human-readable note about this strategy's limits, surfaced in the UI. */
+	readonly caveat: string
+	/** True when delivery is addressed to a specific session (no window-focus dependency). */
+	readonly precise: boolean
+	send: (target: SendTarget, text: string) => Promise<SendResult>
+	/** Runtime availability check (e.g. the sidecar socket must be reachable). */
+	available?: () => Promise<boolean>
+}
+
+/**
+ * The sidecar IPC path — the precise, per-session write. Delivers straight to
+ * `sessionId` over Conductor's own dispatch socket (see sidecar.ts), so it needs
+ * no window focus and the app UI reflects the turn correctly.
+ *
+ * Opt-in (WRITE_STRATEGY=sidecar) because it speaks a private, versioned IPC and
+ * hasn't been validated by an automated live send (that would inject a prompt
+ * into a running agent). It is the intended default once you've confirmed it on
+ * your setup.
+ */
+export class SidecarActuator implements Actuator {
+	readonly name = 'sidecar'
+	readonly caveat =
+		'Delivered straight to the target session over Conductor’s dispatch socket — precise per-workspace targeting.'
+	readonly precise = true
+
+	available(): Promise<boolean> {
+		return sidecarAvailable()
+	}
+
+	async send(target: SendTarget, text: string): Promise<SendResult> {
+		const sessionId = target.sessionId ?? target.workspace.active_session_id
+		if (!sessionId) return { ok: false, strategy: this.name, error: 'no session id to target' }
+		try {
+			await sidecarSendUserMessage(sessionId, text)
+			return { ok: true, strategy: this.name }
+		} catch (err) {
+			return { ok: false, strategy: this.name, error: err instanceof Error ? err.message : String(err) }
+		}
+	}
+}
+
+/**
+ * Drives Conductor's real send path via macOS Accessibility (AppleScript):
+ * activate the app, paste the prompt, press Enter. Uses whatever model /
+ * permission mode the session already has (zero risk of altering the agent),
+ * which is why it's the default. Its one limit is that it lands in the session
+ * Conductor currently has focused — bring the target workspace to front first.
+ */
+export class AppleScriptActuator implements Actuator {
+	readonly name = 'applescript'
+	readonly caveat =
+		'Lands in the session Conductor currently has focused. Bring the target workspace to front first; for precise targeting run with WRITE_STRATEGY=sidecar.'
+	readonly precise = false
+
+	async send(_target: SendTarget, text: string): Promise<SendResult> {
+		// Paste beats keystroke for long/multibyte prompts. We stash the clipboard,
+		// paste, send, and restore.
+		const script = `
+set savedClipboard to the clipboard
+set the clipboard to (do shell script "cat" & " " & quoted form of (system attribute "RELAY_PROMPT_FILE"))
+tell application "Conductor" to activate
+delay 0.35
+tell application "System Events"
+	keystroke "v" using {command down}
+	delay 0.1
+	key code 36
+end tell
+delay 0.1
+set the clipboard to savedClipboard
+`.trim()
+		// Pass the prompt via a temp file + env to avoid AppleScript string escaping.
+		const os = await import('node:os')
+		const fs = await import('node:fs/promises')
+		const path = await import('node:path')
+		const tmp = path.join(os.tmpdir(), `relay-prompt-${process.pid}-${Date.now()}.txt`)
+		await fs.writeFile(tmp, text, 'utf8')
+		try {
+			await exec('osascript', ['-e', script], {
+				env: { ...process.env, RELAY_PROMPT_FILE: tmp },
+				timeout: 10000
+			})
+			return {
+				ok: true,
+				strategy: this.name,
+				warning: 'Delivered to the focused Conductor session — confirm it landed in the intended workspace.'
+			}
+		} catch (err) {
+			return {
+				ok: false,
+				strategy: this.name,
+				error: err instanceof Error ? err.message : String(err)
+			}
+		} finally {
+			await fs.rm(tmp, { force: true }).catch(() => undefined)
+		}
+	}
+}
+
+export type WriteStrategy = 'applescript' | 'sidecar'
+
+export function pickActuator(strategy: WriteStrategy): Actuator {
+	return strategy === 'sidecar' ? new SidecarActuator() : new AppleScriptActuator()
+}
+
+/** Effective actuator description for the UI, factoring in runtime availability. */
+export async function describeActuator(
+	actuator: Actuator
+): Promise<{ name: string; caveat: string; precise: boolean; available: boolean }> {
+	const available = actuator.available ? await actuator.available().catch(() => false) : true
+	return { name: actuator.name, caveat: actuator.caveat, precise: actuator.precise, available }
+}