@nylorun/runtime 0.40.0-beta → 0.42.0-beta

package/dist/tenant/agent-triggers.js

@@ -0,0 +1,196 @@
+/**
+ * The `triggers` tool (D83): an agent whose version declares `harness.engine.triggers` lists,
+ * creates and deletes its own triggers. The Runtime serves each call as a `runtime` effect
+ * (operation `triggers`), in the call's own transaction, keyed by the effect id, so a replayed turn
+ * changes nothing twice (`harness-api/record.ts`). The Tenant's tool policy decides it first (a
+ * rule of `kind: "runtime"`, `tool: "triggers"`), so an `ask` rule can hold a create for a person.
+ *
+ * A trigger an agent makes is a row of `agent_triggers` with origin `agent`: its definition (a
+ * `Trigger`, as a manifest entry holds it) and title on the row, with the session and turn that
+ * made it. It fires through `fireTimer` and `deliverRun` like a manifest's (`triggers.ts`), and an
+ * upgrade never touches it.
+ *
+ * - **Where it runs.** `session: "this"` runs it in the calling session (a follow-up); `"own"` in
+ *   a session named from the calling one, `<session>_t_<id>`, opened at its first run and kept.
+ * - **Scope.** A session lists and deletes the triggers made from it, and a trigger's own session
+ *   may list and delete it too. Creating with an id the session's trigger has replaces it; an id
+ *   another session's trigger, a manifest's or a wake holds is `tool.conflict`.
+ * - **Runs can't multiply.** A turn a trigger or a booked wake started may list and delete, never
+ *   create.
+ * - **Checks.** Every create runs the checks a manifest save runs (`triggerIssues`): cron and
+ *   zone, the minimum interval, `at` in the future, the prompt's length; and the count of the
+ *   Agent's agent-made triggers. Each against the limits in force: the manifest's
+ *   `runtime.limits.triggers` within the Tenant's (`triggerLimitsInForce`).
+ * - **Arming.** No I/O in the transaction: the call returns the rows to arm, which the record arms
+ *   after its commit; the sweep's reconcile arms any it missed.
+ */
+import { TriggerSchema, TriggerToolInputSchema, triggerKindOf, } from "@nylorun/core/contracts";
+import { liveEnvironment } from "./agents.js";
+import { triggerLimitsInForce } from "./limits.js";
+import { readRuntimeLimits } from "./runtime-limits.js";
+import { nextFireAt, originOf, triggerIssues } from "./triggers.js";
+const DELAY_UNITS = { m: 60_000, h: 3_600_000, d: 86_400_000 };
+const failed = (code, message) => ({ outcome: { kind: "failed", code, message }, arm: [] });
+const completed = (output, arm = []) => ({
+    outcome: { kind: "completed", output },
+    arm,
+});
+/** The session an agent-made trigger runs in: the calling one, or its own, `<session>_t_<id>`. */
+export function triggerSessionOf(callingSessionId, id, session) {
+    return session === "this" ? callingSessionId : `${callingSessionId}_t_${id}`;
+}
+/** Whether session `sessionId` may see and delete agent-made trigger `row`: it made it, or the trigger runs there. */
+function reaches(row, sessionId) {
+    if (originOf(row) !== "agent")
+        return false;
+    return row.createdSessionId === sessionId || row.definition?.session === sessionId;
+}
+/** Whether the version session `s` runs declares the Runtime's `nylorun-triggers` plugin (ADR-106). */
+async function declaresTriggersPlugin(t, s) {
+    if (!s.definition)
+        return false;
+    const body = (await t.agentManifest(s.definition.name, s.definition.version))?.body;
+    const plugins = body?.harness?.engine?.plugins;
+    return Array.isArray(plugins) && plugins.some((plugin) => plugin?.name === "nylorun-triggers");
+}
+/** Whether the version session `s` runs declares `harness.engine.triggers`. */
+async function declaresTriggers(t, s) {
+    if (!s.definition)
+        return false;
+    const body = (await t.agentManifest(s.definition.name, s.definition.version))?.body;
+    return body?.harness?.engine?.triggers === true;
+}
+/**
+ * Why session `s` cannot make `triggers` call `request` at all, before the Tenant's tool policy
+ * is asked (off means off, ADR-100): its version does not declare `engine.triggers`
+ * (`tool.unavailable`), or an agent used as a tool made it (`tool.forbidden`). Undefined when it can.
+ */
+export async function triggersRefusal(t, s, request) {
+    if (!(await declaresTriggers(t, s)))
+        return { kind: "failed", code: "tool.unavailable", message: "This session's agent does not set up triggers (engine.triggers)." };
+    if (request.agent !== undefined)
+        return {
+            kind: "failed",
+            code: "tool.forbidden",
+            message: "Triggers are the root agent's: an agent used as a tool can't list, create or delete them.",
+        };
+    return undefined;
+}
+/**
+ * Serves one `triggers` call of session `s`'s active turn in `t` (see the module comment). The
+ * call's `agent` is the agent used as a tool that made it, absent for the root agent.
+ */
+export async function serveTriggersTool(t, s, request) {
+    const refused = await triggersRefusal(t, s, request);
+    if (refused)
+        return { outcome: refused, arm: [] };
+    const parsed = TriggerToolInputSchema.safeParse(request.input);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const at = issue?.path.length ? `${issue.path.join(".")}: ` : "";
+        return failed("tool.invalid-input", `${at}${issue?.message ?? "Not a triggers call"}`);
+    }
+    const input = parsed.data;
+    if (input.command === "list") {
+        const rows = (await t.agentTriggers(s.agentId)).filter((row) => reaches(row, s.id));
+        return completed({
+            now: new Date().toISOString(),
+            triggers: rows.map((row) => {
+                const trigger = row.definition;
+                return {
+                    id: row.triggerId,
+                    title: row.title,
+                    status: row.status,
+                    ...(trigger.schedule === undefined ? {} : { schedule: trigger.schedule, timezone: trigger.timezone ?? "UTC" }),
+                    ...(trigger.at === undefined ? {} : { at: trigger.at }),
+                    session: trigger.session,
+                    nextRunAt: row.status === "active" ? row.nextFireAt : null,
+                    prompt: trigger.prompt,
+                };
+            }),
+        });
+    }
+    if (input.command === "delete") {
+        const row = await t.agentTrigger(s.agentId, input.id, { lock: true });
+        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 });
+        return completed({ id: input.id, deleted: true });
+    }
+    // create: never from a turn a trigger or a booked wake started. Under the `nylorun-triggers`
+    // plugin (ADR-106) such a turn may still set a one-off follow-up in its own session, as a woken
+    // turn books the next wake: never a schedule, never a session of its own.
+    if (s.turnCause !== undefined) {
+        const plugin = await declaresTriggersPlugin(t, s);
+        const followUp = plugin && input.schedule === undefined && input.session === "this";
+        if (!followUp)
+            return failed("tool.forbidden", plugin
+                ? "A run can't create triggers other than a one-off follow-up here (in or at, with session: this): this turn was started by a trigger. It may list and delete them."
+                : "A run can't create triggers: this turn was started by a trigger. It may list and delete them.");
+    }
+    const now = new Date();
+    const stamp = now.toISOString();
+    const session = triggerSessionOf(s.id, input.id, input.session);
+    const delay = input.in === undefined ? undefined : /^([1-9][0-9]*)(m|h|d)$/.exec(input.in);
+    const checked = TriggerSchema.safeParse({
+        ...(input.schedule === undefined ? {} : { schedule: input.schedule }),
+        ...(input.timezone === undefined ? {} : { timezone: input.timezone }),
+        ...(input.at === undefined ? {} : { at: input.at }),
+        ...(delay ? { at: new Date(now.getTime() + Number(delay[1]) * DELAY_UNITS[delay[2]]).toISOString() } : {}),
+        session,
+        prompt: input.prompt,
+    });
+    if (!checked.success)
+        return failed("tool.invalid-input", checked.error.issues[0]?.path[0] === "session"
+            ? `session: own would run it in session ${session}, longer than a trigger's session may be: use a shorter id.`
+            : (checked.error.issues[0]?.message ?? "Not a trigger"));
+    const definition = checked.data;
+    const existing = await t.agentTrigger(s.agentId, input.id, { lock: true });
+    if (existing && (originOf(existing) !== "agent" || existing.createdSessionId !== s.id))
+        return failed("tool.conflict", `The id ${input.id} is taken by another trigger of this Agent: choose another id.`);
+    const runtime = await readRuntimeLimits(t);
+    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;
+        if (made >= inForce.count)
+            return failed("tool.limit", `This Agent has ${made} triggers, the most it can have. Delete one to add another.`);
+    }
+    const issues = triggerIssues({ [input.id]: definition }, { ...runtime, triggersPerAgent: inForce.count, triggerMinIntervalMs: inForce.minIntervalMs }, now, (id) => id);
+    if (issues.length > 0)
+        return failed("tool.invalid-input", issues.join(" "));
+    const next = nextFireAt(s.agentId, input.id, definition, now, runtime);
+    const row = {
+        agentId: s.agentId,
+        triggerId: input.id,
+        kind: triggerKindOf(definition),
+        status: next === null ? "completed" : "active",
+        pausedReason: null,
+        generation: (existing?.generation ?? -1) + 1,
+        nextFireAt: next?.toISOString() ?? null,
+        lastFireAt: existing?.lastFireAt ?? null,
+        endpointId: null,
+        sealedSecret: null,
+        sessionId: session,
+        note: null,
+        effectId: request.effectId,
+        origin: "agent",
+        title: input.title ?? null,
+        definition,
+        createdSessionId: s.id,
+        createdTurnId: s.activeTurnId,
+        createdAt: existing?.createdAt ?? stamp,
+        updatedAt: stamp,
+    };
+    await t.putAgentTrigger(row);
+    await t.agentEvent(s.agentId, existing ? "agent.trigger_updated" : "agent.trigger_created", {
+        triggerId: input.id,
+        kind: definition.schedule === undefined ? "at" : "schedule",
+        sessionId: s.id,
+        session,
+        ...(row.title === null ? {} : { title: row.title }),
+        nextRunAt: row.nextFireAt,
+    });
+    return completed({ id: input.id, status: row.status, nextRunAt: row.nextFireAt, session, now: stamp }, [row]);
+}

package/dist/tenant/agents.d.ts

@@ -196,7 +196,7 @@ export declare function agentEventsOf(ctx: TenantContext, id: string, scope: Aut
         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";
+        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_created" | "agent.trigger_deleted" | "agent.trigger_paused" | "agent.trigger_resumed" | "agent.trigger_secret_rotated" | "agent.trigger_updated" | "agent.version_changed";
         payload: Record<string, unknown>;
     }[];
 }>;

package/dist/tenant/agents.js

@@ -194,7 +194,7 @@ async function viewOf(ctx, t, environment, owner) {
                 : {}),
         },
         runtime: environment.applied,
-        limits: limitsInForce(await readTenantLimits(t), environment.applied.limits),
+        limits: storageView(limitsInForce(await readTenantLimits(t), environment.applied.limits)),
         sessions: visible.map((session) => ({
             id: session.id,
             ownerUserId: session.ownerUserId,
@@ -1273,3 +1273,7 @@ export function sandboxRouteDeps(ctx) {
         session: (id) => ctx.store.tx((t) => sessionOf(t, id)),
     };
 }
+/** The limits an Agent's view shows: its storage's, without its triggers'. */
+function storageView({ triggers: _, ...storage }) {
+    return storage;
+}

package/dist/tenant/limits.d.ts

@@ -1,10 +1,12 @@
 /**
- * What artifacts, skills and disk versions may hold: the Tenant's limits (`artifacts.config`,
- * `skills.config` here, and the Runtime limits `diskVersion*` of `limits.config`), and an
- * Environment's, which its manifest sets (`limits`). A limit the manifest leaves out is the
- * Tenant's as it is when the limit is checked, and none is ever above the Tenant's: a manifest
- * asking for more is refused when the Environment is made, and a Tenant that lowers a limit
- * later lowers it for every Environment.
+ * What artifacts, skills and disk versions may hold, and how many triggers an agent may make and
+ * how often they run (D83): the Tenant's limits (`artifacts.config`, `skills.config` here, and the
+ * Runtime limits `diskVersion*`, `triggersPerAgent`, `triggerMinIntervalMs` and
+ * `triggerRunsPerHour` of `limits.config`), and an Environment's, which its manifest sets
+ * (`limits`). A limit the manifest leaves out is the Tenant's as it is when the limit is checked,
+ * and none is ever looser than the Tenant's (a trigger's minimum interval is never shorter): a
+ * manifest asking for more is refused when the Environment is made, and a Tenant that lowers a
+ * limit later lowers it for every Environment. Lowering a trigger limit deletes nothing.
  *
  * Also the shape a manifest and an Environment's labels must fit, which the Tenant's Runtime
  * limits set (`manifestShapeIssues`, `labelIssues`), checked when they are put rather than by
@@ -21,12 +23,29 @@ export interface DiskLimits {
     readonly versionBytes: number;
     readonly versionEntries: number;
 }
-/** The limits an Environment's artifacts, skills and disk versions are held to. */
+/** How many triggers an Agent's agents may make, and how often its triggers run (D83). */
+export interface TriggerLimits {
+    /** The most triggers its agents may have made (`triggers` tool, origin `agent`). */
+    readonly count: number;
+    /** The shortest gap between two runs of one schedule, and the soonest an `at` or `in` may be. */
+    readonly minIntervalMs: number;
+    /** The most runs its triggers start or queue in any hour. */
+    readonly runsPerHour: number;
+}
+/** The limits an Environment's artifacts, skills and disk versions are held to, and its triggers. */
 export interface StorageLimits {
     readonly artifacts: ArtifactLimits;
     readonly skills: SkillLimits;
     readonly disk: DiskLimits;
+    readonly triggers: TriggerLimits;
 }
+/** The Tenant's trigger limits: its Runtime limits `triggersPerAgent`, `triggerMinIntervalMs`, `triggerRunsPerHour`. */
+export declare function tenantTriggerLimits(runtime: RuntimeLimits): TriggerLimits;
+/**
+ * The trigger limits in force for an Environment whose manifest sets `set` (`limits.triggers`):
+ * the lower count and hourly runs, and the longer minimum interval, of its own and the Tenant's.
+ */
+export declare function triggerLimitsInForce(runtime: RuntimeLimits, set: EnvironmentLimits | undefined): TriggerLimits;
 interface SettingsReader {
     getSetting(key: string): Promise<string | undefined>;
 }

package/dist/tenant/limits.js

@@ -1,10 +1,12 @@
 /**
- * What artifacts, skills and disk versions may hold: the Tenant's limits (`artifacts.config`,
- * `skills.config` here, and the Runtime limits `diskVersion*` of `limits.config`), and an
- * Environment's, which its manifest sets (`limits`). A limit the manifest leaves out is the
- * Tenant's as it is when the limit is checked, and none is ever above the Tenant's: a manifest
- * asking for more is refused when the Environment is made, and a Tenant that lowers a limit
- * later lowers it for every Environment.
+ * What artifacts, skills and disk versions may hold, and how many triggers an agent may make and
+ * how often they run (D83): the Tenant's limits (`artifacts.config`, `skills.config` here, and the
+ * Runtime limits `diskVersion*`, `triggersPerAgent`, `triggerMinIntervalMs` and
+ * `triggerRunsPerHour` of `limits.config`), and an Environment's, which its manifest sets
+ * (`limits`). A limit the manifest leaves out is the Tenant's as it is when the limit is checked,
+ * and none is ever looser than the Tenant's (a trigger's minimum interval is never shorter): a
+ * manifest asking for more is refused when the Environment is made, and a Tenant that lowers a
+ * limit later lowers it for every Environment. Lowering a trigger limit deletes nothing.
  *
  * Also the shape a manifest and an Environment's labels must fit, which the Tenant's Runtime
  * limits set (`manifestShapeIssues`, `labelIssues`), checked when they are put rather than by
@@ -15,6 +17,23 @@ import { parseSandboxDuration } from "@nylorun/core/define";
 import { readArtifactLimits } from "../artifacts/config.js";
 import { readRuntimeLimits } from "./runtime-limits.js";
 export const SKILLS_CONFIG_SETTING = "skills.config";
+/** The Tenant's trigger limits: its Runtime limits `triggersPerAgent`, `triggerMinIntervalMs`, `triggerRunsPerHour`. */
+export function tenantTriggerLimits(runtime) {
+    return { count: runtime.triggersPerAgent, minIntervalMs: runtime.triggerMinIntervalMs, runsPerHour: runtime.triggerRunsPerHour };
+}
+/**
+ * The trigger limits in force for an Environment whose manifest sets `set` (`limits.triggers`):
+ * the lower count and hourly runs, and the longer minimum interval, of its own and the Tenant's.
+ */
+export function triggerLimitsInForce(runtime, set) {
+    const tenant = tenantTriggerLimits(runtime);
+    const asked = set?.triggers;
+    return {
+        count: Math.min(asked?.count ?? tenant.count, tenant.count),
+        minIntervalMs: Math.max(asked?.minIntervalMs ?? tenant.minIntervalMs, tenant.minIntervalMs),
+        runsPerHour: Math.min(asked?.runsPerHour ?? tenant.runsPerHour, tenant.runsPerHour),
+    };
+}
 /** The skill limits in force: the Tenant's, with the default for what it leaves unset. */
 export function effectiveSkillLimits(config) {
     return { totalBytes: config.limits?.totalBytes ?? SKILL_TOTAL_BYTES_DEFAULT };
@@ -39,6 +58,7 @@ export async function readTenantLimits(t) {
         artifacts: await readArtifactLimits(t),
         skills: await readSkillLimits(t),
         disk: { versionBytes: runtime.diskVersionBytes, versionEntries: runtime.diskVersionEntries },
+        triggers: tenantTriggerLimits(runtime),
     };
 }
 /** The limits in force for an Environment whose manifest sets `set`: each within the Tenant's. */
@@ -54,6 +74,11 @@ export function limitsInForce(tenant, set) {
             versionBytes: within(set?.disk?.versionBytes, tenant.disk.versionBytes),
             versionEntries: within(set?.disk?.versionEntries, tenant.disk.versionEntries),
         },
+        triggers: {
+            count: within(set?.triggers?.count, tenant.triggers.count),
+            minIntervalMs: Math.max(set?.triggers?.minIntervalMs ?? tenant.triggers.minIntervalMs, tenant.triggers.minIntervalMs),
+            runsPerHour: within(set?.triggers?.runsPerHour, tenant.triggers.runsPerHour),
+        },
     };
 }
 /** Why a manifest's `limits` cannot be made: each limit above the Tenant's. */
@@ -68,6 +93,14 @@ export function limitIssues(set, tenant) {
     check("skills.totalBytes", set?.skills?.totalBytes, tenant.skills.totalBytes);
     check("disk.versionBytes", set?.disk?.versionBytes, tenant.disk.versionBytes);
     check("disk.versionEntries", set?.disk?.versionEntries, tenant.disk.versionEntries, "entries");
+    // Trigger limits (D83): the Tenant's Runtime limits, set with PUT /v1/tenant/limits.
+    const triggers = set?.triggers;
+    if (triggers?.count !== undefined && triggers.count > tenant.triggers.count)
+        issues.push(`limits.triggers.count asks for ${triggers.count} triggers; this Tenant allows at most ${tenant.triggers.count} (the Runtime limit triggersPerAgent).`);
+    if (triggers?.runsPerHour !== undefined && triggers.runsPerHour > tenant.triggers.runsPerHour)
+        issues.push(`limits.triggers.runsPerHour asks for ${triggers.runsPerHour} runs an hour; this Tenant allows at most ${tenant.triggers.runsPerHour} (the Runtime limit triggerRunsPerHour).`);
+    if (triggers?.minIntervalMs !== undefined && triggers.minIntervalMs < tenant.triggers.minIntervalMs)
+        issues.push(`limits.triggers.minIntervalMs asks for runs ${triggers.minIntervalMs} ms apart; this Tenant allows no less than ${tenant.triggers.minIntervalMs} ms (the Runtime limit triggerMinIntervalMs).`);
     return issues;
 }
 /**

package/dist/tenant/runs-stream.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The Tenant's runs stream (D83): every run of every Agent's triggers, in the `runs` stream of the
+ * Tenant's current basin (Durable Streams, `streams/types.ts`), kept 7 days, and served at
+ * `GET /v1/runs/stream` as server-sent events from a cursor.
+ *
+ * **The outbox.** A run is a `trigger_runs` row, written in its trigger's transaction; nothing is
+ * appended there (no I/O in a transaction). After the commit, the code that made the run appends
+ * it (`appendRuns`) and marks the row (`streamed_at`). A crash between the two leaves the row
+ * unmarked, and the Tenant sweep appends every run still unmarked once it is
+ * `RUNS_STREAM_GRACE_MS` old, oldest first (`streamMissedRuns`), so no run is lost. A run can
+ * therefore arrive twice (appended, then the mark lost); a reader drops a run id it has seen. The
+ * session stream relay is not involved: its replication filter and heads are keyed by session.
+ *
+ * **Basins.** The stream lives in the Tenant's current basin generation: a Tenant reset's new
+ * basin starts it at 0 again. The cursor names the generation, so one from an older basin is
+ * answered `410 cursor_expired`. Without S2 (tests, a local Host) the in-memory streams hold it,
+ * and a restart loses what was unread.
+ *
+ * Nothing inside the Runtime reads it or waits on it (D48): it serves API listeners only.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { TenantRun } from "@nylorun/core/contracts";
+import type { TriggerRunRow } from "../store/types.js";
+import type { TenantContext } from "./context.js";
+/** How old an unmarked run is before the sweep appends it: the code that made it had its chance. */
+export declare const RUNS_STREAM_GRACE_MS = 2000;
+/** A run as the runs stream carries it. */
+export declare function tenantRunOf(row: TriggerRunRow): TenantRun;
+/**
+ * Appends `runs` (made in a transaction that committed) to the Tenant's runs stream, then marks
+ * them. Never throws: a run it cannot append stays unmarked, and the sweep appends it later.
+ */
+export declare function appendRuns(ctx: TenantContext, runs: readonly TriggerRunRow[]): Promise<void>;
+/**
+ * The Tenant sweep's step: appends the runs still unmarked `RUNS_STREAM_GRACE_MS` after they
+ * fired, oldest first, a batch at a time.
+ */
+export declare function streamMissedRuns(ctx: TenantContext): Promise<void>;
+/** The cursor after record `seq` of the runs stream in basin generation `generation`. */
+export declare function runsCursor(generation: number, seq: number): string;
+/**
+ * The first sequence to read for `cursor` in the Tenant's current generation: 0 without one;
+ * `400` for one that is not a runs cursor; `410 cursor_expired` for one from an older basin.
+ */
+export declare function runsStartSeq(cursor: string | undefined, generation: number): number;
+/**
+ * `GET /v1/runs/stream`: the Tenant's runs from the cursor, as `event: run` frames (`id:` the
+ * cursor, `data:` `{cursor, run}`), following the stream until the client leaves, the Tenant moves
+ * to a new basin (the stream ends: resume without a cursor) or it closes.
+ */
+export declare function streamRuns(ctx: TenantContext, request: IncomingMessage, response: ServerResponse, cursor: string | undefined): Promise<void>;

package/dist/tenant/runs-stream.js

@@ -0,0 +1,164 @@
+import { basinOf } from "../streams/basin.js";
+import { RUNS_STREAM, RUNS_STREAM_RETENTION_SECS } from "../streams/types.js";
+import { sleep } from "../retry.js";
+import { hostTuning } from "../tuning.js";
+import { fail } from "./http.js";
+import { openSse, send } from "./session-streams.js";
+/** How old an unmarked run is before the sweep appends it: the code that made it had its chance. */
+export const RUNS_STREAM_GRACE_MS = 2_000;
+/** A run as the runs stream carries it. */
+export function tenantRunOf(row) {
+    return {
+        runId: row.id,
+        agentId: row.agentId,
+        triggerId: row.triggerId,
+        kind: row.kind,
+        status: row.status,
+        reason: row.reason,
+        sessionId: row.sessionId,
+        turnId: row.turnId,
+        queuedMessageId: row.queuedMessageId,
+        dueAt: row.dueAt,
+        firedAt: row.firedAt,
+        late: row.late,
+        origin: row.kind === "wake" ? "wake" : row.origin,
+        title: row.title,
+    };
+}
+/** The basins whose runs stream this process has ensured (its retention set), by streams. */
+const ensured = new WeakMap();
+/**
+ * Appends `runs` (made in a transaction that committed) to the Tenant's runs stream, then marks
+ * them. Never throws: a run it cannot append stays unmarked, and the sweep appends it later.
+ */
+export async function appendRuns(ctx, runs) {
+    const fresh = runs.filter((run) => run.streamedAt === null);
+    if (fresh.length === 0)
+        return;
+    // A Tenant without Durable Streams wired (a test's bare context) appends nothing.
+    const streams = ctx.sessionStreams?.wiring?.streams;
+    if (!streams)
+        return;
+    const basin = basinOf(ctx.config.tenantId, ctx.sessionStreams.generation);
+    try {
+        await ensureRunsStream(streams, basin).catch((error) => 
+        // Not fatal: the stream keeps the basin's default retention, and the next append tries again.
+        ctx.config.logger.warn("runs stream retention not set; appending anyway", {
+            message: error instanceof Error ? error.message : String(error),
+        }));
+        const result = await streams.append(basin, RUNS_STREAM, fresh.map(tenantRunOf));
+        if (result.status !== "ok")
+            return;
+        const at = new Date().toISOString();
+        await ctx.store.tx((t) => t.markTriggerRunsStreamed(fresh.map((run) => run.id), at));
+        for (const run of fresh)
+            run.streamedAt = at;
+    }
+    catch (error) {
+        ctx.config.logger.warn("runs stream append failed; the sweep appends it later", {
+            runs: fresh.length,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/** Sets the runs stream's retention once per basin and process; a failure leaves the basin's default. */
+async function ensureRunsStream(streams, basin) {
+    if (!streams.ensureStream)
+        return;
+    let done = ensured.get(streams);
+    if (!done)
+        ensured.set(streams, (done = new Set()));
+    if (done.has(basin))
+        return;
+    await streams.ensureStream(basin, RUNS_STREAM, { retentionSecs: RUNS_STREAM_RETENTION_SECS });
+    done.add(basin);
+}
+/**
+ * The Tenant sweep's step: appends the runs still unmarked `RUNS_STREAM_GRACE_MS` after they
+ * fired, oldest first, a batch at a time.
+ */
+export async function streamMissedRuns(ctx) {
+    if (!ctx.sessionStreams?.wiring)
+        return;
+    const { batchSize } = hostTuning().sweep;
+    for (let pass = 0; pass < 10; pass++) {
+        const firedBefore = new Date(Date.now() - RUNS_STREAM_GRACE_MS).toISOString();
+        const rows = await ctx.store.tx((t) => t.unstreamedTriggerRuns({ firedBefore, limit: batchSize }));
+        if (rows.length === 0)
+            return;
+        await appendRuns(ctx, rows);
+        // Not marked: the streams failed, and the next pass tries again.
+        if (rows.some((row) => row.streamedAt === null) || rows.length < batchSize)
+            return;
+    }
+}
+// ---------------------------------------------------------------------------
+// GET /v1/runs/stream
+const CURSOR_PREFIX = `${RUNS_STREAM}:`;
+/** The cursor after record `seq` of the runs stream in basin generation `generation`. */
+export function runsCursor(generation, seq) {
+    return Buffer.from(`${CURSOR_PREFIX}${generation}:${seq}`).toString("base64url");
+}
+/**
+ * The first sequence to read for `cursor` in the Tenant's current generation: 0 without one;
+ * `400` for one that is not a runs cursor; `410 cursor_expired` for one from an older basin.
+ */
+export function runsStartSeq(cursor, generation) {
+    if (cursor === undefined || cursor === "")
+        return 0;
+    const text = Buffer.from(cursor, "base64url").toString("utf8");
+    const match = /^runs:(\d+):(\d+)$/.exec(text);
+    if (!match)
+        return fail(400, "cursor is not a cursor of the runs stream", { code: "invalid_cursor" });
+    const from = Number(match[1]);
+    if (from !== generation)
+        return fail(410, "The cursor is from the Tenant's runs stream before its reset: read the stream again without a cursor.", {
+            code: "cursor_expired",
+        });
+    return Number(match[2]) + 1;
+}
+/**
+ * `GET /v1/runs/stream`: the Tenant's runs from the cursor, as `event: run` frames (`id:` the
+ * cursor, `data:` `{cursor, run}`), following the stream until the client leaves, the Tenant moves
+ * to a new basin (the stream ends: resume without a cursor) or it closes.
+ */
+export async function streamRuns(ctx, request, response, cursor) {
+    const streams = ctx.sessionStreams.wiring?.streams ?? fail(503, "The runs stream is unavailable");
+    const generation = ctx.sessionStreams.generation;
+    let next = runsStartSeq(cursor, generation);
+    const basin = basinOf(ctx.config.tenantId, generation);
+    const stop = new AbortController();
+    openSse(request, response, () => stop.abort());
+    void (async () => {
+        const { minMs, maxMs } = hostTuning().streams.retry;
+        let delay = minMs;
+        while (!stop.signal.aborted && ctx.sessionStreams.generation === generation) {
+            try {
+                for await (const record of streams.read(basin, RUNS_STREAM, next, { signal: stop.signal })) {
+                    if (stop.signal.aborted)
+                        return;
+                    if (record.seq < next)
+                        continue;
+                    next = record.seq + 1;
+                    delay = minMs;
+                    const at = runsCursor(generation, record.seq);
+                    send(response, `id: ${at}\nevent: run\ndata: ${JSON.stringify({ cursor: at, run: record.body })}\n\n`);
+                }
+                if (stop.signal.aborted)
+                    return;
+                break;
+            }
+            catch (error) {
+                if (stop.signal.aborted)
+                    return;
+                ctx.config.logger.warn("runs stream read failed; retrying", {
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            await sleep(delay, stop.signal);
+            delay = Math.min(delay * 2, maxMs);
+        }
+        if (!response.writableEnded)
+            response.end();
+    })();
+}

package/dist/tenant/sweep.js

@@ -52,6 +52,7 @@
  */
 import { sweepUnusedAgents } from "./agents.js";
 import { reconcileTriggers } from "./triggers.js";
+import { streamMissedRuns } from "./runs-stream.js";
 import { sweepPendingSeeds } from "../artifacts/disk.js";
 import { pendingAgentEffects, reconcilePendingAgentEffect, } from "../core/flow-host.js";
 import { hostTuning } from "../tuning.js";
@@ -129,6 +130,8 @@ export async function sweep(ctx) {
         // Triggers (track T4): every active one armed on this process's first pass, overdue ones after;
         // runs past their retention deleted.
         ["triggers", () => reconcileTriggers(ctx, first)],
+        // The Tenant runs stream's outbox (D83): runs not appended after their commit.
+        ["runs-stream", () => streamMissedRuns(ctx)],
         // Seeds of new volumes whose engine is connected and no process copies (R2d step 3).
         ["seeds", () => sweepPendingSeeds(ctx)],
         // A harness elsewhere closes its own idle MCP connections.