@nylorun/runtime 0.26.0-beta → 0.28.0-beta

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 {};