From 15383206ca4eb4cc502c15f429dccdec76bf509a Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Tue, 29 Sep 2026 16:38:16 -0700
Subject: [PATCH 01/11] Recover missing OPFS notebooks from Google Drive

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 app/src/storage/filePayloads.ts      |  10 +-
 app/src/storage/local.test.ts        | 297 +++++++++++++++++++++++++++
 app/src/storage/local.ts             | 165 ++++++++++++++-
 app/src/storage/operationLogs.ts     |  15 +-
 docs-dev/CUJs/drive-sync-recovery.md |  23 +++
 5 files changed, 499 insertions(+), 11 deletions(-)

diff --git a/app/src/storage/filePayloads.ts b/app/src/storage/filePayloads.ts
index d6d7e294..dbd4c99d 100644
--- a/app/src/storage/filePayloads.ts
+++ b/app/src/storage/filePayloads.ts
@@ -103,10 +103,12 @@ export class MemoryFilePayloadStorage implements FilePayloadStorage {
   }
   async read(ref: FilePayloadRef): Promise<string> {
     const content = this.values.get(ref.path)
-    if (
-      content === undefined ||
-      (await filePayloadChecksum(content)) !== ref.checksum
-    )
+    if (content === undefined)
+      throw new DOMException(
+        `Notebook payload missing or corrupt: ${ref.path}`,
+        'NotFoundError'
+      )
+    if ((await filePayloadChecksum(content)) !== ref.checksum)
       throw new Error(`Notebook payload missing or corrupt: ${ref.path}`)
     return content
   }
diff --git a/app/src/storage/local.test.ts b/app/src/storage/local.test.ts
index 1d72987c..f9015dc8 100644
--- a/app/src/storage/local.test.ts
+++ b/app/src/storage/local.test.ts
@@ -60,6 +60,7 @@ import LocalNotebooks, {
 } from './local'
 import { NotebookStoreItemType } from './notebook'
 import { MemoryOperationLogStorage } from './operationLogs'
+import { OwnedOperationLogs } from './ownedOperationLogs'
 import { MemoryRevisionDocStorage } from './revisionDocs'
 
 /** Collect small fixture pages for assertions; production APIs always expose a cursor. */
@@ -9955,3 +9956,299 @@ describe('OPFS notebook payload migration', () => {
     expect((await store.files.get(uri))?.name).toBe('renamed.json')
   })
 })
+
+describe('LocalNotebooks missing OPFS recovery', () => {
+  const uri = 'local://file/lost-opfs'
+  const remoteId = 'https://drive.google.com/file/d/recoverable/view'
+
+  /** Keep IndexedDB locators while removing the durable bytes, as after OPFS loss. */
+  async function fixture(format = 'runme') {
+    const notebook = create(parser_pb.NotebookSchema, {
+      cells: [
+        create(parser_pb.CellSchema, {
+          refId: 'recover-cell',
+          kind: parser_pb.CellKind.CODE,
+          languageId: 'python',
+          value: 'print("from Drive")',
+        }),
+      ],
+    })
+    const content =
+      format === 'runme'
+        ? (
+            await convertLegacyNotebookFileToRunme(
+              encodeRunmeNotebook(notebook),
+              'source.json'
+            )
+          ).content
+        : format === 'ipynb'
+          ? encodeIpynbNotebook(notebook).text
+          : encodeRunmeNotebook(notebook)
+    const drive = {
+      loadContent: vi.fn(async () => content),
+      getVersionMetadata: vi.fn(async () => ({
+        md5Checksum: md5(content),
+        version: '1',
+      })),
+      saveContent: vi.fn(),
+      save: vi.fn(),
+    }
+    const logs = new MemoryOperationLogStorage()
+    const store = createTestStore(drive, { operationLogStorage: logs })
+    const payloads = (store as any).payloadStorage as MemoryFilePayloadStorage
+    const operationLogRef =
+      format === 'runme' ? (await logs.initialize(uri, content)).ref : undefined
+    const contentRef =
+      format !== 'runme'
+        ? await payloads.write(encodeRunmeNotebook(notebook))
+        : undefined
+    await store.files.put({
+      id: uri,
+      name: `lost.${format}`,
+      remoteId,
+      doc: '',
+      operationLogRef,
+      contentRef,
+      md5Checksum: 'lost-local-version',
+      lastRemoteChecksum: 'old-upstream',
+      lastSynced: new Date().toISOString(),
+    })
+    if (operationLogRef) await logs.delete(operationLogRef)
+    payloads.values.clear()
+    return { store, drive, logs, payloads, content, operationLogRef }
+  }
+
+  it.each([
+    'load',
+    'loadContent',
+    'loadOperationLogSnapshot',
+    'createOperationLogSaveStore',
+  ] as const)(
+    'restores a missing journal through %s, preserving history and subsequent edits',
+    async (method) => {
+      const f = await fixture()
+      try {
+        if (method === 'createOperationLogSaveStore')
+          await f.store.createOperationLogSaveStore(uri, {
+            actorId: 'open-test',
+          })
+        else await f.store[method](uri)
+        expect(await f.store.loadContent(uri)).toBe(f.content)
+        expect(f.drive.loadContent).toHaveBeenCalledTimes(1)
+        expect(f.drive.saveContent).not.toHaveBeenCalled()
+        expect((await f.store.files.get(uri))?.id).toBe(uri)
+        const editor = await f.store.createOperationLogSaveStore(uri, {
+          actorId: 'recovered-editor',
+        })
+        editor.initialNotebook.cells[0].value = 'print("edited")'
+        await editor.save(uri, editor.initialNotebook)
+        expect((await f.store.load(uri)).cells[0].value).toBe('print("edited")')
+        // A new execution must persist fresh output in the recovered journal.
+        editor.initialNotebook.cells[0].metadata = {
+          ...editor.initialNotebook.cells[0].metadata,
+          [RunmeMetadataKey.LastRunID]: 'recovered-run',
+          [RunmeMetadataKey.ExecutionState]: 'completed',
+        }
+        editor.initialNotebook.cells[0].outputs = [
+          create(parser_pb.CellOutputSchema, {
+            items: [
+              create(parser_pb.CellOutputItemSchema, {
+                mime: 'text/plain',
+                data: new TextEncoder().encode('edited\n'),
+              }),
+            ],
+          }),
+        ]
+        await editor.save(uri, editor.initialNotebook)
+        const reopened = await f.store.load(uri)
+        expect(
+          new TextDecoder().decode(reopened.cells[0].outputs[0].items[0].data)
+        ).toBe('edited\n')
+        const before = parseOperationLog(f.content)
+        const after = parseOperationLog(await f.store.loadContent(uri))
+        expect(after.header.notebook_id).toBe(before.header.notebook_id)
+        for (const op of before.operations)
+          expect(after.operations).toContainEqual(op)
+        expect(f.drive.loadContent).toHaveBeenCalledTimes(1)
+      } finally {
+        f.store.stopSyncQueue()
+      }
+    }
+  )
+
+  it.each(['json', 'ipynb'])(
+    'restores missing %s payloads and persists edits',
+    async (format) => {
+      const f = await fixture(format)
+      try {
+        const loaded = await f.store.load(uri)
+        expect(loaded.cells[0].value).toBe('print("from Drive")')
+        loaded.cells[0].value = 'edited'
+        await f.store.save(uri, loaded)
+        expect((await f.store.load(uri)).cells[0].value).toBe('edited')
+        expect(f.drive.loadContent).toHaveBeenCalledTimes(1)
+      } finally {
+        f.store.stopSyncQueue()
+      }
+    }
+  )
+
+  it('restores through the storage owner without acknowledging an intervening edit', async () => {
+    const f = await fixture()
+    const generations = new Map<string, { path: string; generation: number }>()
+    Object.assign(f.store.files, {
+      db: {
+        transaction: async (...args: unknown[]) =>
+          (args.at(-1) as () => Promise<unknown>)(),
+      },
+    })
+    const owner = new OwnedOperationLogs(
+      f.logs,
+      f.store.files,
+      {
+        get: async (path: string) => generations.get(path),
+        put: async (value: { path: string; generation: number }) =>
+          generations.set(value.path, value),
+      } as any,
+      (id, changes) => (f.store as any).updateFile(id, changes)
+    )
+    Object.assign(f.store, {
+      ownedLogs: owner,
+      operationLogStorage: owner,
+      runtime: { owner: true },
+    })
+    const initialize = owner.initialize.bind(owner)
+    vi.spyOn(owner, 'initialize').mockImplementationOnce(
+      async (id, content) => {
+        const restored = await initialize(id, content)
+        const editor = await f.store.createOperationLogSaveStore(uri, {
+          actorId: 'concurrent-editor',
+          initialDocument: content,
+        })
+        editor.initialNotebook.cells[0].value = 'new edit during recovery'
+        await editor.save(uri, editor.initialNotebook)
+        return restored
+      }
+    )
+    try {
+      expect((await f.store.load(uri)).cells[0].value).toBe(
+        'new edit during recovery'
+      )
+      const record = await f.store.files.get(uri)
+      expect(record?.md5Checksum).toBe('')
+      expect(record?.lastRemoteChecksum).toBe(md5(f.content))
+      expect(record?.pendingInitializationRef).toBeUndefined()
+    } finally {
+      f.store.stopSyncQueue()
+    }
+  })
+
+  it('recovers when the journal and pending initialization payload are both missing', async () => {
+    const f = await fixture()
+    const ref = await f.payloads.write(f.content)
+    await f.store.files.update(uri, { pendingInitializationRef: ref })
+    f.payloads.values.clear()
+    try {
+      expect((await f.store.load(uri)).cells[0].value).toBe(
+        'print("from Drive")'
+      )
+      expect(
+        (await f.store.files.get(uri))?.pendingInitializationRef
+      ).toBeUndefined()
+      expect(await f.store.loadContent(uri)).toBe(f.content)
+    } finally {
+      f.store.stopSyncQueue()
+    }
+  })
+
+  it('downloads once when two opens encounter the same missing file', async () => {
+    const f = await fixture()
+    try {
+      const results = await Promise.all([f.store.load(uri), f.store.load(uri)])
+      expect(results.map((n) => n.cells[0].value)).toEqual([
+        'print("from Drive")',
+        'print("from Drive")',
+      ])
+      expect(f.drive.loadContent).toHaveBeenCalledTimes(1)
+    } finally {
+      f.store.stopSyncQueue()
+    }
+  })
+
+  it.each(['offline', '404', 'malformed', 'empty', 'changed'])(
+    'preserves the reference if Drive is %s',
+    async (failure) => {
+      const f = await fixture()
+      const original = await f.store.files.get(uri)
+      if (failure === 'offline' || failure === '404')
+        f.drive.loadContent.mockRejectedValue(new Error(failure))
+      else {
+        const content = failure === 'empty' ? '' : 'not a notebook'
+        f.drive.loadContent.mockResolvedValue(content)
+        if (failure !== 'changed')
+          f.drive.getVersionMetadata.mockResolvedValue({
+            md5Checksum: md5(content),
+            version: '1',
+          })
+      }
+      try {
+        await expect(f.store.load(uri)).rejects.toThrow()
+        expect(await f.store.files.get(uri)).toEqual(original)
+        await expect(f.logs.read(f.operationLogRef!)).rejects.toMatchObject({
+          name: 'NotFoundError',
+        })
+        expect(f.drive.saveContent).not.toHaveBeenCalled()
+      } finally {
+        f.store.stopSyncQueue()
+      }
+    }
+  )
+
+  it.each(['local-only', 'healthy', 'corrupt', 'permission'])(
+    'does not download for %s storage',
+    async (state) => {
+      const f = await fixture()
+      try {
+        if (state === 'local-only')
+          await f.store.files.update(uri, { remoteId: uri })
+        if (state === 'healthy') await f.logs.initialize(uri, f.content)
+        if (state === 'corrupt')
+          await f.logs.initialize(uri, 'invalid history\n')
+        if (state === 'permission')
+          vi.spyOn(f.logs, 'read').mockRejectedValue(
+            new DOMException('permission denied', 'NotAllowedError')
+          )
+        if (state === 'healthy')
+          expect((await f.store.load(uri)).cells).toHaveLength(1)
+        else await expect(f.store.load(uri)).rejects.toThrow()
+        expect(f.drive.loadContent).not.toHaveBeenCalled()
+        if (state === 'corrupt')
+          expect((await f.logs.read(f.operationLogRef!)).document).toBe(
+            'invalid history\n'
+          )
+      } finally {
+        f.store.stopSyncQueue()
+      }
+    }
+  )
+
+  it('keeps a journal recreated while Drive downloads', async () => {
+    const f = await fixture()
+    const localContent = (
+      await convertLegacyNotebookFileToRunme(
+        notebookJson('new local content'),
+        'local.json'
+      )
+    ).content
+    f.drive.loadContent.mockImplementationOnce(async () => {
+      await f.logs.initialize(uri, localContent)
+      return f.content
+    })
+    try {
+      expect((await f.store.load(uri)).cells[0].value).toBe('new local content')
+      expect(await f.store.loadContent(uri)).toBe(localContent)
+    } finally {
+      f.store.stopSyncQueue()
+    }
+  })
+})
diff --git a/app/src/storage/local.ts b/app/src/storage/local.ts
index 14ead702..ddbdc22a 100644
--- a/app/src/storage/local.ts
+++ b/app/src/storage/local.ts
@@ -153,6 +153,16 @@ import {
 import { SyncDeferred, SyncWorkQueue } from './syncWorkQueue'
 import { readTablePage, scanTable, tableHasRecords } from './tableScan'
 
+/** DOMException identity does not survive every worker boundary; use its name. */
+function isMissingOpfsFile(error: unknown): boolean {
+  return Boolean(
+    error &&
+      typeof error === 'object' &&
+      'name' in error &&
+      error.name === 'NotFoundError'
+  )
+}
+
 // Local folder URI is a special folder that contains all notebooks which are local (i.e. not synced to Drive)
 export const LOCAL_FOLDER_URI = 'local://folder/local'
 
@@ -929,6 +939,136 @@ export class LocalNotebooks extends Dexie {
     }
   }
 
+  /** Retry an explicit open once, and only for a filesystem missing-file error. */
+  private async withMissingOpfsRecovery<T>(
+    uri: string,
+    read: () => Promise<T>
+  ): Promise<T> {
+    try {
+      return await read()
+    } catch (error) {
+      if (!isMissingOpfsFile(error)) throw error
+      const recovered = await this.serializeLocalSave(uri, () =>
+        this.driveSyncCoordinator.runExclusive(uri, () =>
+          this.restoreMissingOpfsFile(uri)
+        )
+      )
+      if (!recovered) throw error
+      return read()
+    }
+  }
+
+  /**
+   * Restore the existing mirror identity after OPFS loss. The caller holds the
+   * local-save queue and Drive lock, so recovery cannot race a save or sync.
+   * Present but invalid files are never replaced by this missing-file path.
+   */
+  private async restoreMissingOpfsFile(uri: string): Promise<boolean> {
+    const record = await this.files.get(uri)
+    if (
+      !record ||
+      !isDriveUri(record.remoteId) ||
+      !isNotebookFileName(record.name)
+    )
+      return false
+    const operationLog =
+      detectNotebookFileFormat(record.name) === 'runme-operation-log'
+    const readLocal = async () => {
+      if (operationLog && record.operationLogRef)
+        await this.operationLogStorage.read(record.operationLogRef)
+      else if (record.contentRef) await this.hydrateFile(record)
+      else return false
+      return true
+    }
+    try {
+      // A concurrent open may already have recovered the same file.
+      if (await readLocal()) return true
+      return false
+    } catch (error) {
+      if (!isMissingOpfsFile(error)) throw error
+    }
+
+    const snapshot = await this.loadConsistentDriveOperationLogSnapshot(
+      record.remoteId
+    )
+    if (!snapshot) throw new DriveSnapshotChangedError(record.remoteId)
+    // Decode before writing, retaining the missing reference if Drive is empty,
+    // malformed, unavailable, or changes during the download.
+    const decoded = decodeNotebookFile(snapshot.content, record.name)
+    const latest = await this.files.get(uri)
+    if (
+      !latest ||
+      latest.remoteId !== record.remoteId ||
+      latest.name !== record.name ||
+      latest.contentRef?.path !== record.contentRef?.path ||
+      latest.operationLogRef?.path !== record.operationLogRef?.path ||
+      latest.md5Checksum !== record.md5Checksum
+    )
+      throw new Error(`Notebook changed during OPFS recovery: ${uri}`)
+    try {
+      if (await readLocal()) return true
+    } catch (error) {
+      if (!isMissingOpfsFile(error)) throw error
+    }
+
+    const upstreamChecksum = md5(snapshot.content)
+    const baseline = {
+      lastRemoteChecksum: upstreamChecksum,
+      lastUpstreamVersion: driveMetadataToUpstreamVersion(snapshot.version),
+      lastSynced: nowIsoString(),
+      lastSyncError: undefined,
+    }
+    if (operationLog) {
+      // initialize refuses to overwrite a journal that appeared meanwhile.
+      // Keep the exact Drive history, including its notebook and operation IDs.
+      const stored = await this.operationLogStorage.initialize(
+        uri,
+        snapshot.content
+      )
+      if (this.ownedLogs) {
+        await this.ownedLogs.acknowledge(uri, stored, record.remoteId, baseline)
+      } else {
+        await this.updateFile(uri, {
+          ...baseline,
+          operationLogRef: stored.ref,
+          md5Checksum: stored.checksum,
+        })
+      }
+      await this.updateFile(uri, {
+        doc: '',
+        pendingOperationLogInitialization: undefined,
+      })
+    } else {
+      const restored = decoded.ipynb
+        ? await this.decodeUpstreamNotebook({
+            localUri: uri,
+            record,
+            content: snapshot.content,
+            upstreamFingerprint: upstreamChecksum,
+          })
+        : {
+            serialized: serializeNotebook(decoded.notebook),
+            ipynbPreservation: undefined,
+          }
+      await this.updateFile(uri, {
+        ...baseline,
+        doc: restored.serialized,
+        md5Checksum: checksumForSerializedNotebook(restored.serialized),
+        ipynbPreservation: restored.ipynbPreservation,
+      })
+    }
+    appLogger.warn('Restored missing OPFS notebook from Google Drive', {
+      attrs: {
+        scope: 'storage.drive.recovery',
+        code: 'NOTEBOOK_OPFS_RESTORED',
+        localUri: uri,
+        remoteUri: record.remoteId,
+      },
+    })
+    this.notifySync(uri)
+    return true
+  }
+
   /** Initialization bytes are recovery input, not part of ordinary content reads. */
   private async readPendingInitialization(
     record: LocalFileRecord | undefined
@@ -2132,8 +2272,7 @@ export class LocalNotebooks extends Dexie {
     }
 
     const initialDocument =
-      options.initialDocument ??
-      (await this.operationLogStorage.read(record.operationLogRef)).document
+      options.initialDocument ?? (await this.loadContent(uri))
     let view: ParsedOperationLog = parseOperationLog(initialDocument)
     let previous = materializedLogToNotebook(
       materializeOperationLog(view.operations)
@@ -3181,7 +3320,12 @@ export class LocalNotebooks extends Dexie {
     }
   }
 
+  /** Read local content, restoring missing OPFS bytes from Drive when necessary. */
   async loadContent(uri: string): Promise<string> {
+    return this.withMissingOpfsRecovery(uri, () => this.loadContentInner(uri))
+  }
+
+  private async loadContentInner(uri: string): Promise<string> {
     await this.recoverLocalInitialization(uri)
     if (!uri.startsWith('local://file/')) {
       throw new Error(
@@ -3283,8 +3427,16 @@ export class LocalNotebooks extends Dexie {
     return content
   }
 
-  /** Materialize the current local .runme OPFS log without upstream I/O. */
+  /** Materialize the local journal, downloading it only when OPFS lost the file. */
   async loadOperationLogSnapshot(uri: string): Promise<parser_pb.Notebook> {
+    return this.withMissingOpfsRecovery(uri, () =>
+      this.loadOperationLogSnapshotInner(uri)
+    )
+  }
+
+  private async loadOperationLogSnapshotInner(
+    uri: string
+  ): Promise<parser_pb.Notebook> {
     if (!uri.startsWith('local://file/')) {
       throw new Error(
         'LocalNotebooks.loadOperationLogSnapshot expects a local://file/ URI; got ' +
@@ -3690,7 +3842,12 @@ export class LocalNotebooks extends Dexie {
     this.notifySync(uri)
   }
 
+  /** Keep healthy opens local; a missing OPFS file can be restored from Drive. */
   async load(uri: string): Promise<parser_pb.Notebook> {
+    return this.withMissingOpfsRecovery(uri, () => this.loadInner(uri))
+  }
+
+  private async loadInner(uri: string): Promise<parser_pb.Notebook> {
     await this.recoverLocalInitialization(uri)
     if (!uri.startsWith('local://file/')) {
       throw new Error(
@@ -3739,7 +3896,7 @@ export class LocalNotebooks extends Dexie {
     }
 
     if (detectNotebookFileFormat(record.name) === 'runme-operation-log') {
-      return this.loadOperationLogSnapshot(uri)
+      return this.loadOperationLogSnapshotInner(uri)
     }
 
     if (!record.doc) {
diff --git a/app/src/storage/operationLogs.ts b/app/src/storage/operationLogs.ts
index d18fb01e..d520b956 100644
--- a/app/src/storage/operationLogs.ts
+++ b/app/src/storage/operationLogs.ts
@@ -331,7 +331,10 @@ export class MemoryOperationLogStorage implements OperationLogStorage {
   async read(ref: OperationLogRef): Promise<OperationLogSnapshot> {
     const document = this.documents.get(ref.path)
     if (document === undefined) {
-      throw new Error(`Operation log not found: ${ref.path}`)
+      throw new DOMException(
+        `Operation log not found: ${ref.path}`,
+        'NotFoundError'
+      )
     }
     validateFraming(document, 'Stored operation log')
     return snapshot(ref, document)
@@ -354,7 +357,10 @@ export class MemoryOperationLogStorage implements OperationLogStorage {
     return this.coordinator.runExclusive(ref.path, async () => {
       const original = this.documents.get(ref.path)
       if (original === undefined) {
-        throw new Error(`Operation log not found: ${ref.path}`)
+        throw new DOMException(
+          `Operation log not found: ${ref.path}`,
+          'NotFoundError'
+        )
       }
       const current = options.prepareDocument?.(original) ?? original
       const records = await createRecords(current)
@@ -376,7 +382,10 @@ export class MemoryOperationLogStorage implements OperationLogStorage {
     validateFraming(document, 'Replacement operation log')
     return this.coordinator.runExclusive(ref.path, async () => {
       if (!this.documents.has(ref.path)) {
-        throw new Error(`Operation log not found: ${ref.path}`)
+        throw new DOMException(
+          `Operation log not found: ${ref.path}`,
+          'NotFoundError'
+        )
       }
       if (
         options.expectedChecksum &&
diff --git a/docs-dev/CUJs/drive-sync-recovery.md b/docs-dev/CUJs/drive-sync-recovery.md
index 302c7833..4cef120d 100644
--- a/docs-dev/CUJs/drive-sync-recovery.md
+++ b/docs-dev/CUJs/drive-sync-recovery.md
@@ -314,3 +314,26 @@ ready items blocked by a file claim and the oldest active attempt.
 through the other real Chromium tab while the first is stalled on credentials.
 Its output includes active count and configured capacity. It then disables both
 tabs' credential availability and verifies offline editing and restart persistence.
+
+## Missing OPFS files with a Drive copy
+
+If IndexedDB still identifies a Drive-backed notebook but its OPFS journal or
+cached JSON/IPYNB payload is missing, opening it downloads a consistent Drive
+snapshot into the same local notebook identity. Healthy cached notebooks still
+open offline. Recovery never uploads an empty replacement or overwrites a
+present but corrupt journal. Drive/auth failures leave the missing-file
+reference intact so opening can retry after connectivity is restored.
+
+Automated regression coverage: the `LocalNotebooks missing OPFS recovery` suite
+in `local.test.ts` removes only fixture OPFS bytes, retains metadata, and verifies
+open, edit, save, reopen, and fresh execution output. It also checks concurrent
+opens, a journal recreated during download, JSON/IPYNB payloads, and failed,
+empty, malformed, or changing Drive downloads. These are storage-level tests;
+the existing browser CUJ does not yet simulate origin storage loss.
+
+Manual acceptance in a disposable browser profile: mirror a Drive notebook,
+close its editor, and remove only its OPFS document while keeping IndexedDB.
+Reopen it and verify its cells are editable, edits and a rerun survive reopening,
+and the Drive file/local URI are unchanged. Repeat while offline, then restore
+connectivity and reopen. Never perform this destructive setup on a user's
+unsynced notebook.

From e3a73c0e30d79e888dc864effb7d16def37ce9b9 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Tue, 29 Sep 2026 19:12:35 -0700
Subject: [PATCH 02/11] Reject invalid JSON before restoring an OPFS notebook

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 app/src/storage/local.test.ts | 25 +++++++++++++++++++++++++
 app/src/storage/local.ts      | 10 ++++++++++
 2 files changed, 35 insertions(+)

diff --git a/app/src/storage/local.test.ts b/app/src/storage/local.test.ts
index f9015dc8..06414b99 100644
--- a/app/src/storage/local.test.ts
+++ b/app/src/storage/local.test.ts
@@ -10093,6 +10093,31 @@ describe('LocalNotebooks missing OPFS recovery', () => {
     }
   )
 
+  it.each([
+    '',
+    '{"error":"upstream failure"}',
+    '{"cells":[],"unrecognized":"data"}',
+  ])(
+    'does not turn invalid Drive JSON %j into an empty recovered notebook',
+    async (content) => {
+      const f = await fixture('json')
+      const original = await f.store.files.get(uri)
+      f.drive.loadContent.mockResolvedValue(content)
+      f.drive.getVersionMetadata.mockResolvedValue({
+        md5Checksum: md5(content),
+        version: '1',
+      })
+      try {
+        await expect(f.store.load(uri)).rejects.toThrow()
+        expect(await f.store.files.get(uri)).toEqual(original)
+        expect(f.payloads.values.size).toBe(0)
+        expect(f.drive.saveContent).not.toHaveBeenCalled()
+      } finally {
+        f.store.stopSyncQueue()
+      }
+    }
+  )
+
   it('restores through the storage owner without acknowledging an intervening edit', async () => {
     const f = await fixture()
     const generations = new Map<string, { path: string; generation: number }>()
diff --git a/app/src/storage/local.ts b/app/src/storage/local.ts
index ddbdc22a..5548f459 100644
--- a/app/src/storage/local.ts
+++ b/app/src/storage/local.ts
@@ -16,6 +16,7 @@ import {
   decodeNotebookFile,
   detectNotebookFileFormat,
   encodeIpynbNotebook,
+  inspectRunmeNotebookJsonShape,
   isNotebookFileName,
   notebookFileExtension,
   validateNotebookRenameFormat,
@@ -994,6 +995,15 @@ export class LocalNotebooks extends Dexie {
     if (!snapshot) throw new DriveSnapshotChangedError(record.remoteId)
     // Decode before writing, retaining the missing reference if Drive is empty,
     // malformed, unavailable, or changes during the download.
+    if (
+      !snapshot.content.trim() ||
+      (detectNotebookFileFormat(record.name) === 'runme-json' &&
+        !inspectRunmeNotebookJsonShape(snapshot.content))
+    ) {
+      throw new Error(
+        `Drive recovery source is not a notebook: ${record.remoteId}`
+      )
+    }
     const decoded = decodeNotebookFile(snapshot.content, record.name)
     const latest = await this.files.get(uri)
     if (

From eaf8ec112fe383d1e6ddda1e4bf73e2e5396ca46 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 13:19:02 -0700
Subject: [PATCH 03/11] Add Agents API monitor widgets to JavaScript notebook
 cells

---
 .../components/Actions/ActionOutputItems.tsx  |   6 +-
 app/src/components/Actions/Actions.test.tsx   |  25 ++
 app/src/components/Actions/Actions.tsx        |  45 +-
 .../components/Agents/AgentMonitor.test.tsx   |  90 ++++
 app/src/components/Agents/AgentMonitor.tsx    | 240 +++++++++++
 app/src/generated/documentationManifest.ts    |   8 +
 app/src/lib/agents/bridge.ts                  |  30 ++
 app/src/lib/agents/monitor.test.ts            | 261 ++++++++++++
 app/src/lib/agents/monitor.ts                 | 391 ++++++++++++++++++
 app/src/lib/agents/runtime.test.ts            |  65 +++
 app/src/lib/agents/runtime.ts                 | 125 ++++++
 app/src/lib/agents/transport.test.ts          |  51 +++
 app/src/lib/agents/transport.ts               | 142 +++++++
 app/src/lib/agents/types.ts                   |  67 +++
 app/src/lib/notebookData.test.ts              |  41 ++
 app/src/lib/notebookData.ts                   |  22 +-
 app/src/lib/runtime/appJsGlobals.ts           |   5 +
 app/src/lib/runtime/codeModeExecutor.ts       |   3 +
 app/src/lib/runtime/sandboxJsKernel.test.ts   |   6 +-
 app/src/lib/runtime/sandboxJsKernel.ts        |  22 +-
 docs-dev/CUJs/agent-monitor.md                |  16 +
 docs-dev/cujs/README.md                       |   2 +
 docs-dev/design/20261003_agents_api_ui.md     | 110 +++++
 docs/20-agent-monitors.md                     |  36 ++
 docs/agent-monitors.json                      |  28 ++
 testing/fake-agents-server.go                 |  89 ++++
 26 files changed, 1919 insertions(+), 7 deletions(-)
 create mode 100644 app/src/components/Agents/AgentMonitor.test.tsx
 create mode 100644 app/src/components/Agents/AgentMonitor.tsx
 create mode 100644 app/src/lib/agents/bridge.ts
 create mode 100644 app/src/lib/agents/monitor.test.ts
 create mode 100644 app/src/lib/agents/monitor.ts
 create mode 100644 app/src/lib/agents/runtime.test.ts
 create mode 100644 app/src/lib/agents/runtime.ts
 create mode 100644 app/src/lib/agents/transport.test.ts
 create mode 100644 app/src/lib/agents/transport.ts
 create mode 100644 app/src/lib/agents/types.ts
 create mode 100644 docs-dev/CUJs/agent-monitor.md
 create mode 100644 docs-dev/design/20261003_agents_api_ui.md
 create mode 100644 docs/20-agent-monitors.md
 create mode 100644 docs/agent-monitors.json
 create mode 100644 testing/fake-agents-server.go

diff --git a/app/src/components/Actions/ActionOutputItems.tsx b/app/src/components/Actions/ActionOutputItems.tsx
index ea8637a9..a365f4e1 100644
--- a/app/src/components/Actions/ActionOutputItems.tsx
+++ b/app/src/components/Actions/ActionOutputItems.tsx
@@ -1,3 +1,5 @@
+import { AgentMonitorOutput } from '../Agents/AgentMonitor'
+import { AGENT_MONITOR_MIME } from '../../lib/agents/types'
 import { HtmlOutput } from './HtmlOutput'
 import React from 'react'
 import { LinkIcon } from '@heroicons/react/20/solid'
@@ -86,7 +88,9 @@ export function ActionOutputItemView({
 
   let content: React.ReactNode = null
 
-  if (mime === 'text/html') {
+  if (mime === AGENT_MONITOR_MIME) {
+    content = <AgentMonitorOutput value={text} />
+  } else if (mime === 'text/html') {
     content = (
       <HtmlOutput
         html={text}
diff --git a/app/src/components/Actions/Actions.test.tsx b/app/src/components/Actions/Actions.test.tsx
index d9a514e4..97ab2de4 100644
--- a/app/src/components/Actions/Actions.test.tsx
+++ b/app/src/components/Actions/Actions.test.tsx
@@ -505,6 +505,31 @@ beforeEach(() => {
 })
 
 describe('Actions tabs', () => {
+  it('toggles agent widget source and render modes without executing or unmounting output', () => {
+    const cell = create(parser_pb.CellSchema, {
+      refId: 'widget-cell', kind: parser_pb.CellKind.CODE, languageId: 'javascript', value: 'agents.monitor("sess_test")',
+      outputs: [create(parser_pb.CellOutputSchema, { items: [create(parser_pb.CellOutputItemSchema, {
+        mime: 'application/vnd.runme.agent-monitor+json',
+        data: new TextEncoder().encode(JSON.stringify({version: 1, id: 'saved-widget', sessionId: 'sess_test', pageSize: 50})),
+      })] })],
+    })
+    const stub = new StubCellData(cell)
+    stub.getRunnerName = () => APPKERNEL_RUNNER_NAME
+    const view = render(<Action cellData={stub as unknown as CellData} docUri="local://file/widget" isFirst={false} />)
+    const editor = view.container.querySelector('[data-cell-focus-role="editor"]') as HTMLElement
+    const output = view.container.querySelector('#widget-output-widget-cell') as HTMLElement
+    expect(editor.hidden).toBe(true)
+    const mounted = screen.getByTestId('agent-monitor')
+    fireEvent.click(screen.getByRole('button', {name: /^Edit$/}))
+    expect(editor.hidden).toBe(false)
+    expect(output.hidden).toBe(true)
+    expect(screen.getByTestId('agent-monitor')).toBe(mounted)
+    fireEvent.click(screen.getByRole('button', {name: /^Render$/}))
+    expect(output.hidden).toBe(false)
+    expect(stub.run).not.toHaveBeenCalled()
+    view.unmount()
+  })
+
 
   it.each([
     ['url', true, true, true],
diff --git a/app/src/components/Actions/Actions.tsx b/app/src/components/Actions/Actions.tsx
index d01f4981..dbcd85bc 100644
--- a/app/src/components/Actions/Actions.tsx
+++ b/app/src/components/Actions/Actions.tsx
@@ -1,3 +1,4 @@
+import { AGENT_MONITOR_MIME } from '../../lib/agents/types'
 import { outputReferenceSource } from '../../lib/outputReferenceRuntime'
 import { OutputReferenceCell } from './OutputReferenceCell'
 import {
@@ -264,7 +265,8 @@ function syncIndicatorPresentation(state: NotebookSyncState | null): {
   switch (state?.status) {
     case 'not-downloaded':
       return {
-        label: 'Notebook has not been downloaded to this browser. Click to download now.',
+        label:
+          'Notebook has not been downloaded to this browser. Click to download now.',
         className: 'border border-nb-text-faint bg-transparent',
         clickable: true,
       }
@@ -805,6 +807,12 @@ export function Action({
   })
   const shareTargetUri =
     shareTarget.docUri === docUri ? shareTarget.targetUri : null
+  const [widgetEditing, setWidgetEditing] = useState(false)
+  const hasWidgetOutput =
+    cell?.outputs?.some((output) =>
+      output.items.some((item) => item.mime === AGENT_MONITOR_MIME)
+    ) ?? false
+  const [widgetSourceChanged, setWidgetSourceChanged] = useState(false)
   const [htmlEditRequest, setHtmlEditRequest] = useState(0)
   const [markdownEditRequest, setMarkdownEditRequest] = useState(0)
   const [pid, setPid] = useState<number | null>(null)
@@ -914,6 +922,8 @@ export function Action({
     if (readOnly) {
       return
     }
+    setWidgetEditing(false)
+    setWidgetSourceChanged(false)
     cellData.run()
   }, [cellData, readOnly])
 
@@ -2133,6 +2143,7 @@ export function Action({
           <div
             className="overflow-hidden rounded-t-nb-md"
             data-cell-focus-role="editor"
+            hidden={hasWidgetOutput && !widgetEditing}
           >
             <Editor
               commentRanges={commentSourceRanges}
@@ -2149,6 +2160,7 @@ export function Action({
               shouldFocus={isActiveCell && isWindowFocused}
               readOnly={readOnly}
               onChange={(v) => {
+                if (hasWidgetOutput) setWidgetSourceChanged(true)
                 const updated = create(parser_pb.CellSchema, cell)
                 updated.value = v
                 updateCellLocal(updated)
@@ -2158,6 +2170,30 @@ export function Action({
           </div>
 
           {/* Minimal toolbar: language + runner selectors + run/trash buttons */}
+          {hasWidgetOutput && (
+            <div
+              id={`widget-mode-${cell.refId}`}
+              className="flex items-center gap-2 border-b px-3 py-2 text-xs"
+            >
+              <button
+                type="button"
+                aria-pressed={widgetEditing}
+                onClick={() => setWidgetEditing(true)}
+              >
+                Edit
+              </button>
+              <button
+                type="button"
+                aria-pressed={!widgetEditing}
+                onClick={() => setWidgetEditing(false)}
+              >
+                Render
+              </button>
+              {widgetSourceChanged && (
+                <span>Source changed — Run to update the monitor.</span>
+              )}
+            </div>
+          )}
           <div id={`cell-toolbar-${cell.refId}`} className="cell-toolbar">
             <div className="flex items-center gap-3">
               <select
@@ -2319,7 +2355,12 @@ export function Action({
             {renderedOutputs}
           </div>
         )}
-        {renderedOutputItems}
+        <div
+          id={`widget-output-${cell.refId}`}
+          hidden={hasWidgetOutput && widgetEditing}
+        >
+          {renderedOutputItems}
+        </div>
       </div>
 
       {/* Context menu */}
diff --git a/app/src/components/Agents/AgentMonitor.test.tsx b/app/src/components/Agents/AgentMonitor.test.tsx
new file mode 100644
index 00000000..b3575743
--- /dev/null
+++ b/app/src/components/Agents/AgentMonitor.test.tsx
@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { AgentItemView, AgentMonitorOutput } from './AgentMonitor'
+import { resetAgentMonitors } from '../../lib/agents/runtime'
+
+afterEach(() => {
+  cleanup()
+  resetAgentMonitors()
+  vi.unstubAllGlobals()
+})
+describe('agent monitor rendering', () => {
+  it('renders Markdown tables and code without executing HTML or loading images', () => {
+    const { container } = render(
+      <AgentItemView
+        item={{
+          id: 'message',
+          type: 'message',
+          role: 'assistant',
+          phase: 'final_answer',
+          status: 'completed',
+          content: [
+            {
+              type: 'output_text',
+              text: '**Done**\n\n|Result|Count|\n|---|---|\n|Passed|5|\n\n```js\nalert(1)\n```\n\n<script>alert(2)</script>\n\n![tracking](https://example.com/image.png)\n\n[bad](javascript:alert(3))',
+            },
+          ],
+        }}
+      />
+    )
+    expect(container.querySelector('strong')?.textContent).toBe('Assistant')
+    expect(container.querySelector('table')?.textContent).toContain('Passed')
+    expect(container.querySelector('pre code')?.textContent).toContain(
+      'alert(1)'
+    )
+    expect(container.querySelector('script')).toBeNull()
+    expect(container.querySelector('img')).toBeNull()
+    expect(container.querySelector('a')?.getAttribute('href')).not.toMatch(
+      /^javascript:/
+    )
+  })
+  it('keeps unknown tool payloads inspectable and distinguishes user messages', () => {
+    render(
+      <>
+        <AgentItemView
+          item={{
+            id: 'tool',
+            type: 'future_tool',
+            status: 'failed',
+            detail: 'Diagnostic',
+          }}
+        />
+        <AgentItemView
+          item={{
+            id: null,
+            type: 'message',
+            role: 'user',
+            content: [{ type: 'input_text', text: 'Hello' }],
+          }}
+        />
+      </>
+    )
+    expect(screen.getByText('future_tool · failed')).toBeTruthy()
+    expect(screen.getByText('You')).toBeTruthy()
+  })
+  it('does not connect saved output automatically and gives actionable configuration errors', async () => {
+    const fetch = vi.fn()
+    vi.stubGlobal('fetch', fetch)
+    render(
+      <AgentMonitorOutput
+        value={JSON.stringify({
+          version: 1,
+          id: 'saved',
+          sessionId: 'sess_saved',
+          pageSize: 50,
+        })}
+      />
+    )
+    expect(fetch).not.toHaveBeenCalled()
+    fireEvent.click(screen.getByRole('button', { name: 'Connect' }))
+    expect((await screen.findByRole('alert')).textContent).toContain(
+      'agents.configure'
+    )
+    expect(fetch).not.toHaveBeenCalled()
+  })
+  it('isolates malformed saved descriptors', () => {
+    render(<AgentMonitorOutput value='{"version":2}' />)
+    expect(screen.getByRole('alert').textContent).toContain('Unsupported')
+  })
+})
diff --git a/app/src/components/Agents/AgentMonitor.tsx b/app/src/components/Agents/AgentMonitor.tsx
new file mode 100644
index 00000000..b4d5dea5
--- /dev/null
+++ b/app/src/components/Agents/AgentMonitor.tsx
@@ -0,0 +1,240 @@
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+
+import {
+  resolveAgentMonitor,
+  mountAgentMonitor,
+} from '../../lib/agents/runtime'
+import {
+  parseMonitorDescriptor,
+  type AgentItem,
+  type AgentMonitorDescriptor,
+} from '../../lib/agents/types'
+
+/** Unknown API objects remain readable without enabling active HTML or scripts. */
+function Details({ title, value }: { title: string; value: unknown }) {
+  return (
+    <details className="my-2">
+      <summary className="cursor-pointer text-sm">{title}</summary>
+      <pre className="overflow-auto whitespace-pre-wrap rounded bg-nb-surface-2 p-3 text-xs [overflow-wrap:anywhere]">
+        {JSON.stringify(value, null, 2)}
+      </pre>
+    </details>
+  )
+}
+
+/** Render message content as safe GFM; tool calls retain their full structured payload. */
+export function AgentItemView({ item }: { item: AgentItem }) {
+  if (item.type !== 'message')
+    return (
+      <Details
+        title={`${item.type} · ${item.status ?? 'unknown'}`}
+        value={item}
+      />
+    )
+  return (
+    <article
+      className="border-b border-nb-border-strong py-4"
+      data-testid="agent-message"
+    >
+      <header className="mb-2 flex flex-wrap gap-2 text-xs text-nb-text-muted">
+        <strong className="text-nb-text">
+          {item.role === 'user'
+            ? 'You'
+            : item.role === 'assistant'
+              ? 'Assistant'
+              : (item.role ?? 'Message')}
+        </strong>
+        {item.phase && <span>{item.phase.replace(/_/g, ' ')}</span>}
+        <span>{item.status ?? 'unknown'}</span>
+      </header>
+      <div
+        data-testid="agent-message-content"
+        className="space-y-2 text-sm leading-relaxed [overflow-wrap:anywhere] [&_pre]:overflow-auto [&_pre]:rounded [&_pre]:bg-nb-surface-2 [&_pre]:p-3 [&_table]:w-full [&_td]:border [&_td]:p-2 [&_th]:border [&_th]:p-2 [&_ul]:list-disc [&_ul]:pl-5 [&_ol]:list-decimal [&_ol]:pl-5 [&_a]:underline"
+      >
+        {(item.content ?? []).map((part, index) => {
+          const text =
+            typeof part?.text === 'string'
+              ? part.text
+              : typeof part?.refusal === 'string'
+                ? part.refusal
+                : null
+          if (text !== null)
+            return (
+              <ReactMarkdown
+                key={index}
+                remarkPlugins={[remarkGfm]}
+                skipHtml
+                components={{
+                  a: ({ children, href }) => (
+                    <a href={href} target="_blank" rel="noopener noreferrer">
+                      {children}
+                    </a>
+                  ),
+                  img: ({ alt }) => <span>[Image: {alt || 'attachment'}]</span>,
+                }}
+              >
+                {text}
+              </ReactMarkdown>
+            )
+          return (
+            <Details
+              key={index}
+              title={String(part?.type ?? 'Content')}
+              value={part}
+            />
+          )
+        })}
+      </div>
+      <Details title="Message details" value={item} />
+    </article>
+  )
+}
+
+/** React observes the domain store; hiding the widget for editing keeps it mounted. */
+function Monitor({ descriptor }: { descriptor: AgentMonitorDescriptor }) {
+  const monitor = useMemo(() => resolveAgentMonitor(descriptor), [descriptor])
+  const state = useSyncExternalStore(monitor.subscribe, monitor.getSnapshot)
+  const viewport = useRef<HTMLDivElement>(null)
+  const follow = useRef(true)
+  useEffect(() => mountAgentMonitor(monitor), [monitor])
+  useEffect(() => {
+    if (!viewport.current) return
+    if (state.historical) viewport.current.scrollTop = 0
+    else if (follow.current)
+      viewport.current.scrollTop = viewport.current.scrollHeight
+  }, [state.items, state.historical])
+  const latest = () => {
+    follow.current = true
+    monitor.latest()
+    if (viewport.current)
+      viewport.current.scrollTop = viewport.current.scrollHeight
+  }
+  const active =
+    state.connection === 'live' || state.connection === 'connecting'
+  return (
+    <section
+      aria-label="Agent session monitor"
+      data-testid="agent-monitor"
+      className="p-4 text-nb-text"
+    >
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <div data-testid="agent-monitor-heading">
+          <strong>Agent session</strong>
+          <p className="font-mono text-xs [overflow-wrap:anywhere]">
+            {descriptor.sessionId}
+          </p>
+        </div>
+        <button
+          className="rounded border px-3 py-1 text-sm"
+          onClick={() => (active ? monitor.pause() : void monitor.connect())}
+        >
+          {active
+            ? 'Pause monitoring'
+            : state.connection === 'paused'
+              ? 'Resume monitoring'
+              : 'Connect'}
+        </button>
+      </header>
+      <p role="status" className="my-3 text-xs">
+        Session: {String(state.session?.status ?? 'unknown')} · Root turn:{' '}
+        {String(state.turn?.status ?? 'unknown')} · Connection:{' '}
+        {state.connection}
+      </p>
+      {state.error && (
+        <p
+          role="alert"
+          className="my-2 rounded bg-red-50 p-3 text-sm text-red-800"
+        >
+          {state.error}
+        </p>
+      )}
+      {state.turn?.error != null && (
+        <Details title="Turn error" value={state.turn.error} />
+      )}
+      {state.session?.error != null && (
+        <Details title="Session error" value={state.session.error} />
+      )}
+      <nav
+        aria-label="Agent history pages"
+        className="flex flex-wrap items-center gap-2 border-y py-2 text-sm"
+      >
+        <button
+          className="rounded border px-3 py-1 disabled:opacity-40"
+          disabled={!state.hasOlder || state.loadingPage}
+          onClick={() => void monitor.older()}
+        >
+          Older
+        </button>
+        <button
+          className="rounded border px-3 py-1 disabled:opacity-40"
+          disabled={!state.hasNewer || state.loadingPage}
+          onClick={() => void monitor.newer()}
+        >
+          Newer
+        </button>
+        <button className="rounded border px-3 py-1" onClick={latest}>
+          Latest{state.newActivity ? ` (${state.newActivity} updates)` : ''}
+        </button>
+        <span className="text-xs text-nb-text-muted">
+          {state.loadingPage
+            ? 'Loading…'
+            : state.historical
+              ? `${state.items.length} earlier items`
+              : `Latest ${state.items.length} items`}
+        </span>
+      </nav>
+      <div
+        ref={viewport}
+        data-testid="agent-monitor-timeline"
+        aria-label="Agent messages and tools"
+        tabIndex={0}
+        className="max-h-[32rem] min-h-24 overflow-auto"
+        onScroll={() => {
+          const element = viewport.current
+          if (element)
+            follow.current =
+              element.scrollHeight - element.scrollTop - element.clientHeight <
+              48
+        }}
+      >
+        {!state.items.length && (
+          <p className="py-6 text-sm text-nb-text-muted">
+            {state.connection === 'connecting'
+              ? 'Loading session history…'
+              : state.session
+                ? 'No saved items yet.'
+                : 'Run this cell or Connect to load session history.'}
+          </p>
+        )}
+        {state.items.map((item, index) => (
+          <AgentItemView key={item.id ?? `legacy-${index}`} item={item} />
+        ))}
+      </div>
+      {Array.isArray(state.session?.required_actions) &&
+        state.session.required_actions.length > 0 && (
+          <Details
+            title="Required actions — respond through your agent client"
+            value={state.session.required_actions}
+          />
+        )}
+      <Details
+        title={`Activity (${state.events.length} recent events)`}
+        value={state.events}
+      />
+    </section>
+  )
+}
+
+/** Malformed or future output versions produce a local diagnostic, not a broken notebook. */
+export function AgentMonitorOutput({ value }: { value: string }) {
+  const descriptor = useMemo(() => parseMonitorDescriptor(value), [value])
+  return descriptor ? (
+    <Monitor key={descriptor.id} descriptor={descriptor} />
+  ) : (
+    <p role="alert" className="p-3">
+      Unsupported or malformed agent monitor output. Edit and rerun the cell.
+    </p>
+  )
+}
diff --git a/app/src/generated/documentationManifest.ts b/app/src/generated/documentationManifest.ts
index 37950cb1..2b92cc88 100644
--- a/app/src/generated/documentationManifest.ts
+++ b/app/src/generated/documentationManifest.ts
@@ -162,4 +162,12 @@ export const DOCUMENTATION_MANIFEST = [
     order: 19,
     path: 'docs/19-notebook-review-rounds.md',
   },
+  {
+    name: 'agent-monitors',
+    title: 'Agent session monitors',
+    description:
+      'Render Agents API sessions in JavaScript cells with live Markdown, tool details, turn status, and history pagination.',
+    order: 20,
+    path: 'docs/20-agent-monitors.md',
+  },
 ] as const satisfies readonly DocumentationManifestEntry[]
diff --git a/app/src/lib/agents/bridge.ts b/app/src/lib/agents/bridge.ts
new file mode 100644
index 00000000..76e3404d
--- /dev/null
+++ b/app/src/lib/agents/bridge.ts
@@ -0,0 +1,30 @@
+import type { createAgentsApi } from './runtime'
+
+/** Explicit allowlist prevents sandbox code from installing credential callbacks. */
+export function callAgentsBridge(
+  api: ReturnType<typeof createAgentsApi>,
+  method: string,
+  args: unknown[]
+): unknown {
+  const id = String(args[0] ?? '')
+  switch (method) {
+    case 'agents.help':
+      return api.help()
+    case 'agents.monitor':
+      return api.monitor(id, (args[1] ?? {}) as { pageSize?: number })
+    case 'agents.get':
+      return api.get(id)
+    case 'agents.pause':
+      return api.pause(id)
+    case 'agents.resume':
+      return api.resume(id)
+    case 'agents.older':
+      return api.older(id)
+    case 'agents.newer':
+      return api.newer(id)
+    case 'agents.latest':
+      return api.latest(id)
+    default:
+      throw new Error(`Unsupported agents sandbox method: ${method}`)
+  }
+}
diff --git a/app/src/lib/agents/monitor.test.ts b/app/src/lib/agents/monitor.test.ts
new file mode 100644
index 00000000..28c14628
--- /dev/null
+++ b/app/src/lib/agents/monitor.test.ts
@@ -0,0 +1,261 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { AgentMonitor } from './monitor'
+import type { AgentEvent, AgentItem, AgentTransport } from './types'
+
+const item = (id: string, text = id): AgentItem => ({
+  id,
+  type: 'message',
+  role: 'assistant',
+  status: 'completed',
+  content: [{ type: 'output_text', text }],
+})
+const page = (ids: string[], has_more = false) => ({
+  data: ids.map((id) => item(id)),
+  has_more,
+  last_id: ids[ids.length - 1] ?? null,
+})
+const models: AgentMonitor[] = []
+afterEach(() => {
+  models.forEach((model) => model.pause())
+  models.length = 0
+  vi.useRealTimers()
+})
+
+/** In-memory stream fixture exercises the controller without a fake network server. */
+function setup(overrides: Partial<AgentTransport> = {}) {
+  let deliver: ((value: IteratorResult<AgentEvent>) => void) | undefined
+  const queued: AgentEvent[] = []
+  const close = vi.fn(() => deliver?.({ done: true, value: undefined }))
+  const transport: AgentTransport = {
+    session: vi.fn(async () => ({ status: 'idle' })),
+    items: vi.fn(async () => page(['b', 'a'], true)),
+    turns: vi.fn(async () => ({
+      data: [
+        { id: 'root', status: 'completed', subagent_id: null, created_at: 1 },
+      ],
+      has_more: false,
+      last_id: 'root',
+    })),
+    stream: vi.fn(async () => ({
+      close,
+      events: {
+        [Symbol.asyncIterator]: () => ({
+          next: () =>
+            queued.length
+              ? Promise.resolve({ done: false, value: queued.shift()! })
+              : new Promise<IteratorResult<AgentEvent>>((resolve) => {
+                  deliver = resolve
+                }),
+        }),
+      },
+    })),
+    ...overrides,
+  }
+  const model = new AgentMonitor(
+    { version: 1, id: 'widget', sessionId: 'sess_test', pageSize: 2 },
+    () => transport
+  )
+  models.push(model)
+  return {
+    model,
+    transport,
+    close,
+    push: (event: AgentEvent) => {
+      if (deliver) {
+        const next = deliver
+        deliver = undefined
+        next({ done: false, value: event })
+      } else queued.push(event)
+    },
+  }
+}
+
+describe('AgentMonitor', () => {
+  it('does not regress final items or root turns when older events arrive', async () => {
+    const { model } = setup()
+    await model.connect()
+    model.applyEvent({
+      type: 'agent.session.turn.item.added',
+      item: { ...item('b', 'stale'), status: 'in_progress' },
+    })
+    model.applyEvent(
+      {
+        type: 'agent.session.turn.in_progress',
+        turn: {
+          id: 'root',
+          subagent_id: null,
+          created_at: 1,
+          status: 'in_progress',
+        },
+      },
+      true
+    )
+    expect(model.getSnapshot().items[1].content?.[0].text).toBe('b')
+    expect(model.getSnapshot().turn?.status).toBe('completed')
+  })
+  it('loads one descending page, renders chronologically and does not confuse idle with success', async () => {
+    const { model, transport } = setup({
+      turns: async () => ({ data: [], has_more: false, last_id: null }),
+    })
+    await model.connect()
+    expect(transport.items).toHaveBeenCalledWith(
+      'sess_test',
+      2,
+      undefined,
+      expect.any(AbortSignal)
+    )
+    expect(model.getSnapshot().items.map((x) => x.id)).toEqual(['a', 'b'])
+    expect(model.getSnapshot().turn).toBeNull()
+    expect(model.getSnapshot().connection).toBe('live')
+  })
+  it('deduplicates deltas, accepts done without deltas, and ignores late deltas', async () => {
+    const { model } = setup()
+    await model.connect()
+    const delta = {
+      type: 'agent.session.turn.output_text.delta',
+      event_id: 'e',
+      item_id: 'c',
+      output_index: 0,
+      content_index: 0,
+      delta: 'partial',
+    }
+    model.applyEvent(delta)
+    model.applyEvent(delta)
+    expect(model.getSnapshot().items[1].content?.[0].text).toBe('partial')
+    model.applyEvent({
+      ...delta,
+      type: 'agent.session.turn.output_text.done',
+      event_id: 'done',
+      text: '**complete**',
+    })
+    model.applyEvent({ ...delta, event_id: 'late' })
+    expect(model.getSnapshot().items[1].content?.[0].text).toBe('**complete**')
+    model.applyEvent({
+      ...delta,
+      type: 'agent.session.turn.output_text.done',
+      event_id: 'other',
+      item_id: 'd',
+      text: 'No deltas',
+    })
+    expect(model.getSnapshot().items[1].content?.[0].text).toBe('No deltas')
+  })
+  it('keeps historical items fixed while live activity arrives and uses server cursors', async () => {
+    const { model, transport } = setup({
+      items: vi.fn(async (_id, _limit, after) =>
+        after ? page(['old2', 'old1']) : page(['b', 'a'], true)
+      ),
+    })
+    await model.connect()
+    await model.older()
+    model.applyEvent({ type: 'agent.session.turn.item.added', item: item('c') })
+    expect(model.getSnapshot().items.map((x) => x.id)).toEqual(['old1', 'old2'])
+    expect(model.getSnapshot().newActivity).toBe(1)
+    expect(transport.items).toHaveBeenLastCalledWith(
+      'sess_test',
+      2,
+      'a',
+      expect.any(AbortSignal)
+    )
+    model.latest()
+    expect(model.getSnapshot().items.map((x) => x.id)).toEqual(['b', 'c'])
+    expect(model.getSnapshot().newActivity).toBe(0)
+  })
+  it('ignores child turn completion and idle when tracking the root turn', async () => {
+    const { model } = setup()
+    await model.connect()
+    model.applyEvent({
+      type: 'agent.session.turn.in_progress',
+      turn: {
+        id: 'next',
+        status: 'in_progress',
+        subagent_id: null,
+        created_at: 2,
+      },
+    })
+    model.applyEvent({
+      type: 'agent.session.turn.completed',
+      turn: {
+        id: 'child',
+        subagent_id: 'sub_1',
+        status: 'completed',
+        created_at: 3,
+      },
+    })
+    model.applyEvent({
+      type: 'agent.session.idle',
+      session: { status: 'idle' },
+    })
+    expect(model.getSnapshot().turn?.status).toBe('in_progress')
+  })
+  it('buffers during hydration and drops replayed deltas for finalized saved items', async () => {
+    let resolvePage!: (value: ReturnType<typeof page>) => void
+    const { model, push } = setup({
+      items: () =>
+        new Promise((resolve) => {
+          resolvePage = resolve
+        }),
+    })
+    const ready = model.connect()
+    await vi.waitFor(() => expect(resolvePage).toBeTypeOf('function'))
+    push({
+      type: 'agent.session.turn.output_text.delta',
+      item_id: 'b',
+      output_index: 0,
+      content_index: 0,
+      delta: ' duplicate',
+    })
+    await Promise.resolve()
+    resolvePage(page(['b', 'a']))
+    await ready
+    expect(model.getSnapshot().items[1].content?.[0].text).toBe('b')
+  })
+  it('does not revive a monitor after pause during hydration', async () => {
+    let resolvePage!: (value: ReturnType<typeof page>) => void
+    const { model, close } = setup({
+      items: () =>
+        new Promise((resolve) => {
+          resolvePage = resolve
+        }),
+    })
+    const ready = model.connect()
+    await vi.waitFor(() => expect(resolvePage).toBeTypeOf('function'))
+    model.pause()
+    resolvePage(page(['late']))
+    await ready
+    expect(model.getSnapshot().connection).toBe('paused')
+    expect(model.getSnapshot().items).toEqual([])
+    expect(close).toHaveBeenCalled()
+  })
+  it('shows stream EOF as disconnected and preserves items', async () => {
+    const { model, close } = setup()
+    await model.connect()
+    close()
+    await vi.waitFor(() =>
+      expect(model.getSnapshot().connection).toBe('disconnected')
+    )
+    expect(model.getSnapshot().items).toHaveLength(2)
+  })
+  it('refuses a non-advancing or missing history cursor', async () => {
+    const { model } = setup({
+      items: async () => ({ ...page(['b', 'a'], true), last_id: null }),
+    })
+    await model.connect()
+    await model.older()
+    expect(model.getSnapshot().error).toContain('pagination cursor')
+  })
+  it('caps activity and live items and preserves legacy null IDs', async () => {
+    const { model } = setup({
+      items: async () => ({
+        data: [item('a'), { ...item('legacy'), id: null }],
+        has_more: false,
+        last_id: null,
+      }),
+    })
+    await model.connect()
+    expect(model.getSnapshot().items).toHaveLength(2)
+    for (let i = 0; i < 110; i++)
+      model.applyEvent({ type: 'future.event', event_id: `e${i}` })
+    expect(model.getSnapshot().events).toHaveLength(100)
+  })
+})
diff --git a/app/src/lib/agents/monitor.ts b/app/src/lib/agents/monitor.ts
new file mode 100644
index 00000000..85c8a02d
--- /dev/null
+++ b/app/src/lib/agents/monitor.ts
@@ -0,0 +1,391 @@
+import type {
+  AgentEvent,
+  AgentItem,
+  AgentMonitorDescriptor,
+  AgentObject,
+  AgentPage,
+  AgentStream,
+  AgentTransport,
+} from './types'
+
+export type MonitorSnapshot = {
+  connection: 'disconnected' | 'connecting' | 'live' | 'paused'
+  session: AgentObject | null
+  turn: AgentObject | null
+  items: AgentItem[]
+  events: AgentEvent[]
+  historical: boolean
+  hasOlder: boolean
+  hasNewer: boolean
+  newActivity: number
+  loadingPage: boolean
+  error: string | null
+}
+const finalStatuses = new Set([
+  'completed',
+  'failed',
+  'cancelled',
+  'incomplete',
+])
+const object = (value: unknown): AgentObject | null =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as AgentObject)
+    : null
+const message = (error: unknown) =>
+  error instanceof Error ? error.message : 'Agent monitor request failed.'
+
+/** Owns one monitor's bounded live window, history cursor stack and stream lifecycle. */
+export class AgentMonitor {
+  private snapshot: MonitorSnapshot = {
+    connection: 'disconnected',
+    session: null,
+    turn: null,
+    items: [],
+    events: [],
+    historical: false,
+    hasOlder: false,
+    hasNewer: false,
+    newActivity: 0,
+    loadingPage: false,
+    error: null,
+  }
+  private listeners = new Set<() => void>()
+  private controller?: AbortController
+  private stream?: AgentStream
+  private pageController?: AbortController
+  private live: AgentItem[] = []
+  private liveHasMore = false
+  private liveCursor: string | null = null
+  private historyCursor: string | null = null
+  private cursors: Array<string | undefined> = []
+  private seen = new Set<string>()
+  private finalParts = new Set<string>()
+  private restoredFinalIds = new Set<string>()
+  private refreshTimer?: ReturnType<typeof setTimeout>
+
+  constructor(
+    readonly descriptor: AgentMonitorDescriptor,
+    private readonly transport: () => AgentTransport
+  ) {}
+
+  getSnapshot = (): MonitorSnapshot => this.snapshot
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+  private update(patch: Partial<MonitorSnapshot>) {
+    this.snapshot = { ...this.snapshot, ...patch }
+    this.listeners.forEach((listener) => listener())
+  }
+
+  /** Stop observation only. Never sends a cancel or other input event. */
+  pause = () => {
+    this.controller?.abort()
+    this.stream?.close()
+    this.pageController?.abort()
+    clearTimeout(this.refreshTimer)
+    this.refreshTimer = undefined
+    this.update({ connection: 'paused', loadingPage: false })
+  }
+
+  /** Subscribe before retrieving history, then replay only updates not already final. */
+  connect = async (): Promise<void> => {
+    this.pause()
+    const controller = new AbortController()
+    this.controller = controller
+    const { signal } = controller
+    this.seen.clear()
+    this.finalParts.clear()
+    this.update({ connection: 'connecting', error: null })
+    let stream: AgentStream | undefined
+    try {
+      const transport = this.transport()
+      stream = await transport.stream(this.descriptor.sessionId, signal)
+      if (signal.aborted) {
+        stream.close()
+        return
+      }
+      this.stream = stream
+      let buffered: AgentEvent[] | null = []
+      let bufferedBytes = 0
+      // Consume immediately; an EOF during hydration invalidates that hydration too.
+      void (async () => {
+        try {
+          for await (const event of stream!.events) {
+            if (signal.aborted) return
+            if (buffered) {
+              bufferedBytes += JSON.stringify(event).length
+              if (buffered.length >= 2000 || bufferedBytes > 4 * 1024 * 1024)
+                throw new Error(
+                  'Too much activity while loading history. Reconnect to retrieve saved output.'
+                )
+              buffered.push(event)
+            } else {
+              this.applyEvent(event)
+            }
+          }
+          if (!signal.aborted)
+            throw new Error(
+              'Event stream disconnected. Reconnect to retrieve saved output.'
+            )
+        } catch (error) {
+          if (!signal.aborted) {
+            this.update({ connection: 'disconnected', error: message(error) })
+            controller.abort()
+            stream?.close()
+          }
+        }
+      })()
+      const [session, page, turns] = await Promise.all([
+        transport.session(this.descriptor.sessionId, signal),
+        transport.items(
+          this.descriptor.sessionId,
+          this.descriptor.pageSize,
+          undefined,
+          signal
+        ),
+        transport.turns(this.descriptor.sessionId, signal),
+      ])
+      if (signal.aborted) return
+      this.installLive(page)
+      this.restoredFinalIds = new Set(
+        this.live
+          .filter((item) => item.id && finalStatuses.has(item.status ?? ''))
+          .map((item) => item.id!)
+      )
+      this.update({
+        session,
+        turn: turns.data.find((turn) => turn.subagent_id === null) ?? null,
+        connection: 'live',
+      })
+      const events = buffered ?? []
+      buffered = null
+      for (const event of events) {
+        if (signal.aborted || session.status === 'failed') break
+        this.applyEvent(event, true)
+      }
+      if (
+        session.status === 'failed' ||
+        this.snapshot.session?.status === 'failed'
+      ) {
+        controller.abort()
+        stream.close()
+        this.update({
+          connection: 'disconnected',
+          error:
+            'Session failed. Resolve the session failure before reconnecting.',
+        })
+      }
+    } catch (error) {
+      if (!signal.aborted) {
+        controller.abort()
+        stream?.close()
+        this.update({ connection: 'disconnected', error: message(error) })
+      }
+    }
+  }
+
+  /** History is never implicitly merged with a live window: pages stay bounded. */
+  private installLive(page: AgentPage<AgentItem>) {
+    this.live = [...page.data].reverse().slice(-this.descriptor.pageSize)
+    this.liveCursor = page.last_id
+    this.liveHasMore = page.has_more
+    if (!this.snapshot.historical)
+      this.update({ items: this.live, hasOlder: page.has_more })
+  }
+
+  /** Refresh saved statuses after terminal turn events without replaying old deltas. */
+  private scheduleRefresh() {
+    if (this.refreshTimer || this.controller?.signal.aborted) return
+    this.refreshTimer = setTimeout(() => {
+      this.refreshTimer = undefined
+      // Full reconnect applies the documented stream-before-snapshot recovery sequence.
+      void this.connect()
+    }, 500)
+  }
+
+  /** Reduce known events; retain unfamiliar events in the bounded activity log. */
+  applyEvent(event: AgentEvent, replay = false) {
+    if (event.session_id && event.session_id !== this.descriptor.sessionId)
+      return
+    if (event.event_id && this.seen.has(event.event_id)) return
+    if (event.event_id) {
+      this.seen.add(event.event_id)
+      if (this.seen.size > 2000)
+        this.seen.delete(this.seen.values().next().value!)
+    }
+    this.update({
+      events: [...this.snapshot.events, event].slice(-100),
+      newActivity: this.snapshot.historical ? this.snapshot.newActivity + 1 : 0,
+    })
+    const session = object(event.session)
+    if (session) this.update({ session })
+    const turn = object(event.turn)
+    if (turn?.subagent_id === null) {
+      // Late completion of an older turn cannot replace a newer running turn.
+      const previous = this.snapshot.turn
+      if (
+        !previous ||
+        (turn.id === previous.id
+          ? !finalStatuses.has(String(previous.status)) ||
+            finalStatuses.has(String(turn.status))
+          : Number(turn.created_at ?? 0) >= Number(previous.created_at ?? 0))
+      ) {
+        this.update({ turn })
+      }
+      if (!replay && finalStatuses.has(String(turn.status)))
+        this.scheduleRefresh()
+    }
+    if (!replay && event.type === 'agent.session.requires_action' && !session)
+      this.scheduleRefresh()
+    if (
+      [
+        'error',
+        'agent.session.failed',
+        'agent.session.environment.failed',
+      ].includes(event.type)
+    ) {
+      this.pause()
+      this.update({
+        connection: 'disconnected',
+        error:
+          event.type === 'error'
+            ? 'The agent reported an error. Inspect Activity for details.'
+            : `Agent lifecycle failure: ${event.type}`,
+      })
+      return
+    }
+    if (event.subagent_id != null) return
+    const item = object(event.item) as AgentItem | null
+    if (event.type === 'agent.session.turn.item.added' && item) {
+      if (!(replay && item.id && this.restoredFinalIds.has(item.id)))
+        this.upsert(item)
+      return
+    }
+    if (event.type === 'agent.session.turn.item.done') {
+      if (item && !(replay && item.id && this.restoredFinalIds.has(item.id)))
+        this.upsert(item)
+      return
+    }
+    const isDelta = event.type === 'agent.session.turn.output_text.delta'
+    const isDone = event.type === 'agent.session.turn.output_text.done'
+    if (!isDelta && !isDone) return
+    const id = typeof event.item_id === 'string' ? event.item_id : ''
+    const index = Number(event.content_index)
+    if (!id || !Number.isInteger(index) || index < 0 || index > 1000) return
+    if (replay && this.restoredFinalIds.has(id)) return
+    const key = `${id}:${event.output_index}:${index}`
+    if (isDelta && this.finalParts.has(key)) return
+    const old = this.live.find((value) => value.id === id)
+    if (old && finalStatuses.has(old.status ?? '')) return
+    const content = [...(old?.content ?? [])]
+    const text = isDone
+      ? String(event.text ?? '')
+      : String(content[index]?.text ?? '') + String(event.delta ?? '')
+    content[index] = { type: 'output_text', text }
+    this.upsert({
+      ...old,
+      id,
+      type: 'message',
+      role: old?.role ?? 'assistant',
+      turn_id: typeof event.turn_id === 'string' ? event.turn_id : old?.turn_id,
+      status: old?.status ?? 'in_progress',
+      content,
+    })
+    if (isDone) {
+      this.finalParts.add(key)
+      if (this.finalParts.size > 1000)
+        this.finalParts.delete(this.finalParts.values().next().value!)
+    }
+  }
+
+  private upsert(item: AgentItem) {
+    const index = item.id
+      ? this.live.findIndex((value) => value.id === item.id)
+      : -1
+    const next = [...this.live]
+    // A delayed item.added cannot replace an authoritative final item.
+    if (index >= 0) {
+      if (
+        finalStatuses.has(next[index].status ?? '') &&
+        !finalStatuses.has(item.status ?? '')
+      )
+        return
+      next[index] = item
+    } else next.push(item)
+    if (next.length > this.descriptor.pageSize) this.liveHasMore = true
+    this.live = next.slice(-this.descriptor.pageSize)
+    // The oldest displayed item is the descending-order cursor after live eviction.
+    this.liveCursor = this.live[0]?.id ?? this.liveCursor
+    if (!this.snapshot.historical)
+      this.update({ items: this.live, hasOlder: this.liveHasMore })
+  }
+
+  older = async () => {
+    if (this.snapshot.loadingPage || !this.snapshot.hasOlder) return
+    const cursor = this.snapshot.historical
+      ? this.historyCursor
+      : this.liveCursor
+    if (!cursor) {
+      this.update({
+        error: 'History has more items but no usable pagination cursor.',
+      })
+      return
+    }
+    await this.loadPage(cursor, [...this.cursors, cursor])
+  }
+  newer = async () => {
+    if (this.snapshot.loadingPage) return
+    if (this.cursors.length <= 1) {
+      this.latest()
+      return
+    }
+    const cursors = this.cursors.slice(0, -1)
+    await this.loadPage(cursors[cursors.length - 1], cursors)
+  }
+  latest = () => {
+    this.pageController?.abort()
+    this.cursors = []
+    this.update({
+      historical: false,
+      items: this.live,
+      hasOlder: this.liveHasMore,
+      hasNewer: false,
+      newActivity: 0,
+      loadingPage: false,
+    })
+  }
+
+  private async loadPage(
+    after: string | undefined,
+    cursors: Array<string | undefined>
+  ) {
+    this.pageController?.abort()
+    const controller = new AbortController()
+    this.pageController = controller
+    this.update({ loadingPage: true, error: null })
+    try {
+      const page = await this.transport().items(
+        this.descriptor.sessionId,
+        this.descriptor.pageSize,
+        after,
+        controller.signal
+      )
+      if (controller.signal.aborted) return
+      if (page.has_more && (!page.last_id || page.last_id === after))
+        throw new Error('History returned a non-advancing pagination cursor.')
+      this.historyCursor = page.last_id
+      this.cursors = cursors
+      this.update({
+        items: [...page.data].reverse(),
+        historical: true,
+        hasOlder: page.has_more,
+        hasNewer: true,
+        loadingPage: false,
+      })
+    } catch (error) {
+      if (!controller.signal.aborted)
+        this.update({ loadingPage: false, error: message(error) })
+    }
+  }
+}
diff --git a/app/src/lib/agents/runtime.test.ts b/app/src/lib/agents/runtime.test.ts
new file mode 100644
index 00000000..755fed4f
--- /dev/null
+++ b/app/src/lib/agents/runtime.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { callAgentsBridge } from './bridge'
+import {
+  createAgentsApi,
+  mountAgentMonitor,
+  resetAgentMonitors,
+  resolveAgentMonitor,
+} from './runtime'
+import { AGENT_MONITOR_MIME, parseMonitorDescriptor } from './types'
+
+afterEach(resetAgentMonitors)
+describe('agents runtime', () => {
+  it('survives the StrictMode remount probe and requires explicit connection after closing', async () => {
+    const api = createAgentsApi(() => {})
+    const monitor = resolveAgentMonitor(api.monitor('sess_test'))
+    const connect = vi.spyOn(monitor, 'connect').mockResolvedValue()
+    const pause = vi.spyOn(monitor, 'pause')
+    const first = mountAgentMonitor(monitor)
+    first()
+    const second = mountAgentMonitor(monitor)
+    await Promise.resolve()
+    expect(pause).not.toHaveBeenCalled()
+    second()
+    await Promise.resolve()
+    expect(pause).toHaveBeenCalledTimes(1)
+    connect.mockClear()
+    const reopened = mountAgentMonitor(monitor)
+    expect(connect).not.toHaveBeenCalled()
+    reopened()
+    await Promise.resolve()
+  })
+  it('emits only a serializable descriptor and never credential configuration', () => {
+    const outputs: string[] = []
+    const api = createAgentsApi((mime, value) => {
+      expect(mime).toBe(AGENT_MONITOR_MIME)
+      outputs.push(value)
+    })
+    api.configure({
+      baseUrl: 'https://api.openai.com/v1',
+      getHeaders: () => ({ Authorization: 'secret' }),
+    })
+    const widget = api.monitor('sess_test')
+    expect(parseMonitorDescriptor(outputs[0])).toEqual(widget)
+    expect(outputs[0]).not.toContain('secret')
+    expect(Object.keys(widget)).toEqual([
+      'version',
+      'id',
+      'sessionId',
+      'pageSize',
+    ])
+    expect(api.get(widget.id).connection).toBe('disconnected')
+    callAgentsBridge(api, 'agents.pause', [widget.id])
+    expect(api.get(widget.id).connection).toBe('paused')
+  })
+  it('rejects invalid page sizes and disallows sandbox configuration', () => {
+    const api = createAgentsApi(() => {})
+    expect(() => api.monitor('s', { pageSize: 101 })).toThrow('pageSize')
+    expect(() => api.monitor('')).toThrow('sessionId')
+    expect(() => callAgentsBridge(api, 'agents.configure', [])).toThrow(
+      'Unsupported'
+    )
+    expect(() => createAgentsApi().monitor('s')).toThrow('notebook JS cell')
+  })
+})
diff --git a/app/src/lib/agents/runtime.ts b/app/src/lib/agents/runtime.ts
new file mode 100644
index 00000000..2aee8edd
--- /dev/null
+++ b/app/src/lib/agents/runtime.ts
@@ -0,0 +1,125 @@
+import { AgentMonitor } from './monitor'
+import { type AgentConnectionOptions, createAgentTransport } from './transport'
+import {
+  AGENT_MONITOR_MIME,
+  type AgentMonitorDescriptor,
+  type AgentTransport,
+} from './types'
+
+type Display = (mime: string, value: string) => void
+let connection: AgentTransport | undefined
+// This registry owns only this browser lifetime. Descriptors never carry auth or code.
+const monitors = new Map<string, AgentMonitor>()
+const autoConnect = new WeakSet<AgentMonitor>()
+const mountedViews = new WeakMap<AgentMonitor, number>()
+
+/** Resolve a saved descriptor without automatically connecting an opened notebook. */
+export function resolveAgentMonitor(
+  descriptor: AgentMonitorDescriptor
+): AgentMonitor {
+  const existing = monitors.get(descriptor.id)
+  if (
+    existing &&
+    existing.descriptor.sessionId === descriptor.sessionId &&
+    existing.descriptor.pageSize === descriptor.pageSize
+  )
+    return existing
+  const monitor = new AgentMonitor(descriptor, () => {
+    if (!connection)
+      throw new Error(
+        'Configure an authenticated connection with agents.configure({ baseUrl, getHeaders }) in AppKernel browser JS, then Connect.'
+      )
+    return connection
+  })
+  // Bound retained, detached monitor state; active widgets still own their controllers.
+  if (monitors.size >= 100) {
+    const oldest = [...monitors.entries()].find(
+      ([, monitor]) => !mountedViews.get(monitor)
+    )
+    if (oldest) {
+      oldest[1].pause()
+      monitors.delete(oldest[0])
+    }
+  }
+  monitors.set(descriptor.id, monitor)
+  return monitor
+}
+
+/** Share a controller across output views and release it after the last view unmounts.
+ * Deferring disposal one microtask tolerates React StrictMode's cleanup/remount probe.
+ */
+export function mountAgentMonitor(monitor: AgentMonitor): () => void {
+  mountedViews.set(monitor, (mountedViews.get(monitor) ?? 0) + 1)
+  if (
+    autoConnect.has(monitor) &&
+    !['live', 'connecting'].includes(monitor.getSnapshot().connection)
+  )
+    void monitor.connect()
+  return () => {
+    mountedViews.set(monitor, (mountedViews.get(monitor) ?? 1) - 1)
+    queueMicrotask(() => {
+      if (mountedViews.get(monitor)) return
+      monitor.pause()
+      autoConnect.delete(monitor)
+    })
+  }
+}
+
+/** Release process-local configuration and subscriptions (also used by tests). */
+export function resetAgentMonitors(): void {
+  monitors.forEach((monitor) => monitor.pause())
+  monitors.clear()
+  connection = undefined
+}
+
+/** The same commands back widget buttons, AppKernel cells and the sandbox bridge. */
+export function createAgentsApi(display?: Display) {
+  const requireMonitor = (id: string) => {
+    const monitor = monitors.get(id)
+    if (!monitor)
+      throw new Error(
+        'Monitor is not mounted in this browser session. Run its cell first.'
+      )
+    return monitor
+  }
+  return {
+    configure: (options: AgentConnectionOptions) => {
+      // Disconnect existing views before changing the authority serving their IDs.
+      monitors.forEach((monitor) => monitor.pause())
+      connection = createAgentTransport(options)
+      return { configured: true }
+    },
+    monitor: (
+      sessionId: string,
+      options: { pageSize?: number } = {}
+    ): AgentMonitorDescriptor => {
+      if (!display)
+        throw new Error(
+          'agents.monitor must run in a notebook JS cell. Insert and execute a JS cell through notebooks.*.'
+        )
+      const pageSize = options.pageSize ?? 50
+      if (typeof sessionId !== 'string' || !sessionId.trim())
+        throw new Error('sessionId must be non-empty.')
+      if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100)
+        throw new Error('pageSize must be between 1 and 100.')
+      const descriptor: AgentMonitorDescriptor = {
+        version: 1,
+        id: crypto.randomUUID(),
+        sessionId: sessionId.trim(),
+        pageSize,
+      }
+      const monitor = resolveAgentMonitor(descriptor)
+      autoConnect.add(monitor)
+      display(AGENT_MONITOR_MIME, JSON.stringify(descriptor))
+      return descriptor
+    },
+    get: (id: string) => requireMonitor(id).getSnapshot(),
+    pause: (id: string) => requireMonitor(id).pause(),
+    resume: (id: string) => requireMonitor(id).connect(),
+    older: (id: string) => requireMonitor(id).older(),
+    newer: (id: string) => requireMonitor(id).newer(),
+    latest: (id: string) => requireMonitor(id).latest(),
+    help: () =>
+      'agents.configure({ baseUrl, getHeaders? }) [browser JS only; memory-only auth]; agents.monitor(sessionId, { pageSize?: 1..100 }) [notebook JS cell]; agents.get(id); agents.pause(id); await agents.resume(id); await agents.older(id); await agents.newer(id); agents.latest(id). Pause stops observation, not the agent. Saved widgets require Connect.',
+  }
+}
diff --git a/app/src/lib/agents/transport.test.ts b/app/src/lib/agents/transport.test.ts
new file mode 100644
index 00000000..f27ba80a
--- /dev/null
+++ b/app/src/lib/agents/transport.test.ts
@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createAgentTransport, readAgentEvents } from './transport'
+
+afterEach(() => vi.unstubAllGlobals())
+describe('agent transport', () => {
+  it('decodes split UTF-8, CRLF, comments and multiline SSE data', async () => {
+    const bytes = new TextEncoder().encode(
+      ': heartbeat\r\ndata: {"type":"test",\r\ndata: "text":"👋"}\r\n\r\ndata: [DONE]\n\n'
+    )
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        for (const byte of bytes) controller.enqueue(Uint8Array.of(byte))
+        controller.close()
+      },
+    })
+    const events = []
+    for await (const event of readAgentEvents(stream)) events.push(event)
+    expect(events).toEqual([{ type: 'test', text: '👋' }])
+  })
+  it('requests bounded descending pages with encoded cursors and refreshed headers', async () => {
+    const fetch = vi.fn<(url: string, options?: RequestInit) => Promise<Response>>(
+      async () => new Response(JSON.stringify({ data: [] }))
+    )
+    vi.stubGlobal('fetch', fetch)
+    const getHeaders = vi.fn(() => ({ Authorization: 'Bearer secret' }))
+    const api = createAgentTransport({
+      baseUrl: 'https://api.openai.com/v1',
+      getHeaders,
+    })
+    const signal = new AbortController().signal
+    await api.items('sess/1', 50, 'a&b', signal)
+    await api.session('sess/1', signal)
+    expect(fetch.mock.calls[0][0]).toBe(
+      'https://api.openai.com/v1/agents/sessions/sess%2F1/items?order=desc&limit=50&after=a%26b'
+    )
+    expect(getHeaders).toHaveBeenCalledTimes(2)
+  })
+  it('does not reflect secret-bearing error bodies', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('Authorization: secret', { status: 401 }))
+    )
+    await expect(
+      createAgentTransport({ baseUrl: 'https://api.openai.com/v1' }).session(
+        's',
+        new AbortController().signal
+      )
+    ).rejects.toThrow('HTTP 401')
+  })
+})
diff --git a/app/src/lib/agents/transport.ts b/app/src/lib/agents/transport.ts
new file mode 100644
index 00000000..05e2b5c4
--- /dev/null
+++ b/app/src/lib/agents/transport.ts
@@ -0,0 +1,142 @@
+import type {
+  AgentEvent,
+  AgentItem,
+  AgentObject,
+  AgentPage,
+  AgentTransport,
+} from './types'
+
+export type AgentConnectionOptions = {
+  baseUrl: string
+  getHeaders?: () => HeadersInit | Promise<HeadersInit>
+}
+
+/** Decode SSE incrementally, including CRLF, multiline data and split UTF-8. */
+export async function* readAgentEvents(
+  body: ReadableStream<Uint8Array>
+): AsyncGenerator<AgentEvent> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let pending = ''
+  let data: string[] = []
+  let eventBytes = 0
+  try {
+    while (true) {
+      const chunk = await reader.read()
+      pending += decoder.decode(chunk.value, { stream: !chunk.done })
+      if (pending.length + eventBytes > 2 * 1024 * 1024)
+        throw new Error('Agent event exceeds the 2 MiB limit.')
+      let newline: number
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        const line = pending.slice(0, newline).replace(/\r$/, '')
+        pending = pending.slice(newline + 1)
+        if (line.startsWith('data:')) {
+          const value = line.slice(5).replace(/^ /, '')
+          data.push(value)
+          eventBytes += value.length
+        } else if (!line && data.length) {
+          const payload = data.join('\n')
+          data = []
+          eventBytes = 0
+          if (payload === '[DONE]') return
+          const event = JSON.parse(payload)
+          if (!event || typeof event.type !== 'string')
+            throw new Error('Malformed agent event.')
+          yield event as AgentEvent
+        }
+      }
+      if (chunk.done) return
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
+    reader.releaseLock()
+  }
+}
+
+/** Read-only REST/SSE transport. Secrets remain in the caller's header provider. */
+export function createAgentTransport(
+  options: AgentConnectionOptions
+): AgentTransport {
+  const base = new URL(
+    options.baseUrl,
+    typeof location === 'undefined' ? 'http://localhost' : location.origin
+  )
+  if (
+    !['https:', 'http:'].includes(base.protocol) ||
+    base.username ||
+    base.password ||
+    base.search ||
+    base.hash
+  ) {
+    throw new Error(
+      'Agents baseUrl must be an HTTP(S) API root without credentials, query, or fragment.'
+    )
+  }
+  const root = base.href.replace(/\/$/, '')
+  const request = async (path: string, signal: AbortSignal, stream = false) => {
+    const headers = new Headers(await options.getHeaders?.())
+    headers.set('OpenAI-Beta', 'agents=v1')
+    headers.set('Accept', stream ? 'text/event-stream' : 'application/json')
+    const response = await fetch(`${root}/agents/sessions/${path}`, {
+      headers,
+      signal,
+      credentials: 'same-origin',
+      redirect: 'error',
+      cache: 'no-store',
+    })
+    // Do not echo upstream response bodies: gateways can include credentials.
+    if (!response.ok)
+      throw new Error(
+        `Agents API returned HTTP ${response.status}. Check access and connection configuration.`
+      )
+    return response
+  }
+  const json = async <T>(path: string, signal: AbortSignal): Promise<T> =>
+    (await request(path, signal)).json()
+  return {
+    session: (id, signal) => json<AgentObject>(encodeURIComponent(id), signal),
+    items: (id, limit, after, signal) => {
+      const query = new URLSearchParams({ order: 'desc', limit: String(limit) })
+      if (after) query.set('after', after)
+      return json<AgentPage<AgentItem>>(
+        `${encodeURIComponent(id)}/items?${query}`,
+        signal
+      )
+    },
+    turns: (id, signal) =>
+      json<AgentPage<AgentObject>>(
+        `${encodeURIComponent(id)}/turns?order=desc&limit=100`,
+        signal
+      ),
+    stream: async (id, signal) => {
+      const controller = new AbortController()
+      const abort = () => controller.abort()
+      signal.addEventListener('abort', abort, { once: true })
+      if (signal.aborted) abort()
+      try {
+        const response = await request(
+          `${encodeURIComponent(id)}/events?stream=true`,
+          controller.signal,
+          true
+        )
+        if (
+          !response.body ||
+          !response.headers.get('content-type')?.includes('text/event-stream')
+        ) {
+          throw new Error('Agents endpoint did not return an event stream.')
+        }
+        return {
+          events: readAgentEvents(response.body),
+          close: () => {
+            signal.removeEventListener('abort', abort)
+            controller.abort()
+          },
+        }
+      } catch (error) {
+        signal.removeEventListener('abort', abort)
+        controller.abort()
+        throw error
+      }
+    },
+  }
+}
diff --git a/app/src/lib/agents/types.ts b/app/src/lib/agents/types.ts
new file mode 100644
index 00000000..f958c38c
--- /dev/null
+++ b/app/src/lib/agents/types.ts
@@ -0,0 +1,67 @@
+/** Wire objects retain unknown fields so new API item types remain inspectable. */
+export type AgentObject = Record<string, unknown>
+export type AgentItem = AgentObject & {
+  id: string | null
+  type: string
+  status?: string
+  turn_id?: string
+  role?: string
+  phase?: string | null
+  content?: AgentObject[]
+}
+export type AgentPage<T> = {
+  data: T[]
+  has_more: boolean
+  last_id: string | null
+}
+export type AgentEvent = AgentObject & { type: string; event_id?: string }
+export type AgentStream = {
+  events: AsyncIterable<AgentEvent>
+  close(): void
+}
+export interface AgentTransport {
+  session(id: string, signal: AbortSignal): Promise<AgentObject>
+  items(
+    id: string,
+    limit: number,
+    after: string | undefined,
+    signal: AbortSignal
+  ): Promise<AgentPage<AgentItem>>
+  turns(id: string, signal: AbortSignal): Promise<AgentPage<AgentObject>>
+  stream(id: string, signal: AbortSignal): Promise<AgentStream>
+}
+export const AGENT_MONITOR_MIME = 'application/vnd.runme.agent-monitor+json'
+export type AgentMonitorDescriptor = {
+  version: 1
+  id: string
+  sessionId: string
+  pageSize: number
+}
+
+/** Validate saved output before using it as a native widget descriptor. */
+export function parseMonitorDescriptor(
+  text: string
+): AgentMonitorDescriptor | null {
+  try {
+    const value = JSON.parse(text)
+    if (
+      value?.version !== 1 ||
+      typeof value.id !== 'string' ||
+      !value.id ||
+      typeof value.sessionId !== 'string' ||
+      !value.sessionId.trim() ||
+      !Number.isInteger(value.pageSize) ||
+      value.pageSize < 1 ||
+      value.pageSize > 100
+    )
+      return null
+    return {
+      version: 1,
+      id: value.id,
+      sessionId: value.sessionId,
+      pageSize: value.pageSize,
+    }
+  } catch {
+    return null
+  }
+}
diff --git a/app/src/lib/notebookData.test.ts b/app/src/lib/notebookData.test.ts
index 2fc48f69..82f5bdce 100644
--- a/app/src/lib/notebookData.test.ts
+++ b/app/src/lib/notebookData.test.ts
@@ -110,6 +110,9 @@ vi.mock("./runtime/sandboxJsKernel", () => ({
     async run(source: string): Promise<void> {
       let exitCode = 0;
       try {
+        if (source.includes("agents.monitor")) {
+          await this.bridge.call("agents.monitor", ["sess_test", { pageSize: 25 }]);
+        }
         if (source.includes("runme.getCurrentNotebook")) {
           const notebook = (await this.bridge.call(
             "runme.getCurrentNotebook",
@@ -292,6 +295,44 @@ async function waitForCondition(
 }
 
 describe("bindStreamsToCell", () => {
+  it.each([APPKERNEL_RUNNER_NAME, APPKERNEL_SANDBOX_RUNNER_NAME])(
+    'renders a typed agent widget from %s without keeping cell execution running',
+    async (runnerName) => {
+      const cell = create(parser_pb.CellSchema, {
+        refId: 'agent-widget-cell',
+        kind: parser_pb.CellKind.CODE,
+        languageId: 'javascript',
+        metadata: { [RunmeMetadataKey.RunnerName]: runnerName },
+        value:
+          'await agents.monitor("sess_test", { pageSize: 25 }); console.log("mounted");',
+      })
+      const model = new NotebookData({
+        notebook: create(parser_pb.NotebookSchema, { cells: [cell] }),
+        uri: 'nb://agents',
+        name: 'agents.runme',
+        notebookStore: null,
+        loaded: true,
+      })
+      model.runCodeCell(cell)
+      await waitForCondition(
+        () =>
+          model.getCellSnapshot(cell.refId)?.metadata?.[
+            RunmeMetadataKey.ExitCode
+          ] === '0'
+      )
+      const output = model
+        .getCellSnapshot(cell.refId)
+        ?.outputs.flatMap((o) => o.items)
+        .find((i) => i.mime === 'application/vnd.runme.agent-monitor+json')
+      expect(output).toBeTruthy()
+      expect(JSON.parse(new TextDecoder().decode(output!.data))).toMatchObject({
+        version: 1,
+        sessionId: 'sess_test',
+        pageSize: 25,
+      })
+    }
+  )
+
   it("appends stdout/stderr to existing outputs", () => {
     const refId = "cell-1";
     const cell = create(parser_pb.CellSchema, {
diff --git a/app/src/lib/notebookData.ts b/app/src/lib/notebookData.ts
index be34f597..1b5569d2 100644
--- a/app/src/lib/notebookData.ts
+++ b/app/src/lib/notebookData.ts
@@ -14,6 +14,7 @@ import {
   RunmeMetadataKey,
   parser_pb,
 } from '../contexts/CellContext'
+import { callAgentsBridge } from './agents/bridge'
 import { isHtmlLanguageId } from './cellContent'
 import { DERIVED_NOTEBOOK_KEY, parseDerivedSource } from './derivedNotebook'
 import { googleAnalytics } from './googleAnalytics'
@@ -1266,12 +1267,26 @@ export class NotebookData {
       listNotebooks: this.listNotebooksForAppKernel,
     })
     const abortController = new AbortController()
+    const richOutputs: parser_pb.CellOutput[] = []
     const appGlobals = createAppJsGlobals({
       runme: runmeApi,
       resolveNotebook: this.resolveNotebookForAppKernel,
       listNotebooks: this.listNotebooksForAppKernel,
       requestNotebookWriteAccess: this.requestNotebookWriteAccess,
       signal: abortController.signal,
+      displayOutput: (mime, value) => {
+        if (abortController.signal.aborted) return
+        richOutputs.push(
+          create(parser_pb.CellOutputSchema, {
+            items: [
+              create(parser_pb.CellOutputItemSchema, {
+                mime,
+                data: encodeCellOutputBytes(value),
+              }),
+            ],
+          })
+        )
+      },
     })
     const notebooksApiBridgeServer = createNotebooksApiBridgeServer({
       notebooksApi: appGlobals.notebooks as typeof hostNotebooksApi,
@@ -1392,7 +1407,10 @@ export class NotebookData {
         // AppKernel runs are not terminal-stream based. Drop stale terminal MIME
         // outputs from prior remote runs so stdout/stderr are visible in the
         // notebook output renderer.
-        updated.outputs = createStdTextOutputs(stdout, stderr)
+        updated.outputs = [
+          ...richOutputs,
+          ...createStdTextOutputs(stdout, stderr),
+        ]
         this.updateCell(updated)
         appLogger.info('Finished AppKernel cell execution', {
           attrs: {
@@ -1417,6 +1435,8 @@ export class NotebookData {
     appGlobals: ReturnType<typeof createAppJsGlobals>
   ): Promise<unknown> {
     const target = args[0]
+    if (method.startsWith('agents.'))
+      return callAgentsBridge(appGlobals.agents, method, args)
     switch (method) {
       case 'runme.clear':
         return runmeApi.clear(target)
diff --git a/app/src/lib/runtime/appJsGlobals.ts b/app/src/lib/runtime/appJsGlobals.ts
index f2f92c04..b07fc290 100644
--- a/app/src/lib/runtime/appJsGlobals.ts
+++ b/app/src/lib/runtime/appJsGlobals.ts
@@ -17,6 +17,7 @@ import { LOCAL_FOLDER_URI } from '../../storage/local'
 import { NotebookStoreItemType } from '../../storage/notebook'
 import { getAuthData } from '../../token'
 import { agentEndpointManager } from '../agentEndpointManager'
+import { createAgentsApi } from '../agents/runtime'
 import { aisreClientManager } from '../aisreClientManager'
 import {
   disableAppConfigOverridesOnLoad,
@@ -368,6 +369,7 @@ function deriveTitleFromUri(uri: string): string {
 export function createAppJsGlobals({
   runme,
   sendOutput,
+  displayOutput,
   resolveNotebookStore,
   ensureFilesystemStore = defaultEnsureFilesystemStore,
   workspace,
@@ -385,6 +387,7 @@ export function createAppJsGlobals({
 }: {
   runme: RunmeConsoleApi
   sendOutput?: SendOutput
+  displayOutput?: (mime: string, value: string) => void
   resolveNotebookStore?: () => RuntimeNotebookStore | null
   ensureFilesystemStore?: () => FilesystemNotebookStore | null
   workspace?: WorkspaceApi
@@ -1813,9 +1816,11 @@ export function createAppJsGlobals({
         }
       },
     },
+    agents: createAgentsApi(displayOutput),
     help: () => {
       const message = [
         'Available namespaces:',
+        '  agents          - Render and control Agents API session monitors',
         '  runme           - Notebook helpers (run all, clear outputs)',
         '  tour            - Highlight UI targets with AI-authored annotations',
         '  notebooks       - Notebook document API plus create/append helpers',
diff --git a/app/src/lib/runtime/codeModeExecutor.ts b/app/src/lib/runtime/codeModeExecutor.ts
index e8e71ff5..be8ddcfe 100644
--- a/app/src/lib/runtime/codeModeExecutor.ts
+++ b/app/src/lib/runtime/codeModeExecutor.ts
@@ -1,3 +1,4 @@
+import { callAgentsBridge } from '../agents/bridge'
 import {
   createDriveFile,
   listDriveFolderItems,
@@ -338,6 +339,8 @@ async function handleSandboxAppKernelBridgeCall({
   notebookDiffApi: ReturnType<typeof createNotebookDiffRuntimeApi>
 }): Promise<unknown> {
   const target = args[0]
+  if (method.startsWith('agents.'))
+    return callAgentsBridge(globals.agents, method, args)
   switch (method) {
     case 'runme.clear':
       return runmeApi.clear(target)
diff --git a/app/src/lib/runtime/sandboxJsKernel.test.ts b/app/src/lib/runtime/sandboxJsKernel.test.ts
index 8c4ef94d..85fbf66f 100644
--- a/app/src/lib/runtime/sandboxJsKernel.test.ts
+++ b/app/src/lib/runtime/sandboxJsKernel.test.ts
@@ -577,7 +577,9 @@ describe('SandboxJSKernel', () => {
   it('exposes app.getVersion in sandbox helpers, discovery, and the allowlist', () => {
     const srcDoc = buildSandboxSrcDoc({ enableOpfs: false, enableNet: false })
     expect(srcDoc).toContain('getVersion: () => hostCall("app.getVersion", [])')
-    expect(srcDoc).toContain('await app.getVersion() (loaded app build metadata)')
+    expect(srcDoc).toContain(
+      'await app.getVersion() (loaded app build metadata)'
+    )
     expect(CODE_MODE_SANDBOX_ALLOWED_METHODS).toContain('app.getVersion')
   })
 
@@ -589,7 +591,7 @@ describe('SandboxJSKernel', () => {
 
     expect(srcDoc).toMatch(/"tour",\s+"ui",\s+"opfs",\s+"net",\s+"embed"/)
     expect(srcDoc).toContain(
-      'runner(consoleProxy, runme, tour, ui, opfs, net, embed, notebooks'
+      'runner(consoleProxy, agents, runme, tour, ui, opfs, net, embed, notebooks'
     )
     expect(srcDoc).toContain('const runmeRunners = {')
     expect(srcDoc).toContain(
diff --git a/app/src/lib/runtime/sandboxJsKernel.ts b/app/src/lib/runtime/sandboxJsKernel.ts
index 8239b9ee..109afd98 100644
--- a/app/src/lib/runtime/sandboxJsKernel.ts
+++ b/app/src/lib/runtime/sandboxJsKernel.ts
@@ -64,6 +64,14 @@ function serializeHostError(error: unknown): string | SerializedHostError {
 }
 
 const DEFAULT_SANDBOX_ALLOWED_METHODS = [
+  'agents.monitor',
+  'agents.get',
+  'agents.pause',
+  'agents.resume',
+  'agents.older',
+  'agents.newer',
+  'agents.latest',
+  'agents.help',
   'runme.clear',
   'runme.clearOutputs',
   'runme.runAll',
@@ -485,6 +493,16 @@ export function buildSandboxSrcDoc(options: {
           grade: (args) => hostCall("suggestionGrader.grade", [args]),
           help: () => hostCall("suggestionGrader.help", []),
         };
+        const agents = {
+          monitor: (id, options) => hostCall("agents.monitor", [id, options]),
+          get: (id) => hostCall("agents.get", [id]),
+          pause: (id) => hostCall("agents.pause", [id]),
+          resume: (id) => hostCall("agents.resume", [id]),
+          older: (id) => hostCall("agents.older", [id]),
+          newer: (id) => hostCall("agents.newer", [id]),
+          latest: (id) => hostCall("agents.latest", [id]),
+          help: () => hostCall("agents.help", []),
+        };
         const notebookDiff = {
           listDriveRevisions: (target) => hostCall("notebookDiff.listDriveRevisions", [target]),
           diffDriveRevision: (args) => hostCall("notebookDiff.diffDriveRevision", [args]),
@@ -628,6 +646,7 @@ export function buildSandboxSrcDoc(options: {
           consoleProxy.log("- await credentials.google.setServiceAccountFromFilePath(path)");
           consoleProxy.log("- await drive.authorize({ mode?, prompt? })");
           consoleProxy.log("- await drive.saveAsCurrentNotebook(folderIdOrUri, fileName)");
+          consoleProxy.log("- agents.monitor(sessionId, { pageSize: 50 }); agents.help()");
           consoleProxy.log("- help()");
         };
 
@@ -636,6 +655,7 @@ export function buildSandboxSrcDoc(options: {
           try {
             const runner = new Function(
               "console",
+              "agents",
               "runme",
               "tour",
               "ui",
@@ -660,7 +680,7 @@ export function buildSandboxSrcDoc(options: {
               "help",
               '"use strict"; return (async () => {\\n' + code + '\\n})();',
             );
-            await runner(consoleProxy, runme, tour, ui, opfs, net, embed, notebooks, documents, documentation, comments, comparisons, revisions, suggestions, notebookDiff, trainingExamples, suggestionGrader, app, runmeRunners, explorer, credentials, drive, help);
+            await runner(consoleProxy, agents, runme, tour, ui, opfs, net, embed, notebooks, documents, documentation, comments, comparisons, revisions, suggestions, notebookDiff, trainingExamples, suggestionGrader, app, runmeRunners, explorer, credentials, drive, help);
           } catch (error) {
             exitCode = 1;
             post({ type: "stderr", data: String(error) + "\\n" });
diff --git a/docs-dev/CUJs/agent-monitor.md b/docs-dev/CUJs/agent-monitor.md
new file mode 100644
index 00000000..b6e8c805
--- /dev/null
+++ b/docs-dev/CUJs/agent-monitor.md
@@ -0,0 +1,16 @@
+# CUJ: Agent monitor in a JavaScript cell
+
+## Setup
+
+Start the Go fixture with `go run testing/fake-agents-server.go` and Runme at `http://127.0.0.1:5173`. Use a separate local browser session. Create a notebook through WebMCP, record its concrete URI, and select AppKernel browser JS. No credentials or live API session are used.
+
+## Journey and acceptance
+
+1. Execute `agents.configure({baseUrl:'http://127.0.0.1:8989/v1'}); agents.monitor('sess_demo',{pageSize:5})` in a targeted notebook cell. Read the cell back: exit code is 0 and output includes `application/vnd.runme.agent-monitor+json`.
+2. Verify Render is selected, the editor is hidden, the widget has five items, GFM tables and fenced code render, and connection is live while the root turn remains in progress.
+3. Select Older using the same runtime controller (`await agents.older(widgetId)`). Assert five earlier items remain visible as events arrive, and the Latest update count increases. Newer/Latest return to the bounded live page.
+4. Toggle Edit then Render. Assert source is visible only in Edit and the existing monitor remains mounted; neither operation executes the cell.
+5. Pause via `agents.pause(widgetId)`. Assert connection is paused and items remain readable. Resume via `await agents.resume(widgetId)` and assert live state returns.
+6. Reload the browser. The saved widget is disconnected, requires Connect, and does not contain credentials or serialized messages. Configure the connection in a new execution before connecting.
+
+Capture the rendered monitor with notebook context and record assertions. Controller/component tests cover root/subagent completion, replay races, EOF, safe Markdown, malformed descriptors and pagination. NotebookData tests cover browser and sandbox output. The Go fixture drives the manual WebMCP browser CUJ; it is not registered in the automated browser orchestrator yet.
diff --git a/docs-dev/cujs/README.md b/docs-dev/cujs/README.md
index 7b93ef69..af8ecb2c 100644
--- a/docs-dev/cujs/README.md
+++ b/docs-dev/cujs/README.md
@@ -8,6 +8,8 @@ from `docs-dev/cujs/`.
 
 ## Current CUJs
 
+- [agent-monitor.md](agent-monitor.md) — JavaScript widget rendering, live history, Edit/Render, and observation lifecycle using the Go Agents API fixture.
+
 - `authentication-settings-persistence.md` — saved OAuth scopes survive refresh under production config precedence.
 
 - [horizontal-rendering.md](horizontal-rendering.md) — viewport-bounded prose with locally scrolling wide
diff --git a/docs-dev/design/20261003_agents_api_ui.md b/docs-dev/design/20261003_agents_api_ui.md
new file mode 100644
index 00000000..8292afa2
--- /dev/null
+++ b/docs-dev/design/20261003_agents_api_ui.md
@@ -0,0 +1,110 @@
+# Agents API monitors in notebooks
+
+Date: 2026-10-03
+
+## Decision
+
+An AppKernel JavaScript cell can render an interactive agent monitor:
+
+```js
+agents.monitor(session_id, { pageSize: 50 })
+```
+
+The cell has Edit and Render modes. Edit shows the source; Render shows the monitor. Running the cell creates the widget and returns immediately. The cell execution finishing does not mean the agent turn finished. Editing does not execute code or cancel the agent. Rerunning replaces the old monitor.
+
+Keep agent creation, sending messages, and cancellation in explicit code cells. The first version is a read-only monitor; it never submits a message, approves a request, or cancels a turn as a side effect of reconnecting. A composer and approval forms can follow once their semantics are designed.
+
+## Current state
+
+The supplied Python cell retrieves the session and iterates all session items in ascending order. It prints assistant text and refusals. It drops user messages and tool calls, prints Markdown literally, and requires rerunning to refresh. Its API key is read on a local runner, which is a different execution environment from browser JavaScript.
+
+AppKernel currently saves stdout/stderr as cell output. Add a typed output MIME for the monitor, rendered by React; do not execute generated HTML or persist callbacks.
+
+## Events versus items
+
+Items are durable messages and tool calls. Events describe changes, including text deltas, item creation, session state, and turn completion. The timeline is an item view. A bounded Activity disclosure shows recent events for diagnosis; it is not a second conversation timeline.
+
+Use item IDs to reconcile persisted and streamed content. Append output-text deltas to their content part; replace the part on output_text.done. Done can arrive without any deltas. Final saved items take precedence over buffered deltas during recovery. Event IDs deduplicate delivery. Preserve unknown item types as expandable JSON.
+
+Session status, root-turn status, and connection status are separate. Idle is not success. A closed stream is not success. Subagent turn completion does not complete the root turn. A completed turn does not guarantee that every tool succeeded. Required actions are displayed from the retrieved session without acting on them.
+
+## Cell UX
+
+1. Write a JS cell and select AppKernel.
+2. Configure an authenticated transport once per browser lifetime, then execute agents.monitor(session_id).
+3. The editor collapses into Render mode. A toolbar retains Edit, Render, Run, and normal cell actions.
+4. Edit reveals source while keeping the monitor mounted but hidden. Returning to Render does not rerun code. After source changes, label the existing output as coming from an earlier execution until Run is pressed.
+5. Clearing output, rerunning, deleting the cell, or closing the notebook releases the widget's stream. Pause monitoring stops observation only. Resume reconnects and reloads saved history.
+6. Saved outputs contain only a versioned descriptor (widget ID, session ID, page size). Reopening a notebook shows a disconnected monitor and requires Connect; it does not run notebook code or reuse saved credentials.
+
+## Monitor layout
+
+```text
+Agent session  sess_…                         [Pause monitoring]
+Session: in progress · Root turn: in progress · Connection: live
+[Older] [Newer] [Latest]                       Latest 50 items
+----------------------------------------------------------------
+You                         completed
+  Check the deployment.
+Assistant · commentary      completed
+  I’ll inspect the rollout.
+▸ shell_call                completed
+Assistant · final answer    completed
+  Markdown text, lists, fenced code, tables, and links
+----------------------------------------------------------------
+▸ Required actions
+▸ Activity (most recent 100 events)
+```
+
+Use chronological order within each page. Messages show role, phase, and status. Render text with react-markdown and GFM, with raw HTML disabled. Tools and unfamiliar content parts retain expandable structured details. Remote images display an attachment placeholder rather than automatic network loads. No Markdown command executes. Buttons have accessible labels; only compact status changes use a live region.
+
+## Pagination and live updates
+
+Default page size is 50, configurable from 1 to 100. Fetch items with order=desc and reverse that page for display. Older requests use the server's last_id as after, retaining the same descending order. Never derive a cursor from a filtered message list. Preserve null-ID legacy messages with page-local keys and stop with an explicit diagnostic if has_more is true without a usable cursor.
+
+Keep one visible history page and one bounded live window. Older replaces the visible page instead of growing the DOM. Newer uses the recorded cursor stack; Latest returns to the live window. While reading history, events update the live window and a new-activity indicator without moving the user's page or scroll. A fixed-height scroll area keeps the notebook stable. Auto-follow applies only at the live bottom; scrolling up disables following until the user returns to the bottom or selects Latest.
+
+## State and recovery
+
+A domain controller owns immutable snapshots and subscribe/getSnapshot methods. React observes it with useSyncExternalStore. UI buttons and agents runtime commands call the same controller.
+
+On connect or reconnect: open the SSE stream and buffer events, retrieve session/items/latest root turn, install the snapshot, then apply buffered events. Ignore buffered deltas for already-final items. Bound the hydration buffer; overflow must report a recoverable error rather than silently drop data. A failed session stops reconnection. Unexpected EOF or network failure shows Disconnected with an explicit Reconnect control, preserving the last visible data. Reconnect fetches authoritative saved state; it never resends work. Request generations and AbortController prevent late responses from reviving a disposed monitor.
+
+The latest root-turn endpoint is consulted independently of item history. Missing turn history is shown as unknown, never inferred from a final-answer message. Root-turn events update the status without letting a child turn replace it.
+
+## Runtime and transport
+
+```ts
+agents.configure({
+  baseUrl: 'https://api.openai.com/v1',
+  getHeaders: async () => ({ Authorization: `Bearer ${await obtainToken()}` }),
+})
+const widget = agents.monitor(session_id, { pageSize: 50 })
+agents.get(widget.id)        // JSON snapshot
+agents.pause(widget.id)
+await agents.resume(widget.id)
+await agents.older(widget.id)
+await agents.newer(widget.id)
+agents.latest(widget.id)
+```
+
+obtainToken is an application-owned credential provider, not a built-in helper. Configuration stays in memory and is never returned from help, serialized into output, or written to localStorage. A deployment may supply a same-origin authenticated proxy base URL instead. This change implements the REST/SSE browser transport, not a new credential broker or server proxy. The existing Runme agent endpoint is unrelated and must not be reused implicitly. The Python runner's local key path cannot be accessed by the browser.
+
+The transport uses GET session, GET items, GET turns, and GET events?stream=true with OpenAI-Beta: agents=v1. Reject redirects and avoid including upstream error bodies or authorization headers in notebook diagnostics. Refresh headers for each request. Sandbox cells may monitor and control already-configured monitors through host methods; they cannot install credential-provider callbacks. WebMCP can use the same read/control methods and create a monitor in a targeted notebook by inserting/executing a JS cell.
+
+## Implementation and validation
+
+Add the transport and controller under app/src/lib/agents; expose agents through AppKernel globals and the sandbox bridge. Emit application/vnd.runme.agent-monitor+json into normal cell outputs. Extend ActionOutputItems with a native monitor renderer and add Edit/Render controls to cells containing that MIME. Keep normal code cells unchanged.
+
+Test SSE framing across chunk boundaries, HTTP errors, abort cleanup, root/subagent outcomes, done without deltas, replay deduplication, reconnect hydration, pagination during live output, source/render behavior, malformed descriptors, and safe Markdown. Run focused tests, type checking, lint, and a production build. Validate the complete notebook path with a synthetic local Go REST/SSE service; live API validation requires the user's chosen authenticated transport.
+
+## Follow-ups
+
+A deployable proxy or runner-backed adapter can bridge the existing local credential workflow. Other follow-ups are explicit send/cancel helpers, request-specific approval forms, subagent drill-down, durable snapshots for offline viewing, and a shared subscription per session. The first version makes each monitor independent so one cell's controls do not affect another.
+
+## References
+
+- [Events and items](https://developers.openai.com/api/docs/guides/agents-api/sessions/events)
+- [List items](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/subresources/items/methods/list)
+- [Streaming events](https://developers.openai.com/api/reference/resources/beta/subresources/agents/streaming-events)
+- [Original Python cell](https://runme.gateway.unified-0.internal.api.openai.org/?doc=https%3A%2F%2Fdrive.google.com%2Ffile%2Fd%2F1wI3tWRteb5QPfwYyrLNennNv8K09hTq8%2Fview#cell=30d5dbb16a214c9f9db8f9c9f757e32b)
diff --git a/docs/20-agent-monitors.md b/docs/20-agent-monitors.md
new file mode 100644
index 00000000..60eadc7f
--- /dev/null
+++ b/docs/20-agent-monitors.md
@@ -0,0 +1,36 @@
+---
+name: agent-monitors
+title: Agent session monitors
+description: Render Agents API sessions in JavaScript cells with live Markdown, tool details, turn status, and history pagination.
+order: 20
+---
+
+# Agent session monitors
+
+Use an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.
+
+Configure a trusted browser-accessible API root once with `agents.configure({ baseUrl, getHeaders })`. The optional async `getHeaders` provider supplies authorization headers without persisting credentials in the notebook. Do not put API keys in cell source. A same-origin authenticated proxy can omit the provider. The Python runner's local key files are not accessible to browser JavaScript. This release does not include a proxy or credential broker.
+
+After configuring the connection, set a session ID and run the following cell using **JS → browser**. Sandbox cells can monitor a connection already configured by browser JS.
+
+```js
+const widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })
+```
+
+## Read and monitor
+
+**Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.
+
+**Older** and **Newer** page through saved items, with at most the configured page size visible. **Latest** returns to the live window. New output never replaces an older page while you read it. Scroll to the live bottom to follow incoming output automatically.
+
+**Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.
+
+Saved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit responses, new messages, or cancellation through your agent client.
+
+Runtime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.
+
+## Synthetic local demo
+
+Start `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.
+
+An executable version is available in `docs/agent-monitors.json`.
diff --git a/docs/agent-monitors.json b/docs/agent-monitors.json
new file mode 100644
index 00000000..40f6b9e2
--- /dev/null
+++ b/docs/agent-monitors.json
@@ -0,0 +1,28 @@
+{
+  "cells": [
+    {
+      "kind": 1,
+      "languageId": "markdown",
+      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nConfigure a trusted browser-accessible API root once with `agents.configure({ baseUrl, getHeaders })`. The optional async `getHeaders` provider supplies authorization headers without persisting credentials in the notebook. Do not put API keys in cell source. A same-origin authenticated proxy can omit the provider. The Python runner's local key files are not accessible to browser JavaScript. This release does not include a proxy or credential broker.\n\nAfter configuring the connection, set a session ID and run the following cell using **JS \u2192 browser**. Sandbox cells can monitor a connection already configured by browser JS.\n",
+      "refId": "0a152c34fb9e412d95c68cec16074052",
+      "metadata": {}
+    },
+    {
+      "kind": 2,
+      "languageId": "javascript",
+      "value": "// Replace with an existing session ID after configuring the connection.\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })",
+      "metadata": {
+        "runme.dev/runnerName": "appkernel-js"
+      },
+      "refId": "8c52f7001a8844d29397e9006943042f"
+    },
+    {
+      "kind": 1,
+      "languageId": "markdown",
+      "value": "## Read and monitor\n\n**Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.\n\n**Older** and **Newer** page through saved items, with at most the configured page size visible. **Latest** returns to the live window. New output never replaces an older page while you read it. Scroll to the live bottom to follow incoming output automatically.\n\n**Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.\n\nSaved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit responses, new messages, or cancellation through your agent client.\n\nRuntime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.\n\n## Synthetic local demo\n\nStart `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.\n",
+      "refId": "002946c0829a4f3ab899510f2563b819",
+      "metadata": {}
+    }
+  ],
+  "metadata": {}
+}
diff --git a/testing/fake-agents-server.go b/testing/fake-agents-server.go
new file mode 100644
index 00000000..b7251ed6
--- /dev/null
+++ b/testing/fake-agents-server.go
@@ -0,0 +1,89 @@
+// Local read-only Agents API fixture for the agent-monitor CUJ.
+// Run: go run testing/fake-agents-server.go
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// main serves synthetic history and an SSE stream on loopback only.
+func main() {
+	http.HandleFunc("/v1/agents/sessions/sess_demo", serveAgentDemo)
+	http.HandleFunc("/v1/agents/sessions/sess_demo/", serveAgentDemo)
+	log.Fatal(http.ListenAndServe("127.0.0.1:8989", nil))
+}
+
+func serveAgentDemo(w http.ResponseWriter, r *http.Request) {
+	origin := r.Header.Get("Origin")
+	if origin == "http://127.0.0.1:5173" || origin == "http://localhost:5173" {
+		w.Header().Set("Access-Control-Allow-Origin", origin)
+		w.Header().Set("Access-Control-Allow-Headers", "OpenAI-Beta")
+	}
+	if r.Method == "OPTIONS" {
+		w.WriteHeader(http.StatusNoContent)
+		return
+	}
+	if r.Method != "GET" {
+		http.Error(w, "Read only", http.StatusMethodNotAllowed)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	switch {
+	case strings.HasSuffix(r.URL.Path, "/events"):
+		w.Header().Set("Content-Type", "text/event-stream")
+		fmt.Fprint(w, ": connected\n\n")
+		w.(http.Flusher).Flush()
+		ticker := time.NewTicker(2 * time.Second)
+		defer ticker.Stop()
+		index := 0
+		for {
+			select {
+			case <-r.Context().Done():
+				return
+			case <-ticker.C:
+				index++
+				payload, _ := json.Marshal(map[string]any{"type": "agent.session.turn.output_text.done", "event_id": fmt.Sprintf("event_%d", index), "session_id": "sess_demo", "turn_id": "turn_live", "item_id": "msg_live", "output_index": 0, "content_index": 0, "text": fmt.Sprintf("**Live update %d.** The monitor is receiving events.\n\n```sh\ngo test ./...\n```", index)})
+				fmt.Fprintf(w, "data: %s\n\n", payload)
+				w.(http.Flusher).Flush()
+			}
+		}
+	case strings.HasSuffix(r.URL.Path, "/items"):
+		limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
+		if limit < 1 || limit > 100 {
+			limit = 50
+		}
+		start := 125
+		if after := r.URL.Query().Get("after"); after != "" {
+			if after == "msg_live" {
+				start = 125
+			} else {
+				value, _ := strconv.Atoi(strings.TrimPrefix(after, "msg_"))
+				start = value - 1
+			}
+		}
+		data := []map[string]any{}
+		for i := start; i > 0 && len(data) < limit; i-- {
+			text := fmt.Sprintf("Saved message **%d**.\n\n| Check | Result |\n|---|---|\n| API request | Passed |", i)
+			row := map[string]any{"id": fmt.Sprintf("msg_%d", i), "type": "message", "role": "assistant", "phase": "final_answer", "status": "completed", "content": []map[string]any{{"type": "output_text", "text": text}}}
+			if i%5 == 0 {
+				row = map[string]any{"id": fmt.Sprintf("msg_%d", i), "type": "shell_call", "status": "completed", "command": "go test ./...", "output": "PASS"}
+			}
+			data = append(data, row)
+		}
+		var last any = nil
+		if len(data) > 0 {
+			last = data[len(data)-1]["id"]
+		}
+		json.NewEncoder(w).Encode(map[string]any{"data": data, "has_more": start-len(data) > 0, "last_id": last})
+	case strings.HasSuffix(r.URL.Path, "/turns"):
+		json.NewEncoder(w).Encode(map[string]any{"data": []map[string]any{{"id": "turn_live", "subagent_id": nil, "status": "in_progress", "created_at": 1}}, "has_more": false, "last_id": "turn_live"})
+	default:
+		json.NewEncoder(w).Encode(map[string]any{"id": "sess_demo", "status": "in_progress", "required_actions": []any{}})
+	}
+}

From fe988ea3b0ab05e3f8eebeff2c2c2ffeb662452f Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 13:37:41 -0700
Subject: [PATCH 04/11] Add encrypted named key vault for agent monitors

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 .../components/Agents/AgentMonitor.test.tsx   |   2 +-
 .../KeyVault/KeyVaultPanel.test.tsx           |  53 +++
 app/src/components/KeyVault/KeyVaultPanel.tsx | 324 ++++++++++++++++++
 .../components/SidePanel/SidePanel.test.tsx   |   6 +
 app/src/components/SidePanel/SidePanel.tsx    |  10 +
 app/src/lib/agents/runtime.test.ts            |  43 +++
 app/src/lib/agents/runtime.ts                 |  32 +-
 app/src/lib/keyvault/store.test.ts            | 110 ++++++
 app/src/lib/keyvault/store.ts                 | 311 +++++++++++++++++
 app/src/lib/runtime/appJsGlobals.ts           |   3 +
 app/src/lib/tourGuide.ts                      |   5 +
 app/src/lib/tourUiController.ts               |   4 +-
 docs-dev/CUJs/agent-monitor.md                |  10 +
 docs-dev/design/20261003_agents_api_ui.md     |  15 +-
 docs/20-agent-monitors.md                     |  11 +-
 docs/agent-monitors.json                      |   4 +-
 16 files changed, 929 insertions(+), 14 deletions(-)
 create mode 100644 app/src/components/KeyVault/KeyVaultPanel.test.tsx
 create mode 100644 app/src/components/KeyVault/KeyVaultPanel.tsx
 create mode 100644 app/src/lib/keyvault/store.test.ts
 create mode 100644 app/src/lib/keyvault/store.ts

diff --git a/app/src/components/Agents/AgentMonitor.test.tsx b/app/src/components/Agents/AgentMonitor.test.tsx
index b3575743..00213c12 100644
--- a/app/src/components/Agents/AgentMonitor.test.tsx
+++ b/app/src/components/Agents/AgentMonitor.test.tsx
@@ -79,7 +79,7 @@ describe('agent monitor rendering', () => {
     expect(fetch).not.toHaveBeenCalled()
     fireEvent.click(screen.getByRole('button', { name: 'Connect' }))
     expect((await screen.findByRole('alert')).textContent).toContain(
-      'agents.configure'
+      'agents.setKey'
     )
     expect(fetch).not.toHaveBeenCalled()
   })
diff --git a/app/src/components/KeyVault/KeyVaultPanel.test.tsx b/app/src/components/KeyVault/KeyVaultPanel.test.tsx
new file mode 100644
index 00000000..ee0abebc
--- /dev/null
+++ b/app/src/components/KeyVault/KeyVaultPanel.test.tsx
@@ -0,0 +1,53 @@
+import { webcrypto } from 'node:crypto'
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+import KeyVaultPanel from './KeyVaultPanel'
+import { KeyVault, VAULT_STORAGE_KEY } from '../../lib/keyvault/store'
+
+beforeEach(() => {
+  localStorage.clear()
+  vi.stubGlobal('crypto', webcrypto)
+})
+afterEach(() => {
+  cleanup()
+  vi.unstubAllGlobals()
+})
+
+it('creates a vault, masks and clears key inputs, and removes keys with confirmation', async () => {
+  const vault = new KeyVault()
+  render(<KeyVaultPanel vault={vault} />)
+  fireEvent.change(screen.getByLabelText('Vault passphrase'), {
+    target: { value: 'long test passphrase' },
+  })
+  fireEvent.change(screen.getByLabelText('Confirm passphrase'), {
+    target: { value: 'long test passphrase' },
+  })
+  fireEvent.click(screen.getByRole('button', { name: 'Create vault' }))
+  await screen.findByRole('button', { name: 'Lock vault' })
+  fireEvent.change(screen.getByLabelText('Key name'), {
+    target: { value: 'openai-api' },
+  })
+  const input = screen.getByLabelText('Key value') as HTMLInputElement
+  expect(input.type).toBe('password')
+  fireEvent.change(input, { target: { value: 'test-secret' } })
+  fireEvent.click(screen.getByRole('button', { name: 'Save key' }))
+  await screen.findByText('Key saved.')
+  expect(input.value).toBe('')
+  expect(localStorage.getItem(VAULT_STORAGE_KEY)).not.toContain('test-secret')
+  fireEvent.click(screen.getByRole('button', { name: 'Delete openai-api' }))
+  expect(vault.getSnapshot().names).toContain('openai-api')
+  fireEvent.click(screen.getByRole('button', { name: 'Confirm removal' }))
+  await screen.findByText('Key removed.')
+  expect(vault.getSnapshot().names).toEqual([])
+  fireEvent.click(screen.getByRole('button', { name: 'Lock vault' }))
+  await waitFor(() =>
+    expect(screen.getByRole('button', { name: 'Unlock vault' })).toBeTruthy()
+  )
+})
diff --git a/app/src/components/KeyVault/KeyVaultPanel.tsx b/app/src/components/KeyVault/KeyVaultPanel.tsx
new file mode 100644
index 00000000..8f602cee
--- /dev/null
+++ b/app/src/components/KeyVault/KeyVaultPanel.tsx
@@ -0,0 +1,324 @@
+import { useEffect, useState, useSyncExternalStore } from 'react'
+
+import { keyVault, type KeyVault } from '../../lib/keyvault/store'
+
+const inputClass =
+  'mt-1 w-full rounded-nb-sm border border-nb-border bg-nb-surface px-2 py-2 text-sm text-nb-text'
+const buttonClass =
+  'rounded-nb-sm border border-nb-border px-3 py-2 text-sm disabled:opacity-50'
+
+/** The sidebar owns secret input fields; unmounting or locking clears those drafts. */
+export default function KeyVaultPanel({
+  vault = keyVault,
+}: {
+  vault?: KeyVault
+}) {
+  const snapshot = useSyncExternalStore(vault.subscribe, vault.getSnapshot)
+  const [passphrase, setPassphrase] = useState('')
+  const [confirmation, setConfirmation] = useState('')
+  const [name, setName] = useState('')
+  const [value, setValue] = useState('')
+  const [editing, setEditing] = useState<string>()
+  const [deleting, setDeleting] = useState<string>()
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState('')
+  const [notice, setNotice] = useState('')
+
+  useEffect(() => {
+    try {
+      vault.refresh()
+    } catch {
+      setError('Browser storage is unavailable.')
+    }
+  }, [vault])
+  useEffect(() => {
+    if (snapshot.status !== 'unlocked') {
+      setValue('')
+      setName('')
+      setEditing(undefined)
+      setDeleting(undefined)
+    }
+  }, [snapshot.status])
+
+  /** Report only controlled vault errors; never log inputs or include them in outputs. */
+  async function act(work: () => Promise<void>) {
+    setBusy(true)
+    setError('')
+    setNotice('')
+    try {
+      await work()
+    } catch (error) {
+      setError(
+        error instanceof Error ? error.message : 'Vault operation failed.'
+      )
+    } finally {
+      setBusy(false)
+      setPassphrase('')
+      setConfirmation('')
+      setValue('')
+    }
+  }
+
+  return (
+    <div
+      id="key-vault-panel"
+      className="flex h-full min-h-0 flex-col bg-nb-surface text-nb-text"
+    >
+      <header className="border-b border-nb-border px-4 py-3">
+        <h2 className="text-sm font-semibold">Key Vault</h2>
+        <p className="mt-1 text-xs text-nb-text-muted">
+          Named keys for your notebook integrations.
+        </p>
+      </header>
+      <div id="key-vault-content" className="space-y-4 overflow-y-auto p-4">
+        <p className="text-xs leading-5 text-nb-text-muted">
+          Encrypted in this browser for this Runme site. Keys are never included
+          in notebook files or Drive sync.
+        </p>
+        {snapshot.status !== 'unlocked' ? (
+          <form
+            className="space-y-3"
+            onSubmit={(event) => {
+              event.preventDefault()
+              void act(async () => {
+                if (snapshot.status === 'new' && passphrase !== confirmation)
+                  throw new Error('Passphrases do not match.')
+                await vault.unlock(passphrase, snapshot.status === 'new')
+              })
+            }}
+          >
+            <p className="text-sm">
+              {snapshot.status === 'new'
+                ? 'Create a vault with a passphrase. You will use it to unlock your keys after reopening Runme.'
+                : 'Unlock your saved keys for this tab.'}
+            </p>
+            <label className="block text-sm">
+              Vault passphrase
+              <input
+                className={inputClass}
+                type="password"
+                autoComplete={
+                  snapshot.status === 'new'
+                    ? 'new-password'
+                    : 'current-password'
+                }
+                value={passphrase}
+                onChange={(e) => setPassphrase(e.target.value)}
+                required
+                disabled={busy}
+                minLength={snapshot.status === 'new' ? 12 : undefined}
+              />
+            </label>
+            {snapshot.status === 'new' && (
+              <>
+                <label className="block text-sm">
+                  Confirm passphrase
+                  <input
+                    className={inputClass}
+                    type="password"
+                    autoComplete="new-password"
+                    value={confirmation}
+                    onChange={(e) => setConfirmation(e.target.value)}
+                    required
+                    disabled={busy}
+                  />
+                </label>
+                <p className="text-xs text-nb-text-muted">
+                  Use at least 12 characters. Keep the passphrase safe: Runme
+                  cannot recover it. Clearing this site's browser data removes
+                  the vault.
+                </p>
+              </>
+            )}
+            <button className={buttonClass} disabled={busy} type="submit">
+              {busy
+                ? 'Unlocking…'
+                : snapshot.status === 'new'
+                  ? 'Create vault'
+                  : 'Unlock vault'}
+            </button>
+          </form>
+        ) : (
+          <>
+            <button
+              type="button"
+              className={buttonClass}
+              onClick={() => {
+                vault.lock()
+                setNotice('')
+                setError('')
+              }}
+            >
+              Lock vault
+            </button>
+            <p className="text-xs text-nb-text-muted">
+              Unlocked for this tab. Run only trusted browser JavaScript while
+              your keys are available.
+            </p>
+            <ul className="space-y-2" aria-label="Saved keys">
+              {snapshot.names.map((key) => (
+                <li
+                  key={key}
+                  className="rounded-nb-sm border border-nb-border p-2"
+                >
+                  <p className="break-all font-mono text-sm">{key}</p>
+                  <div
+                    id={`key-vault-actions-${encodeURIComponent(key)}`}
+                    className="mt-2 flex flex-wrap gap-2"
+                  >
+                    <button
+                      className={buttonClass}
+                      type="button"
+                      disabled={busy}
+                      aria-label={`Edit ${key}`}
+                      onClick={() => {
+                        setName(key)
+                        setValue('')
+                        setEditing(key)
+                        setDeleting(undefined)
+                        setError('')
+                        setNotice('')
+                      }}
+                    >
+                      Edit
+                    </button>
+                    <button
+                      className={buttonClass}
+                      type="button"
+                      disabled={busy}
+                      aria-label={`Delete ${key}`}
+                      onClick={() => setDeleting(key)}
+                    >
+                      Delete
+                    </button>
+                  </div>
+                  {deleting === key && (
+                    <div
+                      id="key-vault-delete-confirmation"
+                      className="mt-2 space-y-2"
+                    >
+                      <p className="text-xs">
+                        Remove this saved key? Keep a copy if you will need it
+                        again.
+                      </p>
+                      <button
+                        className={buttonClass}
+                        type="button"
+                        disabled={busy}
+                        onClick={() =>
+                          void act(async () => {
+                            await vault.deleteKey(key)
+                            setDeleting(undefined)
+                            if (editing === key) {
+                              setEditing(undefined)
+                              setName('')
+                            }
+                            setNotice('Key removed.')
+                          })
+                        }
+                      >
+                        Confirm removal
+                      </button>
+                      <button
+                        className={buttonClass}
+                        type="button"
+                        onClick={() => setDeleting(undefined)}
+                      >
+                        Cancel removal
+                      </button>
+                    </div>
+                  )}
+                </li>
+              ))}
+            </ul>
+            {!snapshot.names.length && (
+              <p className="text-sm">
+                No keys yet. Add your first named key below.
+              </p>
+            )}
+            <form
+              className="space-y-3"
+              onSubmit={(event) => {
+                event.preventDefault()
+                void act(async () => {
+                  await vault.saveKey(name, value, editing)
+                  setName('')
+                  setEditing(undefined)
+                  setNotice('Key saved.')
+                })
+              }}
+            >
+              <h3 className="text-sm font-semibold">
+                {editing ? 'Edit key' : 'Add a key'}
+              </h3>
+              <label className="block text-sm">
+                Key name
+                <input
+                  className={inputClass}
+                  value={name}
+                  placeholder="openai-api"
+                  maxLength={128}
+                  required
+                  disabled={busy}
+                  autoComplete="off"
+                  onChange={(e) => setName(e.target.value)}
+                />
+              </label>
+              <label className="block text-sm">
+                Key value
+                <input
+                  className={inputClass}
+                  type="password"
+                  value={value}
+                  required={!editing}
+                  disabled={busy}
+                  autoComplete="off"
+                  spellCheck={false}
+                  onChange={(e) => setValue(e.target.value)}
+                />
+              </label>
+              {editing && (
+                <p className="text-xs text-nb-text-muted">
+                  Leave the value empty to keep the existing key.
+                </p>
+              )}
+              <button type="submit" className={buttonClass} disabled={busy}>
+                {busy ? 'Saving…' : 'Save key'}
+              </button>
+              {editing && (
+                <button
+                  type="button"
+                  className={buttonClass}
+                  disabled={busy}
+                  onClick={() => {
+                    setEditing(undefined)
+                    setName('')
+                    setValue('')
+                  }}
+                >
+                  Cancel edit
+                </button>
+              )}
+            </form>
+            <p className="text-xs text-nb-text-muted">
+              Use in a browser JS cell:
+            </p>
+            <pre className="whitespace-pre-wrap break-all text-xs">
+              {'agents.setKey(keyvault.getKey("openai-api"))'}
+            </pre>
+          </>
+        )}
+        {error && (
+          <p role="alert" className="text-sm text-red-700">
+            {error}
+          </p>
+        )}
+        {notice && (
+          <p role="status" className="text-sm">
+            {notice}
+          </p>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/app/src/components/SidePanel/SidePanel.test.tsx b/app/src/components/SidePanel/SidePanel.test.tsx
index 3c6855d2..bfe417b9 100644
--- a/app/src/components/SidePanel/SidePanel.test.tsx
+++ b/app/src/components/SidePanel/SidePanel.test.tsx
@@ -412,6 +412,12 @@ describe('SidePanelToolbar drive status button', () => {
     expect(togglePanelMock).toHaveBeenCalledWith('authentication')
   })
 
+  it('opens Key Vault from its dedicated navigation button', () => {
+    render(<SidePanelToolbar />)
+    fireEvent.click(screen.getByRole('button', { name: 'Toggle Key Vault panel' }))
+    expect(togglePanelMock).toHaveBeenCalledWith('keyvault')
+  })
+
   it('opens AI grader settings from the dedicated navigation button', () => {
     render(<SidePanelToolbar />)
     fireEvent.click(screen.getByRole('button', { name: 'Toggle AI grader settings panel' }))
diff --git a/app/src/components/SidePanel/SidePanel.tsx b/app/src/components/SidePanel/SidePanel.tsx
index c62ca5dd..343fd145 100644
--- a/app/src/components/SidePanel/SidePanel.tsx
+++ b/app/src/components/SidePanel/SidePanel.tsx
@@ -10,6 +10,7 @@ import {
   ServerStackIcon,
   UserCircleIcon,
   KeyIcon,
+  LockClosedIcon,
   SparklesIcon,
 } from '@heroicons/react/24/outline'
 import { XMarkIcon } from '@heroicons/react/20/solid'
@@ -59,6 +60,7 @@ import {
   resolveDriveLoginConfiguration,
 } from '../../auth/appLoginConfiguration'
 import { getServiceAccountCredentialStatusError } from '../../auth/googleServiceAccountImpersonation'
+import KeyVaultPanel from '../KeyVault/KeyVaultPanel'
 import AuthenticationSettingsPanel from '../AuthenticationSettings/AuthenticationSettingsPanel'
 import { SuggestionGraderSettings } from '../SuggestionGraderSettings/SuggestionGraderSettings'
 import { showToast } from '../../lib/toast'
@@ -652,6 +654,13 @@ export function SidePanelToolbar() {
           <KeyIcon className="h-5 w-5" />
           <span className={tooltipBase}>Authentication Settings</span>
         </button>
+        <button type="button" data-tour-id="left-nav.key-vault"
+          className={`${sideButtonBase} ${activePanel === 'keyvault' ? sideButtonActive : sideButtonInactive}`}
+          aria-pressed={activePanel === 'keyvault'} aria-label="Toggle Key Vault panel"
+          onClick={() => togglePanel('keyvault')}>
+          <LockClosedIcon className="h-5 w-5" />
+          <span className={tooltipBase}>Key Vault</span>
+        </button>
         <button type="button" data-tour-id="left-nav.grader-settings"
           className={`${sideButtonBase} ${activePanel === 'grader' ? sideButtonActive : sideButtonInactive}`}
           aria-pressed={activePanel === 'grader'} aria-label="Toggle AI grader settings panel"
@@ -697,6 +706,7 @@ export function SidePanelContent() {
 
   return (
     <div className="relative h-full min-h-0 w-full">
+      {activePanel === 'keyvault' && <KeyVaultPanel />}
       {activePanel === 'grader' && <SuggestionGraderSettings />}
       <div
         className={`h-full min-h-0 w-full ${activePanel === 'explorer' ? 'flex' : 'hidden'}`}
diff --git a/app/src/lib/agents/runtime.test.ts b/app/src/lib/agents/runtime.test.ts
index 755fed4f..7437a0ee 100644
--- a/app/src/lib/agents/runtime.test.ts
+++ b/app/src/lib/agents/runtime.test.ts
@@ -63,3 +63,46 @@ describe('agents runtime', () => {
     expect(() => createAgentsApi().monitor('s')).toThrow('notebook JS cell')
   })
 })
+
+it('uses vault keys only for OpenAI requests and stops monitors when the vault locks', async () => {
+  const { webcrypto } = await import('node:crypto')
+  const { keyVault, resolveKeyReference } = await import('../keyvault/store')
+  vi.stubGlobal('crypto', webcrypto)
+  localStorage.clear()
+  keyVault.refresh()
+  await keyVault.unlock('a long test passphrase', true)
+  await keyVault.saveKey('openai-api', 'runtime-secret')
+  const outputs: string[] = []
+  const api = createAgentsApi((_mime, value) => outputs.push(value))
+  expect(api.setKey(keyVault.getKey('openai-api'))).toEqual({
+    configured: true,
+  })
+  const fetchMock = vi.fn(async () => new Response('{}', { status: 401 }))
+  vi.stubGlobal('fetch', fetchMock)
+  const descriptor = api.monitor('sess_test')
+  await api.resume(descriptor.id)
+  expect(fetchMock).toHaveBeenCalled()
+  const [url, options] = fetchMock.mock.calls[0] as unknown as [
+    string,
+    RequestInit,
+  ]
+  expect(url).toBe('https://api.openai.com/v1/agents/sessions/sess_test/events?stream=true')
+  expect(new Headers(options.headers).get('Authorization')).toBe(
+    'Bearer runtime-secret'
+  )
+  expect(outputs.join('')).not.toContain('runtime-secret')
+  expect(JSON.stringify(api.get(descriptor.id))).not.toContain('runtime-secret')
+  keyVault.lock()
+  expect(api.get(descriptor.id).connection).toBe('paused')
+  expect(() => keyVault.getKey('openai-api')).toThrow('Unlock')
+  expect(() =>
+    callAgentsBridge(api, 'agents.setKey', [{ name: 'openai-api' }])
+  ).toThrow('Unsupported')
+  expect(() =>
+    resolveKeyReference({
+      name: 'openai-api',
+      toJSON: () => ({ name: 'openai-api' }),
+    })
+  ).toThrow('getKey')
+  vi.unstubAllGlobals()
+})
diff --git a/app/src/lib/agents/runtime.ts b/app/src/lib/agents/runtime.ts
index 2aee8edd..93723fef 100644
--- a/app/src/lib/agents/runtime.ts
+++ b/app/src/lib/agents/runtime.ts
@@ -1,3 +1,8 @@
+import {
+  type KeyReference,
+  keyVault,
+  resolveKeyReference,
+} from '../keyvault/store'
 import { AgentMonitor } from './monitor'
 import { type AgentConnectionOptions, createAgentTransport } from './transport'
 import {
@@ -8,6 +13,7 @@ import {
 
 type Display = (mime: string, value: string) => void
 let connection: AgentTransport | undefined
+let releaseVaultSubscription: (() => void) | undefined
 // This registry owns only this browser lifetime. Descriptors never carry auth or code.
 const monitors = new Map<string, AgentMonitor>()
 const autoConnect = new WeakSet<AgentMonitor>()
@@ -27,7 +33,7 @@ export function resolveAgentMonitor(
   const monitor = new AgentMonitor(descriptor, () => {
     if (!connection)
       throw new Error(
-        'Configure an authenticated connection with agents.configure({ baseUrl, getHeaders }) in AppKernel browser JS, then Connect.'
+        'Unlock Key Vault and run agents.setKey(keyvault.getKey("openai-api")) in browser JS, then Connect.'
       )
     return connection
   })
@@ -70,6 +76,8 @@ export function resetAgentMonitors(): void {
   monitors.forEach((monitor) => monitor.pause())
   monitors.clear()
   connection = undefined
+  releaseVaultSubscription?.()
+  releaseVaultSubscription = undefined
 }
 
 /** The same commands back widget buttons, AppKernel cells and the sandbox bridge. */
@@ -83,7 +91,27 @@ export function createAgentsApi(display?: Display) {
     return monitor
   }
   return {
+    /** Select a vault reference for the OpenAI API; never serialize the secret. */
+    setKey: (reference: KeyReference) => {
+      resolveKeyReference(reference)
+      const transport = createAgentTransport({
+        baseUrl: 'https://api.openai.com/v1',
+        getHeaders: () => ({
+          Authorization: `Bearer ${resolveKeyReference(reference)}`,
+        }),
+      })
+      monitors.forEach((monitor) => monitor.pause())
+      releaseVaultSubscription?.()
+      connection = transport
+      // Rotation/removal/locking revokes existing streams as well as future requests.
+      releaseVaultSubscription = keyVault.subscribe(() => {
+        monitors.forEach((monitor) => monitor.pause())
+      })
+      return { configured: true }
+    },
     configure: (options: AgentConnectionOptions) => {
+      releaseVaultSubscription?.()
+      releaseVaultSubscription = undefined
       // Disconnect existing views before changing the authority serving their IDs.
       monitors.forEach((monitor) => monitor.pause())
       connection = createAgentTransport(options)
@@ -120,6 +148,6 @@ export function createAgentsApi(display?: Display) {
     newer: (id: string) => requireMonitor(id).newer(),
     latest: (id: string) => requireMonitor(id).latest(),
     help: () =>
-      'agents.configure({ baseUrl, getHeaders? }) [browser JS only; memory-only auth]; agents.monitor(sessionId, { pageSize?: 1..100 }) [notebook JS cell]; agents.get(id); agents.pause(id); await agents.resume(id); await agents.older(id); await agents.newer(id); agents.latest(id). Pause stops observation, not the agent. Saved widgets require Connect.',
+      'agents.setKey(keyvault.getKey(name)) [browser JS; OpenAI API]; agents.configure({ baseUrl, getHeaders? }) [browser JS only; memory-only auth]; agents.monitor(sessionId, { pageSize?: 1..100 }) [notebook JS cell]; agents.get(id); agents.pause(id); await agents.resume(id); await agents.older(id); await agents.newer(id); agents.latest(id). Pause stops observation, not the agent. Saved widgets require Connect.',
   }
 }
diff --git a/app/src/lib/keyvault/store.test.ts b/app/src/lib/keyvault/store.test.ts
new file mode 100644
index 00000000..40c0ab23
--- /dev/null
+++ b/app/src/lib/keyvault/store.test.ts
@@ -0,0 +1,110 @@
+import { webcrypto } from 'node:crypto'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { KeyVault, VAULT_STORAGE_KEY, resolveKeyReference } from './store'
+
+beforeEach(() => {
+  localStorage.clear()
+  vi.stubGlobal('crypto', webcrypto)
+})
+afterEach(() => vi.unstubAllGlobals())
+const password = 'a long test passphrase'
+
+describe('encrypted key vault', () => {
+  it('persists multiple named keys encrypted, unlocks after reload, and redacts references', async () => {
+    const vault = new KeyVault()
+    vault.refresh()
+    expect(vault.getSnapshot().status).toBe('new')
+    await vault.unlock(password, true)
+    await vault.saveKey('openai-api', 'secret-alpha')
+    await vault.saveKey('__proto__', 'secret-beta')
+    expect(vault.getSnapshot().names).toEqual(['__proto__', 'openai-api'])
+    const reference = vault.getKey('openai-api')
+    expect(JSON.stringify(reference)).toBe('{"name":"openai-api"}')
+    expect(resolveKeyReference(reference)).toBe('secret-alpha')
+    const raw = localStorage.getItem(VAULT_STORAGE_KEY)!
+    for (const value of [password, 'secret-alpha', 'secret-beta', 'openai-api'])
+      expect(raw).not.toContain(value)
+    vault.lock()
+    expect(vault.getSnapshot().names).toEqual([])
+    expect(() => resolveKeyReference(reference)).toThrow('Unlock')
+    const reopened = new KeyVault()
+    reopened.refresh()
+    expect(reopened.getSnapshot().status).toBe('locked')
+    await reopened.unlock(password)
+    expect(resolveKeyReference(reopened.getKey('__proto__'))).toBe(
+      'secret-beta'
+    )
+  })
+  it('supports explicit rotation/rename/deletion without silently overwriting duplicate names', async () => {
+    const vault = new KeyVault()
+    await vault.unlock(password, true)
+    await vault.saveKey('first', 'one')
+    await vault.saveKey('second', 'two')
+    const reference = vault.getKey('first')
+    await expect(vault.saveKey('first', 'duplicate')).rejects.toThrow(
+      'already exists'
+    )
+    await expect(vault.saveKey('second', 'duplicate', 'first')).rejects.toThrow(
+      'already exists'
+    )
+    await vault.saveKey('first', 'rotated', 'first')
+    expect(resolveKeyReference(reference)).toBe('rotated')
+    await vault.saveKey('renamed', '', 'first')
+    expect(() => resolveKeyReference(reference)).toThrow('missing')
+    expect(resolveKeyReference(vault.getKey('renamed'))).toBe('rotated')
+    await vault.deleteKey('renamed')
+    expect(vault.getSnapshot().names).toEqual(['second'])
+  })
+  it('preserves ciphertext on incorrect passphrases and malformed data', async () => {
+    const vault = new KeyVault()
+    await vault.unlock(password, true)
+    vault.lock()
+    const raw = localStorage.getItem(VAULT_STORAGE_KEY)
+    await expect(vault.unlock('incorrect')).rejects.toThrow('Unable to unlock')
+    expect(localStorage.getItem(VAULT_STORAGE_KEY)).toBe(raw)
+    localStorage.setItem(VAULT_STORAGE_KEY, 'broken-json')
+    await expect(vault.unlock(password)).rejects.toThrow('Unable to unlock')
+    expect(localStorage.getItem(VAULT_STORAGE_KEY)).toBe('broken-json')
+  })
+  it('rejects stale writes and locks a tab whose ciphertext changed', async () => {
+    const first = new KeyVault(),
+      second = new KeyVault()
+    await first.unlock(password, true)
+    await second.unlock(password)
+    await first.saveKey('first', 'secret')
+    await expect(second.saveKey('second', 'lost-update')).rejects.toThrow(
+      'another tab'
+    )
+    expect(second.getSnapshot().status).toBe('locked')
+    await second.unlock(password)
+    expect(second.getSnapshot().names).toEqual(['first'])
+  })
+  it('does not finish unlocking after a lock and rejects forged references', async () => {
+    const vault = new KeyVault()
+    await vault.unlock(password, true)
+    vault.lock()
+    const pending = vault.unlock(password)
+    vault.lock()
+    await expect(pending).rejects.toThrow('locked')
+    expect(vault.getSnapshot().status).toBe('locked')
+    expect(() =>
+      resolveKeyReference({ name: 'fake', toJSON: () => ({ name: 'fake' }) })
+    ).toThrow('getKey')
+  })
+  it('does not publish unsaved mutations when browser storage is full', async () => {
+    const vault = new KeyVault()
+    await vault.unlock(password, true)
+    await vault.saveKey('first', 'preserved')
+    const mock = vi
+      .spyOn(Storage.prototype, 'setItem')
+      .mockImplementation(() => {
+        throw new Error('Quota')
+      })
+    await expect(vault.saveKey('second', 'unsaved')).rejects.toThrow(
+      'Could not save'
+    )
+    expect(vault.getSnapshot().names).toEqual(['first'])
+    mock.mockRestore()
+  })
+})
diff --git a/app/src/lib/keyvault/store.ts b/app/src/lib/keyvault/store.ts
new file mode 100644
index 00000000..53462840
--- /dev/null
+++ b/app/src/lib/keyvault/store.ts
@@ -0,0 +1,311 @@
+/** Local encrypted vault. Only names and opaque references cross the notebook API. */
+export const VAULT_STORAGE_KEY = 'runme/keyvault/v1'
+const ITERATIONS = 600_000
+
+type Envelope = { version: 1; salt: string; iv: string; ciphertext: string }
+export type KeyReference = Readonly<{
+  name: string
+  toJSON(): { name: string }
+}>
+type Snapshot = Readonly<{
+  status: 'new' | 'locked' | 'unlocked'
+  names: readonly string[]
+}>
+const references = new WeakMap<
+  KeyReference,
+  { vault: KeyVault; name: string }
+>()
+const encode = (bytes: Uint8Array) => {
+  let text = ''
+  for (let i = 0; i < bytes.length; i += 8192)
+    text += String.fromCharCode(...bytes.subarray(i, i + 8192))
+  return btoa(text)
+}
+const decode = (value: string) =>
+  Uint8Array.from(atob(value), (c) => c.charCodeAt(0))
+
+/** Validate envelopes without discarding unreadable or unsupported saved data. */
+function parseEnvelope(raw: string): Envelope {
+  const value = JSON.parse(raw) as Envelope
+  if (
+    value.version !== 1 ||
+    typeof value.salt !== 'string' ||
+    typeof value.iv !== 'string' ||
+    typeof value.ciphertext !== 'string' ||
+    decode(value.salt).length !== 16 ||
+    decode(value.iv).length !== 12
+  ) {
+    throw new Error('Unsupported or damaged vault.')
+  }
+  return value
+}
+
+/** React and notebook helpers share this tab-local store; plaintext is never persisted. */
+export class KeyVault {
+  private snapshot: Snapshot = Object.freeze({ status: 'locked', names: [] })
+  private listeners = new Set<() => void>()
+  private values = new Map<string, string>()
+  private key?: CryptoKey
+  private salt?: string
+  private raw: string | null = null
+  private generation = 0
+  private busy = false
+
+  constructor(private storage: () => Storage = () => window.localStorage) {}
+
+  subscribe = (listener: () => void) => {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+  getSnapshot = () => this.snapshot
+
+  /** Called on panel mount and cross-tab storage changes; never overwrites ciphertext. */
+  refresh = () => {
+    const raw = this.storage().getItem(VAULT_STORAGE_KEY)
+    if (raw !== this.raw || this.snapshot.status !== 'unlocked') {
+      this.lock()
+      this.raw = raw
+      this.publish(raw === null ? 'new' : 'locked')
+    }
+  }
+
+  private publish(status: Snapshot['status']) {
+    this.snapshot = Object.freeze({
+      status,
+      names: Object.freeze([...this.values.keys()].sort()),
+    })
+    this.listeners.forEach((listener) => listener())
+  }
+
+  /** Invalidate in-flight unlocks/saves and immediately release decrypted values. */
+  lock = () => {
+    this.generation++
+    this.key = undefined
+    this.salt = undefined
+    this.values.clear()
+    this.publish(this.raw === null ? 'new' : 'locked')
+  }
+
+  private async derive(passphrase: string, salt: string) {
+    const material = await crypto.subtle.importKey(
+      'raw',
+      new TextEncoder().encode(passphrase),
+      'PBKDF2',
+      false,
+      ['deriveKey']
+    )
+    return crypto.subtle.deriveKey(
+      {
+        name: 'PBKDF2',
+        hash: 'SHA-256',
+        salt: decode(salt),
+        iterations: ITERATIONS,
+      },
+      material,
+      { name: 'AES-GCM', length: 256 },
+      false,
+      ['encrypt', 'decrypt']
+    )
+  }
+
+  /** Serialize this tab's async edits. A storage comparison prevents stale tab writes. */
+  private async exclusive(work: () => Promise<void>) {
+    if (this.busy) throw new Error('A vault operation is already running.')
+    this.busy = true
+    try {
+      // Web Locks coordinates writers in other tabs on this origin.
+      if (typeof navigator !== 'undefined' && navigator.locks) {
+        await navigator.locks.request(VAULT_STORAGE_KEY, work)
+      } else {
+        await work()
+      }
+    } finally {
+      this.busy = false
+    }
+  }
+
+  private checkCurrent(raw: string | null, generation: number) {
+    if (generation !== this.generation)
+      throw new Error('Vault was locked. Unlock and retry.')
+    if (this.storage().getItem(VAULT_STORAGE_KEY) !== raw) {
+      this.refresh()
+      throw new Error('Vault changed in another tab. Unlock it again.')
+    }
+  }
+
+  /** Create or unlock using a passphrase retained only during key derivation. */
+  async unlock(passphrase: string, create = false) {
+    const generation = this.generation
+    await this.exclusive(async () => {
+      const raw = this.storage().getItem(VAULT_STORAGE_KEY)
+      if (create && raw !== null)
+        throw new Error('A vault already exists. Unlock it instead.')
+      if (!create && raw === null) throw new Error('Create a vault first.')
+      if (create && passphrase.length < 12)
+        throw new Error('Use a passphrase of at least 12 characters.')
+      let salt: string, key: CryptoKey, values: Map<string, string>
+      try {
+        const envelope = raw === null ? undefined : parseEnvelope(raw)
+        salt =
+          envelope?.salt ?? encode(crypto.getRandomValues(new Uint8Array(16)))
+        key = await this.derive(passphrase, salt)
+        const entries: unknown = envelope
+          ? JSON.parse(
+              new TextDecoder().decode(
+                await crypto.subtle.decrypt(
+                  { name: 'AES-GCM', iv: decode(envelope.iv) },
+                  key,
+                  decode(envelope.ciphertext)
+                )
+              )
+            )
+          : []
+        if (
+          !Array.isArray(entries) ||
+          !entries.every(
+            (e) =>
+              Array.isArray(e) &&
+              e.length === 2 &&
+              typeof e[0] === 'string' &&
+              typeof e[1] === 'string'
+          )
+        )
+          throw new Error('Invalid entries')
+        values = new Map(entries as [string, string][])
+      } catch {
+        throw new Error(
+          'Unable to unlock vault. Check the passphrase; saved data has not been changed.'
+        )
+      }
+      this.checkCurrent(raw, generation)
+      let saved = raw
+      if (create) saved = await this.persist(values, key, salt, raw, generation)
+      this.checkCurrent(saved, generation)
+      this.raw = saved
+      this.key = key
+      this.salt = salt
+      this.values = values
+      this.publish('unlocked')
+    })
+  }
+
+  private async persist(
+    values: Map<string, string>,
+    key: CryptoKey,
+    salt: string,
+    raw: string | null,
+    generation: number
+  ) {
+    const iv = crypto.getRandomValues(new Uint8Array(12))
+    const ciphertext = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      new TextEncoder().encode(JSON.stringify([...values]))
+    )
+    const saved = JSON.stringify({
+      version: 1,
+      salt,
+      iv: encode(iv),
+      ciphertext: encode(new Uint8Array(ciphertext)),
+    })
+    this.checkCurrent(raw, generation)
+    try {
+      this.storage().setItem(VAULT_STORAGE_KEY, saved)
+    } catch {
+      throw new Error(
+        'Could not save the vault in this browser. Existing keys are unchanged.'
+      )
+    }
+    return saved
+  }
+
+  /** Add a uniquely named key, or explicitly replace/rename an existing key. */
+  async saveKey(name: string, value: string, previousName?: string) {
+    name = name.trim()
+    if (!name || name.length > 128)
+      throw new Error('Use a key name between 1 and 128 characters.')
+    if (!value.trim() && previousName === undefined)
+      throw new Error('Enter a key value.')
+    await this.mutate((values) => {
+      if (previousName !== undefined && !values.has(previousName))
+        throw new Error('Key no longer exists.')
+      if (name !== previousName && values.has(name))
+        throw new Error('That key name already exists.')
+      const secret = value.trim() || values.get(previousName!)!
+      if (previousName !== undefined) values.delete(previousName)
+      values.set(name, secret)
+    })
+  }
+
+  /** Remove a named key without exposing its value. */
+  async deleteKey(name: string) {
+    await this.mutate((values) => {
+      values.delete(name)
+    })
+  }
+
+  private async mutate(update: (values: Map<string, string>) => void) {
+    await this.exclusive(async () => {
+      if (!this.key || !this.salt)
+        throw new Error('Unlock Key Vault in the left navigation first.')
+      const generation = this.generation
+      this.checkCurrent(this.raw, generation)
+      const next = new Map(this.values)
+      update(next)
+      this.raw = await this.persist(
+        next,
+        this.key,
+        this.salt,
+        this.raw,
+        generation
+      )
+      this.checkCurrent(this.raw, generation)
+      this.values = next
+      this.publish('unlocked')
+    })
+  }
+
+  /** Return a harmless reference; logging/serializing it cannot reveal the credential. */
+  getKey = (name: string): KeyReference => {
+    this.requireValue(name)
+    const reference = Object.freeze({ name, toJSON: () => ({ name }) })
+    references.set(reference, { vault: this, name })
+    return reference
+  }
+
+  /** Internal transport access checks lock state and deletion on every request. */
+  requireValue(name: string): string {
+    if (!this.key)
+      throw new Error('Unlock Key Vault in the left navigation first.')
+    this.checkCurrent(this.raw, this.generation)
+    const value = this.values.get(name)
+    if (!value)
+      throw new Error(`Key "${name}" is missing. Add it in Key Vault.`)
+    return value
+  }
+}
+
+/** Only references created by this runtime are accepted; notebook JSON cannot forge one. */
+export function resolveKeyReference(reference: KeyReference) {
+  const entry = references.get(reference)
+  if (!entry) throw new Error('Use keyvault.getKey(name) to select a key.')
+  return entry.vault.requireValue(entry.name)
+}
+
+export const keyVault = new KeyVault()
+if (typeof window !== 'undefined') {
+  window.addEventListener('storage', (event) => {
+    if (event.key === VAULT_STORAGE_KEY || event.key === null)
+      keyVault.refresh()
+  })
+  window.addEventListener('pagehide', () => keyVault.lock())
+}
+
+/** Browser notebook API deliberately excludes writes and raw secret retrieval. */
+export const keyvaultApi = Object.freeze({
+  getKey: keyVault.getKey,
+  help: () =>
+    'Add or unlock named keys in Key Vault (left navigation). Browser JS: agents.setKey(keyvault.getKey("openai-api")). getKey returns an opaque reference, not plaintext. Keys are encrypted locally and never synced with notebooks.',
+})
diff --git a/app/src/lib/runtime/appJsGlobals.ts b/app/src/lib/runtime/appJsGlobals.ts
index b07fc290..e39888df 100644
--- a/app/src/lib/runtime/appJsGlobals.ts
+++ b/app/src/lib/runtime/appJsGlobals.ts
@@ -17,6 +17,7 @@ import { LOCAL_FOLDER_URI } from '../../storage/local'
 import { NotebookStoreItemType } from '../../storage/notebook'
 import { getAuthData } from '../../token'
 import { agentEndpointManager } from '../agentEndpointManager'
+import { keyvaultApi } from '../keyvault/store'
 import { createAgentsApi } from '../agents/runtime'
 import { aisreClientManager } from '../aisreClientManager'
 import {
@@ -1817,9 +1818,11 @@ export function createAppJsGlobals({
       },
     },
     agents: createAgentsApi(displayOutput),
+    keyvault: keyvaultApi,
     help: () => {
       const message = [
         'Available namespaces:',
+        '  keyvault        - Named credential references (browser JS only)',
         '  agents          - Render and control Agents API session monitors',
         '  runme           - Notebook helpers (run all, clear outputs)',
         '  tour            - Highlight UI targets with AI-authored annotations',
diff --git a/app/src/lib/tourGuide.ts b/app/src/lib/tourGuide.ts
index 118cf29e..9c9f6dc6 100644
--- a/app/src/lib/tourGuide.ts
+++ b/app/src/lib/tourGuide.ts
@@ -76,6 +76,11 @@ export const TOUR_TARGETS: readonly TourTarget[] = [
     description:
       'Configure the identities and OAuth clients used by Runme and Google Drive.',
   },
+  {
+    id: 'left-nav.key-vault',
+    label: 'Key Vault',
+    description: 'Store named API keys in an encrypted local vault and unlock them for browser JS.',
+  },
   {
     id: 'left-nav.grader-settings',
     label: 'AI grader',
diff --git a/app/src/lib/tourUiController.ts b/app/src/lib/tourUiController.ts
index 574884e4..7ae60293 100644
--- a/app/src/lib/tourUiController.ts
+++ b/app/src/lib/tourUiController.ts
@@ -2,6 +2,7 @@ export type PanelKey =
   | 'explorer'
   | 'documentation'
   | 'authentication'
+  | 'keyvault'
   | 'grader'
   | 'open-documents'
   | 'outline'
@@ -34,6 +35,7 @@ const PANEL_KEYS = new Set<PanelKey>([
   'explorer',
   'documentation',
   'authentication',
+  'keyvault',
   'grader',
   'open-documents',
   'outline',
@@ -74,7 +76,7 @@ function persistPanel(panel: PanelKey): void {
 function assertPanelKey(panel: unknown): asserts panel is PanelKey {
   if (!PANEL_KEYS.has(panel as PanelKey)) {
     throw new Error(
-      'activePanel must be explorer, documentation, authentication, grader, open-documents, outline, or null.'
+      'activePanel must be explorer, documentation, authentication, keyvault, grader, open-documents, outline, or null.'
     )
   }
 }
diff --git a/docs-dev/CUJs/agent-monitor.md b/docs-dev/CUJs/agent-monitor.md
index b6e8c805..9fb02c5e 100644
--- a/docs-dev/CUJs/agent-monitor.md
+++ b/docs-dev/CUJs/agent-monitor.md
@@ -14,3 +14,13 @@ Start the Go fixture with `go run testing/fake-agents-server.go` and Runme at `h
 6. Reload the browser. The saved widget is disconnected, requires Connect, and does not contain credentials or serialized messages. Configure the connection in a new execution before connecting.
 
 Capture the rendered monitor with notebook context and record assertions. Controller/component tests cover root/subagent completion, replay races, EOF, safe Markdown, malformed descriptors and pagination. NotebookData tests cover browser and sandbox output. The Go fixture drives the manual WebMCP browser CUJ; it is not registered in the automated browser orchestrator yet.
+
+
+## Named key vault
+
+1. Open Key Vault from the left navigation on an isolated test origin. Create a vault with a test passphrase and add two synthetic named keys; values must be masked and cleared after saving.
+2. Reload: the vault is locked. An incorrect passphrase must preserve the existing vault. Unlock with the correct passphrase and verify both names.
+3. Run browser JS `agents.setKey(keyvault.getKey("openai-api"))` with a synthetic test key. Verify no key value appears in notebook source, output descriptors, help, snapshots, or persisted browser ciphertext. Authentication failures must not echo credentials.
+4. Lock the vault with a monitor active. Observation must pause. Unlock/resume to reconnect; deleted or renamed keys must fail until the cell selects an existing name.
+5. Rotate and rename a key, reject duplicate names, and remove a key using inline confirmation. In a second tab, verify edits lock stale state rather than overwriting the first tab's changes.
+6. Keep existing synthetic Go transport tests for rendered messages/events/pagination. A real API credential is entered by the user through the vault sidebar, never by editing the notebook.
diff --git a/docs-dev/design/20261003_agents_api_ui.md b/docs-dev/design/20261003_agents_api_ui.md
index 8292afa2..7815a5e2 100644
--- a/docs-dev/design/20261003_agents_api_ui.md
+++ b/docs-dev/design/20261003_agents_api_ui.md
@@ -31,7 +31,7 @@ Session status, root-turn status, and connection status are separate. Idle is no
 ## Cell UX
 
 1. Write a JS cell and select AppKernel.
-2. Configure an authenticated transport once per browser lifetime, then execute agents.monitor(session_id).
+2. Open Key Vault in the left navigation, create/unlock the vault, and add a named key. In browser JS, call agents.setKey(keyvault.getKey("openai-api")), then agents.monitor(session_id).
 3. The editor collapses into Render mode. A toolbar retains Edit, Render, Run, and normal cell actions.
 4. Edit reveals source while keeping the monitor mounted but hidden. Returning to Render does not rerun code. After source changes, label the existing output as coming from an earlier execution until Run is pressed.
 5. Clearing output, rerunning, deleting the cell, or closing the notebook releases the widget's stream. Pause monitoring stops observation only. Resume reconnects and reloads saved history.
@@ -75,10 +75,7 @@ The latest root-turn endpoint is consulted independently of item history. Missin
 ## Runtime and transport
 
 ```ts
-agents.configure({
-  baseUrl: 'https://api.openai.com/v1',
-  getHeaders: async () => ({ Authorization: `Bearer ${await obtainToken()}` }),
-})
+agents.setKey(keyvault.getKey('openai-api'))
 const widget = agents.monitor(session_id, { pageSize: 50 })
 agents.get(widget.id)        // JSON snapshot
 agents.pause(widget.id)
@@ -88,7 +85,13 @@ await agents.newer(widget.id)
 agents.latest(widget.id)
 ```
 
-obtainToken is an application-owned credential provider, not a built-in helper. Configuration stays in memory and is never returned from help, serialized into output, or written to localStorage. A deployment may supply a same-origin authenticated proxy base URL instead. This change implements the REST/SSE browser transport, not a new credential broker or server proxy. The existing Runme agent endpoint is unrelated and must not be reused implicitly. The Python runner's local key path cannot be accessed by the browser.
+Key Vault is a dedicated left-navigation panel for creating/unlocking a local vault and adding, renaming, rotating, or deleting named keys. Password fields mask values; editing a key never loads its old value into the form. The example uses `openai-api` consistently; users can choose other names.
+
+Persist a versioned AES-256-GCM envelope with a random 96-bit IV per write. Derive the nonextractable encryption key from a user passphrase with PBKDF2-SHA256 (600,000 iterations, random 128-bit salt). Encrypt names and values together. Store only ciphertext, salt, and IV in localStorage, scoped to this browser profile and Runme origin; no Drive or notebook export includes the vault. The passphrase is not saved; forgotten passphrases and cleared browser data are not recoverable. While unlocked, trusted browser JS shares the app's authority; this is not an XSS isolation boundary or a cloud vault.
+
+`keyvault.getKey(name)` returns a process-local opaque reference containing only its name when serialized. `agents.setKey(reference)` accepts only a genuine reference and binds authentication to the OpenAI API. Resolve the current value for each request rather than copying it into a durable descriptor. Lock, rotation, removal, and cross-tab vault changes pause existing streams. Reload/pagehide locks the vault. Missing names and locked vaults produce errors without secret values. Unlock explicitly and resume observation. Web Locks plus ciphertext comparisons reject stale writes; storage failures preserve previous keys, and invalid ciphertext is never automatically deleted.
+
+Keep `agents.configure({ baseUrl, getHeaders })` as an advanced integration point for application-owned proxies. Configuration remains in memory. No server credential broker is added, and browser code cannot read the Python runner's local key file. Vault writes/unlock happen in the sidebar, not in saved notebook source. Sandbox code cannot retrieve keys or install authentication providers.
 
 The transport uses GET session, GET items, GET turns, and GET events?stream=true with OpenAI-Beta: agents=v1. Reject redirects and avoid including upstream error bodies or authorization headers in notebook diagnostics. Refresh headers for each request. Sandbox cells may monitor and control already-configured monitors through host methods; they cannot install credential-provider callbacks. WebMCP can use the same read/control methods and create a monitor in a targeted notebook by inserting/executing a JS cell.
 
diff --git a/docs/20-agent-monitors.md b/docs/20-agent-monitors.md
index 60eadc7f..a512b011 100644
--- a/docs/20-agent-monitors.md
+++ b/docs/20-agent-monitors.md
@@ -9,14 +9,21 @@ order: 20
 
 Use an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.
 
-Configure a trusted browser-accessible API root once with `agents.configure({ baseUrl, getHeaders })`. The optional async `getHeaders` provider supplies authorization headers without persisting credentials in the notebook. Do not put API keys in cell source. A same-origin authenticated proxy can omit the provider. The Python runner's local key files are not accessible to browser JavaScript. This release does not include a proxy or credential broker.
+Open **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Key values are masked and never included in notebook files or Drive sync.
 
-After configuring the connection, set a session ID and run the following cell using **JS → browser**. Sandbox cells can monitor a connection already configured by browser JS.
+The vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.
+
+Run the following cell with **JS → browser**:
 
 ```js
+agents.setKey(keyvault.getKey('openai-api'))
 const widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })
 ```
 
+`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.
+
+For an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.
+
 ## Read and monitor
 
 **Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.
diff --git a/docs/agent-monitors.json b/docs/agent-monitors.json
index 40f6b9e2..cf308832 100644
--- a/docs/agent-monitors.json
+++ b/docs/agent-monitors.json
@@ -3,14 +3,14 @@
     {
       "kind": 1,
       "languageId": "markdown",
-      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nConfigure a trusted browser-accessible API root once with `agents.configure({ baseUrl, getHeaders })`. The optional async `getHeaders` provider supplies authorization headers without persisting credentials in the notebook. Do not put API keys in cell source. A same-origin authenticated proxy can omit the provider. The Python runner's local key files are not accessible to browser JavaScript. This release does not include a proxy or credential broker.\n\nAfter configuring the connection, set a session ID and run the following cell using **JS \u2192 browser**. Sandbox cells can monitor a connection already configured by browser JS.\n",
+      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Key values are masked and never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS \u2192 browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
       "refId": "0a152c34fb9e412d95c68cec16074052",
       "metadata": {}
     },
     {
       "kind": 2,
       "languageId": "javascript",
-      "value": "// Replace with an existing session ID after configuring the connection.\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })",
+      "value": "agents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })",
       "metadata": {
         "runme.dev/runnerName": "appkernel-js"
       },

From 91cea27fc61496d51ff1794fd435daf1a249e8f2 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 15:52:36 -0700
Subject: [PATCH 05/11] Use key and gear icons for vault and authentication
 settings

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 app/src/components/SidePanel/SidePanel.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/app/src/components/SidePanel/SidePanel.tsx b/app/src/components/SidePanel/SidePanel.tsx
index 343fd145..0e731b89 100644
--- a/app/src/components/SidePanel/SidePanel.tsx
+++ b/app/src/components/SidePanel/SidePanel.tsx
@@ -10,7 +10,7 @@ import {
   ServerStackIcon,
   UserCircleIcon,
   KeyIcon,
-  LockClosedIcon,
+  Cog6ToothIcon,
   SparklesIcon,
 } from '@heroicons/react/24/outline'
 import { XMarkIcon } from '@heroicons/react/20/solid'
@@ -651,14 +651,14 @@ export function SidePanelToolbar() {
           aria-label="Toggle Authentication Settings panel"
           onClick={() => togglePanel('authentication')}
         >
-          <KeyIcon className="h-5 w-5" />
+          <Cog6ToothIcon className="h-5 w-5" />
           <span className={tooltipBase}>Authentication Settings</span>
         </button>
         <button type="button" data-tour-id="left-nav.key-vault"
           className={`${sideButtonBase} ${activePanel === 'keyvault' ? sideButtonActive : sideButtonInactive}`}
           aria-pressed={activePanel === 'keyvault'} aria-label="Toggle Key Vault panel"
           onClick={() => togglePanel('keyvault')}>
-          <LockClosedIcon className="h-5 w-5" />
+          <KeyIcon className="h-5 w-5" />
           <span className={tooltipBase}>Key Vault</span>
         </button>
         <button type="button" data-tour-id="left-nav.grader-settings"

From 78f02209709e08e437e0026f6cdcd821afeffe7c Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 15:57:06 -0700
Subject: [PATCH 06/11] Show key vault lock state with red and green icons

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 app/src/components/SidePanel/SidePanel.tsx | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/app/src/components/SidePanel/SidePanel.tsx b/app/src/components/SidePanel/SidePanel.tsx
index 0e731b89..001eafbf 100644
--- a/app/src/components/SidePanel/SidePanel.tsx
+++ b/app/src/components/SidePanel/SidePanel.tsx
@@ -20,6 +20,7 @@ import {
   useEffect,
   useRef,
   useState,
+  useSyncExternalStore,
   type KeyboardEvent as ReactKeyboardEvent,
   type MouseEvent,
 } from 'react'
@@ -61,6 +62,7 @@ import {
 } from '../../auth/appLoginConfiguration'
 import { getServiceAccountCredentialStatusError } from '../../auth/googleServiceAccountImpersonation'
 import KeyVaultPanel from '../KeyVault/KeyVaultPanel'
+import { keyVault } from '../../lib/keyvault/store'
 import AuthenticationSettingsPanel from '../AuthenticationSettings/AuthenticationSettingsPanel'
 import { SuggestionGraderSettings } from '../SuggestionGraderSettings/SuggestionGraderSettings'
 import { showToast } from '../../lib/toast'
@@ -236,6 +238,10 @@ function OpenDocumentsPanel() {
 }
 
 export function SidePanelToolbar() {
+  // Keep the indicator current even while the vault panel is closed.
+  const vaultSnapshot = useSyncExternalStore(keyVault.subscribe, keyVault.getSnapshot)
+  const vaultUnlocked = vaultSnapshot.status === 'unlocked'
+  const vaultStatus = vaultUnlocked ? 'Unlocked' : 'Locked'
   const { activePanel, togglePanel } = useSidePanel()
   const { commentsPanelOpen, toggleCommentsPanel } = useCommentsPanel()
   const { showDocument } = useWorkspaceDocumentContext()
@@ -657,9 +663,10 @@ export function SidePanelToolbar() {
         <button type="button" data-tour-id="left-nav.key-vault"
           className={`${sideButtonBase} ${activePanel === 'keyvault' ? sideButtonActive : sideButtonInactive}`}
           aria-pressed={activePanel === 'keyvault'} aria-label="Toggle Key Vault panel"
+          aria-description={`Key Vault: ${vaultStatus}`}
           onClick={() => togglePanel('keyvault')}>
-          <KeyIcon className="h-5 w-5" />
-          <span className={tooltipBase}>Key Vault</span>
+          <KeyIcon className={`h-5 w-5 ${vaultUnlocked ? 'text-emerald-500' : 'text-red-500'}`} />
+          <span className={tooltipBase}>Key Vault: {vaultStatus}</span>
         </button>
         <button type="button" data-tour-id="left-nav.grader-settings"
           className={`${sideButtonBase} ${activePanel === 'grader' ? sideButtonActive : sideButtonInactive}`}

From d152dc3eacd4f7a4f23c732a060eea3c12f29eb6 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 16:04:24 -0700
Subject: [PATCH 07/11] Add agent conversation composer and vault visibility
 controls

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 .../components/Agents/AgentMonitor.test.tsx   | 62 ++++++++++++++-
 app/src/components/Agents/AgentMonitor.tsx    | 72 ++++++++++++++++-
 .../KeyVault/KeyVaultPanel.test.tsx           | 25 ++++++
 app/src/components/KeyVault/KeyVaultPanel.tsx | 72 ++++++++---------
 app/src/components/SecretInput.tsx            | 64 +++++++++++++++
 app/src/components/SidePanel/SidePanel.tsx    |  3 +-
 app/src/lib/agents/monitor.test.ts            | 77 +++++++++++++++++++
 app/src/lib/agents/monitor.ts                 | 64 +++++++++++++++
 app/src/lib/agents/transport.test.ts          | 45 ++++++++++-
 app/src/lib/agents/transport.ts               | 35 ++++++++-
 app/src/lib/agents/types.ts                   |  6 ++
 docs-dev/CUJs/agent-monitor.md                |  2 +
 docs-dev/design/20261003_agents_api_ui.md     | 10 ++-
 docs-dev/style.md                             |  8 ++
 docs/20-agent-monitors.md                     | 10 ++-
 docs/agent-monitors.json                      |  4 +-
 testing/fake-agents-server.go                 | 67 +++++++++++++++-
 17 files changed, 566 insertions(+), 60 deletions(-)
 create mode 100644 app/src/components/SecretInput.tsx

diff --git a/app/src/components/Agents/AgentMonitor.test.tsx b/app/src/components/Agents/AgentMonitor.test.tsx
index 00213c12..e478048c 100644
--- a/app/src/components/Agents/AgentMonitor.test.tsx
+++ b/app/src/components/Agents/AgentMonitor.test.tsx
@@ -1,15 +1,75 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
 import { AgentItemView, AgentMonitorOutput } from './AgentMonitor'
 import { resetAgentMonitors } from '../../lib/agents/runtime'
+import * as runtime from '../../lib/agents/runtime'
+import { AgentMonitor } from '../../lib/agents/monitor'
 
 afterEach(() => {
   cleanup()
   resetAgentMonitors()
   vi.unstubAllGlobals()
+  vi.restoreAllMocks()
 })
 describe('agent monitor rendering', () => {
+  it('supports multiline drafts, explicit send, failure retry, and disabled disconnected input', async () => {
+    const sendMessage = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('offline'))
+      .mockResolvedValue(undefined)
+    const descriptor = {
+      version: 1 as const,
+      id: 'composer',
+      sessionId: 'sess_composer',
+      pageSize: 50,
+    }
+    const model = new AgentMonitor(descriptor, () => ({
+      sendMessage,
+      session: async () => ({ status: 'idle' }),
+      items: async () => ({ data: [], has_more: false, last_id: null }),
+      turns: async () => ({ data: [], has_more: false, last_id: null }),
+      stream: async () => ({
+        close() {},
+        events: {
+          [Symbol.asyncIterator]: () => ({ next: () => new Promise(() => {}) }),
+        },
+      }),
+    }))
+    vi.spyOn(runtime, 'resolveAgentMonitor').mockReturnValue(model)
+    render(<AgentMonitorOutput value={JSON.stringify(descriptor)} />)
+    const input = screen.getByRole('textbox', {
+      name: 'Message the agent',
+    }) as HTMLTextAreaElement
+    fireEvent.change(input, { target: { value: 'Hello\nagent' } })
+    expect(
+      (
+        screen.getByRole('button', {
+          name: 'Send',
+        }) as HTMLButtonElement
+      ).disabled
+    ).toBe(true)
+    fireEvent.click(screen.getByRole('button', { name: 'Connect' }))
+    await waitFor(() => expect(model.getSnapshot().connection).toBe('live'))
+    fireEvent.keyDown(input, { key: 'Enter', shiftKey: true })
+    fireEvent.keyDown(input, { key: 'Enter', isComposing: true })
+    expect(sendMessage).not.toHaveBeenCalled()
+    fireEvent.keyDown(input, { key: 'Enter' })
+    await screen.findByRole('alert')
+    expect(input.value).toBe('Hello\nagent')
+    fireEvent.click(screen.getByRole('button', { name: 'Send' }))
+    await waitFor(() => expect(input.value).toBe(''))
+    expect(sendMessage.mock.calls[1][2]).toBe(sendMessage.mock.calls[0][2])
+    expect(screen.getByText('Message sent.')).toBeTruthy()
+    act(() => model.pause())
+  })
   it('renders Markdown tables and code without executing HTML or loading images', () => {
     const { container } = render(
       <AgentItemView
diff --git a/app/src/components/Agents/AgentMonitor.tsx b/app/src/components/Agents/AgentMonitor.tsx
index b4d5dea5..d6c1f497 100644
--- a/app/src/components/Agents/AgentMonitor.tsx
+++ b/app/src/components/Agents/AgentMonitor.tsx
@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+import { useEffect, useId, useMemo, useRef, useSyncExternalStore } from 'react'
+import { PaperAirplaneIcon } from '@heroicons/react/24/outline'
 import ReactMarkdown from 'react-markdown'
 import remarkGfm from 'remark-gfm'
 
@@ -98,6 +99,8 @@ function Monitor({ descriptor }: { descriptor: AgentMonitorDescriptor }) {
   const state = useSyncExternalStore(monitor.subscribe, monitor.getSnapshot)
   const viewport = useRef<HTMLDivElement>(null)
   const follow = useRef(true)
+  const composerId = useId()
+  const input = useRef<HTMLTextAreaElement>(null)
   useEffect(() => mountAgentMonitor(monitor), [monitor])
   useEffect(() => {
     if (!viewport.current) return
@@ -113,6 +116,13 @@ function Monitor({ descriptor }: { descriptor: AgentMonitorDescriptor }) {
   }
   const active =
     state.connection === 'live' || state.connection === 'connecting'
+  const canSend =
+    state.connection === 'live' && !state.sending && Boolean(state.draft.trim())
+  /** Follow the active conversation after acceptance; failures preserve the draft. */
+  const send = async () => {
+    if (await monitor.sendMessage()) latest()
+    input.current?.focus()
+  }
   return (
     <section
       aria-label="Agent session monitor"
@@ -212,6 +222,66 @@ function Monitor({ descriptor }: { descriptor: AgentMonitorDescriptor }) {
           <AgentItemView key={item.id ?? `legacy-${index}`} item={item} />
         ))}
       </div>
+      <form
+        id={`agent-composer-${composerId}`}
+        aria-label="Send a message to the agent"
+        className="mt-3 rounded-nb-sm border border-nb-border bg-nb-surface-2 p-3"
+        onSubmit={(event) => {
+          event.preventDefault()
+          if (canSend) void send()
+        }}
+      >
+        <label htmlFor={composerId} className="mb-2 block text-sm font-medium">
+          Message the agent
+        </label>
+        <textarea
+          id={composerId}
+          ref={input}
+          value={state.draft}
+          readOnly={state.sending}
+          rows={3}
+          placeholder="Send a message to this conversation…"
+          aria-describedby={`${composerId}-hint`}
+          className="w-full resize-y rounded-nb-sm border border-nb-border bg-nb-surface px-3 py-2 text-sm text-nb-text focus:outline-none focus:ring-2 focus:ring-blue-500"
+          onChange={(event) => monitor.setDraft(event.target.value)}
+          onKeyDown={(event) => {
+            event.stopPropagation()
+            if (
+              event.key === 'Enter' &&
+              !event.shiftKey &&
+              !event.nativeEvent.isComposing
+            ) {
+              event.preventDefault()
+              if (canSend) void send()
+            }
+          }}
+        />
+        <div className="mt-2 flex items-center justify-between gap-3">
+          <p id={`${composerId}-hint`} className="text-xs text-nb-text-muted">
+            {state.connection !== 'live'
+              ? 'Connect or resume monitoring to send.'
+              : 'Enter to send · Shift+Enter for a new line'}
+          </p>
+          <button
+            type="submit"
+            disabled={!canSend}
+            className="inline-flex items-center gap-2 rounded-nb-sm bg-blue-600 px-3 py-2 text-sm text-white disabled:opacity-40"
+          >
+            <PaperAirplaneIcon className="h-4 w-4" />
+            {state.sending ? 'Sending…' : 'Send'}
+          </button>
+        </div>
+        {state.sendError && (
+          <p role="alert" className="mt-2 text-sm text-red-600">
+            {state.sendError}
+          </p>
+        )}
+        {state.sendNotice && (
+          <p role="status" className="mt-2 text-sm text-nb-text-muted">
+            {state.sendNotice}
+          </p>
+        )}
+      </form>
       {Array.isArray(state.session?.required_actions) &&
         state.session.required_actions.length > 0 && (
           <Details
diff --git a/app/src/components/KeyVault/KeyVaultPanel.test.tsx b/app/src/components/KeyVault/KeyVaultPanel.test.tsx
index ee0abebc..edecd2b9 100644
--- a/app/src/components/KeyVault/KeyVaultPanel.test.tsx
+++ b/app/src/components/KeyVault/KeyVaultPanel.test.tsx
@@ -29,6 +29,20 @@ it('creates a vault, masks and clears key inputs, and removes keys with confirma
   fireEvent.change(screen.getByLabelText('Confirm passphrase'), {
     target: { value: 'long test passphrase' },
   })
+  fireEvent.click(screen.getByRole('button', { name: 'Show vault passphrase' }))
+  expect(
+    (screen.getByLabelText('Vault passphrase') as HTMLInputElement).type
+  ).toBe('text')
+  expect(
+    (screen.getByLabelText('Confirm passphrase') as HTMLInputElement).type
+  ).toBe('password')
+  fireEvent.click(
+    screen.getByRole('button', { name: 'Show confirm passphrase' })
+  )
+  expect(
+    (screen.getByLabelText('Confirm passphrase') as HTMLInputElement).type
+  ).toBe('text')
+  expect(vault.getSnapshot().status).toBe('new')
   fireEvent.click(screen.getByRole('button', { name: 'Create vault' }))
   await screen.findByRole('button', { name: 'Lock vault' })
   fireEvent.change(screen.getByLabelText('Key name'), {
@@ -37,9 +51,17 @@ it('creates a vault, masks and clears key inputs, and removes keys with confirma
   const input = screen.getByLabelText('Key value') as HTMLInputElement
   expect(input.type).toBe('password')
   fireEvent.change(input, { target: { value: 'test-secret' } })
+  fireEvent.click(screen.getByRole('button', { name: 'Show key value' }))
+  expect(input.type).toBe('text')
+  expect(input.value).toBe('test-secret')
+  expect(vault.getSnapshot().names).toEqual([])
+  fireEvent.click(screen.getByRole('button', { name: 'Hide key value' }))
+  expect(input.type).toBe('password')
+  fireEvent.click(screen.getByRole('button', { name: 'Show key value' }))
   fireEvent.click(screen.getByRole('button', { name: 'Save key' }))
   await screen.findByText('Key saved.')
   expect(input.value).toBe('')
+  expect(input.type).toBe('password')
   expect(localStorage.getItem(VAULT_STORAGE_KEY)).not.toContain('test-secret')
   fireEvent.click(screen.getByRole('button', { name: 'Delete openai-api' }))
   expect(vault.getSnapshot().names).toContain('openai-api')
@@ -50,4 +72,7 @@ it('creates a vault, masks and clears key inputs, and removes keys with confirma
   await waitFor(() =>
     expect(screen.getByRole('button', { name: 'Unlock vault' })).toBeTruthy()
   )
+  expect(
+    (screen.getByLabelText('Vault passphrase') as HTMLInputElement).type
+  ).toBe('password')
 })
diff --git a/app/src/components/KeyVault/KeyVaultPanel.tsx b/app/src/components/KeyVault/KeyVaultPanel.tsx
index 8f602cee..e35cba50 100644
--- a/app/src/components/KeyVault/KeyVaultPanel.tsx
+++ b/app/src/components/KeyVault/KeyVaultPanel.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState, useSyncExternalStore } from 'react'
 
 import { keyVault, type KeyVault } from '../../lib/keyvault/store'
+import SecretInput from '../SecretInput'
 
 const inputClass =
   'mt-1 w-full rounded-nb-sm border border-nb-border bg-nb-surface px-2 py-2 text-sm text-nb-text'
@@ -92,37 +93,27 @@ export default function KeyVaultPanel({
                 ? 'Create a vault with a passphrase. You will use it to unlock your keys after reopening Runme.'
                 : 'Unlock your saved keys for this tab.'}
             </p>
-            <label className="block text-sm">
-              Vault passphrase
-              <input
-                className={inputClass}
-                type="password"
-                autoComplete={
-                  snapshot.status === 'new'
-                    ? 'new-password'
-                    : 'current-password'
-                }
-                value={passphrase}
-                onChange={(e) => setPassphrase(e.target.value)}
-                required
-                disabled={busy}
-                minLength={snapshot.status === 'new' ? 12 : undefined}
-              />
-            </label>
+            <SecretInput
+              label="Vault passphrase"
+              autoComplete={
+                snapshot.status === 'new' ? 'new-password' : 'current-password'
+              }
+              value={passphrase}
+              onChange={(e) => setPassphrase(e.target.value)}
+              required
+              disabled={busy}
+              minLength={snapshot.status === 'new' ? 12 : undefined}
+            />
             {snapshot.status === 'new' && (
               <>
-                <label className="block text-sm">
-                  Confirm passphrase
-                  <input
-                    className={inputClass}
-                    type="password"
-                    autoComplete="new-password"
-                    value={confirmation}
-                    onChange={(e) => setConfirmation(e.target.value)}
-                    required
-                    disabled={busy}
-                  />
-                </label>
+                <SecretInput
+                  label="Confirm passphrase"
+                  autoComplete="new-password"
+                  value={confirmation}
+                  onChange={(e) => setConfirmation(e.target.value)}
+                  required
+                  disabled={busy}
+                />
                 <p className="text-xs text-nb-text-muted">
                   Use at least 12 characters. Keep the passphrase safe: Runme
                   cannot recover it. Clearing this site's browser data removes
@@ -264,19 +255,16 @@ export default function KeyVaultPanel({
                   onChange={(e) => setName(e.target.value)}
                 />
               </label>
-              <label className="block text-sm">
-                Key value
-                <input
-                  className={inputClass}
-                  type="password"
-                  value={value}
-                  required={!editing}
-                  disabled={busy}
-                  autoComplete="off"
-                  spellCheck={false}
-                  onChange={(e) => setValue(e.target.value)}
-                />
-              </label>
+              <SecretInput
+                key={editing ? `edit:${editing}` : 'new-key'}
+                label="Key value"
+                value={value}
+                required={!editing}
+                disabled={busy}
+                autoComplete="off"
+                spellCheck={false}
+                onChange={(e) => setValue(e.target.value)}
+              />
               {editing && (
                 <p className="text-xs text-nb-text-muted">
                   Leave the value empty to keep the existing key.
diff --git a/app/src/components/SecretInput.tsx b/app/src/components/SecretInput.tsx
new file mode 100644
index 00000000..579e5ca3
--- /dev/null
+++ b/app/src/components/SecretInput.tsx
@@ -0,0 +1,64 @@
+import { EyeIcon, EyeSlashIcon } from '@heroicons/react/24/outline'
+import { useEffect, useId, useState, type InputHTMLAttributes } from 'react'
+
+type SecretInputProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'type' | 'value'
+> & {
+  label: string
+  value: string
+}
+
+/** A controlled secret field with local, opt-in visibility; clearing resets masking. */
+export default function SecretInput({
+  label,
+  value,
+  id,
+  className = '',
+  disabled,
+  ...props
+}: SecretInputProps) {
+  const generatedId = useId()
+  const inputId = id ?? generatedId
+  const [visible, setVisible] = useState(false)
+  useEffect(() => {
+    if (!value || disabled) setVisible(false)
+  }, [value, disabled])
+  const action = `${visible ? 'Hide' : 'Show'} ${label.toLowerCase()}`
+  return (
+    <div id={`${inputId}-field`}>
+      <label htmlFor={inputId} className="block text-sm">
+        {label}
+      </label>
+      <div id={`${inputId}-control`} className="relative mt-1">
+        <input
+          {...props}
+          id={inputId}
+          value={value}
+          disabled={disabled}
+          type={visible ? 'text' : 'password'}
+          spellCheck={false}
+          autoCapitalize="none"
+          autoCorrect="off"
+          className={`w-full rounded-nb-sm border border-nb-border bg-nb-surface py-2 pl-2 pr-10 text-sm text-nb-text ${className}`}
+        />
+        <button
+          type="button"
+          aria-label={action}
+          title={action}
+          aria-pressed={visible}
+          aria-controls={inputId}
+          disabled={disabled}
+          className="absolute inset-y-0 right-0 flex w-10 items-center justify-center rounded-nb-sm text-nb-text-muted hover:text-nb-text focus-visible:outline focus-visible:outline-2 focus-visible:outline-blue-500 disabled:opacity-40"
+          onClick={() => setVisible((current) => !current)}
+        >
+          {visible ? (
+            <EyeSlashIcon className="h-5 w-5" />
+          ) : (
+            <EyeIcon className="h-5 w-5" />
+          )}
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/app/src/components/SidePanel/SidePanel.tsx b/app/src/components/SidePanel/SidePanel.tsx
index 001eafbf..766700bf 100644
--- a/app/src/components/SidePanel/SidePanel.tsx
+++ b/app/src/components/SidePanel/SidePanel.tsx
@@ -9,12 +9,11 @@ import {
   QueueListIcon,
   ServerStackIcon,
   UserCircleIcon,
-  KeyIcon,
   Cog6ToothIcon,
   SparklesIcon,
 } from '@heroicons/react/24/outline'
 import { XMarkIcon } from '@heroicons/react/20/solid'
-import { CloudIcon as CloudSolidIcon } from '@heroicons/react/24/solid'
+import { CloudIcon as CloudSolidIcon, KeyIcon } from '@heroicons/react/24/solid'
 import {
   useCallback,
   useEffect,
diff --git a/app/src/lib/agents/monitor.test.ts b/app/src/lib/agents/monitor.test.ts
index 28c14628..097ebefc 100644
--- a/app/src/lib/agents/monitor.test.ts
+++ b/app/src/lib/agents/monitor.test.ts
@@ -28,6 +28,7 @@ function setup(overrides: Partial<AgentTransport> = {}) {
   const queued: AgentEvent[] = []
   const close = vi.fn(() => deliver?.({ done: true, value: undefined }))
   const transport: AgentTransport = {
+    sendMessage: vi.fn(async () => {}),
     session: vi.fn(async () => ({ status: 'idle' })),
     items: vi.fn(async () => page(['b', 'a'], true)),
     turns: vi.fn(async () => ({
@@ -72,6 +73,82 @@ function setup(overrides: Partial<AgentTransport> = {}) {
 }
 
 describe('AgentMonitor', () => {
+  it('keeps failed submissions retryable without duplication and requires live observation', async () => {
+    const sendMessage = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('lost response'))
+      .mockResolvedValue(undefined)
+    const { model, transport } = setup({ sendMessage })
+    model.setDraft('Hello\nagent')
+    expect(await model.sendMessage()).toBe(false)
+    expect(sendMessage).not.toHaveBeenCalled()
+    await model.connect()
+    expect(await model.sendMessage()).toBe(false)
+    expect(model.getSnapshot().draft).toBe('Hello\nagent')
+    expect(model.getSnapshot().sendError).toContain('Could not confirm')
+    await model.connect()
+    expect(sendMessage).toHaveBeenCalledTimes(1)
+    expect(await model.sendMessage()).toBe(true)
+    expect(sendMessage.mock.calls[0].slice(0, 3)).toEqual(
+      sendMessage.mock.calls[1].slice(0, 3)
+    )
+    expect(sendMessage.mock.calls[0][0]).toBe('sess_test')
+    expect(transport.stream).toHaveBeenCalled()
+    expect(model.getSnapshot().draft).toBe('')
+    model.setDraft('Hello\nagent')
+    await model.sendMessage()
+    expect(sendMessage.mock.calls[2][2]).not.toBe(sendMessage.mock.calls[1][2])
+  })
+
+  it('prevents double sends, preserves input and aborts pending delivery when paused', async () => {
+    let signal: AbortSignal | undefined
+    const sendMessage = vi.fn(
+      (_id, _text, _key, requestSignal: AbortSignal) =>
+        new Promise<void>((_resolve, reject) => {
+          signal = requestSignal
+          signal.addEventListener('abort', () => reject(new Error('aborted')))
+        })
+    )
+    const { model } = setup({ sendMessage })
+    await model.connect()
+    model.setDraft('  ')
+    expect(await model.sendMessage()).toBe(false)
+    model.setDraft('Keep this draft')
+    const pending = model.sendMessage()
+    expect(model.getSnapshot().sending).toBe(true)
+    expect(await model.sendMessage()).toBe(false)
+    model.setDraft('ignored while sending')
+    model.pause()
+    expect(await pending).toBe(false)
+    expect(signal?.aborted).toBe(true)
+    expect(sendMessage).toHaveBeenCalledTimes(1)
+    expect(model.getSnapshot()).toMatchObject({
+      draft: 'Keep this draft',
+      sending: false,
+    })
+  })
+
+  it('times out uncertain sends and reuses the submission ID after a timeout', async () => {
+    vi.useFakeTimers()
+    const sendMessage = vi
+      .fn()
+      .mockImplementationOnce(
+        (_id, _text, _key, signal: AbortSignal) =>
+          new Promise<void>((_resolve, reject) => {
+            signal.addEventListener('abort', () => reject(new Error('timeout')))
+          })
+      )
+      .mockResolvedValue(undefined)
+    const { model } = setup({ sendMessage })
+    await model.connect()
+    model.setDraft('hello')
+    const sending = model.sendMessage()
+    await vi.advanceTimersByTimeAsync(30_000)
+    expect(await sending).toBe(false)
+    await model.sendMessage()
+    expect(sendMessage.mock.calls[0][2]).toBe(sendMessage.mock.calls[1][2])
+  })
+
   it('does not regress final items or root turns when older events arrive', async () => {
     const { model } = setup()
     await model.connect()
diff --git a/app/src/lib/agents/monitor.ts b/app/src/lib/agents/monitor.ts
index 85c8a02d..a877c7c4 100644
--- a/app/src/lib/agents/monitor.ts
+++ b/app/src/lib/agents/monitor.ts
@@ -20,6 +20,10 @@ export type MonitorSnapshot = {
   newActivity: number
   loadingPage: boolean
   error: string | null
+  draft: string
+  sending: boolean
+  sendError: string | null
+  sendNotice: string | null
 }
 const finalStatuses = new Set([
   'completed',
@@ -48,6 +52,10 @@ export class AgentMonitor {
     newActivity: 0,
     loadingPage: false,
     error: null,
+    draft: '',
+    sending: false,
+    sendError: null,
+    sendNotice: null,
   }
   private listeners = new Set<() => void>()
   private controller?: AbortController
@@ -62,6 +70,7 @@ export class AgentMonitor {
   private finalParts = new Set<string>()
   private restoredFinalIds = new Set<string>()
   private refreshTimer?: ReturnType<typeof setTimeout>
+  private pendingSubmission?: { text: string; id: string }
 
   constructor(
     readonly descriptor: AgentMonitorDescriptor,
@@ -78,6 +87,61 @@ export class AgentMonitor {
     this.listeners.forEach((listener) => listener())
   }
 
+  /** Drafts and retry IDs stay in this controller, never in saved notebook output. */
+  setDraft = (draft: string) => {
+    if (!this.snapshot.sending) this.update({ draft, sendNotice: null })
+  }
+
+  /** A retry reuses the logical submission ID; reconnecting never resends input. */
+  sendMessage = async (): Promise<boolean> => {
+    const text = this.snapshot.draft
+    if (this.snapshot.sending || !text.trim()) return false
+    if (
+      this.snapshot.connection !== 'live' ||
+      !this.controller ||
+      this.controller.signal.aborted
+    ) {
+      this.update({
+        sendError: 'Connect or resume monitoring before sending a message.',
+      })
+      return false
+    }
+    if (this.pendingSubmission?.text !== text)
+      this.pendingSubmission = { text, id: crypto.randomUUID() }
+    const submission = this.pendingSubmission
+    const observation = this.controller.signal
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+    observation.addEventListener('abort', abort, { once: true })
+    const timeout = setTimeout(abort, 30_000)
+    this.update({ sending: true, sendError: null, sendNotice: null })
+    try {
+      await this.transport().sendMessage(
+        this.descriptor.sessionId,
+        submission.text,
+        submission.id,
+        controller.signal
+      )
+      this.pendingSubmission = undefined
+      this.update({ draft: '', sendNotice: 'Message sent.' })
+      this.latest()
+      // Hydrate the accepted user item even if the stream only reports agent output.
+      this.scheduleRefresh()
+      return true
+    } catch {
+      // Acceptance is uncertain after a network failure. Keep both text and retry ID.
+      this.update({
+        sendError:
+          'Could not confirm delivery. Your draft is kept. Retry unchanged to avoid duplicates; editing sends a new message.',
+      })
+      return false
+    } finally {
+      clearTimeout(timeout)
+      observation.removeEventListener('abort', abort)
+      this.update({ sending: false })
+    }
+  }
+
   /** Stop observation only. Never sends a cancel or other input event. */
   pause = () => {
     this.controller?.abort()
diff --git a/app/src/lib/agents/transport.test.ts b/app/src/lib/agents/transport.test.ts
index f27ba80a..eaa20279 100644
--- a/app/src/lib/agents/transport.test.ts
+++ b/app/src/lib/agents/transport.test.ts
@@ -4,6 +4,45 @@ import { createAgentTransport, readAgentEvents } from './transport'
 
 afterEach(() => vi.unstubAllGlobals())
 describe('agent transport', () => {
+  it('posts user text to session events with fresh auth and a stable idempotency header', async () => {
+    const fetch = vi.fn(async () => new Response(null, { status: 204 }))
+    vi.stubGlobal('fetch', fetch)
+    const getHeaders = vi.fn(() => ({ Authorization: 'Bearer test-secret' }))
+    const api = createAgentTransport({
+      baseUrl: 'https://api.openai.com/v1',
+      getHeaders,
+    })
+    await api.sendMessage(
+      'sess/1',
+      'hello\nworld',
+      'submission-1',
+      new AbortController().signal
+    )
+    const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit]
+    expect(url).toBe(
+      'https://api.openai.com/v1/agents/sessions/sess%2F1/events'
+    )
+    expect(init.method).toBe('POST')
+    expect(new Headers(init.headers).get('Idempotency-Key')).toBe(
+      'submission-1'
+    )
+    expect(new Headers(init.headers).get('Authorization')).toBe(
+      'Bearer test-secret'
+    )
+    expect(JSON.parse(init.body as string)).toEqual({
+      events: [
+        {
+          type: 'agent.session.input.message',
+          input: [
+            {
+              role: 'user',
+              content: [{ type: 'input_text', text: 'hello\nworld' }],
+            },
+          ],
+        },
+      ],
+    })
+  })
   it('decodes split UTF-8, CRLF, comments and multiline SSE data', async () => {
     const bytes = new TextEncoder().encode(
       ': heartbeat\r\ndata: {"type":"test",\r\ndata: "text":"👋"}\r\n\r\ndata: [DONE]\n\n'
@@ -19,9 +58,9 @@ describe('agent transport', () => {
     expect(events).toEqual([{ type: 'test', text: '👋' }])
   })
   it('requests bounded descending pages with encoded cursors and refreshed headers', async () => {
-    const fetch = vi.fn<(url: string, options?: RequestInit) => Promise<Response>>(
-      async () => new Response(JSON.stringify({ data: [] }))
-    )
+    const fetch = vi.fn<
+      (url: string, options?: RequestInit) => Promise<Response>
+    >(async () => new Response(JSON.stringify({ data: [] })))
     vi.stubGlobal('fetch', fetch)
     const getHeaders = vi.fn(() => ({ Authorization: 'Bearer secret' }))
     const api = createAgentTransport({
diff --git a/app/src/lib/agents/transport.ts b/app/src/lib/agents/transport.ts
index 05e2b5c4..c2a852c6 100644
--- a/app/src/lib/agents/transport.ts
+++ b/app/src/lib/agents/transport.ts
@@ -53,7 +53,7 @@ export async function* readAgentEvents(
   }
 }
 
-/** Read-only REST/SSE transport. Secrets remain in the caller's header provider. */
+/** REST/SSE transport. Secrets remain in the caller's header provider. */
 export function createAgentTransport(
   options: AgentConnectionOptions
 ): AgentTransport {
@@ -73,11 +73,36 @@ export function createAgentTransport(
     )
   }
   const root = base.href.replace(/\/$/, '')
-  const request = async (path: string, signal: AbortSignal, stream = false) => {
+  const request = async (
+    path: string,
+    signal: AbortSignal,
+    stream = false,
+    submission?: { text: string; id: string }
+  ) => {
     const headers = new Headers(await options.getHeaders?.())
     headers.set('OpenAI-Beta', 'agents=v1')
     headers.set('Accept', stream ? 'text/event-stream' : 'application/json')
+    if (submission) {
+      headers.set('Content-Type', 'application/json')
+      headers.set('Idempotency-Key', submission.id)
+    }
     const response = await fetch(`${root}/agents/sessions/${path}`, {
+      method: submission ? 'POST' : 'GET',
+      body: submission
+        ? JSON.stringify({
+            events: [
+              {
+                type: 'agent.session.input.message',
+                input: [
+                  {
+                    role: 'user',
+                    content: [{ type: 'input_text', text: submission.text }],
+                  },
+                ],
+              },
+            ],
+          })
+        : undefined,
       headers,
       signal,
       credentials: 'same-origin',
@@ -94,6 +119,12 @@ export function createAgentTransport(
   const json = async <T>(path: string, signal: AbortSignal): Promise<T> =>
     (await request(path, signal)).json()
   return {
+    sendMessage: async (id, text, submissionId, signal) => {
+      await request(`${encodeURIComponent(id)}/events`, signal, false, {
+        text,
+        id: submissionId,
+      })
+    },
     session: (id, signal) => json<AgentObject>(encodeURIComponent(id), signal),
     items: (id, limit, after, signal) => {
       const query = new URLSearchParams({ order: 'desc', limit: String(limit) })
diff --git a/app/src/lib/agents/types.ts b/app/src/lib/agents/types.ts
index f958c38c..e44fc2c0 100644
--- a/app/src/lib/agents/types.ts
+++ b/app/src/lib/agents/types.ts
@@ -20,6 +20,12 @@ export type AgentStream = {
   close(): void
 }
 export interface AgentTransport {
+  sendMessage(
+    id: string,
+    text: string,
+    submissionId: string,
+    signal: AbortSignal
+  ): Promise<void>
   session(id: string, signal: AbortSignal): Promise<AgentObject>
   items(
     id: string,
diff --git a/docs-dev/CUJs/agent-monitor.md b/docs-dev/CUJs/agent-monitor.md
index 9fb02c5e..69e8ac2d 100644
--- a/docs-dev/CUJs/agent-monitor.md
+++ b/docs-dev/CUJs/agent-monitor.md
@@ -12,6 +12,8 @@ Start the Go fixture with `go run testing/fake-agents-server.go` and Runme at `h
 4. Toggle Edit then Render. Assert source is visible only in Edit and the existing monitor remains mounted; neither operation executes the cell.
 5. Pause via `agents.pause(widgetId)`. Assert connection is paused and items remain readable. Resume via `await agents.resume(widgetId)` and assert live state returns.
 6. Reload the browser. The saved widget is disconnected, requires Connect, and does not contain credentials or serialized messages. Configure the connection in a new execution before connecting.
+7. In Render, type a multiline message into **Message the agent**. Shift+Enter must not submit; Enter or Send submits one request. The Go fixture echoes a synthetic reply. Verify the draft clears only after acceptance, both the user message and reply appear, and history returns to Latest.
+8. Pause monitoring: the composer retains its draft but Send is disabled. Resume and send. Controller/component tests verify failed delivery preserves the draft, unchanged retries reuse the idempotency key, double sends are blocked, composition Enter does not submit, and reconnect does not resend. Do not send test messages to a real agent session.
 
 Capture the rendered monitor with notebook context and record assertions. Controller/component tests cover root/subagent completion, replay races, EOF, safe Markdown, malformed descriptors and pagination. NotebookData tests cover browser and sandbox output. The Go fixture drives the manual WebMCP browser CUJ; it is not registered in the automated browser orchestrator yet.
 
diff --git a/docs-dev/design/20261003_agents_api_ui.md b/docs-dev/design/20261003_agents_api_ui.md
index 7815a5e2..42599b86 100644
--- a/docs-dev/design/20261003_agents_api_ui.md
+++ b/docs-dev/design/20261003_agents_api_ui.md
@@ -12,7 +12,13 @@ agents.monitor(session_id, { pageSize: 50 })
 
 The cell has Edit and Render modes. Edit shows the source; Render shows the monitor. Running the cell creates the widget and returns immediately. The cell execution finishing does not mean the agent turn finished. Editing does not execute code or cancel the agent. Rerunning replaces the old monitor.
 
-Keep agent creation, sending messages, and cancellation in explicit code cells. The first version is a read-only monitor; it never submits a message, approves a request, or cancels a turn as a side effect of reconnecting. A composer and approval forms can follow once their semantics are designed.
+Keep agent creation, tool approvals, and cancellation in explicit code cells. The rendered conversation includes a message composer. Sending is explicit; connecting, rerunning, or reopening never sends a message.
+
+Use **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.
+
+The composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; retry unchanged to reuse its submission ID and avoid duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.
+
+
 
 ## Current state
 
@@ -103,7 +109,7 @@ Test SSE framing across chunk boundaries, HTTP errors, abort cleanup, root/subag
 
 ## Follow-ups
 
-A deployable proxy or runner-backed adapter can bridge the existing local credential workflow. Other follow-ups are explicit send/cancel helpers, request-specific approval forms, subagent drill-down, durable snapshots for offline viewing, and a shared subscription per session. The first version makes each monitor independent so one cell's controls do not affect another.
+A deployable proxy or runner-backed adapter can bridge the existing local credential workflow. Other follow-ups are explicit cancellation helpers, request-specific approval forms, subagent drill-down, durable snapshots for offline viewing, and a shared subscription per session. The first version makes each monitor independent so one cell's controls do not affect another.
 
 ## References
 
diff --git a/docs-dev/style.md b/docs-dev/style.md
index 3aeedef5..0d00c04c 100644
--- a/docs-dev/style.md
+++ b/docs-dev/style.md
@@ -54,3 +54,11 @@ For CUJ/browser scripts:
 - Default format for Runme documentation notebooks is JSON notebook files (for example `docs/<name>.json`), not markdown `.runme.md`.
 - When adding notebook-based walkthroughs under `docs/`, create/update the JSON notebook directly.
 - Use markdown cells inside the JSON notebook for narrative instructions and code cells for runnable steps.
+
+## Secret input pattern
+
+- Use `app/src/components/SecretInput.tsx` for passwords, vault passphrases, API keys, tokens, and other single-line secret entry fields in new or changed UI.
+- Mask by default with `type="password"`. Include a right-aligned eye button to show the text and a crossed-out eye to hide it again. Keep enough input padding so the button never covers the value.
+- Give each field a visible label. The toggle must be keyboard accessible, use `type="button"` so it cannot submit a form, and announce a field-specific action (for example, “Show key value” / “Hide key value”) with `aria-pressed` and `aria-controls`.
+- Visibility is local to each field. Clear or unmount the input to reset masking; reset it when switching records or completing a form. Never persist the visibility choice, log the value, or copy it into notebook output. Revealing affects presentation only, not vault encryption or storage.
+- Disable spelling corrections and capitalization for secrets; preserve the appropriate password-manager autocomplete value. Do not populate a saved secret solely to support reveal: the toggle reveals only the value already being entered.
diff --git a/docs/20-agent-monitors.md b/docs/20-agent-monitors.md
index a512b011..be6d00b9 100644
--- a/docs/20-agent-monitors.md
+++ b/docs/20-agent-monitors.md
@@ -9,7 +9,7 @@ order: 20
 
 Use an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.
 
-Open **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Key values are masked and never included in notebook files or Drive sync.
+Open **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Visibility resets when the field is cleared or closed. Key values are never included in notebook files or Drive sync.
 
 The vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.
 
@@ -32,10 +32,16 @@ For an application-owned proxy, advanced browser code may still use `agents.conf
 
 **Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.
 
-Saved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit responses, new messages, or cancellation through your agent client.
+Saved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit tool results or cancellation through your agent client.
 
 Runtime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.
 
+## Send a message
+
+Use **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.
+
+The composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; retry unchanged to reuse its submission ID and avoid duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.
+
 ## Synthetic local demo
 
 Start `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.
diff --git a/docs/agent-monitors.json b/docs/agent-monitors.json
index cf308832..17b95bcb 100644
--- a/docs/agent-monitors.json
+++ b/docs/agent-monitors.json
@@ -3,7 +3,7 @@
     {
       "kind": 1,
       "languageId": "markdown",
-      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Key values are masked and never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS \u2192 browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
+      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Visibility resets when the field is cleared or closed. Key values are never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS → browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
       "refId": "0a152c34fb9e412d95c68cec16074052",
       "metadata": {}
     },
@@ -19,7 +19,7 @@
     {
       "kind": 1,
       "languageId": "markdown",
-      "value": "## Read and monitor\n\n**Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.\n\n**Older** and **Newer** page through saved items, with at most the configured page size visible. **Latest** returns to the live window. New output never replaces an older page while you read it. Scroll to the live bottom to follow incoming output automatically.\n\n**Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.\n\nSaved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit responses, new messages, or cancellation through your agent client.\n\nRuntime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.\n\n## Synthetic local demo\n\nStart `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.\n",
+      "value": "## Read and monitor\n\n**Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.\n\n**Older** and **Newer** page through saved items, with at most the configured page size visible. **Latest** returns to the live window. New output never replaces an older page while you read it. Scroll to the live bottom to follow incoming output automatically.\n\n**Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.\n\nSaved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit tool results or cancellation through your agent client.\n\nRuntime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.\n\n## Send a message\n\nUse **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.\n\nThe composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; retry unchanged to reuse its submission ID and avoid duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.\n\n## Synthetic local demo\n\nStart `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.\n\n",
       "refId": "002946c0829a4f3ab899510f2563b819",
       "metadata": {}
     }
diff --git a/testing/fake-agents-server.go b/testing/fake-agents-server.go
index b7251ed6..63b8d081 100644
--- a/testing/fake-agents-server.go
+++ b/testing/fake-agents-server.go
@@ -1,4 +1,4 @@
-// Local read-only Agents API fixture for the agent-monitor CUJ.
+// Local Agents API fixture for the agent-monitor and message composer CUJ.
 // Run: go run testing/fake-agents-server.go
 package main
 
@@ -9,9 +9,59 @@ import (
 	"net/http"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 )
 
+var demoMu sync.Mutex
+var demoMessages = map[int]map[string]any{}
+var demoSubmissions = map[string]string{}
+
+// acceptDemoMessage persists synthetic user/reply items and deduplicates retries.
+func acceptDemoMessage(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Events []struct {
+			Type  string `json:"type"`
+			Input []struct {
+				Role    string `json:"role"`
+				Content []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				} `json:"content"`
+			} `json:"input"`
+		} `json:"events"`
+	}
+	if json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&body) != nil || len(body.Events) != 1 || body.Events[0].Type != "agent.session.input.message" || len(body.Events[0].Input) != 1 || len(body.Events[0].Input[0].Content) != 1 {
+		http.Error(w, "Invalid input event", http.StatusBadRequest)
+		return
+	}
+	text := body.Events[0].Input[0].Content[0].Text
+	key := r.Header.Get("Idempotency-Key")
+	if key == "" || strings.TrimSpace(text) == "" {
+		http.Error(w, "Message and key required", http.StatusBadRequest)
+		return
+	}
+	demoMu.Lock()
+	defer demoMu.Unlock()
+	if previous, exists := demoSubmissions[key]; exists {
+		if previous != text {
+			http.Error(w, "Idempotency conflict", http.StatusConflict)
+			return
+		}
+	} else {
+		demoSubmissions[key] = text
+		for _, message := range []struct{ role, text string }{{"user", text}, {"assistant", "Received your message: " + text}} {
+			id := 126 + len(demoMessages)
+			contentType := "output_text"
+			if message.role == "user" {
+				contentType = "input_text"
+			}
+			demoMessages[id] = map[string]any{"id": fmt.Sprintf("msg_%d", id), "type": "message", "role": message.role, "status": "completed", "content": []map[string]any{{"type": contentType, "text": message.text}}}
+		}
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
 // main serves synthetic history and an SSE stream on loopback only.
 func main() {
 	http.HandleFunc("/v1/agents/sessions/sess_demo", serveAgentDemo)
@@ -23,12 +73,17 @@ func serveAgentDemo(w http.ResponseWriter, r *http.Request) {
 	origin := r.Header.Get("Origin")
 	if origin == "http://127.0.0.1:5173" || origin == "http://localhost:5173" {
 		w.Header().Set("Access-Control-Allow-Origin", origin)
-		w.Header().Set("Access-Control-Allow-Headers", "OpenAI-Beta")
+		w.Header().Set("Access-Control-Allow-Headers", "OpenAI-Beta, Content-Type, Idempotency-Key")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
 	}
 	if r.Method == "OPTIONS" {
 		w.WriteHeader(http.StatusNoContent)
 		return
 	}
+	if r.Method == "POST" && strings.HasSuffix(r.URL.Path, "/events") {
+		acceptDemoMessage(w, r)
+		return
+	}
 	if r.Method != "GET" {
 		http.Error(w, "Read only", http.StatusMethodNotAllowed)
 		return
@@ -54,11 +109,13 @@ func serveAgentDemo(w http.ResponseWriter, r *http.Request) {
 			}
 		}
 	case strings.HasSuffix(r.URL.Path, "/items"):
+		demoMu.Lock()
+		defer demoMu.Unlock()
 		limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))
 		if limit < 1 || limit > 100 {
 			limit = 50
 		}
-		start := 125
+		start := 125 + len(demoMessages)
 		if after := r.URL.Query().Get("after"); after != "" {
 			if after == "msg_live" {
 				start = 125
@@ -69,6 +126,10 @@ func serveAgentDemo(w http.ResponseWriter, r *http.Request) {
 		}
 		data := []map[string]any{}
 		for i := start; i > 0 && len(data) < limit; i-- {
+			if saved, ok := demoMessages[i]; ok {
+				data = append(data, saved)
+				continue
+			}
 			text := fmt.Sprintf("Saved message **%d**.\n\n| Check | Result |\n|---|---|\n| API request | Passed |", i)
 			row := map[string]any{"id": fmt.Sprintf("msg_%d", i), "type": "message", "role": "assistant", "phase": "final_answer", "status": "completed", "content": []map[string]any{{"type": "output_text", "text": text}}}
 			if i%5 == 0 {

From b984aaff4584b8e32b8a94a5228ed9021f519e4a Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 16:09:34 -0700
Subject: [PATCH 08/11] Populate current secret when editing vault keys

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 .../KeyVault/KeyVaultPanel.test.tsx           | 34 +++++++++++++++++++
 app/src/components/KeyVault/KeyVaultPanel.tsx | 25 ++++++++++----
 app/src/lib/keyvault/store.ts                 |  2 +-
 docs-dev/style.md                             |  2 +-
 docs/20-agent-monitors.md                     |  2 +-
 docs/agent-monitors.json                      |  2 +-
 6 files changed, 56 insertions(+), 11 deletions(-)

diff --git a/app/src/components/KeyVault/KeyVaultPanel.test.tsx b/app/src/components/KeyVault/KeyVaultPanel.test.tsx
index edecd2b9..f0529b27 100644
--- a/app/src/components/KeyVault/KeyVaultPanel.test.tsx
+++ b/app/src/components/KeyVault/KeyVaultPanel.test.tsx
@@ -20,6 +20,40 @@ afterEach(() => {
   vi.unstubAllGlobals()
 })
 
+it('loads saved values into a masked editor and clears drafts on cancel or lock', async () => {
+  const vault = new KeyVault()
+  await vault.unlock('long test passphrase', true)
+  await vault.saveKey('openai-api', 'saved-test-key')
+  render(<KeyVaultPanel vault={vault} />)
+  const valueInput = () =>
+    screen.getByLabelText('Key value') as HTMLInputElement
+
+  fireEvent.click(screen.getByRole('button', { name: 'Edit openai-api' }))
+  expect(valueInput().value).toBe('saved-test-key')
+  expect(valueInput().type).toBe('password')
+  fireEvent.click(screen.getByRole('button', { name: 'Show key value' }))
+  expect(valueInput().type).toBe('text')
+  fireEvent.click(screen.getByRole('button', { name: 'Edit openai-api' }))
+  expect(valueInput().value).toBe('saved-test-key')
+  expect(valueInput().type).toBe('password')
+
+  fireEvent.change(valueInput(), { target: { value: 'replacement-test-key' } })
+  fireEvent.click(screen.getByRole('button', { name: 'Save key' }))
+  await screen.findByText('Key saved.')
+  expect(vault.requireValue('openai-api')).toBe('replacement-test-key')
+  expect(valueInput().value).toBe('')
+  fireEvent.click(screen.getByRole('button', { name: 'Edit openai-api' }))
+  expect(valueInput().value).toBe('replacement-test-key')
+  fireEvent.click(screen.getByRole('button', { name: 'Cancel edit' }))
+  expect(valueInput().value).toBe('')
+  fireEvent.click(screen.getByRole('button', { name: 'Edit openai-api' }))
+  fireEvent.click(screen.getByRole('button', { name: 'Lock vault' }))
+  expect(screen.queryByLabelText('Key value')).toBeNull()
+  expect(localStorage.getItem(VAULT_STORAGE_KEY)).not.toContain(
+    'replacement-test-key'
+  )
+})
+
 it('creates a vault, masks and clears key inputs, and removes keys with confirmation', async () => {
   const vault = new KeyVault()
   render(<KeyVaultPanel vault={vault} />)
diff --git a/app/src/components/KeyVault/KeyVaultPanel.tsx b/app/src/components/KeyVault/KeyVaultPanel.tsx
index e35cba50..31e817f0 100644
--- a/app/src/components/KeyVault/KeyVaultPanel.tsx
+++ b/app/src/components/KeyVault/KeyVaultPanel.tsx
@@ -20,6 +20,7 @@ export default function KeyVaultPanel({
   const [name, setName] = useState('')
   const [value, setValue] = useState('')
   const [editing, setEditing] = useState<string>()
+  const [editGeneration, setEditGeneration] = useState(0)
   const [deleting, setDeleting] = useState<string>()
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState('')
@@ -163,12 +164,22 @@ export default function KeyVaultPanel({
                       disabled={busy}
                       aria-label={`Edit ${key}`}
                       onClick={() => {
-                        setName(key)
-                        setValue('')
-                        setEditing(key)
-                        setDeleting(undefined)
-                        setError('')
-                        setNotice('')
+                        try {
+                          // Only the trusted, unlocked editor receives the current secret.
+                          const currentValue = vault.requireValue(key)
+                          setName(key)
+                          setValue(currentValue)
+                          setEditing(key)
+                          // Reopening even the same key starts with a masked input.
+                          setEditGeneration((generation) => generation + 1)
+                          setDeleting(undefined)
+                          setError('')
+                          setNotice('')
+                        } catch {
+                          setError(
+                            'Unable to read this key. Unlock the vault and try again.'
+                          )
+                        }
                       }}
                     >
                       Edit
@@ -256,7 +267,7 @@ export default function KeyVaultPanel({
                 />
               </label>
               <SecretInput
-                key={editing ? `edit:${editing}` : 'new-key'}
+                key={editing ? `edit:${editing}:${editGeneration}` : 'new-key'}
                 label="Key value"
                 value={value}
                 required={!editing}
diff --git a/app/src/lib/keyvault/store.ts b/app/src/lib/keyvault/store.ts
index 53462840..bc23d2be 100644
--- a/app/src/lib/keyvault/store.ts
+++ b/app/src/lib/keyvault/store.ts
@@ -275,7 +275,7 @@ export class KeyVault {
     return reference
   }
 
-  /** Internal transport access checks lock state and deletion on every request. */
+  /** Trusted transport/editor access checks lock state and deletion on every read. */
   requireValue(name: string): string {
     if (!this.key)
       throw new Error('Unlock Key Vault in the left navigation first.')
diff --git a/docs-dev/style.md b/docs-dev/style.md
index 0d00c04c..6dbb356a 100644
--- a/docs-dev/style.md
+++ b/docs-dev/style.md
@@ -61,4 +61,4 @@ For CUJ/browser scripts:
 - Mask by default with `type="password"`. Include a right-aligned eye button to show the text and a crossed-out eye to hide it again. Keep enough input padding so the button never covers the value.
 - Give each field a visible label. The toggle must be keyboard accessible, use `type="button"` so it cannot submit a form, and announce a field-specific action (for example, “Show key value” / “Hide key value”) with `aria-pressed` and `aria-controls`.
 - Visibility is local to each field. Clear or unmount the input to reset masking; reset it when switching records or completing a form. Never persist the visibility choice, log the value, or copy it into notebook output. Revealing affects presentation only, not vault encryption or storage.
-- Disable spelling corrections and capitalization for secrets; preserve the appropriate password-manager autocomplete value. Do not populate a saved secret solely to support reveal: the toggle reveals only the value already being entered.
+- Disable spelling corrections and capitalization for secrets; preserve the appropriate password-manager autocomplete value. An explicit Edit action in an unlocked vault may populate the current secret in the trusted editor, masked by default. Reopening a record must reset visibility. Do not expose saved plaintext through notebook APIs, lists, logs, or serialized output.
diff --git a/docs/20-agent-monitors.md b/docs/20-agent-monitors.md
index be6d00b9..1d2b3693 100644
--- a/docs/20-agent-monitors.md
+++ b/docs/20-agent-monitors.md
@@ -9,7 +9,7 @@ order: 20
 
 Use an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.
 
-Open **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Visibility resets when the field is cleared or closed. Key values are never included in notebook files or Drive sync.
+Open **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Edit loads the current saved key value, masked by default; use the eye to reveal it or type a replacement. Visibility resets when the field is cleared, closed, or reopened. Key values are never included in notebook files or Drive sync.
 
 The vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.
 
diff --git a/docs/agent-monitors.json b/docs/agent-monitors.json
index 17b95bcb..fd4af349 100644
--- a/docs/agent-monitors.json
+++ b/docs/agent-monitors.json
@@ -3,7 +3,7 @@
     {
       "kind": 1,
       "languageId": "markdown",
-      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Visibility resets when the field is cleared or closed. Key values are never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS → browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
+      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Edit loads the current saved key value, masked by default; use the eye to reveal it or type a replacement. Visibility resets when the field is cleared, closed, or reopened. Key values are never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS → browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
       "refId": "0a152c34fb9e412d95c68cec16074052",
       "metadata": {}
     },

From 1f0276b2ad157e6be1b69b7323e9021812da4596 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 16:41:35 -0700
Subject: [PATCH 09/11] Restore agent vault connection when Connect is retried

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 .../components/Agents/AgentMonitor.test.tsx   | 65 +++++++++++++++++-
 app/src/lib/agents/runtime.test.ts            | 66 ++++++++++++++++++-
 app/src/lib/agents/runtime.ts                 | 59 +++++++++++------
 docs/20-agent-monitors.md                     |  4 +-
 docs/agent-monitors.json                      |  2 +-
 5 files changed, 169 insertions(+), 27 deletions(-)

diff --git a/app/src/components/Agents/AgentMonitor.test.tsx b/app/src/components/Agents/AgentMonitor.test.tsx
index e478048c..bb7accf6 100644
--- a/app/src/components/Agents/AgentMonitor.test.tsx
+++ b/app/src/components/Agents/AgentMonitor.test.tsx
@@ -12,10 +12,13 @@ import { AgentItemView, AgentMonitorOutput } from './AgentMonitor'
 import { resetAgentMonitors } from '../../lib/agents/runtime'
 import * as runtime from '../../lib/agents/runtime'
 import { AgentMonitor } from '../../lib/agents/monitor'
+import { keyVault } from '../../lib/keyvault/store'
 
 afterEach(() => {
   cleanup()
   resetAgentMonitors()
+  localStorage.clear()
+  keyVault.refresh()
   vi.unstubAllGlobals()
   vi.restoreAllMocks()
 })
@@ -139,10 +142,70 @@ describe('agent monitor rendering', () => {
     expect(fetch).not.toHaveBeenCalled()
     fireEvent.click(screen.getByRole('button', { name: 'Connect' }))
     expect((await screen.findByRole('alert')).textContent).toContain(
-      'agents.setKey'
+      'Unlock Key Vault'
     )
     expect(fetch).not.toHaveBeenCalled()
   })
+  it('connects a saved widget after unlocking without rerunning its cell', async () => {
+    const { webcrypto } = await import('node:crypto')
+    vi.stubGlobal('crypto', webcrypto)
+    localStorage.clear()
+    keyVault.refresh()
+    await keyVault.unlock('widget unlock passphrase', true)
+    await keyVault.saveKey('openai-api', 'widget-test-secret')
+    keyVault.lock()
+    const fetchMock = vi.fn<
+      (url: string, options?: RequestInit) => Promise<Response>
+    >(async (url) => {
+      if (url.includes('stream=true'))
+        return new Response(new ReadableStream(), {
+          headers: { 'Content-Type': 'text/event-stream' },
+        })
+      return new Response(
+        JSON.stringify(
+          url.endsWith('sess_saved')
+            ? { status: 'idle' }
+            : { data: [], has_more: false, last_id: null }
+        )
+      )
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    render(
+      <AgentMonitorOutput
+        value={JSON.stringify({
+          version: 1,
+          id: 'unlock-retry',
+          sessionId: 'sess_saved',
+          pageSize: 50,
+        })}
+      />
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Connect' }))
+    expect((await screen.findByRole('alert')).textContent).toContain(
+      'Unlock Key Vault'
+    )
+    expect(fetchMock).not.toHaveBeenCalled()
+    await act(async () => {
+      await keyVault.unlock('widget unlock passphrase')
+    })
+    // Unlocking does not issue requests until the user retries Connect.
+    expect(fetchMock).not.toHaveBeenCalled()
+    fireEvent.click(screen.getByRole('button', { name: 'Connect' }))
+    await waitFor(() =>
+      expect(screen.getByRole('status').textContent).toContain(
+        'Connection: live'
+      )
+    )
+    expect(screen.queryByRole('alert')).toBeNull()
+    expect(fetchMock).toHaveBeenCalledTimes(4)
+    expect(
+      new Headers(fetchMock.mock.calls[0][1]?.headers).get('Authorization')
+    ).toBe('Bearer widget-test-secret')
+    act(() => keyVault.lock())
+    expect(
+      screen.getByRole('button', { name: 'Resume monitoring' })
+    ).toBeTruthy()
+  })
   it('isolates malformed saved descriptors', () => {
     render(<AgentMonitorOutput value='{"version":2}' />)
     expect(screen.getByRole('alert').textContent).toContain('Unsupported')
diff --git a/app/src/lib/agents/runtime.test.ts b/app/src/lib/agents/runtime.test.ts
index 7437a0ee..c7791795 100644
--- a/app/src/lib/agents/runtime.test.ts
+++ b/app/src/lib/agents/runtime.test.ts
@@ -9,7 +9,11 @@ import {
 } from './runtime'
 import { AGENT_MONITOR_MIME, parseMonitorDescriptor } from './types'
 
-afterEach(resetAgentMonitors)
+afterEach(() => {
+  resetAgentMonitors()
+  localStorage.clear()
+  vi.unstubAllGlobals()
+})
 describe('agents runtime', () => {
   it('survives the StrictMode remount probe and requires explicit connection after closing', async () => {
     const api = createAgentsApi(() => {})
@@ -64,6 +68,58 @@ describe('agents runtime', () => {
   })
 })
 
+it('restores a named vault key after reload and resolves rotation on resume', async () => {
+  const { webcrypto } = await import('node:crypto')
+  const { keyVault } = await import('../keyvault/store')
+  vi.stubGlobal('crypto', webcrypto)
+  localStorage.clear()
+  keyVault.refresh()
+  await keyVault.unlock('reload test passphrase', true)
+  await keyVault.saveKey('olympus', 'original-secret')
+  const api = createAgentsApi(() => {})
+  api.setKey(keyVault.getKey('olympus'))
+  const descriptor = api.monitor('sess_reload')
+  resetAgentMonitors()
+  keyVault.lock()
+  const restored = resolveAgentMonitor(descriptor)
+  const fetchMock = vi.fn<
+    (url: string, options?: RequestInit) => Promise<Response>
+  >(async () => new Response('{}', { status: 401 }))
+  vi.stubGlobal('fetch', fetchMock)
+  await restored.connect()
+  expect(restored.getSnapshot().error).toContain('Unlock Key Vault')
+  expect(fetchMock).not.toHaveBeenCalled()
+  await keyVault.unlock('reload test passphrase')
+  await restored.connect()
+  expect(
+    new Headers(fetchMock.mock.calls[0][1]?.headers).get('Authorization')
+  ).toBe('Bearer original-secret')
+  await keyVault.saveKey('olympus', 'rotated-secret', 'olympus')
+  expect(restored.getSnapshot().connection).toBe('paused')
+  await restored.connect()
+  expect(
+    new Headers(fetchMock.mock.calls[1][1]?.headers).get('Authorization')
+  ).toBe('Bearer rotated-secret')
+  await keyVault.deleteKey('olympus')
+  await restored.connect()
+  expect(restored.getSnapshot().error).toContain('Key "olympus" is missing')
+  expect(fetchMock).toHaveBeenCalledTimes(2)
+  keyVault.lock()
+})
+
+it('requires reconfiguration for a saved custom connection instead of using a vault key', async () => {
+  const api = createAgentsApi(() => {})
+  api.configure({ baseUrl: 'https://proxy.example/v1' })
+  const descriptor = api.monitor('sess_proxy')
+  resetAgentMonitors()
+  const restored = resolveAgentMonitor(descriptor)
+  const fetchMock = vi.fn()
+  vi.stubGlobal('fetch', fetchMock)
+  await restored.connect()
+  expect(restored.getSnapshot().error).toContain('agents.configure')
+  expect(fetchMock).not.toHaveBeenCalled()
+})
+
 it('uses vault keys only for OpenAI requests and stops monitors when the vault locks', async () => {
   const { webcrypto } = await import('node:crypto')
   const { keyVault, resolveKeyReference } = await import('../keyvault/store')
@@ -77,7 +133,9 @@ it('uses vault keys only for OpenAI requests and stops monitors when the vault l
   expect(api.setKey(keyVault.getKey('openai-api'))).toEqual({
     configured: true,
   })
-  const fetchMock = vi.fn(async () => new Response('{}', { status: 401 }))
+  const fetchMock = vi.fn<
+    (url: string, options?: RequestInit) => Promise<Response>
+  >(async () => new Response('{}', { status: 401 }))
   vi.stubGlobal('fetch', fetchMock)
   const descriptor = api.monitor('sess_test')
   await api.resume(descriptor.id)
@@ -86,7 +144,9 @@ it('uses vault keys only for OpenAI requests and stops monitors when the vault l
     string,
     RequestInit,
   ]
-  expect(url).toBe('https://api.openai.com/v1/agents/sessions/sess_test/events?stream=true')
+  expect(url).toBe(
+    'https://api.openai.com/v1/agents/sessions/sess_test/events?stream=true'
+  )
   expect(new Headers(options.headers).get('Authorization')).toBe(
     'Bearer runtime-secret'
   )
diff --git a/app/src/lib/agents/runtime.ts b/app/src/lib/agents/runtime.ts
index 93723fef..3375eddd 100644
--- a/app/src/lib/agents/runtime.ts
+++ b/app/src/lib/agents/runtime.ts
@@ -18,6 +18,39 @@ let releaseVaultSubscription: (() => void) | undefined
 const monitors = new Map<string, AgentMonitor>()
 const autoConnect = new WeakSet<AgentMonitor>()
 const mountedViews = new WeakMap<AgentMonitor, number>()
+const connectionPreferenceKey = 'runme/agents/connection/v1'
+
+/** Keep only the selected key name locally; custom header callbacks remain memory-only. */
+function vaultTransport(reference: KeyReference): AgentTransport {
+  resolveKeyReference(reference)
+  const transport = createAgentTransport({
+    baseUrl: 'https://api.openai.com/v1',
+    getHeaders: () => ({
+      Authorization: `Bearer ${resolveKeyReference(reference)}`,
+    }),
+  })
+  releaseVaultSubscription?.()
+  // Locking, rotation and deletion revoke open streams, not just future requests.
+  releaseVaultSubscription = keyVault.subscribe(() => {
+    monitors.forEach((monitor) => monitor.pause())
+  })
+  return transport
+}
+
+/** Connect retries current vault state, including after the page lost its transport. */
+function getConnection(): AgentTransport {
+  if (connection) return connection
+  const saved = localStorage.getItem(connectionPreferenceKey)
+  // Empty marks an explicitly configured proxy. Never switch its sessions to OpenAI.
+  if (saved === '')
+    throw new Error(
+      'Run agents.configure(...) in browser JS again, then Connect.'
+    )
+  const name = saved ?? 'openai-api'
+  // Resolve before caching so a locked/missing key can be retried with Connect.
+  connection = vaultTransport(keyVault.getKey(name))
+  return connection
+}
 
 /** Resolve a saved descriptor without automatically connecting an opened notebook. */
 export function resolveAgentMonitor(
@@ -30,13 +63,7 @@ export function resolveAgentMonitor(
     existing.descriptor.pageSize === descriptor.pageSize
   )
     return existing
-  const monitor = new AgentMonitor(descriptor, () => {
-    if (!connection)
-      throw new Error(
-        'Unlock Key Vault and run agents.setKey(keyvault.getKey("openai-api")) in browser JS, then Connect.'
-      )
-    return connection
-  })
+  const monitor = new AgentMonitor(descriptor, getConnection)
   // Bound retained, detached monitor state; active widgets still own their controllers.
   if (monitors.size >= 100) {
     const oldest = [...monitors.entries()].find(
@@ -94,27 +121,19 @@ export function createAgentsApi(display?: Display) {
     /** Select a vault reference for the OpenAI API; never serialize the secret. */
     setKey: (reference: KeyReference) => {
       resolveKeyReference(reference)
-      const transport = createAgentTransport({
-        baseUrl: 'https://api.openai.com/v1',
-        getHeaders: () => ({
-          Authorization: `Bearer ${resolveKeyReference(reference)}`,
-        }),
-      })
+      localStorage.setItem(connectionPreferenceKey, reference.name)
       monitors.forEach((monitor) => monitor.pause())
-      releaseVaultSubscription?.()
-      connection = transport
-      // Rotation/removal/locking revokes existing streams as well as future requests.
-      releaseVaultSubscription = keyVault.subscribe(() => {
-        monitors.forEach((monitor) => monitor.pause())
-      })
+      connection = vaultTransport(reference)
       return { configured: true }
     },
     configure: (options: AgentConnectionOptions) => {
+      const transport = createAgentTransport(options)
+      localStorage.setItem(connectionPreferenceKey, '')
       releaseVaultSubscription?.()
       releaseVaultSubscription = undefined
       // Disconnect existing views before changing the authority serving their IDs.
       monitors.forEach((monitor) => monitor.pause())
-      connection = createAgentTransport(options)
+      connection = transport
       return { configured: true }
     },
     monitor: (
diff --git a/docs/20-agent-monitors.md b/docs/20-agent-monitors.md
index 1d2b3693..0ad5b239 100644
--- a/docs/20-agent-monitors.md
+++ b/docs/20-agent-monitors.md
@@ -20,9 +20,9 @@ agents.setKey(keyvault.getKey('openai-api'))
 const widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })
 ```
 
-`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.
+`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. Only the selected key name is remembered locally for this Runme site. After reloading, unlock the vault and click Connect; no cell rerun is needed. Without a saved selection, Connect uses `openai-api`. Each attempt checks the current vault state and reports a locked vault or missing key accurately. Locking or changing the vault pauses existing monitors; unlock it and use Resume to reconnect. Deleting or renaming a referenced key requires selecting its replacement with `agents.setKey(...)`.
 
-For an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.
+For an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Custom configuration remains memory-only and must be rerun after a reload; Connect never silently replaces an explicitly configured proxy with OpenAI. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.
 
 ## Read and monitor
 
diff --git a/docs/agent-monitors.json b/docs/agent-monitors.json
index fd4af349..f3f755d7 100644
--- a/docs/agent-monitors.json
+++ b/docs/agent-monitors.json
@@ -3,7 +3,7 @@
     {
       "kind": 1,
       "languageId": "markdown",
-      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Edit loads the current saved key value, masked by default; use the eye to reveal it or type a replacement. Visibility resets when the field is cleared, closed, or reopened. Key values are never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS → browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. A missing key or locked vault gives a clear error. Locking or changing the vault pauses existing monitors; unlock it and use Resume, or rerun the cell, to reconnect. Deleting or renaming a referenced key requires selecting its replacement.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
+      "value": "# Agent session monitors\n\nUse an AppKernel JavaScript cell to display an Agents API session as an interactive widget. Messages render Markdown; tools and unfamiliar items expand to structured details. The separate Activity disclosure contains the latest 100 stream events.\n\nOpen **Key Vault** in the left navigation. Create a vault with a passphrase, then add a key named `openai-api` using your session-management API key. You can add any number of named keys (within browser storage capacity), edit their names or values, and remove them. Secret fields are masked by default. Use the eye button on the right to show or hide a passphrase or key value while entering it. Edit loads the current saved key value, masked by default; use the eye to reveal it or type a replacement. Visibility resets when the field is cleared, closed, or reopened. Key values are never included in notebook files or Drive sync.\n\nThe vault is encrypted in this browser for this Runme site. Unlock it after reopening Runme; the passphrase is not saved and cannot be recovered. Clearing the site's browser data removes the vault. Only run trusted browser JavaScript while the vault is unlocked. This is local credential storage, not a cloud secret manager.\n\nRun the following cell with **JS → browser**:\n\n```js\nagents.setKey(keyvault.getKey('openai-api'))\nconst widget = agents.monitor('YOUR_SESSION_ID', { pageSize: 50 })\n```\n\n`getKey` returns an opaque reference, so logging it shows only the key name. `setKey` selects the OpenAI API at `https://api.openai.com/v1` and resolves the current key for every request. Only the selected key name is remembered locally for this Runme site. After reloading, unlock the vault and click Connect; no cell rerun is needed. Without a saved selection, Connect uses `openai-api`. Each attempt checks the current vault state and reports a locked vault or missing key accurately. Locking or changing the vault pauses existing monitors; unlock it and use Resume to reconnect. Deleting or renaming a referenced key requires selecting its replacement with `agents.setKey(...)`.\n\nFor an application-owned proxy, advanced browser code may still use `agents.configure({ baseUrl, getHeaders })`. Custom configuration remains memory-only and must be rerun after a reload; Connect never silently replaces an explicitly configured proxy with OpenAI. Do not put secrets in notebook code. Sandbox cells can monitor a connection previously configured by browser JS, but cannot access the vault or install credential callbacks. The Python runner's key files are separate and cannot be read by browser JavaScript.\n\n",
       "refId": "0a152c34fb9e412d95c68cec16074052",
       "metadata": {}
     },

From 009adecef85c1f3ce2317f8ec1aef49a6ae25699 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 17:13:15 -0700
Subject: [PATCH 10/11] Address agent monitor review findings and enforce
 regression checks

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 .github/workflows/test.yaml                 |  7 +++++
 app/src/components/Actions/Actions.test.tsx |  4 ++-
 app/src/lib/agents/monitor.test.ts          | 33 +++++++++++++++++++++
 app/src/lib/agents/monitor.ts               |  8 ++++-
 docs-dev/design/20261003_agents_api_ui.md   |  8 ++---
 docs/20-agent-monitors.md                   |  2 +-
 docs/agent-monitors.json                    |  2 +-
 7 files changed, 56 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
index 5c1016db..727acfbf 100644
--- a/.github/workflows/test.yaml
+++ b/.github/workflows/test.yaml
@@ -55,3 +55,10 @@ jobs:
         uses: stateful/runme-action@v2
         with:
           workflows: test
+      - name: Test agent widgets and key vault
+        run: >-
+          pnpm -C app exec vitest run
+          src/lib/agents src/lib/keyvault src/components/Agents src/components/KeyVault
+          src/lib/runtime/sandboxJsKernel.test.ts src/lib/notebookData.test.ts
+          src/components/Actions/Actions.test.tsx
+          --maxWorkers=2 --minWorkers=1
diff --git a/app/src/components/Actions/Actions.test.tsx b/app/src/components/Actions/Actions.test.tsx
index 97ab2de4..b8684422 100644
--- a/app/src/components/Actions/Actions.test.tsx
+++ b/app/src/components/Actions/Actions.test.tsx
@@ -3833,7 +3833,9 @@ describe('Action component', () => {
       message: 'Selected text copied',
       tone: 'success',
     })
-    expect(screen.queryByRole('button', { name: 'Copy' })).toBeNull()
+    await waitFor(() => {
+      expect(screen.queryByRole('button', { name: 'Copy' })).toBeNull()
+    })
     selection.removeAllRanges()
   })
 
diff --git a/app/src/lib/agents/monitor.test.ts b/app/src/lib/agents/monitor.test.ts
index 097ebefc..79630fec 100644
--- a/app/src/lib/agents/monitor.test.ts
+++ b/app/src/lib/agents/monitor.test.ts
@@ -73,6 +73,39 @@ function setup(overrides: Partial<AgentTransport> = {}) {
 }
 
 describe('AgentMonitor', () => {
+  it('defers scheduled refreshes until an in-flight message submission settles', async () => {
+    vi.useFakeTimers()
+    let resolveSend!: () => void
+    let sendSignal!: AbortSignal
+    const { model, transport } = setup({
+      sendMessage: (_id, _text, _key, signal) => {
+        sendSignal = signal
+        return new Promise<void>((resolve) => {
+          resolveSend = resolve
+        })
+      },
+    })
+    await model.connect()
+    model.setDraft('Continue the work')
+    const sending = model.sendMessage()
+    model.applyEvent({
+      type: 'agent.session.turn.completed',
+      turn: {
+        id: 'root',
+        subagent_id: null,
+        status: 'completed',
+        created_at: 1,
+      },
+    })
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(sendSignal.aborted).toBe(false)
+    expect(transport.stream).toHaveBeenCalledTimes(1)
+    resolveSend()
+    expect(await sending).toBe(true)
+    await vi.advanceTimersByTimeAsync(500)
+    expect(transport.stream).toHaveBeenCalledTimes(2)
+  })
+
   it('keeps failed submissions retryable without duplication and requires live observation', async () => {
     const sendMessage = vi
       .fn()
diff --git a/app/src/lib/agents/monitor.ts b/app/src/lib/agents/monitor.ts
index a877c7c4..9a0d7f73 100644
--- a/app/src/lib/agents/monitor.ts
+++ b/app/src/lib/agents/monitor.ts
@@ -132,7 +132,7 @@ export class AgentMonitor {
       // Acceptance is uncertain after a network failure. Keep both text and retry ID.
       this.update({
         sendError:
-          'Could not confirm delivery. Your draft is kept. Retry unchanged to avoid duplicates; editing sends a new message.',
+          'Could not confirm delivery. Your draft is kept. Check the latest conversation before retrying: the message may already have been accepted.',
       })
       return false
     } finally {
@@ -263,6 +263,12 @@ export class AgentMonitor {
     if (this.refreshTimer || this.controller?.signal.aborted) return
     this.refreshTimer = setTimeout(() => {
       this.refreshTimer = undefined
+      // Reconnecting aborts the observation signal shared by an active send.
+      // Let delivery settle first so a status refresh cannot interrupt its response.
+      if (this.snapshot.sending) {
+        this.scheduleRefresh()
+        return
+      }
       // Full reconnect applies the documented stream-before-snapshot recovery sequence.
       void this.connect()
     }, 500)
diff --git a/docs-dev/design/20261003_agents_api_ui.md b/docs-dev/design/20261003_agents_api_ui.md
index 42599b86..adc5a20a 100644
--- a/docs-dev/design/20261003_agents_api_ui.md
+++ b/docs-dev/design/20261003_agents_api_ui.md
@@ -16,7 +16,7 @@ Keep agent creation, tool approvals, and cancellation in explicit code cells. Th
 
 Use **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.
 
-The composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; retry unchanged to reuse its submission ID and avoid duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.
+The composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; check the latest conversation before retrying because the message may already have been accepted. Unchanged retries reuse a submission ID for transports that honor it; this is not a guarantee against duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.
 
 
 
@@ -91,11 +91,11 @@ await agents.newer(widget.id)
 agents.latest(widget.id)
 ```
 
-Key Vault is a dedicated left-navigation panel for creating/unlocking a local vault and adding, renaming, rotating, or deleting named keys. Password fields mask values; editing a key never loads its old value into the form. The example uses `openai-api` consistently; users can choose other names.
+Key Vault is a dedicated left-navigation panel for creating/unlocking a local vault and adding, renaming, rotating, or deleting named keys. Secret fields are masked by default with an eye toggle. Editing an unlocked key loads its current value in the trusted editor, masked again on each edit. The example uses `openai-api` consistently; users can choose other names.
 
-Persist a versioned AES-256-GCM envelope with a random 96-bit IV per write. Derive the nonextractable encryption key from a user passphrase with PBKDF2-SHA256 (600,000 iterations, random 128-bit salt). Encrypt names and values together. Store only ciphertext, salt, and IV in localStorage, scoped to this browser profile and Runme origin; no Drive or notebook export includes the vault. The passphrase is not saved; forgotten passphrases and cleared browser data are not recoverable. While unlocked, trusted browser JS shares the app's authority; this is not an XSS isolation boundary or a cloud vault.
+Persist a versioned AES-256-GCM envelope with a random 96-bit IV per write. Derive the nonextractable encryption key from a user passphrase with PBKDF2-SHA256 (600,000 iterations, random 128-bit salt). Encrypt names and values together. Store the vault as ciphertext, salt, and IV in localStorage, scoped to this browser profile and Runme origin; the selected agent key name is a separate local preference without its value; no Drive or notebook export includes the vault. The passphrase is not saved; forgotten passphrases and cleared browser data are not recoverable. While unlocked, trusted browser JS shares the app's authority; this is not an XSS isolation boundary or a cloud vault.
 
-`keyvault.getKey(name)` returns a process-local opaque reference containing only its name when serialized. `agents.setKey(reference)` accepts only a genuine reference and binds authentication to the OpenAI API. Resolve the current value for each request rather than copying it into a durable descriptor. Lock, rotation, removal, and cross-tab vault changes pause existing streams. Reload/pagehide locks the vault. Missing names and locked vaults produce errors without secret values. Unlock explicitly and resume observation. Web Locks plus ciphertext comparisons reject stale writes; storage failures preserve previous keys, and invalid ciphertext is never automatically deleted.
+`keyvault.getKey(name)` returns a process-local opaque reference containing only its name when serialized. `agents.setKey(reference)` accepts only a genuine reference and binds authentication to the OpenAI API. Resolve the current value for each request rather than copying it into a durable descriptor. Lock, rotation, removal, and cross-tab vault changes pause existing streams. Reload/pagehide locks the vault. Missing names and locked vaults produce errors without secret values. Unlock explicitly and resume observation. Connect restores the locally selected key name after reload, defaulting to openai-api for an existing widget without a selection, and resolves the current vault value on every request. Explicit custom proxy configuration must be rerun after reload and never falls back to OpenAI. Web Locks plus ciphertext comparisons reject stale writes; storage failures preserve previous keys, and invalid ciphertext is never automatically deleted.
 
 Keep `agents.configure({ baseUrl, getHeaders })` as an advanced integration point for application-owned proxies. Configuration remains in memory. No server credential broker is added, and browser code cannot read the Python runner's local key file. Vault writes/unlock happen in the sidebar, not in saved notebook source. Sandbox code cannot retrieve keys or install authentication providers.
 
diff --git a/docs/20-agent-monitors.md b/docs/20-agent-monitors.md
index 0ad5b239..df2a5948 100644
--- a/docs/20-agent-monitors.md
+++ b/docs/20-agent-monitors.md
@@ -40,7 +40,7 @@ Runtime controls use the descriptor returned by `agents.monitor`: `agents.get(wi
 
 Use **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.
 
-The composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; retry unchanged to reuse its submission ID and avoid duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.
+The composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; check the latest conversation before retrying because the message may already have been accepted. Unchanged retries reuse a submission ID for transports that honor it; this is not a guarantee against duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.
 
 ## Synthetic local demo
 
diff --git a/docs/agent-monitors.json b/docs/agent-monitors.json
index f3f755d7..46e9fd50 100644
--- a/docs/agent-monitors.json
+++ b/docs/agent-monitors.json
@@ -19,7 +19,7 @@
     {
       "kind": 1,
       "languageId": "markdown",
-      "value": "## Read and monitor\n\n**Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.\n\n**Older** and **Newer** page through saved items, with at most the configured page size visible. **Latest** returns to the live window. New output never replaces an older page while you read it. Scroll to the live bottom to follow incoming output automatically.\n\n**Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.\n\nSaved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit tool results or cancellation through your agent client.\n\nRuntime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.\n\n## Send a message\n\nUse **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.\n\nThe composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; retry unchanged to reuse its submission ID and avoid duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.\n\n## Synthetic local demo\n\nStart `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.\n\n",
+      "value": "## Read and monitor\n\n**Edit** shows the source and **Render** shows the widget, without running the cell again. Editing keeps observation active. Press Run to apply changed source. The JS cell finishes immediately; the separate root-turn status tracks agent completion.\n\n**Older** and **Newer** page through saved items, with at most the configured page size visible. **Latest** returns to the live window. New output never replaces an older page while you read it. Scroll to the live bottom to follow incoming output automatically.\n\n**Pause monitoring** stops this widget's requests, not the agent. **Resume monitoring** reloads saved state and reconnects. A closed stream displays Disconnected; it does not imply completion. Session status, root-turn status, and connection status are separate. Child-turn completion does not complete the root turn.\n\nSaved widget outputs contain only a session ID, widget ID, version, and page size. Reopening a notebook requires Connect. Credentials and live messages are not serialized into the widget output. Required actions are shown for inspection; submit tool results or cancellation through your agent client.\n\nRuntime controls use the descriptor returned by `agents.monitor`: `agents.get(widget.id)`, `agents.pause(widget.id)`, `await agents.resume(widget.id)`, `await agents.older(widget.id)`, `await agents.newer(widget.id)`, and `agents.latest(widget.id)`. `agents.help()` lists the commands.\n\n## Send a message\n\nUse **Message the agent** below the rendered conversation. Press **Send** or Enter to submit; Shift+Enter inserts a new line. The monitor must be connected. Sending starts a new turn when idle or steers the active turn. The input stays visible while browsing history; a successful send returns to Latest.\n\nThe composer prevents simultaneous submissions and clears the draft only after the API accepts it. On a timeout or error, the draft stays available; check the latest conversation before retrying because the message may already have been accepted. Unchanged retries reuse a submission ID for transports that honor it; this is not a guarantee against duplicates. Editing sends a new message. Reconnecting never sends automatically. Drafts and retry IDs stay in memory for the current widget; reloading or rerunning the cell discards them. After an uncertain send, retry before reloading, or check conversation history before submitting again.\n\n## Synthetic local demo\n\nStart `go run testing/fake-agents-server.go` from the repository and Runme on port 5173. Configure `agents.configure({ baseUrl: 'http://127.0.0.1:8989/v1' })`, then run `agents.monitor('sess_demo', { pageSize: 5 })`. This fixture contains 125 items and emits live text every two seconds. No real agent or credentials are involved.\n\n",
       "refId": "002946c0829a4f3ab899510f2563b819",
       "metadata": {}
     }

From 9423d648c5d47743601b88c220dca8bb68b33526 Mon Sep 17 00:00:00 2001
From: Jeremy lewi <jeremy@lewi.us>
Date: Sat, 3 Oct 2026 17:16:13 -0700
Subject: [PATCH 11/11] Allow bounded CI headroom for source scans and comment
 lifecycle tests

Signed-off-by: Jeremy lewi <jeremy@lewi.us>
---
 app/src/components/Actions/Actions.test.tsx | 3 ++-
 app/src/storage/boundedStorageReads.test.js | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/app/src/components/Actions/Actions.test.tsx b/app/src/components/Actions/Actions.test.tsx
index b8684422..faa1374c 100644
--- a/app/src/components/Actions/Actions.test.tsx
+++ b/app/src/components/Actions/Actions.test.tsx
@@ -997,7 +997,8 @@ describe('Actions tabs', () => {
     )
     expect(await screen.findByText('Feedback from diff')).toBeTruthy()
     expect(screen.getByText(/Historical source/)).toBeTruthy()
-  })
+    // Multiple rendered edit/reply/resolve cycles exceed 5s on shared CI CPUs.
+  }, 20_000)
 
   it.each(['rendered', 'code', 'markdown-source'])(
     'submits a %s selection through real operation-log persistence after a pending flush and later edit',
diff --git a/app/src/storage/boundedStorageReads.test.js b/app/src/storage/boundedStorageReads.test.js
index 28c09d2e..9896f1ba 100644
--- a/app/src/storage/boundedStorageReads.test.js
+++ b/app/src/storage/boundedStorageReads.test.js
@@ -36,6 +36,7 @@ describe('bounded storage read guardrail', () => {
   })
 
   it('keeps production file and creation enumeration behind the helpers', async () => {
+    // This scans the entire source tree; allow bounded headroom on shared CI CPUs.
     // Run the same rule in the regular app test suite, even when CI skips lint.
     const lint = new ESLint({
       allowInlineConfig: false,
@@ -51,5 +52,5 @@ describe('bounded storage read guardrail', () => {
     expect(results.flatMap((result) => result.messages.map((message) =>
       `${result.filePath}:${message.line} ${message.message}`
     ))).toEqual([])
-  })
+  }, 30_000)
 })