@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1 → 2.1.0

package/src/bridge/react/usePlatformAgentSessionDrive.tsx

@@ -1,729 +1,749 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import {
-  AgentRunEventType,
-  createIdleLiveTurn,
-  isComposerEnabled,
-  mapAgentMessages,
-  mapApprovalPendingToolCalls,
-  mapRunState,
-  mergeUsageTurn,
-  reduceAgentLiveTurn,
-  withContextWindowUsage,
-  type PlatformAgentRunEventPayload,
-} from '../../agents/runtime/index.js'
-import type {
-  AgentLiveTurn,
-  AgentUiMessage,
-  AgentUiRunState,
-  AgentUiRunUsage,
-  AgentUiToolCall,
-} from '../../components/agents/agentTypes.js'
-import type {
-  PlatformAgentLlmMenuOption,
-  PlatformAgentRunSnapshot,
-  PlatformAgentSessionConfigPatch,
-  PlatformAgentSessionRecord,
-  PlatformAgentSessionScope,
-  PlatformAgentSessionSummary,
-  PlatformAgentSessionToolPolicy,
-} from '../agentTypes.js'
-import { isAgentAutoModelId, DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID } from '../agentModelTiers.js'
-import {
-  getPlatformPreferences,
-  patchPlatformPreferences,
-} from '../preferences.mjs'
-import {
-  advanceAgentSessionPending,
-  approveAgentSessionTools,
-  createAgentSession,
-  deleteAgentSession,
-  interruptAgentSession,
-  listAgentSessions,
-  onAgentRunEvent,
-  readAgentLlmMenuOptions,
-  readAgentSession,
-  rejectAgentSessionTools,
-  sendAgentSessionMessage,
-  updateAgentSession,
-} from '../agents.mjs'
-
-const DEFAULT_SESSION_TITLE = 'New chat'
-
-export interface UsePlatformAgentSessionDriveOptions {
-  /** App slug that owns app-scoped sessions and tool routing. */
-  appSlug: string
-  scope?: PlatformAgentSessionScope
-  enabled?: boolean
-  /**
-   * Bind to one specific session (e.g. an ephemeral thread that lives only while
-   * a modal is open). When set, the hook drives exactly this session and skips
-   * list auto-load and auto-create — the app owns its create/delete lifecycle.
-   */
-  sessionId?: string
-  /** Persisted to session metadata so the shell can restore the bound tab. */
-  restoreTabId?: string
-  /** Create a fresh session when the scope has none. Ignored when `sessionId` is set. Defaults to true. */
-  autoCreate?: boolean
-  rejectReason?: string
-}
-
-export interface UsePlatformAgentSessionDrive {
-  scope: PlatformAgentSessionScope
-  setScope: (scope: PlatformAgentSessionScope) => void
-  sessionRecord: PlatformAgentSessionRecord | null
-  sessionSummaries: PlatformAgentSessionSummary[]
-  sessionId: string | null
-  messages: AgentUiMessage[]
-  liveTurn: AgentLiveTurn
-  pendingToolCalls: AgentUiToolCall[]
-  runState: AgentUiRunState | null
-  busy: boolean
-  error: string | null
-  composerValue: string
-  setComposerValue: (value: string) => void
-  modelId: string
-  setModelId: (modelId: string) => Promise<void>
-  modelOptions: PlatformAgentLlmMenuOption[]
-  modelUnavailableReason: string | null
-  usage: AgentUiRunUsage | null
-  canSend: boolean
-  canInterrupt: boolean
-  interruptRun: (reason?: string) => Promise<void>
-  /** Send the composer value, or an explicit message (programmatic). Returns the final snapshot. */
-  sendMessage: (message?: string) => Promise<PlatformAgentRunSnapshot | null>
-  approveTools: (toolCallIds?: readonly string[]) => Promise<void>
-  approveToolAlwaysForSession: (
-    qualifiedName: string,
-    toolCallId: string,
-  ) => Promise<void>
-  rejectTools: (toolCallIds?: readonly string[]) => Promise<void>
-  selectSession: (sessionId: string) => Promise<void>
-  createNewSession: () => Promise<void>
-  deleteSession: () => Promise<void>
-  renameSession: (title: string) => Promise<void>
-  allowedTargetApps: string[]
-  setAllowedTargetApps: (slugs: readonly string[]) => Promise<void>
-  setToolApprovalOverride: (
-    qualifiedName: string,
-    requiresApproval: boolean,
-  ) => Promise<void>
-  refresh: () => Promise<void>
-}
-
-interface DriveResult {
-  session: PlatformAgentSessionRecord
-  snapshot: PlatformAgentRunSnapshot
-  effectiveToolPolicy?: PlatformAgentSessionToolPolicy
-  manualPendingToolCalls: AgentUiToolCall[]
-}
-
-/** Display snapshot from a persisted session record (before any live run this turn). */
-function recordSnapshot(
-  record: PlatformAgentSessionRecord | null,
-): PlatformAgentRunSnapshot | null {
-  if (!record) return null
-  return {
-    runId: record.runId ?? '',
-    state: record.snapshot.state,
-    turn: record.snapshot.turn,
-    messages: record.snapshot.messages,
-    error: record.snapshot.error,
-    interruptedReason: record.snapshot.interruptedReason,
-  }
-}
-
-function mergeScopeDefaultPatch(
-  base: PlatformAgentSessionConfigPatch | undefined,
-  patch: PlatformAgentSessionConfigPatch,
-): PlatformAgentSessionConfigPatch {
-  const toolPolicy =
-    patch.toolPolicy || base?.toolPolicy
-      ? {
-          ...base?.toolPolicy,
-          ...patch.toolPolicy,
-          approvalOverrides: {
-            ...base?.toolPolicy?.approvalOverrides,
-            ...patch.toolPolicy?.approvalOverrides,
-          },
-        }
-      : undefined
-  return { ...base, ...patch, ...(toolPolicy ? { toolPolicy } : {}) }
-}
-
-export function usePlatformAgentSessionDrive({
-  appSlug,
-  scope: initialScope = 'app',
-  enabled = true,
-  sessionId: boundSessionId,
-  restoreTabId,
-  autoCreate = true,
-  rejectReason,
-}: UsePlatformAgentSessionDriveOptions): UsePlatformAgentSessionDrive {
-  const [scope, setScope] = useState<PlatformAgentSessionScope>(initialScope)
-  const [sessionRecord, setSessionRecord] =
-    useState<PlatformAgentSessionRecord | null>(null)
-  const [sessionSummaries, setSessionSummaries] = useState<
-    PlatformAgentSessionSummary[]
-  >([])
-  const [snapshot, setSnapshot] = useState<PlatformAgentRunSnapshot | null>(
-    null,
-  )
-  const [policy, setPolicy] = useState<
-    PlatformAgentSessionToolPolicy | undefined
-  >(undefined)
-  const [drivePendingToolCalls, setDrivePendingToolCalls] = useState<
-    AgentUiToolCall[] | undefined
-  >(undefined)
-  const [liveTurn, setLiveTurn] = useState<AgentLiveTurn>(createIdleLiveTurn)
-  const [busy, setBusy] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-  const [composerValue, setComposerValue] = useState('')
-  const [optimisticModelId, setOptimisticModelId] = useState<string | null>(
-    null,
-  )
-  const [modelOptions, setModelOptions] = useState<
-    PlatformAgentLlmMenuOption[]
-  >([])
-
-  // one active run per hook instance. Latches runId from the first
-  // forwarded event so first-turn streaming works before the RPC resolves.
-  // Upgrade path: thread an explicit runId if one iframe drives many runs at once.
-  const activeRunIdRef = useRef<string | undefined>(undefined)
-  const stopRequestedRef = useRef(false)
-
-  const scopeAppSlug = scope === 'app' ? appSlug : undefined
-
-  const sessionQuery = useCallback(
-    (sessionId: string) => ({ scope, sessionId, appSlug: scopeAppSlug }),
-    [scope, scopeAppSlug],
-  )
-
-  const refreshSessionList = useCallback(async () => {
-    const listed = await listAgentSessions({ scope, appSlug: scopeAppSlug })
-    setSessionSummaries(listed)
-    return listed
-  }, [scope, scopeAppSlug])
-
-  const adoptRecord = useCallback((record: PlatformAgentSessionRecord) => {
-    setSessionRecord(record)
-    setSnapshot(null)
-    setPolicy(undefined)
-    setDrivePendingToolCalls(undefined)
-    setLiveTurn(createIdleLiveTurn())
-    activeRunIdRef.current = record.runId
-  }, [])
-
-  const applyDriveResult = useCallback((result: DriveResult) => {
-    setSessionRecord(result.session)
-    setSnapshot(result.snapshot)
-    setPolicy(result.effectiveToolPolicy)
-    setDrivePendingToolCalls(result.manualPendingToolCalls)
-    activeRunIdRef.current = result.snapshot.runId
-    setLiveTurn(createIdleLiveTurn())
-  }, [])
-
-  const settlePersistedPending = useCallback(
-    async (record: PlatformAgentSessionRecord) => {
-      if (record.snapshot.state !== 'pending_tools') return
-      const result = await advanceAgentSessionPending({
-        session: sessionQuery(record.sessionId),
-      })
-      if (result) applyDriveResult(result)
-    },
-    [applyDriveResult, sessionQuery],
-  )
-
-  const loadSession = useCallback(async () => {
-    // Bound mode: drive exactly the app-owned session, no list/auto-create.
-    if (boundSessionId) {
-      const record = await readAgentSession(sessionQuery(boundSessionId))
-      adoptRecord(record)
-      await settlePersistedPending(record)
-      return
-    }
-    const listed = await refreshSessionList()
-    const first = listed[0]
-    if (first) {
-      const record = await readAgentSession(sessionQuery(first.sessionId))
-      adoptRecord(record)
-      await settlePersistedPending(record)
-      return
-    }
-    if (!autoCreate) {
-      setSessionRecord(null)
-      return
-    }
-    const created = await createAgentSession({
-      scope,
-      appSlug: scopeAppSlug,
-      title: DEFAULT_SESSION_TITLE,
-      restoreTabId,
-    })
-    adoptRecord(created)
-    await refreshSessionList()
-  }, [
-    adoptRecord,
-    autoCreate,
-    boundSessionId,
-    refreshSessionList,
-    restoreTabId,
-    scope,
-    scopeAppSlug,
-    sessionQuery,
-    settlePersistedPending,
-  ])
-
-  useEffect(() => {
-    if (!enabled) return
-    let cancelled = false
-    void loadSession().catch((cause: unknown) => {
-      if (!cancelled) {
-        setError(cause instanceof Error ? cause.message : String(cause))
-      }
-    })
-    return () => {
-      cancelled = true
-    }
-  }, [enabled, loadSession])
-
-  useEffect(() => {
-    if (!enabled) return
-    let cancelled = false
-    void readAgentLlmMenuOptions({})
-      .then(options => {
-        if (!cancelled) setModelOptions(options)
-      })
-      .catch(() => {
-        if (!cancelled) setModelOptions([])
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [enabled])
-
-  useEffect(() => {
-    setOptimisticModelId(null)
-  }, [sessionRecord?.sessionId])
-
-  // Streaming: persistent listener; latches runId from forwarded events.
-  useEffect(() => {
-    if (!enabled) return
-    let live = createIdleLiveTurn()
-    const unsubscribe = onAgentRunEvent(event => {
-      const payload = event as PlatformAgentRunEventPayload
-      const runId = activeRunIdRef.current
-      if (runId && payload.runId !== runId) return
-      if (!runId) activeRunIdRef.current = payload.runId
-
-      if (
-        payload.type === AgentRunEventType.StateChanged &&
-        'snapshot' in payload
-      ) {
-        setSnapshot({ ...payload.snapshot })
-      }
-      if (payload.type === AgentRunEventType.UsageUpdated) {
-        setSnapshot(current =>
-          current
-            ? {
-                ...current,
-                usage: mergeUsageTurn(
-                  current.usage,
-                  payload.usage,
-                  payload.estimated,
-                ),
-              }
-            : current,
-        )
-      }
-
-      live = reduceAgentLiveTurn(live, payload)
-      setLiveTurn(live)
-    })
-    return unsubscribe
-  }, [enabled, sessionRecord?.sessionId])
-
-  const refresh = useCallback(async () => {
-    if (!sessionRecord) return
-    const record = await readAgentSession(sessionQuery(sessionRecord.sessionId))
-    setSessionRecord(record)
-  }, [sessionQuery, sessionRecord])
-
-  const drive = useCallback(
-    async (
-      run: () => Promise<DriveResult | null>,
-    ): Promise<DriveResult | null> => {
-      if (!enabled || busy) return null
-      setBusy(true)
-      setError(null)
-      try {
-        const result = await run()
-        if (!result) return null
-        applyDriveResult(result)
-        await refreshSessionList()
-        return result
-      } catch (cause) {
-        if (!stopRequestedRef.current) {
-          setError(cause instanceof Error ? cause.message : String(cause))
-        }
-        setLiveTurn(createIdleLiveTurn())
-        return null
-      } finally {
-        stopRequestedRef.current = false
-        setBusy(false)
-      }
-    },
-    [applyDriveResult, busy, enabled, refreshSessionList],
-  )
-
-  const committed = useMemo(
-    () => snapshot ?? recordSnapshot(sessionRecord),
-    [sessionRecord, snapshot],
-  )
-  const displaySnapshot = useMemo(
-    () => recordSnapshot(sessionRecord),
-    [sessionRecord],
-  )
-  const threadSnapshot = useMemo(() => {
-    if (busy && snapshot) return snapshot
-    return committed
-  }, [busy, committed, snapshot])
-  const runState = displaySnapshot ? mapRunState(displaySnapshot.state) : null
-
-  const selectedModelId =
-    optimisticModelId ?? sessionRecord?.config.modelId ?? 'auto'
-
-  const modelUnavailableReason = useMemo(() => {
-    if (isAgentAutoModelId(selectedModelId)) return null
-    if (modelOptions.length === 0) return null
-    const known = modelOptions.some(option => option.value === selectedModelId)
-    return known
-      ? null
-      : 'This model is not available. Check API keys or local runtime in Settings.'
-  }, [modelOptions, selectedModelId])
-
-  const toolPolicy =
-    policy ?? sessionRecord?.config?.toolPolicy ?? undefined
-
-  const pendingToolCalls = useMemo(() => {
-    if (drivePendingToolCalls !== undefined) return drivePendingToolCalls
-    return mapApprovalPendingToolCalls(threadSnapshot, toolPolicy)
-  }, [drivePendingToolCalls, threadSnapshot, toolPolicy])
-  const messages = useMemo(
-    () => mapAgentMessages(threadSnapshot, liveTurn),
-    [liveTurn, threadSnapshot],
-  )
-  const canSend =
-    enabled &&
-    isComposerEnabled(runState, busy) &&
-    !modelUnavailableReason &&
-    composerValue.trim().length > 0
-
-  const canInterrupt = enabled && busy && sessionRecord !== null
-
-  const contextWindowByModelId = useMemo(() => {
-    const map = new Map<string, number>()
-    for (const option of modelOptions) {
-      if (option.contextWindowTokens) {
-        map.set(option.value, option.contextWindowTokens)
-      }
-    }
-    return map
-  }, [modelOptions])
-
-  const usage = useMemo<AgentUiRunUsage | null>(() => {
-    const raw = threadSnapshot?.usage
-    if (!raw) return null
-    if (raw.contextWindowTokens) return raw
-    const modelId =
-      threadSnapshot?.effectiveModelId ??
-      (isAgentAutoModelId(selectedModelId)
-        ? DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID
-        : selectedModelId)
-    return (
-      withContextWindowUsage(raw, contextWindowByModelId.get(modelId)) ?? raw
-    )
-  }, [contextWindowByModelId, selectedModelId, threadSnapshot])
-
-  const sendMessage = useCallback(
-    async (
-      messageOverride?: string,
-    ): Promise<PlatformAgentRunSnapshot | null> => {
-      const message = (messageOverride ?? composerValue).trim()
-      if (!message || !sessionRecord) return null
-      // Composer sends respect canSend; programmatic sends only respect busy.
-      if (messageOverride === undefined && !canSend) return null
-      const result = await drive(async () => {
-        const driven = await sendAgentSessionMessage({
-          session: sessionQuery(sessionRecord.sessionId),
-          message,
-        })
-        if (messageOverride === undefined) setComposerValue('')
-        return driven
-      })
-      return result?.snapshot ?? null
-    },
-    [canSend, composerValue, drive, sessionQuery, sessionRecord],
-  )
-
-  const approveTools = useCallback(
-    async (toolCallIds?: readonly string[]) => {
-      if (!sessionRecord || pendingToolCalls.length === 0) return
-      await drive(async () => {
-        const driven = await approveAgentSessionTools({
-          session: sessionQuery(sessionRecord.sessionId),
-          ...(toolCallIds?.length ? { toolCallIds: [...toolCallIds] } : {}),
-        })
-        return driven
-      })
-    },
-    [drive, pendingToolCalls.length, sessionQuery, sessionRecord],
-  )
-
-  const rejectTools = useCallback(
-    async (toolCallIds?: readonly string[]) => {
-      if (!sessionRecord || pendingToolCalls.length === 0) return
-      await drive(async () =>
-        rejectAgentSessionTools({
-          session: sessionQuery(sessionRecord.sessionId),
-          rejectReason,
-          ...(toolCallIds?.length ? { toolCallIds: [...toolCallIds] } : {}),
-        }),
-      )
-    },
-    [drive, pendingToolCalls.length, rejectReason, sessionQuery, sessionRecord],
-  )
-
-  const interruptRun = useCallback(
-    async (reason?: string) => {
-      if (!enabled || !sessionRecord || !canInterrupt) return
-      stopRequestedRef.current = true
-      setError(null)
-      try {
-        const result = await interruptAgentSession({
-          session: sessionQuery(sessionRecord.sessionId),
-          reason,
-        })
-        applyDriveResult(result)
-        await refreshSessionList()
-      } catch (cause) {
-        if (!stopRequestedRef.current) {
-          setError(cause instanceof Error ? cause.message : String(cause))
-        }
-      } finally {
-        stopRequestedRef.current = false
-        setBusy(false)
-      }
-    },
-    [applyDriveResult, canInterrupt, enabled, refreshSessionList, sessionQuery, sessionRecord],
-  )
-
-  const selectSession = useCallback(
-    async (sessionId: string) => {
-      const record = await readAgentSession(sessionQuery(sessionId))
-      adoptRecord(record)
-      setComposerValue('')
-      setError(null)
-      await settlePersistedPending(record)
-    },
-    [adoptRecord, sessionQuery, settlePersistedPending],
-  )
-
-  const createNewSession = useCallback(async () => {
-    const created = await createAgentSession({
-      scope,
-      appSlug: scopeAppSlug,
-      title: DEFAULT_SESSION_TITLE,
-      restoreTabId,
-    })
-    adoptRecord(created)
-    setComposerValue('')
-    await refreshSessionList()
-  }, [adoptRecord, refreshSessionList, restoreTabId, scope, scopeAppSlug])
-
-  const deleteSession = useCallback(async () => {
-    if (!sessionRecord) return
-    await deleteAgentSession(sessionQuery(sessionRecord.sessionId))
-    const listed = await refreshSessionList()
-    const next = listed[0]
-    if (next) {
-      await selectSession(next.sessionId)
-      return
-    }
-    if (autoCreate) await createNewSession()
-    else setSessionRecord(null)
-  }, [
-    autoCreate,
-    createNewSession,
-    refreshSessionList,
-    selectSession,
-    sessionQuery,
-    sessionRecord,
-  ])
-
-  const renameSession = useCallback(
-    async (title: string) => {
-      if (!sessionRecord) return
-      const trimmed = title.trim()
-      if (!trimmed) return
-      const updated = await updateAgentSession({
-        query: sessionQuery(sessionRecord.sessionId),
-        patch: { metadata: { title: trimmed } },
-      })
-      setSessionRecord(updated)
-      await refreshSessionList()
-    },
-    [refreshSessionList, sessionQuery, sessionRecord],
-  )
-
-  const persistScopeDefault = useCallback(
-    async (patch: PlatformAgentSessionConfigPatch) => {
-      try {
-        const prefs = (await getPlatformPreferences()) as {
-          agentSessionDefaults?: {
-            global?: PlatformAgentSessionConfigPatch
-            apps?: Record<string, PlatformAgentSessionConfigPatch>
-          }
-        }
-        const stored = prefs.agentSessionDefaults ?? {}
-        if (scope === 'global') {
-          await patchPlatformPreferences({
-            agentSessionDefaults: {
-              ...stored,
-              global: mergeScopeDefaultPatch(stored.global, patch),
-            },
-          })
-          return
-        }
-        if (!scopeAppSlug) return
-        const apps = { ...(stored.apps ?? {}) }
-        apps[scopeAppSlug] = mergeScopeDefaultPatch(apps[scopeAppSlug], patch)
-        await patchPlatformPreferences({
-          agentSessionDefaults: { ...stored, apps },
-        })
-      } catch {
-        /* scope defaults are best-effort */
-      }
-    },
-    [scope, scopeAppSlug],
-  )
-
-  const setModelId = useCallback(
-    async (modelId: string) => {
-      if (!sessionRecord) return
-      setOptimisticModelId(modelId)
-      try {
-        const updated = await updateAgentSession({
-          query: sessionQuery(sessionRecord.sessionId),
-          patch: { config: { modelId } },
-        })
-        setSessionRecord(updated)
-        setOptimisticModelId(null)
-        await persistScopeDefault({ modelId })
-      } catch (cause) {
-        setOptimisticModelId(null)
-        setError(cause instanceof Error ? cause.message : String(cause))
-      }
-    },
-    [persistScopeDefault, sessionQuery, sessionRecord],
-  )
-
-  const allowedTargetApps =
-    sessionRecord?.config.toolPolicy?.allowedTargetApps ?? []
-
-  const setAllowedTargetApps = useCallback(
-    async (slugs: readonly string[]) => {
-      if (!sessionRecord) return
-      const normalized = [
-        ...new Set(slugs.map(slug => slug.trim()).filter(Boolean)),
-      ]
-      const updated = await updateAgentSession({
-        query: sessionQuery(sessionRecord.sessionId),
-        patch: { config: { toolPolicy: { allowedTargetApps: normalized } } },
-      })
-      setSessionRecord(updated)
-      await persistScopeDefault({
-        toolPolicy: { allowedTargetApps: normalized },
-      })
-    },
-    [persistScopeDefault, sessionQuery, sessionRecord],
-  )
-
-  const setToolApprovalOverride = useCallback(
-    async (qualifiedName: string, requiresApproval: boolean) => {
-      if (!sessionRecord) return
-      const overrides = {
-        ...sessionRecord.config.toolPolicy?.approvalOverrides,
-        [qualifiedName]: requiresApproval,
-      }
-      const updated = await updateAgentSession({
-        query: sessionQuery(sessionRecord.sessionId),
-        patch: { config: { toolPolicy: { approvalOverrides: overrides } } },
-      })
-      setSessionRecord(updated)
-      await persistScopeDefault({
-        toolPolicy: { approvalOverrides: overrides },
-      })
-    },
-    [persistScopeDefault, sessionQuery, sessionRecord],
-  )
-
-  const approveToolAlwaysForSession = useCallback(
-    async (qualifiedName: string, toolCallId: string) => {
-      if (!sessionRecord) return
-      await drive(async () => {
-        const overrides = {
-          ...sessionRecord.config.toolPolicy?.approvalOverrides,
-          [qualifiedName]: false,
-        }
-        const updated = await updateAgentSession({
-          query: sessionQuery(sessionRecord.sessionId),
-          patch: { config: { toolPolicy: { approvalOverrides: overrides } } },
-        })
-        await persistScopeDefault({
-          toolPolicy: { approvalOverrides: overrides },
-        })
-        return approveAgentSessionTools({
-          session: sessionQuery(updated.sessionId),
-          toolCallIds: [toolCallId],
-        })
-      })
-    },
-    [drive, persistScopeDefault, sessionQuery, sessionRecord],
-  )
-
-  return {
-    scope,
-    setScope,
-    sessionRecord,
-    sessionSummaries,
-    sessionId: sessionRecord?.sessionId ?? null,
-    messages,
-    liveTurn,
-    pendingToolCalls,
-    runState,
-    busy,
-    error,
-    composerValue,
-    setComposerValue,
-    modelId: selectedModelId,
-    setModelId,
-    modelOptions,
-    modelUnavailableReason,
-    usage,
-    canSend,
-    canInterrupt,
-    sendMessage,
-    interruptRun,
-    approveTools,
-    approveToolAlwaysForSession,
-    rejectTools,
-    selectSession,
-    createNewSession,
-    deleteSession,
-    renameSession,
-    allowedTargetApps,
-    setAllowedTargetApps,
-    setToolApprovalOverride,
-    refresh,
-  }
-}
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  AgentRunEventType,
+  createIdleLiveTurn,
+  isComposerEnabled,
+  mapAgentMessages,
+  mapApprovalPendingToolCalls,
+  mapRunState,
+  mergeUsageTurn,
+  reduceAgentLiveTurn,
+  withContextWindowUsage,
+  type PlatformAgentRunEventPayload,
+} from '../../agents/runtime/index.js'
+import type {
+  AgentLiveTurn,
+  AgentUiMessage,
+  AgentUiRunState,
+  AgentUiRunUsage,
+  AgentUiToolCall,
+} from '../../components/agents/agentTypes.js'
+import type {
+  PlatformAgentLlmMenuOption,
+  PlatformAgentRunSnapshot,
+  PlatformAgentSessionConfigPatch,
+  PlatformAgentSessionRecord,
+  PlatformAgentSessionScope,
+  PlatformAgentSessionSummary,
+  PlatformAgentSessionToolPolicy,
+} from '../agentTypes.js'
+import { isAgentAutoModelId, DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID } from '../agentModelTiers.js'
+import {
+  getPlatformPreferences,
+  patchPlatformPreferences,
+} from '../preferences.mjs'
+import {
+  advanceAgentSessionPending,
+  approveAgentSessionTools,
+  createAgentSession,
+  deleteAgentSession,
+  interruptAgentSession,
+  listAgentSessions,
+  onAgentRunEvent,
+  readAgentLlmMenuOptions,
+  readAgentSession,
+  rejectAgentSessionTools,
+  sendAgentSessionMessage,
+  updateAgentSession,
+} from '../agents.mjs'
+
+const DEFAULT_SESSION_TITLE = 'New chat'
+
+export interface UsePlatformAgentSessionDriveOptions {
+  /** App slug that owns app-scoped sessions and tool routing. */
+  appSlug: string
+  scope?: PlatformAgentSessionScope
+  enabled?: boolean
+  /**
+   * Bind to one specific session (e.g. an ephemeral thread that lives only while
+   * a modal is open). When set, the hook drives exactly this session and skips
+   * list auto-load and auto-create — the app owns its create/delete lifecycle.
+   */
+  sessionId?: string
+  /** Persisted to session metadata so the shell can restore the bound tab. */
+  restoreTabId?: string
+  /** Create a fresh session when the scope has none. Ignored when `sessionId` is set. Defaults to true. */
+  autoCreate?: boolean
+  rejectReason?: string
+}
+
+export interface UsePlatformAgentSessionDrive {
+  scope: PlatformAgentSessionScope
+  setScope: (scope: PlatformAgentSessionScope) => void
+  sessionRecord: PlatformAgentSessionRecord | null
+  sessionSummaries: PlatformAgentSessionSummary[]
+  sessionId: string | null
+  messages: AgentUiMessage[]
+  liveTurn: AgentLiveTurn
+  pendingToolCalls: AgentUiToolCall[]
+  runState: AgentUiRunState | null
+  busy: boolean
+  error: string | null
+  composerValue: string
+  setComposerValue: (value: string) => void
+  modelId: string
+  setModelId: (modelId: string) => Promise<void>
+  modelOptions: PlatformAgentLlmMenuOption[]
+  modelUnavailableReason: string | null
+  usage: AgentUiRunUsage | null
+  canSend: boolean
+  canInterrupt: boolean
+  interruptRun: (reason?: string) => Promise<void>
+  /** Send the composer value, or an explicit message (programmatic). Returns the final snapshot. */
+  sendMessage: (message?: string) => Promise<PlatformAgentRunSnapshot | null>
+  approveTools: (toolCallIds?: readonly string[]) => Promise<void>
+  approveToolAlwaysForSession: (
+    qualifiedName: string,
+    toolCallId: string,
+  ) => Promise<void>
+  rejectTools: (toolCallIds?: readonly string[]) => Promise<void>
+  selectSession: (sessionId: string) => Promise<void>
+  createNewSession: () => Promise<void>
+  deleteSession: () => Promise<void>
+  renameSession: (title: string) => Promise<void>
+  allowedTargetApps: string[]
+  setAllowedTargetApps: (slugs: readonly string[]) => Promise<void>
+  setToolApprovalOverride: (
+    qualifiedName: string,
+    requiresApproval: boolean,
+  ) => Promise<void>
+  refresh: () => Promise<void>
+}
+
+interface DriveResult {
+  session: PlatformAgentSessionRecord
+  snapshot: PlatformAgentRunSnapshot
+  effectiveToolPolicy?: PlatformAgentSessionToolPolicy
+  manualPendingToolCalls: AgentUiToolCall[]
+}
+
+/** Display snapshot from a persisted session record (before any live run this turn). */
+function recordSnapshot(
+  record: PlatformAgentSessionRecord | null,
+): PlatformAgentRunSnapshot | null {
+  if (!record) return null
+  return {
+    runId: record.runId ?? '',
+    state: record.snapshot.state,
+    turn: record.snapshot.turn,
+    messages: record.snapshot.messages,
+    error: record.snapshot.error,
+    interruptedReason: record.snapshot.interruptedReason,
+  }
+}
+
+function mergeScopeDefaultPatch(
+  base: PlatformAgentSessionConfigPatch | undefined,
+  patch: PlatformAgentSessionConfigPatch,
+): PlatformAgentSessionConfigPatch {
+  const toolPolicy =
+    patch.toolPolicy || base?.toolPolicy
+      ? {
+          ...base?.toolPolicy,
+          ...patch.toolPolicy,
+          approvalOverrides: {
+            ...base?.toolPolicy?.approvalOverrides,
+            ...patch.toolPolicy?.approvalOverrides,
+          },
+        }
+      : undefined
+  return { ...base, ...patch, ...(toolPolicy ? { toolPolicy } : {}) }
+}
+
+export function usePlatformAgentSessionDrive({
+  appSlug,
+  scope: initialScope = 'app',
+  enabled = true,
+  sessionId: boundSessionId,
+  restoreTabId,
+  autoCreate = true,
+  rejectReason,
+}: UsePlatformAgentSessionDriveOptions): UsePlatformAgentSessionDrive {
+  const [scope, setScope] = useState<PlatformAgentSessionScope>(initialScope)
+  const [sessionRecord, setSessionRecord] =
+    useState<PlatformAgentSessionRecord | null>(null)
+  const [sessionSummaries, setSessionSummaries] = useState<
+    PlatformAgentSessionSummary[]
+  >([])
+  const [snapshot, setSnapshot] = useState<PlatformAgentRunSnapshot | null>(
+    null,
+  )
+  const [policy, setPolicy] = useState<
+    PlatformAgentSessionToolPolicy | undefined
+  >(undefined)
+  const [drivePendingToolCalls, setDrivePendingToolCalls] = useState<
+    AgentUiToolCall[] | undefined
+  >(undefined)
+  const [liveTurn, setLiveTurn] = useState<AgentLiveTurn>(createIdleLiveTurn)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [composerValue, setComposerValue] = useState('')
+  const [optimisticModelId, setOptimisticModelId] = useState<string | null>(
+    null,
+  )
+  const [modelOptions, setModelOptions] = useState<
+    PlatformAgentLlmMenuOption[]
+  >([])
+
+  // one active run per hook instance. Latches runId from the first
+  // forwarded event so first-turn streaming works before the RPC resolves.
+  // Upgrade path: thread an explicit runId if one iframe drives many runs at once.
+  const activeRunIdRef = useRef<string | undefined>(undefined)
+  const stopRequestedRef = useRef(false)
+
+  const scopeAppSlug = scope === 'app' ? appSlug : undefined
+
+  const sessionQuery = useCallback(
+    (sessionId: string) => ({ scope, sessionId, appSlug: scopeAppSlug }),
+    [scope, scopeAppSlug],
+  )
+
+  const refreshSessionList = useCallback(async () => {
+    const listed = await listAgentSessions({ scope, appSlug: scopeAppSlug })
+    setSessionSummaries(listed)
+    return listed
+  }, [scope, scopeAppSlug])
+
+  const adoptRecord = useCallback((record: PlatformAgentSessionRecord) => {
+    setSessionRecord(record)
+    setSnapshot(null)
+    setPolicy(undefined)
+    setDrivePendingToolCalls(undefined)
+    setLiveTurn(createIdleLiveTurn())
+    activeRunIdRef.current = record.runId
+  }, [])
+
+  const applyDriveResult = useCallback((result: DriveResult) => {
+    setSessionRecord(result.session)
+    setSnapshot(result.snapshot)
+    setPolicy(result.effectiveToolPolicy)
+    setDrivePendingToolCalls(result.manualPendingToolCalls)
+    activeRunIdRef.current = result.snapshot.runId
+    setLiveTurn(createIdleLiveTurn())
+  }, [])
+
+  const settlePersistedPending = useCallback(
+    async (record: PlatformAgentSessionRecord) => {
+      if (record.snapshot.state !== 'pending_tools') return
+      const result = await advanceAgentSessionPending({
+        session: sessionQuery(record.sessionId),
+      })
+      if (result) applyDriveResult(result)
+    },
+    [applyDriveResult, sessionQuery],
+  )
+
+  const loadSession = useCallback(async () => {
+    // Bound mode: drive exactly the app-owned session, no list/auto-create.
+    if (boundSessionId) {
+      const record = await readAgentSession(sessionQuery(boundSessionId))
+      adoptRecord(record)
+      await settlePersistedPending(record)
+      return
+    }
+    const listed = await refreshSessionList()
+    const first = listed[0]
+    if (first) {
+      const record = await readAgentSession(sessionQuery(first.sessionId))
+      adoptRecord(record)
+      await settlePersistedPending(record)
+      return
+    }
+    if (!autoCreate) {
+      setSessionRecord(null)
+      return
+    }
+    const created = await createAgentSession({
+      scope,
+      appSlug: scopeAppSlug,
+      title: DEFAULT_SESSION_TITLE,
+      restoreTabId,
+    })
+    adoptRecord(created)
+    await refreshSessionList()
+  }, [
+    adoptRecord,
+    autoCreate,
+    boundSessionId,
+    refreshSessionList,
+    restoreTabId,
+    scope,
+    scopeAppSlug,
+    sessionQuery,
+    settlePersistedPending,
+  ])
+
+  useEffect(() => {
+    if (!enabled) return
+    let cancelled = false
+    void loadSession().catch((cause: unknown) => {
+      if (!cancelled) {
+        setError(cause instanceof Error ? cause.message : String(cause))
+      }
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [enabled, loadSession])
+
+  useEffect(() => {
+    if (!enabled) return
+    let cancelled = false
+    void readAgentLlmMenuOptions({})
+      .then(options => {
+        if (!cancelled) setModelOptions(options)
+      })
+      .catch(() => {
+        if (!cancelled) setModelOptions([])
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [enabled])
+
+  useEffect(() => {
+    setOptimisticModelId(null)
+  }, [sessionRecord?.sessionId])
+
+  // Streaming: persistent listener; latches runId from forwarded events.
+  useEffect(() => {
+    if (!enabled) return
+    let live = createIdleLiveTurn()
+    const unsubscribe = onAgentRunEvent(event => {
+      const payload = event as PlatformAgentRunEventPayload
+      const runId = activeRunIdRef.current
+      if (runId && payload.runId !== runId) return
+      if (!runId) activeRunIdRef.current = payload.runId
+
+      if (
+        payload.type === AgentRunEventType.StateChanged &&
+        'snapshot' in payload
+      ) {
+        setSnapshot({ ...payload.snapshot })
+      }
+      if (payload.type === AgentRunEventType.UsageUpdated) {
+        setSnapshot(current =>
+          current
+            ? {
+                ...current,
+                usage: mergeUsageTurn(
+                  current.usage,
+                  payload.usage,
+                  payload.estimated,
+                ),
+              }
+            : current,
+        )
+      }
+
+      live = reduceAgentLiveTurn(live, payload)
+      setLiveTurn(live)
+    })
+    return unsubscribe
+  }, [enabled, sessionRecord?.sessionId])
+
+  const refresh = useCallback(async () => {
+    if (!sessionRecord) return
+    const record = await readAgentSession(sessionQuery(sessionRecord.sessionId))
+    setSessionRecord(record)
+  }, [sessionQuery, sessionRecord])
+
+  const drive = useCallback(
+    async (
+      run: () => Promise<DriveResult | null>,
+    ): Promise<DriveResult | null> => {
+      if (!enabled || busy) return null
+      setBusy(true)
+      setError(null)
+      try {
+        const result = await run()
+        if (!result) return null
+        applyDriveResult(result)
+        await refreshSessionList()
+        return result
+      } catch (cause) {
+        if (!stopRequestedRef.current) {
+          setError(cause instanceof Error ? cause.message : String(cause))
+        }
+        setLiveTurn(createIdleLiveTurn())
+        return null
+      } finally {
+        stopRequestedRef.current = false
+        setBusy(false)
+      }
+    },
+    [applyDriveResult, busy, enabled, refreshSessionList],
+  )
+
+  const committed = useMemo(
+    () => snapshot ?? recordSnapshot(sessionRecord),
+    [sessionRecord, snapshot],
+  )
+  const displaySnapshot = useMemo(
+    () => recordSnapshot(sessionRecord),
+    [sessionRecord],
+  )
+  const threadSnapshot = useMemo(() => {
+    if (busy && snapshot) return snapshot
+    return committed
+  }, [busy, committed, snapshot])
+  const runState = displaySnapshot ? mapRunState(displaySnapshot.state) : null
+
+  const selectedModelId =
+    optimisticModelId ?? sessionRecord?.config.modelId ?? 'auto'
+
+  const modelUnavailableReason = useMemo(() => {
+    if (isAgentAutoModelId(selectedModelId)) return null
+    if (modelOptions.length === 0) return null
+    const known = modelOptions.some(option => option.value === selectedModelId)
+    return known
+      ? null
+      : 'This model is not available. Check API keys or local runtime in Settings.'
+  }, [modelOptions, selectedModelId])
+
+  const toolPolicy =
+    policy ?? sessionRecord?.config?.toolPolicy ?? undefined
+  const acceptedPendingToolCallIds = useMemo(
+    () =>
+      sessionRecord?.runId && sessionRecord.runId === threadSnapshot?.runId
+        ? sessionRecord.snapshot.acceptedPendingToolCallIds ?? []
+        : [],
+    [
+      sessionRecord?.runId,
+      sessionRecord?.snapshot.acceptedPendingToolCallIds,
+      threadSnapshot?.runId,
+    ],
+  )
+
+  const pendingToolCalls = useMemo(() => {
+    if (drivePendingToolCalls !== undefined) return drivePendingToolCalls
+    return mapApprovalPendingToolCalls(
+      threadSnapshot,
+      toolPolicy,
+      acceptedPendingToolCallIds,
+    )
+  }, [
+    acceptedPendingToolCallIds,
+    drivePendingToolCalls,
+    threadSnapshot,
+    toolPolicy,
+  ])
+  const messages = useMemo(
+    () => mapAgentMessages(threadSnapshot, liveTurn),
+    [liveTurn, threadSnapshot],
+  )
+  const canSend =
+    enabled &&
+    isComposerEnabled(runState, busy) &&
+    !modelUnavailableReason &&
+    composerValue.trim().length > 0
+
+  const canInterrupt = enabled && busy && sessionRecord !== null
+
+  const contextWindowByModelId = useMemo(() => {
+    const map = new Map<string, number>()
+    for (const option of modelOptions) {
+      if (option.contextWindowTokens) {
+        map.set(option.value, option.contextWindowTokens)
+      }
+    }
+    return map
+  }, [modelOptions])
+
+  const usage = useMemo<AgentUiRunUsage | null>(() => {
+    const raw = threadSnapshot?.usage
+    if (!raw) return null
+    if (raw.contextWindowTokens) return raw
+    const modelId =
+      threadSnapshot?.effectiveModelId ??
+      (isAgentAutoModelId(selectedModelId)
+        ? DEFAULT_AGENT_HIGH_LEVEL_MODEL_ID
+        : selectedModelId)
+    return (
+      withContextWindowUsage(raw, contextWindowByModelId.get(modelId)) ?? raw
+    )
+  }, [contextWindowByModelId, selectedModelId, threadSnapshot])
+
+  const sendMessage = useCallback(
+    async (
+      messageOverride?: string,
+    ): Promise<PlatformAgentRunSnapshot | null> => {
+      const message = (messageOverride ?? composerValue).trim()
+      if (!message || !sessionRecord) return null
+      // Composer sends respect canSend; programmatic sends only respect busy.
+      if (messageOverride === undefined && !canSend) return null
+      const result = await drive(async () => {
+        const driven = await sendAgentSessionMessage({
+          session: sessionQuery(sessionRecord.sessionId),
+          message,
+        })
+        if (messageOverride === undefined) setComposerValue('')
+        return driven
+      })
+      return result?.snapshot ?? null
+    },
+    [canSend, composerValue, drive, sessionQuery, sessionRecord],
+  )
+
+  const approveTools = useCallback(
+    async (toolCallIds?: readonly string[]) => {
+      if (!sessionRecord || pendingToolCalls.length === 0) return
+      await drive(async () => {
+        const driven = await approveAgentSessionTools({
+          session: sessionQuery(sessionRecord.sessionId),
+          ...(toolCallIds?.length ? { toolCallIds: [...toolCallIds] } : {}),
+        })
+        return driven
+      })
+    },
+    [drive, pendingToolCalls.length, sessionQuery, sessionRecord],
+  )
+
+  const rejectTools = useCallback(
+    async (toolCallIds?: readonly string[]) => {
+      if (!sessionRecord || pendingToolCalls.length === 0) return
+      await drive(async () =>
+        rejectAgentSessionTools({
+          session: sessionQuery(sessionRecord.sessionId),
+          rejectReason,
+          ...(toolCallIds?.length ? { toolCallIds: [...toolCallIds] } : {}),
+        }),
+      )
+    },
+    [drive, pendingToolCalls.length, rejectReason, sessionQuery, sessionRecord],
+  )
+
+  const interruptRun = useCallback(
+    async (reason?: string) => {
+      if (!enabled || !sessionRecord || !canInterrupt) return
+      stopRequestedRef.current = true
+      setError(null)
+      try {
+        const result = await interruptAgentSession({
+          session: sessionQuery(sessionRecord.sessionId),
+          reason,
+        })
+        applyDriveResult(result)
+        await refreshSessionList()
+      } catch (cause) {
+        if (!stopRequestedRef.current) {
+          setError(cause instanceof Error ? cause.message : String(cause))
+        }
+      } finally {
+        stopRequestedRef.current = false
+        setBusy(false)
+      }
+    },
+    [applyDriveResult, canInterrupt, enabled, refreshSessionList, sessionQuery, sessionRecord],
+  )
+
+  const selectSession = useCallback(
+    async (sessionId: string) => {
+      const record = await readAgentSession(sessionQuery(sessionId))
+      adoptRecord(record)
+      setComposerValue('')
+      setError(null)
+      await settlePersistedPending(record)
+    },
+    [adoptRecord, sessionQuery, settlePersistedPending],
+  )
+
+  const createNewSession = useCallback(async () => {
+    const created = await createAgentSession({
+      scope,
+      appSlug: scopeAppSlug,
+      title: DEFAULT_SESSION_TITLE,
+      restoreTabId,
+    })
+    adoptRecord(created)
+    setComposerValue('')
+    await refreshSessionList()
+  }, [adoptRecord, refreshSessionList, restoreTabId, scope, scopeAppSlug])
+
+  const deleteSession = useCallback(async () => {
+    if (!sessionRecord) return
+    await deleteAgentSession(sessionQuery(sessionRecord.sessionId))
+    const listed = await refreshSessionList()
+    const next = listed[0]
+    if (next) {
+      await selectSession(next.sessionId)
+      return
+    }
+    if (autoCreate) await createNewSession()
+    else setSessionRecord(null)
+  }, [
+    autoCreate,
+    createNewSession,
+    refreshSessionList,
+    selectSession,
+    sessionQuery,
+    sessionRecord,
+  ])
+
+  const renameSession = useCallback(
+    async (title: string) => {
+      if (!sessionRecord) return
+      const trimmed = title.trim()
+      if (!trimmed) return
+      const updated = await updateAgentSession({
+        query: sessionQuery(sessionRecord.sessionId),
+        patch: { metadata: { title: trimmed } },
+      })
+      setSessionRecord(updated)
+      await refreshSessionList()
+    },
+    [refreshSessionList, sessionQuery, sessionRecord],
+  )
+
+  const persistScopeDefault = useCallback(
+    async (patch: PlatformAgentSessionConfigPatch) => {
+      try {
+        const prefs = (await getPlatformPreferences()) as {
+          agentSessionDefaults?: {
+            global?: PlatformAgentSessionConfigPatch
+            apps?: Record<string, PlatformAgentSessionConfigPatch>
+          }
+        }
+        const stored = prefs.agentSessionDefaults ?? {}
+        if (scope === 'global') {
+          await patchPlatformPreferences({
+            agentSessionDefaults: {
+              ...stored,
+              global: mergeScopeDefaultPatch(stored.global, patch),
+            },
+          })
+          return
+        }
+        if (!scopeAppSlug) return
+        const apps = { ...(stored.apps ?? {}) }
+        apps[scopeAppSlug] = mergeScopeDefaultPatch(apps[scopeAppSlug], patch)
+        await patchPlatformPreferences({
+          agentSessionDefaults: { ...stored, apps },
+        })
+      } catch {
+        /* scope defaults are best-effort */
+      }
+    },
+    [scope, scopeAppSlug],
+  )
+
+  const setModelId = useCallback(
+    async (modelId: string) => {
+      if (!sessionRecord) return
+      setOptimisticModelId(modelId)
+      try {
+        const updated = await updateAgentSession({
+          query: sessionQuery(sessionRecord.sessionId),
+          patch: { config: { modelId } },
+        })
+        setSessionRecord(updated)
+        setOptimisticModelId(null)
+        await persistScopeDefault({ modelId })
+      } catch (cause) {
+        setOptimisticModelId(null)
+        setError(cause instanceof Error ? cause.message : String(cause))
+      }
+    },
+    [persistScopeDefault, sessionQuery, sessionRecord],
+  )
+
+  const allowedTargetApps =
+    sessionRecord?.config.toolPolicy?.allowedTargetApps ?? []
+
+  const setAllowedTargetApps = useCallback(
+    async (slugs: readonly string[]) => {
+      if (!sessionRecord) return
+      const normalized = [
+        ...new Set(slugs.map(slug => slug.trim()).filter(Boolean)),
+      ]
+      const updated = await updateAgentSession({
+        query: sessionQuery(sessionRecord.sessionId),
+        patch: { config: { toolPolicy: { allowedTargetApps: normalized } } },
+      })
+      setSessionRecord(updated)
+      await persistScopeDefault({
+        toolPolicy: { allowedTargetApps: normalized },
+      })
+    },
+    [persistScopeDefault, sessionQuery, sessionRecord],
+  )
+
+  const setToolApprovalOverride = useCallback(
+    async (qualifiedName: string, requiresApproval: boolean) => {
+      if (!sessionRecord) return
+      const overrides = {
+        ...sessionRecord.config.toolPolicy?.approvalOverrides,
+        [qualifiedName]: requiresApproval,
+      }
+      const updated = await updateAgentSession({
+        query: sessionQuery(sessionRecord.sessionId),
+        patch: { config: { toolPolicy: { approvalOverrides: overrides } } },
+      })
+      setSessionRecord(updated)
+      await persistScopeDefault({
+        toolPolicy: { approvalOverrides: overrides },
+      })
+    },
+    [persistScopeDefault, sessionQuery, sessionRecord],
+  )
+
+  const approveToolAlwaysForSession = useCallback(
+    async (qualifiedName: string, toolCallId: string) => {
+      if (!sessionRecord) return
+      await drive(async () => {
+        const overrides = {
+          ...sessionRecord.config.toolPolicy?.approvalOverrides,
+          [qualifiedName]: false,
+        }
+        const updated = await updateAgentSession({
+          query: sessionQuery(sessionRecord.sessionId),
+          patch: { config: { toolPolicy: { approvalOverrides: overrides } } },
+        })
+        await persistScopeDefault({
+          toolPolicy: { approvalOverrides: overrides },
+        })
+        return approveAgentSessionTools({
+          session: sessionQuery(updated.sessionId),
+          toolCallIds: [toolCallId],
+        })
+      })
+    },
+    [drive, persistScopeDefault, sessionQuery, sessionRecord],
+  )
+
+  return {
+    scope,
+    setScope,
+    sessionRecord,
+    sessionSummaries,
+    sessionId: sessionRecord?.sessionId ?? null,
+    messages,
+    liveTurn,
+    pendingToolCalls,
+    runState,
+    busy,
+    error,
+    composerValue,
+    setComposerValue,
+    modelId: selectedModelId,
+    setModelId,
+    modelOptions,
+    modelUnavailableReason,
+    usage,
+    canSend,
+    canInterrupt,
+    sendMessage,
+    interruptRun,
+    approveTools,
+    approveToolAlwaysForSession,
+    rejectTools,
+    selectSession,
+    createNewSession,
+    deleteSession,
+    renameSession,
+    allowedTargetApps,
+    setAllowedTargetApps,
+    setToolApprovalOverride,
+    refresh,
+  }
+}