@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/tenant/agent-versions.js

@@ -0,0 +1,389 @@
+import { hashManifest } from "@nylorun/core/compatibility";
+import { loopManifestOf, runtimeOf } from "@nylorun/core/define";
+import { isWorkflowManifest } from "../core/flow-host.js";
+import { canonical } from "../store/canonical.js";
+import { resolveRecipe, sandboxSpecOf } from "../sandbox/resolve.js";
+import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
+import { HARNESS_ID } from "../sandbox/placement.js";
+import { slotHolds } from "../vault/service.js";
+import { manifestRecipeRequest, sectionChanges } from "./agent-manifests.js";
+import { podLifecycleConfig } from "../sandbox/pods/spec.js";
+import { hostTuning } from "../tuning.js";
+import { harnessOf } from "./context.js";
+import { fail } from "./http.js";
+import { limitIssues, manifestShapeIssues, readTenantLimits } from "./limits.js";
+import { readRuntimeLimits } from "./runtime-limits.js";
+import { mergeAgentTriggers } from "./triggers.js";
+/**
+ * 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 async function pinOf(t, agent) {
+    const version = (await t.agentManifest(agent.manifestName, agent.manifestVersion)) ??
+        fail(409, `Agent ${agent.id}'s manifest ${agent.manifestName}@${agent.manifestVersion} is gone.`, {
+            code: "agent_unavailable",
+        });
+    const manifest = loopManifestOf(version.body);
+    const config = await readSandboxConfig(t);
+    const loop = version.body.harness.loop;
+    const sandbox = agent.kind === "none" ? undefined : sandboxSpecOf(agent.applied, effectiveSandboxConfig(config).limits.idle);
+    return {
+        version,
+        pin: {
+            manifest,
+            manifestHash: hashManifest(manifest),
+            definition: { name: version.name, version: version.version },
+            ...(loop === undefined ? {} : { loop }),
+            harness: isWorkflowManifest(manifest) ? HARNESS_ID : agent.applied.harness,
+            ...(sandbox === undefined ? {} : { sandbox }),
+        },
+    };
+}
+/** Writes `pin` onto `session` (the caller saves it). */
+export function applyPin(session, pin) {
+    session.manifest = pin.manifest;
+    session.manifestHash = pin.manifestHash;
+    session.definition = { ...pin.definition };
+    if (pin.loop === undefined)
+        delete session.loop;
+    else
+        session.loop = pin.loop;
+    session.harness = pin.harness;
+    if (pin.sandbox === undefined)
+        delete session.sandbox;
+    else
+        session.sandbox = pin.sandbox;
+}
+/**
+ * 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 async function repinTurn(t, session) {
+    const id = session.environmentId;
+    const checkpoint = session.checkpoint;
+    if (id === undefined || session.definition === undefined || session.flowRootId !== undefined)
+        return false;
+    if (isWorkflowManifest(session.manifest) || session.activeTurnId === null)
+        return false;
+    if (!checkpoint || checkpoint.segment !== 0 || checkpoint.turnId !== session.activeTurnId)
+        return false;
+    // A variant the message named (a turn-manifest variant) is validated against the old pin.
+    if (checkpoint.manifestHash !== session.manifestHash)
+        return false;
+    const agent = await t.environment(id);
+    if (!agent)
+        return false;
+    if (session.definition.name === agent.manifestName && session.definition.version === agent.manifestVersion)
+        return false;
+    if ((await t.effectsForTurn(session.id, session.activeTurnId)).length > 0)
+        return false;
+    const { pin } = await pinOf(t, agent);
+    if (pin.harness !== harnessOf(session))
+        return false;
+    const changed = pin.manifestHash !== session.manifestHash;
+    applyPin(session, pin);
+    session.environmentVersion = agent.version;
+    session.checkpoint = { ...session.checkpoint, manifestHash: pin.manifestHash };
+    // MCP discovery is per loop manifest: the next one is the new version's.
+    if (changed) {
+        delete session.mcpSnapshot;
+        delete session.mcpDiagnostics;
+    }
+    return true;
+}
+/** The runtime fields a pod applies only when it starts: a change waits for its next start. */
+const START_FIELDS = ["image", "resources", "network", "setup", "files"];
+/** Whether pod Agent `agent` applies `recipe` only at its next start. */
+function needsStart(agent, recipe) {
+    return agent.kind === "pod" && START_FIELDS.some((field) => canonical(recipe[field]) !== canonical(agent.applied[field]));
+}
+/**
+ * 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 async function planMove(t, agent, target, tracking) {
+    const runtime = runtimeOf(target.body);
+    const recipe = target.version === agent.manifestVersion ? agent.applied : await resolvedRuntime(t, target);
+    const refusals = [];
+    const fixed = (field, from, to) => {
+        if (canonical(from) !== canonical(to))
+            refusals.push({ field, ...(from === undefined ? {} : { from }), ...(to === undefined ? {} : { to }) });
+    };
+    fixed("kind", agent.kind, runtime.kind);
+    fixed("harness", agent.applied.harness, recipe.harness);
+    fixed("storage", agent.applied.storage, recipe.storage);
+    const { missing, dormant } = await secretsOf(t, agent.id, recipe.secrets);
+    const current = await t.agentManifest(agent.manifestName, agent.manifestVersion);
+    const from = agent.manifestVersion;
+    const applies = refusals.length > 0
+        ? "refused"
+        : target.version === from
+            ? "none"
+            : missing.length > 0
+                ? "secrets"
+                : needsStart(agent, recipe)
+                    ? "next_start"
+                    : "now";
+    return {
+        target,
+        recipe,
+        plan: {
+            agent: agent.id,
+            manifest: tracking === "tracking" ? target.name : `${target.name}@${target.version}`,
+            from,
+            to: target.version,
+            tracking,
+            applies,
+            changes: target.version === from ? [] : sectionChanges(current?.body, target.body),
+            missingSecrets: missing,
+            dormantSecrets: dormant,
+            refusals,
+            sessions: (await t.sessionsOnEnvironment(agent.id)).length,
+        },
+    };
+}
+/**
+ * Version `target`'s runtime resolved against the Tenant's limits now, as a create resolves it:
+ * `400` when it no longer fits them. (What an Agent runs already stays, whatever its limits.)
+ */
+async function resolvedRuntime(t, target) {
+    const runtime = runtimeOf(target.body);
+    const resolved = resolveRecipe(runtime.kind, manifestRecipeRequest(target.body), effectiveSandboxConfig(await readSandboxConfig(t)));
+    const errors = [
+        ...(resolved.kind === "error" ? resolved.errors : []),
+        ...limitIssues(runtime.limits, await readTenantLimits(t)),
+        ...manifestShapeIssues(runtime, await readRuntimeLimits(t)),
+    ];
+    if (resolved.kind === "error" || errors.length > 0)
+        return fail(400, `${target.name}@${target.version} does not fit this Tenant's limits now: ${errors.join(" ")}`);
+    return resolved.recipe;
+}
+/**
+ * Of Agent `id`'s vault and the secret slots `slots` of a version: each required slot with no
+ * value that fills it (`slotHolds`), and each secret that fills none, which stays dormant.
+ */
+async function secretsOf(t, id, slots) {
+    const vault = await t.vaultOfEnvironment(id);
+    const rows = vault ? (await t.credentialsForVault(vault.id)).filter((row) => row.type !== "model") : [];
+    if (slots === undefined)
+        return { missing: [], dormant: [] };
+    const fills = (name) => rows.some((row) => row.name === name && slotHolds(slots[name], row));
+    return {
+        missing: Object.entries(slots)
+            .filter(([name, slot]) => slot.required === true && !fills(name))
+            .map(([name]) => name)
+            .sort(),
+        dormant: rows
+            .filter((row) => slots[row.name] === undefined || !slotHolds(slots[row.name], row))
+            .map((row) => row.name)
+            .sort(),
+    };
+}
+/** The `409 agent_fixed_field` of a move that would change what is fixed for an Agent's life. */
+export function refuseFixed(agentId, plan) {
+    return fail(409, `Agent ${agentId}'s ${plan.refusals.map((refusal) => refusal.field).join(", ")} ${plan.refusals.length === 1 ? "is" : "are"} fixed for its life, and version ${plan.to} changes ${plan.refusals.length === 1 ? "it" : "them"}: fork it into a new Agent with POST /v1/agents/${encodeURIComponent(agentId)}/fork.`, { code: "agent_fixed_field", details: { fields: plan.refusals, from: plan.from, to: plan.to } });
+}
+/**
+ * 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 async function moveAgent(t, agent, move, now) {
+    const { plan, target, recipe } = move;
+    if (plan.applies === "refused")
+        refuseFixed(agent.id, plan);
+    // Asked again while it waits for secrets: nothing new.
+    if (plan.applies === "secrets" && agent.targetVersion === plan.to && agent.appliedVersion === agent.version) {
+        if (agent.manifestRef !== plan.tracking)
+            await t.updateEnvironment(agent.id, { manifestRef: plan.tracking }, now);
+        return plan.applies;
+    }
+    const pending = agent.appliedVersion !== agent.version;
+    // What it runs, with no pending runtime: the base every move starts from.
+    const version = pending ? agent.version + 1 : agent.version;
+    const base = pending ? { recipe: agent.applied, version, appliedVersion: version } : {};
+    const ref = { manifestRef: plan.tracking };
+    switch (plan.applies) {
+        case "none":
+            await t.updateEnvironment(agent.id, { ...base, ...ref, targetVersion: null }, now);
+            break;
+        case "secrets":
+            await t.updateEnvironment(agent.id, { ...base, ...ref, targetVersion: plan.to }, now);
+            await t.agentEvent(agent.id, "agent.outdated", { from: plan.from, to: plan.to, waitingFor: "secrets" });
+            break;
+        case "next_start":
+            // `applied` stays what runs: `recipe` differs from it until the start applies it.
+            await t.updateEnvironment(agent.id, { ...ref, recipe, version: agent.version + 1, targetVersion: plan.to }, now);
+            await t.agentEvent(agent.id, "agent.outdated", { from: plan.from, to: plan.to, waitingFor: "start" });
+            // A running pod stops sooner once idle, so its next start applies the version.
+            if (agent.pod?.desired === "running") {
+                const idleMs = Math.min(podLifecycleConfig(await readSandboxConfig(t), recipe).idleMs, hostTuning().tenant.upgradeIdleMs);
+                const at = Math.max(Date.parse(agent.pod.lastActiveAt ?? now) + idleMs, Date.parse(now));
+                await t.signalSandbox(agent.id, { kind: "arm", timer: "idle", at });
+            }
+            break;
+        case "now":
+            await t.updateEnvironment(agent.id, {
+                ...ref,
+                recipe,
+                applied: recipe,
+                version: version + 1,
+                appliedVersion: version + 1,
+                manifestVersion: target.version,
+                manifestHash: target.hash,
+                targetVersion: null,
+                failedVersion: null,
+            }, now);
+            await t.agentEvent(agent.id, "agent.version_changed", { from: plan.from, to: plan.to });
+            await mergeAgentTriggers(t, { ...agent, manifestVersion: target.version }, agent.manifestVersion);
+            break;
+    }
+    return plan.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 async function resumeMove(t, agent, now) {
+    if (agent.targetVersion === undefined || agent.appliedVersion !== agent.version)
+        return;
+    const target = await t.agentManifest(agent.manifestName, agent.targetVersion);
+    if (!target)
+        return void (await t.updateEnvironment(agent.id, { targetVersion: null }, now));
+    const move = await planMove(t, agent, target, agent.manifestRef);
+    if (move.plan.applies === "refused")
+        return;
+    await moveAgent(t, agent, move, now);
+}
+/**
+ * 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 async function switchTo(t, agent, now) {
+    if (agent.targetVersion === undefined || agent.appliedVersion === agent.version)
+        return false;
+    const target = await t.agentManifest(agent.manifestName, agent.targetVersion);
+    if (!target)
+        return false;
+    // A start that replaces one still being checked goes back as far as that one would.
+    const from = agent.startCheck?.from ?? {
+        manifestVersion: agent.manifestVersion,
+        manifestHash: agent.manifestHash,
+        applied: agent.applied,
+        ...(agent.pod?.imageDigest === undefined ? {} : { imageDigest: agent.pod.imageDigest }),
+    };
+    await t.updateEnvironment(agent.id, {
+        applied: agent.recipe,
+        appliedVersion: agent.version,
+        manifestVersion: target.version,
+        manifestHash: target.hash,
+        targetVersion: null,
+        ...(agent.pod ? { startCheck: { from, startedAt: now } } : {}),
+    }, now);
+    if (agent.pod?.imageDigest !== undefined && canonical(agent.recipe.image) !== canonical(agent.applied.image))
+        await t.updateEnvironmentPod(agent.id, { imageDigest: null }, now);
+    await t.agentEvent(agent.id, "agent.version_changed", { from: agent.manifestVersion, to: target.version });
+    await mergeAgentTriggers(t, { ...agent, manifestVersion: target.version }, agent.manifestVersion);
+    return true;
+}
+/** What an outdated Agent waits for: its secrets, or its pod's next start; `null` when it is not. */
+export function waitingFor(agent) {
+    if (agent.targetVersion === undefined)
+        return null;
+    return agent.appliedVersion === agent.version ? "secrets" : "start";
+}
+/** How long pod Agent `agent` may idle before it stops: shorter while a start would apply a new version. */
+export function idleMsOf(config, agent) {
+    const idleMs = podLifecycleConfig(config, agent.recipe).idleMs;
+    return waitingFor(agent) === "start" ? Math.min(idleMs, hostTuning().tenant.upgradeIdleMs) : idleMs;
+}
+/**
+ * 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 async function passStartCheck(ctx, id, epoch) {
+    await ctx.store.tx(async (t) => {
+        const agent = await t.environment(id, { lock: true });
+        if (!agent?.startCheck || agent.pod?.hostEpoch !== epoch)
+            return;
+        await t.updateEnvironment(id, { startCheck: null, failedVersion: null }, new Date().toISOString());
+    });
+}
+/**
+ * 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 async function revertStart(t, agent, reason, now) {
+    const check = agent.startCheck;
+    const pod = agent.pod;
+    if (!check || !pod)
+        return false;
+    const version = agent.version + 1;
+    await t.updateEnvironment(agent.id, {
+        recipe: check.from.applied,
+        applied: check.from.applied,
+        version,
+        appliedVersion: version,
+        manifestVersion: check.from.manifestVersion,
+        manifestHash: check.from.manifestHash,
+        targetVersion: null,
+        failedVersion: agent.manifestVersion,
+        startCheck: null,
+    }, now);
+    await t.updateEnvironmentPod(agent.id, {
+        imageDigest: check.from.imageDigest ?? null,
+        desired: "running",
+        rev: pod.rev + 1,
+        observed: "creating",
+        startedAt: now,
+        lastActiveAt: now,
+        reason: null,
+    }, now);
+    await t.agentEvent(agent.id, "agent.start_failed", {
+        from: check.from.manifestVersion,
+        to: agent.manifestVersion,
+        reason,
+        reverted: true,
+    });
+    await t.agentEvent(agent.id, "agent.version_changed", { from: agent.manifestVersion, to: check.from.manifestVersion });
+    await mergeAgentTriggers(t, { ...agent, manifestVersion: check.from.manifestVersion }, agent.manifestVersion);
+    await t.signalSandbox(agent.id, { kind: "reconcile" });
+    return true;
+}
+/**
+ * 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 async function sweepStartChecks(ctx, now = Date.now()) {
+    const limit = hostTuning().tenant.upgradeStartMs;
+    const due = (agent) => agent.startCheck !== undefined && Date.parse(agent.startCheck.startedAt) + limit <= now;
+    for (const candidate of (await ctx.store.tx((t) => t.listEnvironments())).filter(due)) {
+        try {
+            await ctx.store.tx(async (t) => {
+                const agent = await t.environment(candidate.id, { lock: true });
+                if (!agent || !due(agent))
+                    return;
+                await revertStart(t, agent, `The pod did not start within ${Math.round(limit / 1000)} s`, new Date(now).toISOString());
+            });
+        }
+        catch (error) {
+            ctx.config.logger.warn("agent start check not swept", {
+                environmentId: candidate.id,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}

package/dist/tenant/agents.d.ts

@@ -0,0 +1,230 @@
+import { type AgentAttention, type AgentMovePlan, type AgentState, type EnvironmentRecipe, type AgentView, type ForkAgentRequest, type ForkAgentResponse, type PutAgentRequest, type PutAgentSecretRequest } from "@nylorun/core/contracts";
+import type { Environment, AgentEventsQuery, Tx } from "../store/types.js";
+import type { SandboxRouteDeps } from "../core/sandbox-routes.js";
+import { type AuthScope, type Session, type TenantContext } from "./context.js";
+import type { SealedSecretCopies } from "../vault/service.js";
+/** The Agent grants that limit `scope`, or undefined when it reaches every Agent. */
+export declare function agentGrantsOf(scope: AuthScope): readonly string[] | undefined;
+/** Who the vault's audit rows name for a request: the subject, else the application. */
+export declare function actorOf(scope: AuthScope): string;
+/** Refuses (the 404 of a missing one) Agent `id` when the caller's grants miss it. */
+export declare function assertReaches(scope: AuthScope, id: string): void;
+/** An Agent's row, unless it is gone or being deleted. */
+export declare function liveEnvironment(t: Tx, id: string, options?: {
+    lock?: boolean;
+}): Promise<Environment | undefined>;
+/**
+ * An Agent's state (protocol 16), from its desired state, its compute and its sessions, and
+ * every state that holds with the session behind it (`attention`), highest first. A session waits
+ * on a person while it is paused (an approval or an interaction) or uncertain, and the Agent while
+ * a move waits for its required secrets (track T3); a session's last turn
+ * failed while it is `failed`; a turn runs while it is `running`, `runnable` or `waiting`.
+ */
+export declare function stateOf(agent: Pick<Environment, "desiredState" | "pod"> & Partial<Pick<Environment, "targetVersion" | "appliedVersion" | "version" | "failedVersion">>, sessions: readonly Pick<Session, "id" | "status">[]): {
+    state: AgentState;
+    attention: AgentAttention[];
+};
+/** How an Agent names its manifest: `name` when it tracks it, `name@n` when pinned. */
+export declare function manifestRefOf(agent: Pick<Environment, "manifestName" | "manifestVersion" | "manifestRef">): string;
+/**
+ * Why input files cannot be used: each that is not a version of a Tenant-wide artifact (a
+ * session's artifacts go with the session). Pins nothing else: the version is the one named.
+ */
+export declare function fileErrors(t: Tx, files: EnvironmentRecipe["files"]): Promise<string[]>;
+/**
+ * `PUT /v1/agents/{id}`: creates the Agent and its vault (within the Tenant's limit on their
+ * number) from a saved agent manifest's version, or finds the one with this id, so "get or
+ * create" is one call. On an existing one, its labels and owner guard may change, and `manifest`
+ * moves it to the version it names (track T3, `moveAgent`): `name` tracks the latest (unless that
+ * failed to start), `name@n` pins `n`. Another manifest name is `409 agent_fixed_field`. Every
+ * `PUT` counts as the Agent's use.
+ */
+export declare function putAgent(ctx: TenantContext, id: string, body: PutAgentRequest, scope: AuthScope, options?: {
+    fork?: Fork;
+}): Promise<AgentView>;
+/**
+ * `PUT /v1/agents/{id}?dryRun=true` (track T3): what moving existing Agent `id` to the version
+ * `body.manifest` names would do (`AgentMovePlan`), with nothing changed.
+ */
+export declare function planAgentPut(ctx: TenantContext, id: string, body: PutAgentRequest, scope: AuthScope): Promise<{
+    dryRun: true;
+    plan: AgentMovePlan;
+}>;
+/**
+ * After a secret write on Agent `id`: a move that waited for its required secrets goes on once
+ * they are set (track T3). Best effort: the write stands either way.
+ */
+export declare function secretWritten(ctx: TenantContext, id: string): Promise<void>;
+/**
+ * The secret write `raw` asks of Environment `id` (D64). When what it runs declares secret
+ * slots, the name must be one (`409 secret_not_in_manifest`), and the body is `{ value }` (or
+ * `{ headers }` for a `headers` slot) with the binding from the slot; a full typed body is
+ * accepted only when its binding is the slot's. Without slots, today's typed body.
+ */
+export declare function secretRequestFor(ctx: TenantContext, id: string, name: string, raw: unknown): Promise<PutAgentSecretRequest>;
+/** What a create does for a fork (`POST .../fork`); `copied` is filled in by the create. */
+interface Fork {
+    source: string;
+    /** The manifest version the plan resolved, which the create makes the fork from. */
+    version: number;
+    setup: boolean;
+    /**
+     * The source's secrets sealed by keys for the new vault `vaultId` (F4.2), before the create's
+     * transaction, which inserts them; absent with `secrets: none`.
+     */
+    sealed?: {
+        vaultId: string;
+        copies: SealedSecretCopies;
+    };
+    copied?: {
+        copied: string[];
+        dropped: string[];
+    };
+}
+/**
+ * `POST /v1/agents/{id}/fork` (Q15): copies an Agent into a new one, which is how an Agent changes
+ * what is fixed for its life (its manifest, kind, harness or storage). A new Agent `body.id` is made from the manifest
+ * (default the source's manifest name, tracking, at its latest version), its disk started from a
+ * version of the source's (`latest` takes a snapshot first, refused during a turn), and its
+ * secrets copied inside the Runtime. A fork onto other setup runs that setup on the copied disk
+ * before its first turn (Q17). The source keeps what it runs, its disk and its sessions. With
+ * `dryRun`, the plan only.
+ */
+export declare function forkAgent(ctx: TenantContext, sourceId: string, body: ForkAgentRequest, scope: AuthScope): Promise<ForkAgentResponse>;
+/** `GET /v1/agents/{id}`. */
+export declare function getAgent(ctx: TenantContext, id: string, scope: AuthScope): Promise<AgentView>;
+/**
+ * What `GET /v1/agents` filters on: labels (all of them), the derived state, the manifest's name
+ * and whether it is outdated.
+ */
+export interface AgentFilters {
+    labels: Record<string, string>;
+    state?: string;
+    manifest?: string;
+    /** Only Agents moving to another version (track T3): waiting for their secrets or their pod's start. */
+    outdated?: boolean;
+}
+/**
+ * `GET /v1/agents?label=k=v&state=s&manifest=m`: every Agent with all the labels, in the state
+ * and made from the manifest, that the caller reaches, by id. With `page`, at most `limit` after
+ * the Agent id `after` (the cursor), and the id to continue from.
+ */
+export declare function listAgents(ctx: TenantContext, filters: AgentFilters, scope: AuthScope, page?: {
+    limit: number;
+    after?: string;
+}): Promise<{
+    agents: AgentView[];
+    next: string | null;
+}>;
+/**
+ * Asks pod Environment `id` to run when it is stopped or failed (a disk copy needs its engine),
+ * with its recipe applied, as a turn start would.
+ */
+export declare function wakePod(ctx: TenantContext, id: string): Promise<void>;
+/** Whether a disk lease (R2d step 3) holds `environment` now. */
+export declare function diskHeld(environment: Environment, now?: number): boolean;
+/** Refused while a snapshot or restore copies the disk (a pending seed does not count). */
+export declare function refuseDiskCopy(environment: Environment): void;
+/**
+ * `DELETE /v1/agents/{id}`: deletes the Environment, its vault and its workspace. Refused
+ * while a session that names it has an active turn. Sessions keep its id: their next turn is
+ * refused (`agent_unavailable`) unless an Environment with this id exists again.
+ */
+export declare function deleteAgent(ctx: TenantContext, id: string, scope: AuthScope): Promise<{
+    id: string;
+    deleted: boolean;
+}>;
+/**
+ * Deletes every Environment unused for its `lifecycle.deleteAfter` (Q13): no turn, recipe
+ * change, secret write, stop or reset since. One with a turn running waits for the next sweep.
+ * Run by the Tenant sweep.
+ */
+export declare function sweepUnusedAgents(ctx: TenantContext, now?: number): Promise<void>;
+/**
+ * `POST /v1/agents/{id}/stop`: suspends a pod Environment. Its volume is kept, and the next
+ * turn of a session that names it starts it again. Refused during a turn.
+ */
+export declare function stopAgent(ctx: TenantContext, id: string, scope: AuthScope): Promise<AgentView>;
+/**
+ * `POST /v1/agents/{id}/restart` (track T3): applies a pending version now, refused during a
+ * turn. With `retry`, it first moves the Agent to the version that failed to start again. A
+ * running pod stops, so the next turn starts it on the version; a stopped or failed one is asked
+ * to run at once. Kinds `virtual` and `none` apply a version at once anyway.
+ */
+export declare function restartAgent(ctx: TenantContext, id: string, options: {
+    retry?: boolean;
+}, scope: AuthScope): Promise<AgentView>;
+/**
+ * `POST /v1/agents/{id}/reset`: a new pod on a new, empty volume (the next volume
+ * generation), with a new join token and the recipe applied; the old Sandbox and volume are
+ * deleted. Leaves `lost` and `failed`. Refused during a turn, and while an earlier reset's
+ * Sandbox is still being deleted.
+ */
+export declare function resetAgent(ctx: TenantContext, id: string, scope: AuthScope): Promise<AgentView>;
+/**
+ * Gives pod Environment `environment` (locked) a new pod on a new, empty volume, the next volume
+ * generation, with its recipe applied: the old Sandbox and volume are retired. With `seed`, the
+ * new volume starts from that disk version before any turn (R2d step 3): a restore, or the
+ * recovery of a lost volume.
+ */
+export declare function newVolume(ctx: TenantContext, t: Tx, environment: Environment, options?: {
+    seed?: {
+        artifactId: string;
+        version: number;
+    };
+    reason?: "restore" | "lost";
+}): Promise<number>;
+/** `GET /v1/agents/{id}/events`: the Environment's lifecycle stream. */
+export declare function agentEventsOf(ctx: TenantContext, id: string, scope: AuthScope, query?: AgentEventsQuery): Promise<{
+    events: {
+        schema: "nylorun.agent-event/1";
+        eventId: string;
+        tenantId: string;
+        agentId: string;
+        seq: number;
+        time: string;
+        type: "agent.attached" | "agent.created" | "agent.deleted" | "agent.detached" | "agent.egress" | "agent.failed" | "agent.forked" | "agent.lost" | "agent.memory_updated" | "agent.outdated" | "agent.relaunched" | "agent.reset" | "agent.run" | "agent.running" | "agent.start_failed" | "agent.suspended" | "agent.trigger_paused" | "agent.trigger_resumed" | "agent.trigger_secret_rotated" | "agent.version_changed";
+        payload: Record<string, unknown>;
+    }[];
+}>;
+/**
+ * Opens a new session on Environment `id` (`PutSessionRequest.environment`): it must exist, be
+ * reachable with `grants` and pass its owner guard. Runs in the session's transaction, after
+ * its session row lock; holds the Environment's row lock.
+ */
+export declare function openAgent(t: Tx, id: string, options: {
+    grants?: readonly string[];
+    ownerUserId: string;
+    opaque: boolean;
+}): Promise<Environment>;
+/** Records the attachment on the session's log and on the Environment's stream. */
+export declare function recordAttachment(t: Tx, sessionId: string, agentId: string): Promise<void>;
+/**
+ * Checks a turn start on a session that names an Environment, in the command's transaction
+ * after the session row lock: the Environment still exists, a token caller's grants reach it,
+ * its owner guard admits the session's owner, and no disk copy holds it. Other sessions' turns
+ * do not stop it (D66). Holds the Environment row's lock until the transaction ends, so a turn
+ * start and disk work on one Environment are decided one after the other.
+ *
+ * A pod Environment must also be usable: not lost (`agent_lost`), on a Runtime with
+ * sandbox pods (`agent_unavailable`). A stopped or failed pod is asked to run again, with
+ * its recipe applied, after the commit.
+ */
+export declare function checkAgentTurn(t: Tx, session: Session, scope: AuthScope, ctx?: TenantContext): Promise<void>;
+/** A sessions reset detaches every session from its Environment: each one's stream says so. */
+export declare function detachAllSessions(t: Tx): Promise<void>;
+/**
+ * Marks the end of a turn's segment on Environment `id`: it was used now (`deleteAfter` counts
+ * from here), and for a running pod idle counts from now and the idle timer is armed (D34).
+ * Best effort.
+ */
+export declare function touchAgent(ctx: TenantContext, id: string): Promise<void>;
+/**
+ * Re-arms the idle timer of every running pod after the Tenant's settings change, so a shorter
+ * `limits.idle` applies to pods already idle (D36: the settings are read whenever a timer is
+ * set). Best effort.
+ */
+export declare function rearmPodTimers(ctx: TenantContext): Promise<void>;
+/** Session lookups for the sandbox route handlers (`core/sandbox-routes.ts`). */
+export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;
+export {};