@jc_stack/ez-agents 0.1.0-beta.33 → 0.1.0-beta.36

package/src/control-state.ts

@@ -1,7 +1,8 @@
 import { assertEffort } from './model-policy.js'
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
 import { mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { isPreset, persistedPreset, type AiPreset, type ExecutionChoice } from './ai.js'
+import { isPreset, persistedPreset, type AiPreset, type ExecutionChoice, type ModelChoice } from './ai.js'
 
 export type Owner = {
   id?: string
@@ -32,7 +33,7 @@ export const validOwner = (owner: unknown): owner is Owner => {
       Number.isSafeInteger(p.telegramChatId) && (p.kind === 'group' ? p.telegramChatId! < 0 : p.kind === undefined && p.telegramChatId! > 0))
 }
 
-export type PairingRequest = {
+type TelegramPairingRequest = {
   kind?: 'group'
   title?: string
   telegramUserId: number
@@ -41,6 +42,18 @@ export type PairingRequest = {
   expiresAt: string
 }
 
+type ApplicationPairingRequest = {
+  application: {
+    bindingId: string
+    tokenHash: string
+    owner: Owner
+  }
+  requestedAt: string
+  expiresAt: string
+}
+
+export type PairingRequest = TelegramPairingRequest | ApplicationPairingRequest
+
 export type SessionState = {
   sessionId: string
   hasStarted: boolean
@@ -71,6 +84,20 @@ const emptyState = (): ControlState => ({ version: 1, owner: null, pending: [] }
 const isPositiveId = (value: unknown): value is number =>
   typeof value === 'number' && Number.isSafeInteger(value) && value > 0
 
+const applicationPairing = (request: PairingRequest): request is ApplicationPairingRequest =>
+  'application' in request
+
+const telegramPairing = (request: PairingRequest): request is TelegramPairingRequest =>
+  !applicationPairing(request)
+
+const applicationBindingId = (value: unknown): value is string =>
+  typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value)
+
+const pairingToken = (value: unknown): value is string =>
+  typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value)
+
+const pairingDigest = (value: string): string => createHash('sha256').update(value).digest('hex')
+
 const isRecentIds = (value: unknown): value is string[] =>
   Array.isArray(value) && value.length <= 3 && new Set(value).size === value.length &&
   value.every((id) => typeof id === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(id))
@@ -78,13 +105,25 @@ const isRecentIds = (value: unknown): value is string[] =>
 const isState = (value: unknown): value is ControlState => {
   if (!value || typeof value !== 'object') return false
   const candidate = value as Partial<ControlState>
-  const identity = (person: unknown): boolean => {
+  const telegramIdentity = (person: unknown): boolean => {
     if (!person || typeof person !== 'object') return false
     const p = person as Owner
     return isPositiveId(p.telegramUserId) && (p.kind === 'group'
       ? Number.isSafeInteger(p.telegramChatId) && p.telegramChatId! < 0
       : p.kind === undefined && isPositiveId(p.telegramChatId))
   }
+  const pairing = (request: unknown): request is PairingRequest => {
+    if (!request || typeof request !== 'object') return false
+    const value = request as Partial<ApplicationPairingRequest & TelegramPairingRequest>
+    if (!Number.isFinite(Date.parse(value.expiresAt ?? '')) || !Number.isFinite(Date.parse(value.requestedAt ?? '')))
+      return false
+    if (value.application !== undefined) {
+      const application = value.application
+      return Object.keys(value).every((key) => ['application', 'requestedAt', 'expiresAt'].includes(key)) &&
+        !!application && applicationBindingId(application.bindingId) && /^[a-f0-9]{64}$/.test(application.tokenHash) && validOwner(application.owner)
+    }
+    return telegramIdentity(value)
+  }
   const session = (s: SessionState) => s && /^[0-9a-f-]{36}$/i.test(s.sessionId) && typeof s.hasStarted === 'boolean' &&
     (s.title === undefined || (typeof s.title === 'string' && s.title.length <= 80)) &&
     (s.archived === undefined || typeof s.archived === 'boolean') &&
@@ -94,7 +133,7 @@ const isState = (value: unknown): value is ControlState => {
   return (
     candidate.version === 1 &&
     Array.isArray(candidate.pending) &&
-    candidate.pending.every((p) => identity(p) && Number.isFinite(Date.parse(p.expiresAt))) &&
+    candidate.pending.every(pairing) &&
     (candidate.owner === null || validOwner(candidate.owner)) &&
     (candidate.ai === undefined || (Array.isArray(candidate.ai.presets) &&
       candidate.ai.presets.every(isPreset) &&
@@ -145,6 +184,9 @@ export class ControlStore {
     private readonly clock: Clock = () => Date.now(),
   ) {
     this.statePath = path.join(controlDir, 'control-state.json')
+    // The lock stays on the shared control volume: relay (container) and CLI
+    // children (host) must exclude each other. Hot reads avoid it entirely
+    // (see status/captureChoice fast paths); only real mutations take it.
     this.lockPath = path.join(controlDir, 'control-state.lock')
   }
 
@@ -170,8 +212,16 @@ export class ControlStore {
   }
 
   private async writeState(state: ControlState): Promise<void> {
+    const serialized = `${JSON.stringify(state, null, 2)}\n`
+    // Steady-state reads (owner checks, session pins that already match) must
+    // not churn control/: skip the write when nothing changed.
+    try {
+      if ((await readFile(this.statePath, 'utf8')) === serialized) return
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
     const temporary = `${this.statePath}.${process.pid}.tmp`
-    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
+    await writeFile(temporary, serialized, { mode: 0o600 })
     await rename(temporary, this.statePath)
   }
 
@@ -200,6 +250,12 @@ export class ControlStore {
   }
 
   async status(): Promise<ControlState> {
+    // Hot path (owner checks every message and every source tick): when no
+    // pairing expired, the pruned state is returned with zero control/ writes
+    // and without taking the lock. Expiry still converges under the lock.
+    const current = await this.readState()
+    const pruned = this.prune(current)
+    if (pruned.pending.length === current.pending.length) return pruned
     return this.withLock(async () => {
       const state = this.prune(await this.readState())
       await this.writeState(state)
@@ -221,7 +277,7 @@ export class ControlStore {
       if (telegramOwner(state.owner)) return 'owner-exists'
       if (
         state.pending.some(
-          (request) => request.telegramUserId === telegramUserId && request.telegramChatId === telegramChatId,
+          (request) => telegramPairing(request) && request.telegramUserId === telegramUserId && request.telegramChatId === telegramChatId,
         )
       ) {
         await this.writeState(state)
@@ -282,14 +338,75 @@ export class ControlStore {
     })
   }
 
+  async createApplicationTelegramPairing(bindingId: string, expectedOwner: Owner): Promise<{ token: string; expiresAt: string } | null> {
+    if (!applicationBindingId(bindingId) || !validOwner(expectedOwner)) throw new Error('Invalid application Telegram pairing request')
+    return this.withLock(async () => {
+      const state = this.prune(await this.readState())
+      if (!sameOwner(expectedOwner, state.owner)) throw new Error('Application authority revoked')
+      if (telegramOwner(state.owner)) {
+        await this.writeState(state)
+        return null
+      }
+      const retained = state.pending.filter((request) => !applicationPairing(request) || request.application.bindingId !== bindingId)
+      if (retained.length >= 3) throw new Error('Telegram pairing capacity reached')
+      const token = randomBytes(32).toString('base64url')
+      const now = this.clock()
+      const expiresAt = new Date(now + this.pairingTtlMs).toISOString()
+      state.pending = [...retained, {
+        application: { bindingId, tokenHash: pairingDigest(token), owner: expectedOwner },
+        requestedAt: new Date(now).toISOString(),
+        expiresAt,
+      }]
+      await this.writeState(state)
+      return { token, expiresAt }
+    })
+  }
+
+  async claimApplicationTelegramPairing(
+    token: string,
+    telegramUserId: number,
+    telegramChatId: number,
+    authorize: (bindingId: string, owner: Owner) => Promise<boolean>,
+  ): Promise<Owner | null> {
+    if (!pairingToken(token) || !isPositiveId(telegramUserId) || !isPositiveId(telegramChatId)) return null
+    return this.withLock(async () => {
+      const state = this.prune(await this.readState())
+      const request = state.pending.find((candidate): candidate is ApplicationPairingRequest =>
+        applicationPairing(candidate) && /^[a-f0-9]{64}$/.test(candidate.application.tokenHash) &&
+        timingSafeEqual(Buffer.from(candidate.application.tokenHash, 'hex'), Buffer.from(pairingDigest(token), 'hex')))
+      if (!request || telegramOwner(state.owner) || !sameOwner(request.application.owner, state.owner)) {
+        if (request) state.pending = state.pending.filter((candidate) => candidate !== request)
+        await this.writeState(state)
+        return null
+      }
+      if (!await authorize(request.application.bindingId, request.application.owner)) {
+        state.pending = state.pending.filter((candidate) => candidate !== request)
+        await this.writeState(state)
+        return null
+      }
+      const owner: Owner = {
+        id: ownerId(state.owner!),
+        generation: state.owner!.generation,
+        telegramUserId,
+        telegramChatId,
+        telegramLinkedAt: crypto.randomUUID(),
+        pairedAt: state.owner!.pairedAt,
+      }
+      state.owner = owner
+      state.pending = []
+      await this.writeState(state)
+      return owner
+    })
+  }
+
   async approveOwner(telegramUserId: number, group = false): Promise<Owner> {
     if (!(group ? Number.isSafeInteger(telegramUserId) && telegramUserId < 0 : isPositiveId(telegramUserId))) throw new Error('Supply a positive user ID or negative group ID')
     return this.withLock(async () => {
       const state = this.prune(await this.readState())
       if (telegramOwner(state.owner)) throw new Error('An owner is already paired; unlink locally before replacing its Telegram channel')
-      const request = state.pending.find((candidate) => group
+      const request = state.pending.find((candidate): candidate is TelegramPairingRequest => telegramPairing(candidate) && (group
         ? candidate.kind === 'group' && candidate.telegramChatId === telegramUserId
-        : candidate.kind === undefined && candidate.telegramUserId === telegramUserId)
+        : candidate.kind === undefined && candidate.telegramUserId === telegramUserId))
       if (!request) throw new Error('No active pairing request exists for that Telegram user ID')
       const owner: Owner = {
         generation: state.owner ? state.owner.generation : crypto.randomUUID(),
@@ -463,14 +580,75 @@ export class ControlStore {
     })
   }
 
+  async normalizeProviderBindings(catalog: ModelChoice[]): Promise<boolean> {
+    const providerFor = (preset: AiPreset): AiPreset => {
+      if (preset.provider || preset.cli !== 'codex' || !preset.model) return preset
+      const matches = catalog.filter((model) => model.cli === preset.cli && model.model === preset.model && model.provider &&
+        (preset.effort === undefined || model.efforts.includes(preset.effort)))
+      if (matches.length !== 1) return preset
+      const model = matches[0]
+      return persistedPreset({
+        ...preset,
+        provider: model.provider,
+      })
+    }
+    return this.withLock(async () => {
+      const state = await this.readState()
+      if (!state.ai) return false
+      let changed = false
+      const normalize = (preset: AiPreset | undefined): AiPreset | undefined => {
+        if (!preset) return undefined
+        const next = providerFor(preset)
+        if (next !== preset) changed = true
+        return next
+      }
+      state.ai.presets = state.ai.presets.map((preset) => normalize(preset)!)
+      if (state.activeSession?.preset) state.activeSession.preset = normalize(state.activeSession.preset)
+      state.sessions = state.sessions?.map((session) => ({
+        ...session,
+        ...(session.preset ? { preset: normalize(session.preset) } : {}),
+      }))
+      if (changed) await this.writeState(state)
+      return changed
+    })
+  }
+
   async captureChoice(initial: AiPreset, title?: string): Promise<ExecutionChoice> {
+    // Hot path (every inbound message and every source tick): when the pinned
+    // session already matches the selected preset, return it with zero
+    // control/ writes and without taking the lock. Any divergence (missing
+    // session, CLI/provider/model change, untitled fresh session) falls
+    // through to the serializing slow path. A concurrent control edit inside
+    // the microsecond unlocked window fails closed downstream (the execution
+    // session lookup rejects a stale pin; the batch can be retried).
+    const settled = await this.readState()
+    const settledAi = settled.ai
+    const settledPreset = settledAi?.presets.find((p) => p.id === settledAi.selectedId)
+    const session = settled.activeSession
+    if (settledPreset && session && (session.cli || session.hasStarted) &&
+      !(session.cli === settledPreset.cli && session.hasStarted && session.preset &&
+        (session.preset.provider !== settledPreset.provider || session.preset.model !== settledPreset.model)) &&
+      (session.cli !== settledPreset.cli || JSON.stringify(session.preset) === JSON.stringify(settledPreset)) &&
+      Boolean(session.title || session.hasStarted || !title?.trim()))
+      return { sessionId: session.sessionId, preset: settledPreset }
     return this.withLock(async () => {
       const state = await this.readState()
       state.ai ??= { presets: [persistedPreset(initial)], defaultId: initial.id, selectedId: initial.id, recentIds: [] }
       const preset = state.ai.presets.find((p) => p.id === state.ai!.selectedId)!
       state.activeSession ??= { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli }
       if (!state.activeSession.cli && !state.activeSession.hasStarted) state.activeSession.cli = preset.cli
-      if (state.activeSession.cli === preset.cli) state.activeSession.preset = preset
+      if (state.activeSession.cli === preset.cli) {
+        const previous = state.activeSession.preset
+        // Same CLI, different provider/model: web/Telegram must not resume the old native thread.
+        // Undefined is the native client default and is a distinct selection.
+        if (state.activeSession.hasStarted && previous &&
+            (previous.provider !== preset.provider || previous.model !== preset.model)) {
+          ;(state.sessions ??= []).push(state.activeSession)
+          state.activeSession = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli, preset }
+        } else {
+          state.activeSession.preset = preset
+        }
+      }
       if (!state.activeSession.title && !state.activeSession.hasStarted && title?.trim())
         state.activeSession.title = title.replace(/\s+/g, ' ').trim().slice(0, 80)
       await this.writeState(state)

package/src/conversation-menu.ts

@@ -1,9 +1,9 @@
 import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, sessionTitle } from './control-state.js'
-import type { RunStore } from './runs.js'
 
 // IDs identify existing relay bindings only; the engine still owns all context.
-export const createConversationMenu = (control: ControlStore, runs: Pick<RunStore, 'list'>) => {
+// Titles come from owner renames; no run text or delivery history is read here.
+export const createConversationMenu = (control: ControlStore) => {
   const render = async (ctx: Context, text: string, keyboard: InlineKeyboard) => {
     if (!ctx.callbackQuery?.message) { await ctx.reply(text, { reply_markup: keyboard }); return }
     try { await ctx.editMessageText(text, { reply_markup: keyboard }) }
@@ -13,23 +13,12 @@ export const createConversationMenu = (control: ControlStore, runs: Pick<RunStor
   }
   const sessionsWithNames = async () => {
     const sessions = await control.listSessions()
-    if (sessions.every(s => s.title)) return sessions
-    // Display existing owner input only. Do not create another history store or
-    // ask an engine to generate titles just to render a menu. Commands and JSON
-    // event records (including approval callbacks) are not readable chat names.
-    const history = await runs.list()
+    // Display session bindings only. Titles come from explicit owner renames;
+    // no prompt, run or delivery history is read to derive a menu label.
     return sessions.flatMap((session, index) => {
       if (session.title) return [session]
-      const first = history.find(run => run.execution?.sessionId === session.sessionId &&
-        run.messageId && !run.taskId && !run.scheduled && !run.external && !run.replyOnly &&
-        run.texts[0]?.trim() && !/^[/{]/.test(run.texts[0].trim()))
-      // New only reserves a routing ID. Do not present empty routing placeholders
-      // as engine conversations. Retain the records for already accepted work.
-      if (!session.hasStarted && !session.nativeSessionId && !first) return []
-      const title = first
-        ? `${first.texts[0].replace(/\s+/g, ' ').trim().slice(0, 40)} · ${first.createdAt.slice(0, 16).replace('T', ' ')} UTC`
-        : `Untitled conversation ${index + 1}`
-      return [{ ...session, title }]
+      if (!session.hasStarted && !session.nativeSessionId) return []
+      return [{ ...session, title: `Untitled conversation ${index + 1}` }]
     })
   }
   const list = async (ctx: Context, archived = false, page = 0) => {

package/src/delivery-socket-client.d.mts

@@ -0,0 +1,4 @@
+export type DeliverySocketRequest = { op: string; payload?: unknown }
+export function deliverySocketPath(controlDir: string): string
+export function callDeliverySocket(socketPath: string, op: DeliverySocketRequest, timeoutMs?: number): Promise<unknown>
+export function deliverySocketAlive(socketPath: string, timeoutMs?: number): Promise<boolean>

package/src/delivery-socket-client.mjs

@@ -0,0 +1,104 @@
+import { createConnection } from 'node:net'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+// Plain-JS delivery transport shared by the TypeScript relay and the
+// plain-Node tools (plugin manager, update supervisor, install status). The
+// relay owns run records in memory; every other process reaches them through
+// this socket on the shared control volume. Newline-delimited JSON frames:
+// {id, op, payload} -> {id, ok, result?, error?}.
+//
+// Host-capable deployments publish a loopback TCP endpoint as well: on Docker
+// Desktop/OrbStack the container's Unix socket is not connectable from the
+// macOS host, so host processes fall back to the relay's authenticated
+// loopback listener described by control/delivery-endpoint.json.
+export const deliverySocketPath = controlDir => path.join(controlDir, 'delivery.sock')
+
+const encode = value => `${JSON.stringify(value)}\n`
+const endpointName = 'delivery-endpoint.json'
+const connectFailureCodes = new Set(['ENOENT', 'ECONNREFUSED', 'EACCES', 'EPROTOTYPE'])
+
+const unavailable = (target, cause) => {
+  const error = new Error(`Delivery relay unavailable at ${target}`)
+  if (cause !== undefined) error.cause = cause
+  error.connectFailure = true
+  return error
+}
+
+// A timeout is not a connect failure: the relay may already have processed the
+// request, so replaying the frame elsewhere could duplicate an uncertain write.
+const timedOut = target => new Error(`Delivery relay unavailable at ${target}`)
+
+const exchange = (connect, envelope, timeoutMs, target) => new Promise((resolve, reject) => {
+  let done = false
+  const socket = connect()
+  const timer = setTimeout(() => {
+    if (done) return
+    done = true
+    socket.destroy()
+    reject(timedOut(target))
+  }, timeoutMs)
+  let buffer = ''
+  socket.setEncoding('utf8')
+  socket.once('error', error => {
+    if (done) return
+    done = true
+    clearTimeout(timer)
+    reject(error?.code && connectFailureCodes.has(error.code) ? unavailable(target, error) : error)
+  })
+  socket.on('data', chunk => {
+    buffer += chunk
+    let newline
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline)
+      buffer = buffer.slice(newline + 1)
+      if (!line.trim()) continue
+      let response
+      try { response = JSON.parse(line) } catch { continue }
+      if (response.id !== envelope.id) continue
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      socket.destroy()
+      if (response.ok) resolve(response.result)
+      else reject(new Error(typeof response.error === 'string' ? response.error : 'Delivery request failed'))
+    }
+  })
+  socket.write(encode(envelope))
+})
+
+const readEndpoint = async controlDir => {
+  try {
+    const value = JSON.parse(await readFile(path.join(controlDir, endpointName), 'utf8'))
+    if (value?.host !== '127.0.0.1' || !Number.isSafeInteger(value.port) || value.port < 1 || value.port > 65535 ||
+      typeof value.token !== 'string' || !/^[a-f0-9]{64}$/.test(value.token)) return null
+    return value
+  } catch { return null }
+}
+
+export const callDeliverySocket = async (socketPath, op, timeoutMs = 130_000) => {
+  const id = `${Date.now().toString(36)}_${Math.floor(Math.random() * 0xffffff).toString(16)}`
+  try {
+    return await exchange(() => createConnection(socketPath), { id, ...op }, timeoutMs, socketPath)
+  } catch (error) {
+    if (!error?.connectFailure) throw error
+  }
+  const endpoint = await readEndpoint(path.dirname(socketPath))
+  if (!endpoint) throw unavailable(socketPath)
+  const target = `${endpoint.host}:${endpoint.port}`
+  try {
+    return await exchange(() => createConnection({ host: endpoint.host, port: endpoint.port }), { id, token: endpoint.token, ...op }, timeoutMs, target)
+  } catch (error) {
+    if (!error?.connectFailure) throw error
+    throw unavailable(`${socketPath} and ${target}`, error)
+  }
+}
+
+export const deliverySocketAlive = async (socketPath, timeoutMs = 2000) => {
+  try {
+    await callDeliverySocket(socketPath, { op: 'ping' }, timeoutMs)
+    return true
+  } catch {
+    return false
+  }
+}