@nocobase/app-plugin-agents 0.1.0-beta.1 → 0.1.0-beta.10

package/dist/server/core/runs/claim.js

@@ -6,7 +6,10 @@
  * team or belongs to the person who woke the agent, its features cover what the run requires (worked out from the
  * payload: checkouts, directories, skills, secrets), its owner's local policy (`Runner.policy`) lets it take the
  * agent's runs on the run's subject and repositories, and it has a free slot. A working directory that is a directory
- * on one runner pins the run to that runner, one run at a time per directory.
+ * on one runner pins the run to that runner, one run at a time per directory. A run's variables go to the runner that
+ * takes it, personal ones included, unless one of them is for team runners only (`teamRunnersOnly`): then only a team
+ * runner takes the run, and the variables that asked for one are noted on it (`teamOnlyVariables`), so its wait says
+ * which.
  *
  * A slot is free for a run when the runner's total has room and so does the coding tool it runs with: the tool's limit
  * (`Runner.toolSlots`, never above the total) over the runs of that tool the runner holds here, and what the runner
@@ -14,6 +17,10 @@
  * agent's entries whose tool the runner runs and has room for, so an agent listing two tools runs with the second while
  * the first is full; a run none of whose tools has room is passed over for the runs behind it.
  *
+ * Variables are checked and opened in the claim's own transaction, on its connection: which ones the assembled payload
+ * gets, whether any is for team runners only, and their values, so what the runner receives is what was checked. The
+ * names taken from the runner go in `workspace.passthrough`, without values.
+ *
  * A claim is one transaction per run. It first writes the agent's row (`lockAgentForClaim`): on databases with row
  * locks, concurrent claims for the same agent wait there, so the concurrency count read next is current. The run is
  * then taken with a guarded update (`status = 'queued'`), so two runners can never take the same run. The payload is
@@ -22,39 +29,32 @@
  *
  * Portable by design: the database layer offers no `FOR UPDATE SKIP LOCKED` or advisory locks, and the guarded update
  * plus the agent-row write give the same guarantees on every dialect (SQLite serializes writers anyway).
- *
- * Runners take only runner agents' runs. Online agents' runs are taken by the application itself (`claimServer`, for the
- * server executor of each instance), through the same guarded update, so two instances never take the same run: the
- * holder is the instance (`server:<instance>`), there is no per-agent or per-holder limit, and the payload is a brief,
- * the run's token and its skills (read in the run's sandbox, `online/sandbox.ts`), without directories, variables or
- * mounts.
+
  */
-import { policyAllowsAgent, policyAllowsRepo, policyAllowsSubject, TIMINGS, } from '@nocobase/agent-protocol';
-import { runsTool, toolLimit } from '../../../shared/runners.js';
+import { ANNOUNCED_FAILURES, isProtocolSupported, policyAllowsAgent, policyAllowsRepo, policyAllowsSubject, TIMINGS, } from '@nocobase/agent-protocol';
+import { runnerLowOnDisk, runsEntry, toolLimit, supportsWorkspaceKey, } from '../../../shared/runners.js';
+import { queueStart } from './selection.js';
 import { createHash } from 'node:crypto';
-import { onlineEntriesOrDefault, runnerEntries, sameEntry, } from '../../../shared/agents.js';
 import { later } from '../../kernel/clock.js';
 import { notFound } from '../../kernel/errors.js';
 import { runSecretsKey } from '../../kernel/redaction.js';
 import { cleanList, covers } from '../../kernel/values.js';
 import { findAgent, lockAgentForClaim } from '../agents/index.js';
-import { consultSection, } from '../consultations/index.js';
-import { joinBrief, onlineSkillsSection, renderBrief, } from '../brief/index.js';
+import { joinBrief, renderBrief } from '../brief/index.js';
 import { cliPackageFor } from './cli-package.js';
+import { executionHistory } from './execution.js';
+import { describeVariables, variableRefs, } from '../variables/index.js';
 import { mountsFor, prepareExtensions, repoAccessFor, sessionKeyOf, withSections, } from './extensions.js';
-import { dialectOf, } from './ports.js';
 import { MAX_CLAIM_FAILURES, toolPolicyFor } from './policy.js';
 import { mintRunToken } from './run-tokens.js';
 import { runsHeldByTool } from './runner-view.js';
 import { ACTIVE, countActive, eventsRepo, findRunRecord, markDelivered, pendingInputs, runsOfKey, runsRepo, sessionsRepo, toInput, toRun, } from './run.store.js';
+import { dropInputs } from './input-gate.js';
 import { finishRun } from './transitions.js';
+import { refreshQueuedIdentity } from './identity.js';
 import { consumeReset, saveBrief } from './workspace.store.js';
 /** Queued runs looked at per claim, oldest first by priority. */
 const CANDIDATES = 50;
-/** Whether a run holder id is an application instance's (an online run's), not a runner's. */
-export function isServerHolder(runnerId) {
-    return runnerId !== null && runnerId.startsWith('server:');
-}
 class AssemblyError extends Error {
     cause;
     constructor(message, cause) {
@@ -70,6 +70,15 @@ class NotForThisRunner extends Error {
         this.name = 'NotForThisRunner';
     }
 }
+/** The run gets variables only team runners may receive, and this runner is a personal one. */
+class TeamRunnersOnly extends NotForThisRunner {
+    variables;
+    constructor(variables) {
+        super();
+        this.variables = variables;
+        this.name = 'TeamRunnersOnly';
+    }
+}
 function toolRoom(tools) {
     const left = new Map(Object.entries(tools ?? {}));
     return {
@@ -82,50 +91,50 @@ function toolRoom(tools) {
     };
 }
 /**
- * The entry `runner` takes a run of `agent` with: the first whose tool it has enabled, installed and signed in. Null
- * when it has none of them, and always for an online agent, which has no tool.
+ * The entry `runner` takes a run of `agent` with: the first whose tool it has enabled, installed and signed in, with
+ * the entry's model among those it reports (`runsEntry`). Null when it has none of them.
  */
 export function pickEntry(runner, agent) {
-    return (runnerEntries(agent).find((entry) => runsTool(runner, entry.tool)) ?? null);
+    return agent.modelEntries.find((entry) => runsEntry(runner, entry)) ?? null;
 }
 /**
  * The entry `runner` takes a run of `agent` with when some of its tools are full: the first whose tool it runs and
  * `open` says has room. Null when none has.
  */
 export function pickOpenEntry(runner, agent, open) {
-    return (runnerEntries(agent).find((entry) => runsTool(runner, entry.tool) && open(entry.tool)) ?? null);
+    return (agent.modelEntries.find((entry) => runsEntry(runner, entry) && open(entry.tool)) ?? null);
 }
-/** Whether `runner` has one of `agent`'s tools enabled, installed and signed in; never for an online agent. */
+/** Whether `runner` has one of `agent`'s tools and models enabled, installed, signed in and reported. */
 export function hasTool(runner, agent) {
     return pickEntry(runner, agent) !== null;
 }
 /**
- * The entry an online run uses: the one its subject asks for while the agent lists it, else the agent's first; for an
- * agent that lists none, the system default chat model (`fallback`).
+ * Whether `runner` may run work of `agent` as `actorUserId` that needs `requires`, before any lock is taken and before
+ * a payload is known: the agent enabled, its tool and model reported there, its owner's policy, and trust.
  */
-export function onlineEntryOf(agent, wanted, fallback = null) {
-    const entries = onlineEntriesOrDefault(agent, fallback);
-    return ((wanted && entries.find((entry) => sameEntry(entry, wanted))) ??
-        entries[0] ??
-        null);
-}
-/** Whether `runner` may run `run` of `agent`, before any lock is taken and before its payload is known. */
-export function fits(runner, agent, run) {
-    if (agent.archivedAt || agent.type !== 'runner')
+export function fitsActor(runner, agent, actorUserId, requires) {
+    if (agent.status !== 'enabled' || runnerLowOnDisk(runner))
+        return false;
+    if (!isProtocolSupported(runner.protocolVersion) ||
+        runner.status === 'upgrade_required' ||
+        runner.status === 'revoked')
         return false;
-    if (!covers(runner.features, toRun(run).requires))
+    if (!covers(runner.features, requires))
         return false;
     if (!hasTool(runner, agent))
         return false;
     if (!policyAllowsAgent(runner.policy, agent))
         return false;
-    if (agent.runnerIds.length > 0 && !agent.runnerIds.includes(runner.id))
-        return false;
-    return runner.trust === 'team' || runner.ownerUserId === run.actorUserId;
+    return runner.trust === 'team' || runner.ownerUserId === actorUserId;
+}
+/** Whether `runner` may run `run` of `agent`, before any lock is taken and before its payload is known. */
+export function fits(runner, agent, run) {
+    return fitsActor(runner, agent, run.actorUserId, toRun(run).requires);
 }
 /** The runner features a payload needs. */
-export function payloadRequires(dirs, skills, variables) {
+export function payloadRequires(dirs, skills, variables, workspaceKey = false) {
     return [
+        ...(workspaceKey ? ['workspaceKey'] : []),
         ...(dirs.some((dir) => dir.kind === 'repo') ? ['checkout'] : []),
         ...(dirs.some((dir) => dir.kind === 'directory')
             ? ['directories']
@@ -172,7 +181,6 @@ function fingerprint(agent, entry, layers, skills) {
 /** The brief for `assembly`, with the skills a run would get. */
 export function briefOf(agent, assembly, skills, cli, appName) {
     const rendered = renderBrief({
-        dialect: dialectOf(agent),
         agentName: agent.name,
         subject: { noun: assembly.subject.noun, key: assembly.subject.key },
         task: assembly.task,
@@ -192,6 +200,10 @@ export function briefOf(agent, assembly, skills, cli, appName) {
         : assembly.turn.prompt;
     return { layers, turn, prompt: joinBrief(layers) };
 }
+/** Whether `runner` asks for repository credentials on demand rather than taking them with the claim. */
+export function asksCredentialsOnDemand(runner) {
+    return runner.features.includes('gitCredentials');
+}
 const DIRECTORY_KEY_SEPARATOR = '\n';
 /** The directories a run holds on its runner, as stored in `agRuns.directoryKey`. */
 function directoryKeyOf(runnerId, dirs) {
@@ -214,8 +226,214 @@ async function directoryBusy(conn, runnerId, runId, key) {
         .split(DIRECTORY_KEY_SEPARATOR)
         .some((part) => part !== '' && wanted.has(part)));
 }
+/** Resolve omitted subject input in the claim transaction, keeping it in the audit history. */
+async function settleClaimInputs(conn, pending, effective, now) {
+    const ids = new Set(effective.map((input) => input.id));
+    await dropInputs(conn, pending.filter((input) => !ids.has(input.id)).map((input) => input.id), now);
+    await markDelivered(conn, pending.filter((input) => ids.has(input.id)), now);
+}
 export function createClaimService(deps) {
     const { tx, clock } = deps;
+    /** Database reads only; used by the actual claim and ordered-model diagnostics. */
+    async function assemblyCompatibility(conn, run, agent, runner, assembly) {
+        if (!isProtocolSupported(runner.protocolVersion) ||
+            (assembly.workspaceKey && !supportsWorkspaceKey(runner)))
+            return 'incompatible';
+        const skills = await deps.skills.forRun(conn, skillTargets(agent, assembly), run.id);
+        const targets = variableTargets(agent, assembly);
+        const names = await deps.variables.namesOf(conn, targets);
+        if (!covers(runner.features, [
+            ...run.requires,
+            ...payloadRequires(payloadDirs(assembly.dirs), skills.length, names.length, Boolean(assembly.workspaceKey)),
+        ]))
+            return 'incompatible';
+        if (!fitsActor(runner, agent, run.actorUserId, run.requires) ||
+            !policyAllowsSubject(runner.policy, assembly.subject.key) ||
+            assembly.dirs.some((dir) => (dir.kind === 'repo' && !policyAllowsRepo(runner.policy, dir.url)) ||
+                (dir.kind === 'directory' && dir.runnerId !== runner.id)))
+            return 'restricted';
+        if (runner.trust !== 'team' &&
+            (await deps.variables.teamOnly(conn, targets)).length > 0)
+            return 'restricted';
+        return 'ready';
+    }
+    async function selectionFacts(conn, run, agent, requirePolicy = true) {
+        const policy = await deps.selectionPolicies?.forRun(conn, run);
+        if ((requirePolicy && !policy) || !deps.runners)
+            return null;
+        const now = clock.now();
+        const start = queueStart(run);
+        const registered = await deps.runners.all(conn);
+        const binding = deps.subjects.get(run.subject.kind);
+        if (!binding)
+            throw new Error(`No context provider for ${run.subject.kind}.`);
+        const inputs = (await pendingInputs(conn, run.id)).map(toInput);
+        const active = await countActive(conn, 'agentId', agent.id);
+        const sameWork = (await runsOfKey(conn, {
+            agentId: agent.id,
+            subjectKind: run.subject.kind,
+            subjectId: run.subject.id,
+            threadScope: run.threadScope,
+        }, ACTIVE)).length > 0;
+        const entries = [];
+        for (const entry of agent.modelEntries) {
+            const single = { ...agent, modelEntries: [entry] };
+            const candidates = registered.filter((runner) => runner.status !== 'revoked');
+            const connected = candidates.filter((runner) => (runner.status === 'online' ||
+                runner.status === 'upgrade_required') &&
+                runner.lastSeenAt !== null &&
+                new Date(runner.lastSeenAt).getTime() + TIMINGS.offlineAfterMs >
+                    now.getTime());
+            const installed = connected.filter((runner) => runner.tools.some((tool) => tool.kind === entry.tool));
+            const usable = installed.filter((runner) => runsEntry(runner, entry));
+            const online = usable.filter((runner) => runner.trust === 'team' || runner.ownerUserId === run.actorUserId);
+            const compatible = [];
+            const loads = [];
+            let unknown = false;
+            let incompatible = false;
+            let ready = false;
+            let directoryBlocked = false;
+            for (const runner of online) {
+                if (!isProtocolSupported(runner.protocolVersion) ||
+                    runner.status === 'upgrade_required') {
+                    incompatible = true;
+                    loads.push({
+                        name: runner.name,
+                        ownerUserId: runner.ownerUserId,
+                        reason: 'incompatible',
+                        lastSeenAt: runner.lastSeenAt,
+                    });
+                    continue;
+                }
+                const assembly = await binding.context
+                    .assemble(conn, {
+                    run: run,
+                    agent,
+                    runner,
+                    inputs,
+                    cli: deps.cli.name,
+                    appName: deps.app.name,
+                })
+                    .catch(() => null);
+                if (!assembly) {
+                    unknown = true;
+                    loads.push({
+                        name: runner.name,
+                        ownerUserId: runner.ownerUserId,
+                        reason: 'unknown',
+                        lastSeenAt: runner.lastSeenAt,
+                    });
+                    continue;
+                }
+                const reason = await assemblyCompatibility(conn, run, single, runner, assembly);
+                if (reason !== 'ready') {
+                    incompatible ||= reason === 'incompatible';
+                    loads.push({
+                        name: runner.name,
+                        ownerUserId: runner.ownerUserId,
+                        reason,
+                        lastSeenAt: runner.lastSeenAt,
+                    });
+                    continue;
+                }
+                const requiredVariables = await deps.variables.passthroughOf(conn, variableTargets(single, assembly));
+                if (requiredVariables.length > 0 && runner.variables == null) {
+                    unknown = true;
+                    continue;
+                }
+                if (requiredVariables.some((name) => !runner.variables?.includes(name)))
+                    continue;
+                compatible.push(runner);
+                const byTool = await runsHeldByTool(conn, runner.id);
+                const used = await deps.slotsUsed(conn, runner.id);
+                const directory = directoryKeyOf(runner.id, payloadDirs(assembly.dirs));
+                const blockedDirectory = directory !== null &&
+                    (await directoryBusy(conn, runner.id, run.id, directory));
+                directoryBlocked ||= blockedDirectory;
+                const hasRoom = !runner.draining &&
+                    (runner.globalFree ?? 1) > 0 &&
+                    used < runner.slots &&
+                    (byTool[entry.tool] ?? 0) < toolLimit(runner, entry.tool) &&
+                    (runner.toolLoad?.[entry.tool]?.free ?? 1) > 0 &&
+                    !blockedDirectory;
+                ready ||= hasRoom && runner.globalFree !== undefined;
+                if (hasRoom && runner.globalFree === undefined)
+                    unknown = true;
+                loads.push({
+                    name: runner.name,
+                    ownerUserId: runner.ownerUserId,
+                    reason: hasRoom
+                        ? runner.globalFree === undefined
+                            ? 'unknown'
+                            : 'ready'
+                        : runner.draining
+                            ? runner.draining
+                            : blockedDirectory
+                                ? 'restricted'
+                                : 'busy',
+                    lastSeenAt: runner.lastSeenAt,
+                    used,
+                    limit: runner.slots,
+                    toolUsed: byTool[entry.tool] ?? 0,
+                    toolLimit: toolLimit(runner, entry.tool),
+                    reportedFree: runner.toolLoad?.[entry.tool]?.free,
+                    reportedTotalFree: runner.globalFree,
+                });
+            }
+            let reason = compatible.length
+                ? ready
+                    ? 'ready'
+                    : 'busy'
+                : online.length
+                    ? incompatible
+                        ? 'incompatible'
+                        : 'restricted'
+                    : usable.length
+                        ? 'noSharedRunner'
+                        : installed.length
+                            ? 'toolUnavailable'
+                            : connected.length
+                                ? 'toolNotInstalled'
+                                : 'offline';
+            if (directoryBlocked && !ready)
+                reason = 'restricted';
+            if (!ready &&
+                compatible.length > 0 &&
+                loads.every((runner) => runner.reason === 'updatePending' || runner.reason === 'pruning'))
+                reason = loads.some((runner) => runner.reason === 'updatePending')
+                    ? 'updatePending'
+                    : 'pruning';
+            if (unknown &&
+                !ready &&
+                !loads.some((runner) => runner.reason === 'busy'))
+                reason = 'unknown';
+            if (compatible.length && sameWork)
+                reason = 'sameWorkActive';
+            else if (compatible.length && active >= agent.maxConcurrentRuns)
+                reason = 'concurrencyFull';
+            else if (start > now.getTime())
+                reason = 'delayed';
+            entries.push({
+                tool: entry.tool,
+                model: entry.model,
+                reason,
+                compatibleCount: compatible.length,
+                blockers: [
+                    ...(unknown ? ['unknown'] : []),
+                    ...new Set(loads
+                        .map((runner) => runner.reason)
+                        .filter((reason) => reason !== undefined && reason !== 'ready')),
+                ],
+                runners: loads,
+            });
+        }
+        return {
+            queueEnteredAt: new Date(start).toISOString(),
+            fallbackAfterSeconds: policy?.fallbackAfterSeconds ?? 0,
+            sampledAt: now.toISOString(),
+            entries,
+        };
+    }
     async function assemble({ conn }, run, agent, runner, inputs, leaseExpiresAt, prepared, entry) {
         const binding = deps.subjects.get(run.subjectKind);
         if (!binding)
@@ -228,9 +446,13 @@ export function createClaimService(deps) {
             inputs,
             cli: deps.cli.name,
             appName: deps.app.name,
-            dialect: 'cli',
         };
-        const assembly = await binding.context.assemble(conn, claim);
+        const assembly = await binding.context.assemble(conn, claim, prepared.get('subject'));
+        // workspace.key is required for coordinating runs; old runners must not silently ignore it.
+        if ((await assemblyCompatibility(conn, toRun(run), agent, runner, assembly)) === 'incompatible')
+            throw new NotForThisRunner();
+        inputs = assembly.inputs ?? inputs;
+        const effectiveClaim = { ...claim, inputs };
         // Its owner's local policy keeps this runner off the subject, or off one of the repositories: another runner takes
         // the run.
         if (!policyAllowsSubject(runner.policy, assembly.subject.key) ||
@@ -249,16 +471,25 @@ export function createClaimService(deps) {
         const names = await deps.variables.namesOf(conn, variables);
         const requires = cleanList([
             ...view.requires,
-            ...payloadRequires(dirs, skills.length, names.length),
+            ...payloadRequires(dirs, skills.length, names.length, Boolean(assembly.workspaceKey)),
         ]);
         if (!covers(runner.features, requires))
             throw new NotForThisRunner();
+        // A variable for team runners only keeps a personal runner off the run.
+        if (names.length > 0 && runner.trust !== 'team') {
+            const teamOnly = await deps.variables.teamOnly(conn, variables);
+            if (teamOnly.length > 0)
+                throw new TeamRunnersOnly(teamOnly);
+        }
         const env = names.length > 0
             ? await deps.variables.forRun(conn, variables, {
                 runId: run.id,
                 runnerId: runner.id,
             })
             : [];
+        // Variables taken from the runner: names only. A runner that does not provide one fails the run while preparing
+        // it, saying how to provide it; runners are not chosen by them.
+        const passthrough = await deps.variables.passthroughOf(conn, variables);
         const nowText = clock.now().toISOString();
         const clean = await consumeReset(conn, { kind: run.subjectKind, id: run.subjectId }, run.id, nowText);
         const session = await sessionsRepo(conn).findOne({
@@ -274,6 +505,7 @@ export function createClaimService(deps) {
         const git = await repoAccessFor(conn, deps.repoAccess, {
             claim,
             repos: dirs.filter((dir) => dir.kind === 'repo'),
+            onDemand: asksCredentialsOnDemand(runner),
         }, prepared);
         deps.secrets?.remember(runSecretsKey(run.id), [
             ...env.map((variable) => variable.value),
@@ -284,9 +516,10 @@ export function createClaimService(deps) {
             filter: { runId: run.id },
             sort: (sort) => sort.field('seq').desc(),
         });
-        const brief = briefOf(agent, await withSections(conn, deps.sections, claim, assembly, prepared), skills, deps.cli.name, deps.app.name);
+        const brief = briefOf(agent, await withSections(conn, deps.sections, effectiveClaim, assembly, prepared), skills, deps.cli.name, deps.app.name);
         const briefFingerprint = fingerprint(agent, entry, brief.layers, skills);
-        const resume = !clean &&
+        const resume = !run.freshSession &&
+            !clean &&
             session &&
             !session.poisoned &&
             session.fingerprint === briefFingerprint;
@@ -294,13 +527,23 @@ export function createClaimService(deps) {
         // hears what changed in them in its turn instead.
         const { mounts, resumeNotes } = runner.features.includes('mounts')
             ? await mountsFor(conn, deps.mounts, {
-                claim,
+                claim: effectiveClaim,
                 assembly,
                 session: resume ? 'resume' : 'fresh',
                 sessionKey: sessionKeyOf(view),
             }, prepared)
             : { mounts: [], resumeNotes: [] };
-        const turn = [brief.turn, ...resumeNotes].join('\n\n');
+        const sessionNote = resume ? assembly.turn.resumed : assembly.turn.fresh;
+        const turn = [
+            brief.turn,
+            ...(run.failureReason === 'runnerUpgrade'
+                ? [
+                    'The previous attempt was interrupted by a runner upgrade. Continue from the current state.',
+                ]
+                : []),
+            ...resumeNotes,
+            ...(sessionNote ? [sessionNote] : []),
+        ].join('\n\n');
         await saveBrief(conn, () => deps.ids.next(), {
             runId: run.id,
             attempt: Number(run.attempt),
@@ -319,6 +562,7 @@ export function createClaimService(deps) {
                 leaseExpiresAt,
                 requires,
                 firstSeq: (last ? Number(last.seq) : 0) + 1,
+                acceptedFailures: Object.keys(ANNOUNCED_FAILURES),
             },
             app: deps.app,
             subject: {
@@ -340,9 +584,13 @@ export function createClaimService(deps) {
             },
             inputs,
             workspace: {
+                sessionScope: run.threadScope,
                 dirs,
                 env,
+                ...(passthrough.length > 0 ? { passthrough } : {}),
                 ...(clean ? { clean: true } : {}),
+                ...(assembly.workspaceKey ? { key: assembly.workspaceKey } : {}),
+                ...(assembly.readOnly ? { readOnly: true } : {}),
                 ...(git ? { git } : {}),
             },
             skills,
@@ -368,75 +616,266 @@ export function createClaimService(deps) {
             requires,
             directoryKey,
             entry,
+            gitOnDemand: git?.onDemand ?? [],
         };
     }
+    /**
+     * Notes on a queued run which of its variables kept a personal runner off it, and tells its actor and owner the first
+     * time; nothing when that is what it says already.
+     */
+    async function noteTeamOnly(candidate, variables) {
+        const same = (value) => JSON.stringify(variableRefs(value)) === JSON.stringify(variables);
+        if (same(candidate.teamOnlyVariables))
+            return;
+        await tx.run(async (unit) => {
+            const run = await findRunRecord(unit.conn, candidate.id);
+            if (!run || run.status !== 'queued' || same(run.teamOnlyVariables))
+                return;
+            await runsRepo(unit.conn).updateMany({
+                filter: (f) => f.and([f.string('id').eq(run.id), f.string('status').eq('queued')]),
+                values: { teamOnlyVariables: variables.map((each) => ({ ...each })) },
+            });
+            unit.emit({ type: 'run.changed', runId: run.id, status: 'queued' });
+            if (variableRefs(run.teamOnlyVariables).length === 0)
+                unit.emit({
+                    type: 'notice',
+                    notice: {
+                        key: `run-secrets:${run.id}`,
+                        type: 'run_secrets_not_allowed',
+                        userIds: [
+                            ...new Set([run.actorUserId, run.ownerUserId].filter((id) => Boolean(id))),
+                        ],
+                        subject: { kind: 'run', id: run.id, label: run.id },
+                        title: 'A run waits for a team runtime',
+                        body: `Some of its variables are for team runtimes only: ${describeVariables(variables)}.`,
+                        params: {
+                            runId: run.id,
+                            agentId: run.agentId,
+                            variables: describeVariables(variables),
+                        },
+                    },
+                });
+        });
+    }
+    async function admit(unit, run, agent, runner, inputs) {
+        const rejection = await deps.subjects
+            .get(run.subjectKind)
+            ?.context.admit?.(unit.conn, {
+            run: toRun(run),
+            agent,
+            runner,
+            inputs,
+            cli: deps.cli.name,
+            appName: deps.app.name,
+        });
+        if (!rejection)
+            return true;
+        await finishRun(unit, deps, run, {
+            status: 'cancelled',
+            reason: null,
+            detail: `${rejection.reason}${rejection.detail ? `: ${rejection.detail}` : ''}`,
+        });
+        return false;
+    }
     async function attempt(runner, agent, candidate, reported) {
-        // Before the transaction: on SQLite it holds the only connection, so the providers read what else they need now.
-        const prepared = await prepareExtensions(toRun(candidate), deps.sections, deps.mounts, (error) => deps.onClaimFailure?.(candidate.id, error), deps.repoAccess);
-        return tx.run(async (unit) => {
-            const { conn } = unit;
-            const now = clock.now();
-            const nowText = now.toISOString();
-            await lockAgentForClaim(conn, agent.id, nowText);
-            if ((await countActive(conn, 'agentId', agent.id)) >=
-                agent.maxConcurrentRuns)
-                return { kind: 'skipped' };
-            // Slots are shared with the jobs the runner holds.
-            if ((await deps.slotsUsed(conn, runner.id)) >= runner.slots)
-                return { kind: 'skipped' };
-            // The first of the agent's tools with room, by its limit here and by what the runner said it can take.
-            const byTool = await runsHeldByTool(conn, runner.id);
-            const entry = pickOpenEntry(runner, agent, (tool) => (byTool[tool] ?? 0) < toolLimit(runner, tool) && reported.has(tool));
-            if (!entry)
-                return { kind: 'skipped' };
-            const busy = await runsOfKey(conn, candidate, ACTIVE);
-            if (busy.length > 0)
-                return { kind: 'skipped' };
-            const leaseExpiresAt = later(now, TIMINGS.leaseMs);
-            const taken = await runsRepo(conn).updateMany({
-                filter: (f) => f.and([
-                    f.string('id').eq(candidate.id),
-                    f.string('status').eq('queued'),
-                ]),
-                values: {
-                    status: 'dispatched',
-                    runnerId: runner.id,
-                    leaseExpiresAt,
-                    dispatchedAt: nowText,
-                    lastActivityAt: nowText,
-                    availableAt: null,
-                    updatedAt: nowText,
-                },
+        // Repair pre-upgrade queued work before even checking personal runner ownership.
+        if (deps.subjects.get(candidate.subjectKind)?.actsAs) {
+            const current = await tx.run(async (unit) => {
+                await lockAgentForClaim(unit.conn, agent.id, clock.now().toISOString());
+                const run = await findRunRecord(unit.conn, candidate.id);
+                return run?.status === 'queued'
+                    ? refreshQueuedIdentity(unit, deps, run)
+                    : null;
             });
-            if (taken.updatedCount !== 1)
+            if (!current)
                 return { kind: 'skipped' };
-            const run = (await findRunRecord(conn, candidate.id));
-            const pending = await pendingInputs(conn, run.id);
-            let assembled;
+            candidate = current;
+        }
+        // Avoid assembling or asking authorization when a cheap claim rule already rules this work out.
+        const conn = tx.read();
+        if (!fits(runner, agent, candidate) ||
+            (await deps.slotsUsed(conn, runner.id)) >= runner.slots ||
+            (await countActive(conn, 'agentId', agent.id)) >=
+                agent.maxConcurrentRuns ||
+            (await runsOfKey(conn, candidate, ACTIVE)).length > 0)
+            return { kind: 'skipped' };
+        // Before the transaction: on SQLite it holds the only connection, so the providers read what else they need now.
+        const prepared = new Map(await prepareExtensions(toRun(candidate), deps.sections, deps.mounts, (error) => deps.onClaimFailure?.(candidate.id, error), deps.repoAccess, { onDemand: asksCredentialsOnDemand(runner) }));
+        const subjectContext = deps.subjects.get(candidate.subjectKind)?.context;
+        if (subjectContext?.prepare) {
             try {
-                assembled = await assemble(unit, run, agent, runner, pending.map(toInput), leaseExpiresAt, prepared, entry);
+                prepared.set('subject', await subjectContext.prepare(toRun(candidate)));
             }
             catch (error) {
-                if (error instanceof NotForThisRunner)
-                    throw error;
-                throw new AssemblyError(error instanceof Error ? error.message : String(error), error);
+                deps.onClaimFailure?.(candidate.id, error);
             }
-            await markDelivered(conn, pending, nowText);
-            await runsRepo(conn).updateMany({
-                filter: { id: run.id },
-                values: {
-                    payloadFingerprint: assembled.fingerprint,
-                    requires: [...assembled.requires],
-                    directoryKey: assembled.directoryKey,
-                    tool: assembled.entry.tool,
-                    modelService: null,
-                    model: assembled.entry.model,
-                    effort: assembled.entry.effort ?? null,
-                },
+        }
+        let taken;
+        try {
+            taken = await tx.run(async (unit) => {
+                const { conn } = unit;
+                const now = clock.now();
+                const nowText = now.toISOString();
+                await lockAgentForClaim(conn, agent.id, nowText);
+                const queuedRun = await findRunRecord(conn, candidate.id);
+                if (!queuedRun || queuedRun.status !== 'queued')
+                    return null;
+                const identity = await refreshQueuedIdentity(unit, deps, queuedRun);
+                // Providers were prepared for the candidate's identity outside this transaction.
+                if (!identity || identity.actorUserId !== candidate.actorUserId)
+                    return null;
+                if ((await countActive(conn, 'agentId', agent.id)) >=
+                    agent.maxConcurrentRuns)
+                    return null;
+                // Slots are shared with the jobs the runner holds.
+                if ((await deps.slotsUsed(conn, runner.id)) >= runner.slots)
+                    return null;
+                // The first of the agent's tools with room, by its limit here and by what the runner said it can take.
+                const byTool = await runsHeldByTool(conn, runner.id);
+                const current = await findRunRecord(conn, candidate.id);
+                if (!current ||
+                    current.status !== 'queued' ||
+                    (current.availableAt &&
+                        new Date(current.availableAt).getTime() > now.getTime()))
+                    return null;
+                const entry = pickOpenEntry(runner, agent, (tool) => (byTool[tool] ?? 0) < toolLimit(runner, tool) && reported.has(tool));
+                if (!entry)
+                    return null;
+                const busy = await runsOfKey(conn, candidate, ACTIVE);
+                if (busy.length > 0)
+                    return null;
+                const leaseExpiresAt = later(now, TIMINGS.leaseMs);
+                const claimed = await runsRepo(conn).updateMany({
+                    filter: (f) => f.and([
+                        f.string('id').eq(candidate.id),
+                        f.string('status').eq('queued'),
+                        f.string('actorUserId').eq(candidate.actorUserId),
+                    ]),
+                    values: {
+                        status: 'dispatched',
+                        runnerId: runner.id,
+                        // Brief providers observe this reservation inside the claim transaction.
+                        // Replace a previous attempt's tool before computing the roster.
+                        tool: entry.tool,
+                        leaseExpiresAt,
+                        dispatchedAt: nowText,
+                        lastActivityAt: nowText,
+                        availableAt: null,
+                        updatedAt: nowText,
+                    },
+                });
+                if (claimed.updatedCount !== 1)
+                    return null;
+                const run = (await findRunRecord(conn, candidate.id));
+                const pending = await pendingInputs(conn, run.id);
+                let assembled;
+                let selectionSnapshot;
+                try {
+                    if (!(await admit(unit, run, agent, runner, pending.map(toInput))))
+                        return null;
+                    // Admission must precede preflight assembly: a missing or obsolete
+                    // subject is cancelled normally, rather than counted as setup failure.
+                    const selection = await selectionFacts(conn, toRun(current), agent);
+                    const elapsed = Math.max(0, (now.getTime() - queueStart(toRun(current))) / 1000);
+                    const preferredAvailable = (selection?.entries[0]?.compatibleCount ?? 0) > 0 ||
+                        selection?.entries[0]?.reason === 'unknown' ||
+                        selection?.entries[0]?.blockers?.includes('unknown') === true;
+                    const chosenIndex = agent.modelEntries.indexOf(entry);
+                    if (selection && chosenIndex > 0) {
+                        // Throw to roll back the provisional dispatch; the original run keeps
+                        // waiting for its first choice without consuming an attempt or token.
+                        if (preferredAvailable && elapsed < selection.fallbackAfterSeconds)
+                            throw new NotForThisRunner();
+                        selectionSnapshot = {
+                            reason: preferredAvailable
+                                ? 'preferredQueued'
+                                : 'preferredUnavailable',
+                            preferredTool: agent.modelEntries[0].tool,
+                            preferredModel: agent.modelEntries[0].model,
+                            queueEnteredAt: selection.queueEnteredAt,
+                            waitedSeconds: elapsed,
+                        };
+                    }
+                    assembled = await assemble(unit, run, agent, runner, pending.map(toInput), leaseExpiresAt, prepared, entry);
+                }
+                catch (error) {
+                    if (error instanceof NotForThisRunner)
+                        throw error;
+                    throw new AssemblyError(error instanceof Error ? error.message : String(error), error);
+                }
+                await settleClaimInputs(conn, pending, assembled.payload.inputs, nowText);
+                await runsRepo(conn).updateMany({
+                    filter: { id: run.id },
+                    values: {
+                        payloadFingerprint: assembled.fingerprint,
+                        requires: [...assembled.requires],
+                        directoryKey: assembled.directoryKey,
+                        tool: assembled.entry.tool,
+                        executionHistory: executionHistory(run, {
+                            ...(selectionSnapshot ? { selection: selectionSnapshot } : {}),
+                            attempt: Number(run.attempt),
+                            runnerId: runner.id,
+                            runnerName: runner.name,
+                            runnerOwnerUserId: runner.ownerUserId,
+                            runnerOwnerName: runner.ownerUserId
+                                ? ((await deps.people?.names(conn, [runner.ownerUserId]))?.get(runner.ownerUserId) ?? runner.ownerName)
+                                : null,
+                            runnerTrust: runner.trust,
+                            tool: assembled.entry.tool,
+                            toolVersion: runner.tools.find((tool) => tool.kind === assembled.entry.tool)
+                                ?.version ?? null,
+                            modelService: null,
+                            model: assembled.entry.model,
+                            actualModels: [],
+                            effort: assembled.entry.effort ?? null,
+                            dispatchedAt: nowText,
+                            finishedAt: null,
+                            failureReason: null,
+                        }),
+                        modelService: null,
+                        model: assembled.entry.model,
+                        effort: assembled.entry.effort ?? null,
+                        teamOnlyVariables: null,
+                        gitCredentialUrls: assembled.gitOnDemand.length > 0
+                            ? [...assembled.gitOnDemand]
+                            : null,
+                    },
+                });
+                unit.emit({ type: 'run.changed', runId: run.id, status: 'dispatched' });
+                if (variableRefs(candidate.teamOnlyVariables).length > 0)
+                    unit.emit({
+                        type: 'notice.cleared',
+                        notice: {
+                            type: 'run_secrets_not_allowed',
+                            subject: { kind: 'run', id: run.id, label: run.id },
+                        },
+                    });
+                return assembled.payload;
             });
-            unit.emit({ type: 'run.changed', runId: run.id, status: 'dispatched' });
-            return { kind: 'claimed', payload: assembled.payload };
-        });
+        }
+        catch (error) {
+            await discardRepoAccess(candidate, prepared);
+            if (error instanceof TeamRunnersOnly) {
+                await noteTeamOnly(candidate, error.variables);
+                return { kind: 'skipped' };
+            }
+            throw error;
+        }
+        if (!taken) {
+            await discardRepoAccess(candidate, prepared);
+            return { kind: 'skipped' };
+        }
+        return { kind: 'claimed', payload: taken };
+    }
+    async function discardRepoAccess(run, prepared) {
+        for (const provider of deps.repoAccess?.list() ?? []) {
+            try {
+                await provider.discard?.(toRun(run), prepared.get(`repo:${provider.key}`));
+            }
+            catch (error) {
+                deps.onClaimFailure?.(run.id, error);
+            }
+        }
     }
     /** Counts a failed assembly; the run fails once it has failed too often. */
     async function recordFailure(runId, error) {
@@ -463,15 +902,12 @@ export function createClaimService(deps) {
             });
         });
     }
-    /** Queued runs of agents of `type` that may be claimed now, in claim order. */
-    async function candidatesOf(type) {
+    /** Queued runs that may be claimed now, in claim order. */
+    async function candidates() {
         const now = clock.now();
         return runsRepo(tx.read()).findMany({
             filter: (f) => f.and([
                 f.string('status').eq('queued'),
-                f.string('agentType').eq(type),
-                // A consultation is taken by the holder of the run that asked it, never from the queue.
-                f.string('parentRunId').empty(),
                 f.or([
                     f.date('availableAt').empty(),
                     f.date('availableAt').notAfter(now),
@@ -485,151 +921,22 @@ export function createClaimService(deps) {
             limit: CANDIDATES,
         });
     }
-    /** Takes an online run for `holder` in one transaction, or skips it when another holder or run got there first. */
-    async function attemptServer(holder, agent, candidate) {
-        const prepared = await prepareExtensions(toRun(candidate), deps.sections, undefined, (error) => deps.onClaimFailure?.(candidate.id, error));
-        return tx.run(async (unit) => {
-            const { conn } = unit;
-            const now = clock.now();
-            const nowText = now.toISOString();
-            // Serializes claims and enqueues of this agent, so one key never has two runs held.
-            await lockAgentForClaim(conn, agent.id, nowText);
-            if ((await runsOfKey(conn, candidate, ACTIVE)).length > 0)
-                return null;
-            const leaseExpiresAt = later(now, TIMINGS.leaseMs);
-            const taken = await runsRepo(conn).updateMany({
-                filter: (f) => f.and([
-                    f.string('id').eq(candidate.id),
-                    f.string('status').eq('queued'),
-                ]),
-                values: {
-                    status: 'dispatched',
-                    runnerId: holder.id,
-                    leaseExpiresAt,
-                    dispatchedAt: nowText,
-                    lastActivityAt: nowText,
-                    availableAt: null,
-                    updatedAt: nowText,
-                },
-            });
-            if (taken.updatedCount !== 1)
-                return null;
-            const run = (await findRunRecord(conn, candidate.id));
-            const pending = await pendingInputs(conn, run.id);
-            const inputs = pending.map(toInput);
-            let claimed;
-            try {
-                claimed = await assembleServer(unit, run, agent, holder, inputs, leaseExpiresAt, prepared);
-            }
-            catch (error) {
-                throw new AssemblyError(error instanceof Error ? error.message : String(error), error);
-            }
-            await markDelivered(conn, pending, nowText);
-            await runsRepo(conn).updateMany({
-                filter: { id: run.id },
-                values: {
-                    tool: null,
-                    modelService: claimed.model?.modelService ?? null,
-                    model: claimed.model?.model ?? null,
-                    effort: claimed.model?.effort ?? null,
-                },
-            });
-            unit.emit({ type: 'run.changed', runId: run.id, status: 'dispatched' });
-            return {
-                ...claimed,
-                run: {
-                    ...claimed.run,
-                    tool: null,
-                    modelService: claimed.model?.modelService ?? null,
-                    model: claimed.model?.model ?? null,
-                    effort: claimed.model?.effort ?? null,
-                },
-            };
-        });
-    }
-    async function assembleServer({ conn }, run, agent, holder, inputs, leaseExpiresAt, prepared) {
-        const binding = deps.subjects.get(run.subjectKind);
-        if (!binding)
-            throw new Error(`No context provider is registered for subjects of kind "${run.subjectKind}".`);
-        const view = toRun(run);
-        const claim = {
-            run: view,
-            agent,
-            runner: null,
-            inputs,
-            cli: deps.cli.name,
-            appName: deps.app.name,
-            dialect: 'tools',
-        };
-        const assembly = await binding.context.assemble(conn, claim);
-        if (assembly.dirs.length > 0)
-            throw new Error('An online agent has no working directory, and this work needs one.');
-        const skills = await deps.skills.forRun(conn, skillTargets(agent, assembly), run.id);
-        const own = new Set(skills.map((skill) => skill.slug));
-        const rendered = briefOf(agent, await withSections(conn, deps.sections, claim, assembly, prepared), [], deps.cli.name, deps.app.name);
-        // The skills an online run reads through its tools, and the agents it may consult, whatever system layer its
-        // subject gives it.
-        const consultable = (await deps.consultations?.targets(conn, run, agent)) ?? [];
-        const depth = run.parentRunId
-            ? ((await deps.consultations?.chain(conn, run))?.length ?? 1) - 1
-            : 0;
-        const section = [
-            ...onlineSkillsSection([
-                ...skills,
-                ...(deps.onlineSkills?.() ?? []).filter((skill) => !own.has(skill.slug)),
-            ]),
-            ...(consultable.length > 0 ? ['', ...consultSection(consultable)] : []),
-        ];
-        const layers = section.length > 0
-            ? {
-                ...rendered.layers,
-                system: [rendered.layers.system, '', ...section].join('\n'),
-            }
-            : rendered.layers;
-        const brief = { ...rendered, layers, prompt: joinBrief(layers) };
-        const token = await mintRunToken(conn, deps, run, holder.id);
-        deps.secrets?.remember(runSecretsKey(run.id), [token.value]);
-        const last = await eventsRepo(conn).findOne({
-            filter: { runId: run.id },
-            sort: (sort) => sort.field('seq').desc(),
-        });
-        await saveBrief(conn, () => deps.ids.next(), {
-            runId: run.id,
-            attempt: Number(run.attempt),
-            layers: brief.layers,
-            turn: brief.turn,
-            prompt: brief.prompt,
-            createdAt: clock.now().toISOString(),
-        });
-        return {
-            runId: run.id,
-            attempt: Number(run.attempt),
-            agent,
-            run: view,
-            model: onlineEntryOf(agent, assembly.model, (await deps.defaultModel?.(conn)) ?? null),
-            system: brief.prompt,
-            turn: brief.turn,
-            inputs,
-            token: token.value,
-            skills,
-            leaseExpiresAt,
-            firstSeq: (last ? Number(last.seq) : 0) + 1,
-            consultable,
-            depth,
-        };
-    }
     async function claimOne(runner, seen, reported) {
+        if (runner.draining)
+            return null;
         const conn = tx.read();
-        const candidates = await candidatesOf('runner');
+        const queued = await candidates();
         const agents = new Map();
-        for (const candidate of candidates) {
+        for (const candidate of queued) {
             if (seen.has(candidate.id))
                 continue;
             seen.add(candidate.id);
             if (!agents.has(candidate.agentId))
                 agents.set(candidate.agentId, await findAgent(conn, candidate.agentId));
             const agent = agents.get(candidate.agentId);
-            if (!agent || !fits(runner, agent, candidate))
+            if (!agent ||
+                (!deps.subjects.get(candidate.subjectKind)?.actsAs &&
+                    !fits(runner, agent, candidate)))
                 continue;
             // None of its tools has room on the runner's side: the runs behind it may still fit.
             if (!pickOpenEntry(runner, agent, (tool) => reported.has(tool)))
@@ -651,8 +958,19 @@ export function createClaimService(deps) {
         return null;
     }
     return {
+        diagnose: (conn, run, agent) => selectionFacts(conn, run, agent, false),
+        async selectionWait(runId) {
+            const conn = tx.read();
+            const run = await findRunRecord(conn, runId);
+            if (!run || run.status !== 'queued')
+                return null;
+            const agent = await findAgent(conn, run.agentId);
+            return agent ? selectionFacts(conn, toRun(run), agent, false) : null;
+        },
         async claim(runner, free, tools) {
-            if (runner.status !== 'online')
+            if (runner.status !== 'online' || runnerLowOnDisk(runner))
+                return [];
+            if ((await deps.slotsUsed(tx.read(), runner.id)) >= runner.slots)
                 return [];
             const payloads = [];
             const seen = new Set();
@@ -667,64 +985,6 @@ export function createClaimService(deps) {
             }
             return payloads;
         },
-        async claimServer(holder, limit) {
-            const claimed = [];
-            const conn = tx.read();
-            const agents = new Map();
-            for (const candidate of await candidatesOf('online')) {
-                if (claimed.length >= limit)
-                    break;
-                if (!agents.has(candidate.agentId))
-                    agents.set(candidate.agentId, await findAgent(conn, candidate.agentId));
-                const agent = agents.get(candidate.agentId);
-                if (!agent || agent.archivedAt || agent.type !== 'online')
-                    continue;
-                try {
-                    const taken = await attemptServer(holder, agent, candidate);
-                    if (taken)
-                        claimed.push(taken);
-                }
-                catch (error) {
-                    if (!(error instanceof AssemblyError))
-                        throw error;
-                    await recordFailure(candidate.id, error);
-                }
-            }
-            return claimed;
-        },
-        async claimChild(holder, runId) {
-            const conn = tx.read();
-            const candidate = await findRunRecord(conn, runId);
-            if (!candidate?.parentRunId || candidate.status !== 'queued')
-                throw notFound('Run');
-            const parent = await findRunRecord(conn, candidate.parentRunId);
-            if (parent?.runnerId !== holder.id)
-                throw notFound('Run');
-            const agent = await findAgent(conn, candidate.agentId);
-            if (!agent || agent.archivedAt || agent.type !== 'online')
-                throw notFound('Agent');
-            try {
-                const taken = await attemptServer(holder, agent, candidate);
-                if (!taken)
-                    throw notFound('Run');
-                return taken;
-            }
-            catch (error) {
-                if (!(error instanceof AssemblyError))
-                    throw error;
-                // One attempt: a consultation that cannot be assembled fails at once.
-                await tx.run(async (unit) => {
-                    const run = await findRunRecord(unit.conn, runId);
-                    if (run)
-                        await finishRun(unit, deps, run, {
-                            status: 'failed',
-                            reason: 'setupFailed',
-                            detail: error.message,
-                        });
-                });
-                throw error;
-            }
-        },
         async runSkills(runner, runId) {
             const conn = tx.read();
             const run = await findRunRecord(conn, runId);
@@ -741,8 +1001,7 @@ export function createClaimService(deps) {
                 inputs: [],
                 cli: deps.cli.name,
                 appName: deps.app.name,
-                dialect: dialectOf(agent),
-            });
+            }, await binding.context.prepare?.(toRun(run)));
             return deps.skills.forRun(conn, skillTargets(agent, assembly), run.id);
         },
     };