@nocobase/app-plugin-agents 0.1.0-beta.8 → 1.0.0-beta.15

package/dist/server/core/runs/run.service.js

@@ -9,16 +9,17 @@
  */
 import { ProtocolError, TERMINAL_RUN_STATUSES, } from '@nocobase/agent-protocol';
 import { conflict, forbidden, invalid, notFound, precondition, } from '../../kernel/errors.js';
-import { asJson, cleanList, jsonObject } from '../../kernel/values.js';
+import { asJson, cleanList, jsonObject, stringArray, } from '../../kernel/values.js';
 import { findAgent, lockAgentForClaim } from '../agents/index.js';
+import { agentNamesOf } from '../agents/agent.store.js';
 import { createRunRequestService, insertRunRequest, } from './run-requests.js';
 import { authenticateRunToken } from './run-tokens.js';
-import { ACTIVE, eventsRepo, findRunRecord, inputsOnSince, inputsRepo, isActive, isTerminal, lastSummary, openRunsOn, pendingInputs, reposRepo, runsOfKey, runsRepo, toInput, toInputView, toRepo, toRun, usageRepo, } from './run.store.js';
-import { dialectOf, takesType } from './ports.js';
-import { readWorkload } from './workload.js';
+import { ACTIVE, eventsRepo, findRunRecord, inputsOnSince, inputsRepo, isActive, isTerminal, lastSummary, openRunsOn, openRunsOnEach, pendingInputs, reposRepo, runsOfKey, runsRepo, toInput, toInputView, toRepo, toRun, usageRepo, } from './run.store.js';
+import { readQueueWait, readWorkload, } from './workload.js';
 import { finishRun } from './transitions.js';
 import { gateInputs, gatePending } from './input-gate.js';
 import { findBrief, requestReset } from './workspace.store.js';
+import { findCommentRoot, currentCommentOwner, commentConsent, commentFromOwner, } from './comment-consent.js';
 export const DEFAULT_THREAD = 'main';
 /**
  * The run work went into, for a caller that names no responsible (a conversation, a consultation): such work is never
@@ -31,7 +32,9 @@ export function queuedRun(result) {
 }
 /** Who a chain of work a run belongs to started with: who confirmed it, else who it was requested by. */
 function chainSourceOf(run) {
-    return run.confirmedByUserId ?? run.requestedByUserId ?? run.actorUserId;
+    return run.commentRootRunId
+        ? (run.requestedByUserId ?? run.actorUserId)
+        : (run.confirmedByUserId ?? run.requestedByUserId ?? run.actorUserId);
 }
 /** A delay as the moment a run may be claimed, or null for now (and for any moment already past). */
 function fireAtOf(value, now) {
@@ -42,8 +45,20 @@ function fireAtOf(value, now) {
         throw invalid('fireAt is not a date.');
     return at.getTime() > now.getTime() ? at.toISOString() : null;
 }
+const COMMENT_CANCEL_DETAIL = 'The personal runner request was declined or switched to the commenter.';
 export function createRunService(deps) {
     const { tx, ids, clock } = deps;
+    /** Ends one unfinished run of a declined chain; a run that moved since it was read rolls the decision back. */
+    async function endCommentRun(unit, run, byUserId) {
+        const ended = await finishRun(unit, deps, run, {
+            status: 'cancelled',
+            reason: null,
+            detail: COMMENT_CANCEL_DETAIL,
+            cancelledById: byUserId,
+        });
+        if (!ended)
+            throw conflict('The comment work changed; read it again.');
+    }
     const require = async (conn, id) => {
         const run = await findRunRecord(conn, id);
         if (!run)
@@ -79,22 +94,20 @@ export function createRunService(deps) {
         const agent = await findAgent(unit.conn, agentId);
         if (!agent)
             throw notFound('Agent');
-        if (agent.archivedAt)
-            throw precondition('AGENT_ARCHIVED', 'The agent is archived.');
+        if (agent.status !== 'enabled')
+            throw precondition('AGENT_NOT_ENABLED', 'The agent is not enabled.');
         if (!deps.agents.mayInvoke(agent, userId))
             throw forbidden('You may not wake this agent.');
         return agent;
     }
     async function createRun(unit, agent, values) {
-        if (!takesType(deps.subjects.get(values.subject.kind), agent.type))
-            throw invalid(`A ${agent.type} agent cannot work on a ${values.subject.kind}.`, { reason: 'AGENT_TYPE_NOT_ALLOWED', agentType: agent.type });
         const now = clock.now().toISOString();
         const id = ids.next();
         await runsRepo(unit.conn).createOne({
             values: {
                 id,
                 agentId: agent.id,
-                agentType: agent.type,
+                agentType: 'runner',
                 runnerId: null,
                 status: 'queued',
                 priority: values.priority,
@@ -106,6 +119,11 @@ export function createRunService(deps) {
                 subjectKind: values.subject.kind,
                 subjectId: values.subject.id,
                 threadScope: values.threadScope,
+                commentRootRunId: values.commentRootRunId === ''
+                    ? id
+                    : (values.commentRootRunId ?? null),
+                commentExecution: values.commentExecution ?? null,
+                commentOwnerKey: values.commentOwnerKey ?? null,
                 actorUserId: values.actorUserId,
                 requestedByUserId: values.requestedByUserId,
                 confirmedByUserId: values.confirmedByUserId,
@@ -113,6 +131,7 @@ export function createRunService(deps) {
                 requires: cleanList([...values.requires]),
                 acceptsInput: false,
                 availableAt: values.availableAt ?? null,
+                queueEnteredAt: now,
                 leaseExpiresAt: null,
                 dispatchedAt: null,
                 startedAt: null,
@@ -208,13 +227,93 @@ export function createRunService(deps) {
                 actualModels: models.get(run.id) ?? [],
             });
     }
+    /** Cross-root appends require both sources to retain the same owner's authorization. */
+    async function equivalentCommentAuthority(unit, run, work) {
+        if (run.ownerUserId !== work.ownerUserId ||
+            (run.commentOwnerKey ?? null) !== (work.commentOwnerKey ?? null) ||
+            (run.commentExecution ?? 'owner') !== (work.commentExecution ?? 'owner'))
+            return false;
+        if ((run.commentRootRunId ?? null) === (work.commentRootRunId ?? null)) {
+            if (!run.commentRootRunId)
+                return true;
+            const root = await findCommentRoot(unit.conn, run.commentRootRunId);
+            // Requester execution keeps its own identity; it does not borrow the owner's consent.
+            if (root.commentExecution === 'requester')
+                return (root.actorUserId === work.actorUserId &&
+                    (await currentCommentOwner(unit.conn, deps.subjects, root)));
+            return await authorizedRoot(root);
+        }
+        if (work.commentExecution === 'requester' ||
+            run.commentExecution === 'requester' ||
+            !work.sourceRunId)
+            return false;
+        const source = await findRunRecord(unit.conn, work.sourceRunId);
+        if (!source ||
+            source.subjectKind !== run.subjectKind ||
+            source.subjectId !== run.subjectId ||
+            source.ownerUserId !== run.ownerUserId ||
+            source.actorUserId !== run.actorUserId)
+            return false;
+        const sourceRoot = source.commentRootRunId
+            ? await findCommentRoot(unit.conn, source.commentRootRunId)
+            : source;
+        const targetRoot = run.commentRootRunId
+            ? await findCommentRoot(unit.conn, run.commentRootRunId)
+            : run;
+        return ((await authorizedRoot(sourceRoot)) && (await authorizedRoot(targetRoot)));
+        async function authorizedRoot(root) {
+            if (!(await currentCommentOwner(unit.conn, deps.subjects, root)))
+                return false;
+            if (!root.commentRootRunId)
+                return chainSourceOf(root) === root.ownerUserId;
+            const { decision } = await commentConsent(unit.conn, root);
+            if (decision === 'pending' || decision === 'rejected')
+                return false;
+            return (decision === 'confirmed' || (await commentFromOwner(unit.conn, root)));
+        }
+    }
     /**
      * Queues `work` for `agent`: it joins the run working on its key while that run can still be told, else the run
      * waiting for it, else starts a new run.
      */
     async function queue(unit, agent, work) {
+        if (work.commentRootRunId) {
+            // A plain read: the root's subject never changes, and the agent lock below serializes the chain's enqueues.
+            const root = await findCommentRoot(unit.conn, work.commentRootRunId);
+            if (root.subjectKind !== work.subject.kind ||
+                root.subjectId !== work.subject.id)
+                throw invalid('A comment authorization cannot cross subjects.');
+        }
         // Serializes enqueues and claims for this agent, so a key never gets two waiting runs.
         await lockAgentForClaim(unit.conn, agent.id, clock.now().toISOString());
+        if (work.preferActive) {
+            const commentId = jsonObject(work.input.payload).commentId;
+            if (typeof commentId === 'string') {
+                const prior = await inputsRepo(unit.conn).findOne({
+                    filter: (f) => f.and([
+                        f.string('type').eq('comment'),
+                        f.json('payload').path(['commentId']).eq(commentId),
+                        f
+                            .relation('run')
+                            .some((r) => r.and([
+                            r.string('agentId').eq(agent.id),
+                            r.string('subjectKind').eq(work.subject.kind),
+                            r.string('subjectId').eq(work.subject.id),
+                        ])),
+                    ]),
+                });
+                if (prior) {
+                    const run = (await findRunRecord(unit.conn, prior.runId));
+                    return {
+                        runId: run.id,
+                        inputId: prior.id,
+                        outcome: 'appended',
+                        status: run.status,
+                        duplicate: true,
+                    };
+                }
+            }
+        }
         const key = {
             agentId: agent.id,
             subjectKind: work.subject.kind,
@@ -223,24 +322,87 @@ export function createRunService(deps) {
         };
         // Only into work done as the same person: merged into another's run, it would borrow their identity, or wait
         // for a runner that never takes it.
-        const open = await runsOfKey(unit.conn, key, ['queued', ...ACTIVE], work.actorUserId);
-        const candidate = open.find((run) => !work.freshSession &&
-            (run.status === 'dispatched' ||
-                (run.status === 'running' && Boolean(run.acceptsInput))));
-        // Joins the working run only when the subject would let the agent act on it now; otherwise it waits in a queued run,
-        // which the claim admits or cancels.
-        const working = candidate &&
-            (await gateInputs(unit.conn, deps, candidate, agent, [
-                {
+        const unfiltered = await runsOfKey(unit.conn, key, ['queued', ...ACTIVE], work.actorUserId);
+        const open = unfiltered.filter((run) => (run.commentRootRunId ?? null) === (work.commentRootRunId ?? null) &&
+            (run.commentExecution ?? null) === (work.commentExecution ?? null));
+        let working;
+        for (let candidate of work.preferActive ? unfiltered : open) {
+            if (work.freshSession ||
+                candidate.cancelRequestedAt ||
+                !(candidate.status === 'dispatched' ||
+                    (candidate.status === 'running' && Boolean(candidate.acceptsInput))))
+                continue;
+            if (work.preferActive) {
+                if (!candidate.runnerId ||
+                    !['claude', 'codex', 'pi', 'opencode'].includes(candidate.tool ?? ''))
+                    continue;
+                const runner = await deps.runners.find(unit.conn, candidate.runnerId);
+                if (!runner?.features.includes('steer'))
+                    continue;
+            }
+            for (let attempt = 0; attempt < 4; attempt += 1) {
+                if (work.preferActive &&
+                    !(await equivalentCommentAuthority(unit, candidate, work)))
+                    break;
+                const input = {
                     id: '',
                     at: clock.now().toISOString(),
                     ...work.input,
-                },
-            ])).length > 0
-            ? candidate
-            : undefined;
+                    ...(candidate.commentRootRunId
+                        ? {
+                            payload: {
+                                ...jsonObject(work.input.payload),
+                                commentRootRunId: candidate.commentRootRunId,
+                            },
+                        }
+                        : {}),
+                };
+                if ((await gateInputs(unit.conn, deps, candidate, agent, [input]))
+                    .length === 0)
+                    break;
+                const touched = await runsRepo(unit.conn).updateMany({
+                    filter: (f) => f.and([
+                        f.string('id').eq(candidate.id),
+                        f.string('status').eq(candidate.status),
+                        f.number('revision').eq(candidate.revision),
+                        f.date('cancelRequestedAt').empty(),
+                    ]),
+                    values: { updatedAt: clock.now().toISOString() },
+                });
+                if (touched.updatedCount === 1) {
+                    working = candidate;
+                    break;
+                }
+                const current = await findRunRecord(unit.conn, candidate.id);
+                if (!current ||
+                    current.cancelRequestedAt ||
+                    !(current.status === 'dispatched' ||
+                        (current.status === 'running' && current.acceptsInput)))
+                    break;
+                // A claim/start may change the holder or tool; re-evaluate those on a subsequent dispatch.
+                if (current.actorUserId !== work.actorUserId ||
+                    current.threadScope !== work.threadScope ||
+                    current.runnerId !== candidate.runnerId ||
+                    current.tool !== candidate.tool)
+                    break;
+                candidate = current;
+                if (attempt === 3)
+                    throw conflict('The run revision changed during append; retry the dispatch.');
+            }
+            if (working)
+                break;
+        }
         const waiting = open.find((run) => run.status === 'queued');
         const target = working ?? waiting;
+        const commentInput = (rootId) => rootId
+            ? {
+                ...work.input,
+                payload: {
+                    ...jsonObject(work.input.payload),
+                    commentRootRunId: rootId,
+                },
+            }
+            : work.input;
         if (!working && waiting)
             await hurry(unit, waiting, work.priority, work.fireAt);
         if (target) {
@@ -249,7 +411,7 @@ export function createRunService(deps) {
                     filter: { id: target.id, status: 'queued' },
                     values: { freshSession: true, updatedAt: clock.now().toISOString() },
                 });
-            const inputId = await insertInput(unit, target.id, work.input);
+            const inputId = await insertInput(unit, target.id, commentInput(target.commentRootRunId));
             return {
                 runId: target.id,
                 outcome: working ? 'appended' : 'merged',
@@ -258,6 +420,9 @@ export function createRunService(deps) {
             };
         }
         const runId = await createRun(unit, agent, {
+            commentRootRunId: work.commentRootRunId,
+            commentExecution: work.commentExecution,
+            commentOwnerKey: work.commentOwnerKey,
             freshSession: work.freshSession,
             subject: work.subject,
             threadScope: work.threadScope,
@@ -272,16 +437,23 @@ export function createRunService(deps) {
             ...(work.parentRunId ? { parentRunId: work.parentRunId } : {}),
             ...(work.maxAttempts ? { maxAttempts: work.maxAttempts } : {}),
         });
-        const inputId = await insertInput(unit, runId, work.input);
+        const inputId = await insertInput(unit, runId, commentInput(work.commentRootRunId === '' ? runId : work.commentRootRunId));
         return { runId, outcome: 'created', status: 'queued', inputId };
     }
     /** The source of the chain of work a request belongs to (`EnqueueRequest.requestedByUserId`). */
     async function sourceOf(unit, request) {
+        if (request.comment &&
+            request.input.actor.kind === 'user' &&
+            jsonObject(request.input.payload).byAgent !== true &&
+            (request.requestedByUserId ?? request.actorUserId))
+            return (request.requestedByUserId ?? request.actorUserId);
         if (request.causedByRunId) {
             const cause = await findRunRecord(unit.conn, request.causedByRunId);
             if (!cause)
                 throw invalid('causedByRunId names no run.');
-            return chainSourceOf(cause);
+            return request.comment
+                ? (cause.requestedByUserId ?? cause.actorUserId)
+                : chainSourceOf(cause);
         }
         const source = request.requestedByUserId ??
             request.actorUserId ??
@@ -290,10 +462,23 @@ export function createRunService(deps) {
             throw invalid('Name who woke the agent: actorUserId, requestedByUserId or responsibleUserId.');
         return source;
     }
+    async function selectedIdentity(unit, request, commentExecution) {
+        const identity = await deps.subjects
+            .get(request.subject.kind)
+            ?.actsAs?.(unit.conn, {
+            subjectId: request.subject.id,
+            agentId: request.agentId,
+            causedByRunId: request.causedByRunId,
+            commentExecution,
+            actorUserId: request.actorUserId,
+            inputs: [request.input],
+        });
+        if (identity && !identity.actorUserId)
+            throw new ProtocolError('FORBIDDEN', 'The subject has no valid execution identity.', { identityReason: identity.reason ?? 'noOwner' });
+        return identity;
+    }
     /** Refuses work run as `userId` when no runner they may use can run the agent now: it would only wait. */
     async function requireRunnerFor(unit, agent, userId, requires) {
-        if (agent.type !== 'runner')
-            return;
         // By the claim's own rules, the agent's variables included; the subject's are the claim's to check.
         if (!(await deps.eligibility.canClaim(unit.conn, agent, {
             actorUserId: userId,
@@ -312,26 +497,225 @@ export function createRunService(deps) {
         mayInvoke: (agent, userId) => deps.agents.mayInvoke(agent, userId),
         requireInvocable,
         requireRunnerFor,
-        direct: (unit, run) => queue(unit, run.agent, {
-            freshSession: run.freshSession,
-            subject: run.subject,
-            threadScope: run.threadScope,
-            actorUserId: run.actorUserId,
-            requestedByUserId: run.requestedByUserId,
-            confirmedByUserId: run.confirmedByUserId,
-            ownerUserId: run.ownerUserId,
-            priority: run.priority,
-            // As it was asked: a moment already past when it is confirmed means now.
-            fireAt: fireAtOf(run.fireAt ?? undefined, clock.now()),
-            requires: run.requires,
-            ...(run.maxAttempts === null ? {} : { maxAttempts: run.maxAttempts }),
-            input: run.input,
-        }),
+        prepareCommentActor: async (record, byUserId) => {
+            const mayRead = deps.subjects.get(record.subjectKind)?.commentActorMayRead;
+            if (mayRead && !(await mayRead(record.subjectId, byUserId)))
+                throw forbidden('The acting user may no longer read this issue.');
+        },
+        checkCommentRequest: async (unit, record) => {
+            const root = await findCommentRoot(unit.conn, record.commentRootRunId);
+            if (!(await currentCommentOwner(unit.conn, deps.subjects, root)) ||
+                root.commentExecution !== 'owner' ||
+                root.ownerUserId !== record.responsibleUserId ||
+                (root.commentOwnerKey ?? null) !== (record.commentOwnerKey ?? null))
+                throw precondition('RUN_REQUEST_SETTLED', 'This comment request belongs to an earlier owner assignment.');
+        },
+        releaseCommentRequest: async (unit, record, byUserId) => {
+            const run = await findRunRecord(unit.conn, record.commentRunId);
+            if (!run ||
+                run.status !== 'queued' ||
+                run.commentRootRunId !== record.commentRootRunId)
+                throw precondition('RUN_REQUEST_SETTLED', 'The requested work is no longer waiting.');
+            const inputs = await pendingInputs(unit.conn, run.id);
+            const now = clock.now().toISOString();
+            // Guarded on the requested run itself: a claim that took it first wins, and this confirmation rolls back.
+            const released = await runsRepo(unit.conn).updateMany({
+                filter: { id: run.id, status: 'queued' },
+                values: { confirmedByUserId: byUserId, updatedAt: now },
+            });
+            if (released.updatedCount !== 1)
+                throw precondition('RUN_REQUEST_SETTLED', 'The requested work is no longer waiting.');
+            await runsRepo(unit.conn).updateMany({
+                filter: {
+                    commentRootRunId: record.commentRootRunId,
+                    status: 'queued',
+                    actorUserId: record.responsibleUserId,
+                },
+                values: { confirmedByUserId: byUserId, updatedAt: now },
+            });
+            unit.emit({ type: 'run.changed', runId: run.id, status: 'queued' });
+            return {
+                runId: run.id,
+                outcome: 'merged',
+                status: 'queued',
+                inputId: inputs[0].id,
+            };
+        },
+        cancelCommentRequest: async (unit, record, byUserId) => {
+            for (const run of await runsRepo(unit.conn).findMany({
+                filter: { commentRootRunId: record.commentRootRunId },
+            }))
+                if (!isTerminal(run.status))
+                    await endCommentRun(unit, run, byUserId);
+        },
+        runCommentAsRequester: async (unit, record, byUserId) => {
+            // Queuing the replacements takes their agents' rows, as claims do before they take a run. Taking every agent of
+            // the chain first, in one order, keeps this from holding a run a claim waits on while it waits for that claim.
+            const agentIds = new Set((await runsRepo(unit.conn).findMany({
+                filter: { commentRootRunId: record.commentRootRunId },
+            })).map((run) => run.agentId));
+            for (const agentId of [...agentIds].sort())
+                await lockAgentForClaim(unit.conn, agentId, clock.now().toISOString());
+            const chain = await runsRepo(unit.conn).findMany({
+                filter: { commentRootRunId: record.commentRootRunId },
+                sort: (sort) => [sort.field('createdAt').asc(), sort.field('id').asc()],
+            });
+            const targets = [];
+            for (const old of chain) {
+                // Rejection ends the queued chain, but leaves its inputs unhandled. Do not revive independently ended work.
+                const declined = record.status === 'rejected' &&
+                    old.status === 'cancelled' &&
+                    old.cancelledById === record.responsibleUserId &&
+                    old.failureDetail === COMMENT_CANCEL_DETAIL;
+                if (isTerminal(old.status) && !declined)
+                    continue;
+                const inputs = await pendingInputs(unit.conn, old.id);
+                if (inputs.length === 0)
+                    continue;
+                await selectedIdentity(unit, {
+                    agentId: old.agentId,
+                    subject: { kind: old.subjectKind, id: old.subjectId },
+                    input: toInput(inputs[0]),
+                    actorUserId: byUserId,
+                }, 'requester');
+                const agent = await requireInvocable(unit, old.agentId, byUserId);
+                const requires = stringArray(old.requires);
+                await requireRunnerFor(unit, agent, byUserId, requires);
+                targets.push({ old, inputs, agent, requires });
+            }
+            if (!targets.length)
+                throw precondition('RUN_REQUEST_SETTLED', 'No comment work is still waiting.');
+            // Validate all targets before stopping any of them. Each stop is guarded on the status read, so a run a claim took
+            // meanwhile rolls this back rather than being replaced twice; the settled request covers repeat clicks.
+            for (const old of chain)
+                if (!isTerminal(old.status))
+                    await endCommentRun(unit, old, byUserId);
+            const replacements = new Map();
+            let rootId;
+            for (const { old, inputs, agent, requires } of targets) {
+                const first = inputs[0];
+                const next = await queue(unit, agent, {
+                    commentRootRunId: rootId ?? '',
+                    commentExecution: 'requester',
+                    commentOwnerKey: record.commentOwnerKey ?? null,
+                    freshSession: Boolean(old.freshSession),
+                    subject: { kind: old.subjectKind, id: old.subjectId },
+                    threadScope: old.threadScope,
+                    actorUserId: byUserId,
+                    requestedByUserId: byUserId,
+                    confirmedByUserId: null,
+                    ownerUserId: old.ownerUserId,
+                    priority: Number(old.priority),
+                    fireAt: fireAtOf(old.availableAt ?? undefined, clock.now()),
+                    requires,
+                    maxAttempts: Number(old.maxAttempts),
+                    input: toInput(first),
+                });
+                rootId ??= next.runId;
+                replacements.set(old.id, next);
+                for (const input of inputs.slice(1))
+                    await insertInput(unit, next.runId, {
+                        ...toInput(input),
+                        payload: { ...jsonObject(input.payload), commentRootRunId: rootId },
+                    });
+            }
+            // Remap causal references only for replaced work; completed ancestors remain the original historical runs.
+            for (const { old } of targets) {
+                const next = replacements.get(old.id);
+                if (old.parentRunId)
+                    await runsRepo(unit.conn).updateMany({
+                        filter: { id: next.runId },
+                        values: {
+                            parentRunId: replacements.get(old.parentRunId)?.runId ?? old.parentRunId,
+                        },
+                    });
+                for (const input of await pendingInputs(unit.conn, next.runId)) {
+                    const payload = jsonObject(input.payload);
+                    const cause = typeof payload.causedByRunId === 'string'
+                        ? replacements.get(payload.causedByRunId)
+                        : undefined;
+                    if (cause)
+                        await inputsRepo(unit.conn).updateMany({
+                            filter: { id: input.id },
+                            values: {
+                                payload: asJson({ ...payload, causedByRunId: cause.runId }),
+                            },
+                        });
+                }
+            }
+            const rootInputs = await pendingInputs(unit.conn, rootId);
+            if (!rootInputs.some((input) => input.type === record.inputType &&
+                input.text === record.inputText &&
+                jsonObject(input.payload).commentId ===
+                    jsonObject(record.inputPayload).commentId)) {
+                const sourceId = await insertInput(unit, rootId, {
+                    type: record.inputType,
+                    actor: {
+                        kind: record.inputActorKind,
+                        id: record.inputActorId,
+                        name: record.inputActorName,
+                    },
+                    text: record.inputText,
+                    payload: {
+                        ...jsonObject(record.inputPayload),
+                        commentSourceSnapshot: true,
+                        commentRootRunId: rootId,
+                    },
+                });
+                await inputsRepo(unit.conn).updateMany({
+                    filter: { id: sourceId },
+                    values: { handledAt: clock.now().toISOString() },
+                });
+            }
+            return (replacements.get(record.commentRunId) ??
+                replacements.values().next().value);
+        },
+        direct: async (unit, run) => {
+            const identity = await selectedIdentity(unit, {
+                agentId: run.agent.id,
+                subject: run.subject,
+                input: run.input,
+                actorUserId: run.actorUserId,
+            });
+            const actorUserId = identity?.actorUserId ?? run.actorUserId;
+            const agent = await requireInvocable(unit, run.agent.id, actorUserId);
+            return queue(unit, agent, {
+                freshSession: run.freshSession,
+                subject: run.subject,
+                threadScope: run.threadScope,
+                actorUserId,
+                requestedByUserId: run.requestedByUserId,
+                confirmedByUserId: run.confirmedByUserId,
+                ownerUserId: identity ? actorUserId : run.ownerUserId,
+                priority: run.priority,
+                fireAt: fireAtOf(run.fireAt ?? undefined, clock.now()),
+                requires: run.requires,
+                ...(run.maxAttempts === null ? {} : { maxAttempts: run.maxAttempts }),
+                input: run.input,
+            });
+        },
     });
     return {
         enqueue: (request, outer) => tx.run(async (unit) => {
             const source = await sourceOf(unit, request);
-            const responsible = request.responsibleUserId ?? null;
+            const cause = request.causedByRunId
+                ? await findRunRecord(unit.conn, request.causedByRunId)
+                : null;
+            const inherited = !request.comment &&
+                cause?.commentRootRunId &&
+                cause.subjectKind === request.subject.kind &&
+                cause.subjectId === request.subject.id
+                ? cause
+                : null;
+            const commentRootRunId = request.comment?.rootRunId ??
+                inherited?.commentRootRunId ??
+                (request.comment ? '' : null);
+            const commentExecution = inherited?.commentExecution ?? (request.comment ? 'owner' : null);
+            const commentOwnerKey = request.comment?.ownerKey ?? inherited?.commentOwnerKey ?? null;
+            const identity = await selectedIdentity(unit, request, commentExecution);
+            const responsible = identity
+                ? null
+                : (request.responsibleUserId ?? null);
             const threadScope = request.threadScope ?? DEFAULT_THREAD;
             const foreign = responsible !== null && source !== responsible;
             if (foreign && (request.execution ?? 'auto') === 'auto') {
@@ -342,8 +726,6 @@ export function createRunService(deps) {
                 const agent = await requireInvocable(unit, request.agentId, source);
                 if (!deps.agents.mayInvoke(agent, responsible))
                     throw forbidden('The person who answers for this may not wake this agent.');
-                if (!takesType(deps.subjects.get(request.subject.kind), agent.type))
-                    throw invalid(`A ${agent.type} agent cannot work on a ${request.subject.kind}.`, { reason: 'AGENT_TYPE_NOT_ALLOWED', agentType: agent.type });
                 const created = await insertRunRequest(unit, { ids, clock }, {
                     agentId: agent.id,
                     freshSession: request.freshSession,
@@ -368,20 +750,30 @@ export function createRunService(deps) {
             }
             // As the responsible when they caused it; as the source when they run it as themselves (`mine`); as whoever
             // woke the agent when nobody answers for the subject.
-            const actorUserId = foreign
-                ? source
-                : (responsible ?? request.actorUserId ?? source);
+            const actorUserId = (commentExecution === 'requester'
+                ? inherited?.actorUserId
+                : identity?.actorUserId) ??
+                (foreign ? source : (responsible ?? request.actorUserId ?? source));
             const agent = await requireInvocable(unit, request.agentId, actorUserId);
             if (foreign)
                 await requireRunnerFor(unit, agent, actorUserId, request.requires ?? []);
-            return queue(unit, agent, {
+            const result = await queue(unit, agent, {
+                preferActive: request.preferActive,
+                sourceRunId: request.causedByRunId,
+                commentRootRunId,
+                commentExecution,
+                commentOwnerKey,
                 freshSession: request.freshSession,
                 subject: request.subject,
                 threadScope,
                 actorUserId,
                 requestedByUserId: source,
-                confirmedByUserId: null,
-                ownerUserId: request.ownerUserId ?? null,
+                confirmedByUserId: inherited?.confirmedByUserId ?? null,
+                ownerUserId: commentExecution === 'requester'
+                    ? (inherited?.ownerUserId ?? request.ownerUserId ?? null)
+                    : identity
+                        ? actorUserId
+                        : (request.ownerUserId ?? null),
                 priority: request.priority ?? 0,
                 fireAt: fireAtOf(request.fireAt, clock.now()),
                 requires: request.requires ?? [],
@@ -389,12 +781,45 @@ export function createRunService(deps) {
                 ...(request.maxAttempts ? { maxAttempts: request.maxAttempts } : {}),
                 input: request.input,
             });
+            if (commentRootRunId !== null)
+                await deps.reconcileCommentConsent?.(unit, result.runId);
+            return result;
         }, outer),
         requests,
+        identityInputs: async (conn, runId) => {
+            const run = await findRunRecord(conn, runId);
+            if (!run)
+                return null;
+            const inputs = await inputsRepo(conn).findMany({ filter: { runId } });
+            return { run: toRun(run), inputs: inputs.map(toInput) };
+        },
         addInput: (runId, input, outer) => tx.run(async (unit) => {
             const run = await require(unit.conn, runId);
+            if (run.commentRootRunId &&
+                input.type === 'comment' &&
+                jsonObject(input.payload).commentRootRunId !== run.commentRootRunId)
+                throw forbidden('A comment must be queued in its own authorized run chain.');
             if (isTerminal(run.status))
                 throw new ProtocolError('RUN_NOT_ACTIVE', `The run is ${run.status}.`);
+            if (isActive(run.status)) {
+                let current = run;
+                for (let attempt = 0; attempt < 4; attempt += 1) {
+                    const updated = await runsRepo(unit.conn).updateMany({
+                        filter: {
+                            id: current.id,
+                            status: current.status,
+                            revision: current.revision,
+                        },
+                        values: { updatedAt: clock.now().toISOString() },
+                    });
+                    if (updated.updatedCount === 1)
+                        return insertInput(unit, current.id, input);
+                    current = await require(unit.conn, run.id);
+                    if (!isActive(current.status))
+                        throw conflict('The run moved on before input was appended.');
+                }
+                throw conflict('The run revision changed during append; retry the input.');
+            }
             return insertInput(unit, run.id, input);
         }, outer),
         cancel: (runId, byUserId, outer) => tx.run(async (unit) => {
@@ -459,47 +884,192 @@ export function createRunService(deps) {
             }
             return ended;
         }, outer),
-        retry: (runId, byUserId) => tx.run(async (unit) => {
-            const run = await require(unit.conn, runId);
-            if (run.status !== 'failed' && run.status !== 'cancelled')
-                throw precondition('RUN_NOT_RETRYABLE', 'Only a failed or cancelled run can be retried.');
-            if (run.parentRunId)
-                throw precondition('RUN_NOT_RETRYABLE', 'A consultation is not retried: the agent that asked asks again.');
-            const agent = await requireInvocable(unit, run.agentId, byUserId);
-            await lockAgentForClaim(unit.conn, agent.id, clock.now().toISOString());
-            const open = await runsOfKey(unit.conn, run, ['queued', ...ACTIVE], byUserId);
-            if (open.length > 0)
-                throw precondition('AGENT_BUSY', 'The agent is already working on this.', {
-                    runId: open[0].id,
+        retry: async (runId, byUserId, source = 'api') => {
+            const target = await require(tx.read(), runId);
+            // Resolve collection metadata outside the transaction too. The lock must
+            // precede consistent reads so repeatable-read databases see a concurrent
+            // retry that committed while this request waited for the lock.
+            await findAgent(tx.read(), target.agentId);
+            return tx.run(async (unit) => {
+                await lockAgentForClaim(unit.conn, target.agentId, clock.now().toISOString());
+                const run = await require(unit.conn, runId);
+                if (run.status !== 'failed' && run.status !== 'cancelled')
+                    throw precondition('RUN_NOT_RETRYABLE', 'Only a failed or cancelled run can be retried.');
+                if (run.parentRunId)
+                    throw precondition('RUN_NOT_RETRYABLE', 'A consultation is not retried: the agent that asked asks again.');
+                // The agent lock serializes retry and enqueue across server instances. Check
+                // the relationship even after the replacement has already ended.
+                const retried = await runsRepo(unit.conn).findOne({
+                    filter: { retryOfRunId: run.id },
+                    sort: (sort) => [
+                        sort.field('createdAt').asc(),
+                        sort.field('id').asc(),
+                    ],
                 });
-            const newId = await createRun(unit, agent, {
-                subject: { kind: run.subjectKind, id: run.subjectId },
-                threadScope: run.threadScope,
-                actorUserId: byUserId,
-                requestedByUserId: byUserId,
-                confirmedByUserId: null,
-                ownerUserId: run.ownerUserId,
-                priority: Number(run.priority),
-                requires: toRun(run).requires,
-                retryOfRunId: run.id,
-                freshSession: run.freshSession,
-            });
-            for (const input of await pendingInputs(unit.conn, run.id))
+                if (retried)
+                    throw precondition('RUN_ALREADY_RETRIED', 'This run has already been retried.', {
+                        runId: retried.id,
+                    });
+                const previousInputs = await inputsRepo(unit.conn).findMany({
+                    filter: { runId: run.id },
+                });
+                if (!run.commentRootRunId &&
+                    deps.subjects.get(run.subjectKind)?.commentOwnerKey &&
+                    previousInputs.some((input) => input.type === 'comment' &&
+                        !(input.actorKind === 'user' &&
+                            input.actorId === run.ownerUserId &&
+                            jsonObject(input.payload).byAgent !== true)))
+                    throw precondition('RUN_NOT_RETRYABLE', 'Post the comment again to start a new authorized comment chain.');
+                const oldRoot = run.commentRootRunId
+                    ? await findRunRecord(unit.conn, run.commentRootRunId)
+                    : null;
+                const renewComment = oldRoot
+                    ? !(await currentCommentOwner(unit.conn, deps.subjects, oldRoot))
+                    : false;
+                const commentExecution = renewComment &&
+                    run.commentExecution === 'requester' &&
+                    byUserId !== run.actorUserId
+                    ? 'owner'
+                    : run.commentExecution;
+                const identity = await deps.subjects
+                    .get(run.subjectKind)
+                    ?.actsAs?.(unit.conn, {
+                    subjectId: run.subjectId,
+                    agentId: run.agentId,
+                    inputs: previousInputs.map(toInput),
+                    causedByRunId: run.retryOfRunId ?? undefined,
+                    commentExecution,
+                    actorUserId: run.actorUserId,
+                });
+                if (identity && !identity.actorUserId)
+                    throw forbidden(identity.reason ?? 'noOwner');
+                const actorUserId = commentExecution === 'requester'
+                    ? run.actorUserId
+                    : (identity?.actorUserId ?? byUserId);
+                const agent = await requireInvocable(unit, run.agentId, actorUserId);
+                const open = await runsOfKey(unit.conn, run, ['queued', ...ACTIVE], actorUserId);
+                const sameChain = run.commentRootRunId
+                    ? open.filter((candidate) => candidate.commentRootRunId === run.commentRootRunId)
+                    : open;
+                if (sameChain.length > 0)
+                    throw precondition('AGENT_BUSY', 'The agent is already working on this.', {
+                        runId: sameChain[0].id,
+                    });
+                const newId = await createRun(unit, agent, {
+                    subject: { kind: run.subjectKind, id: run.subjectId },
+                    threadScope: run.threadScope,
+                    actorUserId,
+                    commentRootRunId: renewComment ? '' : run.commentRootRunId,
+                    commentExecution,
+                    commentOwnerKey: renewComment
+                        ? ((await deps.subjects
+                            .get(run.subjectKind)
+                            ?.commentOwnerKey?.(unit.conn, run.subjectId)) ?? null)
+                        : run.commentOwnerKey,
+                    requestedByUserId: run.commentRootRunId
+                        ? (run.requestedByUserId ?? run.actorUserId)
+                        : byUserId,
+                    confirmedByUserId: null,
+                    ownerUserId: run.commentRootRunId
+                        ? ((await deps.subjects
+                            .get(run.subjectKind)
+                            ?.responsibleUserId?.(unit.conn, run.subjectId)) ?? null)
+                        : identity
+                            ? actorUserId
+                            : run.ownerUserId,
+                    priority: Number(run.priority),
+                    requires: toRun(run).requires,
+                    retryOfRunId: run.id,
+                    freshSession: run.freshSession,
+                });
+                if (renewComment && oldRoot) {
+                    const origins = await inputsRepo(unit.conn).findMany({
+                        filter: { runId: oldRoot.id },
+                        sort: (s) => [s.field('createdAt').asc(), s.field('id').asc()],
+                    });
+                    const origin = origins.find((input) => input.type === 'comment' &&
+                        jsonObject(input.payload).commentSourceSnapshot === true) ?? origins.find((input) => input.type === 'comment');
+                    if (origin) {
+                        const snapshotId = await insertInput(unit, newId, {
+                            type: 'comment',
+                            actor: toInput(origin).actor,
+                            text: origin.text,
+                            payload: {
+                                ...jsonObject(origin.payload),
+                                commentRootRunId: newId,
+                                commentSourceSnapshot: true,
+                            },
+                        });
+                        await inputsRepo(unit.conn).updateMany({
+                            filter: { id: snapshotId },
+                            values: { handledAt: clock.now().toISOString() },
+                        });
+                    }
+                }
+                for (const input of await pendingInputs(unit.conn, run.id))
+                    await insertInput(unit, newId, {
+                        type: input.type,
+                        actor: toInput(input).actor,
+                        text: input.text,
+                        ...(input.payload === null
+                            ? {}
+                            : {
+                                payload: {
+                                    ...jsonObject(input.payload),
+                                    ...(renewComment ? { commentRootRunId: newId } : {}),
+                                },
+                            }),
+                    });
                 await insertInput(unit, newId, {
-                    type: input.type,
-                    actor: toInput(input).actor,
-                    text: input.text,
-                    ...(input.payload === null ? {} : { payload: input.payload }),
+                    type: 'retry',
+                    actor: {
+                        kind: 'user',
+                        id: byUserId,
+                        name: (await deps.people.names(unit.conn, [byUserId])).get(byUserId) ??
+                            byUserId,
+                    },
+                    text: 'Retry the work of the previous run.',
+                    payload: {
+                        retryOfRunId: run.id,
+                        failureReason: run.failureReason,
+                        source,
+                    },
                 });
-            await insertInput(unit, newId, {
-                type: 'retry',
-                actor: { kind: 'user', id: byUserId, name: byUserId },
-                text: 'Retry the work of the previous run.',
-                payload: { retryOfRunId: run.id, failureReason: run.failureReason },
+                unit.emit({
+                    type: 'run.retried',
+                    runId: newId,
+                    retryOfRunId: run.id,
+                    previousStatus: run.status,
+                });
+                if (run.commentRootRunId)
+                    await deps.reconcileCommentConsent?.(unit, newId);
+                return toRun(await require(unit.conn, newId));
             });
-            return toRun(await require(unit.conn, newId));
-        }),
+        },
         get: async (runId) => (await readRuns([await require(tx.read(), runId)]))[0],
+        async retryInfo(runId) {
+            const conn = tx.read();
+            const next = await runsRepo(conn).findOne({
+                filter: { retryOfRunId: runId },
+                sort: (sort) => [sort.field('createdAt').asc(), sort.field('id').asc()],
+            });
+            if (!next)
+                return null;
+            const input = await inputsRepo(conn).findOne({
+                filter: { runId: next.id, type: 'retry' },
+                sort: (sort) => [
+                    sort.field('createdAt').desc(),
+                    sort.field('id').desc(),
+                ],
+            });
+            const source = input?.payload?.source;
+            return {
+                runId: next.id,
+                actorUserId: next.actorUserId,
+                actorName: input ? toInputView(input).actor.name : next.actorUserId,
+                source: typeof source === 'string' ? source : 'unknown',
+            };
+        },
         async detail(runId) {
             const conn = tx.read();
             const run = await require(conn, runId);
@@ -508,17 +1078,39 @@ export function createRunService(deps) {
                 sort: (sort) => [sort.field('createdAt').asc(), sort.field('id').asc()],
             });
             const repos = await reposRepo(conn).findMany({ filter: { runId } });
+            const retried = await runsRepo(conn).findOne({
+                filter: { retryOfRunId: runId },
+                sort: (sort) => [sort.field('createdAt').asc(), sort.field('id').asc()],
+            });
             const children = await runsRepo(conn).findMany({
                 filter: { parentRunId: runId },
                 sort: (sort) => [sort.field('createdAt').asc(), sort.field('id').asc()],
             });
-            const names = new Map();
-            for (const child of children)
-                if (!names.has(child.agentId))
-                    names.set(child.agentId, (await findAgent(conn, child.agentId))?.name ?? null);
+            const names = await agentNamesOf(conn, [
+                ...children.map((child) => child.agentId),
+                ...inputs.flatMap((input) => input.actorKind === 'agent' && input.actorId ? [input.actorId] : []),
+            ]);
             return {
                 ...(await readRuns([run]))[0],
-                inputs: inputs.map(toInputView),
+                actorName: (await deps.people.names(conn, [run.actorUserId])).get(run.actorUserId) ?? run.actorUserId,
+                confirmedByName: run.confirmedByUserId
+                    ? ((await deps.people.names(conn, [run.confirmedByUserId])).get(run.confirmedByUserId) ?? run.confirmedByUserId)
+                    : undefined,
+                requestedByName: (await deps.people.names(conn, [
+                    run.requestedByUserId ?? run.actorUserId,
+                ])).get(run.requestedByUserId ?? run.actorUserId) ??
+                    run.requestedByUserId ??
+                    run.actorUserId,
+                retriedRunId: retried?.id ?? null,
+                inputs: inputs.map((input) => {
+                    const view = toInputView(input);
+                    const name = view.actor.kind === 'agent' && view.actor.id
+                        ? names.get(view.actor.id)
+                        : undefined;
+                    return name === undefined
+                        ? view
+                        : { ...view, actor: { ...view.actor, name } };
+                }),
                 repos: repos.map(toRepo),
                 usage: await usageOf(conn, runId),
                 children: children.map((child) => ({
@@ -533,6 +1125,33 @@ export function createRunService(deps) {
                 })),
             };
         },
+        async inputTriggers(runIds) {
+            const result = new Map();
+            if (!runIds.length)
+                return result;
+            const rows = await tx
+                .read()
+                .query.selectFrom('agRunInputs as input')
+                .select(['input.runId', 'input.type', 'input.payload'])
+                .where('input.runId', 'in', [...runIds])
+                .where((eb) => eb('input.id', '=', eb
+                .selectFrom('agRunInputs as first')
+                .select('first.id')
+                .whereRef('first.runId', '=', 'input.runId')
+                .orderBy('first.createdAt', 'asc')
+                .orderBy('first.id', 'asc')
+                .limit(1)))
+                .execute();
+            for (const row of rows) {
+                const inputs = result.get(String(row.runId)) ?? [];
+                inputs.push({
+                    type: String(row.type),
+                    payload: jsonObject(row.payload),
+                });
+                result.set(String(row.runId), inputs);
+            }
+            return result;
+        },
         async list(filter) {
             const records = await runsRepo(tx.read()).findMany({
                 filter: (f) => f.and([
@@ -609,6 +1228,9 @@ export function createRunService(deps) {
         workload(query) {
             return readWorkload(tx.read(), clock, deps.runners, query);
         },
+        queueWait(runId) {
+            return readQueueWait(tx.read(), clock, deps.runners, runId, deps.diagnose);
+        },
         async events(runId, afterSeq, limit, types) {
             const conn = tx.read();
             await require(conn, runId);
@@ -643,7 +1265,16 @@ export function createRunService(deps) {
                 lastSeq: events.length > 0 ? events[events.length - 1].seq : afterSeq,
             };
         },
-        authenticateToken: (value) => authenticateRunToken(tx.read(), clock, value),
+        authenticateToken: async (value) => {
+            const conn = tx.read();
+            const identity = await authenticateRunToken(conn, clock, value);
+            if (identity.run.commentRootRunId) {
+                const root = await findRunRecord(conn, identity.run.commentRootRunId);
+                if (!root || !(await currentCommentOwner(conn, deps.subjects, root)))
+                    throw precondition('RUN_TOKEN_INVALID', 'The comment authorization belongs to an earlier owner assignment.');
+            }
+            return identity;
+        },
         async self({ run }) {
             const conn = tx.read();
             const agent = await findAgent(conn, run.agentId);
@@ -672,14 +1303,10 @@ export function createRunService(deps) {
             const conn = tx.read();
             const binding = deps.subjects.get(run.subjectKind);
             const agent = await findAgent(conn, run.agentId);
-            // An online run is held by the application itself, not by a registered runner.
-            const runner = run.runnerId && agent?.type === 'runner'
+            const runner = run.runnerId
                 ? await deps.runners.find(conn, run.runnerId)
                 : null;
-            if (!binding ||
-                !agent ||
-                (agent.type === 'runner' && !runner) ||
-                !isActive(run.status))
+            if (!binding || !agent || !runner || !isActive(run.status))
                 throw notFound('Run context');
             const assembly = await binding.context.assemble(conn, {
                 run: toRun(run),
@@ -688,11 +1315,11 @@ export function createRunService(deps) {
                 inputs: (await pendingInputs(conn, run.id)).map(toInput),
                 cli: deps.cliName,
                 appName: deps.appName,
-                dialect: dialectOf(agent),
-            });
+            }, await binding.context.prepare?.(toRun(run)));
             return assembly.data;
         },
         openOn: openRunsOn,
+        openOnEach: openRunsOnEach,
         pendingInputs: async (conn, runId) => (await pendingInputs(conn, runId)).map(toInput),
         inputsSince: inputsOnSince,
         lastSummary,