@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/tenant/triggers.d.ts

@@ -0,0 +1,143 @@
+import { Cron } from "croner";
+import { type RuntimeLimits, type Trigger, type TriggerRun, type TriggerView } from "@nylorun/core/contracts";
+import type { AgentTriggerRow, Environment, TriggerRunRow, Tx } from "../store/types.js";
+import type { Session, TenantContext } from "./context.js";
+/** The durable timer key of an Agent's trigger. Agent ids hold no `:`. */
+export declare const triggerTimerKey: (agentId: string, triggerId: string) => string;
+/** A webhook trigger's endpoint id: `wh_` and 128 random bits, kept across moves (D75). */
+export declare const newEndpointId: () => string;
+/** A webhook endpoint's path, under the Runtime API's origin. */
+export declare const webhookPath: (endpointId: string) => string;
+/** A new run id: increasing with time, so runs list newest first by id. */
+export declare function newRunId(now?: number): string;
+/** A schedule's cron in its time zone (UTC by default); throws on a bad pattern or zone. */
+export declare function cronOf(trigger: Pick<Trigger, "schedule" | "timezone">): Cron;
+/**
+ * The fixed offset of a schedule's runs: from a hash of the Agent and trigger id, at most
+ * `triggerJitterPercent` of its interval and `triggerJitterMaxMs`, so a fleet of hourly Agents
+ * spreads out and none of them drifts.
+ */
+export declare function jitterMs(agentId: string, triggerId: string, intervalMs: number, limits: RuntimeLimits): number;
+/**
+ * When trigger `trigger` of Agent `agentId` fires next after `after`, or `null` when it never
+ * does again (an `at` that passed, a webhook).
+ */
+export declare function nextFireAt(agentId: string, triggerId: string, trigger: Trigger, after: Date, limits: RuntimeLimits): Date | null;
+/**
+ * Why `triggers` cannot be saved (D74): more than `triggersPerAgent`, a cron or time zone croner
+ * refuses, two runs closer than `triggerMinIntervalMs` over the next `triggers.intervalCheckFires`
+ * fires, an `at` that is not in the future, a prompt past `triggerPromptChars`.
+ */
+export declare function triggerIssues(triggers: Readonly<Record<string, Trigger>> | undefined, limits: RuntimeLimits, now?: Date): string[];
+/**
+ * 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`).
+ */
+export declare function createAgentTriggers(t: Tx, agent: Environment, now?: Date): Promise<void>;
+/**
+ * After Agent `agent` (locked) moved from manifest version `from` to the version it now runs (track
+ * T3, D73), in the move's transaction: its triggers merge by id. One the new version adds arrives
+ * paused (`new`), one it drops loses its state (its runs stay), and one whose timing changed gets a
+ * new generation and next time; a changed prompt or session applies at the next fire. The sweep
+ * arms what changed (`reconcileTriggers`).
+ */
+export declare function mergeAgentTriggers(t: Tx, agent: Environment, from: number, now?: Date): Promise<void>;
+/** Arms one trigger's timer for its next time, or the next step of a wait past `TIMER_MAX_MS`. */
+export declare function armTrigger(ctx: TenantContext, row: Pick<AgentTriggerRow, "agentId" | "triggerId" | "status" | "nextFireAt">): Promise<void>;
+/** Arms every active trigger of Agent `agentId`, after the commit that changed them. */
+export declare function armAgentTriggers(ctx: TenantContext, agentId: string): Promise<void>;
+/**
+ * The Tenant sweep's step (see the module comment): every active trigger on the first pass on
+ * this process, overdue ones after; and runs past `triggerRunRetentionMs` are deleted.
+ */
+export declare function reconcileTriggers(ctx: TenantContext, first: boolean): Promise<void>;
+/** `DurableExecution.timer` fired for key `key` (`TenantWorker.fire`). */
+export declare function fireTimer(ctx: TenantContext, key: string): Promise<void>;
+/** What makes a run: its cause's key, when it was due, whether late. */
+interface RunCause {
+    runKey: string;
+    dueAt: string;
+    late: boolean;
+    /** A webhook's delivery: its body, as data under the prompt (D75). */
+    payload?: WebhookPayload;
+}
+/** What a delivery brought, as the model sees it under the prompt. */
+export interface WebhookPayload {
+    readonly body: string;
+    readonly contentType: string | undefined;
+    readonly receivedAt: string;
+}
+/**
+ * Runs trigger `triggerId` of `agent` (locked, with the trigger's row) in `t`: see the module
+ * comment. Returns the run; a cause already run returns that run.
+ */
+export declare function deliverRun(ctx: TenantContext, t: Tx, agent: Environment, triggerId: string, trigger: Trigger, row: Pick<AgentTriggerRow, "kind">, cause: RunCause): Promise<TriggerRunRow>;
+/** A run as the API shows it. */
+export declare function runView(row: TriggerRunRow): TriggerRun;
+/** `GET /v1/agents/{id}/triggers`. */
+export declare function listTriggers(ctx: TenantContext, agentId: string, origin?: string): Promise<{
+    triggers: TriggerView[];
+}>;
+/** `POST .../triggers/{triggerId}/pause` and `/resume`. */
+export declare function setTriggerStatus(ctx: TenantContext, agentId: string, triggerId: string, action: "pause" | "resume", origin?: string): Promise<{
+    triggers: TriggerView[];
+}>;
+/**
+ * `POST .../triggers/{triggerId}/run`: runs it now, whatever its status, keyed by the request's
+ * `Idempotency-Key`, so a retried request makes one run.
+ */
+export declare function runTriggerNow(ctx: TenantContext, agentId: string, triggerId: string, idempotencyKey: string): Promise<TriggerRun>;
+/** `GET /v1/agents/{id}/runs`: newest first, `limit` per page, after cursor `before`. */
+export declare function listRuns(ctx: TenantContext, agentId: string, options: {
+    triggerId?: string;
+    cursor?: string;
+    limit: number;
+}): Promise<{
+    runs: TriggerRun[];
+    nextCursor: string | null;
+}>;
+/**
+ * `POST .../triggers/{triggerId}/secret`: a new signing secret for a webhook trigger, made and
+ * sealed in the keys service, shown this once. The one before stops working at once.
+ */
+export declare function rotateWebhookSecret(ctx: TenantContext, agentId: string, triggerId: string, origin: string): Promise<{
+    triggerId: string;
+    webhookUrl: string;
+    secret: string;
+}>;
+/** A delivery to a webhook endpoint, as it arrived. */
+export interface InboundDelivery {
+    readonly id: string | undefined;
+    readonly timestamp: string | undefined;
+    readonly signature: string | undefined;
+    readonly contentType: string | undefined;
+    readonly body: Buffer;
+}
+/**
+ * `POST /v1/webhooks/{endpointId}` (D75), after the route read the body within
+ * `webhookBodyBytes`: Standard Webhooks headers present, the timestamp within the Host's
+ * `triggers.webhookToleranceMs`, and a signature the keys service verifies with the sealed secret,
+ * or `401` and nothing is written. A paused trigger answers `409 trigger_paused` only after that,
+ * so an unsigned probe learns nothing about it. Then the run, keyed by the delivery id: a sender's
+ * retry answers the first run.
+ */
+export declare function receiveWebhook(ctx: TenantContext, endpointId: string, delivery: InboundDelivery): Promise<{
+    runId: string;
+    status: TriggerRun["status"];
+    reason: string | null;
+}>;
+/** The id of session `sessionId`'s booked wake among its Agent's triggers: one per session. */
+export declare const wakeIdOf: (sessionId: string) => string;
+/**
+ * `schedule_wake` (D77), served by the record in the call's transaction (a `runtime` effect): on
+ * session `s` (locked), when the version it runs sets `runtime.selfWake`. `{in | at, note}` books
+ * its next turn, replacing a booking before, at least `triggerMinIntervalMs` and at most
+ * `wakeMaxAheadMs` ahead, the note at most `wakeNoteChars`; `{cancel: true}` removes the booking.
+ * The booking is the session's Agent's trigger `wake:<sessionId>`, armed by the sweep's next pass.
+ */
+export declare function serveRuntimeTool(t: Tx, s: Session, request: {
+    effectId: string;
+    input?: unknown;
+    target?: unknown;
+}): Promise<unknown>;
+export {};