@jc_stack/ez-agents 0.1.0-beta.26 → 0.1.0-beta.28

package/src/config.ts

@@ -1,3 +1,4 @@
+import { parseWebLauncher, type WebLauncher } from './web-launcher.js'
 import { repairEnabled } from './repair-policy.js'
 import path from 'node:path'
 import { homedir } from 'node:os'
@@ -9,13 +10,18 @@ export type ControlConfig = {
 
 export type Config = ControlConfig & {
   repairEnabled?: boolean
+  telegramEnabled?: boolean
+  webLauncher?: WebLauncher
   telegramBotToken: string
   workspace: string
   executorTimeoutMs: number
+  codexSandbox?: 'external'
   codexAutoCompactTokens?: number
   executorCli: string
   channelBackendUrl?: string
   channelBackendToken?: string
+  applicationPort?: number
+  applicationHost?: string
   geminiApiKey?: string
   openaiApiKey?: string
   pagerDutyRoutingKey?: string
@@ -24,8 +30,8 @@ export type Config = ControlConfig & {
   pagerDutyFailureThreshold?: number
 }
 
-const positiveInteger = (value: string | undefined, name: string, fallback: number): number => {
-  if (!value) return fallback
+const positiveInteger = (value: string | undefined, name: string, fallback?: number): number => {
+  if (!value && fallback !== undefined) return fallback
   const parsed = Number(value)
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
     throw new Error(`${name} must be a positive integer`)
@@ -42,10 +48,17 @@ export const loadControlConfig = (env: NodeJS.ProcessEnv = process.env): Control
 }
 
 export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
-  const telegramBotToken = env.TELEGRAM_BOT_TOKEN?.trim()
-  if (!telegramBotToken) throw new Error('TELEGRAM_BOT_TOKEN is required')
+  if (env.EZ_TELEGRAM_ENABLED !== undefined && !['true', 'false'].includes(env.EZ_TELEGRAM_ENABLED)) throw new Error('EZ_TELEGRAM_ENABLED must be true or false')
+  const telegramEnabled = env.EZ_TELEGRAM_ENABLED !== 'false'
+  const telegramBotToken = telegramEnabled ? env.TELEGRAM_BOT_TOKEN?.trim() || '' : ''
+  if (!telegramEnabled && !env.EZ_APPLICATION_PORT) throw new Error('Application-only execution requires EZ_APPLICATION_PORT')
+  if (telegramEnabled && !telegramBotToken) throw new Error('TELEGRAM_BOT_TOKEN is required')
 
   if (env.EZ_CHANNEL_BACKEND_URL && !env.EZ_CHANNEL_BACKEND_TOKEN?.trim()) throw new Error('EZ_CHANNEL_BACKEND_TOKEN is required')
+  if (env.EZ_APPLICATION_PORT && env.EZ_CHANNEL_BACKEND_URL) throw new Error('Application input requires the native Ez executor, not a channel backend')
+  const codexSandbox = env.EZ_CODEX_SANDBOX?.trim()
+  if (codexSandbox && codexSandbox !== 'external') throw new Error('EZ_CODEX_SANDBOX must be external or unset')
+  if (codexSandbox && (env.EZ_CHANNEL_BACKEND_URL || env.EZ_EXECUTOR_TRANSPORT !== 'local')) throw new Error('External Codex sandbox requires native local execution')
   const pagerDutyRoutingKey = env.PAGERDUTY_ROUTING_KEY?.trim()
   const pagerDutyStocksHealthUrl = env.EZ_PAGERDUTY_STOCKS_HEALTH_URL?.trim()
   if (pagerDutyStocksHealthUrl && !pagerDutyRoutingKey)
@@ -59,12 +72,17 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
   }
   return {
     ...loadControlConfig(env),
+    telegramEnabled,
+    webLauncher: parseWebLauncher(env.EZ_TELEGRAM_WEB_APP),
     telegramBotToken,
     repairEnabled: repairEnabled(env.EZ_REPAIR_ENABLED),
     workspace: path.resolve(env.EZ_AGENT_WORKSPACE?.trim() || './agent'),
     executorTimeoutMs: 0,
-    codexAutoCompactTokens: positiveInteger(env.EZ_CODEX_AUTO_COMPACT_TOKENS, 'EZ_CODEX_AUTO_COMPACT_TOKENS', 64000),
+    codexSandbox: codexSandbox === 'external' ? 'external' : undefined,
+    codexAutoCompactTokens: !env.EZ_CODEX_AUTO_COMPACT_TOKENS?.trim() ? undefined : positiveInteger(env.EZ_CODEX_AUTO_COMPACT_TOKENS, 'EZ_CODEX_AUTO_COMPACT_TOKENS'),
     executorCli: env.EZ_EXECUTOR_CLI?.trim() || 'agy',
+    applicationPort: env.EZ_APPLICATION_PORT ? positiveInteger(env.EZ_APPLICATION_PORT, 'EZ_APPLICATION_PORT') : undefined,
+    applicationHost: env.EZ_APPLICATION_HOST?.trim() || '127.0.0.1',
     channelBackendUrl: env.EZ_CHANNEL_BACKEND_URL?.trim(),
     channelBackendToken: env.EZ_CHANNEL_BACKEND_TOKEN?.trim(),
     geminiApiKey: env.GEMINI_API_KEY?.trim(),

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,14 +46,21 @@ 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
   pending: PairingRequest[]
   activeSession?: SessionState | null
-  ai?: { presets: AiPreset[]; defaultId: string; selectedId: string }
+  ai?: { presets: AiPreset[]; defaultId: string; selectedId: string; recentIds?: string[] }
   sessions?: SessionState[]
 }
 
@@ -42,6 +71,10 @@ const emptyState = (): ControlState => ({ version: 1, owner: null, pending: [] }
 const isPositiveId = (value: unknown): value is number =>
   typeof value === 'number' && Number.isSafeInteger(value) && value > 0
 
+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))
+
 const isState = (value: unknown): value is ControlState => {
   if (!value || typeof value !== 'object') return false
   const candidate = value as Partial<ControlState>
@@ -49,27 +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.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))
 
@@ -94,7 +156,12 @@ export class ControlStore {
     try {
       const parsed: unknown = JSON.parse(await readFile(this.statePath, 'utf8'))
       if (!isState(parsed)) throw new Error('Control state has an unsupported shape')
-      if (parsed.ai) parsed.ai.presets = parsed.ai.presets.map(persistedPreset)
+      if (parsed.ai) {
+        parsed.ai.presets = parsed.ai.presets.map(persistedPreset)
+        parsed.ai.recentIds = (parsed.ai.recentIds ?? [parsed.ai.selectedId])
+          .filter((id) => parsed.ai!.presets.some((preset) => preset.id === id))
+          .slice(0, 3)
+      }
       return parsed
     } catch (error: unknown) {
       if ((error as NodeJS.ErrnoException).code === 'ENOENT') return emptyState()
@@ -151,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,
@@ -174,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 = []
@@ -243,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
@@ -262,7 +439,7 @@ export class ControlStore {
   async aiState(initial: AiPreset) {
     return this.withLock(async () => {
       const state = await this.readState()
-      state.ai ??= { presets: [persistedPreset(initial)], defaultId: initial.id, selectedId: initial.id }
+      state.ai ??= { presets: [persistedPreset(initial)], defaultId: initial.id, selectedId: initial.id, recentIds: [] }
       await this.writeState(state)
       return state.ai
     })
@@ -274,29 +451,101 @@ export class ControlStore {
       const state = await this.readState()
       const first = initial.cli === 'codex' || initial.cli === 'codex-gui'
         ? initial : discovered.find((p) => p.cli === initial.cli) ?? initial
-      state.ai ??= { presets: [persistedPreset(first)], defaultId: first.id, selectedId: first.id }
+      state.ai ??= { presets: [persistedPreset(first)], defaultId: first.id, selectedId: first.id, recentIds: [] }
       const ai = state.ai
       // Refresh discovery entries, but never rewrite an active/default or user-saved choice.
       const preserved = ai.presets.filter((p) => !p.id.startsWith('detected_') ||
         p.id === ai.selectedId || p.id === ai.defaultId).map(persistedPreset)
       ai.presets = [...preserved, ...discovered.map(persistedPreset).filter((p) => !preserved.some((old) => old.id === p.id))]
+      ai.recentIds = (ai.recentIds ?? []).filter((id) => ai.presets.some((preset) => preset.id === id)).slice(0, 3)
       if (initial.id === 'chat-default' && !ai.presets.some(p => p.id === initial.id)) ai.presets.push(persistedPreset(initial))
       await this.writeState(state)
     })
   }
 
-  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 }
+      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
@@ -324,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.')
@@ -337,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')
@@ -348,10 +599,12 @@ 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 }
       }
       ai.selectedId = id
+      ai.recentIds = [id, ...(ai.recentIds ?? []).filter((recentId) => recentId !== id)].slice(0, 3)
       await this.writeState(state)
       return true
     })

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);
+}