feat(daemon): interval-scheduler formula (endoclaw-timer Phase 1 remainder)

Graduate the @endo/genie interval-scheduler prototype
(packages/genie/src/interval/) into @endo/daemon as a first-class
`interval-scheduler` formula, so an agent can hold a scheduled-interval
(heartbeat) capability. This is the "Phase 1 remainder" of the
endoclaw-timer design: formula type, extractDeps edge, and maker-table
entry.

- src/interval-scheduler.js: SES-safe port of the genie scheduler. Uses
  the daemon's filePowers (write-then-rename) for per-interval
  persistence instead of node:fs, an injected id generator instead of
  node:crypto, and injectable setTimeout/clearTimeout/now so the logic is
  testable against a deterministic clock. Start-to-start scheduling,
  resolve/reschedule with exponential backoff, tick-timeout auto-resolve,
  host limits (maxActive/minPeriodMs), pause/resume/revoke, and startup
  recovery with missed-tick coalescing all carry over.
- formula-type.js / types.d.ts: register the `interval-scheduler` type,
  its formula record ({ agent, maxActive, minPeriodMs, paused }), and the
  scheduler powers/facet/entry typedefs.
- daemon.js: extractLabeledDeps case (strong `agent` GC edge), the
  maker-table entry (per-formula persistence dir keyed by formula number,
  context.thisDiesIfThatDies(agent) + onCancel disarm), and
  formulateIntervalScheduler.
- host.js / interfaces.js: a lean `makeIntervalScheduler(petName, opts?)`
  host command + HostInterface guard so an agent can obtain and hold the
  capability end-to-end.

Tick delivery as daemon mail messages (with a TickResponse exo), the
scheduler's own handle, the proper IntervalScheduler/IntervalControl
facet split on the host method, and CLI commands remain later phases
(Phase 2 / Phase 4) of the design.

Tests: packages/daemon/test/interval-scheduler.test.js (7 cases:
create/persist/list/tick, limits, cancel, pause/resume, revoke, startup
recovery) plus the formula-type registry list. tsc + eslint clean.

Design: journal plan/designs/endo-but-for-bots/endoclaw-timer.md

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: endolinbot

packages/daemon/src/daemon.js

@@ -82,6 +82,11 @@ import {
   readableTreeHelp,
 } from './help-text.js';
 import { getMountBacking, lineageOf, makeMount } from './mount.js';
+import {
+  makeIntervalScheduler,
+  DEFAULT_MAX_ACTIVE,
+  DEFAULT_MIN_PERIOD_MS,
+} from './interval-scheduler.js';
 
 // Sorted:
 import {
@@ -801,6 +806,11 @@ const makeDaemonCore = async (
           ['hostAgent', formula.hostAgent],
           ['hostHandle', formula.hostHandle],
         ];
+      case 'interval-scheduler':
+        // Strong edge: the scheduler (and all its persisted intervals) is
+        // collected when its owning agent is. Phase 2 adds the scheduler's
+        // own `handle` here once ticks are delivered by mail.
+        return [['agent', formula.agent]];
       default:
         return [];
     }
@@ -3905,6 +3915,53 @@ const makeDaemonCore = async (
           `Timer "${timerLabel || 'timer'}" firing every ${interval}ms. Ticks: ${tickCount}`,
       });
     },
+    'interval-scheduler': async (formula, context, _id, formulaNumber) => {
+      const {
+        agent: agentId,
+        maxActive,
+        minPeriodMs,
+        paused,
+      } = formula;
+      // One directory per scheduler instance (keyed by formula number),
+      // holding one JSON file per interval — mirroring the pet-store
+      // persistence pattern (endoclaw-timer design § Persistence).
+      const persistDir = filePowers.joinPath(
+        persistencePowers.statePath,
+        'interval-scheduler',
+        /** @type {string} */ (formulaNumber),
+        'intervals',
+      );
+      const { scheduler, schedulerControl, disarmAll } =
+        await makeIntervalScheduler({
+          filePowers,
+          persistDir,
+          // A short, unguessable id per interval entry.
+          makeId: async () => (await randomHex256()).slice(0, 16),
+          maxActive,
+          minPeriodMs,
+          paused,
+        });
+      // Die with the owning agent, and clear all timers on cancellation so
+      // no orphan interval keeps ticking after GC.
+      context.thisDiesIfThatDies(agentId);
+      context.onCancel(() => disarmAll());
+      // Phase 1 returns a single capability exposing both the agent-facing
+      // scheduler methods and the host-facing control methods. Phase 4 splits
+      // these into the `IntervalScheduler` / `IntervalControl` facet pair the
+      // host method returns.
+      return Far('IntervalScheduler', {
+        makeInterval: (label, periodMs, opts) =>
+          scheduler.makeInterval(label, periodMs, opts),
+        list: () => scheduler.list(),
+        help: () => scheduler.help(),
+        setMaxActive: n => schedulerControl.setMaxActive(n),
+        setMinPeriodMs: ms => schedulerControl.setMinPeriodMs(ms),
+        pause: () => schedulerControl.pause(),
+        resume: () => schedulerControl.resume(),
+        revoke: () => schedulerControl.revoke(),
+        listAll: () => schedulerControl.listAll(),
+      });
+    },
     channel: async (formula, context, id) => {
       const {
         handle: handleId,
@@ -4512,6 +4569,46 @@ const makeDaemonCore = async (
     });
   };
 
+  /**
+   * Formulate an `interval-scheduler` bound to an agent, with host-set limits.
+   *
+   * @param {FormulaIdentifier} agentId - the agent the scheduler is bound to.
+   * @param {{ maxActive?: number, minPeriodMs?: number } | undefined} options
+   * @param {import('./types.js').DeferredTasks<import('./types.js').IntervalSchedulerDeferredTaskParams>} deferredTasks
+   */
+  const formulateIntervalScheduler = async (
+    agentId,
+    options,
+    deferredTasks,
+  ) => {
+    const {
+      maxActive = DEFAULT_MAX_ACTIVE,
+      minPeriodMs = DEFAULT_MIN_PERIOD_MS,
+    } = options ?? {};
+    return withFormulaGraphLock(async () => {
+      const intervalSchedulerNumber = /** @type {FormulaNumber} */ (
+        await randomHex256()
+      );
+      const intervalSchedulerId = formatId({
+        number: intervalSchedulerNumber,
+        node: localNodeNumber,
+      });
+
+      await deferredTasks.execute({ intervalSchedulerId });
+
+      /** @type {import('./types.js').IntervalSchedulerFormula} */
+      const formula = harden({
+        type: /** @type {const} */ ('interval-scheduler'),
+        agent: agentId,
+        maxActive,
+        minPeriodMs,
+        paused: false,
+      });
+
+      return formulate(intervalSchedulerNumber, formula);
+    });
+  };
+
   /**
    * Unlike other formulate functions, formulateNumberedHandle *only* writes a
    * formula to the formula graph and does not attempt to incarnate it.
@@ -6519,6 +6616,7 @@ const makeDaemonCore = async (
     getFormulaForId,
     formulateChannel,
     formulateTimer,
+    formulateIntervalScheduler,
     makeMailbox,
     makeDirectoryNode,
     localNodeNumber,

packages/daemon/src/formula-type.js

@@ -14,6 +14,7 @@ const formulaTypes = new Set([
   'guest',
   'handle',
   'host',
+  'interval-scheduler',
   'invitation',
   'known-peers-store',
   'least-authority',

packages/daemon/src/host.js

@@ -108,6 +108,7 @@ const normalizeHostOrGuestOptions = opts => {
  * @param {DaemonCore['getPeerIdForNodeIdentifier']} args.getPeerIdForNodeIdentifier
  * @param {DaemonCore['formulateChannel']} args.formulateChannel
  * @param {DaemonCore['formulateTimer']} args.formulateTimer
+ * @param {DaemonCore['formulateIntervalScheduler']} args.formulateIntervalScheduler
  * @param {DaemonCore['getAllNetworkAddresses']} args.getAllNetworkAddresses
  * @param {DaemonCore['getTypeForId']} args.getTypeForId
  * @param {DaemonCore['getFormulaForId']} args.getFormulaForId
@@ -152,6 +153,7 @@ export const makeHostMaker = ({
   getPeerIdForNodeIdentifier,
   formulateChannel,
   formulateTimer,
+  formulateIntervalScheduler,
   getAllNetworkAddresses,
   getTypeForId,
   getFormulaForId,
@@ -1308,6 +1310,27 @@ export const makeHostMaker = ({
       return value;
     };
 
+    /**
+     * Create an interval scheduler bound to this agent and store it under the
+     * given pet name. The returned capability lets the agent create and manage
+     * periodic wakeup intervals (the EndoClaw heartbeat facility). Tick
+     * delivery as mail messages is a later phase of the endoclaw-timer design.
+     *
+     * @param {PetName} petName - Pet name to store the scheduler under.
+     * @param {{ maxActive?: number, minPeriodMs?: number }} [options] - Host
+     *   limits: maximum active intervals and minimum period.
+     */
+    const makeIntervalSchedulerCmd = async (petName, options) => {
+      assertPetName(petName);
+      /** @type {DeferredTasks<import('./types.js').IntervalSchedulerDeferredTaskParams>} */
+      const tasks = makeDeferredTasks();
+      tasks.push(identifiers =>
+        petStore.storeIdentifier(petName, identifiers.intervalSchedulerId),
+      );
+      const { value } = await formulateIntervalScheduler(hostId, options, tasks);
+      return value;
+    };
+
     /**
      * Create a new channel and store it under the given pet name.
      * @param {NameOrPath} petName - Pet name or path to store the channel under.
@@ -1931,6 +1954,7 @@ export const makeHostMaker = ({
       deliver,
       makeChannel: makeChannelCmd,
       makeTimer: makeTimerCmd,
+      makeIntervalScheduler: makeIntervalSchedulerCmd,
       invite,
       accept,
       endow,

packages/daemon/src/interfaces.js

@@ -12,6 +12,7 @@ import {
   getInfoMethodGuard,
 } from '@endo/platform/fs/lite';
 import {
+  NameShape,
   NamePathShape,
   NameOrPathShape,
   NamesOrPathsShape,
@@ -369,6 +370,10 @@ export const HostInterface = M.interface('EndoHost', {
   makeTimer: M.call(NameOrPathShape, M.number())
     .optional(M.string())
     .returns(M.promise()),
+  // Create an interval scheduler (EndoClaw heartbeat facility)
+  makeIntervalScheduler: M.call(NameShape)
+    .optional(M.record())
+    .returns(M.promise()),
   // Cancel a value
   cancel: M.call(NameOrPathShape).optional(M.error()).returns(M.promise()),
   // Get the greeter