@nylorun/agents 0.23.0-beta → 0.24.0-beta

package/dist/agents.d.ts

@@ -0,0 +1,456 @@
+/**
+ * Agents (protocol 16): `client.agents`. An Agent is the live instance of one version of an agent
+ * manifest (`client.agentManifests`): one environment of the manifest's runtime kind (`virtual`,
+ * `pod` or `none`), one vault of secrets for its shell, MCP servers and HTTP tools, and the
+ * sessions that run on it. It is made only from a saved manifest, `name` (tracking) or `name@n`
+ * (pinned), and runs one version of it at a time: `put` with another version moves it, and a save
+ * moves every Agent that tracks the manifest (track T3). Its manifest, kind, harness and storage
+ * are fixed (`409 agent_fixed_field`): `fork` makes a new Agent to change them. It has
+ * its own id and outlives its sessions; whether it serves one person or a project is the app's
+ * choice, made by its id:
+ *
+ * - `agents.put("users/alice/triage", { manifest: "triage", owner: "alice" })`: get-or-create
+ *   in one call. Write its secrets with `agents.secrets.put(id, name, { value })` and open
+ *   sessions on it with `createSession({ agent: id, ... })`. Creating it opens no session (D71).
+ *
+ * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
+ * write-only: no call reads one back.
+ *
+ * Triggers (track T4, D74): what its manifest's `runtime.triggers` declares starts its turns with
+ * no client connected. `triggers(id)` lists them with their status and next run, `pauseTrigger`,
+ * `resumeTrigger` and `runTrigger` change or run one, `rotateWebhookSecret` makes a webhook
+ * trigger's signing secret (D75), and `runs(id)` pages what each fire came to.
+ *
+ * Memory (track T5, D72): an Agent whose manifest sets `harness.memory` keeps Markdown files under
+ * `/memories` across sessions. `agents.memories` lists, reads, writes (to seed it), deletes and
+ * pages the versions every change leaves.
+ *
+ * Disk versions (Host feature `environment-disk-versions`): `snapshot(id)` keeps a version of
+ * the Agent's disk between turns, `restore(id, version)` puts one back, and
+ * `put(id, { manifest, from: { agent, version } })` creates a new Agent from another's version.
+ */
+import { type AgentDiskVersions, type AgentEvent, type AgentEventType, type AgentForkPlan, type AgentMovePlan, type AgentRestore, type AgentSecretView, type AgentSnapshot, type AgentView, type DeleteAgentResponse, type ForkAgentRequest, type Memory, type MemoryList, type MemoryVersionDetail, type MemoryVersionPage, type PutAgentRequest, type PutAgentSecretRequest, type TriggerRun, type TriggerRunPage, type TriggerView } from "@nylorun/core/contracts";
+import { type Transport } from "./http.js";
+/** What an Agent is made from (`manifest: "name"` or `"name@n"`), and its owner guard, labels and `from`. */
+export type AgentInput = Omit<PutAgentRequest, "requestId">;
+/**
+ * One secret of an Agent's vault, as written: typed, or only its value (`{ value }`, or
+ * `{ headers }` for a `headers` secret) when its manifest declares the slot (D64).
+ */
+export type AgentSecretInput = PutAgentSecretRequest | {
+    readonly value: string;
+} | {
+    readonly headers: Readonly<Record<string, string>>;
+};
+/** Which Agents a `list` or `page` answers: those with every label, and the state or manifest given. */
+export interface AgentFilter {
+    readonly labels?: Readonly<Record<string, string>>;
+    /** `working`, `sleeping`, `input_required`, `failing` or `paused`. */
+    readonly state?: string;
+    /** The agent manifest's name. */
+    readonly manifest?: string;
+    /** `true`: only Agents moving to another version of their manifest (track T3); `false`: the others. */
+    readonly outdated?: boolean;
+}
+/** The bytes of files by hash, by `sha256:<hex>` (`runtimeFiles(...).bytes`). */
+export type RuntimeFileBytes = Readonly<Record<string, Uint8Array>>;
+/**
+ * A runtime section's `files` entry by content hash (Q6): `contents` (each file's path under
+ * `path` and its bytes or text) hashed, as `entry` for the manifest's `runtime.files` and `bytes`
+ * for `agentManifests.save`'s `files`, which uploads them. Each file holds at most 2 GiB.
+ */
+export declare function runtimeFiles(path: string, contents: Readonly<Record<string, Uint8Array | string>>): Promise<{
+    entry: {
+        path: string;
+        files: Record<string, string>;
+    };
+    bytes: Record<string, Uint8Array>;
+}>;
+/** An Agent's secrets: `client.agents.secrets`. */
+export declare class AgentSecretsClient {
+    private readonly transport;
+    private readonly path;
+    constructor(transport: Transport, path: (agentId: string) => string);
+    /**
+     * Creates or replaces secret `name` (`PUT /v1/agents/{id}/secrets/{name}`): for
+     * `environment_secret` and `environment_variable` the name is the variable's. A second
+     * credential for a host or a URL is a 409 `credential_conflict`. When the Agent's manifest
+     * declares the secret's slot (D64), send only `{ value }` (or `{ headers }`); a name it does
+     * not declare is `409 secret_not_in_manifest`.
+     */
+    put(agentId: string, name: string, secret: AgentSecretInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSecretView>;
+    /** The secrets' names, types and bindings; never a value. */
+    list(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSecretView[]>;
+    get(agentId: string, name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSecretView>;
+    delete(agentId: string, name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+    }>;
+}
+/**
+ * An Agent's memories (track T5, D72): `client.agents.memories`. A path is a memory's path under
+ * `/memories` (`conventions/release.md` or `/memories/conventions/release.md`).
+ */
+export declare class AgentMemoriesClient {
+    private readonly transport;
+    private readonly path;
+    constructor(transport: Transport, path: (agentId: string) => string);
+    private memoryPath;
+    /** The Agent's memories by path; `pathPrefix` keeps one folder's. */
+    list(agentId: string, options?: {
+        pathPrefix?: string;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<MemoryList>;
+    /** One memory with its content. */
+    get(agentId: string, path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Memory>;
+    /**
+     * Writes the memory whole, creating or replacing it: how an app seeds an Agent's memory. With
+     * `contentSha256` the write applies only while the memory still has that content (`""`: only
+     * while there is none); otherwise `409 memory_conflict`.
+     */
+    put(agentId: string, path: string, content: string, options?: {
+        contentSha256?: string;
+        signal?: AbortSignal;
+    }): Promise<Memory>;
+    /** Deletes a memory, or every memory in a folder. */
+    delete(agentId: string, path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        path: string;
+        deleted: number;
+    }>;
+    /** Every change to the Agent's memories, newest first; `path` keeps one memory's. */
+    versions(agentId: string, options?: {
+        path?: string;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<MemoryVersionPage>;
+    /** One version with the content it left (`null` for a delete). */
+    version(agentId: string, versionId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<MemoryVersionDetail>;
+}
+/** The Tenant's Agents: `client.agents`. */
+export declare class AgentInstancesClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    private path;
+    /** The Agent's secrets. */
+    get secrets(): AgentSecretsClient;
+    /** The Agent's memories (track T5). */
+    get memories(): AgentMemoriesClient;
+    /**
+     * Creates the Agent, its vault and its compute from a saved agent manifest, or finds the one
+     * with this id (`PUT /v1/agents/{id}`): `{ manifest: "name" }` tracks the manifest (its latest
+     * version when the Agent is made), `"name@n"` pins version n. On an existing Agent, labels
+     * replace, `owner` sets or clears the owner guard, and `manifest` moves it to that version of
+     * its manifest (track T3): at once, at its pod's next start for a runtime change (`targetVersion`,
+     * `waitingFor: "start"`), or once a required secret the version adds is set. Another manifest,
+     * kind, harness or storage is `409 agent_fixed_field` (fork it instead).
+     */
+    put(agentId: string, input: AgentInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentView>;
+    /**
+     * What `put` would do to the existing Agent (`PUT /v1/agents/{id}?dryRun=true`, track T3): the
+     * version it runs and the one `input.manifest` names, when that applies (`now`, `next_start`,
+     * `secrets`, or `refused` with each fixed field), the changes, and the secrets it would wait
+     * for or leave unused. Nothing changes.
+     */
+    plan(agentId: string, input: AgentInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentMovePlan>;
+    get(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentView>;
+    /** The Agents this client reaches with every label in `labels`, and the `state` or `manifest` given. */
+    list(options?: AgentFilter & {
+        signal?: AbortSignal;
+    }): Promise<AgentView[]>;
+    /** One page of `list` (Host feature `session-reads`). */
+    page(options?: AgentFilter & {
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        agents: {
+            id: string;
+            manifest: string;
+            resolvedVersion: number;
+            manifestHash: string;
+            tracking: "pinned" | "tracking";
+            targetVersion: number | null;
+            waitingFor: "secrets" | "start" | null;
+            failedVersion: number | null;
+            startCheck: {
+                from: number;
+                startedAt: string;
+            } | null;
+            kind: "none" | "pod" | "virtual";
+            harness: string;
+            owner: string | null;
+            labels: Record<string, string>;
+            state: string;
+            attention: {
+                state: "failing" | "input_required" | "paused" | "sleeping" | "working";
+                sessionId?: string | undefined;
+                reason: string;
+            }[];
+            desired: "off" | "on";
+            nextWakeAt: string | null;
+            compute: {
+                state: string;
+                pod?: {
+                    desired: "deleted" | "running" | "suspended";
+                    observed: "creating" | "deleting" | "failed" | "lost" | "running" | "suspended";
+                    volumeGeneration: number;
+                    hostEpoch: number;
+                    reason?: string | undefined;
+                    imageDigest?: string | undefined;
+                } | undefined;
+            };
+            runtime: {
+                image?: string | undefined;
+                resources?: {
+                    cpus: number;
+                    memory: string;
+                } | undefined;
+                storage?: string | undefined;
+                network?: {
+                    allowedHosts: string[];
+                } | undefined;
+                harness: string;
+                lifecycle: {
+                    idle?: string | undefined;
+                    deleteAfter?: string | undefined;
+                };
+                setup?: {
+                    command: string;
+                    cwd?: string | undefined;
+                    timeout?: string | undefined;
+                }[] | undefined;
+                files?: ({
+                    artifactId: string;
+                    version: number;
+                    path: string;
+                } | {
+                    path: string;
+                    files: Record<string, string>;
+                })[] | undefined;
+                limits?: {
+                    artifacts?: {
+                        fileBytes?: number | undefined;
+                        totalBytes?: number | undefined;
+                    } | undefined;
+                    skills?: {
+                        totalBytes?: number | undefined;
+                    } | undefined;
+                    disk?: {
+                        versionBytes?: number | undefined;
+                        versionEntries?: number | undefined;
+                    } | undefined;
+                } | undefined;
+                secrets?: Record<string, {
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "environment_secret";
+                    allowedHosts: string[];
+                    inject?: {
+                        header: string;
+                        format: string;
+                    } | undefined;
+                } | {
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "environment_variable";
+                } | {
+                    via?: string | undefined;
+                    identity?: {
+                        header: string;
+                    } | undefined;
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "bearer";
+                    url: string;
+                } | {
+                    via?: string | undefined;
+                    identity?: {
+                        header: string;
+                    } | undefined;
+                    required?: boolean | undefined;
+                    description?: string | undefined;
+                    type: "headers";
+                    url: string;
+                }> | undefined;
+            };
+            limits: {
+                artifacts: {
+                    fileBytes: number;
+                    totalBytes: number;
+                };
+                skills: {
+                    totalBytes: number;
+                };
+                disk: {
+                    versionBytes: number;
+                    versionEntries: number;
+                };
+            };
+            sessions: {
+                id: string;
+                ownerUserId: string;
+                status: string;
+                activeTurnId: string | null;
+            }[];
+            slots: {
+                name: string;
+                type: string;
+                required: boolean;
+                set: boolean;
+            }[];
+            disk?: {
+                latestVersion: number | null;
+                operation: {
+                    kind: "restore" | "seed" | "snapshot";
+                    version?: number | undefined;
+                    startedAt: string;
+                } | null;
+            } | undefined;
+            forkedFrom: {
+                agent: string;
+                disk: number | null;
+            } | null;
+            lastUsedAt: string;
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        nextCursor: string | null;
+    }>;
+    /** Stops a pod Agent's compute: its volume is kept, and the next turn starts it again. */
+    stop(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentView>;
+    /**
+     * Applies a version the Agent waits to apply (`POST /v1/agents/{id}/restart`, track T3): a
+     * running pod stops, so the next turn starts it on the version; a stopped one starts at once.
+     * `retry` first moves it to the version that failed to start again. Refused during a turn.
+     */
+    restart(agentId: string, options?: {
+        retry?: boolean;
+        signal?: AbortSignal;
+    }): Promise<AgentView>;
+    /** Resets a pod Agent: a new pod on a new, empty volume, with its runtime section applied. */
+    reset(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentView>;
+    /**
+     * Keeps a version of the Agent's disk (`POST /v1/agents/{id}/snapshot`), between turns;
+     * `unchanged` when the disk is as the latest version has it.
+     */
+    snapshot(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSnapshot>;
+    /**
+     * Puts disk version `version` back: at once for a virtual Agent (`done`), on a new volume
+     * seeded before the next turn for a pod (`pending`).
+     */
+    restore(agentId: string, version: number | "latest", options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentRestore>;
+    /**
+     * Forks the Agent into a new one, `options.id` (Q15): how an Agent changes what is fixed for its
+     * life (its manifest, kind, harness or storage). It is made from `options.manifest` (default the source's manifest,
+     * tracking), its disk starts from `options.disk` (`latest`, the default, snapshots first; a
+     * version; or `empty`) and the secrets the new manifest declares are copied
+     * (`options.secrets: "none"` copies none). The source keeps what it runs, its disk and its
+     * sessions. Answers the new Agent and the plan it ran.
+     */
+    fork(agentId: string, options: Omit<ForkAgentRequest, "requestId" | "dryRun"> & {
+        signal?: AbortSignal;
+    }): Promise<{
+        agent: AgentView;
+        plan: AgentForkPlan;
+    }>;
+    /** What `fork` would do (the disk, the secrets copied and left behind, the changes), making nothing. */
+    planFork(agentId: string, options: Omit<ForkAgentRequest, "requestId" | "dryRun"> & {
+        signal?: AbortSignal;
+    }): Promise<AgentForkPlan>;
+    /** The Agent's disk versions, newest first. */
+    versions(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentDiskVersions>;
+    /** Deletes disk version `version`; `deleted` is false when there was none. */
+    deleteVersion(agentId: string, version: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        agentId: string;
+        version: number;
+        deleted: boolean;
+    }>;
+    /** Deletes the Agent, its vault and its files; `deleted` is false when there was none. */
+    delete(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DeleteAgentResponse>;
+    /**
+     * The Agent's events, from `from` on: its lifecycle, and `agent.egress` for every connection
+     * its sandbox opens (with the turns that were running). `types` keeps only those types;
+     * `since` and `until` keep events recorded in that window (ISO times or `Date`s).
+     */
+    events(agentId: string, options?: {
+        from?: number;
+        types?: readonly AgentEventType[];
+        since?: string | Date;
+        until?: string | Date;
+        signal?: AbortSignal;
+    }): Promise<AgentEvent[]>;
+    /** The Agent's triggers: each one's status (`active`, `paused`, `completed`), next and last run. */
+    triggers(agentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<TriggerView[]>;
+    /** Pauses trigger `triggerId`: it stops firing until it is resumed. Answers the Agent's triggers. */
+    pauseTrigger(agentId: string, triggerId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<TriggerView[]>;
+    /** Resumes trigger `triggerId` from its next time after now. Answers the Agent's triggers. */
+    resumeTrigger(agentId: string, triggerId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<TriggerView[]>;
+    /**
+     * Runs trigger `triggerId` once now, as if it fired: `idempotencyKey` (default a new one) makes a
+     * retried call answer the same run.
+     */
+    runTrigger(agentId: string, triggerId: string, options?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<TriggerRun>;
+    /**
+     * A new Standard Webhooks signing secret for webhook trigger `triggerId` (`whsec_…`), shown this
+     * once with the trigger's `webhookUrl`; the one before stops working at once.
+     */
+    rotateWebhookSecret(agentId: string, triggerId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        triggerId: string;
+        webhookUrl: string;
+        secret: string;
+    }>;
+    /** The Agent's runs, newest first; `triggerId` keeps one trigger's. */
+    runs(agentId: string, options?: {
+        triggerId?: string;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<TriggerRunPage>;
+}