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

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

@@ -0,0 +1,1009 @@
+/**
+ * Claiming: handing queued runs to a runner that fits them, within each agent's concurrency limit, one run per
+ * (agent, subject, thread) at a time, through the runners' one long-poll (`routes/runners/runner.ts`), which hands
+ * out jobs from the same slots. A runner fits a run when it has the agent's
+ * tool enabled (on the web), installed and signed in, the agent names no runner or names it, it is shared with the
+ * 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. 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
+ * said it can still take of that tool across every application (`ClaimRequest.tools`). The run takes the first of its
+ * 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
+ * assembled in the same transaction; if assembly fails the transaction rolls back, the run stays queued, and the
+ * failure is counted (`claimFailures`) until the run fails `setupFailed`.
+ *
+ * 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).
+
+ */
+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 { 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 { 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 { 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;
+class AssemblyError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'AssemblyError';
+    }
+}
+/** The run does not fit this runner after all (its payload needs another runner, or a busy directory). */
+class NotForThisRunner extends Error {
+    constructor() {
+        super('The run does not fit this runner.');
+        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 {
+        has: (tool) => (left.get(tool) ?? Number.POSITIVE_INFINITY) > 0,
+        take: (tool) => {
+            const count = left.get(tool);
+            if (count !== undefined)
+                left.set(tool, count - 1);
+        },
+    };
+}
+/**
+ * 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 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 (agent.modelEntries.find((entry) => runsEntry(runner, entry) && open(entry.tool)) ?? null);
+}
+/** 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;
+}
+/**
+ * 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 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, requires))
+        return false;
+    if (!hasTool(runner, agent))
+        return false;
+    if (!policyAllowsAgent(runner.policy, agent))
+        return false;
+    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, workspaceKey = false) {
+    return [
+        ...(workspaceKey ? ['workspaceKey'] : []),
+        ...(dirs.some((dir) => dir.kind === 'repo') ? ['checkout'] : []),
+        ...(dirs.some((dir) => dir.kind === 'directory')
+            ? ['directories']
+            : []),
+        ...(skills > 0 ? ['skills'] : []),
+        ...(variables > 0 ? ['secrets'] : []),
+    ];
+}
+/** The working directories as a runner receives them: without what only the server uses. */
+export function payloadDirs(dirs) {
+    return dirs.map((dir) => {
+        const { scopeId: _scope, runnerId: _runner, ...rest } = dir;
+        return rest;
+    });
+}
+/** Where a run's variables come from, in merge order: the subject's scopes, its directories', the agent's. */
+export function variableTargets(agent, assembly) {
+    return [
+        ...assembly.scopes,
+        ...assembly.dirs.flatMap((dir) => dir.scopeId ? [{ scope: 'workdir', scopeId: dir.scopeId }] : []),
+        { scope: 'agent', scopeId: agent.id },
+    ];
+}
+/** Where a run's skills come from, the agent's first so its own win a shared slug. */
+export function skillTargets(agent, assembly) {
+    return [
+        { scope: 'agent', scopeId: agent.id },
+        ...assembly.scopes,
+        ...assembly.dirs.flatMap((dir) => dir.scopeId ? [{ scope: 'workdir', scopeId: dir.scopeId }] : []),
+    ];
+}
+function fingerprint(agent, entry, layers, skills) {
+    return createHash('sha256')
+        .update(JSON.stringify([
+        entry.tool,
+        entry.model,
+        agent.instructions,
+        layers.system,
+        layers.agent,
+        skills.map((skill) => [skill.slug, skill.hash]),
+    ]))
+        .digest('hex');
+}
+/** The brief for `assembly`, with the skills a run would get. */
+export function briefOf(agent, assembly, skills, cli, appName) {
+    const rendered = renderBrief({
+        agentName: agent.name,
+        subject: { noun: assembly.subject.noun, key: assembly.subject.key },
+        task: assembly.task,
+        context: assembly.context,
+        instructions: agent.instructions,
+        dirs: payloadDirs(assembly.dirs),
+        skills,
+        cli,
+        appName,
+        ...(assembly.guidance ? { guidance: assembly.guidance } : {}),
+    });
+    const layers = assembly.system === undefined
+        ? rendered
+        : { ...rendered, system: assembly.system };
+    const turn = assembly.turn.previousSummary
+        ? `${assembly.turn.prompt}\n\nWhat earlier runs on this already did:\n\n${assembly.turn.previousSummary}`
+        : 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) {
+    const paths = dirs
+        .filter((dir) => dir.kind === 'directory')
+        .map((dir) => `${runnerId}:${dir.path}`);
+    return paths.length > 0 ? paths.join(DIRECTORY_KEY_SEPARATOR) : null;
+}
+/** Whether another run held by the runner works in any of `key`'s directories. */
+async function directoryBusy(conn, runnerId, runId, key) {
+    const wanted = new Set(key.split(DIRECTORY_KEY_SEPARATOR));
+    const held = await runsRepo(conn).findMany({
+        filter: (f) => f.and([
+            f.string('runnerId').eq(runnerId),
+            f.string('id').ne(runId),
+            f.or(ACTIVE.map((status) => f.string('status').eq(status))),
+        ]),
+    });
+    return held.some((run) => (run.directoryKey ?? '')
+        .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)
+            throw new Error(`No context provider is registered for subjects of kind "${run.subjectKind}".`);
+        const view = toRun(run);
+        const claim = {
+            run: view,
+            agent,
+            runner,
+            inputs,
+            cli: deps.cli.name,
+            appName: deps.app.name,
+        };
+        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) ||
+            assembly.dirs.some((dir) => dir.kind === 'repo' && !policyAllowsRepo(runner.policy, dir.url)))
+            throw new NotForThisRunner();
+        // A directory on another runner: that runner takes the run.
+        if (assembly.dirs.some((dir) => dir.kind === 'directory' && dir.runnerId !== runner.id))
+            throw new NotForThisRunner();
+        const dirs = payloadDirs(assembly.dirs);
+        const directoryKey = directoryKeyOf(runner.id, dirs);
+        if (directoryKey !== null &&
+            (await directoryBusy(conn, runner.id, run.id, directoryKey)))
+            throw new NotForThisRunner();
+        const skills = await deps.skills.forRun(conn, skillTargets(agent, assembly), run.id);
+        const variables = variableTargets(agent, assembly);
+        const names = await deps.variables.namesOf(conn, variables);
+        const requires = cleanList([
+            ...view.requires,
+            ...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({
+            filter: {
+                agentId: run.agentId,
+                runnerId: runner.id,
+                subjectKind: run.subjectKind,
+                subjectId: run.subjectId,
+                threadScope: run.threadScope,
+            },
+        });
+        const token = await mintRunToken(conn, deps, run, runner.id);
+        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),
+            token.value,
+            ...(git?.credentials ?? []).map((credential) => credential.password),
+        ]);
+        const last = await eventsRepo(conn).findOne({
+            filter: { runId: run.id },
+            sort: (sort) => sort.field('seq').desc(),
+        });
+        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 = !run.freshSession &&
+            !clean &&
+            session &&
+            !session.poisoned &&
+            session.fingerprint === briefFingerprint;
+        // Mounts only for a runner that places them; their hashes stay out of the fingerprint, and a resumed session
+        // hears what changed in them in its turn instead.
+        const { mounts, resumeNotes } = runner.features.includes('mounts')
+            ? await mountsFor(conn, deps.mounts, {
+                claim: effectiveClaim,
+                assembly,
+                session: resume ? 'resume' : 'fresh',
+                sessionKey: sessionKeyOf(view),
+            }, prepared)
+            : { mounts: [], resumeNotes: [] };
+        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),
+            layers: brief.layers,
+            turn,
+            prompt: brief.prompt,
+            createdAt: nowText,
+        });
+        const payload = {
+            run: {
+                id: run.id,
+                attempt: Number(run.attempt),
+                maxAttempts: Number(run.maxAttempts),
+                priority: Number(run.priority),
+                createdAt: run.createdAt,
+                leaseExpiresAt,
+                requires,
+                firstSeq: (last ? Number(last.seq) : 0) + 1,
+                acceptedFailures: Object.keys(ANNOUNCED_FAILURES),
+            },
+            app: deps.app,
+            subject: {
+                key: assembly.subject.key,
+                ...(assembly.subject.title ? { title: assembly.subject.title } : {}),
+                url: assembly.subject.url,
+            },
+            tool: {
+                kind: entry.tool,
+                ...(entry.model ? { model: entry.model } : {}),
+                ...(entry.effort ? { effort: entry.effort } : {}),
+                policy: toolPolicyFor(agent.toolPolicy),
+            },
+            prompt: {
+                system: brief.prompt,
+                turn,
+                session: resume ? 'resume' : 'fresh',
+                ...(resume ? { resumeSessionId: session.sessionId } : {}),
+            },
+            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,
+            ...(mounts.length > 0 ? { mounts } : {}),
+            cli: {
+                name: deps.cli.name,
+                package: await cliPackageFor(deps.cli.name, deps.cli.package, deps.dist, runner),
+                credential: {
+                    file: deps.cli.credentialFile,
+                    content: {
+                        token: token.value,
+                        runId: run.id,
+                        manifestUrl: deps.manifestUrl,
+                        expiresAt: token.expiresAt,
+                    },
+                },
+            },
+            agent: { id: agent.id, name: agent.name },
+        };
+        return {
+            payload,
+            fingerprint: briefFingerprint,
+            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) {
+        // 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 (!current)
+                return { kind: 'skipped' };
+            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 {
+                prepared.set('subject', await subjectContext.prepare(toRun(candidate)));
+            }
+            catch (error) {
+                deps.onClaimFailure?.(candidate.id, error);
+            }
+        }
+        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;
+            });
+        }
+        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) {
+        deps.onClaimFailure?.(runId, error.cause);
+        await tx.run(async (unit) => {
+            const run = await findRunRecord(unit.conn, runId);
+            if (!run || run.status !== 'queued')
+                return;
+            const failures = Number(run.claimFailures) + 1;
+            if (failures >= MAX_CLAIM_FAILURES) {
+                await finishRun(unit, deps, run, {
+                    status: 'failed',
+                    reason: 'setupFailed',
+                    detail: error.message,
+                });
+                return;
+            }
+            await runsRepo(unit.conn).updateMany({
+                filter: { id: runId },
+                values: {
+                    claimFailures: failures,
+                    failureDetail: error.message.slice(0, 10_000),
+                },
+            });
+        });
+    }
+    /** 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.or([
+                    f.date('availableAt').empty(),
+                    f.date('availableAt').notAfter(now),
+                ]),
+            ]),
+            sort: (sort) => [
+                sort.field('priority').asc(),
+                sort.field('createdAt').asc(),
+                sort.field('id').asc(),
+            ],
+            limit: CANDIDATES,
+        });
+    }
+    async function claimOne(runner, seen, reported) {
+        if (runner.draining)
+            return null;
+        const conn = tx.read();
+        const queued = await candidates();
+        const agents = new Map();
+        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 ||
+                (!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)))
+                continue;
+            try {
+                const result = await attempt(runner, agent, candidate, reported);
+                if (result.kind === 'claimed')
+                    return result.payload;
+            }
+            catch (error) {
+                // Rolled back: the run stays queued for a runner it fits.
+                if (error instanceof NotForThisRunner)
+                    continue;
+                if (!(error instanceof AssemblyError))
+                    throw error;
+                await recordFailure(candidate.id, error);
+            }
+        }
+        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' || runnerLowOnDisk(runner))
+                return [];
+            if ((await deps.slotsUsed(tx.read(), runner.id)) >= runner.slots)
+                return [];
+            const payloads = [];
+            const seen = new Set();
+            const limit = Math.min(free, runner.slots);
+            const reported = toolRoom(tools);
+            while (payloads.length < limit) {
+                const payload = await claimOne(runner, seen, reported);
+                if (!payload)
+                    break;
+                payloads.push(payload);
+                reported.take(payload.tool.kind);
+            }
+            return payloads;
+        },
+        async runSkills(runner, runId) {
+            const conn = tx.read();
+            const run = await findRunRecord(conn, runId);
+            if (!run)
+                throw notFound('Run');
+            const agent = await findAgent(conn, run.agentId);
+            const binding = deps.subjects.get(run.subjectKind);
+            if (!agent || !binding)
+                return [];
+            const assembly = await binding.context.assemble(conn, {
+                run: toRun(run),
+                agent,
+                runner,
+                inputs: [],
+                cli: deps.cli.name,
+                appName: deps.app.name,
+            }, await binding.context.prepare?.(toRun(run)));
+            return deps.skills.forRun(conn, skillTargets(agent, assembly), run.id);
+        },
+    };
+}
+//# sourceMappingURL=claim.js.map