@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/store/types.d.ts

@@ -63,11 +63,11 @@
 import type { KeyRole } from "@nylorun/core/compatibility";
 import type { RecordReader } from "../streams/relay/types.js";
 import type { SandboxSignal, Wake } from "../execution/types.js";
-import type { EventPayload, EventType, EventWriter, LiveEvent, EnvironmentEvent, EnvironmentEventPayload, EnvironmentEventType, EnvironmentKind, EnvironmentManifest, EnvironmentRecipe, PodDesired, PodObserved, SessionEventOf } from "@nylorun/core/contracts";
+import type { EventPayload, EventType, EventWriter, LiveEvent, AgentEvent, AgentEventPayload, AgentEventType, AgentManifestV8, EnvironmentKind, EnvironmentRecipe, PodDesired, PodObserved, SessionEventOf } from "@nylorun/core/contracts";
 import type { HostEffect } from "@nylorun/harness/run";
-import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
+import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, QueuedMessageRow, AgentTriggerRow, TriggerRunRow, MemoryRow, MemoryVersionRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
-export type DocTable = "definitions" | "sessions" | "commands" | "effects" | "sandboxes" | "links";
+export type DocTable = "sessions" | "commands" | "effects" | "sandboxes" | "links";
 export declare const DOC_TABLES: readonly DocTable[];
 /** Session lifecycle (architecture §10.2). */
 export type SessionStatus = "idle" | "runnable" | "running" | "waiting" | "paused" | "uncertain" | "completed" | "failed" | "cancelled";
@@ -117,17 +117,15 @@ export interface LinkDoc {
     effectId: string;
     turnId: string;
 }
-/** A definition document. Indexed: `manifest.id`. */
-export interface DefinitionDoc {
-    manifest: {
-        id: string;
-    };
-}
 /** A sandbox record, keyed by sandbox key. */
 export interface SandboxDoc {
     key: string;
 }
-/** An Environment (`environments`, D55): what `PUT /v1/environments/{id}` created. */
+/**
+ * An Agent's row (`agents`; an Environment's before protocol 16): what `PUT /v1/agents/{id}`
+ * created. The Runtime's own code calls the part it runs on (its kind, recipe, pod, disk and
+ * vault) the Agent's environment, keyed by the Agent's id.
+ */
 export interface Environment {
     id: string;
     kind: EnvironmentKind;
@@ -138,7 +136,7 @@ export interface Environment {
     applied: EnvironmentRecipe;
     version: number;
     appliedVersion: number;
-    /** The owner guard: only this owner's sessions may name it. */
+    /** The owner guard (`owner` on the API): only this owner's sessions may run on it. */
     ownerUserId?: string;
     /** ISO time it was last used (`lifecycle.deleteAfter` counts from it). */
     lastUsedAt: string;
@@ -153,16 +151,39 @@ export interface Environment {
      * Q17): the setup runs once the version is written (`written`), and the seed stays until it is done.
      */
     diskSeed?: DiskSeed;
-    /** The environment manifest it was made from and its version (D63); absent for an inline one. */
-    manifestName?: string;
-    manifestVersion?: number;
-    /** The hash of what it runs (`recipe`), recorded at creation (protocol 14). */
-    manifestHash?: string;
-    /** The Environment it was forked from and the disk version it started from (Q15). */
+    /** The agent manifest it was made from and the version it resolved then, which it runs. */
+    manifestName: string;
+    manifestVersion: number;
+    /** How it names the manifest: `tracking` (`name`) or `pinned` (`name@n`). */
+    manifestRef: "tracking" | "pinned";
+    /** The hash of that manifest version. */
+    manifestHash: string;
+    /** `on`, or `off` once paused (track T6). */
+    desiredState: "on" | "off";
+    /** The Agent it was forked from and the disk version it started from (Q15). */
     forkedFrom?: {
-        environment: string;
+        agent: string;
         disk: number | null;
     };
+    /**
+     * The manifest version it moves to while it is outdated (track T3, D73): it waits for its
+     * required secrets or its pod's next start. Absent when it runs the version it should.
+     */
+    targetVersion?: number;
+    /** A version that failed to start (T3): a tracking Agent does not move to it again on its own. */
+    failedVersion?: number;
+    /** While a pod starts on a new version (T3): what it ran before, which a failed start reverts to. */
+    startCheck?: AgentStartCheck;
+}
+/** What a pod Agent ran before it started on a new version (track T3), and since when it starts. */
+export interface AgentStartCheck {
+    from: {
+        manifestVersion: number;
+        manifestHash: string;
+        applied: EnvironmentRecipe;
+        imageDigest?: string;
+    };
+    startedAt: string;
 }
 /** A pending seed of an Environment's disk (`disk_seed`). */
 export interface DiskSeed {
@@ -173,11 +194,11 @@ export interface DiskSeed {
     /** The version is written; with `setup`, the seed waits for the setup to be done. */
     written?: true;
 }
-/** One version of an environment manifest (`environment_manifests`, D63). */
-export interface EnvironmentManifestRow {
+/** One version of an agent manifest (`agent_manifests`, protocol 16). */
+export interface AgentManifestRow {
     name: string;
     version: number;
-    body: EnvironmentManifest;
+    body: AgentManifestV8;
     hash: string;
     savedBy: {
         actor: string;
@@ -260,11 +281,11 @@ export type CommitListener = (commit: Commit) => void;
  * `bytea` columns, never inside a JSON body), the vault's audit and idempotency records, the
  * Tenant's signing keys, a model call in the usage ledger and a model budget.
  */
-export type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, ToolCrossingRow, PrincipalRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
+export type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, ToolCrossingRow, QueuedMessageRow, AgentTriggerRow, TriggerRunRow, MemoryRow, MemoryVersionRow, PrincipalRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
 /** Which rows of the usage ledger a total covers. */
 export interface ModelUsageQuery {
-    scope: "tenant" | "agent" | "turn";
-    /** The agent or turn id; ignored for `tenant`. */
+    scope: "tenant" | "manifest" | "turn";
+    /** The agent manifest's name or the turn id; ignored for `tenant`. */
     id?: string;
     /** Only rows created at or after this ISO time. */
     since?: string;
@@ -289,9 +310,9 @@ export interface StoreCounts {
     /** Effects `uncertain`. */
     uncertainEffects: number;
     sandboxes: number;
-    definitions: number;
+    agentManifests: number;
 }
-export type ResetScope = "sessions" | "environments" | "all";
+export type ResetScope = "sessions" | "agents" | "all";
 /** Result of `takeOwnership`. */
 export type TakeOwnership = {
     status: "owned";
@@ -541,9 +562,8 @@ export interface Tx {
         agentId?: string;
         ownerUserId?: string;
     }): Promise<StoredSession<T>[]>;
-    listDefinitions<T extends DefinitionDoc = DefinitionDoc>(): Promise<T[]>;
     listSandboxes<T extends SandboxDoc = SandboxDoc>(): Promise<T[]>;
-    /** Environment `id`; with `lock`, its row is locked until the transaction ends. */
+    /** Agent `id`'s row; with `lock`, it is locked until the transaction ends. */
     environment(id: string, options?: {
         lock?: boolean;
     }): Promise<Environment | undefined>;
@@ -554,8 +574,8 @@ export interface Tx {
     createEnvironment(row: Environment, limit: number): Promise<"created" | "exists" | "limit">;
     /**
      * Changes an Environment's columns other than its pod's (the caller holds the row's lock):
-     * labels, recipe and version, the applied recipe and its version, the owner guard (`null`
-     * clears it), and when it was last used.
+     * labels, recipe and version, the applied recipe and its version, the manifest version it runs
+     * and how it names it (track T3), the owner guard (`null` clears it), and when it was last used.
      */
     updateEnvironment(id: string, patch: {
         labels?: Record<string, string>;
@@ -563,6 +583,12 @@ export interface Tx {
         version?: number;
         applied?: EnvironmentRecipe;
         appliedVersion?: number;
+        manifestVersion?: number;
+        manifestHash?: string;
+        manifestRef?: "tracking" | "pinned";
+        targetVersion?: number | null;
+        failedVersion?: number | null;
+        startCheck?: AgentStartCheck | null;
         ownerUserId?: string | null;
         lastUsedAt?: string;
         diskOp?: DiskOperation | null;
@@ -576,32 +602,32 @@ export interface Tx {
     listEnvironments(filter?: {
         labels?: Record<string, string>;
     }): Promise<Environment[]>;
-    /** Sessions that name Environment `environmentId` (`Session.environmentId`), by id. */
+    /** Sessions on Agent `environmentId` (`Session.environmentId`), by id. */
     sessionsOnEnvironment<T extends SessionDoc = SessionDoc>(environmentId: string): Promise<StoredSession<T>[]>;
     /**
-     * Appends an event to the Environment's lifecycle stream through the record module. The
-     * caller holds the Environment row's lock (or created the row in this transaction).
+     * Appends an event to the Agent's lifecycle stream through the record module. The caller holds
+     * the Agent row's lock (or created the row in this transaction).
      */
-    environmentEvent<T extends EnvironmentEventType>(environmentId: string, type: T, payload: EnvironmentEventPayload<T>): Promise<EnvironmentEvent>;
+    agentEvent<T extends AgentEventType>(agentId: string, type: T, payload: AgentEventPayload<T>): Promise<AgentEvent>;
     /**
-     * The Environment's stream, from `fromSeq` on, at most `limit` events: only `types` when given,
-     * and only events recorded at or after `since` and before `until` (ISO times) when given.
+     * The Agent's stream, from `fromSeq` on, at most `limit` events: only `types` when given, and
+     * only events recorded at or after `since` and before `until` (ISO times) when given.
      */
-    environmentEvents(environmentId: string, options?: EnvironmentEventsQuery): Promise<EnvironmentEvent[]>;
+    agentEvents(agentId: string, options?: AgentEventsQuery): Promise<AgentEvent[]>;
     /** Holds manifest `name`'s save lock until the transaction ends, so saves of one name are serial. */
-    lockEnvironmentManifest(name: string): Promise<void>;
+    lockAgentManifest(name: string): Promise<void>;
     /** Version `version` of manifest `name`, or its latest when `version` is omitted. */
-    environmentManifest(name: string, version?: number): Promise<EnvironmentManifestRow | undefined>;
+    agentManifest(name: string, version?: number): Promise<AgentManifestRow | undefined>;
     /** Writes a new version (the caller holds the name's lock and chose the next number). */
-    insertEnvironmentManifest(row: EnvironmentManifestRow): Promise<void>;
+    insertAgentManifest(row: AgentManifestRow): Promise<void>;
     /** Each manifest's latest version, by name. */
-    listEnvironmentManifests(): Promise<EnvironmentManifestRow[]>;
+    listAgentManifests(): Promise<AgentManifestRow[]>;
     /** Every version of manifest `name`, newest first. */
-    environmentManifestVersions(name: string): Promise<EnvironmentManifestRow[]>;
+    agentManifestVersions(name: string): Promise<AgentManifestRow[]>;
     /** Deletes every version of manifest `name`; how many there were. */
-    deleteEnvironmentManifest(name: string): Promise<number>;
-    /** How many Environments were made from each version of manifest `name` (deleting ones too). */
-    environmentsOfManifest(name: string): Promise<Map<number, number>>;
+    deleteAgentManifest(name: string): Promise<number>;
+    /** How many Agents were made from each version of manifest `name` (deleting ones too). */
+    agentsOfManifest(name: string): Promise<Map<number, number>>;
     /** `invoking` effects of one session; takeover turns them `uncertain`. */
     invokingEffects<T extends EffectDoc = EffectDoc>(sessionId: string): Promise<T[]>;
     effectsForSession<T extends EffectDoc = EffectDoc>(sessionId: string, filter?: SessionEffectFilter): Promise<T[]>;
@@ -609,6 +635,86 @@ export interface Tx {
     effectsWithStatus<T extends EffectDoc = EffectDoc>(statuses: readonly (EffectStatus | (string & {}))[], filter?: {
         kinds?: readonly EffectKind[];
     }): Promise<T[]>;
+    /** Adds a message at the end of its session's queue; returns its position in the queue's order. */
+    enqueueMessage(row: Omit<QueuedMessageRow, "seq">): Promise<number>;
+    /** A session's queued messages, first to go first. */
+    queuedMessages(sessionId: string): Promise<QueuedMessageRow[]>;
+    countQueuedMessages(sessionId: string): Promise<number>;
+    /** Removes queued messages a turn took. */
+    deleteQueuedMessages(ids: readonly string[]): Promise<void>;
+    agentTriggers(agentId: string): Promise<AgentTriggerRow[]>;
+    /** One trigger's state; with `lock`, its row is locked until the transaction ends. */
+    agentTrigger(agentId: string, triggerId: string, options?: {
+        lock?: boolean;
+    }): Promise<AgentTriggerRow | undefined>;
+    /** Inserts or replaces a trigger's state (its `createdAt` is kept). */
+    putAgentTrigger(row: AgentTriggerRow): Promise<void>;
+    deleteAgentTrigger(agentId: string, triggerId: string): Promise<void>;
+    /** Deletes an Agent's triggers and runs. */
+    deleteAgentTriggers(agentId: string): Promise<void>;
+    /**
+     * Active triggers with a next fire time (due by `dueBefore`, changed since `changedSince`, when
+     * given), by Agent and trigger id.
+     */
+    activeTriggers(options: {
+        dueBefore?: string;
+        changedSince?: string;
+        after?: {
+            agentId: string;
+            triggerId: string;
+        };
+        limit: number;
+    }): Promise<AgentTriggerRow[]>;
+    /** The webhook trigger whose endpoint id is `endpointId`. */
+    agentTriggerByEndpoint(endpointId: string): Promise<AgentTriggerRow | undefined>;
+    /** The earliest next fire time of an Agent's active triggers, or `null`. */
+    nextWakeAt(agentId: string): Promise<string | null>;
+    /** Records a run; false when one with the same `runKey` exists for the Agent. */
+    insertTriggerRun(row: TriggerRunRow): Promise<boolean>;
+    triggerRunByKey(agentId: string, runKey: string): Promise<TriggerRunRow | undefined>;
+    updateTriggerRun(id: string, patch: Partial<Omit<TriggerRunRow, "id">>): Promise<void>;
+    /** An Agent's runs fired at or after `since` with one of `statuses`. */
+    countTriggerRuns(agentId: string, since: string, statuses: readonly TriggerRunRow["status"][]): Promise<number>;
+    /** An Agent's runs, newest first, before run id `before`. */
+    listTriggerRuns(agentId: string, options: {
+        triggerId?: string;
+        before?: string;
+        limit: number;
+    }): Promise<TriggerRunRow[]>;
+    /** Deletes runs fired before `before`; returns how many. */
+    pruneTriggerRuns(before: string): Promise<number>;
+    /** One memory; with `lock`, its path is locked until the transaction ends, whether or not a row has it. */
+    memory(agentId: string, path: string, options?: {
+        lock?: boolean;
+    }): Promise<MemoryRow | undefined>;
+    /**
+     * An Agent's memories by path: those inside `folder` (a normalised folder path, `/memories` for
+     * all), after path `after`; with `lock`, their rows are locked until the transaction ends.
+     */
+    memories(agentId: string, options: {
+        folder?: string;
+        after?: string;
+        limit?: number;
+        lock?: boolean;
+    }): Promise<MemoryRow[]>;
+    countMemories(agentId: string): Promise<number>;
+    /** An Agent's newest memories first (by `updatedAt`, then path): what the pinned index lists. */
+    recentMemories(agentId: string, limit: number): Promise<Pick<MemoryRow, "path" | "description" | "bytes">[]>;
+    /** Inserts or replaces a memory. */
+    putMemory(row: MemoryRow): Promise<void>;
+    deleteMemory(agentId: string, path: string): Promise<void>;
+    insertMemoryVersion(row: MemoryVersionRow): Promise<void>;
+    /** An Agent's memory versions, newest first, before version id `before`; `path` keeps one path's. */
+    memoryVersions(agentId: string, options: {
+        path?: string;
+        before?: string;
+        limit: number;
+    }): Promise<MemoryVersionRow[]>;
+    memoryVersion(agentId: string, id: string): Promise<MemoryVersionRow | undefined>;
+    /** Copies Agent `from`'s memories to new Agent `to`, each at version 1, with no history (a fork). */
+    copyMemories(from: string, to: string, now: string): Promise<number>;
+    /** Deletes an Agent's memories and their versions. */
+    deleteAgentMemories(agentId: string): Promise<void>;
     /** Links of one workflow session joined to their existing agent sessions, ordered by agent session id. */
     linkedSessions<S extends SessionDoc = SessionDoc>(workflowSessionId: string): Promise<LinkedSession<S>[]>;
     counts(): Promise<StoreCounts>;
@@ -794,16 +900,15 @@ export interface Tx {
      *   Tenant's record rows and log heads. The Tenant moves to the next basin
      *   generation and the current one is retired, so session ids it frees start again in an
      *   empty basin;
-     * - `environments`: sandbox records, Environments with their vaults, and their lifecycle
-     *   streams;
-     * - `all`: both, plus definitions (and which definition files they use),
+     * - `agents`: sandbox records, Agents with their vaults, and their lifecycle streams;
+     * - `all`: both, plus agent manifests (and which definition files they use),
      *   the model usage ledger, the model budgets and Tenant-wide artifacts. The host vault, principals, signing keys,
      *   settings, audit and vault idempotency rows stay.
      */
     reset(scope: ResetScope): Promise<void>;
 }
-/** Which of an Environment's events to read (`Tx.environmentEvents`). */
-export interface EnvironmentEventsQuery {
+/** Which of an Agent's events to read (`Tx.agentEvents`). */
+export interface AgentEventsQuery {
     readonly fromSeq?: number;
     readonly limit?: number;
     readonly types?: readonly string[];

package/dist/store/types.js

@@ -1,5 +1,4 @@
 export const DOC_TABLES = [
-    "definitions",
     "sessions",
     "commands",
     "effects",

package/dist/tenant/advance.js

@@ -50,11 +50,11 @@ import { recoversModelCalls } from "./effects.js";
 import { contextCompacted } from "./transcript.js";
 import { slimModelEffects } from "./slim.js";
 import { applyUpdates, leanState, transcriptShadow, withTranscript, } from "./history.js";
-import { command } from "./commands.js";
-import { dropRunGrant, grantRun } from "./run-grants.js";
+import { command, startQueuedTurn } from "./commands.js";
+import { dropRunGrant, grantRun, rootAgentOf } from "./run-grants.js";
 import { startHeartbeat } from "../harness-api/renew.js";
 import { buildTurnStart, startSegment } from "../harness-api/start.js";
-import { touchEnvironment } from "./environments.js";
+import { touchAgent } from "./agents.js";
 import { endTurn, pauseTurn } from "./turn-timing.js";
 import { hostTuning } from "../tuning.js";
 import { AdvanceAbort, AdvanceDeadlineError, abortKind, } from "./worker.js";
@@ -124,7 +124,10 @@ export async function advance(ctx, id, signal) {
     ctx.work.running.set(id, controller);
     ctx.work.runningTurns.set(id, taken.session.activeTurnId ?? null);
     // A harness renews the lease once it holds the run; until then, and without one, core does.
-    const run = { agentId: taken.session.agentId, activeTurnId: taken.session.activeTurnId };
+    // The run token names the root agent as the engine does: the loop manifest's id, i.e. the
+    // agent manifest's name (protocol 16), never the Agent the session runs on. The model gate's
+    // usage rows and `manifest` budgets key on it.
+    const run = { agentId: rootAgentOf(taken.session), activeTurnId: taken.session.activeTurnId };
     const heartbeat = startHeartbeat(ctx, lease, controller, run);
     let result = DONE;
     let release = true;
@@ -181,7 +184,7 @@ export async function advance(ctx, id, signal) {
         // The Environment was used: `deleteAfter`, and a pod's idle time (D34), count from the end
         // of each segment.
         if (placed.environment !== undefined)
-            await touchEnvironment(ctx, placed.environment);
+            await touchAgent(ctx, placed.environment);
     }
     return result;
 }
@@ -194,11 +197,11 @@ function podUnusable(ctx, segment) {
         return `Environment ${pod.id} is a pod Environment, and this Runtime has no sandbox pods`;
     const state = pod.pod;
     if (state.desired === "deleted")
-        return `Environment ${pod.id} was deleted`;
+        return `Agent ${pod.id} was deleted`;
     if (state.observed === "lost")
-        return `Environment ${pod.id} was lost: ${state.reason ?? "its volume is gone"}`;
+        return `Agent ${pod.id} was lost: ${state.reason ?? "its volume is gone"}`;
     if (state.observed === "failed")
-        return `Environment ${pod.id} failed to start: ${state.reason ?? "its pod was not ready"}`;
+        return `Agent ${pod.id} failed to start: ${state.reason ?? "its pod was not ready"}`;
     return undefined;
 }
 /**
@@ -285,6 +288,10 @@ async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, p
         // A new volume being seeded from a disk version takes no turn until it holds it (R2d step 3).
         if (segment.pod?.seeding)
             throw new HarnessUnavailable();
+        // A pod starting on a new version takes no turn until its harness joins (track T3): a start
+        // that fails goes back to the version it ran, and the turn's first segment re-pins to it.
+        if (segment.pod?.starting)
+            throw new HarnessUnavailable();
         const pod = segment.pod?.id;
         if (started.environmentId !== undefined)
             placed.environment = started.environmentId;
@@ -562,6 +569,9 @@ writer) {
         await t.event(id, s.activeTurnId, type, payload, writer);
         await t.put("sessions", id, current);
         await wakeWorkflowOf(ctx, t, current, s.activeTurnId, type, payload);
+        // Messages that waited for this turn start the next one (protocol 17).
+        if (await startQueuedTurn(ctx, t, current, id))
+            await t.put("sessions", id, current);
         return siblings;
     });
     for (const agentId of siblingCancelIds) {
@@ -636,6 +646,8 @@ async function settleFailure(ctx, lease, s, error) {
         current.activeTurnId = null;
         await t.put("sessions", id, current);
         await wakeWorkflowOf(ctx, t, current, s.activeTurnId, "turn.failed", payload);
+        if (await startQueuedTurn(ctx, t, current, id))
+            await t.put("sessions", id, current);
     });
 }
 /** Whether the session runs our harness, whose state core may store lean (R4.2). */

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

@@ -0,0 +1,72 @@
+/**
+ * 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 { type AgentManifestChange, type AgentManifestPlan, type AgentManifestV8, type AgentManifestVersions, type AgentManifestView, type PutAgentManifestRequest, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
+import { type RecipeRequest } from "../sandbox/resolve.js";
+import type { AuthScope, TenantContext } from "./context.js";
+/** What a manifest's runtime section asks of an Agent's recipe, with the harness its loop names. */
+export declare function manifestRecipeRequest(manifest: Pick<AgentManifestV8, "harness" | "runtime">): RecipeRequest;
+/** The hash a manifest's version records: equal manifests hash the same. */
+export declare function agentManifestHash(manifest: AgentManifestV8): string;
+/** The owner a version's definition files are recorded under, for the sweep. */
+export declare function manifestFileOwner(name: string): string;
+/** Each field that differs between `before` and `after`, by path; arrays compare whole. */
+export declare function manifestChanges(before: unknown, after: unknown, path?: string): {
+    path: string;
+    from?: unknown;
+    to?: unknown;
+}[];
+/**
+ * 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 declare function sectionChanges(before: Partial<AgentManifestV8> | undefined, after: AgentManifestV8): AgentManifestChange[];
+/**
+ * `PUT /v1/agent-manifests/{name}`: saves `body` as manifest `name`'s next version, or answers
+ * the latest unchanged; with `dryRun`, the plan of that save and nothing saved.
+ */
+export declare function saveAgentManifest(ctx: TenantContext, name: string, body: PutAgentManifestRequest, scope: AuthScope, options: {
+    dryRun: true;
+    ifMatch?: number;
+}): Promise<AgentManifestPlan>;
+export declare function saveAgentManifest(ctx: TenantContext, name: string, body: PutAgentManifestRequest, scope: AuthScope, options?: {
+    dryRun?: false;
+    ifMatch?: number;
+}): Promise<SaveAgentManifestResponse>;
+/** `GET /v1/agent-manifests/{name}` (the latest) and `.../versions/{n}`. */
+export declare function getAgentManifest(ctx: TenantContext, name: string, version?: number): Promise<AgentManifestView>;
+/** `GET /v1/agent-manifests`: each manifest's latest version. */
+export declare function listAgentManifests(ctx: TenantContext): Promise<{
+    manifests: AgentManifestView[];
+}>;
+/** `GET /v1/agent-manifests/{name}/versions`: every version, newest first. */
+export declare function agentManifestVersions(ctx: TenantContext, name: string): Promise<AgentManifestVersions>;
+/**
+ * `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 declare function deleteAgentManifest(ctx: TenantContext, name: string): Promise<{
+    name: string;
+    deleted: boolean;
+}>;