@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/tenant/agent-manifests.js

@@ -0,0 +1,359 @@
+/**
+ * Agent manifests (protocol 16, track T2): `/v1/agent-manifests/{name}`, named and versioned
+ * documents with what runs inside an agent's loop (`harness`) and what the Runtime provides
+ * around it (`runtime`). They replace agent definitions (`PUT /v1/agents/:id` before protocol
+ * 16) and environment manifests.
+ *
+ * - **Versions.** A save whose manifest hashes the same as the latest answers it unchanged; any
+ *   other writes the next version. A version is never changed or deleted alone.
+ * - **Tracking Agents move.** Saving a version moves every Agent that tracks the manifest to it
+ *   (track T3, `moveAgent`), in the save's transaction: at once, at its pod's next start, or once
+ *   its required secrets are set. A pinned Agent stays, and so does one the version cannot move
+ *   (a fixed field) or whose start failed on it. The plan counts both.
+ * - **Both sections at once.** The Runtime sees both sections, so it checks them against each
+ *   other (`sectionGaps`): every gap is named in one `422 manifest_inconsistent`, which is what
+ *   `requires` checked when a session opened before protocol 16. Each section's own checks run
+ *   too: the harness's (no code tools, no approvals, HTTP tool timeouts, the skill files) and the
+ *   runtime's (the Tenant's limits, its files).
+ * - **Plan and drift.** `?dryRun=true` answers what a save would do and saves nothing: the
+ *   changes from the latest by section, every reason the Runtime would refuse it, warnings, the
+ *   Agents it moves and how many stay on older versions. `If-Match: <version>` refuses
+ *   (`412 manifest_changed`) a save whose latest version moved since the client read it; `0` asks
+ *   for a manifest that does not exist yet.
+ * - **Every client is equal** (Q12): a version records who saved it (`savedBy`).
+ */
+import { definitionFilesOf, } from "@nylorun/core/contracts";
+import { hashManifest } from "@nylorun/core/compatibility";
+import { approvalRefusal, codeToolRefusal, harnessIdOf, loopManifestOf, runtimeOf, sectionGaps, } from "@nylorun/core/define";
+import { canonical } from "../store/canonical.js";
+import { resolveRecipe } from "../sandbox/resolve.js";
+import { declaredSandboxes } from "../sandbox/share.js";
+import { httpToolTimeoutIssues } from "../gates/http-tool.js";
+import { limitIssues, limitsInForce, manifestShapeIssues, readTenantLimits } from "./limits.js";
+import { triggerIssues } from "./triggers.js";
+import { readRuntimeLimits } from "./runtime-limits.js";
+import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
+import { actorOf, fileErrors } from "./agents.js";
+import { moveAgent, planMove } from "./agent-versions.js";
+import { definitionFileIssues } from "./definition-files.js";
+import { fail } from "./http.js";
+/** What a manifest's runtime section asks of an Agent's recipe, with the harness its loop names. */
+export function manifestRecipeRequest(manifest) {
+    const runtime = runtimeOf(manifest);
+    return {
+        ...(runtime.image === undefined ? {} : { image: runtime.image }),
+        ...(runtime.resources === undefined ? {} : { resources: runtime.resources }),
+        ...(runtime.storage === undefined ? {} : { storage: runtime.storage }),
+        ...(runtime.network === undefined ? {} : { network: runtime.network }),
+        harness: harnessIdOf(manifest.harness),
+        ...(runtime.lifecycle === undefined ? {} : { lifecycle: runtime.lifecycle }),
+        ...(runtime.setup === undefined ? {} : { setup: runtime.setup }),
+        ...(runtime.files === undefined ? {} : { files: runtime.files }),
+        ...(runtime.limits === undefined ? {} : { limits: runtime.limits }),
+        ...(runtime.secrets === undefined ? {} : { secrets: runtime.secrets }),
+    };
+}
+/** The hash a manifest's version records: equal manifests hash the same. */
+export function agentManifestHash(manifest) {
+    return hashManifest(manifest);
+}
+/** The owner a version's definition files are recorded under, for the sweep. */
+export function manifestFileOwner(name) {
+    return `agent-manifest:${name}`;
+}
+const notFound = (name, version) => fail(404, version === undefined ? `No agent manifest is named ${name}.` : `Agent manifest ${name} has no version ${version}.`, {
+    code: "manifest_not_found",
+});
+function viewOf(row, counts) {
+    return {
+        name: row.name,
+        version: row.version,
+        hash: row.hash,
+        manifest: row.body,
+        savedBy: row.savedBy,
+        createdAt: row.createdAt,
+        agents: counts.get(row.version) ?? 0,
+    };
+}
+/** Each field that differs between `before` and `after`, by path; arrays compare whole. */
+export function manifestChanges(before, after, path = "") {
+    const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+    if (object(before) && object(after)) {
+        const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
+        return keys.flatMap((key) => manifestChanges(before[key], after[key], path ? `${path}.${key}` : key));
+    }
+    if (canonical(before) === canonical(after))
+        return [];
+    return [
+        {
+            path,
+            ...(before === undefined ? {} : { from: before }),
+            ...(after === undefined ? {} : { to: after }),
+        },
+    ];
+}
+/**
+ * The changes from `before` to `after` by section: `manifest` for the top-level fields, else
+ * `harness` or `runtime` with the path inside it. A section added or removed whole is one change.
+ */
+export function sectionChanges(before, after) {
+    const op = (from, to) => from === undefined ? "add" : to === undefined ? "remove" : "replace";
+    const changes = [];
+    const { harness: beforeHarness, runtime: beforeRuntime, ...beforeTop } = before ?? {};
+    const { harness, runtime, ...top } = after;
+    for (const change of manifestChanges(beforeTop, top))
+        changes.push({ section: "manifest", ...change, op: op(change.from, change.to) });
+    for (const [section, from, to] of [
+        ["harness", beforeHarness, harness],
+        ["runtime", beforeRuntime, runtime],
+    ]) {
+        if (from === undefined || to === undefined) {
+            if (from !== to)
+                changes.push({
+                    section,
+                    path: "",
+                    op: op(from, to),
+                    ...(from === undefined ? {} : { from }),
+                    ...(to === undefined ? {} : { to }),
+                });
+            continue;
+        }
+        for (const change of manifestChanges(from, to))
+            changes.push({ section, ...change, op: op(change.from, change.to) });
+    }
+    return changes;
+}
+/**
+ * Each live Agent of manifest `name` on another version than `to`, and whether a save of `to`
+ * moves it: it tracks the manifest, is not moving to `to` already, and `to` did not fail to start on it.
+ */
+async function agentsBehind(t, name, to) {
+    return (await t.listEnvironments())
+        .filter((agent) => agent.manifestName === name && agent.pod?.desired !== "deleted" && agent.manifestVersion !== to)
+        .map((agent) => ({
+        agent,
+        moves: agent.manifestRef === "tracking" && agent.targetVersion !== to && agent.failedVersion !== to,
+    }));
+}
+/**
+ * Plans (or with `apply`, makes) the move of each Agent that tracks manifest `version.name` to
+ * `version` (track T3): each under its row lock, in the save's transaction.
+ */
+async function moveTracking(t, version, apply) {
+    const moves = { now: 0, nextStart: 0, secrets: 0, behind: 0 };
+    const now = new Date().toISOString();
+    for (const { agent: listed, moves: tracks } of await agentsBehind(t, version.name, version.version)) {
+        const agent = tracks && apply ? await t.environment(listed.id, { lock: true }) : listed;
+        if (!agent || !tracks) {
+            if (agent && agent.targetVersion !== version.version)
+                moves.behind++;
+            continue;
+        }
+        const move = await planMove(t, agent, version, "tracking");
+        if (move.plan.applies === "refused") {
+            moves.behind++;
+            continue;
+        }
+        const applies = apply ? await moveAgent(t, agent, move, now) : move.plan.applies;
+        if (applies === "now")
+            moves.now++;
+        else if (applies === "next_start")
+            moves.nextStart++;
+        else if (applies === "secrets")
+            moves.secrets++;
+    }
+    return moves;
+}
+/** What a save of `manifest` should tell its saver, though it would be saved. */
+function warningsOf(ctx, manifest, to, moves) {
+    const warnings = [];
+    const runtime = runtimeOf(manifest);
+    if (runtime.image !== undefined && !runtime.image.includes("@sha256:"))
+        warnings.push({
+            code: "image_tag",
+            message: `runtime.image ${runtime.image} is a tag, not a digest: each Agent pins what its first pod pulls, so two Tenants may run different bytes.`,
+        });
+    if (runtime.kind === "pod" && !ctx.pods)
+        warnings.push({
+            code: "pods_unavailable",
+            message: "runtime.kind pod needs sandbox pods, which this Tenant does not have: an Agent made from it is refused until `nylorun local sandbox enable`.",
+        });
+    if (moves === undefined)
+        return warnings;
+    const moved = moves.now + moves.nextStart + moves.secrets;
+    if (moved > 0) {
+        const parts = [
+            ...(moves.now > 0 ? [`${moves.now} at once`] : []),
+            ...(moves.nextStart > 0 ? [`${moves.nextStart} at their pod's next start`] : []),
+            ...(moves.secrets > 0 ? [`${moves.secrets} once their required secrets are set`] : []),
+        ];
+        warnings.push({
+            code: "agents_move",
+            message: `${moved} Agent${moved === 1 ? " tracks" : "s track"} ${manifest.name} and move${moved === 1 ? "s" : ""} to version ${to}: ${parts.join(", ")}.`,
+        });
+    }
+    if (moves.behind > 0)
+        warnings.push({
+            code: "agents_behind",
+            message: `${moves.behind} Agent${moves.behind === 1 ? " stays" : "s stay"} on an older version of ${manifest.name}: pinned, or ${moves.behind === 1 ? "it" : "they"} cannot move to version ${to} (move or fork ${moves.behind === 1 ? "it" : "them"}).`,
+        });
+    return warnings;
+}
+/**
+ * Every reason the Runtime would refuse `manifest` now, apart from the gaps between its sections:
+ * its harness section's own checks and its runtime section's (the Tenant's limits, its files).
+ */
+async function errorsOf(t, manifest) {
+    const loop = loopManifestOf(manifest);
+    const errors = [];
+    // The Runtime runs agents from their manifests alone (track R2): no tool may need it.
+    const code = codeToolRefusal(loop);
+    if (code)
+        errors.push(code);
+    // Tool approvals are the Tenant's tool policy, decided at the Tool Gate (R5 step 2).
+    const approval = approvalRefusal(loop);
+    if (approval)
+        errors.push(approval);
+    const declared = declaredSandboxes(loop);
+    if (declared.length > 0)
+        errors.push(`${declared.join(", ")} declares a sandbox: what an agent runs on is the manifest's runtime section.`);
+    const runtimeLimits = await readRuntimeLimits(t);
+    errors.push(...httpToolTimeoutIssues(loop, runtimeLimits.httpToolTimeoutMs));
+    const runtime = runtimeOf(manifest);
+    const config = effectiveSandboxConfig(await readSandboxConfig(t));
+    const resolved = resolveRecipe(runtime.kind, manifestRecipeRequest(manifest), config);
+    const tenantLimits = await readTenantLimits(t);
+    errors.push(...(resolved.kind === "error" ? resolved.errors : []), ...limitIssues(runtime.limits, tenantLimits), ...manifestShapeIssues({ ...runtime, ...(manifest.description === undefined ? {} : { description: manifest.description }) }, runtimeLimits), ...(await fileErrors(t, runtime.files)), ...triggerIssues(runtime.triggers, runtimeLimits));
+    // A skill's files count against the manifest's own skill limit, never above the Tenant's.
+    const limitBytes = limitsInForce(tenantLimits, runtime.limits).skills.totalBytes;
+    const { missing, oversized } = await definitionFileIssues(t, loop, limitBytes);
+    if (missing.length > 0)
+        errors.push(`The manifest names ${missing.length} file(s) the Runtime does not hold; upload each with PUT /v1/files/<sha256> first: ${missing.join(", ")}`);
+    if (oversized.length > 0)
+        errors.push(`A skill's files may hold at most ${limitBytes} bytes together: ${oversized.map((skill) => `'${skill.name}' holds ${skill.bytes}`).join(", ")}`);
+    return { errors, missing, oversized, limitBytes };
+}
+export async function saveAgentManifest(ctx, name, body, scope, options = {}) {
+    const { requestId: _, ...manifest } = body;
+    if (manifest.name !== name)
+        fail(400, `The manifest is named ${manifest.name}, and the path names ${name}: they must match.`);
+    const hash = agentManifestHash(manifest);
+    const gaps = sectionGaps(manifest);
+    return ctx.store.tx(async (t) => {
+        await t.lockAgentManifest(name);
+        const latest = await t.agentManifest(name);
+        if (options.ifMatch !== undefined && (latest?.version ?? 0) !== options.ifMatch)
+            fail(412, latest === undefined
+                ? `Agent manifest ${name} does not exist, and If-Match named version ${options.ifMatch}.`
+                : `Agent manifest ${name} is at version ${latest.version}, not ${options.ifMatch}: someone saved it since you read it. Read it again, or save without If-Match to replace it.`, { code: "manifest_changed", details: { latest: latest?.version ?? 0 } });
+        const unchanged = latest?.hash === hash;
+        const to = unchanged ? latest.version : (latest?.version ?? 0) + 1;
+        const counts = await t.agentsOfManifest(name);
+        const checked = await errorsOf(t, manifest);
+        // The version as it would be saved, for the plan of the Agents it moves.
+        const row = unchanged
+            ? latest
+            : { name, version: to, body: manifest, hash, savedBy: { actor: actorOf(scope) }, createdAt: new Date().toISOString() };
+        if (options.dryRun) {
+            const errors = [...gaps, ...checked.errors];
+            // A save with errors moves nothing; one that changes nothing moves no Agent either.
+            const moves = errors.length > 0 || unchanged ? undefined : await moveTracking(t, row, false);
+            return {
+                name,
+                from: latest?.version ?? null,
+                to,
+                unchanged,
+                changes: unchanged ? [] : sectionChanges(latest?.body, manifest),
+                warnings: warningsOf(ctx, manifest, to, moves),
+                errors,
+                behind: moves?.behind ?? (await agentsBehind(t, name, to)).length,
+                moves: { now: moves?.now ?? 0, nextStart: moves?.nextStart ?? 0, secrets: moves?.secrets ?? 0 },
+            };
+        }
+        if (gaps.length > 0)
+            fail(422, `Agent manifest ${name}'s harness and runtime sections do not fit: ${gaps.join("; ")}.`, {
+                code: "manifest_inconsistent",
+                details: { gaps },
+            });
+        if (checked.missing.length > 0)
+            fail(400, checked.errors.find((error) => error.startsWith("The manifest names")), {
+                code: "definition_files_missing",
+                details: { missing: checked.missing },
+            });
+        if (checked.oversized.length > 0)
+            fail(413, `This manifest allows a skill's files at most ${checked.limitBytes} bytes together: ${checked.oversized.map((skill) => `'${skill.name}' holds ${skill.bytes}`).join(", ")}`, {
+                code: "limit_exceeded",
+                details: { limitBytes: checked.limitBytes, skills: checked.oversized },
+            });
+        if (checked.errors.length > 0)
+            fail(400, checked.errors.join(" "));
+        if (unchanged)
+            return { manifest: viewOf(latest, counts), unchanged: true, warnings: warningsOf(ctx, manifest, to, undefined) };
+        await t.insertAgentManifest(row);
+        // Its files by hash, skills' and runtime files' alike, for the sweep that deletes unused ones.
+        const shas = new Set(definitionFilesOf(loopManifestOf(manifest)));
+        for (const file of runtimeOf(manifest).files ?? [])
+            if ("files" in file)
+                for (const sha of Object.values(file.files))
+                    shas.add(sha);
+        if (shas.size > 0)
+            await t.insertDefinitionFileUses(manifestFileOwner(name), hash, [...shas]);
+        // Every Agent that tracks the manifest moves to the new version (track T3).
+        const moves = await moveTracking(t, row, true);
+        return { manifest: viewOf(row, await t.agentsOfManifest(name)), unchanged: false, warnings: warningsOf(ctx, manifest, to, moves) };
+    });
+}
+/** `GET /v1/agent-manifests/{name}` (the latest) and `.../versions/{n}`. */
+export async function getAgentManifest(ctx, name, version) {
+    return ctx.store.tx(async (t) => {
+        const row = (await t.agentManifest(name, version)) ?? notFound(name, version);
+        return viewOf(row, await t.agentsOfManifest(name));
+    });
+}
+/** `GET /v1/agent-manifests`: each manifest's latest version. */
+export async function listAgentManifests(ctx) {
+    return ctx.store.tx(async (t) => {
+        const manifests = [];
+        for (const row of await t.listAgentManifests())
+            manifests.push(viewOf(row, await t.agentsOfManifest(row.name)));
+        return { manifests };
+    });
+}
+/** `GET /v1/agent-manifests/{name}/versions`: every version, newest first. */
+export async function agentManifestVersions(ctx, name) {
+    return ctx.store.tx(async (t) => {
+        const rows = await t.agentManifestVersions(name);
+        if (rows.length === 0)
+            notFound(name);
+        const counts = await t.agentsOfManifest(name);
+        return {
+            name,
+            latest: rows[0].version,
+            versions: rows.map((row) => ({
+                version: row.version,
+                hash: row.hash,
+                savedBy: row.savedBy,
+                createdAt: row.createdAt,
+                agents: counts.get(row.version) ?? 0,
+            })),
+        };
+    });
+}
+/**
+ * `DELETE /v1/agent-manifests/{name}`: deletes every version, refused while any Agent was made
+ * from one (`409 manifest_in_use`): the Agent names the version it runs.
+ */
+export async function deleteAgentManifest(ctx, name) {
+    return ctx.store.tx(async (t) => {
+        await t.lockAgentManifest(name);
+        let made = 0;
+        for (const n of (await t.agentsOfManifest(name)).values())
+            made += n;
+        if (made > 0)
+            fail(409, `${made} Agent(s) were made from agent manifest ${name}: delete them first, or keep the manifest.`, {
+                code: "manifest_in_use",
+                details: { agents: made },
+            });
+        return { name, deleted: (await t.deleteAgentManifest(name)) > 0 };
+    });
+}

package/dist/tenant/agent-versions.d.ts

@@ -0,0 +1,126 @@
+/**
+ * An Agent's versions (track T3, D73): which version of its agent manifest it runs, how it moves
+ * to another, and which version a session's turn runs.
+ *
+ * - **One version at a time.** An Agent runs one version of its manifest (`manifestVersion`),
+ *   both sections together: the loop manifest its harness section makes, and the runtime its
+ *   compute applies (`applied`). A session pins all of it (`pinOf`) when it opens.
+ * - **A move** (`moveAgent`: `PUT /v1/agents/{id}`, and a save for each Agent that tracks the
+ *   manifest) changes no data: its id, disk, vault and sessions stay. A version whose runtime a
+ *   pod applies only when it starts (`START_FIELDS`) makes the Agent outdated (`targetVersion`,
+ *   with the target's runtime in `recipe`) until its pod's next start switches it (`switchTo`);
+ *   any other applies at once. A version that adds a required secret with no value the version
+ *   can use waits for it (`resumeMove` after each secret write). Its manifest's name, kind,
+ *   harness and storage are fixed for its life (`409 agent_fixed_field`).
+ * - **The start check** (pods): a start on a new version records what ran before
+ *   (`startCheck`) until the new pod's harness joins (`passStartCheck`). A failed setup, a failed
+ *   pod or a start past the Host's `tenant.upgradeStartMs` goes back to it (`revertStart`): the
+ *   definition, not the data. The version is the Agent's `failedVersion`, which a tracking Agent
+ *   does not move to again, until a start on a new version succeeds. While a pod waits to start
+ *   on a new version, it idles at most `tenant.upgradeIdleMs` (`idleMsOf`).
+ * - **A turn takes the Agent's version.** A turn's first segment re-pins its session to the
+ *   version the Agent runs when that changed since the session's last turn (`repinTurn`), before
+ *   anything of the turn has run: no effect is journaled for it yet. The turn keeps that version
+ *   through every later segment, approval and rollover. A turn whose message named a variant,
+ *   and a flow's sessions, keep the version they pinned.
+ *
+ * Re-pinning at the first segment, not when the message is accepted, keeps a turn that waits for
+ * its compute to start on a version the Agent has at that start.
+ */
+import type { AgentMovePlan, EnvironmentRecipe } from "@nylorun/core/contracts";
+import { type SandboxManifest } from "@nylorun/core/define";
+import type { AgentManifestRow, Environment, Tx } from "../store/types.js";
+import type { TenantSandboxConfig } from "../sandbox/tenant-config.js";
+import { type Session, type TenantContext } from "./context.js";
+/** What a session pins of the version its Agent runs. */
+export interface SessionPin {
+    /** The loop manifest the version's harness section makes (`loopManifestOf`). */
+    readonly manifest: any;
+    readonly manifestHash: string;
+    readonly definition: {
+        readonly name: string;
+        readonly version: number;
+    };
+    /** The version's `harness.loop`, when it sets one. */
+    readonly loop?: Record<string, unknown>;
+    /** The harness that runs its turns: the runtime's, or ours for a flow. */
+    readonly harness: string;
+    /** The sandbox spec of the runtime the Agent's compute runs (kinds `virtual` and `pod`). */
+    readonly sandbox?: SandboxManifest;
+}
+/**
+ * The pin of the version Agent `agent` runs: its manifest version's loop manifest, and the
+ * harness and sandbox spec of the runtime its compute applies (`applied`). `409 agent_unavailable`
+ * when that version is gone.
+ */
+export declare function pinOf(t: Tx, agent: Environment): Promise<{
+    pin: SessionPin;
+    version: AgentManifestRow;
+}>;
+/** Writes `pin` onto `session` (the caller saves it). */
+export declare function applyPin(session: Session, pin: SessionPin): void;
+/**
+ * Re-pins `session` (in the segment's owned transaction) to the version its Agent runs, when its
+ * active turn is about to run its first segment and nothing of the turn has run yet: the turn
+ * then runs that version. Returns whether it changed the session (the caller saves it).
+ *
+ * Leaves the session as it is for a flow and a flow's linked session, a turn whose message named
+ * a variant, a later segment, a turn with any journaled effect, and a version whose harness is
+ * not the session's (an Agent's harness is fixed for its life, D73).
+ */
+export declare function repinTurn(t: Tx, session: Session): Promise<boolean>;
+/** What a move of `agent` to `target` would do, and the target's runtime resolved. */
+export interface Move {
+    plan: AgentMovePlan;
+    target: AgentManifestRow;
+    recipe: EnvironmentRecipe;
+}
+/**
+ * The plan of moving `agent` to version `target` of its manifest, named `tracking` after it:
+ * the target's runtime resolved against the Tenant's limits (a `400` when it no longer fits),
+ * what it changes, the fixed fields it would change, and the required secrets it would wait for.
+ */
+export declare function planMove(t: Tx, agent: Environment, target: AgentManifestRow, tracking: Environment["manifestRef"]): Promise<Move>;
+/** The `409 agent_fixed_field` of a move that would change what is fixed for an Agent's life. */
+export declare function refuseFixed(agentId: string, plan: Pick<AgentMovePlan, "refusals" | "to" | "from">): never;
+/**
+ * Moves `agent` (locked, live) per `move` (`planMove`), in the caller's transaction. A move
+ * replaces a pending one: the runtime it waited to apply is dropped first. `none` (back to what it
+ * runs) only clears the target; `now` switches; `next_start` keeps the target's runtime in
+ * `recipe` for the pod's next start (`switchTo`); `secrets` names the target and waits.
+ * Returns when it applies.
+ */
+export declare function moveAgent(t: Tx, agent: Environment, move: Move, now: string): Promise<AgentMovePlan["applies"]>;
+/**
+ * After a secret write: an Agent that waits for its secrets moves on once the target's required
+ * slots are filled (`moveAgent` again, to the same target). In the caller's transaction.
+ */
+export declare function resumeMove(t: Tx, agent: Environment, now: string): Promise<void>;
+/**
+ * At a pod Agent's start (`wantRunning`, `newVolume`): switches `agent` (locked) to the version it
+ * moves to when its runtime waits for this start. Applies the target's runtime and version, drops
+ * the pinned image digest when the image changed, and records what ran before (`startCheck`)
+ * until the new pod's harness joins. Returns whether it switched.
+ */
+export declare function switchTo(t: Tx, agent: Environment, now: string): Promise<boolean>;
+/** What an outdated Agent waits for: its secrets, or its pod's next start; `null` when it is not. */
+export declare function waitingFor(agent: Pick<Environment, "targetVersion" | "appliedVersion" | "version">): "secrets" | "start" | null;
+/** How long pod Agent `agent` may idle before it stops: shorter while a start would apply a new version. */
+export declare function idleMsOf(config: TenantSandboxConfig, agent: Environment): number;
+/**
+ * The harness of pod Agent `id` joined at host epoch `epoch` (its `hello`): a start on a new
+ * version succeeded, setup included. Clears the start check and the failed version.
+ */
+export declare function passStartCheck(ctx: TenantContext, id: string, epoch: number): Promise<void>;
+/**
+ * Pod Agent `agent` (locked) did not start on the version it switched to (`reason`): back to what
+ * it ran before (`startCheck.from`), its definition and not its data, with that version as its
+ * `failedVersion`, and its pod asked to run again. A turn waiting for the start runs on the
+ * version it went back to. Returns whether there was a start to go back from.
+ */
+export declare function revertStart(t: Tx, agent: Environment, reason: string, now: string): Promise<boolean>;
+/**
+ * The Tenant sweep: each pod Agent whose start on a new version has taken longer than the Host's
+ * `tenant.upgradeStartMs` goes back to the version it ran (`revertStart`).
+ */
+export declare function sweepStartChecks(ctx: TenantContext, now?: number): Promise<void>;