@nylorun/runtime 0.51.2-beta → 0.52.0-beta

package/dist/store/postgres/schema.js

@@ -249,11 +249,14 @@ export const agentTriggers = nylorun.table("agent_triggers", {
     note: text(),
     effectId: text(),
     /**
-     * Where its definition comes from (D83): `manifest` (the version's `runtime.triggers`),
-     * `agent` (`definition`, made with the `triggers` tool) or `wake` (a booked wake).
+     * Where its definition comes from (D83, D88): `manifest` (the version's `runtime.triggers`),
+     * `agent` (`definition`, made with the `triggers` tool), `api` (`definition`, put by a client
+     * over the API) or `wake` (a booked wake).
      */
-    origin: text({ enum: ["manifest", "agent", "wake"] }).notNull().default("manifest"),
-    /** An agent-made trigger's title, its definition, and the session and turn that made it. */
+    origin: text({ enum: ["manifest", "agent", "api", "wake"] }).notNull().default("manifest"),
+    /** Who put an `api` trigger (D88): the caller's principal. */
+    principal: text(),
+    /** An agent-made or put trigger's title, its definition, and the session and turn that made it. */
     title: text(),
     definition: jsonText(),
     createdSessionId: textC(),
@@ -261,7 +264,7 @@ export const agentTriggers = nylorun.table("agent_triggers", {
     createdAt: textC().notNull(),
     updatedAt: textC().notNull(),
 }, (t) => [
-    check("agent_triggers_origin_check", sql `${t.origin} IN ('manifest', 'agent', 'wake')`),
+    check("agent_triggers_origin_check", sql `${t.origin} IN ('manifest', 'agent', 'api', 'wake')`),
     primaryKey({ name: "agent_triggers_pkey", columns: [t.agentId, t.triggerId] }),
     index("agent_triggers_created_session").on(t.agentId, t.createdSessionId).where(sql `created_session_id IS NOT NULL`),
     index("agent_triggers_due").on(t.status, t.nextFireAt),
@@ -326,8 +329,8 @@ export const triggerRuns = nylorun.table("trigger_runs", {
     sessionId: textC(),
     turnId: textC(),
     queuedMessageId: textC(),
-    /** Its trigger's origin and title when it ran (D83), for the runs stream after the trigger is gone. */
-    origin: text({ enum: ["manifest", "agent", "wake"] }).notNull().default("manifest"),
+    /** Its trigger's origin and title when it ran (D83, D88), for the runs stream after the trigger is gone. */
+    origin: text({ enum: ["manifest", "agent", "api", "wake"] }).notNull().default("manifest"),
     title: text(),
     /** When it was appended to the Tenant's `runs` stream (ISO), or null until then. */
     streamedAt: textC(),

package/dist/tenant/agent-triggers.js

@@ -115,7 +115,7 @@ export async function serveTriggersTool(t, s, request) {
         if (!row || !reaches(row, s.id))
             return failed("tool.not-found", `This session has no trigger ${input.id}: list shows the ones it has.`);
         await t.deleteAgentTrigger(s.agentId, input.id);
-        await t.agentEvent(s.agentId, "agent.trigger_deleted", { triggerId: input.id, sessionId: s.id });
+        await t.agentEvent(s.agentId, "agent.trigger_deleted", { triggerId: input.id, origin: "agent", sessionId: s.id });
         return completed({ id: input.id, deleted: true });
     }
     // create: never from a turn a trigger or a booked wake started. Under the `nylorun-triggers`
@@ -153,7 +153,8 @@ export async function serveTriggersTool(t, s, request) {
     const agent = await liveEnvironment(t, s.agentId);
     const inForce = triggerLimitsInForce(runtime, agent?.applied?.limits);
     if (!existing) {
-        const made = (await t.agentTriggers(s.agentId)).filter((row) => originOf(row) === "agent").length;
+        // One count for every trigger not from the definition: the tool's and the API's (D88).
+        const made = (await t.agentTriggers(s.agentId)).filter((row) => originOf(row) === "agent" || originOf(row) === "api").length;
         if (made >= inForce.count)
             return failed("tool.limit", `This Agent has ${made} triggers, the most it can have. Delete one to add another.`);
     }
@@ -176,6 +177,7 @@ export async function serveTriggersTool(t, s, request) {
         note: null,
         effectId: request.effectId,
         origin: "agent",
+        principal: null,
         title: input.title ?? null,
         definition,
         createdSessionId: s.id,
@@ -187,6 +189,7 @@ export async function serveTriggersTool(t, s, request) {
     await t.agentEvent(s.agentId, existing ? "agent.trigger_updated" : "agent.trigger_created", {
         triggerId: input.id,
         kind: definition.schedule === undefined ? "at" : "schedule",
+        origin: "agent",
         sessionId: s.id,
         session,
         ...(row.title === null ? {} : { title: row.title }),

package/dist/tenant/api-triggers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Triggers a client puts on one Agent (D88): `PUT /v1/agents/{agentId}/triggers/{triggerId}` with
+ * a `Trigger`, exactly as a definition's `runtime.triggers` entry holds it, and an optional title.
+ *
+ * - **Origin `api`.** The row keeps its own definition, like an agent-made trigger (D83), and the
+ *   principal that put it. Upgrades and moves never touch it (`mergeAgentTriggers` merges
+ *   `manifest` rows only); `DELETE` removes it; pause, resume, run and a webhook's secret work as
+ *   for any trigger; it fires through `fireTimer` and `deliverRun` like every other.
+ * - **Create or replace.** A new id makes it active with its next time. The same id replaces it:
+ *   `generation` goes up and the next time is worked out again, so the timer armed for the old
+ *   time does nothing. A paused one stays paused; an `at` that ran is active again at its new time.
+ * - **The same body again changes nothing** and records no event, so a client may put its desired
+ *   state as often as it likes.
+ * - **Conflicts.** An id the definition declares, or a row of another origin holds, is
+ *   `409 trigger_conflict`: the API never replaces a trigger it didn't put.
+ * - **Checks and limits.** Those a definition save runs (`triggerIssues`), against the limits in
+ *   force; `count` covers the Agent's `agent` and `api` triggers together (`422 trigger_limit`).
+ * - **Events.** `agent.trigger_created` or `agent.trigger_updated` (with `changed`) on the Agent.
+ *
+ * One transaction with the Agent locked; the timer is armed after the commit.
+ */
+import { type Trigger, type TriggerPut, type TriggerView } from "@nylorun/core/contracts";
+import type { TenantContext } from "./context.js";
+/** The `Trigger` part of a put body, with only the fields it has. */
+export declare function definitionOfPut(body: TriggerPut): Trigger;
+/** The definition fields that differ between `before` and `after`, and `title` when it changed. */
+export declare function changedFields(before: Trigger, after: Trigger, titleBefore: string | null, titleAfter: string | null): string[];
+/**
+ * `PUT /v1/agents/{agentId}/triggers/{triggerId}` (D88): creates or replaces the Agent's `api`
+ * trigger `triggerId` and answers it as the list shows it. `principal` is who put it; `origin` is
+ * the URL origin the request reached, for a webhook's URL.
+ */
+export declare function putTrigger(ctx: TenantContext, agentId: string, triggerId: string, body: TriggerPut, principal: string | undefined, origin?: string): Promise<TriggerView>;

package/dist/tenant/api-triggers.js

@@ -0,0 +1,140 @@
+/**
+ * Triggers a client puts on one Agent (D88): `PUT /v1/agents/{agentId}/triggers/{triggerId}` with
+ * a `Trigger`, exactly as a definition's `runtime.triggers` entry holds it, and an optional title.
+ *
+ * - **Origin `api`.** The row keeps its own definition, like an agent-made trigger (D83), and the
+ *   principal that put it. Upgrades and moves never touch it (`mergeAgentTriggers` merges
+ *   `manifest` rows only); `DELETE` removes it; pause, resume, run and a webhook's secret work as
+ *   for any trigger; it fires through `fireTimer` and `deliverRun` like every other.
+ * - **Create or replace.** A new id makes it active with its next time. The same id replaces it:
+ *   `generation` goes up and the next time is worked out again, so the timer armed for the old
+ *   time does nothing. A paused one stays paused; an `at` that ran is active again at its new time.
+ * - **The same body again changes nothing** and records no event, so a client may put its desired
+ *   state as often as it likes.
+ * - **Conflicts.** An id the definition declares, or a row of another origin holds, is
+ *   `409 trigger_conflict`: the API never replaces a trigger it didn't put.
+ * - **Checks and limits.** Those a definition save runs (`triggerIssues`), against the limits in
+ *   force; `count` covers the Agent's `agent` and `api` triggers together (`422 trigger_limit`).
+ * - **Events.** `agent.trigger_created` or `agent.trigger_updated` (with `changed`) on the Agent.
+ *
+ * One transaction with the Agent locked; the timer is armed after the commit.
+ */
+import { triggerKindOf } from "@nylorun/core/contracts";
+import { liveEnvironment } from "./agents.js";
+import { fail } from "./http.js";
+import { triggerLimitsInForce } from "./limits.js";
+import { readRuntimeLimits } from "./runtime-limits.js";
+import { armTrigger, newEndpointId, nextFireAt, originOf, triggerIssues, triggersOf, triggerView } from "./triggers.js";
+/** The definition fields a put compares, in a fixed order. */
+const DEFINITION_FIELDS = ["schedule", "timezone", "at", "webhook", "session", "prompt"];
+/** The `Trigger` part of a put body, with only the fields it has. */
+export function definitionOfPut(body) {
+    const definition = {};
+    for (const field of DEFINITION_FIELDS)
+        if (body[field] !== undefined)
+            definition[field] = body[field];
+    return definition;
+}
+/** The definition fields that differ between `before` and `after`, and `title` when it changed. */
+export function changedFields(before, after, titleBefore, titleAfter) {
+    const changed = DEFINITION_FIELDS.filter((field) => before[field] !== after[field]);
+    if (titleBefore !== titleAfter)
+        changed.push("title");
+    return changed;
+}
+/** The event payload's timing and session for `trigger`. */
+function timingOf(trigger) {
+    return {
+        session: trigger.session,
+        ...(trigger.schedule === undefined ? {} : { schedule: trigger.schedule, timezone: trigger.timezone ?? "UTC" }),
+        ...(trigger.at === undefined ? {} : { at: trigger.at }),
+    };
+}
+/**
+ * `PUT /v1/agents/{agentId}/triggers/{triggerId}` (D88): creates or replaces the Agent's `api`
+ * trigger `triggerId` and answers it as the list shows it. `principal` is who put it; `origin` is
+ * the URL origin the request reached, for a webhook's URL.
+ */
+export async function putTrigger(ctx, agentId, triggerId, body, principal, origin = "") {
+    const definition = definitionOfPut(body);
+    const title = body.title ?? null;
+    const { row, changed } = await ctx.store.tx(async (t) => {
+        const agent = (await liveEnvironment(t, agentId, { lock: true })) ?? fail(404, `Agent ${agentId} not found`, { code: "not_found" });
+        const existing = await t.agentTrigger(agentId, triggerId, { lock: true });
+        const declared = await triggersOf(t, agent);
+        const held = existing ? originOf(existing) : declared[triggerId] !== undefined ? "manifest" : undefined;
+        if (held !== undefined && held !== "api")
+            fail(409, held === "manifest"
+                ? `Trigger ${triggerId} comes from the Agent's definition: put your trigger under another id.`
+                : held === "agent"
+                    ? `Trigger ${triggerId} was made by one of the Agent's agents: put your trigger under another id.`
+                    : `${triggerId} is a session's booked wake: put your trigger under another id.`, { code: "trigger_conflict", details: { origin: held } });
+        const before = existing?.definition;
+        if (existing && before) {
+            const fields = changedFields(before, definition, existing.title, title);
+            // The same body again: nothing changes and nothing is recorded.
+            if (fields.length === 0)
+                return { row: existing, changed: undefined };
+        }
+        const now = new Date();
+        const stamp = now.toISOString();
+        const runtime = await readRuntimeLimits(t);
+        const inForce = triggerLimitsInForce(runtime, agent.applied?.limits);
+        if (!existing) {
+            // One count for every trigger not from the definition: the tool's and the API's.
+            const made = (await t.agentTriggers(agentId)).filter((other) => originOf(other) === "agent" || originOf(other) === "api").length;
+            if (made >= inForce.count)
+                fail(422, `Agent ${agentId} has ${made} triggers its agents or clients made, the most it can have (limits.triggers.count ${inForce.count}). Delete one to add another.`, {
+                    code: "trigger_limit",
+                    details: { limit: "triggers.count", max: inForce.count },
+                });
+        }
+        const issues = triggerIssues({ [triggerId]: definition }, { ...runtime, triggersPerAgent: inForce.count, triggerMinIntervalMs: inForce.minIntervalMs }, now, (id) => `trigger ${id}`);
+        if (issues.length > 0)
+            fail(400, issues.join(" "), { code: "invalid_request", details: { issues } });
+        const paused = existing?.status === "paused";
+        const next = paused ? null : nextFireAt(agentId, triggerId, definition, now, runtime);
+        const kind = triggerKindOf(definition);
+        const row = {
+            agentId,
+            triggerId,
+            kind,
+            // A webhook has no next time and stays active; an `at` with none has run.
+            status: paused ? "paused" : kind === "at" && next === null ? "completed" : "active",
+            pausedReason: paused ? existing.pausedReason : null,
+            generation: (existing?.generation ?? -1) + 1,
+            nextFireAt: next?.toISOString() ?? null,
+            lastFireAt: existing?.lastFireAt ?? null,
+            // A webhook keeps its endpoint and secret across replaces; another kind has none.
+            endpointId: kind === "webhook" ? (existing?.endpointId ?? newEndpointId()) : null,
+            sealedSecret: kind === "webhook" ? (existing?.sealedSecret ?? null) : null,
+            sessionId: null,
+            note: null,
+            effectId: null,
+            origin: "api",
+            principal: principal ?? existing?.principal ?? null,
+            title,
+            definition,
+            createdSessionId: null,
+            createdTurnId: null,
+            createdAt: existing?.createdAt ?? stamp,
+            updatedAt: stamp,
+        };
+        await t.putAgentTrigger(row);
+        const fields = existing && before ? changedFields(before, definition, existing.title, title) : undefined;
+        await t.agentEvent(agentId, existing ? "agent.trigger_updated" : "agent.trigger_created", {
+            triggerId,
+            kind,
+            origin: "api",
+            ...(row.principal === null ? {} : { principal: row.principal }),
+            ...timingOf(definition),
+            ...(title === null ? {} : { title }),
+            ...(fields === undefined ? {} : { changed: fields }),
+            nextRunAt: row.status === "active" ? row.nextFireAt : null,
+        });
+        return { row, changed: true };
+    });
+    if (changed)
+        await armTrigger(ctx, row);
+    return triggerView(row, definition, origin);
+}

package/dist/tenant/triggers.d.ts

@@ -36,6 +36,8 @@ export declare function nextFireAt(agentId: string, triggerId: string, trigger:
 export declare function triggerIssues(triggers: Readonly<Record<string, Trigger>> | undefined, limits: RuntimeLimits, now?: Date, 
 /** How an issue names trigger `id`: its place in the manifest by default. */
 label?: (id: string) => string): string[];
+/** The triggers of the manifest version an Agent runs. */
+export declare function triggersOf(t: Tx, agent: Environment): Promise<Record<string, Trigger>>;
 /**
  * The line an agent-made trigger's run starts with under the `nylorun-triggers` plugin (ADR-106):
  * which trigger woke the turn, and that nobody is watching.
@@ -45,7 +47,7 @@ export declare function triggerFrame(triggerId: string, title: string | null | u
 export declare function originOf(row: Pick<AgentTriggerRow, "origin" | "kind">): AgentTriggerRow["origin"];
 /**
  * The definition trigger row `row` fires with (D83): a booked wake's, from its session and note;
- * an agent-made trigger's own, from the row; a manifest trigger's, the entry of the version the
+ * an agent-made or put trigger's own, from the row (D88); a manifest trigger's, the entry of the version the
  * Agent runs (`manifest`, read once by the caller). Undefined when it has none.
  */
 export declare function definitionOf(row: AgentTriggerRow, manifest: Readonly<Record<string, Trigger>>): Trigger | undefined;
@@ -113,9 +115,9 @@ export declare function setTriggerStatus(ctx: TenantContext, agentId: string, tr
     triggers: TriggerView[];
 }>;
 /**
- * `DELETE /v1/agents/{id}/triggers/{triggerId}` (D83): deletes a trigger one of the Agent's agents
- * made (origin `agent`), with `agent.trigger_deleted`. A manifest's is the manifest's to drop
- * (`409 trigger_from_manifest`); its runs stay.
+ * `DELETE /v1/agents/{id}/triggers/{triggerId}` (D83, D88): deletes a trigger one of the Agent's
+ * agents made (origin `agent`) or a client put (origin `api`), with `agent.trigger_deleted`. A
+ * manifest's is the manifest's to drop (`409 trigger_from_manifest`); its runs stay.
  */
 export declare function deleteTrigger(ctx: TenantContext, agentId: string, triggerId: string, principal?: string): Promise<void>;
 /**

package/dist/tenant/triggers.js

@@ -164,7 +164,7 @@ label = (id) => `runtime.triggers.${id}`) {
     return issues;
 }
 /** The triggers of the manifest version an Agent runs. */
-async function triggersOf(t, agent) {
+export async function triggersOf(t, agent) {
     return (await pinnedOf(t, agent)).triggers;
 }
 /** What the manifest version an Agent runs says of triggers: its own, and whether it declares the capability. */
@@ -192,7 +192,7 @@ export function originOf(row) {
 }
 /**
  * The definition trigger row `row` fires with (D83): a booked wake's, from its session and note;
- * an agent-made trigger's own, from the row; a manifest trigger's, the entry of the version the
+ * an agent-made or put trigger's own, from the row (D88); a manifest trigger's, the entry of the version the
  * Agent runs (`manifest`, read once by the caller). Undefined when it has none.
  */
 export function definitionOf(row, manifest) {
@@ -200,13 +200,14 @@ export function definitionOf(row, manifest) {
         case "wake":
             return wakeTriggerOf(row);
         case "agent":
+        case "api":
             return (row.definition ?? undefined);
         default:
             return manifest[row.triggerId];
     }
 }
 /** The columns a row of origin `manifest` or `wake` leaves empty. */
-const NO_AGENT_FIELDS = { title: null, definition: null, createdSessionId: null, createdTurnId: null };
+const NO_AGENT_FIELDS = { title: null, definition: null, createdSessionId: null, createdTurnId: null, principal: null };
 /**
  * Writes the state of a new Agent's triggers (D74): every trigger of the version it is made from
  * starts active, with its next time. Arm them after the commit (`armAgentTriggers`).
@@ -386,8 +387,8 @@ export async function fireTimer(ctx, key) {
         const trigger = definitionOf(row, pinned.triggers);
         if (!trigger) {
             // A manifest's that the version no longer has, or a wake with nothing to say. An agent's
-            // row always holds its definition.
-            if (origin !== "agent")
+            // or a put row always holds its definition.
+            if (origin !== "agent" && origin !== "api")
                 await t.deleteAgentTrigger(agentId, triggerId);
             return undefined;
         }
@@ -593,6 +594,7 @@ export function triggerView(row, trigger, origin = "") {
         origin: from,
         title: row.title,
         createdSessionId: row.createdSessionId,
+        principal: row.principal,
         status: row.status,
         pausedReason: row.pausedReason,
         ...(trigger.schedule === undefined ? {} : { schedule: trigger.schedule, timezone: trigger.timezone ?? "UTC" }),
@@ -652,7 +654,11 @@ export async function setTriggerStatus(ctx, agentId, triggerId, action, origin =
         const next = nextFireAt(agentId, triggerId, trigger, now, await readRuntimeLimits(t));
         // An `at` runs once: one that ran, or whose time passed, does not run again.
         if (trigger.at !== undefined && (next === null || row.status === "completed"))
-            fail(409, `Trigger ${triggerId} was due at ${trigger.at} and does not run again: ${originOf(row) === "agent" ? "the agent creates it again with a new time" : "save a manifest version with a new time"}.`, { code: "trigger_expired" });
+            fail(409, `Trigger ${triggerId} was due at ${trigger.at} and does not run again: ${originOf(row) === "agent"
+                ? "the agent creates it again with a new time"
+                : originOf(row) === "api"
+                    ? "put it again with a new time"
+                    : "save a manifest version with a new time"}.`, { code: "trigger_expired" });
         const updated = {
             ...row,
             status: "active",
@@ -670,19 +676,24 @@ export async function setTriggerStatus(ctx, agentId, triggerId, action, origin =
     return listTriggers(ctx, agentId, origin);
 }
 /**
- * `DELETE /v1/agents/{id}/triggers/{triggerId}` (D83): deletes a trigger one of the Agent's agents
- * made (origin `agent`), with `agent.trigger_deleted`. A manifest's is the manifest's to drop
- * (`409 trigger_from_manifest`); its runs stay.
+ * `DELETE /v1/agents/{id}/triggers/{triggerId}` (D83, D88): deletes a trigger one of the Agent's
+ * agents made (origin `agent`) or a client put (origin `api`), with `agent.trigger_deleted`. A
+ * manifest's is the manifest's to drop (`409 trigger_from_manifest`); its runs stay.
  */
 export async function deleteTrigger(ctx, agentId, triggerId, principal) {
     await ctx.store.tx(async (t) => {
         const { row } = await lockedTrigger(t, agentId, triggerId);
-        if (originOf(row) !== "agent")
+        const origin = originOf(row);
+        if (origin !== "agent" && origin !== "api")
             fail(409, `Trigger ${triggerId} is declared by the Agent's manifest: save a version without it, or pause it.`, {
                 code: "trigger_from_manifest",
             });
         await t.deleteAgentTrigger(agentId, triggerId);
-        await t.agentEvent(agentId, "agent.trigger_deleted", { triggerId, ...(principal === undefined ? {} : { principal }) });
+        await t.agentEvent(agentId, "agent.trigger_deleted", {
+            triggerId,
+            origin: origin,
+            ...(principal === undefined ? {} : { principal }),
+        });
     });
 }
 /**

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.51.2-beta";
+export declare const RUNTIME_VERSION = "0.52.0-beta";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in step with package.json by runtime/server/scripts/check-package.mjs, which runs in npm run check.
 // release:prepare also rewrites this when it bumps @nylorun/runtime.
-export const RUNTIME_VERSION = "0.51.2-beta";
+export const RUNTIME_VERSION = "0.52.0-beta";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.51.2-beta",
+  "version": "0.52.0-beta",
   "description": "Nylorun Runtime: the agent execution Host on Postgres, Restate and S2, and model providers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -65,8 +65,8 @@
     "@hono/node-server": "^2.1.8",
     "@hono/zod-openapi": "^1.6.3",
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "@nylorun/core": "0.44.0-beta",
-    "@nylorun/harness": "0.36.4-beta",
+    "@nylorun/core": "0.45.0-beta",
+    "@nylorun/harness": "0.36.5-beta",
     "@restatedev/restate-sdk": "1.18.3",
     "@restatedev/restate-sdk-clients": "1.18.3",
     "@s2-dev/streamstore": "0.30.0",