@jc_stack/ez-agents 0.1.0-beta.27 → 0.1.0-beta.29

package/src/control-state.ts

@@ -4,12 +4,34 @@ import path from 'node:path'
 import { isPreset, persistedPreset, type AiPreset, type ExecutionChoice } from './ai.js'
 
 export type Owner = {
+  id?: string
+  generation?: string
   kind?: 'group'
-  telegramUserId: number
-  telegramChatId: number
+  telegramUserId?: number
+  telegramChatId?: number
+  telegramLinkedAt?: string
   pairedAt: string
 }
 
+export type TelegramOwner = Owner & { telegramUserId: number; telegramChatId: number }
+export const telegramOwner = (owner: Owner | null): TelegramOwner | null =>
+  owner && Number.isSafeInteger(owner.telegramUserId) && Number.isSafeInteger(owner.telegramChatId) ? owner as TelegramOwner : null
+export const ownerId = (owner: Owner): string => owner.id ?? `telegram:${owner.telegramUserId}:${owner.telegramChatId}`
+export const ownerEpoch = (owner: Owner): string => owner.generation ?? owner.pairedAt
+export const sameOwner = (left: Owner, right: Owner | null): boolean =>
+  !!right && ownerId(left) === ownerId(right) && ownerEpoch(left) === ownerEpoch(right)
+export const validOwner = (owner: unknown): owner is Owner => {
+  if (!owner || typeof owner !== 'object') return false
+  const p = owner as Owner
+  const linked = p.telegramUserId !== undefined || p.telegramChatId !== undefined
+  return typeof p.pairedAt === 'string' && Number.isFinite(Date.parse(p.pairedAt)) &&
+    (p.generation === undefined || typeof p.generation === 'string' && /^[a-f0-9-]{36}$/.test(p.generation)) &&
+    (p.telegramLinkedAt === undefined || typeof p.telegramLinkedAt === 'string') &&
+    (p.id === undefined ? linked : typeof p.id === 'string' && /^[a-zA-Z0-9_:.-]{1,200}$/.test(p.id)) &&
+    (!linked ? p.kind === undefined : Number.isSafeInteger(p.telegramUserId) && p.telegramUserId! > 0 &&
+      Number.isSafeInteger(p.telegramChatId) && (p.kind === 'group' ? p.telegramChatId! < 0 : p.kind === undefined && p.telegramChatId! > 0))
+}
+
 export type PairingRequest = {
   kind?: 'group'
   title?: string
@@ -24,8 +46,15 @@ export type SessionState = {
   hasStarted: boolean
   cli?: string
   nativeSessionId?: string
+  title?: string
+  archived?: boolean
+  preset?: AiPreset
+  applicationScope?: string
+  telegramShared?: boolean
 }
 
+export type ControlGuard = { owner: Owner; authorize: () => Promise<unknown>; expectedSession?: string | null; applicationScope?: string }
+
 type ControlState = {
   version: 1
   owner: Owner | null
@@ -53,28 +82,56 @@ const isState = (value: unknown): value is ControlState => {
     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
+      ? Number.isSafeInteger(p.telegramChatId) && p.telegramChatId! < 0
       : p.kind === undefined && isPositiveId(p.telegramChatId))
   }
+  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') &&
+    (s.applicationScope === undefined || /^[a-f0-9]{64}$/.test(s.applicationScope)) &&
+    (s.telegramShared === undefined || typeof s.telegramShared === 'boolean') &&
+    (s.preset === undefined || (isPreset(s.preset) && s.preset.cli === s.cli))
   return (
     candidate.version === 1 &&
     Array.isArray(candidate.pending) &&
     candidate.pending.every((p) => identity(p) && Number.isFinite(Date.parse(p.expiresAt))) &&
-    (candidate.owner === null || identity(candidate.owner)) &&
+    (candidate.owner === null || validOwner(candidate.owner)) &&
     (candidate.ai === undefined || (Array.isArray(candidate.ai.presets) &&
       candidate.ai.presets.every(isPreset) &&
       candidate.ai.presets.some((p) => p.id === candidate.ai!.defaultId) &&
       candidate.ai.presets.some((p) => p.id === candidate.ai!.selectedId) &&
       (candidate.ai.recentIds === undefined || isRecentIds(candidate.ai.recentIds)))) &&
     (candidate.sessions === undefined || (Array.isArray(candidate.sessions) && candidate.sessions.every(
-      (s) => /^[0-9a-f-]{36}$/i.test(s.sessionId) && typeof s.hasStarted === 'boolean'))) &&
+      session))) &&
     (candidate.activeSession == null ||
-      (typeof candidate.activeSession.sessionId === 'string' &&
-        /^[0-9a-f-]{36}$/i.test(candidate.activeSession.sessionId) &&
-        typeof candidate.activeSession.hasStarted === 'boolean'))
+      session(candidate.activeSession))
   )
 }
 
+export const sessionTitle = (session: SessionState): string =>
+  session.title || `Conversation ${session.sessionId.slice(0, 8)}`
+
+const rememberPreset = (state: ControlState) => {
+  const preset = state.ai?.presets.find(p => p.id === state.ai!.selectedId)
+  if (state.activeSession && preset && state.activeSession.cli === preset.cli)
+    state.activeSession.preset = preset
+}
+
+const currentApplicationSession = (state: ControlState, scope: string) =>
+  [state.activeSession, ...(state.sessions ?? [])].find(session => session?.applicationScope === scope && !session.archived)
+
+const requireControlGuard = async (state: ControlState, guard?: ControlGuard) => {
+  if (!guard) return
+  // The callback may inspect binding authority, but must not acquire this store's lock.
+  await guard.authorize()
+  const expected = guard.owner
+  if (!sameOwner(expected, state.owner)) throw new Error('Control owner changed. Refresh the connection.')
+  const current = guard.applicationScope ? currentApplicationSession(state, guard.applicationScope) : state.activeSession
+  if (guard.applicationScope && current && (current.telegramShared || current === state.activeSession))
+    throw new Error('Application scope is shared; use shared controls')
+  if (guard.expectedSession !== undefined && (current?.sessionId ?? null) !== guard.expectedSession) throw new Error('Conversation changed. Refresh controls before trying again.')
+}
+
 const wait = (milliseconds: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, milliseconds))
 
@@ -161,7 +218,7 @@ export class ControlStore {
       throw new Error('Telegram identity must be a positive numeric ID')
     return this.withLock(async () => {
       const state = this.prune(await this.readState())
-      if (state.owner) return 'owner-exists'
+      if (telegramOwner(state.owner)) return 'owner-exists'
       if (
         state.pending.some(
           (request) => request.telegramUserId === telegramUserId && request.telegramChatId === telegramChatId,
@@ -184,20 +241,63 @@ export class ControlStore {
     })
   }
 
+  async bootstrapApplicationOwner(operatorId: number): Promise<Owner> {
+    if (!isPositiveId(operatorId)) throw new Error('Supply the real administrator Telegram user ID')
+    return this.withLock(async () => {
+      const state = await this.readState()
+      if (state.owner) throw new Error('An owner already exists; application bootstrap cannot replace it')
+      const owner: Owner = { generation: crypto.randomUUID(), telegramUserId: operatorId, telegramChatId: operatorId, pairedAt: new Date(this.clock()).toISOString() }
+      state.owner = owner
+      state.pending = []
+      await this.writeState(state)
+      return owner
+    })
+  }
+
+  async registerOwner(id: string): Promise<Owner> {
+    if (!/^[a-zA-Z0-9_:.-]{1,200}$/.test(id)) throw new Error('Invalid owner ID')
+    return this.withLock(async () => {
+      const state = await this.readState()
+      if (state.owner) {
+        if (ownerId(state.owner) !== id) throw new Error('Installation already has a different owner')
+        return state.owner
+      }
+      const bindings = await readFile(path.join(path.dirname(this.statePath), 'application-bindings.json'), 'utf8')
+        .then(text => JSON.parse(text), error => { if (error.code === 'ENOENT') return []; throw error })
+      if (!Array.isArray(bindings) || bindings.some(binding => !validOwner(binding?.owner)) || state.activeSession || state.sessions?.length)
+        throw new Error('Existing unowned state requires explicit ownership recovery')
+      state.owner = {id, generation: crypto.randomUUID(), pairedAt: new Date(this.clock()).toISOString()}
+      await this.writeState(state)
+      return state.owner
+    })
+  }
+
+  async unlinkTelegram(): Promise<void> {
+    await this.withLock(async () => {
+      const state = await this.readState()
+      if (!state.owner) throw new Error('No installation owner')
+      state.owner = {id: ownerId(state.owner), generation: state.owner.generation, pairedAt: state.owner.pairedAt}
+      state.pending = []
+      await this.writeState(state)
+    })
+  }
+
   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 (state.owner) throw new Error('An owner is already paired; revoke locally before replacing it')
+      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
         ? candidate.kind === 'group' && candidate.telegramChatId === 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(),
+        ...(state.owner ? {id: ownerId(state.owner), telegramLinkedAt: crypto.randomUUID()} : {}),
         ...(group ? {kind: 'group' as const} : {}),
         telegramUserId: request.telegramUserId,
         telegramChatId: request.telegramChatId,
-        pairedAt: new Date(this.clock()).toISOString(),
+        pairedAt: state.owner?.pairedAt ?? new Date(this.clock()).toISOString(),
       }
       state.owner = owner
       state.pending = []
@@ -253,14 +353,81 @@ export class ControlStore {
     })
   }
 
-  async resetSession(): Promise<SessionState> {
+  async listSessions(): Promise<SessionState[]> {
+    const state = await this.status()
+    return [...(state.activeSession ? [state.activeSession] : []), ...(state.sessions ?? []).filter(session => !session.applicationScope || session.telegramShared).slice().reverse()]
+  }
+
+  async switchSession(sessionId: string, expectedSession?: string | null, guard?: ControlGuard): Promise<SessionState> {
     return this.withLock(async () => {
       const state = await this.readState()
+      await requireControlGuard(state, guard)
+      if (expectedSession !== undefined && (state.activeSession?.sessionId ?? null) !== expectedSession) throw new Error('Conversation changed. Refresh controls before trying again.')
+      if (state.activeSession?.sessionId === sessionId) return state.activeSession
+      const session = state.sessions?.find(s => s.sessionId === sessionId)
+      if (!session || session.archived || (session.applicationScope && !session.telegramShared)) throw new Error('Conversation unavailable. Open /chats again.')
+      if (session.cli === 'agy')
+        throw new Error('Antigravity only resumes its latest conversation; selecting an older session is not supported.')
+      const ai = state.ai
+      // Older sessions did not record their model. Reuse a known preset for the
+      // same CLI; never resume an engine ID through a different client.
+      const preset = session.preset ?? ai?.presets.find(p => p.cli === session.cli)
+      if (!ai || !preset || preset.cli !== session.cli)
+        throw new Error('This older conversation has no saved AI binding. Start a new conversation.')
+      if (session.hasStarted && ['codex', 'codex-gui', 'opencode'].includes(session.cli!) && !session.nativeSessionId)
+        throw new Error('This conversation has no native session ID. Start a new conversation.')
+      assertEffort(preset.effort, preset.model, preset.cli)
+      rememberPreset(state)
+      state.sessions = state.sessions!.filter(s => s.sessionId !== sessionId)
+      if (state.activeSession) state.sessions.push(state.activeSession)
+      state.activeSession = session
+      ai.presets = [...ai.presets.filter(p => p.id !== preset.id), persistedPreset(preset)]
+      ai.selectedId = preset.id
+      await this.writeState(state)
+      return session
+    })
+  }
+
+  async archiveSession(sessionId: string, archived: boolean): Promise<void> {
+    await this.withLock(async () => {
+      const state = await this.readState()
+      const session = state.activeSession?.sessionId === sessionId ? state.activeSession
+        : state.sessions?.find(s => s.sessionId === sessionId)
+      if (!session) throw new Error('Conversation unavailable. Open /chats again.')
+      if (archived && state.activeSession === session) {
+        rememberPreset(state)
+        state.sessions ??= []
+        state.sessions.push(session)
+        state.activeSession = null
+        if (state.ai) state.ai.selectedId = state.ai.defaultId
+      }
+      session.archived = archived
+      await this.writeState(state)
+    })
+  }
+
+  async renameSession(title: string): Promise<void> {
+    title = title.replace(/\s+/g, ' ').trim()
+    if (!title || title.length > 80) throw new Error('Use /rename followed by a name of 1–80 characters.')
+    await this.withLock(async () => {
+      const state = await this.readState()
+      if (!state.activeSession) throw new Error('Open a conversation first with /chats or /new.')
+      state.activeSession.title = title
+      await this.writeState(state)
+    })
+  }
+
+  async resetSession(expectedSession?: string | null, guard?: ControlGuard): Promise<SessionState> {
+    return this.withLock(async () => {
+      const state = await this.readState()
+      await requireControlGuard(state, guard)
+      if (expectedSession !== undefined && (state.activeSession?.sessionId ?? null) !== expectedSession) throw new Error('Conversation changed. Refresh controls before trying again.')
       const next: SessionState = {
         sessionId: crypto.randomUUID(),
         hasStarted: false,
         cli: state.ai?.presets.find((p) => p.id === state.ai!.defaultId)?.cli,
       }
+      rememberPreset(state)
       if (state.activeSession) (state.sessions ??= []).push(state.activeSession)
       if (state.ai) state.ai.selectedId = state.ai.defaultId
       state.activeSession = next
@@ -296,18 +463,89 @@ export class ControlStore {
     })
   }
 
-  async captureChoice(initial: AiPreset): Promise<ExecutionChoice> {
+  async captureChoice(initial: AiPreset, title?: string): Promise<ExecutionChoice> {
     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.title && !state.activeSession.hasStarted && title?.trim())
+        state.activeSession.title = title.replace(/\s+/g, ' ').trim().slice(0, 80)
       await this.writeState(state)
       return { sessionId: state.activeSession.sessionId, preset }
     })
   }
 
+  async captureApplicationChoice(initial: AiPreset, scope: string, shareTelegram = false, requested?: AiPreset, expectedNativeSessionId?: string): Promise<ExecutionChoice> {
+    if (!/^[a-f0-9]{64}$/.test(scope)) throw new Error('Invalid application scope')
+    return this.withLock(async () => {
+      const state = await this.readState()
+      state.ai ??= { presets: [persistedPreset(initial)], defaultId: initial.id, selectedId: initial.id }
+      state.sessions ??= []
+      const previous = currentApplicationSession(state, scope)
+      if (expectedNativeSessionId !== undefined && previous?.nativeSessionId !== expectedNativeSessionId) throw new Error('Application request conflicts with native session; import the existing scope before cutover')
+      const activate = (session: SessionState) => {
+        if (!shareTelegram) return
+        session.telegramShared = true
+        session.archived = false
+        if (state.activeSession?.sessionId !== session.sessionId) {
+          state.sessions = state.sessions!.filter(item => item.sessionId !== session.sessionId)
+          if (state.activeSession) state.sessions.push(state.activeSession)
+          state.activeSession = session
+        }
+        state.ai!.presets = [...state.ai!.presets.filter(item => item.id !== session.preset!.id), session.preset!]
+        state.ai!.selectedId = session.preset!.id
+      }
+      if (previous?.preset) {
+        if (requested && requested.cli !== previous.cli) throw new Error('Application request conflicts with existing session engine')
+        if (requested) previous.preset = requested
+        activate(previous)
+        if (shareTelegram || requested) await this.writeState(state)
+        return { sessionId: previous.sessionId, preset: previous.preset }
+      }
+      const preset = requested ?? state.ai.presets.find(item => item.id === state.ai!.selectedId)!
+      if (preset.cli === 'agy') throw new Error('Application scopes require an engine with explicit session selection')
+      const session: SessionState = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli, preset, applicationScope: scope }
+      state.sessions.push(session)
+      activate(session)
+      await this.writeState(state)
+      return { sessionId: session.sessionId, preset }
+    })
+  }
+
+  async applicationSession(scope: string): Promise<SessionState | undefined> {
+    return currentApplicationSession(await this.status(), scope) ?? undefined
+  }
+
+  async changeApplicationSession(scope: string, guard: ControlGuard, preset?: AiPreset): Promise<SessionState> {
+    if (!/^[a-f0-9]{64}$/.test(scope) || guard.applicationScope !== scope || guard.expectedSession === undefined)
+      throw new Error('Invalid application scope control')
+    return this.withLock(async () => {
+      const state = await this.readState()
+      await requireControlGuard(state, guard)
+      const previous = currentApplicationSession(state, scope)
+      if (previous && (previous.telegramShared || previous === state.activeSession))
+        throw new Error('Application scope is shared; use shared controls')
+      const nextPreset = preset ?? state.ai?.presets.find(item => item.id === state.ai!.defaultId)
+      if (!nextPreset || !isPreset(nextPreset) || nextPreset.cli === 'agy') throw new Error('Invalid application AI selection')
+      if (preset && previous?.cli === preset.cli) {
+        previous.preset = persistedPreset(preset)
+        await this.writeState(state)
+        return previous
+      }
+      // Retire the binding, not its native session. Admitted work still resolves
+      // the old immutable session ID; private history stays absent from /chats.
+      if (previous) previous.archived = true
+      const next: SessionState = {sessionId:crypto.randomUUID(), hasStarted:false,
+        cli:nextPreset.cli, preset:persistedPreset(nextPreset), applicationScope:scope}
+      ;(state.sessions ??= []).push(next)
+      await this.writeState(state)
+      return next
+    })
+  }
+
   async executionSession(choice: ExecutionChoice): Promise<SessionState> {
     const state = await this.status()
     const session = state.activeSession?.sessionId === choice.sessionId ? state.activeSession
@@ -335,11 +573,12 @@ export class ControlStore {
     })
   }
 
-  async savePreset(preset: AiPreset): Promise<void> {
+  async savePreset(preset: AiPreset, guard?: ControlGuard): Promise<void> {
     if (!isPreset(preset)) throw new Error('Invalid AI preset')
     assertEffort(preset.effort, preset.model, preset.cli)
     await this.withLock(async () => {
       const state = await this.readState()
+      await requireControlGuard(state, guard)
       if (!state.ai) throw new Error('AI settings not initialized')
       if (state.ai.presets.length >= 12 && !state.ai.presets.some((p) => p.id === preset.id))
         throw new Error('Keep it small: at most 12 saved AIs.')
@@ -348,9 +587,10 @@ export class ControlStore {
     })
   }
 
-  async selectPreset(id: string, expectedSession: string | null, fresh = false): Promise<boolean> {
+  async selectPreset(id: string, expectedSession: string | null, fresh = false, guard?: ControlGuard): Promise<boolean> {
     return this.withLock(async () => {
       const state = await this.readState()
+      await requireControlGuard(state, guard)
       const ai = state.ai
       const preset = ai?.presets.find((p) => p.id === id)
       if (!ai || !preset) throw new Error('Saved AI no longer exists')
@@ -359,6 +599,7 @@ export class ControlStore {
       const current = ai.presets.find((p) => p.id === ai.selectedId)!
       if (state.activeSession && (current.cli !== preset.cli || !state.activeSession.cli) && !fresh) return false
       if (fresh || !state.activeSession) {
+        rememberPreset(state)
         if (state.activeSession) (state.sessions ??= []).push(state.activeSession)
         state.activeSession = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli }
       }

package/src/conversation-menu.ts

@@ -0,0 +1,89 @@
+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'>) => {
+  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 }) }
+    catch (error) {
+      if (!String((error as {description?: string})?.description).includes('message is not modified')) throw error
+    }
+  }
+  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()
+    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 }]
+    })
+  }
+  const list = async (ctx: Context, archived = false, page = 0) => {
+    const all = await sessionsWithNames()
+    const sessions = all.filter(s => Boolean(s.archived) === archived)
+    page = Math.min(page, Math.max(0, Math.ceil(sessions.length / 8) - 1))
+    const active = await control.getActiveSession()
+    const keyboard = new InlineKeyboard()
+    for (const session of sessions.slice(page * 8, page * 8 + 8))
+      keyboard.text(`${session.sessionId === active?.sessionId ? '✓ ' : ''}${sessionTitle(session)}`.slice(0, 64), `chat:open:${session.sessionId}`).row()
+    if (page > 0) keyboard.text('Previous', `chat:list:${Number(archived)}:${page - 1}`)
+    if ((page + 1) * 8 < sessions.length) keyboard.text('Next', `chat:list:${Number(archived)}:${page + 1}`)
+    if (page > 0 || (page + 1) * 8 < sessions.length) keyboard.row()
+    keyboard.text(archived ? 'Conversations' : 'Archived conversations', `chat:list:${Number(!archived)}:0`)
+      .text('+ New conversation', 'menu:new')
+    await render(ctx, archived
+      ? sessions.length ? 'Archived conversations' : 'No archived conversations.'
+      : sessions.length ? 'Conversations\nSelect a name to continue.' : 'No active conversations.\nSend a message to start a chat, or open Archived conversations.', keyboard)
+  }
+  return {
+    list,
+    async handle(ctx: Context): Promise<boolean> {
+      const data = ctx.callbackQuery?.data
+      if (!data?.startsWith('chat:')) return false
+      await ctx.answerCallbackQuery().catch(() => {})
+      try {
+        const page = /^chat:list:([01]):(\d{1,6})$/.exec(data)
+        if (page) { await list(ctx, page[1] === '1', Number(page[2])); return true }
+        const action = /^chat:(open|archive|restore):([0-9a-f-]{36})$/i.exec(data)
+        if (!action) throw new Error('Conversation unavailable. Open /chats again.')
+        const [, verb, id] = action
+        const session = (await sessionsWithNames()).find(s => s.sessionId === id)
+        if (!session) throw new Error('Conversation unavailable. Open /chats again.')
+        if (verb === 'archive' || verb === 'restore') {
+          await control.archiveSession(id, verb === 'archive')
+          await ctx.reply(`${verb === 'archive' ? 'Archived' : 'Restored'}: ${sessionTitle(session)}${verb === 'archive' ? '\nExisting work keeps its conversation. Archiving does not stop it.' : ''}`)
+          await list(ctx, verb === 'restore' ? false : true)
+        } else if (session.archived) {
+          await render(ctx, sessionTitle(session), new InlineKeyboard().text('Restore conversation', `chat:restore:${id}`).row().text('Back', 'chat:list:1:0'))
+        } else {
+          const keyboard = new InlineKeyboard().text('Archive this conversation', `chat:archive:${id}`).row()
+            .text('Back to conversations', 'chat:list:0:0')
+          try { await control.switchSession(id) }
+          catch (error) {
+            // Even an older session that cannot resume can still be archived.
+            await render(ctx, `${sessionTitle(session)}\n${error instanceof Error ? error.message : 'Unable to continue.'}`, keyboard)
+            return true
+          }
+          await render(ctx, `Current conversation: ${sessionTitle(session)}\nSend a message to continue. To rename it, use /rename followed by a name.`, keyboard)
+        }
+      } catch (error) {
+        await ctx.reply(error instanceof Error ? error.message : 'Conversation selection failed.')
+      }
+      return true
+    },
+  }
+}

package/src/delivery-context.d.mts

@@ -0,0 +1,5 @@
+import type {Owner} from './control-state.js';
+export type DeliveryContext={version:1;connectionId:string;plugin:string;revision:string;owner:Owner};
+export function authorizeDeliveryContext(context:unknown,owner:unknown):DeliveryContext;
+export function currentDeliveryOwner(controlDir:string):Promise<Owner|null>;
+export function captureDeliveryContext(controlDir:string,plugin:string,revision:string):Promise<DeliveryContext|undefined>;

package/src/delivery-context.mjs

@@ -0,0 +1,25 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const validOwner=owner=>owner&&typeof owner==='object'&&Number.isSafeInteger(owner.telegramUserId)&&owner.telegramUserId>0&&Number.isSafeInteger(owner.telegramChatId)&&(owner.kind==='group'?owner.telegramChatId<0:owner.kind===undefined&&owner.telegramChatId>0)&&typeof owner.pairedAt==='string'&&Number.isFinite(Date.parse(owner.pairedAt))&&(owner.id===undefined||typeof owner.id==='string'&&/^[a-zA-Z0-9_:.-]{1,200}$/.test(owner.id))&&(owner.generation===undefined||typeof owner.generation==='string'&&/^[a-f0-9-]{36}$/.test(owner.generation))&&(owner.telegramLinkedAt===undefined||typeof owner.telegramLinkedAt==='string');
+const ownerId=owner=>owner.id??`telegram:${owner.telegramUserId}:${owner.telegramChatId}`;
+const ownerEpoch=owner=>owner.generation??owner.pairedAt;
+const telegramEpoch=owner=>owner.telegramLinkedAt??owner.pairedAt;
+const sameDeliveryOwner=(left,right)=>validOwner(left)&&validOwner(right)&&ownerId(left)===ownerId(right)&&ownerEpoch(left)===ownerEpoch(right)&&left.kind===right.kind&&left.telegramUserId===right.telegramUserId&&left.telegramChatId===right.telegramChatId&&telegramEpoch(left)===telegramEpoch(right);
+export function authorizeDeliveryContext(context,owner) {
+  if(!context||context.version!==1||typeof context.connectionId!=='string'||!/^[a-zA-Z0-9_-]{1,100}$/.test(context.connectionId)||typeof context.plugin!=='string'||!/^[a-z][a-z0-9-]{0,39}$/.test(context.plugin)||typeof context.revision!=='string'||!context.revision||!sameDeliveryOwner(context.owner,owner))throw Error('Owner delivery context is invalid or revoked');
+  return context;
+}
+export async function currentDeliveryOwner(controlDir) {
+  const state=JSON.parse(await readFile(path.join(controlDir,'control-state.json'),'utf8'));
+  if(state.version!==1)throw Error('Invalid owner control state');
+  return state.owner;
+}
+export async function captureDeliveryContext(controlDir,plugin,revision) {
+  const owner=await currentDeliveryOwner(controlDir).catch(error=>{if(error.code==='ENOENT')return null;throw error;});
+  if(!owner)return undefined;
+  // A channel-neutral installation has no Telegram delivery destination.
+  if(owner.telegramUserId===undefined&&owner.telegramChatId===undefined)return undefined;
+  return authorizeDeliveryContext({version:1,connectionId:randomUUID(),plugin,revision,owner},owner);
+}

package/src/event-sources.ts

@@ -49,8 +49,8 @@ export class EventSources {
     const value = await read<{ version: number; sources: EventSource[] }>(this.registry, { version: 1, sources: [] })
     if (value.version !== 1 || !Array.isArray(value.sources) || value.sources.some(s => !identifier(s.id) || !identifier(s.bindingId) ||
       typeof s.socketPath !== 'string' || !isAbsolute(s.socketPath) || !cursorOK(s.initialCursor) ||
-      !Number.isSafeInteger(s.owner?.telegramUserId) || s.owner.telegramUserId <= 0 || !Number.isSafeInteger(s.owner.telegramChatId) ||
-      (s.owner.kind === 'group' ? s.owner.telegramChatId >= 0 : s.owner.kind !== undefined || s.owner.telegramChatId <= 0)) ||
+      !Number.isSafeInteger(s.owner?.telegramUserId) || s.owner.telegramUserId! <= 0 || !Number.isSafeInteger(s.owner.telegramChatId) ||
+      (s.owner.kind === 'group' ? s.owner.telegramChatId! >= 0 : s.owner.kind !== undefined || s.owner.telegramChatId! <= 0)) ||
       new Set(value.sources.map(s => s.id)).size !== value.sources.length) throw new Error('Invalid event-source registry')
     return value.sources
   }

package/src/execution-authority.ts

@@ -1,3 +1,4 @@
+import { ApplicationBindings } from './application-channel.js'
 import { ControlStore } from './control-state.js'
 import { RunStore, type RunRecord } from './runs.js'
 import type { Owner } from './control-state.js'
@@ -21,5 +22,6 @@ export async function requireOwnerExecution(controlDir: string, runId: string):
   const owner = (await new ControlStore(controlDir, 900_000).status()).owner
   const reason = executionBlockReason(run, owner)
   if (reason) throw new Error(`Execution blocked: ${reason}`)
+  if (run.application || run.delivery) await new ApplicationBindings(controlDir).authorize(run)
   return run
 }

package/src/executor.ts

@@ -27,6 +27,7 @@ export type ExecutorOptions = {
   eventSource?: string
   model?: string
   effort?: string
+  codexSandbox?: 'external'
   codexAutoCompactTokens?: number
   onSession?: (id: string) => Promise<void>
 }
@@ -74,7 +75,7 @@ export type CliAdapter = {
   command: string
   description: string
   buildArgs: (
-    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'codexAutoCompactTokens'> & { controlDir?: string },
+    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'codexAutoCompactTokens' | 'codexSandbox'> & { controlDir?: string },
     promptFile: string,
     promptText: string,
   ) => string[]
@@ -84,7 +85,8 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
   codex: {
     name: 'codex', command: 'codex', description: 'Codex CLI',
     buildArgs: (opts, _file, prompt) => {
-      const args = ['exec', '--skip-git-repo-check', '--json', '--sandbox', 'workspace-write', '--disable', 'memories', '--enable', 'skip_host_skill_discovery', '-c', 'approval_policy="never"']
+      if (opts.codexSandbox !== undefined && opts.codexSandbox !== 'external') throw new Error('Invalid Codex sandbox selection')
+      const args = ['exec', '--skip-git-repo-check', '--json', '--sandbox', opts.codexSandbox === 'external' ? 'danger-full-access' : 'workspace-write', '--disable', 'memories', '--enable', 'skip_host_skill_discovery', '-c', 'approval_policy="never"']
       const limit = opts.codexAutoCompactTokens
       if (limit !== undefined) {
         if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error('Invalid Codex compaction token limit')
@@ -232,6 +234,7 @@ export const startExecutorJob = async (
   options = executionDefaults(executorKey(options.cli), options)
   if(options.runId.startsWith('r_schedule_') && !/^[a-zA-Z0-9_-]+$/.test(options.runId))throw new Error('Invalid native task run ID')
   const run = await new RunStore(options.controlDir).get(options.runId)
+  if (options.codexSandbox !== undefined && (options.codexSandbox !== 'external' || process.env.EZ_EXECUTOR_TRANSPORT !== 'local' || !run || run.taskId || executorKey(options.cli) !== 'codex')) throw new Error('External Codex sandbox requires an owner-authorized native local run')
   if (run?.taskId) {
     if (run.status !== 'running') throw new Error('No active task run')
     await new Tasks(options.controlDir).authorize(run, process.env.EZ_EXECUTOR_TRANSPORT === 'host')
@@ -244,10 +247,13 @@ export const startExecutorJob = async (
   const gui = !host && key === 'codex-gui'
   const nativeSession = !host && key === 'codex' && options.runId.startsWith('r_schedule_')
   // Chat-mode experiment: only direct chat input at the engine boundary.
+  const applicationReminder = !host && (run?.application || run?.delivery)
+    ? '\n\n[Application channel] This is an owner-authorized application conversation. Send text replies using ezenciel-agents-message; stdout alone is not delivered. Attachments/reactions/approval controls are unsupported here. Domain tools can retrieve private context from ezenciel-agents-schedule context under run.application.context; do not expose credentials from that data. The application scope is ' + JSON.stringify((run.application ?? run.delivery)!.scope) + '.'
+    : ''
   const chatReminder = !host && !run?.taskId && run?.messageId !== undefined
     ? '\n\n[Chat context] You are replying in chat. Send replies with ezenciel-agents-message --text "..."; your final answer alone is not delivered. Before lengthy tool or repository work, briefly acknowledge through that CLI. Keep chat responsive: use ezenciel-agents-schedule for long-running work and native subagents for useful independent parts. Decide when to delegate and what to send.'
     : ''
-  const promptText = texts.join('\n\n') + chatReminder
+  const promptText = texts.join('\n\n') + applicationReminder + chatReminder
   const promptFile = path.join(outputDirectory, 'prompt.txt')
   await writeFile(promptFile, promptText, { encoding: 'utf8', mode: 0o600 })
 
@@ -298,7 +304,7 @@ export const startExecutorJob = async (
     throw error
   })
   child.stdin?.end(host
-    ? JSON.stringify({texts,options:{...options,onSession:undefined}})
+    ? JSON.stringify({texts,options:{...options,onSession:undefined,codexSandbox:undefined}})
     : nativeSession ? JSON.stringify({...options,onSession:undefined,prompt:promptText})
     : gui ? JSON.stringify({prompt:promptText,options:{...options,onSession:undefined}})
     : ['codex', 'claude'].includes(key) ? promptText : undefined)

package/src/host-executor.ts

@@ -59,6 +59,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
         await appendFile(base+'.events',JSON.stringify({stream:'exit',code:1})+'\n',{mode:0o600})
         await rm(path.join(directory,file))
       }
+      if (agent.toolsHome) await (await import('./plugins/workspace-lease.mjs')).recoverNativeLease(agent.toolsHome)
     }
     let catalogAt=Date.now()
     while (!signal.aborted) {
@@ -90,7 +91,11 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
           }
           const sharedWorkspace=sharedWorkspaces.get(agent)
           const base=path.join(directory,id)
-          await rename(base+'.request.json',base+'.running.json')
+          const releaseWorkspace = !run?.scheduled && agent.toolsHome
+            ? await (await import('./plugins/workspace-lease.mjs')).workspaceLease(agent.toolsHome,{kind:'native',runId:id}) : undefined
+          if (!run?.scheduled && agent.toolsHome && !releaseWorkspace) continue
+          try { await rename(base+'.request.json',base+'.running.json') }
+          catch (error) { await releaseWorkspace?.(); throw error }
           const task=(async()=>{
             let job: Awaited<ReturnType<typeof startExecutorJob>> | undefined
             let cancellation: ReturnType<typeof setInterval> | undefined
@@ -133,6 +138,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
               await rm(base+'.process.json',{force:true})
               await rm(base+'.cancel',{force:true})
               active.delete(base)
+              await releaseWorkspace?.()
             }
           })()
           tasks.add(task); void task.finally(()=>tasks.delete(task))