@jc_stack/ez-agents 0.1.0-beta.12

package/src/runs.ts

@@ -0,0 +1,445 @@
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { validOrigin, type ExternalOrigin } from './event-sources.js'
+import { normalizeReactionEmoji } from './reaction.js'
+import { assertId } from './identity.js'
+import { isExecutionChoice, type ExecutionChoice } from './ai.js'
+
+export type RunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+export type RunRecord = {
+  version: 1
+  id: string
+  chatId: number
+  telegramUserId: number
+  messageId?: number
+  texts: string[]
+  status: RunStatus
+  createdAt: string
+  startedAt?: string
+  endedAt?: string
+  pid?: number
+  execution?: ExecutionChoice
+  external?: ExternalOrigin
+}
+
+export type OutboxItemType = 'message' | 'reaction' | 'document' | 'voice' | 'approval'
+
+export type OutboxItem = {
+  id: string
+  runId: string
+  chatId: number
+  type?: OutboxItemType
+  text?: string
+  emoji?: string
+  messageId?: number
+  replyToMessageId?: number
+  documentPath?: string
+  voiceText?: string
+  approvalPrompt?: string
+  approvalActionId?: string
+  createdAt: string
+}
+
+const isRun = (value: unknown): value is RunRecord => {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<RunRecord>
+  return (
+    candidate.version === 1 &&
+    typeof candidate.id === 'string' &&
+    /^[a-zA-Z0-9_-]+$/.test(candidate.id) &&
+    Number.isSafeInteger(candidate.chatId) &&
+    Number.isSafeInteger(candidate.telegramUserId) &&
+    Array.isArray(candidate.texts) &&
+    candidate.texts.every((text) => typeof text === 'string') &&
+    ['queued', 'running', 'completed', 'failed', 'cancelled'].includes(candidate.status ?? '') &&
+    typeof candidate.createdAt === 'string' &&
+    Number.isFinite(Date.parse(candidate.createdAt)) &&
+    (candidate.pid === undefined || (Number.isSafeInteger(candidate.pid) && candidate.pid > 0)) &&
+    (candidate.external === undefined || validOrigin(candidate.external)) &&
+    (candidate.execution === undefined || isExecutionChoice(candidate.execution))
+  )
+}
+
+export const newRunId = (): string => `r_${Date.now().toString(36)}_${randomBytes(3).toString('hex')}`
+
+export const isPidAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export class RunStore {
+  private readonly runsDir: string
+  private readonly outboxDir: string
+
+  constructor(controlDir: string) {
+    this.runsDir = path.join(controlDir, 'runs')
+    this.outboxDir = path.join(controlDir, 'outbox')
+  }
+
+  private async ensure(): Promise<void> {
+    await mkdir(this.runsDir, { recursive: true, mode: 0o700 })
+    await mkdir(this.outboxDir, { recursive: true, mode: 0o700 })
+  }
+
+  private runPath(id: string): string {
+    return path.join(this.runsDir, `${assertId(id)}.json`)
+  }
+
+  private async writeRun(run: RunRecord): Promise<void> {
+    await this.ensure()
+    const temporary = `${this.runPath(run.id)}.${process.pid}.tmp`
+    await writeFile(temporary, `${JSON.stringify(run, null, 2)}\n`, { mode: 0o600 })
+    await rename(temporary, this.runPath(run.id))
+  }
+
+  async create(input: {
+    id?: string
+    chatId: number
+    telegramUserId: number
+    texts: string[]
+    messageId?: number
+    execution?: ExecutionChoice
+    external?: ExternalOrigin
+  }): Promise<RunRecord> {
+    if (input.id) {
+      const existing = await this.get(input.id)
+      if (existing) {
+        if (existing.chatId !== input.chatId || existing.telegramUserId !== input.telegramUserId)
+          throw new Error('Run ownership mismatch')
+        return existing
+      }
+    }
+    const run: RunRecord = {
+      version: 1,
+      id: input.id ?? newRunId(),
+      chatId: input.chatId,
+      telegramUserId: input.telegramUserId,
+      messageId: input.messageId,
+      texts: input.texts,
+      execution: input.execution,
+      external: input.external,
+      status: 'queued',
+      createdAt: new Date().toISOString(),
+    }
+    await this.writeRun(run)
+    return run
+  }
+
+  async get(id: string): Promise<RunRecord | null> {
+    try {
+      const parsed: unknown = JSON.parse(await readFile(this.runPath(id), 'utf8'))
+      if (!isRun(parsed) || parsed.id !== id) throw new Error('Run record has an unsupported shape')
+      return parsed
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+      throw error
+    }
+  }
+
+  async patch(
+    id: string,
+    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid'>>,
+  ): Promise<RunRecord> {
+    const run = await this.get(id)
+    if (!run) throw new Error(`Unknown run ${id}`)
+    const next = { ...run, ...change }
+    await this.writeRun(next)
+    return next
+  }
+
+  async list(): Promise<RunRecord[]> {
+    await this.ensure()
+    const names = await readdir(this.runsDir)
+    const runs: RunRecord[] = []
+    for (const name of names) {
+      if (!name.endsWith('.json') || name.includes('.tmp')) continue
+      try {
+        const run = await this.get(name.slice(0, -5))
+        if (run) runs.push(run)
+      } catch {
+        console.error('Unreadable run record', name)
+      }
+    }
+    return runs.sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+  }
+
+  async running(): Promise<RunRecord | undefined> {
+    const runs = await this.list()
+    for (const run of runs) {
+      if (run.status === 'running') {
+        if (run.pid && !isPidAlive(run.pid)) {
+          await this.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+          continue
+        }
+        return run
+      }
+    }
+    return undefined
+  }
+
+  async nextQueued(): Promise<RunRecord | undefined> {
+    return (await this.list()).find((run) => run.status === 'queued')
+  }
+
+  async deliveryStatus(): Promise<{ failed: number; unknown: number }> {
+    await this.ensure()
+    const names = await readdir(this.outboxDir)
+    const result = { failed: 0, unknown: names.filter((name) => name.endsWith('.sending.json')).length }
+    for (const name of names.filter((name) => name.endsWith('.failed.json'))) {
+      try {
+        const item = JSON.parse(await readFile(path.join(this.outboxDir, name), 'utf8'))
+        if (item.deliveryUnknown) result.unknown++
+        else result.failed++
+      } catch {
+        result.unknown++
+      }
+    }
+    return result
+  }
+
+  private async writeOutboxItem(item: OutboxItem): Promise<OutboxItem> {
+    await this.ensure()
+    const file = path.join(this.outboxDir, `${item.id}.json`)
+    const temporary = `${file}.${process.pid}.tmp`
+    await writeFile(temporary, `${JSON.stringify(item, null, 2)}\n`, { mode: 0o600 })
+    await rename(temporary, file)
+    return item
+  }
+
+  async enqueueMessage(
+    runId: string,
+    text: string,
+    options?: { replyToMessageId?: number },
+  ): Promise<OutboxItem> {
+    const run = await this.get(runId)
+    if (!run) throw new Error(`Unknown run ${runId}`)
+    if (run.status !== 'running' && run.status !== 'queued') throw new Error(`Run ${runId} cannot send`)
+    const item: OutboxItem = {
+      id: `${runId}_${Date.now().toString(36)}_${randomBytes(2).toString('hex')}`,
+      runId,
+      chatId: run.chatId,
+      type: 'message',
+      text,
+      replyToMessageId: options?.replyToMessageId,
+      createdAt: new Date().toISOString(),
+    }
+    return this.writeOutboxItem(item)
+  }
+
+  async enqueueDocument(
+    runId: string,
+    documentPath: string,
+    options?: { caption?: string; replyToMessageId?: number },
+  ): Promise<OutboxItem> {
+    const run = await this.get(runId)
+    if (!run) throw new Error(`Unknown run ${runId}`)
+    if (run.status !== 'running' && run.status !== 'queued') throw new Error(`Run ${runId} cannot send`)
+    const item: OutboxItem = {
+      id: `${runId}_${Date.now().toString(36)}_${randomBytes(2).toString('hex')}`,
+      runId,
+      chatId: run.chatId,
+      type: 'document',
+      documentPath,
+      text: options?.caption,
+      replyToMessageId: options?.replyToMessageId,
+      createdAt: new Date().toISOString(),
+    }
+    return this.writeOutboxItem(item)
+  }
+
+  async enqueueVoice(
+    runId: string,
+    voiceText: string,
+    options?: { replyToMessageId?: number },
+  ): Promise<OutboxItem> {
+    const run = await this.get(runId)
+    if (!run) throw new Error(`Unknown run ${runId}`)
+    if (run.status !== 'running' && run.status !== 'queued') throw new Error(`Run ${runId} cannot send`)
+    const item: OutboxItem = {
+      id: `${runId}_${Date.now().toString(36)}_${randomBytes(2).toString('hex')}`,
+      runId,
+      chatId: run.chatId,
+      type: 'voice',
+      voiceText,
+      replyToMessageId: options?.replyToMessageId,
+      createdAt: new Date().toISOString(),
+    }
+    return this.writeOutboxItem(item)
+  }
+
+  async enqueueApproval(
+    runId: string,
+    prompt: string,
+    actionId: string,
+    options?: { replyToMessageId?: number },
+  ): Promise<OutboxItem> {
+    const run = await this.get(runId)
+    if (!run) throw new Error(`Unknown run ${runId}`)
+    if (run.status !== 'running' && run.status !== 'queued')
+      throw new Error(`Run ${runId} cannot request approval`)
+    const item: OutboxItem = {
+      id: `${runId}_${Date.now().toString(36)}_${randomBytes(2).toString('hex')}`,
+      runId,
+      chatId: run.chatId,
+      type: 'approval',
+      approvalPrompt: prompt,
+      approvalActionId: actionId,
+      replyToMessageId: options?.replyToMessageId,
+      createdAt: new Date().toISOString(),
+    }
+    return this.writeOutboxItem(item)
+  }
+
+  async enqueueReaction(runId: string, rawEmoji: string): Promise<OutboxItem> {
+    const run = await this.get(runId)
+    if (!run) throw new Error(`Unknown run ${runId}`)
+    if (run.status !== 'running' && run.status !== 'queued') throw new Error(`Run ${runId} cannot react`)
+    if (!run.messageId) throw new Error(`Run ${runId} has no messageId to react to`)
+    const emoji = normalizeReactionEmoji(rawEmoji)
+    if (!emoji) {
+      throw new Error(`Invalid Telegram reaction emoji "${rawEmoji}"`)
+    }
+    const item: OutboxItem = {
+      id: `${runId}_${Date.now().toString(36)}_${randomBytes(2).toString('hex')}`,
+      runId,
+      chatId: run.chatId,
+      type: 'reaction',
+      emoji,
+      messageId: run.messageId,
+      createdAt: new Date().toISOString(),
+    }
+    return this.writeOutboxItem(item)
+  }
+
+  async pendingOutbox(): Promise<OutboxItem[]> {
+    await this.ensure()
+    const names = (await readdir(this.outboxDir)).filter(
+      (name) =>
+        name.endsWith('.json') &&
+        !name.endsWith('.sent.json') &&
+        !name.endsWith('.failed.json') &&
+        !name.endsWith('.sending.json') &&
+        !name.includes('.tmp'),
+    )
+    const items: OutboxItem[] = []
+    for (const name of names) {
+      try {
+        const parsed: unknown = JSON.parse(await readFile(path.join(this.outboxDir, name), 'utf8'))
+        if (
+          parsed &&
+          typeof parsed === 'object' &&
+          ('text' in parsed ||
+            'emoji' in parsed ||
+            'documentPath' in parsed ||
+            'voiceText' in parsed ||
+            'approvalPrompt' in parsed ||
+            'type' in parsed)
+        ) {
+          items.push(parsed as OutboxItem)
+        }
+      } catch (error: unknown) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
+          console.error('Unreadable outbox record', name)
+      }
+    }
+    return items.sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+  }
+
+  async claimOutbox(id: string): Promise<boolean> {
+    assertId(id)
+    const from = path.join(this.outboxDir, `${id}.json`)
+    const to = path.join(this.outboxDir, `${id}.sending.json`)
+    try {
+      await rename(from, to)
+      return true
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+      throw error
+    }
+  }
+
+  async waitForDelivery(id: string, timeoutMs = 120_000): Promise<unknown> {
+    assertId(id)
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      for (const status of ['sent', 'failed'] as const) {
+        let item
+        try {
+          item = JSON.parse(await readFile(path.join(this.outboxDir, `${id}.${status}.json`), 'utf8'))
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
+          throw error
+        }
+        if (status === 'failed' && item.deliveryUnknown)
+          throw new Error(`Delivery outcome unknown; inspect before retrying: ${item.deliveryError || id}`)
+        if (status === 'failed')
+          throw new Error(item.deliveryError || 'Delivery failed; inspect the local outbox')
+        return item.receipt ?? { delivered: true }
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100))
+    }
+    throw new Error(`Delivery outcome unknown for ${id}; inspect the outbox before retrying`)
+  }
+
+  async failOutbox(id: string, reason = 'Delivery failed', deliveryUnknown = false): Promise<void> {
+    assertId(id)
+    const source = path.join(this.outboxDir, `${id}.sending.json`)
+    const item = JSON.parse(await readFile(source, 'utf8'))
+    const temporary = `${source}.${process.pid}.tmp`
+    await writeFile(temporary, JSON.stringify({ ...item, deliveryError: reason, deliveryUnknown }), {
+      mode: 0o600,
+    })
+    await rename(temporary, source)
+    await rename(
+      path.join(this.outboxDir, `${id}.sending.json`),
+      path.join(this.outboxDir, `${id}.failed.json`),
+    )
+  }
+
+  async unclaimOutbox(id: string): Promise<void> {
+    assertId(id)
+    const from = path.join(this.outboxDir, `${id}.sending.json`)
+    const to = path.join(this.outboxDir, `${id}.json`)
+    try {
+      await rename(from, to)
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+  }
+
+  async markOutboxSent(id: string, messageIds: number[] = []): Promise<void> {
+    assertId(id)
+    const sendingFile = path.join(this.outboxDir, `${id}.sending.json`)
+    const normalFile = path.join(this.outboxDir, `${id}.json`)
+    const target = path.join(this.outboxDir, `${id}.sent.json`)
+    if (messageIds.length) {
+      const record = JSON.parse(await readFile(sendingFile, 'utf8'))
+      const temporary = `${sendingFile}.${process.pid}.tmp`
+      await writeFile(
+        temporary,
+        JSON.stringify({ ...record, receipt: { messageIds, deliveredAt: new Date().toISOString() } }),
+        { mode: 0o600 },
+      )
+      await rename(temporary, sendingFile)
+    }
+    try {
+      await rename(sendingFile, target)
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        try {
+          await rename(normalFile, target)
+        } catch (e: unknown) {
+          if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e
+        }
+      } else {
+        throw err
+      }
+    }
+  }
+}

package/src/service.ts

@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { lstat, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseEnv } from 'node:util'
+
+const run = promisify(execFile)
+const packageRoot = fileURLToPath(new URL('../', import.meta.url))
+
+export const serviceDefinition = (directory: string) => {
+  const root = path.resolve(directory)
+  if (/[\r\n\0]/.test(root)) throw new Error('Service paths must be single-line values.')
+  return { command: 'docker', args: ['compose', '--project-directory', packageRoot,
+    '--env-file', path.join(root, 'docker.env'), 'up', '-d', '--wait', 'relay'] }
+}
+
+// Docker owns lifecycle. No host-service fallback or provider onboarding here.
+export const installService = async (directory: string) => {
+  const definition = serviceDefinition(directory)
+  const file = path.join(path.resolve(directory), 'docker.env')
+  if (!(await lstat(file)).isFile()) throw new Error('docker.env must be a regular file')
+  const values = parseEnv(await readFile(file, 'utf8'))
+  if (!values.COMPOSE_PROJECT_NAME || !values.EZ_RELAY_ENV_FILE)
+    throw new Error('docker.env must bind COMPOSE_PROJECT_NAME and EZ_RELAY_ENV_FILE; see docs/docker-runtime.md')
+  await run(definition.command, definition.args)
+  return { service: 'relay', runtime: 'docker', project: values.COMPOSE_PROJECT_NAME, active: true }
+}

package/src/setup.ts

@@ -0,0 +1,180 @@
+import { access, constants, readFile, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { parseEnv } from 'node:util'
+import { initializeWorkspace } from './workspace.js'
+import { configureInstallation } from './install-config.js'
+import { installService } from './service.js'
+import { discoverDefaults } from './client-defaults.js'
+import { initialPreset } from './ai.js'
+import { ControlStore } from './control-state.js'
+import { loadControlConfig } from './config.js'
+import { EXECUTOR_REGISTRY, resolveExecutor, executorKey } from './executor.js'
+import { desktopCodexPath } from './desktop-bridge.js'
+
+export const findExecutableInPath = async (
+  command: string,
+  envPath: string = process.env.PATH ?? '',
+): Promise<string | null> => {
+  const dirs = envPath.split(path.delimiter).filter(Boolean)
+  for (const dir of dirs) {
+    const fullPath = path.join(dir, command)
+    try {
+      await access(fullPath, constants.X_OK)
+      return fullPath
+    } catch {
+      // continue searching
+    }
+  }
+  return null
+}
+
+export const readActiveExecutor = async (envFilePath: string): Promise<string> => {
+  try {
+    const content = await readFile(envFilePath, 'utf8')
+    const active = parseEnv(content).EZ_EXECUTOR_CLI?.trim()
+    if (active) return active
+  } catch {
+    // env file doesn't exist yet
+  }
+  return process.env.EZ_EXECUTOR_CLI?.trim() || 'agy'
+}
+
+export const setExecutorInEnv = async (envFilePath: string, cliName: string): Promise<void> => {
+  const adapter = resolveExecutor(cliName)
+  let content = ''
+  try {
+    content = await readFile(envFilePath, 'utf8')
+  } catch {
+    content = ''
+  }
+
+  const newLine = `EZ_EXECUTOR_CLI=${adapter.name}`
+  if (/^EZ_EXECUTOR_CLI=.*$/m.test(content)) {
+    content = content.replace(/^EZ_EXECUTOR_CLI=.*$/m, newLine)
+  } else {
+    content = content ? `${content.trimEnd()}\n${newLine}\n` : `${newLine}\n`
+  }
+  await writeFile(envFilePath, content, 'utf8')
+}
+
+export type ExecutorStatus = {
+  id: string
+  name: string
+  command: string
+  description: string
+  installedPath: string | null
+  isActive: boolean
+}
+
+export const getExecutorsStatus = async (
+  envFilePath: string = path.resolve(process.cwd(), '.env'),
+): Promise<{ active: string; items: ExecutorStatus[] }> => {
+  const active = await readActiveExecutor(envFilePath)
+  const resolvedActive = executorKey(active)
+
+  const items: ExecutorStatus[] = []
+  for (const [id, adapter] of Object.entries(EXECUTOR_REGISTRY)) {
+    const installedPath = id === 'codex-gui' ? await desktopCodexPath() : await findExecutableInPath(adapter.command)
+    items.push({
+      id,
+      name: adapter.name,
+      command: adapter.command,
+      description: adapter.description,
+      installedPath,
+      isActive: id === resolvedActive,
+    })
+  }
+  return { active, items }
+}
+
+const printStatus = (status: { active: string; items: ExecutorStatus[] }): void => {
+  console.log('\nSupported CLI Executors:\n')
+  for (const item of status.items) {
+    const activeBadge = item.isActive ? ' [ACTIVE]' : ''
+    const statusText = item.installedPath ? `✓ installed (${item.installedPath})` : '✗ not found in PATH'
+    console.log(`  * ${item.id.padEnd(14)} (${item.command})${activeBadge}`)
+    console.log(`    ${item.description}`)
+    console.log(`    Status: ${statusText}\n`)
+  }
+  console.log(`Active executor: ${status.active}`)
+  console.log('Initialize the persistent mind: ezenciel-agents-setup init')
+  console.log('\nTo switch executor:')
+  console.log('  pnpm run setup <executor-name>')
+  console.log('  Examples: pnpm run setup claude')
+  console.log('            pnpm run setup agy')
+  console.log('            pnpm run setup grok')
+  console.log('            pnpm run setup opencode')
+  console.log('            pnpm run setup codex-gui\n')
+}
+
+export const runCli = async (): Promise<void> => {
+  const args = process.argv.slice(2).filter((arg) => arg !== '--')
+  const envFilePath = path.resolve(process.cwd(), '.env')
+
+  if (args[0] === '--help' || args[0] === '-h') {
+    console.log('Usage: ezenciel-agents-setup configure <executor> [--token-stdin] | service | init | status | <executor>\nconfigure writes private .env paths and seeds missing mind files; it does not start or pair the bot.\n--token-stdin accepts the BotFather token without putting it in command arguments or output.\nservice starts only the Docker Compose relay bound by docker.env in the current directory. It does not install the host-executor service; follow docs/host-service.md. It does not pair the owner.\nFollow docs/setup.md through a real Telegram reply; package installation alone is incomplete.')
+    return
+  }
+
+  if (args[0] === 'service') {
+    if (args.length !== 1) throw new Error('Usage: ezenciel-agents-setup service')
+    console.log(JSON.stringify(await installService(process.cwd())))
+    return
+  }
+
+  if (args[0] === 'configure') {
+    if (!args[1] || args.length > 3 || (args[2] && args[2] !== '--token-stdin'))
+      throw new Error('Usage: ezenciel-agents-setup configure <executor> [--token-stdin]')
+    let token: string | undefined
+    if (args[2]) {
+      if (process.stdin.isTTY) throw new Error('Supply the token through stdin, not a command argument.')
+      let input = ''
+      for await (const chunk of process.stdin) {
+        input += chunk.toString()
+        if (input.length > 512) throw new Error('Token input is too long.')
+      }
+      token = input.trim()
+    }
+    console.log(JSON.stringify(await configureInstallation(process.cwd(), args[1], token)))
+    return
+  }
+
+  if (args[0] === 'init') {
+    if (args.length !== 1) throw new Error('Usage: ezenciel-agents-setup init (uses EZ_AGENT_WORKSPACE or ./agent)')
+    const workspace = path.resolve(process.env.EZ_AGENT_WORKSPACE?.trim() || './agent')
+    const created = await initializeWorkspace(workspace)
+    const config = loadControlConfig()
+    await new ControlStore(config.controlDir, config.pairingTtlMs).syncClientPresets(
+      initialPreset(await readActiveExecutor(envFilePath)), await discoverDefaults(workspace))
+    console.log(JSON.stringify({ workspace, created }))
+    return
+  }
+
+  if (args.length === 0 || args[0] === 'status') {
+    const status = await getExecutorsStatus(envFilePath)
+    printStatus(status)
+    return
+  }
+
+  const target = args[0]
+  try {
+    const adapter = resolveExecutor(target)
+    await setExecutorInEnv(envFilePath, adapter.name)
+    const installed = await findExecutableInPath(adapter.command)
+    console.log(`\n✓ Active CLI executor switched to: ${adapter.name} (${adapter.command})`)
+    if (installed) {
+      console.log(`  Binary verified at: ${installed}`)
+    } else {
+      console.warn(`  Warning: Binary "${adapter.command}" not found in PATH. Install it before starting the relay.`)
+    }
+    console.log(`  Updated: ${envFilePath}\n`)
+  } catch (error) {
+    console.error(`\nError: ${(error as Error).message}\n`)
+    process.exit(1)
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  void runCli().catch(error => { console.error((error as Error).message); process.exitCode = 1 })
+}

package/src/software-status.ts

@@ -0,0 +1,23 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { packageVersion } from './version.js'
+
+export const installedPluginVersions = async (toolsHome?: string) => {
+  if (!toolsHome) return null
+  try {
+    const registry = JSON.parse(await readFile(path.join(toolsHome, 'registry.json'), 'utf8')) as {plugins: Record<string, {manifest: {id: string; version: string}}>}
+    return Object.values(registry.plugins).map(record => ({ id: record.manifest.id, version: record.manifest.version }))
+  } catch { return null }
+}
+
+export const softwareStatus = async (controlDir: string): Promise<string[]> => {
+  const lines = [`Ez relay: ${packageVersion} (running)`]
+  try {
+    const h = JSON.parse(await readFile(path.join(controlDir, 'host-executor/heartbeat.json'), 'utf8'))
+    if (!Number.isFinite(h.at) || h.at > Date.now() + 5000 || Date.now() - h.at >= 15000) throw Error('Stale host')
+    lines.push(`Host transport: ${typeof h.version === 'string' ? h.version : 'version unknown'} (running)`)
+    if (!Array.isArray(h.plugins)) lines.push('Plugins (installed): unknown')
+    else lines.push(`Plugins (installed): ${h.plugins.length ? h.plugins.map((p: {id: string; version: string}) => `${p.id} ${p.version}`).join(', ') : 'none'}`)
+  } catch { lines.push('Host transport: unavailable', 'Plugins (installed): unknown') }
+  return lines
+}

package/src/source-cli.ts

@@ -0,0 +1,18 @@
+import { parseArgs } from 'node:util'
+import { loadControlConfig } from './config.js'
+import { ControlStore } from './control-state.js'
+import { EventSources } from './event-sources.js'
+
+async function main() {
+  const { values } = parseArgs({ options: { name: { type: 'string' }, socket: { type: 'string' }, remove: { type: 'boolean' }, list: { type: 'boolean' }, help: { type: 'boolean' } } })
+  if (values.help) { console.log('ezenciel-agents-source --list | --name NAME --socket /absolute/service.sock | --name NAME --remove'); return }
+  const config = loadControlConfig()
+  const sources = new EventSources(config.controlDir)
+  if (values.list) { console.log(JSON.stringify(await sources.list())); return }
+  if (!values.name || (!!values.socket === !!values.remove)) throw new Error('Supply --name and either --socket or --remove')
+  const owner = (await new ControlStore(config.controlDir, config.pairingTtlMs).status()).owner
+  if (!owner) throw new Error('Pair an owner before registering event sources')
+  const source = await sources.register(values.name, values.remove ? null : values.socket!, owner)
+  console.log(JSON.stringify({ ok: true, source: source ?? null }))
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1 })