@nocobase/app-plugin-agents 1.0.0-beta.26 → 1.0.0-beta.28

package/dist/server/core/conversations/conversation.service.js

@@ -1,4 +1,4 @@
-import { outputBlock } from '@nocobase/agent-protocol';
+import { outputBlock, TERMINAL_RUN_STATUSES } from '@nocobase/agent-protocol';
 import { historicalPageContext, hasContent, renderPageContext, } from './page-context.js';
 import { nativeExecutionStatus, runnerBinding, } from '../../online/agent/persistence/state.js';
 /**
@@ -28,14 +28,19 @@ import { asJson, jsonObject } from '../../kernel/values.js';
 import { findAgent } from '../agents/index.js';
 import { agentNamesOf } from '../agents/agent.store.js';
 import { eventsAfter, hasSession, lastSummary, openRunsOnEach, queuedRun, } from '../runs/index.js';
-import { findRunRecord, toRun } from '../runs/run.store.js';
+import { eventsRepo, findRunRecord, inputsRepo, runsRepo, sessionsRepo, toRun, } from '../runs/run.store.js';
 import { readAttachmentIds, storedAttachments, } from './attachments.js';
 import { availabilityOf, wakeable } from './availability.js';
-import { appendMessage, conversationsRepo, findConversation, findDraft, metadataOf, rewriteMessage, lockConversation, messagesRepo, toMessage, updateMessageRun, } from './conversation.store.js';
+import { appendMessage, conversationsRepo, findConversation, findDraft, metadataOf, queuedRevision, rewriteMessage, lockConversation, messagesRepo, toMessage, updateMessageRun, } from './conversation.store.js';
 import { attachmentLines, conversationContext, conversationKey, conversationSystemLayer, conversationTask, conversationTurn, conversationUrl, } from './prompt.js';
 import { autoTitle, cleanTitle } from './titles.js';
+import { createConversationLinks } from './links.js';
 /** Events read per page while turning a run's events into messages. */
 const SYNC_PAGE = 500;
+/** Archived conversations one purge pass reads at a time, the most it deletes, and how long it may take. */
+const ARCHIVED_PURGE_BATCH = 50;
+const ARCHIVED_PURGE_LIMIT = 1000;
+const ARCHIVED_PURGE_TIME_MS = 5 * 60_000;
 function conversationConflict(reason, message) {
     return new ProtocolError('CONVERSATION_CONFLICT', message, { reason });
 }
@@ -100,6 +105,8 @@ function noticeText(notice, names) {
             return `${name(notice.fromAgentId)} has no runner for you now, so ${name(notice.agentId)} answers until you switch back.`;
         case 'onlineFallbackUnavailable':
             return `The online fallback agent cannot answer (${notice.reason}). This conversation stays with ${name(notice.fromAgentId)} while it waits for a runner.`;
+        case 'switchedAgent':
+            return `This conversation now uses ${name(notice.agentId)}. The conversation history is preserved.`;
         case 'switchedBack':
             return `This conversation is back with ${name(notice.agentId)}.`;
         case 'runFailed':
@@ -150,6 +157,39 @@ function onlineExecution(record, open = [], active = false) {
         ...(call.requiresEffectReview ? { requiresEffectReview: true } : {}),
     };
 }
+/** At most this many characters of what an agent asks its owner are kept. */
+const QUESTION_MAX = 500;
+function needsYouOf(record) {
+    const reason = record.needsYou;
+    if (!reason ||
+        record.needsYouSeq === null ||
+        record.needsYouSeq === undefined)
+        return null;
+    return {
+        reason,
+        seq: Number(record.needsYouSeq),
+        text: record.needsYouText ?? null,
+    };
+}
+/** What settles what waits for the owner. */
+const SETTLED = {
+    needsYou: null,
+    needsYouSeq: null,
+    needsYouText: null,
+};
+function runnerOf(id, runner) {
+    if (!runner)
+        return { id, name: null, status: 'missing' };
+    return {
+        id,
+        name: runner.name,
+        status: runner.status === 'online'
+            ? 'online'
+            : runner.status === 'revoked'
+                ? 'revoked'
+                : 'offline',
+    };
+}
 export function createConversationService(deps) {
     const { tx, ids, clock } = deps;
     const now = () => clock.now().toISOString();
@@ -157,6 +197,13 @@ export function createConversationService(deps) {
     const viewOf = (record) => toMessage(record, deps.basePath?.() ?? '');
     const rules = [];
     const sources = createSources();
+    const links = createConversationLinks({
+        tx,
+        ids,
+        now,
+        refOf,
+        changed: (unit, record) => changed(unit, record),
+    });
     // -------------------------------------------------------------------------------------------------------------------
     // Reading
     // -------------------------------------------------------------------------------------------------------------------
@@ -203,6 +250,10 @@ export function createConversationService(deps) {
                 if (id && !agents.has(id))
                     agents.set(id, await findAgent(conn, id));
         const open = await openRunsOnEach(conn, CONVERSATION_SUBJECT, records.map((record) => record.id));
+        const runnerIds = [
+            ...new Set(records.flatMap((record) => (record.runnerId ? [record.runnerId] : []))),
+        ];
+        const machines = new Map((runnerIds.length ? await deps.runners.all(conn, runnerIds) : []).map((runner) => [runner.id, runner]));
         return Promise.all(records.map(async (record) => ({
             id: record.id,
             title: record.title,
@@ -232,6 +283,12 @@ export function createConversationService(deps) {
             createdAt: record.createdAt,
             updatedAt: record.updatedAt,
             run: runRef(open.filter((run) => run.subject.id === record.id)),
+            runner: record.runnerId
+                ? runnerOf(record.runnerId, machines.get(record.runnerId))
+                : null,
+            lastSeq: Number(record.lastSeq),
+            seenSeq: Number(record.seenSeq ?? 0),
+            needsYou: needsYouOf(record),
         })));
     }
     async function systemDefault(conn, userId) {
@@ -305,12 +362,16 @@ export function createConversationService(deps) {
     // -------------------------------------------------------------------------------------------------------------------
     // Writing
     // -------------------------------------------------------------------------------------------------------------------
-    function changed(unit, record, lastSeq) {
+    function changed(unit, record, at) {
         unit.emit({
             type: 'conversation.changed',
             conversationId: record.id,
             userId: record.userId,
-            ...(lastSeq === undefined ? {} : { lastSeq }),
+            ...(at === undefined
+                ? {}
+                : typeof at === 'number'
+                    ? { lastSeq: at }
+                    : at),
         });
     }
     async function append(unit, record, message) {
@@ -348,7 +409,8 @@ export function createConversationService(deps) {
         }
         const agentIds = value.code === 'switchedToDefault' ||
             value.code === 'switchedToOnline' ||
-            value.code === 'switchedBack'
+            value.code === 'switchedBack' ||
+            value.code === 'switchedAgent'
             ? [value.agentId, value.fromAgentId]
             : value.code === 'onlineFallbackUnavailable'
                 ? [value.fromAgentId]
@@ -427,10 +489,13 @@ export function createConversationService(deps) {
      * Moves the conversation to `agent`: its queued work is withdrawn, the thread moves on (a new session), and the
      * messages nobody answered go to the new agent.
      */
-    async function rebind(unit, record, agent, fallbackFromAgentId, value) {
-        if (runnerBinding(record.metadata))
+    async function rebind(unit, record, agent, fallbackFromAgentId, value, idleOnly = false) {
+        const binding = runnerBinding(record.metadata);
+        if (binding && !idleOnly)
             throw conflict('Start a new conversation to choose another agent.');
-        const withdrawn = await deps.runs.withdrawQueued({ subject: subjectOf(record.id), byUserId: record.userId }, unit);
+        const withdrawn = idleOnly
+            ? []
+            : await deps.runs.withdrawQueued({ subject: subjectOf(record.id), byUserId: record.userId }, unit);
         await conversationsRepo(unit.conn).updateMany({
             filter: { id: record.id },
             values: {
@@ -439,11 +504,27 @@ export function createConversationService(deps) {
                 modelService: null,
                 model: null,
                 fallbackFromAgentId,
+                ...(binding
+                    ? {
+                        metadata: asJson({
+                            ...jsonObject(record.metadata),
+                            runnerOnlineAgent: {
+                                ...binding,
+                                config: { ...binding.config, agentId: agent.id },
+                            },
+                        }),
+                    }
+                    : {}),
                 thread: Number(record.thread) + 1,
+                runnerId: null,
                 updatedAt: now(),
             },
         });
         const moved = (await findConversation(unit.conn, record.id));
+        if (idleOnly) {
+            await notice(unit, moved, value);
+            return moved;
+        }
         const runIds = withdrawn.map((run) => run.id);
         const unanswered = await messagesRepo(unit.conn).findMany({
             filter: (f) => f.and([
@@ -458,6 +539,7 @@ export function createConversationService(deps) {
         });
         await notice(unit, moved, value);
         await wake(unit, moved, unanswered);
+        return moved;
     }
     // -------------------------------------------------------------------------------------------------------------------
     // Turning run events into messages
@@ -487,6 +569,10 @@ export function createConversationService(deps) {
             const events = await eventsAfter(unit.conn, run.id, after, SYNC_PAGE);
             for (const event of events) {
                 after = Number(event.seq);
+                if (event.type === 'input') {
+                    await pickUp(unit, record, jsonObject(event.meta).inputId);
+                    continue;
+                }
                 const text = event.type === 'text' ? (event.content ?? '') : '';
                 const meta = jsonObject(event.meta);
                 const output = event.type === 'text' ? outputBlock(meta) : undefined;
@@ -521,6 +607,118 @@ export function createConversationService(deps) {
                 values: { syncRunId: run.id, syncSeq: after },
             });
     }
+    /** A queued message the agent took (its run's `input` event): it is no longer waiting. */
+    async function pickUp(unit, record, inputId) {
+        if (typeof inputId !== 'string')
+            return;
+        const [message] = await messagesRepo(unit.conn).findMany({
+            filter: (f) => f.and([
+                f.string('conversationId').eq(record.id),
+                f.string('role').eq('user'),
+                f.json('metadata').path(['inputId']).eq(inputId),
+            ]),
+            limit: 1,
+        });
+        const metadata = message ? jsonObject(message.metadata) : {};
+        if (!message || !metadata.queued || metadata.pickedUp)
+            return;
+        await messagesRepo(unit.conn).updateMany({
+            filter: { id: message.id },
+            values: {
+                metadata: asJson({ ...metadata, pickedUp: true }),
+                updatedAt: now(),
+            },
+        });
+        changed(unit, record, {
+            messageId: message.id,
+            revision: queuedRevision(message.seq, 'pickedUp'),
+        });
+    }
+    /** Deletes the runs of `ids` with everything they recorded. */
+    async function deleteRuns(conn, ids) {
+        for (let start = 0; start < ids.length; start += 200) {
+            const chunk = ids.slice(start, start + 200);
+            for (const name of [
+                'agRunEvents',
+                'agRunUsage',
+                'agRunInputs',
+                'agRunTokens',
+                'agRunRepos',
+                'agRunBriefs',
+            ])
+                await conn.repository(name).deleteMany({
+                    filter: (f) => f.or(chunk.map((id) => f.string('runId').eq(id))),
+                });
+            await runsRepo(conn).deleteMany({
+                filter: (f) => f.or(chunk.map((id) => f.string('id').eq(id))),
+            });
+        }
+    }
+    /** Ended runs of conversations deleted while those runs were still stopping, a batch at a time. */
+    async function purgeOrphanRuns() {
+        const conn = tx.read();
+        const ended = await runsRepo(conn).findMany({
+            filter: (f) => f.and([
+                f.string('subjectKind').eq(CONVERSATION_SUBJECT),
+                f.or(TERMINAL_RUN_STATUSES.map((status) => f.string('status').eq(status))),
+            ]),
+            sort: (sort) => sort.field('id').asc(),
+            limit: 500,
+        });
+        const subjects = [...new Set(ended.map((run) => String(run.subjectId)))];
+        if (subjects.length === 0)
+            return;
+        const kept = new Set((await conversationsRepo(conn).findMany({
+            filter: (f) => f.or(subjects.map((id) => f.string('id').eq(id))),
+        })).map((record) => String(record.id)));
+        const orphans = ended
+            .filter((run) => !kept.has(String(run.subjectId)))
+            .map((run) => String(run.id));
+        if (orphans.length)
+            await tx.run((unit) => deleteRuns(unit.conn, orphans));
+    }
+    /**
+     * Deletes `record` inside `unit`: cancels its open runs (as `by`), deletes its messages, files, links and kept
+     * sessions and the conversation, and announces the change (which settles its inbox notices). Answers what removes
+     * the files' bytes once the transaction committed.
+     */
+    async function remove(unit, record, by) {
+        for (const run of await openRunsOnEach(unit.conn, CONVERSATION_SUBJECT, [
+            record.id,
+        ]))
+            await deps.runs.cancel(run.id, by, unit);
+        const released = deps.attachments
+            ? await deps.attachments.release(unit.conn, record.id)
+            : async () => { };
+        await messagesRepo(unit.conn).deleteMany({
+            filter: { conversationId: record.id },
+        });
+        await unit.conn
+            .repository('agConversationLinks')
+            .deleteMany({ filter: { conversationId: record.id } });
+        // Runners remove the directories and session files on their next report: the conversation is gone (`settled`).
+        await sessionsRepo(unit.conn).deleteMany({
+            filter: { subjectKind: CONVERSATION_SUBJECT, subjectId: record.id },
+        });
+        // Its finished runs and what they recorded; one still stopping goes once it ended (`purgeOrphanRuns`).
+        await deleteRuns(unit.conn, (await runsRepo(unit.conn).findMany({
+            filter: (f) => f.and([
+                f.string('subjectKind').eq(CONVERSATION_SUBJECT),
+                f.string('subjectId').eq(record.id),
+                f.or(TERMINAL_RUN_STATUSES.map((status) => f.string('status').eq(status))),
+            ]),
+        })).map((run) => String(run.id)));
+        await conversationsRepo(unit.conn).deleteMany({
+            filter: { id: record.id },
+        });
+        changed(unit, record);
+        unit.emit({
+            type: 'conversation.deleted',
+            conversationId: record.id,
+            userId: record.userId,
+        });
+        return released;
+    }
     // -------------------------------------------------------------------------------------------------------------------
     // The run subject
     // -------------------------------------------------------------------------------------------------------------------
@@ -539,6 +737,11 @@ export function createConversationService(deps) {
             ownerName,
             cli: claim.cli,
         })));
+        const linked = await links.turnSection(conn, conversation);
+        const turnSections = [
+            ...(linked ? [linked] : []),
+            ...added.flatMap((lines) => lines.turn ?? []),
+        ];
         return {
             subject: {
                 key,
@@ -566,7 +769,10 @@ export function createConversationService(deps) {
                 history,
             }),
             turn: {
-                prompt: conversationTurn(claim.inputs.length),
+                prompt: [
+                    conversationTurn(claim.inputs.length),
+                    ...turnSections.map((section) => section.join('\n')),
+                ].join('\n\n'),
                 ...(previousSummary ? { previousSummary } : {}),
             },
             data: {
@@ -582,8 +788,53 @@ export function createConversationService(deps) {
             scopes: [],
         };
     }
+    /**
+     * After a turn ended: the conversation waits for its owner when they have not seen all of it, or when its agent asked
+     * them something; announced once per turn.
+     */
+    async function attend(unit, id, run) {
+        if (run.status !== 'completed' && run.status !== 'failed')
+            return;
+        const record = await findConversation(unit.conn, id);
+        if (!record || record.archivedAt)
+            return;
+        const seq = Number(record.lastSeq);
+        // A failed run asked nothing it can still be answered on: the failure is what waits.
+        const reason = run.status === 'failed'
+            ? 'failed'
+            : record.needsYou === 'confirm'
+                ? 'confirm'
+                : 'reply';
+        if (reason !== 'confirm' && seq <= Number(record.seenSeq ?? 0))
+            return;
+        const text = reason === 'confirm' ? (record.needsYouText ?? null) : null;
+        await conversationsRepo(unit.conn).updateMany({
+            filter: { id },
+            values: { needsYou: reason, needsYouSeq: seq, needsYouText: text },
+        });
+        changed(unit, record);
+        unit.emit({
+            type: 'conversation.attention',
+            conversationId: id,
+            userId: record.userId,
+            reason,
+            seq,
+            title: record.title,
+            text,
+        });
+    }
     const binding = {
         kind: CONVERSATION_SUBJECT,
+        // A deleted conversation's work is over: runners remove what they keep for it.
+        workspaces: {
+            async settled(conn, subjectIds) {
+                const kept = await conversationsRepo(conn).findMany({
+                    filter: (f) => f.or(subjectIds.map((id) => f.string('id').eq(id))),
+                });
+                const known = new Set(kept.map((record) => String(record.id)));
+                return new Set(subjectIds.filter((id) => !known.has(id)));
+            },
+        },
         private: true,
         title: { key: 'subjects.conversation', ns: ACCESS_NAMESPACE },
         triggers: CONVERSATION_TRIGGERS,
@@ -617,7 +868,8 @@ export function createConversationService(deps) {
                 if (!record || record.userId !== claim.run.actorUserId)
                     throw new Error('The conversation is gone.');
                 const ownerName = await nameOf(conn, record.userId);
-                const fresh = !claim.runner ||
+                const fresh = claim.freshSession === true ||
+                    !claim.runner ||
                     !(await hasSession(conn, {
                         agentId: claim.agent.id,
                         runnerId: claim.runner.id,
@@ -639,7 +891,8 @@ export function createConversationService(deps) {
                         limit: CONVERSATION_HISTORY_IN_PROMPT + pending.size,
                     });
                     history = recent
-                        .filter((message) => !pending.has(message.id))
+                        .filter((message) => !pending.has(message.id) &&
+                        !jsonObject(message.metadata).withdrawn)
                         .slice(0, CONVERSATION_HISTORY_IN_PROMPT)
                         .reverse()
                         .map((message) => {
@@ -686,6 +939,29 @@ export function createConversationService(deps) {
                     : assembly;
             },
         },
+        runnerPin: {
+            async runnerOf(conn, run) {
+                const record = await findConversation(conn, run.subject.id);
+                if (!record || record.userId !== run.actorUserId)
+                    return null;
+                return record.runnerId ?? null;
+            },
+            async pin(unit, run, runner) {
+                const record = await findConversation(unit.conn, run.subject.id);
+                if (!record || record.userId !== run.actorUserId)
+                    return true;
+                if (record.runnerId)
+                    return record.runnerId === runner.id;
+                const bound = await conversationsRepo(unit.conn).updateMany({
+                    filter: (f) => f.and([f.string('id').eq(record.id), f.string('runnerId').empty()]),
+                    values: { runnerId: runner.id },
+                });
+                if (bound.updatedCount !== 1)
+                    return false;
+                changed(unit, record);
+                return true;
+            },
+        },
         sink: {
             async onRunFinished(unit, run) {
                 await syncIn(unit, run);
@@ -733,9 +1009,27 @@ export function createConversationService(deps) {
                     }, now());
                     changed(unit, record, Number(draft.seq));
                 }
-                if (run.status !== 'failed')
-                    return;
-                await notice(unit, record, { code: 'runFailed', runId: run.id, reason: run.failureReason }, run.id);
+                if (run.status === 'failed')
+                    await notice(unit, record, { code: 'runFailed', runId: run.id, reason: run.failureReason }, run.id);
+                // The run's response now closes with its turn's footer, one revision on: a page showing it rereads it.
+                const [answered] = await messagesRepo(unit.conn).findMany({
+                    filter: (f) => f.and([
+                        f.string('conversationId').eq(record.id),
+                        f.string('runId').eq(run.id),
+                        f.or([
+                            f.string('role').eq('assistant'),
+                            f.string('role').eq('user'),
+                        ]),
+                    ]),
+                    sort: (sort) => [sort.field('role').asc(), sort.field('seq').desc()],
+                    limit: 1,
+                });
+                if (answered)
+                    changed(unit, record, {
+                        messageId: `runner:${run.id}`,
+                        revision: Number(answered.seq) + 1,
+                    });
+                await attend(unit, record.id, run);
             },
         },
     };
@@ -782,6 +1076,8 @@ export function createConversationService(deps) {
         }
     }
     async function sendMessage(userId, id, request, realtime) {
+        if (request.agentId !== undefined && (!realtime || !request.agentId.trim()))
+            throw invalid('Agent selection requires a Runner realtime message.');
         const content = request.content;
         const attachmentIds = readAttachmentIds(request.attachmentIds);
         if (typeof content !== 'string' ||
@@ -814,22 +1110,44 @@ export function createConversationService(deps) {
             ? await historicalPageContext(deps.contextKinds, tx.read(), userId, previous[0]?.workContext, realtime.workContext)
             : undefined;
         const sent = await measuredAdmission(async (unit) => {
-            const record = await lockOwned(unit, userId, id, Boolean(realtime));
-            const binding = runnerBinding(record.metadata);
+            let record = await lockOwned(unit, userId, id, Boolean(realtime));
+            let binding = runnerBinding(record.metadata);
             if (realtime) {
                 if (!binding)
                     throw invalid('This is not a Runner OnlineAgent conversation.');
                 if (!isDeepStrictEqual(binding.config, realtime.expectedConfig))
                     throw conflict('The conversation configuration changed; read it again.');
-                if ((realtime.config.agentId ?? 'online') !== record.agentId)
+                const targetId = request.agentId ?? record.agentId;
+                const switching = targetId !== record.agentId;
+                if ((realtime.config.agentId ?? 'online') !== targetId)
                     throw conflict('Start a new conversation to choose another agent.');
-                if (binding.closingRunId ||
-                    (await openRunsOnEach(unit.conn, CONVERSATION_SUBJECT, [id])).length)
-                    throw conflict('This conversation is busy.');
-                const agent = await pickAgent(unit.conn, userId, record.agentId);
+                if (switching &&
+                    (realtime.queue || record.archivedAt || record.mode !== 'runner'))
+                    throw conflict('Only an idle, unarchived Runner conversation can change agents.');
+                const open = await openRunsOnEach(unit.conn, CONVERSATION_SUBJECT, [
+                    id,
+                ]);
+                // Queued input joins the run at work; otherwise a new one starts only once the last one closed.
+                if (realtime.queue
+                    ? !open.some((run) => run.status !== 'queued')
+                    : binding.closingRunId || open.length)
+                    throw conflict(realtime.queue
+                        ? 'The agent is not working on this conversation.'
+                        : 'This conversation is busy.');
+                const agent = await pickAgent(unit.conn, userId, targetId);
+                // A conversation bound to a runner waits for it, online or not.
                 if (agent.source !== 'runner' ||
-                    !(await canAnswer(unit.conn, agent, userId)))
+                    ((switching || !record.runnerId) &&
+                        !(await canAnswer(unit.conn, agent, userId))))
                     throw conflict('This agent has no available execution environment.');
+                if (switching) {
+                    record = await rebind(unit, record, agent, null, {
+                        code: 'switchedAgent',
+                        agentId: agent.id,
+                        fromAgentId: record.agentId,
+                    }, true);
+                    binding = runnerBinding(record.metadata);
+                }
                 if (!isDeepStrictEqual(binding.config, realtime.config))
                     await conversationsRepo(unit.conn).updateMany({
                         filter: { id },
@@ -861,6 +1179,7 @@ export function createConversationService(deps) {
                 workContext: realtime?.workContext ?? context,
                 metadata: {
                     ...(request.clientId ? { clientId: request.clientId } : {}),
+                    ...(realtime?.queue ? { queued: true } : {}),
                 },
             });
             if (links && attachmentIds.length > 0) {
@@ -874,12 +1193,21 @@ export function createConversationService(deps) {
                 }));
             }
             const run = await wake(unit, record, [message], realtime?.business, previousPage);
-            if (realtime && (!run || run.outcome !== 'created'))
-                throw conflict('This conversation could not accept a new execution.');
+            if (realtime &&
+                (!run ||
+                    (realtime.queue
+                        ? run.outcome !== 'appended'
+                        : run.outcome !== 'created')))
+                throw conflict(realtime.queue
+                    ? 'The agent is no longer working on this conversation.'
+                    : 'This conversation could not accept a new execution.');
+            // Writing answers what waited for the owner, and they have seen what they answered.
             await conversationsRepo(unit.conn).updateMany({
                 filter: { id },
-                values: { read: true },
+                values: { read: true, seenSeq: Number(message.seq), ...SETTLED },
             });
+            // Announced apart from the new message, so a listener that settles what waited (an inbox notice) hears it.
+            changed(unit, record);
             return {
                 run,
                 message: (await messagesRepo(unit.conn).findOne({
@@ -905,6 +1233,18 @@ export function createConversationService(deps) {
             const limit = limitOf(query.pageSize, CONVERSATION_PAGE_DEFAULT, CONVERSATION_PAGE_MAX);
             const cursor = query.pageToken ? decodeCursor(query.pageToken) : null;
             const q = query.q?.trim();
+            if ((query.linkKind === undefined) !== (query.linkTargetId === undefined))
+                throw invalid('linkKind and linkTargetId go together.', {
+                    field: query.linkKind === undefined ? 'linkKind' : 'linkTargetId',
+                });
+            const linked = query.linkKind !== undefined && query.linkTargetId !== undefined
+                ? await links.conversationIds(conn, {
+                    kind: query.linkKind,
+                    targetId: query.linkTargetId,
+                })
+                : null;
+            if (linked && linked.length === 0)
+                return { items: [], nextCursor: null };
             const rows = await conversationsRepo(conn).findMany({
                 filter: (f) => f.and([
                     f.string('userId').eq(userId),
@@ -931,6 +1271,9 @@ export function createConversationService(deps) {
                         ]
                         : []),
                     ...(query.source ? [f.string('source').eq(query.source)] : []),
+                    ...(linked
+                        ? [f.or(linked.map((id) => f.string('id').eq(id)))]
+                        : []),
                     ...(q
                         ? [
                             f.or([
@@ -1029,10 +1372,13 @@ export function createConversationService(deps) {
                     values.title = titleFor(patch.title, CONVERSATION_TITLE_MAX);
                     values.titleSource = 'user';
                 }
-                if (patch.archived !== undefined)
+                if (patch.archived !== undefined) {
                     values.archivedAt = patch.archived
                         ? (record.archivedAt ?? now())
                         : null;
+                    if (patch.archived)
+                        Object.assign(values, SETTLED);
+                }
                 if (Object.keys(values).length === 0)
                     return;
                 await conversationsRepo(unit.conn).updateMany({
@@ -1127,6 +1473,45 @@ export function createConversationService(deps) {
         },
         send: (userId, id, request) => sendMessage(userId, id, request),
         sendRealtime: (userId, id, request, input) => sendMessage(userId, id, request, input),
+        async withdraw(userId, id, messageId) {
+            await tx.run(async (unit) => {
+                const record = await lockOwned(unit, userId, id, true);
+                const message = await messagesRepo(unit.conn).findOne({
+                    filter: { id: messageId, conversationId: id },
+                });
+                if (!message || message.role !== 'user')
+                    throw notFound('Message');
+                const metadata = jsonObject(message.metadata);
+                if (metadata.withdrawn)
+                    return;
+                // Taken back only while no runner has it: one conditional update, which a delivery racing it cannot both
+                // pass (`markDelivered` updates only an input not handled).
+                const taken = !metadata.queued ||
+                    metadata.pickedUp ||
+                    typeof metadata.inputId !== 'string' ||
+                    (await inputsRepo(unit.conn).updateMany({
+                        filter: (f) => f.and([
+                            f.string('id').eq(metadata.inputId),
+                            f.date('deliveredAt').empty(),
+                            f.date('handledAt').empty(),
+                        ]),
+                        values: { handledAt: now() },
+                    })).updatedCount !== 1;
+                if (taken)
+                    throw conversationConflict('messageTaken', 'The agent already has this message.');
+                await messagesRepo(unit.conn).updateMany({
+                    filter: { id: message.id },
+                    values: {
+                        metadata: asJson({ ...metadata, withdrawn: true }),
+                        updatedAt: now(),
+                    },
+                });
+                changed(unit, record, {
+                    messageId: message.id,
+                    revision: queuedRevision(message.seq, 'withdrawn'),
+                });
+            });
+        },
         async start(userId, request) {
             if (!sources.has(request.source))
                 throw invalid(`source must be one of ${sources
@@ -1152,18 +1537,292 @@ export function createConversationService(deps) {
             });
         },
         async markRead(userId, id) {
+            const record = await owned(tx.read(), userId, id);
+            return service.markSeen(userId, id, Number(record.lastSeq));
+        },
+        async markSeen(userId, id, seq) {
+            if (!Number.isInteger(seq) || seq < 0)
+                throw invalid('seq must be a message seq.', { field: 'seq' });
+            const changes = (record) => {
+                const last = Number(record.lastSeq);
+                const seen = Math.max(Number(record.seenSeq ?? 0), Math.min(seq, last));
+                const waiting = needsYouOf(record);
+                return {
+                    ...(seen !== Number(record.seenSeq ?? 0) ? { seenSeq: seen } : {}),
+                    ...(seen >= last && !record.read ? { read: true } : {}),
+                    ...(waiting && waiting.reason !== 'confirm' && seen >= waiting.seq
+                        ? SETTLED
+                        : {}),
+                };
+            };
+            // Nothing new seen: no write at all, not even the lock (a read-only deployment acknowledges freely).
+            if (Object.keys(changes(await owned(tx.read(), userId, id))).length === 0)
+                return detail(userId, id);
             await tx.run(async (unit) => {
                 const record = await lockOwned(unit, userId, id, true);
-                if (record.read)
+                const values = changes(record);
+                if (Object.keys(values).length === 0)
                     return;
                 await conversationsRepo(unit.conn).updateMany({
                     filter: { id },
-                    values: { read: true },
+                    values,
                 });
                 changed(unit, record);
             });
             return detail(userId, id);
         },
+        async attention(userId) {
+            const conn = tx.read();
+            const [unread, needsYou] = await Promise.all([
+                conversationsRepo(conn).count({
+                    filter: (f) => f.and([
+                        f.string('userId').eq(userId),
+                        f.boolean('showInChatList').isTrue(),
+                        f.date('archivedAt').empty(),
+                        f.boolean('read').isFalse(),
+                    ]),
+                }),
+                conversationsRepo(conn).count({
+                    filter: (f) => f.and([
+                        f.string('userId').eq(userId),
+                        f.boolean('showInChatList').isTrue(),
+                        f.date('archivedAt').empty(),
+                        f.string('needsYou').notEmpty(),
+                    ]),
+                }),
+            ]);
+            return { unread, needsYou };
+        },
+        async usage(userId, id) {
+            const conn = tx.read();
+            await owned(conn, userId, id);
+            const totals = await conn.query
+                .selectFrom('agRunUsage as u')
+                .innerJoin('agRuns as r', 'r.id', 'u.runId')
+                .where('r.subjectKind', '=', CONVERSATION_SUBJECT)
+                .where('r.subjectId', '=', id)
+                .select((eb) => [
+                eb.fn.sum('u.inputTokens').as('inputTokens'),
+                eb.fn.sum('u.cacheReadTokens').as('cacheReadTokens'),
+                eb.fn.sum('u.outputTokens').as('outputTokens'),
+                eb.fn.count('u.runId').distinct().as('runs'),
+            ])
+                .executeTakeFirst();
+            // The status events its runs reported, read through the Repository: `content` is a text field, which some
+            // dialects (Oracle's CLOB) do not compare with `=`.
+            const runIds = (await runsRepo(conn).findMany({
+                filter: (f) => f.and([
+                    f.string('subjectKind').eq(CONVERSATION_SUBJECT),
+                    f.string('subjectId').eq(id),
+                ]),
+            })).map((run) => String(run.id));
+            const statuses = async (content, limit) => runIds.length === 0
+                ? []
+                : eventsRepo(conn).findMany({
+                    filter: (f) => f.and([
+                        f.or(runIds.map((runId) => f.string('runId').eq(runId))),
+                        f.string('type').eq('status'),
+                        f.text('content').eq(content),
+                    ]),
+                    sort: (sort) => limit
+                        ? [sort.field('createdAt').desc(), sort.field('seq').desc()]
+                        : [sort.field('seq').asc()],
+                    ...(limit ? { limit } : {}),
+                });
+            // The latest run that said how full its context window was.
+            const [latest] = await statuses('context', 1);
+            const context = jsonObject(jsonObject(latest?.meta).context);
+            const used = Number(context.used);
+            const size = Number(context.size);
+            // A run's tool reports what it cost so far at each turn's end: its last report is the run's.
+            const turns = await statuses('turnCompleted');
+            const costs = new Map();
+            for (const turn of turns) {
+                const cost = Number(jsonObject(turn.meta).costUsd);
+                if (Number.isFinite(cost) && cost >= 0)
+                    costs.set(String(turn.runId), cost);
+            }
+            return {
+                inputTokens: Number(totals?.inputTokens ?? 0),
+                cacheReadTokens: Number(totals?.cacheReadTokens ?? 0),
+                outputTokens: Number(totals?.outputTokens ?? 0),
+                runs: Number(totals?.runs ?? 0),
+                context: Number.isFinite(used) && Number.isFinite(size) && size > 0
+                    ? { used, size }
+                    : null,
+                costUsd: costs.size
+                    ? Math.round([...costs.values()].reduce((sum, cost) => sum + cost, 0) * 1e6) / 1e6
+                    : null,
+            };
+        },
+        async markNoticed(conversationId, seq) {
+            await tx.run(async (unit) => {
+                const record = await lockConversation(unit.conn, conversationId, now());
+                if (!record || Number(record.noticedSeq ?? -1) >= seq)
+                    return;
+                await conversationsRepo(unit.conn).updateMany({
+                    filter: { id: conversationId },
+                    values: { noticedSeq: seq },
+                });
+            });
+        },
+        async switchAgent(userId, id, agentId) {
+            if (typeof agentId !== 'string' || !agentId.trim())
+                throw invalid('Select a valid agentId.');
+            await tx.run(async (unit) => {
+                const record = await lockOwned(unit, userId, id, true);
+                if (record.mode !== 'runner' || jsonObject(record.metadata).onlineAgent)
+                    throw invalid('Only Runner conversations can switch agents.');
+                if (record.archivedAt)
+                    throw conflict('Restore the conversation before changing agents.', {
+                        reason: 'archived',
+                    });
+                const agent = await pickAgent(unit.conn, userId, agentId);
+                if (agent.source !== 'runner')
+                    throw invalid('Select a callable Runner agent.');
+                if (record.agentId === agent.id)
+                    return;
+                const binding = runnerBinding(record.metadata);
+                // Sending, queueing and switching serialize on this same conversation row. An admitted or closing stream
+                // also keeps the boundary busy until its durable run and canonical history have settled.
+                if (deps.runnerBusy?.(id) ||
+                    binding?.closingRunId ||
+                    (await openRunsOnEach(unit.conn, CONVERSATION_SUBJECT, [id])).length)
+                    throw conflict('Finish the conversation’s pending work before changing agents.', { reason: 'busy' });
+                await rebind(unit, record, agent, null, {
+                    code: 'switchedAgent',
+                    agentId: agent.id,
+                    fromAgentId: record.agentId,
+                }, true);
+            });
+            return detail(userId, id);
+        },
+        async switchRunner(userId, id) {
+            await tx.run(async (unit) => {
+                const record = await lockOwned(unit, userId, id, true);
+                if (!record.runnerId)
+                    return;
+                await conversationsRepo(unit.conn).updateMany({
+                    filter: { id },
+                    values: { runnerId: null, updatedAt: now() },
+                });
+                changed(unit, record);
+            });
+            return detail(userId, id);
+        },
+        async askOwnerFromRun(run, question, issue) {
+            const text = question.trim();
+            if (text === '' || [...text].length > QUESTION_MAX)
+                throw invalid(`question must be 1 to ${QUESTION_MAX} characters.`, {
+                    field: 'question',
+                });
+            const conversation = await tx.run(async (unit) => {
+                if (run.subject.kind !== CONVERSATION_SUBJECT)
+                    throw notFound('Conversation');
+                const record = await lockConversation(unit.conn, run.subject.id, now());
+                if (!record || record.userId !== run.actorUserId)
+                    throw notFound('Conversation');
+                await conversationsRepo(unit.conn).updateMany({
+                    filter: { id: record.id },
+                    values: {
+                        needsYou: 'confirm',
+                        needsYouSeq: Number(record.lastSeq),
+                        needsYouText: text,
+                        metadata: asJson({
+                            ...jsonObject(record.metadata),
+                            ownerQuestion: issue ? { issue, askedAt: now() } : null,
+                        }),
+                    },
+                });
+                changed(unit, record);
+                return record;
+            });
+            return detail(conversation.userId, conversation.id);
+        },
+        async settleOwnerQuestion(id, issue, resumedAt) {
+            const resumed = Date.parse(resumedAt);
+            const matches = (record) => {
+                if (!record || record.needsYou !== 'confirm')
+                    return false;
+                const question = jsonObject(jsonObject(record.metadata).ownerQuestion);
+                return (question.issue === issue &&
+                    typeof question.askedAt === 'string' &&
+                    Date.parse(question.askedAt) < resumed);
+            };
+            // Filter before taking the existing conversation write boundary, then recheck under it.
+            if (!matches(await findConversation(tx.read(), id)))
+                return false;
+            return tx.run(async (unit) => {
+                const record = await lockConversation(unit.conn, id, now());
+                if (!record || !matches(record))
+                    return false;
+                await conversationsRepo(unit.conn).updateMany({
+                    filter: { id },
+                    values: {
+                        ...SETTLED,
+                        metadata: asJson({
+                            ...jsonObject(record.metadata),
+                            ownerQuestion: null,
+                        }),
+                    },
+                });
+                changed(unit, record);
+                return true;
+            });
+        },
+        async ofRunId(runId) {
+            const conn = tx.read();
+            const stored = await findRunRecord(conn, runId);
+            return stored ? service.homeOf(conn, toRun(stored)) : null;
+        },
+        links,
+        async delete(userId, id) {
+            const cleanup = await tx.run(async (unit) => {
+                const record = await lockOwned(unit, userId, id, true);
+                return remove(unit, record, userId);
+            });
+            await cleanup();
+        },
+        async purgeArchived(days, at = new Date()) {
+            if (days <= 0)
+                return 0;
+            const cutoff = new Date(at.getTime() - days * 86_400_000).toISOString();
+            const started = Date.now();
+            let purged = 0;
+            for (;;) {
+                const due = await conversationsRepo(tx.read()).findMany({
+                    filter: (f) => f.and([
+                        f.date('archivedAt').notEmpty(),
+                        f.date('archivedAt').before(cutoff),
+                    ]),
+                    sort: (sort) => [
+                        sort.field('archivedAt').asc(),
+                        sort.field('id').asc(),
+                    ],
+                    limit: ARCHIVED_PURGE_BATCH,
+                });
+                for (const candidate of due) {
+                    const cleanup = await tx.run(async (unit) => {
+                        const record = await lockConversation(unit.conn, candidate.id, now());
+                        // Restored meanwhile, or already gone: not counted.
+                        if (!record?.archivedAt ||
+                            new Date(record.archivedAt).toISOString() >= cutoff)
+                            return null;
+                        return remove(unit, record, record.userId);
+                    });
+                    if (!cleanup)
+                        continue;
+                    await cleanup();
+                    purged += 1;
+                }
+                if (due.length < ARCHIVED_PURGE_BATCH ||
+                    purged >= ARCHIVED_PURGE_LIMIT ||
+                    Date.now() - started > ARCHIVED_PURGE_TIME_MS) {
+                    await purgeOrphanRuns();
+                    return purged;
+                }
+            }
+        },
         async stop(userId, id) {
             await tx.run(async (unit) => {
                 const record = await lockOwned(unit, userId, id, true);
@@ -1276,11 +1935,13 @@ export function createConversationService(deps) {
             if (!record)
                 return null;
             await notice(outer, record, news.notice);
-            // New bindings save business notices atomically but never wake a second execution.
+            // Native bindings save business notices atomically but never wake a second execution; a Runner binding only
+            // when the application asks it to.
             if (jsonObject(record.metadata).onlineAgent ||
-                runnerBinding(record.metadata))
+                (runnerBinding(record.metadata) && !news.wake))
                 return null;
-            if (!news.input)
+            // An archived conversation keeps the news but is not woken by it.
+            if (!news.input || record.archivedAt)
                 return null;
             const agent = record.agentId
                 ? await findAgent(outer.conn, record.agentId)