@jc_stack/ez-agents 0.1.0-beta.12

package/src/host-executor.ts

@@ -0,0 +1,129 @@
+import { mkdir, readFile, writeFile, readdir, rename, rm, appendFile, realpath } from 'node:fs/promises'
+import path from 'node:path'
+import { isHostRunId } from './host-executor-protocol.js'
+import { fileURLToPath } from 'node:url'
+import { startExecutorJob, terminateJob, resolveExecutor, type ExecutorOptions } from './executor.js'
+import { readModels, validateSelection } from './ai.js'
+import type { ChildProcess } from 'node:child_process'
+import { packageVersion } from './version.js'
+import { installedPluginVersions } from './software-status.js'
+
+export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string }
+export type HostInstallation = { cli: string; agents: HostBinding[] }
+
+export const serveHostExecutor = async (installation: HostInstallation, signal: AbortSignal) => {
+  resolveExecutor(installation.cli)
+  if (new Set(installation.agents.map(a=>a.workspace)).size !== installation.agents.length ||
+      new Set(installation.agents.map(a=>a.controlDir)).size !== installation.agents.length)
+    throw new Error('Each agent requires a separate workspace and control directory')
+  const active = new Map<string, ChildProcess>()
+  const busy = new Set<string>()
+  const tasks = new Set<Promise<void>>()
+  const locks: string[] = []
+  try {
+    for (const agent of installation.agents) {
+      if (![agent.workspace,agent.controlDir,agent.binDir].every(path.isAbsolute)) throw new Error('Host bindings require absolute paths')
+      if (agent.toolsHome) {
+        if (!path.isAbsolute(agent.toolsHome)) throw new Error('Plugin registry binding requires an absolute path')
+        const config=JSON.parse(await readFile(path.join(agent.toolsHome,'config.json'),'utf8'))
+        if (config.schemaVersion!==1 || config.workspace!==await realpath(agent.workspace)) throw new Error('Plugin registry belongs to another workspace')
+      }
+      const directory = path.join(agent.controlDir,'host-executor')
+      await mkdir(directory,{recursive:true,mode:0o700})
+      const lock=path.join(directory,'worker.lock')
+      try { const prior=JSON.parse(await readFile(lock,'utf8')); try { process.kill(prior.pid,0); throw new Error('Host executor already running') } catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }; await rm(lock) }
+      catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+      await writeFile(lock,JSON.stringify({pid:process.pid}),{mode:0o600,flag:'wx'})
+      locks.push(lock)
+      await writeFile(path.join(directory,'models.json'),JSON.stringify(await readModels()),{mode:0o600})
+      // A host crash is terminal for a claimed job. Never replay an action.
+      for (const file of await readdir(directory)) if (file.endsWith('.running.json')) {
+        const base=path.join(directory,file.slice(0,-13))
+        try {
+          const prior=JSON.parse(await readFile(base+'.process.json','utf8'))
+          try { process.kill(prior.pid,0); throw new Error('Previous host CLI is still running; stop it before recovery') }
+          catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }
+        } catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+        await rm(base+'.process.json',{force:true})
+        await appendFile(base+'.events',JSON.stringify({stream:'exit',code:1})+'\n',{mode:0o600})
+        await rm(path.join(directory,file))
+      }
+    }
+    let catalogAt=Date.now()
+    while (!signal.aborted) {
+      const parent=Number(process.env.EZ_HOST_SUPERVISOR_PID)
+      if(parent) { try { process.kill(parent,0) } catch { break } }
+      if(Date.now()-catalogAt>30000){
+        const models=JSON.stringify(await readModels())
+        for(const agent of installation.agents){
+          const file=path.join(agent.controlDir,'host-executor/models.json')
+          await writeFile(file+'.tmp',models,{mode:0o600});await rename(file+'.tmp',file)
+        }
+        catalogAt=Date.now()
+      }
+      for (const agent of installation.agents) {
+        const directory=path.join(agent.controlDir,'host-executor')
+        await writeFile(path.join(directory,'heartbeat.tmp'),JSON.stringify({at:Date.now(),pid:process.pid,version:packageVersion,plugins:await installedPluginVersions(agent.toolsHome)}),{mode:0o600})
+        await rename(path.join(directory,'heartbeat.tmp'),path.join(directory,'heartbeat.json'))
+        for (const file of await readdir(directory)) {
+          if ((!file.endsWith('.request.json') || !isHostRunId(file.slice(0,-13))) || busy.has(agent.name)) continue
+          const base=path.join(directory,file.slice(0,-13))
+          await rename(base+'.request.json',base+'.running.json')
+          busy.add(agent.name)
+          const task=(async()=>{
+            let job: Awaited<ReturnType<typeof startExecutorJob>> | undefined
+            let cancellation: ReturnType<typeof setInterval> | undefined
+            let writes=Promise.resolve()
+            const emit=(event:unknown)=>{writes=writes.then(()=>appendFile(base+'.events',JSON.stringify(event)+'\n',{mode:0o600}))}
+            try {
+              try { await readFile(base+'.cancel'); throw new Error('Cancelled') } catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+              const request=JSON.parse(await readFile(base+'.running.json','utf8'))
+              if (!Array.isArray(request.texts) || request.texts.some((text:unknown)=>typeof text!=='string')) throw new Error('Invalid job')
+              const opts=request.options as ExecutorOptions
+              const cli = opts.cli || installation.cli
+              resolveExecutor(cli)
+              if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,model:opts.model,effort:opts.effort},await readModels())
+              const options:ExecutorOptions={workspace:agent.workspace,controlDir:agent.controlDir,binDir:agent.binDir,toolsHome:agent.toolsHome,cli,
+                runId:path.basename(base),timeoutMs:Math.min(Math.max(Number(opts.timeoutMs)||300000,1000),1800000),
+                sessionId:opts.sessionId,isResume:opts.isResume,eventSource:opts.eventSource,model:opts.model,effort:opts.effort}
+              job=await startExecutorJob(request.texts,options)
+              active.set(agent.name,job.child)
+              await writeFile(base+'.process.json',JSON.stringify({pid:job.child.pid}),{mode:0o600})
+              if(signal.aborted)terminateJob(job.child)
+              job.child.stdout?.on('data',chunk=>emit({stream:'stdout',text:chunk.toString()}))
+              job.child.stderr?.on('data',chunk=>emit({stream:'stderr',text:chunk.toString()}))
+              cancellation=setInterval(()=>{void readFile(base+'.cancel').then(()=>terminateJob(job!.child)).catch(()=>{})},250)
+              const code=await new Promise<number>(resolve=>job!.child.once('close',code=>resolve(code??1)))
+              emit({stream:'exit',code})
+            } catch { emit({stream:'stderr',text:'Host CLI execution failed\n'}); emit({stream:'exit',code:1}) }
+            finally {
+              if(cancellation)clearInterval(cancellation)
+              await job?.cleanup()
+              await writes
+              await rm(base+'.running.json',{force:true})
+              await rm(base+'.process.json',{force:true})
+              await rm(base+'.cancel',{force:true})
+              active.delete(agent.name)
+              busy.delete(agent.name)
+            }
+          })()
+          tasks.add(task); void task.finally(()=>tasks.delete(task))
+          // Do not claim a second job while asynchronous spawning is pending.
+          break
+        }
+      }
+      await new Promise(resolve=>setTimeout(resolve,250))
+    }
+  } finally {
+    for(const child of active.values())terminateJob(child)
+    await Promise.allSettled(tasks)
+    for(const lock of locks)await rm(lock,{force:true})
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1])===fileURLToPath(import.meta.url)) {
+  const abort=new AbortController()
+  for(const signal of ['SIGTERM','SIGINT'] as const)process.once(signal,()=>abort.abort())
+  const config=JSON.parse(await readFile(process.argv[2],'utf8'))
+  await serveHostExecutor(config,abort.signal)
+}

package/src/identity.ts

@@ -0,0 +1,17 @@
+import type { Context } from 'grammy'
+import type { Owner } from './control-state.js'
+
+export const isOwner = (ctx: Pick<Context, 'from' | 'chat'>, owner: Owner | null): boolean =>
+  Boolean(
+    owner &&
+      ctx.from &&
+      !ctx.from.is_bot &&
+      ctx.chat?.type === 'private' &&
+      ctx.from.id === owner.telegramUserId &&
+      ctx.chat.id === owner.telegramChatId,
+  )
+
+export const assertId = (id: string): string => {
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) throw new Error('Invalid record identifier')
+  return id
+}

package/src/inbox.ts

@@ -0,0 +1,171 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Update } from 'grammy/types'
+import { isExecutionChoice, type ExecutionChoice } from './ai.js'
+
+export type IncomingItem = {
+  text: string
+  messageId?: number
+  updateId: number
+  chatId: number
+  fromId: number
+}
+
+type Entry = { update: Update; receivedAt: number; execution?: ExecutionChoice }
+export type InboxBatch = { id: string; entries: Entry[]; status: 'pending' | 'failed' | 'cancelled' }
+type State = { version: 1; seen: number[]; waiting: Entry[]; batches: InboxBatch[] }
+
+// One relay writer. Serialize read/modify/rename, including commands arriving during STT.
+export class InboxStore {
+  private lock: Promise<unknown> = Promise.resolve()
+  private readonly file: string
+  constructor(
+    private readonly directory: string,
+    private readonly now = Date.now,
+  ) {
+    this.file = join(directory, 'inbox.json')
+  }
+
+  private async read(): Promise<State> {
+    try {
+      const state = JSON.parse(await readFile(this.file, 'utf8')) as State
+      const entry = (e: Entry) =>
+        e && Number.isSafeInteger(e.update?.update_id) && Number.isFinite(e.receivedAt) &&
+        (e.execution === undefined || isExecutionChoice(e.execution))
+      if (
+        state.version !== 1 ||
+        !Array.isArray(state.seen) ||
+        !state.seen.every(Number.isSafeInteger) ||
+        !Array.isArray(state.waiting) ||
+        !state.waiting.every(entry) ||
+        !Array.isArray(state.batches) ||
+        !state.batches.every(
+          (b) =>
+            /^tg_\d+$/.test(b.id) &&
+            ['pending', 'failed', 'cancelled'].includes(b.status) &&
+            Array.isArray(b.entries) &&
+            b.entries.length > 0 &&
+            b.entries.every(entry),
+        )
+      )
+        throw new Error('Invalid inbox shape')
+      return state
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT')
+        return { version: 1, seen: [], waiting: [], batches: [] }
+      throw new Error('Inbox unreadable; restore the local journal before accepting messages')
+    }
+  }
+
+  private change<T>(work: (state: State) => T): Promise<T> {
+    const next = this.lock.then(async () => {
+      const state = await this.read()
+      const result = work(state)
+      await mkdir(this.directory, { recursive: true, mode: 0o700 })
+      const temporary = `${this.file}.${process.pid}.tmp`
+      await writeFile(temporary, JSON.stringify(state), { mode: 0o600 })
+      await rename(temporary, this.file)
+      return result
+    })
+    this.lock = next.catch(() => {})
+    return next
+  }
+
+  accept(update: Update, execution?: ExecutionChoice): Promise<boolean> {
+    if (!Number.isSafeInteger(update.update_id) || update.update_id < 0) throw new Error('Invalid update ID')
+    return this.change((state) => {
+      if (state.seen.includes(update.update_id)) return false
+      state.seen.push(update.update_id)
+      state.waiting.push({ update, receivedAt: this.now(), execution })
+      return true
+    })
+  }
+
+  // Seal membership BEFORE normalization or run creation. Replay uses the same run ID.
+  next(force = false): Promise<InboxBatch | undefined> {
+    return this.change((state) => {
+      const pending = state.batches.find((b) => b.status === 'pending')
+      if (pending) return pending
+      if (!state.waiting.length) return
+      const first = state.waiting[0]
+      const last = state.waiting.at(-1)!
+      if (
+        !force &&
+        (state.waiting.length < 10 || last.update.message?.media_group_id) &&
+        this.now() - last.receivedAt < 2000 &&
+        this.now() - first.receivedAt < 30000
+      )
+        return
+      const boundary = state.waiting.findIndex((e) => JSON.stringify(e.execution) !== JSON.stringify(first.execution))
+      const entries = state.waiting.splice(0, boundary < 0 ? 10 : Math.min(10, boundary))
+      // Telegram albums contain at most ten items. Don't split one at the batch boundary.
+      const album = entries.at(-1)?.update.message?.media_group_id
+      while (album && state.waiting[0]?.update.message?.media_group_id === album &&
+        JSON.stringify(state.waiting[0].execution) === JSON.stringify(first.execution))
+        entries.push(state.waiting.shift()!)
+      const batch: InboxBatch = { id: `tg_${first.update.update_id}`, entries, status: 'pending' }
+      state.batches.push(batch)
+      return batch
+    })
+  }
+
+  finish(id: string, failed = false): Promise<void> {
+    return this.change((state) => {
+      const batch = state.batches.find((b) => b.id === id)
+      if (!batch || batch.status !== 'pending') return
+      if (failed) batch.status = 'failed'
+      else state.batches = state.batches.filter((b) => b.id !== id)
+    })
+  }
+
+  cancel(): Promise<number> {
+    return this.change((state) => {
+      let count = state.waiting.length
+      state.waiting = []
+      for (const batch of state.batches) {
+        if (batch.status !== 'pending') continue
+        count += batch.entries.length
+        batch.status = 'cancelled'
+      }
+      return count
+    })
+  }
+
+  retryLatest(userId: number, chatId: number): Promise<string | undefined> {
+    return this.change((state) => {
+      const batch = [...state.batches].reverse().find(
+        (b) =>
+          b.status === 'failed' &&
+          b.entries.every((e) => {
+            const message = e.update.message || e.update.callback_query?.message
+            const from = e.update.message?.from || e.update.callback_query?.from
+            return (
+              from?.id === userId &&
+              !from.is_bot &&
+              message?.chat.type === 'private' &&
+              message.chat.id === chatId
+            )
+          }),
+      )
+      if (!batch) return
+      batch.status = 'pending'
+      return batch.id
+    })
+  }
+
+  async pending(id: string): Promise<boolean> {
+    await this.lock
+    return (await this.read()).batches.some((b) => b.id === id && b.status === 'pending')
+  }
+
+  async status(): Promise<{ pending: number; failed: number }> {
+    await this.lock
+    const state = await this.read()
+    return {
+      pending:
+        state.waiting.length +
+        state.batches.filter((b) => b.status === 'pending').reduce((n, b) => n + b.entries.length, 0),
+      failed: state.batches.filter((b) => b.status === 'failed').length,
+    }
+  }
+}