@mono-agent/web 0.20.10 → 0.20.14

package/dist/service.js

@@ -1,10 +1,11 @@
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { DEFAULT_AGENT_ATTACHMENT_MAX_BYTES, DEFAULT_AGENT_ATTACHMENT_MIME_ALLOWLIST, createChannelUserCancelReason, isChannelUserCancelReason, toolNameLeaf, } from "@mono-agent/agent-contracts";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { AGENT_LIVE_INPUT_MAX_CHARACTERS, DEFAULT_AGENT_ATTACHMENT_MAX_BYTES, DEFAULT_AGENT_ATTACHMENT_MIME_ALLOWLIST, createChannelUserCancelReason, isChannelUserCancelReason, toolNameLeaf, } from "@mono-agent/agent-contracts";
 import { EFFORT_LEVELS } from "@mono-agent/config";
 import { WEB_API_VERSION, WEB_MAX_CONCURRENT_UPLOADS, WEB_MAX_ACTIVE_ATTACHMENT_TURN_BYTES, WEB_MAX_FILES_PER_TURN, WEB_MAX_STAGED_UPLOAD_BYTES, WEB_MAX_STAGED_UPLOADS, WEB_MAX_QUEUED_ATTACHMENT_TURNS, WEB_MAX_TURN_TEXT_CHARACTERS, WEB_MAX_TURN_ATTACHMENT_BYTES, WEB_STAGED_UPLOAD_TTL_MS, } from "./contracts.js";
 import { discoverOperatorAgents, } from "./discovery.js";
 import { conversationTitleFromFrame } from "./conversation-title.js";
+import { advertisedEffortLevels, effectiveModelForAgent, effortLevelsForModel } from "./effort-ladder.js";
 import { errorCode, errorMessage, WebConsoleError } from "./errors.js";
 import { OperatorClient } from "./operator-client.js";
 import { generateWebPushIdentity, normalizeWebPushEndpoint, resolveWebPushSubject, validateWebPushEndpoint, validateWebPushKeys, WebPushDispatcher, WEB_PUSH_SERVICE_WORKER_VERSION, } from "./push.js";
@@ -14,7 +15,15 @@ const DEFAULT_DISCOVERY_INTERVAL_MS = 5_000;
 const DEFAULT_PURGE_INTERVAL_MS = 60 * 60 * 1_000;
 const INFO_TIMEOUT_MS = 2_500;
 const ASK_DISCOVERY_TIMEOUT_MS = 120_000;
+/** Bounded per-agent catalog-admitted model refs; beyond it, oldest go first. */
+const MODEL_CATALOG_CACHE_CAP = 2_048;
 const REPLY_ACCESS_TTL_MS = 10 * 60 * 1_000;
+/**
+ * Raster types the console keeps its own copy of. `image/svg+xml` is absent on
+ * purpose: it is active content, and both the inline gate in the browser and
+ * `setReplyDownloadHeaders` already refuse to treat it as an image.
+ */
+const REPLY_IMAGE_MEDIA_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
 function formatQuotedTurn(quote, text) {
     const blockquote = quote
         .trim()
@@ -23,6 +32,31 @@ function formatQuotedTurn(quote, text) {
         .join("\n");
     return `Quoted context:\n${blockquote}\n\n${text}`;
 }
+function assertMonitorWakeAddress(input) {
+    const originConversation = input.monitor.origin.conversationId.split("#", 1)[0];
+    const expectedDeliveryKey = `monitor:${input.monitor.monitorId}:${String(input.monitor.counters.seq)}`;
+    if (input.monitor.origin.channel !== "web"
+        || originConversation !== `web:${input.threadId}`
+        || input.deliveryKey !== expectedDeliveryKey) {
+        throw new WebConsoleError("invalid_notification", "The Monitor wake origin or delivery key does not match its web destination.", 409);
+    }
+}
+function monitorWakePayloadSha256(monitor, wakePrompt) {
+    return createHash("sha256")
+        .update(canonicalJson(monitor))
+        .update("\0")
+        .update(wakePrompt)
+        .digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
 export class WebService {
     store;
     options;
@@ -33,9 +67,10 @@ export class WebService {
     drainingLiveInputThreads = new Set();
     activeUploads = new Map();
     activeNotifications = new Map();
-    processJobWakeTails = new Map();
-    processJobWakeReservations = new Map();
-    activeProcessJobWakes = new Map();
+    /** One serialization lane shared by queued user input and every host wake kind. */
+    hostWakeTails = new Map();
+    hostWakeReservations = new Map();
+    activeHostWakes = new Map();
     allowlist = new Set(DEFAULT_AGENT_ATTACHMENT_MIME_ALLOWLIST);
     attachmentTurnBudget;
     pushIdentity;
@@ -44,6 +79,15 @@ export class WebService {
     replyAccessKey;
     askWatches = new Map();
     connections = new Map();
+    /** Bounded catalog-admitted model refs per agent, seeded from `modelOptions`
+     *  and appended to by every proxied `/v1/models` page. Admission is `has`,
+     *  metadata is `get`. Map preserves insertion order, so evicting the oldest
+     *  entry is deleting the head. Scoped to the agent GENERATION that filled it
+     *  (see `reconcileModelCatalogCache`), because a source id outlives the
+     *  process behind it. */
+    modelCatalogCache = new Map();
+    /** Parts whose durable copy is being fetched, so concurrent reads fetch once. */
+    persistingReplyImages = new Set();
     discoveryTimer;
     purgeTimer;
     purgePromise;
@@ -309,6 +353,23 @@ export class WebService {
         return result;
     }
     patchThread(id, patch) {
+        if (patch.ifRunConfigUnset === true) {
+            // Compare-and-set for the console's one-time adoption of a browser-local
+            // override. Whoever set an override first keeps it; the loser adopts what
+            // it reads back, and no event is emitted because nothing changed.
+            //
+            // The check and the write are one `BEGIN IMMEDIATE` inside the store, not
+            // two calls from here: this request handler is synchronous, so no other
+            // HTTP request can interleave, but the process lease is held on a
+            // separate database file and does not stop a second connection to the
+            // state DB from writing between a bare read and a bare write.
+            const result = this.store.patchThreadIfRunConfigUnset(id, patch);
+            if (!result.applied)
+                return result.thread;
+            this.emit("thread.changed", result.thread.id, { thread: result.thread });
+            this.emit("threads.changed", result.thread.id);
+            return result.thread;
+        }
         const thread = this.store.patchThread(id, patch);
         this.emit("thread.changed", thread.id, { thread });
         this.emit("threads.changed", thread.id);
@@ -333,7 +394,7 @@ export class WebService {
     }
     patchAgent(sourceId, patch) {
         const agent = this.store.setAgentPinned(sourceId, patch.pinned);
-        this.emit("agents.changed", undefined, { agents: this.store.listAgents() });
+        this.emit("agents.changed");
         return agent;
     }
     agentSkills(sourceId) {
@@ -408,6 +469,47 @@ export class WebService {
         }
         return this.decorateMessage(message);
     }
+    async agentModels(sourceId, input) {
+        const agent = this.store.getAgent(sourceId);
+        if (agent === undefined)
+            throw new WebConsoleError("agent_not_found", "Agent not found.", 404);
+        const connection = this.connections.get(sourceId);
+        if (connection === undefined)
+            throw new WebConsoleError("agent_offline", "This agent is offline.", 409);
+        const generation = this.modelCatalogCache.get(sourceId)?.generation;
+        const page = await connection.client.models({
+            ...(input.provider === undefined ? {} : { provider: input.provider }),
+            ...(input.q === undefined ? {} : { q: input.q }),
+            ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+            limit: input.limit,
+            signal: AbortSignal.timeout(INFO_TIMEOUT_MS),
+        });
+        // Every proxied page widens the per-agent catalog cache, the only feed
+        // (besides `modelOptions` keys) that makes tier-2 model admission possible,
+        // and the only place the effort ladder a catalog model advertises is ever
+        // seen -- `modelOptions` never describes it, so dropping it here is what
+        // left effort validation with nothing to judge against.
+        //
+        // Admitted under the generation the request was ISSUED under, never under
+        // whatever is current when it answers. A discovery refresh can retire this
+        // agent's generation inside the await above, and keyed by source id alone
+        // the reply -- fetched from a process that is gone -- was written straight
+        // into the freshly reconciled map, where `source: "page"` overwrites
+        // unconditionally. Generation 1's ladder then judged generation 2's turns.
+        this.admitCatalogRefs(sourceId, generation, page.models.flatMap((model) => {
+            const record = { source: "page", efforts: advertisedEffortLevels(model) };
+            // The wire carries provider-local ids while every selection surface
+            // speaks the canonical `<provider>:<model>` reference. Admit both, or a
+            // turn is judged against metadata the page did advertise but under a
+            // name nothing ever asks for.
+            const reference = model.provider ? `${model.provider}:${model.id}` : model.id;
+            const entries = [[model.id, record]];
+            if (reference !== model.id)
+                entries.push([reference, record]);
+            return entries;
+        }));
+        return page;
+    }
     async cronConfigView(sourceId) {
         const connection = this.requireCronConnection(sourceId, false);
         return await connection.client.cronConfigView(AbortSignal.timeout(INFO_TIMEOUT_MS));
@@ -449,6 +551,29 @@ export class WebService {
         }
         if (this.store.getAgent(input.sourceId) === undefined)
             await this.refreshAgents();
+        if (this.stopped) {
+            throw new WebConsoleError("web_service_stopping", "The web service is stopping.", 409);
+        }
+        if (input.triggerKind === "monitor") {
+            assertMonitorWakeAddress(input);
+            const thread = this.store.getThread(input.threadId);
+            if (thread === undefined || thread.sourceId !== input.sourceId) {
+                return {
+                    duplicate: true,
+                    tombstoned: true,
+                    delivery: { delivered: false, code: "monitor_origin_mismatch", retryable: false },
+                };
+            }
+            if (thread.archivedAt !== null || thread.trigger !== undefined) {
+                return {
+                    thread,
+                    duplicate: false,
+                    delivery: { delivered: false, code: "monitor_wake_failed", retryable: false },
+                };
+            }
+            const result = await this.deliverMonitorWake(input);
+            return { thread, duplicate: result.duplicate, delivery: result.receipt };
+        }
         if (input.triggerKind === "job") {
             const completed = this.store.upsertProcessJobCard({
                 sourceId: input.sourceId,
@@ -468,6 +593,9 @@ export class WebService {
                 return completed;
             if (this.connections.get(input.sourceId) === undefined)
                 await this.refreshAgents();
+            if (this.stopped) {
+                throw new WebConsoleError("web_service_stopping", "The web service is stopping.", 409);
+            }
             const delivery = await this.deliverProcessJobWake(input);
             return { ...completed, delivery };
         }
@@ -522,8 +650,15 @@ export class WebService {
         if (agent === undefined || connection === undefined || !thread.canSend) {
             throw new WebConsoleError("agent_offline", "This agent is offline. The conversation remains available read-only.", 409);
         }
-        validateModelAndEffort(agent, input.model, input.effort);
-        const started = this.store.beginTurn({ threadId, text, attachmentIds, ...(input.quote === undefined ? {} : { quote: input.quote }), ...(input.model === undefined ? {} : { model: input.model }), ...(input.effort === undefined ? {} : { effort: input.effort }) });
+        // The per-thread override is server state now, so it governs turns this
+        // server starts too -- process-job follow-ups and other assistant-owned
+        // wakes omit model/effort and would otherwise silently run on the agent
+        // default, ignoring the selection made in that very conversation. An
+        // explicit request value still wins.
+        const model = input.model ?? thread.runModel ?? undefined;
+        const effort = input.effort ?? thread.runEffort ?? undefined;
+        this.validateModelAndEffort(thread.sourceId, agent, model, effort);
+        const started = this.store.beginTurn({ threadId, text, attachmentIds, ...(input.quote === undefined ? {} : { quote: input.quote }), ...(model === undefined ? {} : { model }), ...(effort === undefined ? {} : { effort }) });
         this.launchTurn(started, connection.client, operatorText);
         this.emit("turn.changed", threadId, { turn: started.thread.runState });
         this.emit("threads.changed", threadId);
@@ -701,7 +836,7 @@ export class WebService {
         const active = [...this.activeTurns.values()];
         const activeLiveInputs = [...this.activeLiveInputs.entries()];
         const activeNotifications = [...this.activeNotifications.values()];
-        const activeProcessJobWakes = [...this.activeProcessJobWakes.values()];
+        const activeHostWakes = [...this.activeHostWakes.values()];
         const trackedIds = new Set(active.map((turn) => turn.turnId));
         for (const turnId of this.store.listActiveTurnIds()) {
             if (!trackedIds.has(turnId))
@@ -717,7 +852,7 @@ export class WebService {
         }
         await Promise.allSettled(active.map((turn) => turn.completion));
         await Promise.allSettled(activeLiveInputs.map(([, input]) => input.completion));
-        await Promise.allSettled(activeProcessJobWakes);
+        await Promise.allSettled(activeHostWakes);
         await Promise.allSettled(activeNotifications);
         await Promise.allSettled(askWatches.map((watch) => watch.promise));
         await this.pushDispatcher.stopAndDrain(5_000);
@@ -729,7 +864,7 @@ export class WebService {
         this.store.close();
         await this.lease.release();
     }
-    async runTurn(started, client, controller, operatorText, processJobWakeDeliveryKey) {
+    async runTurn(started, client, controller, operatorText, hostWakeDeliveryKey) {
         const coalescer = new StreamFrameCoalescer(async (frames) => {
             const message = this.store.applyStreamFrames(started.turnId, frames);
             this.emit("message.changed", started.thread.id, { messageId: message.id, updatedAt: message.updatedAt });
@@ -753,13 +888,13 @@ export class WebService {
                         threadId: started.thread.id,
                         turnId: started.turnId,
                         ...modelMetadata,
-                        ...(processJobWakeDeliveryKey === undefined && this.store.canApplyAgentTitle(started.thread.id)
+                        ...(hostWakeDeliveryKey === undefined && this.store.canApplyAgentTitle(started.thread.id)
                             ? { conversationTitle: { schema: 1, writable: true } }
                             : {}),
                     },
                     tui: modelMetadata,
                 },
-                ...(processJobWakeDeliveryKey === undefined ? {} : { processJobWakeDeliveryKey }),
+                ...(hostWakeDeliveryKey === undefined ? {} : { processJobWakeDeliveryKey: hostWakeDeliveryKey }),
                 onFrame: (frame) => {
                     this.observeAskUserFrame(started.thread.id, started.turnId, frame);
                     this.observeConversationTitleFrame(started.thread.id, started.turnId, frame);
@@ -767,11 +902,19 @@ export class WebService {
                 },
             });
             await coalescer.flush();
-            const detail = this.store.completeTurn(started.turnId, response.finalText, response.metadata, response.parts);
+            const silentMonitorWake = hostWakeDeliveryKey?.startsWith("monitor:") === true
+                && (response.finalText === undefined || response.finalText.length === 0)
+                && (response.parts === undefined || response.parts.length === 0);
+            const detail = this.store.completeTurn(started.turnId, response.finalText, response.metadata, response.parts, { suppressResponsePush: silentMonitorWake });
             this.emit("turn.changed", started.thread.id, { turn: detail.thread.runState });
             this.emit("thread.changed", started.thread.id, { revision: detail.thread.revision });
             this.emit("threads.changed", started.thread.id);
-            this.announcePushEvent(`turn:${started.turnId}:terminal`);
+            if (!silentMonitorWake)
+                this.announcePushEvent(`turn:${started.turnId}:terminal`);
+            // Detached: the turn is already finished and reported, and keeping a copy
+            // must neither delay nor fail it. The agent is still connected here, which
+            // is when a fetch is most likely to succeed.
+            void this.persistReplyImages(started.thread.id, detail.messages);
         }
         catch (error) {
             let failure = error;
@@ -800,14 +943,14 @@ export class WebService {
             coalescer.close();
         }
     }
-    launchTurn(started, client, operatorText, processJobWakeDeliveryKey) {
+    launchTurn(started, client, operatorText, hostWakeDeliveryKey) {
         const threadId = started.thread.id;
         const controller = new AbortController();
-        const completion = this.runTurn(started, client, controller, operatorText, processJobWakeDeliveryKey).finally(() => {
+        const completion = this.runTurn(started, client, controller, operatorText, hostWakeDeliveryKey).finally(() => {
             const active = this.activeTurns.get(threadId);
             if (active?.turnId === started.turnId)
                 this.activeTurns.delete(threadId);
-            if (!this.stopped && !this.processJobWakeReservations.has(threadId)) {
+            if (!this.stopped && !this.hostWakeReservations.has(threadId)) {
                 void this.drainQueuedLiveInputs(threadId);
             }
         });
@@ -853,7 +996,7 @@ export class WebService {
     async drainQueuedLiveInputs(threadId) {
         if (this.stopped
             || this.activeTurns.has(threadId)
-            || this.processJobWakeReservations.has(threadId)
+            || this.hostWakeReservations.has(threadId)
             || this.drainingLiveInputThreads.has(threadId))
             return;
         this.drainingLiveInputThreads.add(threadId);
@@ -880,8 +1023,8 @@ export class WebService {
         }
     }
     async deliverProcessJobWake(input) {
-        const activeKey = `${input.sourceId}\0${input.processJob.jobId}`;
-        const existing = this.activeProcessJobWakes.get(activeKey);
+        const activeKey = `${input.sourceId}\0${input.deliveryKey}`;
+        const existing = this.activeHostWakes.get(activeKey);
         if (existing !== undefined)
             return await existing;
         const reservation = this.store.reserveProcessJobWake({
@@ -901,8 +1044,8 @@ export class WebService {
                 ambiguous: true,
             };
         }
-        this.retainProcessJobWakeReservation(input.threadId);
-        const previous = this.processJobWakeTails.get(input.threadId) ?? Promise.resolve();
+        this.retainHostWakeReservation(input.threadId);
+        const previous = this.hostWakeTails.get(input.threadId) ?? Promise.resolve();
         const delivery = previous.catch(() => undefined).then(async () => {
             const connection = this.connections.get(input.sourceId);
             if (connection === undefined) {
@@ -1011,30 +1154,206 @@ export class WebService {
             return { delivered: true, disposition: "follow_up" };
         });
         const tail = delivery.then(() => undefined, () => undefined);
-        this.processJobWakeTails.set(input.threadId, tail);
-        this.activeProcessJobWakes.set(activeKey, delivery);
+        this.hostWakeTails.set(input.threadId, tail);
+        this.activeHostWakes.set(activeKey, delivery);
         try {
             return await delivery;
         }
         finally {
-            if (this.processJobWakeTails.get(input.threadId) === tail) {
-                this.processJobWakeTails.delete(input.threadId);
+            if (this.hostWakeTails.get(input.threadId) === tail) {
+                this.hostWakeTails.delete(input.threadId);
+            }
+            if (this.activeHostWakes.get(activeKey) === delivery) {
+                this.activeHostWakes.delete(activeKey);
+            }
+            this.releaseHostWakeReservation(input.threadId);
+        }
+    }
+    async deliverMonitorWake(input) {
+        const activeKey = `${input.sourceId}\0${input.deliveryKey}`;
+        const reservation = this.store.reserveMonitorWake({
+            sourceId: input.sourceId,
+            threadId: input.threadId,
+            monitorId: input.monitor.monitorId,
+            deliveryKey: input.deliveryKey,
+            payloadSha256: monitorWakePayloadSha256(input.monitor, input.wakePrompt),
+            monitor: input.monitor,
+        });
+        if (reservation.kind === "completed") {
+            return {
+                receipt: { delivered: true, disposition: reservation.disposition },
+                duplicate: true,
+            };
+        }
+        if (reservation.kind === "uncertain") {
+            const existing = this.activeHostWakes.get(activeKey);
+            if (existing !== undefined)
+                return { receipt: await existing, duplicate: true };
+            return {
+                receipt: {
+                    delivered: false,
+                    code: "monitor_wake_ambiguous",
+                    retryable: false,
+                    ambiguous: true,
+                },
+                duplicate: true,
+            };
+        }
+        this.retainHostWakeReservation(input.threadId);
+        const previous = this.hostWakeTails.get(input.threadId) ?? Promise.resolve();
+        const delivery = previous.catch(() => undefined).then(async () => {
+            const abandon = () => this.store.abandonMonitorWake({
+                sourceId: input.sourceId,
+                monitorId: input.monitor.monitorId,
+                deliveryKey: input.deliveryKey,
+            });
+            let connection = this.connections.get(input.sourceId);
+            if (connection === undefined) {
+                try {
+                    await this.refreshAgents();
+                }
+                catch (error) {
+                    abandon();
+                    this.options.logger?.debug?.("Web Monitor destination refresh failed before delivery.", {
+                        threadId: input.threadId,
+                        monitorId: input.monitor.monitorId,
+                        error: errorMessage(error),
+                    });
+                    return { delivered: false, code: "destination_channel_unavailable", retryable: true };
+                }
+                connection = this.connections.get(input.sourceId);
+            }
+            if (this.stopped || connection === undefined) {
+                abandon();
+                return { delivered: false, code: "destination_channel_unavailable", retryable: true };
+            }
+            const destination = this.store.getThread(input.threadId);
+            if (destination === undefined
+                || destination.sourceId !== input.sourceId
+                || destination.archivedAt !== null
+                || destination.trigger !== undefined) {
+                abandon();
+                return { delivered: false, code: "monitor_origin_mismatch", retryable: false };
+            }
+            const active = this.activeTurns.get(input.threadId);
+            if (active !== undefined
+                && connection.info.supportsLiveInput
+                && input.wakePrompt.length <= AGENT_LIVE_INPUT_MAX_CHARACTERS) {
+                try {
+                    const settlement = await active.client.liveInput({
+                        conversationId: `web:${input.threadId}`,
+                        id: input.deliveryKey,
+                        text: input.wakePrompt,
+                        receivedAt: new Date().toISOString(),
+                        deliveryKey: input.deliveryKey,
+                        signal: AbortSignal.timeout(10 * 60 * 1_000),
+                    });
+                    if (settlement.status === "applied") {
+                        const message = this.store.completeMonitorWake({
+                            sourceId: input.sourceId,
+                            monitorId: input.monitor.monitorId,
+                            deliveryKey: input.deliveryKey,
+                            disposition: "steered",
+                            turnId: active.turnId,
+                        });
+                        if (message !== undefined) {
+                            this.emit("message.changed", input.threadId, { messageId: message.id, updatedAt: message.updatedAt });
+                        }
+                        return { delivered: true, disposition: "steered" };
+                    }
+                }
+                catch (error) {
+                    this.options.logger?.warn?.("Web Monitor steering outcome is unknown; automatic fallback is suppressed.", {
+                        threadId: input.threadId,
+                        monitorId: input.monitor.monitorId,
+                        error: errorMessage(error),
+                    });
+                    return {
+                        delivered: false,
+                        code: "monitor_wake_ambiguous",
+                        retryable: false,
+                        ambiguous: true,
+                    };
+                }
+            }
+            if (active !== undefined)
+                await active.completion;
+            if (this.stopped) {
+                abandon();
+                return { delivered: false, code: "destination_channel_unavailable", retryable: true };
+            }
+            const refreshedConnection = this.connections.get(input.sourceId);
+            if (refreshedConnection === undefined) {
+                abandon();
+                return { delivered: false, code: "destination_channel_unavailable", retryable: true };
+            }
+            let started;
+            try {
+                started = this.store.beginAssistantTurn({
+                    threadId: input.threadId,
+                    prompt: input.wakePrompt,
+                    storedPrompt: "[Monitor wake]",
+                });
+            }
+            catch (error) {
+                abandon();
+                return {
+                    delivered: false,
+                    code: errorCode(error) ?? "monitor_wake_failed",
+                    retryable: false,
+                };
+            }
+            const completion = this.launchTurn(started, refreshedConnection.client, input.wakePrompt, input.deliveryKey);
+            this.emit("message.changed", input.threadId, {
+                messageId: started.assistantMessageId,
+                updatedAt: started.thread.updatedAt,
+            });
+            this.emit("turn.changed", input.threadId, { turn: started.thread.runState });
+            this.emit("threads.changed", input.threadId);
+            await completion;
+            if (this.store.turnStatus(started.turnId) !== "complete") {
+                return {
+                    delivered: false,
+                    code: "monitor_wake_failed",
+                    retryable: false,
+                    ambiguous: true,
+                };
             }
-            if (this.activeProcessJobWakes.get(activeKey) === delivery) {
-                this.activeProcessJobWakes.delete(activeKey);
+            const message = this.store.completeMonitorWake({
+                sourceId: input.sourceId,
+                monitorId: input.monitor.monitorId,
+                deliveryKey: input.deliveryKey,
+                disposition: "follow_up",
+                turnId: started.turnId,
+            });
+            if (message !== undefined) {
+                this.emit("message.changed", input.threadId, { messageId: message.id, updatedAt: message.updatedAt });
             }
-            this.releaseProcessJobWakeReservation(input.threadId);
+            return { delivered: true, disposition: "follow_up" };
+        });
+        const tail = delivery.then(() => undefined, () => undefined);
+        this.hostWakeTails.set(input.threadId, tail);
+        this.activeHostWakes.set(activeKey, delivery);
+        try {
+            return { receipt: await delivery, duplicate: false };
+        }
+        finally {
+            if (this.hostWakeTails.get(input.threadId) === tail)
+                this.hostWakeTails.delete(input.threadId);
+            if (this.activeHostWakes.get(activeKey) === delivery)
+                this.activeHostWakes.delete(activeKey);
+            this.releaseHostWakeReservation(input.threadId);
         }
     }
-    retainProcessJobWakeReservation(threadId) {
-        this.processJobWakeReservations.set(threadId, (this.processJobWakeReservations.get(threadId) ?? 0) + 1);
+    retainHostWakeReservation(threadId) {
+        this.hostWakeReservations.set(threadId, (this.hostWakeReservations.get(threadId) ?? 0) + 1);
     }
-    releaseProcessJobWakeReservation(threadId) {
-        const remaining = (this.processJobWakeReservations.get(threadId) ?? 1) - 1;
+    releaseHostWakeReservation(threadId) {
+        const remaining = (this.hostWakeReservations.get(threadId) ?? 1) - 1;
         if (remaining > 0)
-            this.processJobWakeReservations.set(threadId, remaining);
+            this.hostWakeReservations.set(threadId, remaining);
         else
-            this.processJobWakeReservations.delete(threadId);
+            this.hostWakeReservations.delete(threadId);
         if (!this.stopped)
             void this.drainQueuedLiveInputs(threadId);
     }
@@ -1092,13 +1411,22 @@ export class WebService {
             const changed = this.store.replaceAgents([]);
             this.connections = new Map();
             if (changed)
-                this.emit("agents.changed", undefined, { agents: this.store.listAgents() });
+                this.emit("agents.changed");
             return;
         }
         const nextConnections = new Map();
+        // What the cache is allowed to survive: the same process, at the same
+        // endpoint, since the same start. Anything else is a new generation whose
+        // catalog the previous one cannot speak for.
+        const generations = new Map(discovered.map((agent) => [
+            agent.source.sourceId,
+            agentGeneration(agent),
+        ]));
+        this.reconcileModelCatalogCache(generations);
         const summaries = await Promise.all(discovered.map(async (agent) => {
+            const generation = generations.get(agent.source.sourceId);
             if (agent.baseUrl === undefined)
-                return offlineSummary(agent);
+                return offlineSummary(agent, generation);
             const client = new OperatorClient({
                 baseUrl: agent.baseUrl,
                 ...(agent.apiKey === undefined ? {} : { apiKey: agent.apiKey }),
@@ -1108,9 +1436,11 @@ export class WebService {
             try {
                 const info = await client.info(AbortSignal.any([signal, AbortSignal.timeout(INFO_TIMEOUT_MS)]));
                 nextConnections.set(agent.source.sourceId, { client, info });
+                this.seedModelCatalogFromOptions(agent.source.sourceId, generation, info.modelOptions);
                 const efforts = collectEfforts(info);
                 return {
                     sourceId: agent.source.sourceId,
+                    generation,
                     label: info.label ?? agent.source.label,
                     status: agent.source.health === "running" ? "online" : "degraded",
                     pinned: false,
@@ -1121,6 +1451,7 @@ export class WebService {
                     ...(info.effort === undefined ? {} : { defaultEffort: info.effort }),
                     ...(efforts.length === 0 ? {} : { efforts }),
                     ...(info.modelOptions === undefined ? {} : { modelOptions: info.modelOptions }),
+                    ...(info.providers === undefined ? {} : { providers: info.providers }),
                     ...(info.cron === undefined ? {} : { cron: info.cron }),
                     ...(info.supportsAskById ? { supportsAskById: true } : {}),
                     updatedAt: agent.source.updatedAt,
@@ -1131,7 +1462,7 @@ export class WebService {
                     sourceId: agent.source.sourceId,
                     error: errorMessage(error),
                 });
-                return offlineSummary(agent);
+                return offlineSummary(agent, generation);
             }
         }));
         this.connections = nextConnections;
@@ -1154,7 +1485,7 @@ export class WebService {
             }
         }));
         if (agentsChanged)
-            this.emit("agents.changed", undefined, { agents: this.store.listAgents() });
+            this.emit("agents.changed");
         for (const sourceId of cronChangedSources)
             this.emit("cron.changed", undefined, { sourceId });
         if (cronChangedSources.size > 0)
@@ -1353,6 +1684,116 @@ export class WebService {
         }
         return connection;
     }
+    /**
+     * Tier-2 admission: the catalog cache, seeded from `modelOptions` keys and
+     * appended to by every proxied `/v1/models` page.
+     *
+     * Both feeds cross an await between deciding what to admit and admitting it,
+     * so both name the generation they read. A write whose generation is no
+     * longer the one on file is dropped outright rather than filed under the
+     * successor: it describes a process that has been replaced, and admitting it
+     * is exactly the cross-generation contamination `reconcileModelCatalogCache`
+     * exists to prevent. Nothing is created here either -- an entry exists for
+     * every discovered source from the moment a refresh reconciles it, and a
+     * source with no entry is one discovery has dropped.
+     *
+     * @returns whether the refs were admitted.
+     */
+    admitCatalogRefs(sourceId, generation, refs) {
+        if (generation === undefined)
+            return false;
+        const entry = this.modelCatalogCache.get(sourceId);
+        if (entry === undefined || entry.generation !== generation)
+            return false;
+        for (const [ref, record] of refs)
+            this.admitModelRef(entry.models, ref, record);
+        return true;
+    }
+    /**
+     * Bind the cache to the agent process that filled it, and to nothing else.
+     * A source id outlives the process behind it: reconfigure an agent and
+     * restart it and the next generation advertises a different catalog under
+     * the same id. Keyed by id alone, generation 1's ladder judged generation
+     * 2's turns and rejected grades the running agent accepts, with no way to
+     * clear it short of restarting the console.
+     *
+     * The single place the cache is scoped, so there is one answer to "whose
+     * catalog is this". Runs before the per-agent probes of a refresh, so a seed
+     * or a proxied page during that refresh files under the current generation.
+     * Sources discovery no longer reports are dropped outright, or a retired
+     * agent's refs would accumulate for the life of the process.
+     */
+    reconcileModelCatalogCache(generations) {
+        for (const sourceId of [...this.modelCatalogCache.keys()]) {
+            if (!generations.has(sourceId))
+                this.modelCatalogCache.delete(sourceId);
+        }
+        for (const [sourceId, generation] of generations) {
+            if (this.modelCatalogCache.get(sourceId)?.generation === generation)
+                continue;
+            this.modelCatalogCache.set(sourceId, { generation, models: new Map() });
+        }
+    }
+    seedModelCatalogFromOptions(sourceId, generation, modelOptions) {
+        if (modelOptions === undefined)
+            return;
+        // `modelOptions` stays the authority for the refs it names, so the seed
+        // only records admission; recording a ladder here would shadow it.
+        this.admitCatalogRefs(sourceId, generation, Object.keys(modelOptions).map((key) => [key, { source: "shortlist", efforts: undefined }]));
+    }
+    admitModelRef(entries, ref, record) {
+        const known = entries.get(ref);
+        if (known !== undefined) {
+            // A page is the live word on what it serves, so its metadata replaces
+            // whatever is held -- including replacing a ladder with silence, which
+            // is how a re-fetched catalog heals a model whose grades changed. The
+            // shortlist seed only records admission and must never shadow a page.
+            // Re-setting an existing key leaves its eviction position alone.
+            if (record.source === "page")
+                entries.set(ref, record);
+            return;
+        }
+        entries.set(ref, record);
+        if (entries.size > MODEL_CATALOG_CACHE_CAP) {
+            const oldest = entries.keys().next().value;
+            if (oldest !== undefined)
+                entries.delete(oldest);
+        }
+    }
+    validateModelAndEffort(sourceId, agent, model, effort) {
+        if (model !== undefined && !this.modelAdmitted(sourceId, agent, model)) {
+            throw new WebConsoleError("invalid_model", "This agent did not advertise the selected model.", 400);
+        }
+        // Both ends resolve a blank selection to the same route -- the browser fell
+        // back to the first shortlist entry while this stopped at `defaultModel`,
+        // so any `/v1/info` omitting `model` had the picker offering one ladder and
+        // this rejecting from another.
+        const effectiveModel = effectiveModelForAgent(agent, model);
+        // `modelOptions` only ever covers the configured shortlist, so a model
+        // reached through the provider catalog has no entry there. `effort-ladder`
+        // holds the tiering, and the browser runs the exact same function, so the
+        // picker cannot offer a grade this rejects or hide one it accepts.
+        const cached = effectiveModel === undefined
+            ? undefined
+            : this.modelCatalogCache.get(sourceId)?.models.get(effectiveModel);
+        const allowedEfforts = effortLevelsForModel(agent, effectiveModel, cached?.efforts);
+        if (effort !== undefined && !allowedEfforts.includes(effort)) {
+            throw new WebConsoleError("invalid_effort", "This agent did not advertise the selected effort for this model.", 400);
+        }
+    }
+    modelAdmitted(sourceId, agent, model) {
+        // Tier 1: the configured-route shortlist — unchanged, always allowed.
+        if (agent.models === undefined ? model === agent.defaultModel : agent.models.includes(model))
+            return true;
+        // Tier 2: a model reached only through the catalog cache.
+        const cached = this.modelCatalogCache.get(sourceId);
+        if (cached !== undefined && cached.models.has(model))
+            return true;
+        // Tier 3: syntactic `<provider>:<model>` floor. The web package has no pi-ai
+        // access, so a well-formed ref passes here and the agent itself is the real
+        // gate at turn time.
+        return modelPassesSyntacticFloor(model);
+    }
     authorizeReplyPart(threadId, messageId, partId, type, expires, token) {
         const access = this.replyAccessTokenStatus(threadId, messageId, type, partId, expires, token);
         if (access === "invalid") {
@@ -1385,6 +1826,10 @@ export class WebService {
         }
     }
     decorateThreadDetail(detail) {
+        // Backfill: messages that predate this feature, and any turn whose own
+        // attempt failed or was interrupted. Idempotent and guarded, so repeated
+        // reads of the same thread fetch each image at most once.
+        void this.persistReplyImages(detail.thread.id, detail.messages);
         return { ...detail, messages: detail.messages.map((message) => this.decorateMessage(message)) };
     }
     decorateMessage(message) {
@@ -1395,14 +1840,123 @@ export class WebService {
         });
         return { ...message, parts };
     }
+    /**
+     * Keeps the console's own copy of an image the agent published.
+     *
+     * Reply artifacts are proxied from the agent and never stored, so without this
+     * a generated image dies at the agent's retention deadline and shows broken
+     * whenever that agent is stopped. Raster types only: `image/svg+xml` is active
+     * content, is refused inline by both the client and `setReplyDownloadHeaders`,
+     * and is deliberately never persisted either.
+     *
+     * Entirely best-effort. Every failure leaves the part on its existing
+     * capability path, because a stored copy is an optimisation and a turn must
+     * never fail over one.
+     */
+    async persistReplyImages(threadId, messages) {
+        for (const message of messages) {
+            for (const part of message.parts) {
+                if (part.type !== "attachment")
+                    continue;
+                if (!REPLY_IMAGE_MEDIA_TYPES.has(part.mediaType.toLowerCase()))
+                    continue;
+                if (part.sizeBytes > DEFAULT_AGENT_ATTACHMENT_MAX_BYTES)
+                    continue;
+                if (this.store.storedReplyAttachment(message.id, part.id) !== undefined)
+                    continue;
+                const key = WebStore.replyAttachmentId(message.id, part.id);
+                if (this.persistingReplyImages.has(key))
+                    continue;
+                this.persistingReplyImages.add(key);
+                try {
+                    await this.persistReplyImage(threadId, message, part);
+                }
+                catch (error) {
+                    this.options.logger?.debug?.("Web reply image was not persisted.", {
+                        threadId,
+                        messageId: message.id,
+                        partId: part.id,
+                        error: errorMessage(error),
+                    });
+                }
+                finally {
+                    this.persistingReplyImages.delete(key);
+                }
+            }
+        }
+    }
+    async persistReplyImage(threadId, message, part) {
+        const thread = this.store.getThread(threadId);
+        if (thread === undefined)
+            return;
+        const connection = this.connections.get(thread.sourceId);
+        if (connection === undefined || connection.info.replyAttachments?.version !== 1)
+            return;
+        const response = await connection.client.replyArtifact(this.conversationIdForThread(thread.id), {
+            type: "attachment",
+            id: part.id,
+            reference: { scheme: "mono-agent-artifact", id: part.artifactId },
+            name: part.name,
+            mediaType: part.mediaType,
+            sizeBytes: part.sizeBytes,
+            integrityId: part.integrityId,
+            ...(part.expiresAt === undefined ? {} : { expiresAt: part.expiresAt }),
+        });
+        if (!response.ok || response.body === null)
+            return;
+        const bytes = Buffer.from(await response.arrayBuffer());
+        // The same pair the browser checks before handing a download to the user. A
+        // copy that fails either is not written at all, so a corrupt artifact can
+        // never be served from a stable URL that outlives its source.
+        if (bytes.byteLength !== part.sizeBytes)
+            return;
+        const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+        if (digest !== part.integrityId.toLowerCase())
+            return;
+        const storageName = `${randomUUID()}.bin`;
+        const destination = this.store.attachmentPath({ storageName });
+        const staging = `${destination}.partial-${randomUUID()}`;
+        await writeFile(staging, bytes, { mode: 0o600 });
+        try {
+            await rename(staging, destination);
+        }
+        catch (error) {
+            await unlink(staging).catch(() => undefined);
+            throw error;
+        }
+        try {
+            this.store.recordReplyAttachment({
+                threadId: thread.id,
+                messageId: message.id,
+                partId: part.id,
+                name: part.name,
+                contentType: part.mediaType,
+                sizeBytes: bytes.byteLength,
+                storageName,
+            });
+        }
+        catch (error) {
+            await unlink(destination).catch(() => undefined);
+            throw error;
+        }
+    }
     decorateReplyPart(message, part) {
+        // A durable copy is resolved before the retention gate below, because
+        // outliving that deadline is the entire reason it was kept.
+        const stored = part.type === "attachment"
+            ? this.store.storedReplyAttachment(message.id, part.id)
+            : undefined;
+        const storedUrl = stored === undefined
+            ? {}
+            : { storedUrl: `/api/v1/uploads/${encodeURIComponent(stored.id)}/content` };
         const now = this.currentDate().getTime();
         const retentionDeadline = part.expiresAt === undefined
             ? Number.POSITIVE_INFINITY
             : Date.parse(part.expiresAt);
         const expiresAt = Math.min(now + REPLY_ACCESS_TTL_MS, retentionDeadline);
-        if (!Number.isFinite(expiresAt) || expiresAt <= now)
-            return part;
+        if (!Number.isFinite(expiresAt) || expiresAt <= now) {
+            return part.type === "attachment" ? { ...part, ...storedUrl } : part;
+        }
         const expires = String(Math.floor(expiresAt / 1_000));
         const token = this.replyAccessToken(message.threadId, message.id, part.type, part.id, expires);
         const base = `/api/v1/threads/${encodeURIComponent(message.threadId)}`
@@ -1411,6 +1965,7 @@ export class WebService {
         return part.type === "attachment"
             ? {
                 ...part,
+                ...storedUrl,
                 contentUrl: `${base}/reply-attachments/${encodeURIComponent(part.id)}/content?${query}`,
             }
             : {
@@ -1619,9 +2174,53 @@ export class WeightedTurnBudget {
         }
     }
 }
-function offlineSummary(agent) {
+/**
+ * The identity of the agent PROCESS behind a source id. `sourceId` is stable
+ * across restarts by design, so it cannot scope anything the running process
+ * told us: a reconfigured agent restarts at a new endpoint, with a new pid and
+ * a new `startedAt`, and advertises a different catalog under the same id.
+ * Deliberately excludes `updatedAt`, which every heartbeat moves.
+ *
+ * This is what the model catalog cache is scoped to -- and, since the browser
+ * caches the same `/v1/models` pages and had nothing generation-shaped to
+ * watch, what `WebAgentSummary.generation` carries to it.
+ *
+ * Hashed because it now goes on the wire: the raw form names the agent's
+ * operator endpoint and pid, and the console has no reason to hand those to a
+ * page. The token only has to be stable while one process lives and different
+ * once it is replaced, which a digest of those three fields is.
+ *
+ * Length-prefixed rather than `|`-joined. A separator that can occur inside a
+ * field is not a separator: two different accepted tuples whose parts happen to
+ * contain the delimiter flatten to the same string and hash to the same token,
+ * and two distinct processes sharing a generation is precisely the state the
+ * token exists to make impossible. Nothing first-party produces such a tuple
+ * today, which is why this is robustness rather than a live defect --- but a
+ * digest whose only defence is what its inputs happen to look like is one
+ * unrelated change away from being wrong.
+ *
+ * Hashed as UTF-16 code units for the same reason the prefix replaced the
+ * delimiter. UTF-8 has no encoding for an unpaired surrogate, so a lone high
+ * surrogate and a lone low surrogate both became the replacement character and
+ * two different one-character fields -- identically length-prefixed -- hashed
+ * alike. `utf16le` is a lossless transcription of exactly the code units the
+ * length prefix counts, so what is hashed is what was measured.
+ */
+export function agentGeneration(agent) {
+    const parts = [
+        agent.baseUrl ?? "",
+        String(agent.source.pid ?? ""),
+        agent.source.startedAt,
+    ];
+    return createHash("sha256")
+        .update(parts.map((part) => `${String(part.length)}:${part}`).join(""), "utf16le")
+        .digest("hex")
+        .slice(0, 16);
+}
+function offlineSummary(agent, generation) {
     return {
         sourceId: agent.source.sourceId,
+        generation,
         label: agent.source.label,
         status: "offline",
         pinned: false,
@@ -1637,32 +2236,25 @@ function collectEfforts(info) {
     if (info.modelOptions === undefined)
         return EFFORT_LEVELS;
     const models = info.models ?? (info.model === undefined ? [] : [info.model]);
-    return [...new Set(models.flatMap((model) => effortLevelsForOption(info.modelOptions?.[model])))];
-}
-function validateModelAndEffort(agent, model, effort) {
-    if (model !== undefined
-        && (agent.models === undefined ? model !== agent.defaultModel : !agent.models.includes(model))) {
-        throw new WebConsoleError("invalid_model", "This agent did not advertise the selected model.", 400);
-    }
-    const effectiveModel = model ?? agent.defaultModel;
-    const option = effectiveModel === undefined ? undefined : agent.modelOptions?.[effectiveModel];
-    const allowedEfforts = agent.modelOptions === undefined
-        ? agent.efforts
-        : effortLevelsForOption(option);
-    if (effort !== undefined && (allowedEfforts === undefined || !allowedEfforts.includes(effort))) {
-        throw new WebConsoleError("invalid_effort", "This agent did not advertise the selected effort for this model.", 400);
-    }
+    // Same rule as every other effort decision, so the union an agent advertises
+    // cannot disagree with what a turn on one of those models may carry.
+    return [...new Set(models.flatMap((model) => effortLevelsForModel(info, model, undefined)))];
 }
-function effortLevelsForOption(option) {
-    if (option === undefined
-        || option.reasoning === false
-        || option.reasoningMode === "none"
-        || option.effortLevels?.length === 0) {
-        return [];
-    }
-    if (option.reasoningMode === "toggle")
-        return ["high", "none"];
-    return option.effortLevels ?? [];
+/**
+ * Tier 3: the syntactic floor. `@mono-agent/web` may not import pi-ai, so this
+ * cannot be authoritative -- the agent is. It exists to reject obvious garbage,
+ * and it must not be looser than the runtime parser, or a reference the console
+ * accepts is silently ignored and the turn runs on the default model instead.
+ */
+function modelPassesSyntacticFloor(model) {
+    const separator = model.indexOf(":");
+    if (separator <= 0 || separator >= model.length - 1)
+        return false;
+    const provider = model.slice(0, separator);
+    const rest = model.slice(separator + 1);
+    // Provider ids are lowercase kebab/alphanumeric; the model half may carry
+    // further colons and slashes but must not be blank or padded.
+    return /^[a-z0-9][a-z0-9-]*$/u.test(provider) && rest.trim() === rest && rest.trim().length > 0;
 }
 function normalizeFilename(value) {
     const withoutPath = value.replace(/\\/gu, "/").split("/").at(-1)?.trim() ?? "";