@nylorun/runtime 0.51.1-beta → 0.52.0-beta

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.52.0-beta
+
+### Minor Changes
+
+- 17951fe: A client can give one Agent a trigger over the API (D88, ADR-145; Host feature `api-triggers`). `PUT /v1/agents/{agentId}/triggers/{triggerId}` creates or replaces the Agent's trigger of a fourth origin, `api`: the body is a `Trigger` exactly as a definition's `runtime.triggers` entry holds it (one of `schedule` with `timezone`, `at` or `webhook`; `session`; `prompt`) and an optional `title`. A new one is active with its next time; a replaced one gets its next time again and keeps its status; the same body again changes nothing and records no event. An id the definition declares, or one an agent's trigger or a booked wake holds, is `409 trigger_conflict`. The checks and limits are a definition's, and `runtime.limits.triggers.count` now counts the triggers an Agent's agents made and those clients put together (`422 trigger_limit`). Upgrades and moves never touch an `api` trigger, `DELETE` removes it, and pause, resume, run and a webhook's secret work as for any trigger.
+
+  - `@nylorun/core`: `TRIGGER_ORIGINS` adds `api`; `TriggerPutSchema`; `TriggerView.principal`; `agent.trigger_created` and `agent.trigger_updated` carry `origin`, `principal`, the timing and `changed` (their `sessionId` is now optional, set for `agent` only; `kind` adds `webhook`), and `agent.trigger_deleted` carries `origin`; Host feature `api-triggers`.
+  - `@nylorun/runtime`: the route; `agent_triggers.principal` and the `api` origin (store migration 0049, run at start).
+  - `@nylorun/agents`: `agents.putTrigger(agentId, triggerId, trigger)`; `deleteTrigger` deletes `api` triggers too.
+  - `nylorun`: `nylorun agents triggers put <id> <trigger>` with `--schedule`, `--timezone`, `--at`, `--webhook`, `--session`, `--prompt` and `--title`, or a JSON file; `rm` deletes `api` triggers.
+  - `@nylorun/studio`: the Triggers tab shows where each trigger came from (the definition's version, the agent that made it, or the principal that put it), its prompt and time zone for every origin, and deletes one an agent made or a client put; Activity words trigger changes and filters them.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [17951fe]
+- Updated dependencies
+  - @nylorun/core@0.45.0-beta
+  - @nylorun/harness@0.36.5-beta
+
+## 0.51.2-beta
+
+### Patch Changes
+
+- b04a877: Pods on Agent Substrate (preview): a pod's engine tries its first join again while the edge can't be reached. A new actor can start before its egress policy reaches Substrate's egress, so the first join failed at the network ("fetch failed") and the engine exited; Substrate doesn't restart an actor's main process, so the actor stayed RUNNING with no engine and the start failed at the ready deadline (E13 on kind: 2 of 3 first starts). The first join is now tried again from 250 ms, doubling to 5 s, for up to 4 minutes (`sandbox_join_retry` in the engine's log); a refusal is still final at once.
+
 ## 0.51.1-beta
 
 ### Patch Changes

package/dist/api/components.d.ts

@@ -2301,11 +2301,13 @@ export declare const TriggerList: z.ZodObject<{
         }>;
         origin: z.ZodEnum<{
             agent: "agent";
+            api: "api";
             manifest: "manifest";
             wake: "wake";
         }>;
         title: z.ZodNullable<z.ZodString>;
         createdSessionId: z.ZodNullable<z.ZodString>;
+        principal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         status: z.ZodEnum<{
             active: "active";
             completed: "completed";
@@ -2323,6 +2325,50 @@ export declare const TriggerList: z.ZodObject<{
         prompt: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+export declare const TriggerView: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        at: "at";
+        schedule: "schedule";
+        wake: "wake";
+        webhook: "webhook";
+    }>;
+    origin: z.ZodEnum<{
+        agent: "agent";
+        api: "api";
+        manifest: "manifest";
+        wake: "wake";
+    }>;
+    title: z.ZodNullable<z.ZodString>;
+    createdSessionId: z.ZodNullable<z.ZodString>;
+    principal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodEnum<{
+        active: "active";
+        completed: "completed";
+        paused: "paused";
+    }>;
+    pausedReason: z.ZodNullable<z.ZodString>;
+    schedule: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodString>;
+    session: z.ZodString;
+    nextRunAt: z.ZodNullable<z.ZodString>;
+    lastRunAt: z.ZodNullable<z.ZodString>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    secretSet: z.ZodOptional<z.ZodBoolean>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const PutTriggerRequest: z.ZodObject<{
+    schedule: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    at: z.ZodOptional<z.ZodISODateTime>;
+    webhook: z.ZodOptional<z.ZodEnum<{
+        "standard-webhooks": "standard-webhooks";
+    }>>;
+    session: z.ZodString;
+    prompt: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const MemoryList: z.ZodObject<{
     memories: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
@@ -2440,6 +2486,7 @@ export declare const TenantRun: z.ZodObject<{
     late: z.ZodBoolean;
     origin: z.ZodEnum<{
         agent: "agent";
+        api: "api";
         manifest: "manifest";
         wake: "wake";
     }>;
@@ -2472,6 +2519,7 @@ export declare const TenantRunEvent: z.ZodObject<{
         late: z.ZodBoolean;
         origin: z.ZodEnum<{
             agent: "agent";
+            api: "api";
             manifest: "manifest";
             wake: "wake";
         }>;

package/dist/api/components.js

@@ -5,7 +5,7 @@
  * global registry.
  */
 import { z } from "zod";
-import { PutSessionModelRequestSchema, SessionModelViewSchema, QueuedResponseSchema, TriggerListSchema, MemoryListSchema, MemorySchema, PutMemoryRequestSchema, MemoryVersionPageSchema, MemoryVersionDetailSchema, TriggerRunPageSchema, RunTriggerResponseSchema, WebhookSecretResponseSchema, WebhookAcceptedResponseSchema, AgentManifestV8Schema, EnvironmentSecretSlotsSchema, DeleteAgentManifestResponseSchema, AgentManifestPlanSchema, AgentManifestVersionsSchema, AgentManifestViewSchema, ListAgentManifestsResponseSchema, PutAgentManifestRequestSchema, PutAgentFolderRequestSchema, AgentManifestSourceSchema, AgentManifestSourceDiffSchema, PutAgentSecretValueRequestSchema, SaveAgentManifestResponseSchema, SessionListItemSchema, ModelCallSchema, SessionPageSchema, SessionManifestViewSchema, HistoryPageSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ModelCallExportPageSchema, AgentPageSchema, ToolCallSchema, ToolCallsPageSchema, TurnTraceSchema, TurnChangesPageSchema, TurnSummarySchema, JwksSchema, SigningKeyListSchema, SigningKeyViewSchema, RotateSigningKeysRequestSchema, RevokeSigningKeyRequestSchema, MeResponseSchema, TenantStatusSchema, ResetTenantRequestSchema, ResetTenantResponseSchema, SeedTenantConfigRequestSchema, SeedTenantConfigResponseSchema, HostModelCatalogSchema, TenantSandboxViewSchema, ModelUsageTotalsSchema, ModelBudgetsSchema, PutModelBudgetsRequestSchema, ToolPolicySchema, PutToolPolicyRequestSchema, PutModelInputsRequestSchema, ModelInputsViewSchema, PutTenantEnvironmentsRequestSchema, ListProvidersResponseSchema, HostModelViewSchema, PutHostModelRequestSchema, SelectHostModelRequestSchema, PutAgentSecretRequestSchema, AgentSecretViewSchema, ListAgentSecretsResponseSchema, McpPreviewRequestSchema, McpPreviewSchema, CredentialCoverageRequestSchema, CredentialCoverageSchema, DeletedResponseSchema, TenantRunEventSchema, TenantRunSchema, ListSessionsResponseSchema, LiveEventSchema, PutAgentRequestSchema, PutSessionRequestSchema, SessionItemsResponseSchema, SessionViewSchema, StreamClosedFrameSchema, AcceptedResponseSchema, SandboxToolOutcomeSchema, AgentViewSchema, AgentSnapshotSchema, RestoreAgentRequestSchema, ForkAgentRequestSchema, AgentForkPlanSchema, ForkAgentResponseSchema, PutAgentDryRunResponseSchema, RestartAgentRequestSchema, AgentRestoreSchema, AgentDiskVersionsSchema, ListAgentsResponseSchema, DeleteAgentResponseSchema, ListAgentEventsResponseSchema, ArtifactViewSchema, ArtifactListItemSchema, ArtifactPageSchema, ArtifactVersionViewSchema, ListArtifactsResponseSchema, UploadArtifactResponseSchema, DefinitionFileViewSchema, DeleteArtifactResponseSchema, CreateArtifactLinkRequestSchema, ArtifactLinkSchema, PutTenantArtifactsRequestSchema, PutTenantSkillsRequestSchema, PutTenantLimitsRequestSchema, TenantLimitsViewSchema, TenantArtifactsViewSchema, TenantSkillsViewSchema, ArtifactTreeSchema, ArtifactDiffSchema, SessionCommandSchema, ListOperatorKeysResponseSchema, PutOperatorKeyResponseSchema, DeleteOperatorKeyResponseSchema, OperatorKeySchema, ProtocolRejectedResponseSchema, RejectedResponseSchema, EVENT_SCHEMAS, EVENT_TYPES, } from "@nylorun/core/contracts";
+import { PutSessionModelRequestSchema, SessionModelViewSchema, QueuedResponseSchema, TriggerListSchema, TriggerPutSchema, TriggerViewSchema, MemoryListSchema, MemorySchema, PutMemoryRequestSchema, MemoryVersionPageSchema, MemoryVersionDetailSchema, TriggerRunPageSchema, RunTriggerResponseSchema, WebhookSecretResponseSchema, WebhookAcceptedResponseSchema, AgentManifestV8Schema, EnvironmentSecretSlotsSchema, DeleteAgentManifestResponseSchema, AgentManifestPlanSchema, AgentManifestVersionsSchema, AgentManifestViewSchema, ListAgentManifestsResponseSchema, PutAgentManifestRequestSchema, PutAgentFolderRequestSchema, AgentManifestSourceSchema, AgentManifestSourceDiffSchema, PutAgentSecretValueRequestSchema, SaveAgentManifestResponseSchema, SessionListItemSchema, ModelCallSchema, SessionPageSchema, SessionManifestViewSchema, HistoryPageSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ModelCallExportPageSchema, AgentPageSchema, ToolCallSchema, ToolCallsPageSchema, TurnTraceSchema, TurnChangesPageSchema, TurnSummarySchema, JwksSchema, SigningKeyListSchema, SigningKeyViewSchema, RotateSigningKeysRequestSchema, RevokeSigningKeyRequestSchema, MeResponseSchema, TenantStatusSchema, ResetTenantRequestSchema, ResetTenantResponseSchema, SeedTenantConfigRequestSchema, SeedTenantConfigResponseSchema, HostModelCatalogSchema, TenantSandboxViewSchema, ModelUsageTotalsSchema, ModelBudgetsSchema, PutModelBudgetsRequestSchema, ToolPolicySchema, PutToolPolicyRequestSchema, PutModelInputsRequestSchema, ModelInputsViewSchema, PutTenantEnvironmentsRequestSchema, ListProvidersResponseSchema, HostModelViewSchema, PutHostModelRequestSchema, SelectHostModelRequestSchema, PutAgentSecretRequestSchema, AgentSecretViewSchema, ListAgentSecretsResponseSchema, McpPreviewRequestSchema, McpPreviewSchema, CredentialCoverageRequestSchema, CredentialCoverageSchema, DeletedResponseSchema, TenantRunEventSchema, TenantRunSchema, ListSessionsResponseSchema, LiveEventSchema, PutAgentRequestSchema, PutSessionRequestSchema, SessionItemsResponseSchema, SessionViewSchema, StreamClosedFrameSchema, AcceptedResponseSchema, SandboxToolOutcomeSchema, AgentViewSchema, AgentSnapshotSchema, RestoreAgentRequestSchema, ForkAgentRequestSchema, AgentForkPlanSchema, ForkAgentResponseSchema, PutAgentDryRunResponseSchema, RestartAgentRequestSchema, AgentRestoreSchema, AgentDiskVersionsSchema, ListAgentsResponseSchema, DeleteAgentResponseSchema, ListAgentEventsResponseSchema, ArtifactViewSchema, ArtifactListItemSchema, ArtifactPageSchema, ArtifactVersionViewSchema, ListArtifactsResponseSchema, UploadArtifactResponseSchema, DefinitionFileViewSchema, DeleteArtifactResponseSchema, CreateArtifactLinkRequestSchema, ArtifactLinkSchema, PutTenantArtifactsRequestSchema, PutTenantSkillsRequestSchema, PutTenantLimitsRequestSchema, TenantLimitsViewSchema, TenantArtifactsViewSchema, TenantSkillsViewSchema, ArtifactTreeSchema, ArtifactDiffSchema, SessionCommandSchema, ListOperatorKeysResponseSchema, PutOperatorKeyResponseSchema, DeleteOperatorKeyResponseSchema, OperatorKeySchema, ProtocolRejectedResponseSchema, RejectedResponseSchema, EVENT_SCHEMAS, EVENT_TYPES, } from "@nylorun/core/contracts";
 function named(id, schema) {
     return schema.meta({ id });
 }
@@ -65,6 +65,8 @@ export const SessionCommand = named("SessionCommand", SessionCommandSchema);
 export const AcceptedResponse = named("AcceptedResponse", AcceptedResponseSchema);
 export const QueuedResponse = named("QueuedResponse", QueuedResponseSchema);
 export const TriggerList = named("TriggerList", TriggerListSchema);
+export const TriggerView = named("TriggerView", TriggerViewSchema);
+export const PutTriggerRequest = named("PutTriggerRequest", TriggerPutSchema);
 export const MemoryList = named("MemoryList", MemoryListSchema);
 export const MemoryView = named("Memory", MemorySchema);
 export const PutMemoryRequest = named("PutMemoryRequest", PutMemoryRequestSchema);

package/dist/api/http/routes/triggers.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
-import { isAgentId } from "@nylorun/core/contracts";
-import { DeletedResponse, RunTriggerResponse, TriggerList, TriggerRunPage, WebhookAcceptedResponse, WebhookSecretResponse, } from "../../components.js";
+import { isAgentId, TriggerIdSchema, TriggerPutSchema } from "@nylorun/core/contracts";
+import { DeletedResponse, PutTriggerRequest, RunTriggerResponse, TriggerList, TriggerRunPage, TriggerView, WebhookAcceptedResponse, WebhookSecretResponse, } from "../../components.js";
 import { assertReaches } from "../../../tenant/agents.js";
 import { fail } from "../../../tenant/http.js";
 import { deleteTrigger, listRuns, listTriggers, receiveWebhook, rotateWebhookSecret, runTriggerNow, setTriggerStatus, } from "../../../tenant/triggers.js";
 import { readRuntimeLimits } from "../../../tenant/runtime-limits.js";
-import { readBytes } from "../body.js";
+import { readBytes, readJson } from "../body.js";
+import { putTrigger } from "../../../tenant/api-triggers.js";
 import { tenantRoute } from "../define.js";
 import { pageQuery, pageSize, parseQuery } from "./reads.js";
 import { jsonResponse } from "../respond.js";
@@ -46,7 +47,7 @@ export function triggerRoutes(api) {
         path: "/v1/agents/{agentId}/triggers",
         tags: ["Triggers"],
         summary: "List an Agent's triggers",
-        description: "Each trigger its manifest declares, and each its agents made with the `triggers` tool (`origin: agent`, with the title and the session that made it), with what the Agent holds of it: its status (`active`, `paused` with a reason, `completed` for an `at` that ran), its prompt, when it runs next and last ran. A session's booked wake is not listed.",
+        description: "Each trigger its manifest declares, each its agents made with the `triggers` tool (`origin: agent`, with the title and the session that made it), and each a client put over the API (`origin: api`, with the title and the `principal` that put it), with what the Agent holds of it: its status (`active`, `paused` with a reason, `completed` for an `at` that ran), its prompt, when it runs next and last ran. A session's booked wake is not listed.",
         request: { params: agentId },
         responses: { 200: json(TriggerList, "The triggers") },
     }, async (c) => {
@@ -73,12 +74,43 @@ export function triggerRoutes(api) {
             assertReaches(c.get("scope"), id);
             return jsonResponse(200, await setTriggerStatus(c.env.tenant, id, c.req.param("triggerId"), action, originOf(c)));
         });
+    tenantRoute(api, WRITE, {
+        method: "put",
+        path: "/v1/agents/{agentId}/triggers/{triggerId}",
+        tags: ["Triggers"],
+        summary: "Put a trigger on an Agent",
+        description: "Creates or replaces the Agent's trigger `triggerId` of origin `api`: a `Trigger` exactly as a definition's `runtime.triggers` entry holds it (one of `schedule` with `timezone`, `at` or `webhook`; `session`; `prompt`), and an optional `title`. A new one is active with its next time; a replaced one gets its next time again and keeps its status, so a paused one stays paused. The same body again changes nothing and records no event. The checks and limits are a definition's; `runtime.limits.triggers.count` covers the triggers the Agent's agents made and those put here. Upgrades never touch it; `DELETE` removes it. Records `agent.trigger_created` or `agent.trigger_updated` (with `changed`) on the Agent's events. Host feature `api-triggers`.",
+        request: {
+            params: triggerPath,
+            body: { required: true, content: { "application/json": { schema: PutTriggerRequest } } },
+        },
+        responses: {
+            200: json(TriggerView, "The trigger, as the list shows it"),
+            400: { description: "Not a trigger, or one the checks refuse: a bad cron or time zone, runs closer than the minimum interval, an `at` not in the future, a prompt too long" },
+            404: { description: "No such Agent" },
+            409: { description: "The definition declares this id, or an agent's trigger or a booked wake holds it (`trigger_conflict`)" },
+            422: { description: "The Agent holds as many triggers its agents or clients made as `limits.triggers.count` allows (`trigger_limit`)" },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        const scope = c.get("scope");
+        assertReaches(scope, id);
+        const triggerId = TriggerIdSchema.safeParse(c.req.param("triggerId"));
+        if (!triggerId.success)
+            fail(400, triggerId.error.issues[0]?.message ?? "Not a trigger id");
+        const body = TriggerPutSchema.safeParse(await readJson(c));
+        if (!body.success)
+            fail(400, body.error.issues.map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`).join("; "), {
+                code: "invalid_request",
+            });
+        return jsonResponse(200, await putTrigger(c.env.tenant, id, triggerId.data, body.data, principalOf(scope), originOf(c)));
+    });
     tenantRoute(api, WRITE, {
         method: "delete",
         path: "/v1/agents/{agentId}/triggers/{triggerId}",
         tags: ["Triggers"],
-        summary: "Delete a trigger an agent made",
-        description: "Deletes a trigger one of the Agent's agents made with the `triggers` tool (`origin: agent`), with `agent.trigger_deleted` on the Agent's events; its runs stay. A trigger its manifest declares is refused (`trigger_from_manifest`): save a version without it, or pause it.",
+        summary: "Delete a trigger an agent made or a client put",
+        description: "Deletes a trigger one of the Agent's agents made with the `triggers` tool (`origin: agent`) or a client put (`origin: api`), with `agent.trigger_deleted` on the Agent's events; its runs stay. A trigger its manifest declares is refused (`trigger_from_manifest`): save a version without it, or pause it.",
         request: { params: triggerPath },
         responses: {
             200: json(DeletedResponse, "Deleted"),

package/dist/api/openapi.js

@@ -161,6 +161,7 @@ const RUNTIME_TAGS = [
         description: "What starts an Agent's turns with no client connected: the schedules, one-shot times and webhook endpoints its manifest's `runtime.triggers` declare, and the schedules and follow-ups its agents set up with the `triggers` tool (`engine.triggers`). Each trigger's status is the Agent's: pause and resume it, run it now, delete one an agent made, make a webhook trigger's signing secret, and read its runs (`started`, `queued`, `skipped` or `failed`, with a reason), an Agent's or the whole Tenant's as a stream. In `@nylorun/agents` and `nylorun agents triggers`.",
         operations: [
             "GET /v1/agents/{agentId}/triggers",
+            "PUT /v1/agents/{agentId}/triggers/{triggerId}",
             "POST /v1/agents/{agentId}/triggers/{triggerId}/pause",
             "POST /v1/agents/{agentId}/triggers/{triggerId}/resume",
             "POST /v1/agents/{agentId}/triggers/{triggerId}/run",

package/dist/harness/main.js

@@ -27,7 +27,7 @@ import { createHostLogger } from "../host/logger.js";
 import { RUNTIME_VERSION } from "../version.js";
 import { localBackend, localExec } from "../adapters/sandbox/local.js";
 import { awaitNetworkPolicy } from "../sandbox/pods/network-gate.js";
-import { podHost } from "./pod.js";
+import { firstJoin, podHost } from "./pod.js";
 import { prepareDisk } from "./setup.js";
 import { harnessRunTokens } from "./run-tokens.js";
 import { startHarnessService } from "./service.js";
@@ -59,8 +59,9 @@ export async function runHarness(stack, baseline) {
             caBundleFile: join(config.root, "egress-ca-bundle.pem"),
             ...(config.pod.egressCaFile ? { extraCaFile: config.pod.egressCaFile } : {}),
         });
-        // Join, then make the disk ready (R2d step 2) before taking any turn.
-        await pod.token();
+        // Join, then make the disk ready (R2d step 2) before taking any turn. The first join is tried
+        // again while the edge can't be reached yet (a new Agent Substrate actor's egress policy).
+        await firstJoin(pod, (message, fields) => logger.warn(message, fields));
         const host = pod;
         prepare = () => prepareDisk({
             host,

package/dist/harness/pod.d.ts

@@ -52,6 +52,23 @@ export interface PodHost {
     setupFile(index: number, path?: string): Promise<Response>;
     stop(): void;
 }
+/**
+ * The engine's first join, tried again while the edge can't be reached. On Agent Substrate a new
+ * actor can start before its egress policy reaches the egress gateway, so its first request to
+ * the edge fails at the network ("fetch failed"), and an engine that then exited stayed down: an
+ * actor's main process is not restarted the way a pod's container is (E13, 2 of 3 first starts on
+ * a GitHub runner). A refusal (400, 401) is final at once; anything else is tried again with a
+ * pause from 250 ms doubling to 5 s, until `budgetMs` (default 4 min, inside the Runtime's 5-minute
+ * ready deadline) has passed.
+ */
+export declare function firstJoin(host: Pick<PodHost, "token">, log: (message: string, fields: Record<string, unknown>) => void, options?: {
+    budgetMs?: number;
+    firstWaitMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<void>;
+/** Whether `error` is the Runtime refusing a join or a renewal (final), not the network. */
+export declare function isRefused(error: unknown): boolean;
 export declare function podHost(config: PodHostConfig, logger: {
     info(message: string, fields?: Record<string, unknown>): void;
     warn(message: string, fields?: Record<string, unknown>): void;

package/dist/harness/pod.js

@@ -29,6 +29,38 @@ const TRUST_VARIABLES = [
 ];
 class Refused extends Error {
 }
+/**
+ * The engine's first join, tried again while the edge can't be reached. On Agent Substrate a new
+ * actor can start before its egress policy reaches the egress gateway, so its first request to
+ * the edge fails at the network ("fetch failed"), and an engine that then exited stayed down: an
+ * actor's main process is not restarted the way a pod's container is (E13, 2 of 3 first starts on
+ * a GitHub runner). A refusal (400, 401) is final at once; anything else is tried again with a
+ * pause from 250 ms doubling to 5 s, until `budgetMs` (default 4 min, inside the Runtime's 5-minute
+ * ready deadline) has passed.
+ */
+export async function firstJoin(host, log, options = {}) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + (options.budgetMs ?? 240_000);
+    let wait = options.firstWaitMs ?? 250;
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await host.token();
+            return;
+        }
+        catch (error) {
+            if (error instanceof Refused || now() + wait > deadline)
+                throw error;
+            log("sandbox_join_retry", { attempt, waitMs: wait, error: error instanceof Error ? error.message : String(error) });
+            await sleep(wait);
+            wait = Math.min(wait * 2, 5_000);
+        }
+    }
+}
+/** Whether `error` is the Runtime refusing a join or a renewal (final), not the network. */
+export function isRefused(error) {
+    return error instanceof Refused;
+}
 export function podHost(config, logger, options = {}) {
     const call = options.fetch ?? fetch;
     const imageEngine = options.imageEngine ?? isBuiltinEngine(import.meta.url);

package/dist/management-openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Management API",
-    "version": "0.51.1-beta",
+    "version": "0.52.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,
@@ -44,6 +44,7 @@
         "secret-routing",
         "remove-tools",
         "agent-triggers",
+        "api-triggers",
         "steer",
         "queue-recovery",
         "a2a-steer"