@framers/agentos-ext-triggers 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,98 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+   Copyright (c) 2025 Framers
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# @framers/agentos-ext-triggers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI Status](https://github.com/framerslab/agentos-extensions/workflows/CI/badge.svg)](https://github.com/framerslab/agentos-extensions/actions)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+A scheduler of record in a product's own database, through the SQL storage adapter it already passes. Jobs are defined in code and registered when the process starts; their rows, their runs and the due times they missed live in three tables under a prefix of the product's choosing. A lease with a claim token gives each due time one run across processes, a missed-run rule decides what a job does with the due times it missed while its process was down or it was paused, and staff pause, resume and run a job by hand through the rows, with an audit hook the product writes its own record through. A stall watcher in a process that runs no jobs tells the product when a job goes quiet and when it runs again, and loops that run on their own timer report their runs here, so one page shows every job.
+
+```ts
+import { computeNextRunAtMs, migrateTriggers, scheduleWords } from '@framers/agentos-ext-triggers';
+
+await migrateTriggers(db, { prefix: 'trig', lockKey: 724313571 });
+
+const next = computeNextRunAtMs({ kind: 'cron', expr: '20 0 * * *' }, Date.now()); // the next 00:20 UTC
+const words = scheduleWords({ kind: 'cron', expr: '20 0 * * *' }); // "Daily at 00:20 UTC"
+```
+
+## What the package holds
+
+| Part | What it does |
+|---|---|
+| `createScheduler` | Registration, the restore at start with the missed-run rules, the tick, the lease with a claim token, the fenced settlement, retries, pause, resume, run now, the reads, `forgetActor`, `report()` for reports-only jobs and the hourly retention. |
+| `createSchedulerForTests` | The same scheduler with no interval armed: a host's tests drive `tick()` and `settled()` on their own clock. |
+| `createWatcher` | The stall watcher for a process that runs no jobs: a stall told once, its recovery told once, a job that stays failed told again once a day. |
+| `migrateTriggers` | Builds `<prefix>_jobs`, `<prefix>_runs`, `<prefix>_missed` and their migration ledger, `<prefix>_schema_migrations`, on PostgreSQL and SQLite. |
+| `computeNextRunAtMs` | The next due time of a schedule strictly after a given time, or `undefined` when there is none. |
+| `scheduleWords` | The sentence a schedule reads as on a jobs page. |
+| The types | `Schedule`, `MissedRunRule`, `JobDefinition`, `RunContext`, `RunSummary`, `JobState`, `RunOutcome`, `JobView`, `RunView`, `MissedView`, `TriggersRefusal`, `TriggersAuditEntry`, `TriggersLogger`, `Keep`, `TriggersOptions`, `Scheduler`, `SchedulerInternals`, `Watcher`, `WatcherFailedAgain`, `WatcherOptions`. |
+
+## Installation
+
+```bash
+npm install @framers/agentos-ext-triggers @framers/sql-storage-adapter
+```
+
+Node 22 or later. `@framers/sql-storage-adapter` 0.7.15 or later is an optional peer: the package loads it when `migrateTriggers` runs, so a process that only reads schedules never needs it.
+
+## Adopting it
+
+1. **Migrate.** The product's migration command calls `migrateTriggers` after the operations package's tables and before its own migrations, with the lock key its own runner takes:
+
+   ```ts
+   await migrateTriggers(db, { prefix: 'trig', lockKey });
+   ```
+
+   It builds the three tables and the ledger under the prefix; run again, it applies nothing. A prefix is a lower-case letter followed by at most 32 lower-case letters, digits or underscores, `trig` when none is given; on SQLite, `sqlite` and a prefix beginning `sqlite_` are refused, since SQLite keeps those names for itself. The lock key is 724313571 when none is given, the adapter runner's own default, which the operations package takes too, so runners that share a database share a key.
+
+2. **Build** one scheduler in each process that runs jobs, and one in each process that only reads and commands, which it never starts:
+
+   ```ts
+   import { createScheduler } from '@framers/agentos-ext-triggers';
+
+   const scheduler = createScheduler({
+     db,                      // the product's StorageAdapter
+     prefix: 'trig',
+     process: 'sweeper',      // the process word its leases carry
+     logger,                  // info, warn, error
+     audit: (trx, entry) => writeStaffEvent(trx, entry), // pause, resume and run now, inside the command's transaction
+     describe: (error) => ({ kind: errorKind(error) }),  // a failed try's kind as a word
+   });
+   ```
+
+   `now` (the clock, `Date.now` by default), `tickMs` (10 s by default, the smallest `every`), `handRunsPerHour` (20 by default) and `keep` (the retention, below) are the other options.
+
+3. **Register** each job before `start()`:
+
+   ```ts
+   scheduler.register({
+     name: 'ticket_routing',            // a lower-case letter, then at most 63 lower-case letters, digits or underscores
+     title: 'Ticket routing',
+     process: 'sweeper',
+     schedule: { kind: 'every', everyMs: 300_000 },
+     rule: 'catch_up_once',             // or 'skip', or 'required'
+     safeToRepeat: true,                // offers run now; a lost run is run again
+     stallAfterMs: 900_000,
+     run: async ({ signal }) => {
+       const routed = await routeWaitingTickets({ signal });
+       return { did: `${routed} routed` };
+     },
+   });
+   ```
+
+   `register` throws on a name outside the rule, a duplicate name, an `every` below the tick, a cron expression the parser refuses, and a job marked `legalDuty` whose rule is not `required`. `retries` (5), `backoffMs` (30 s doubling to 10 minutes) and `timeoutMs` (10 minutes) take those defaults when left out.
+
+4. **Start** after the product's other registrations, and stop inside the process's SIGTERM grace:
+
+   ```ts
+   await scheduler.start();
+   process.on('SIGTERM', () => void scheduler.stop({ waitMs: 5_000 }));
+   ```
+
+   `start()` writes each definition into its row, restores every job (below) and arms the tick. A second call while it runs waits for the same start and arms nothing more. `stop()` stops claiming (a tick in progress finishes first, and a claim it takes after `stop()` began starts no run and frees the job), holds the lease of each run in flight through `waitMs`, waits up to `waitMs` for those runs and then aborts their signals; a run that settles in the wait releases its lease, and one that does not keeps the held lease until it runs out two ticks after the wait, when the next claim marks it `lost`.
+
+5. **Watch** from a process that runs no jobs, so a stall is seen while the process that runs them is down (below):
+
+   ```ts
+   import { createWatcher } from '@framers/agentos-ext-triggers';
+
+   const watcher = createWatcher({ db, prefix: 'trig', process: 'web', logger });
+   watcher.onStalled(async (job, since) => openRequest(job.name, since));   // answers the request's id, stored on the job's row
+   watcher.onRecovered(async (job, since, ref) => resolveRequest(ref));
+   watcher.onFailedAgain(async (job, days) => alertAgain(job.name, days));
+   watcher.start();
+   process.on('SIGTERM', () => void watcher.stop());
+   ```
+
+A process that only reads and commands calls `list`, `get`, `runs`, `missed`, `pause`, `resume` and `runNow` on its unstarted scheduler. `pause(name, actor, note?)` and `resume(name, actor)` answer the job's view or a refusal; `runNow(name, actor)` answers `{ queued: true }` or a refusal, and the process that runs the job runs it within one tick. A refusal is `{ refused, status }`: `not_found` (404), `already`, `in_flight`, `not_safe`, `reports_only` (409), and `hand_runs_used` (429, with `retryAt`, the next whole UTC hour), past `handRunsPerHour` hand runs in one UTC clock hour on the instance; two asks at once never both pass the bound.
+
+## What the scheduler guarantees
+
+- **One run per due time across processes.** A run starts only under a claim: a conditional update that writes the process's lease and a fresh 128-bit token on a job that is due and free. Two processes on one PostgreSQL database give one run per due time; SQLite is one process by the adapter's design.
+- **A run that outlives its lease never settles over its successor.** Every write a settlement makes is conditional on its token, so a run whose lease another process took changes no job row; it is left open for that process's claim, which reads it `lost` whenever the first run's body ended. A job not marked `safeToRepeat` is paused by the system after a lost run, never run again on its own. A hand run's row is written under the job row's lock, so an account erased by `forgetActor` before the run row is written is on neither the row nor the run's context. A claim whose lease another process took before its run row was written runs nothing. Between a claim and its run row (one database round trip), a job's `lease.since` reads the claim's time; a command that writes the job row in that gap moves it to the command's time, never ahead of now, until the run row is written.
+- **A restart restores every job and loses no row.** Due times that passed while no process ran a job are written to `<prefix>_missed` with cause `worker_down` and follow the job's rule: `skip` records each one skipped; `catch_up_once` records them skipped but the latest, which one run catches up; `required` catches up every one, the run's `covers` naming them. The rows and the move of the job's next due time land in one transaction, and a due time is recorded once whatever number of processes start at once. A catch-up runs on a due time the schedule had, never on "now". A next due time within the last two ticks is left to the claim, never recorded missed, since a process still running the job claims it within a tick. A one-shot first registered after its time is owed at once and follows its rule. A due time whose run's process died holding the lease is never recorded missed: the claim reads that run `lost` first, then runs the due time again or, for a job not safe to repeat, pauses it. Past 1,000 missed due times, `skip` and `catch_up_once` record the newest 1,000 and count the rest in the log line; `required` records the oldest 1,000 and each catch-up's settlement records the next batch.
+- **Retries serve the due time their first try served.** A failed try below `retries` waits its backoff and runs again on the same due time, a restart past the backoff included; at the bound the job is paused by the system, reads `failed`, and `onFailed` fires once. `resume` clears it, and records the due times passed while it was paused (cause `paused`) by the job's rule. A resume before the next due time keeps it, and a run claimed before the pause keeps the due time it serves; a run that settles while its job is paused records the due times passed in the pause by the rule, so the resume owes the same catch-up whichever comes first.
+- **A changed definition wins over a run in flight.** A run claimed under an older definition settles onto the rule stored by the newest registration and keeps the next due time that registration set, so a rolling restart never writes the old schedule back.
+- **A hand run never doubles a run in flight and never runs a job not marked safe.** It leaves the schedule, the tries and a pause as they were.
+- **Commands decide by their write.** Each of `pause`, `resume` and `runNow` is a conditional update; two at once on one job give one change and one `already`. The `audit` hook writes inside the command's transaction only after its row changed, and a hook that throws rolls the command back.
+- **A timeout is seen at the first tick at or past it**, so a job's `signal` aborts (reason `timeout`) within one tick of its `timeoutMs`, and the try counts as failed when the body settles. The lease is renewed each tick until then.
+- **A renewal the database refuses aborts the run's `signal` with `lease_lost` at once**, before another process can take the job.
+
+## What a job body must do
+
+- Honour `signal`: stop its work when it aborts (`timeout`, `lease_lost` or `stop`).
+- When it is not safe to repeat, write `runId` and `dueAt` beside its effects, so a run after a lost one can tell what was done.
+- Answer `{ outcome: 'failed' }`, or throw or reject (with any value, `undefined` included), for a failed try; `{ outcome: 'skipped' }` when there was nothing to do; `{ did }` for the words the jobs page shows. Words and integers only: never a person's name, address or message.
+- Never outlive its timeout.
+
+## The stall watcher
+
+A job is stalled when it has gone quiet for longer than its `stallAfterMs` (15 minutes by default). A reports-only job is quiet since its last report. A scheduled job is quiet only while it is owed a run (its next due time, or its retry's readiness, has come), and since its last run (its registration when it never ran) or the time it became owed, whichever is later: a job due less often than its gap, a one-shot registered days ahead and a retry waiting out its backoff read stalled only once they have stayed owed for longer than their gap with no run, never while a due time that came less than a gap ago waits for its run. `createWatcher` judges every job, scheduled and reports-only, from a process that runs none of them, so a stall is seen while the process that runs them is down. Several processes may run a watcher; a pass runs under the watch lease, a row of its own named `__watch` (never listed, never commanded), so one pass at a time judges, across processes: the pass renews the lease every half interval and before each job, a host's slow handler included, and a pass whose lease another holder took judges no further job. Each handler call is bounded by `handlerTimeoutMs` (30 seconds by default): a call that has not settled by then is given up as a throw (one `watch_handler_timed_out` line), so a handler that never settles never holds the pass or its lease, and the next pass calls it again. It passes at `start()` and then every `everyMs` (a minute by default).
+
+- **A stall is told once.** The pass marks the stall on the job's row (`stall_since`, the stall's start: the last run's time, or the registration time of a job never run), then calls `onStalled(job, since)` and stores the reference the handler answers (the host's request id, say) as `stall_ref`. The reference is stored only once every handler settled: a handler that throws leaves the stall marked and unacknowledged, and the next pass calls it again, so the host's handler is idempotent by the job's name and `since` (it finds the record it made before opening one). A handler that answers `null` acknowledges the stall with no reference. A second watcher and a restarted one find the stall stored and tell nothing.
+- **A recovery is told once.** When the job runs again, `onRecovered(job, since, ref)` is called with the stored reference (`null` when the stall was acknowledged with none), and the stall is cleared only once every handler settled; a handler that throws is called again on the next pass with the same reference. A job that ran again before its stall was acknowledged is told the stall first, so the recovery carries the reference the host made; while that stays unacknowledged the stall is kept.
+- **What is never judged stalled.** A paused job and a failed job, whose state already says what is wrong; a scheduled job with nothing owed: a one-shot that ran, or a job whose next due time or retry is still ahead; and a job whose row changed after the pass read it (a run settled, a pause, a failure, or a registration that moved its next due time ahead or changed its gap): the mark is one conditional update on the row as the pass judged it.
+- **A job that stays failed is told again once a day.** `onFailedAgain(job, days)` is called when the job's `alerted_at` (the time of its last alert) is a day old, with the whole days since it failed; `alerted_at` moves to now only once every handler settled, so a handler that throws is called again on the next pass. The handler keys its alert by the day count. The row is read again at the job's turn, so a job resumed since the pass began is not told.
+
+A pass that fails (the database cannot be reached) writes one `watch_failed` line through the logger, and the next pass tries again; no handler's throw stops the pass. `stop()` clears the interval and waits for a pass in progress, which frees the watch lease; a watcher that dies inside a pass leaves the lease to run out two intervals later.
+
+## Reports-only jobs
+
+A loop that runs on its own timer (a box's cron line, a loop inside the product's own process) reports each run, so the jobs page shows it and the watcher judges it:
+
+```ts
+scheduler.report('backup_dump', { title: 'Backup', process: 'box', everyMs: 86_400_000 }, 'ok');
+```
+
+The scheduler keeps a row of kind `reports_only` and a run row for it, written once a minute at most a job: reports in between are coalesced in memory, so a loop may report each second. A `failed` report after a written `ok` or `skipped` is written at once, so the row never reads ok over a failure its loop reported (two writes a minute at most), and a job's writes land in the order they began. The row's stall gap is the facts' `stallAfterMs`, else twice `everyMs`, and never under three minutes, since a healthy loop's row can read up to a minute old. `report()` never throws and never waits: a name outside the job-name rule, facts no schedule can have (an interval or a gap that is not a whole number of milliseconds above 0), an outcome other than `ok`, `failed` or `skipped`, and a store that refuses the write log one warning (`report_refused` or `report_failed`); a report refused before the store holds no minute, and a report under the name of a scheduled job changes nothing of that job. `settled()` on a scheduler from `createSchedulerForTests` waits for the writes a report began. A reports-only job has no lease, no pause and no hand run: `pause`, `resume` and `runNow` answer `reports_only` (409), and a tick never claims it.
+
+## Retention
+
+| Rows | Kept | Who deletes |
+|---|---|---|
+| `<prefix>_runs` | the newest 100 a job, and those of the last 14 days | the scheduler's tick, once an hour at most |
+| `<prefix>_missed` | the newest 50 a job, and those of the last 7 days | the same |
+| a staff account's id in `<prefix>_jobs` and `<prefix>_runs` | until the product deletes that account | the product's deletion step calls `scheduler.forgetActor(trx, accountId)` |
+
+A run still running and a missed due time still owed to a catch-up are kept whatever their age and number, so a `required` catch-up that fails and retries still covers every due time it owes. `keep` (`runsPerJob`, `runDays`, `missedPerJob`, `missedDays`) replaces each default it gives; a field that is not a whole number above 0 throws a `RangeError` when the scheduler is built.
+
+## Privacy
+
+Nothing in these tables is a person's data beyond a staff account id in three columns: `paused_by` and `hand_run_by` on a job's row and `by_hand` on a run. `forgetActor` nulls them, or makes a pause's actor `system`, when the product deletes that staff account. Everything else is a job's name, title and process word, its schedule, times, counts, a run's outcome and error kind, the `did` words a job answers (words and integers, never a person's name, address or message) and the reference a host's stall handler answers. No customer's deletion touches these tables.
+
+## Schedules
+
+Three kinds. Every time is milliseconds since the epoch, and every clock is UTC.
+
+| Kind | Shape | The next due time after `afterMs` |
+|---|---|---|
+| `at` | `{ kind: 'at', at }` | `at`, when it is later than `afterMs`; otherwise none. |
+| `every` | `{ kind: 'every', everyMs, anchorMs? }` | `afterMs + everyMs`; with an anchor, the next step of the anchor's grid, or the anchor itself while it is ahead. An interval that is not a positive integer has none. |
+| `cron` | `{ kind: 'cron', expr }` | The next whole minute whose UTC fields match. |
+
+A cron expression has five fields: the minute (0 to 59), the hour (0 to 23), the day of the month (1 to 31), the month (1 to 12) and the day of the week (0 to 6, 0 for Sunday). A field is `*`, a number, a range `a-b`, a step `*/n`, `a-b/n` or `a/n` (from `a` to the field's end), or a comma list of these. Every value, range and step is checked when the expression is parsed: a step of 0, a value outside its field, a reversed range, an empty part, a word or a count of fields other than five throws a `RangeError` named `CronRefused`, which says the reason and the expression. A restricted day of the month and a restricted day of the week must both match (`0 0 13 * 5` is a Friday the 13th), where [crontab(5)](https://man7.org/linux/man-pages/man5/crontab.5.html) runs a line when either matches. The search steps a day at a time over one 400-year Gregorian cycle, after which the calendar repeats, so a match years away is found (`30 6 29 2 1`, 29 February on a Monday, comes 40 years apart across 2100) and an expression no day can match answers `undefined` (`0 0 31 2 *`). It reads the UTC fields only, so neither the host's zone nor its daylight-saving changes move a due time.
+
+`scheduleWords` reads a schedule as one of these forms:
+
+| Schedule | Words |
+|---|---|
+| `{ kind: 'every', everyMs: 300_000 }` | Every 5 minutes |
+| `{ kind: 'every', everyMs: 8 * 86_400_000 }` | Every 8 days |
+| `{ kind: 'cron', expr: '*/15 * * * *' }` | Every 15 minutes |
+| `{ kind: 'cron', expr: '40 * * * *' }` | Every hour at :40 |
+| `{ kind: 'cron', expr: '20 0 * * *' }` | Daily at 00:20 UTC |
+| `{ kind: 'cron', expr: '23 8 * * 1' }` | Weekly on Monday at 08:23 UTC |
+| `{ kind: 'cron', expr: '0 6 1 * *' }` | Monthly on day 1 at 06:00 UTC |
+| `{ kind: 'at', at: Date.UTC(2026, 10, 4, 9, 0) }` | Once, 4 Nov 2026 09:00 UTC |
+
+Any other cron expression reads `Cron <expr> UTC`. A minute step reads as an interval only when it divides the hour: `*/7` runs at :56 and again at :00, so it reads `Cron */7 * * * * UTC`. `scheduleWords` throws a `RangeError` for an interval that is not a whole number of milliseconds above 0 or a time that is not finite, and `CronRefused` for a cron expression the parser refuses, so it never reads them as words. `register` checks more (`requireSchedule`: an interval of at least `tickMs`, a finite anchor), so a schedule these words describe, such as `{ kind: 'every', everyMs: 300_000, anchorMs: NaN }` ("Every 5 minutes"), can still be refused there.
+
+## Tests
+
+The suite runs every table case on SQLite through sql.js in memory and, when `AGENTOS_TEST_POSTGRES_URL` names a server, on PostgreSQL; without it the PostgreSQL half shows as skipped under its reason. The repository's CI runs both, PostgreSQL 16 among its services. The cron cases run under UTC and, in `test/cron-tz.test.ts`, under `America/New_York` across its fall-back on 1 November 2026. `test/scheduler.test.ts` drives the tick by hand on a fake clock (`createSchedulerForTests` gives a host the same); its cases that need two processes at once run their calls at once on PostgreSQL and one after the other on SQLite. `test/watcher.test.ts`, `test/report.test.ts` and `test/housekeeping.test.ts` drive the watcher's passes and the tick by hand on the same clock.
+
+## Releases
+
+New versions are published from [framerslab/agentos-extensions](https://github.com/framerslab/agentos-extensions) by GitHub Actions. The first version publishes through the release workflow's npm token, since npm configures a trusted publisher only for a package it holds; every later version publishes through npm trusted publishing, with a provenance statement, once that publisher is configured ([RELEASING.md](https://github.com/framerslab/agentos-extensions/blob/master/RELEASING.md)).
+
+## License
+
+Apache-2.0

package/dist/contract.d.ts

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview The package's types: a job's definition, its schedule and missed-run rule, the
+ * context a run is given and the summary it answers, the views the reads answer, the refusals the
+ * commands answer, the options `createScheduler` and `createWatcher` take, and the `Scheduler` and
+ * `Watcher` surfaces. Every shape is `readonly`. Times are milliseconds since the epoch; every
+ * schedule is UTC.
+ */
+import type { SchemaMigrationReport, StorageAdapter } from '@framers/sql-storage-adapter';
+/** When a job runs. Times are milliseconds since the epoch; cron is five fields, UTC. `every` is the scheduler's tick at least, 10 s by default. */
+export type Schedule = {
+    readonly kind: 'at';
+    readonly at: number;
+} | {
+    readonly kind: 'every';
+    readonly everyMs: number;
+    readonly anchorMs?: number;
+} | {
+    readonly kind: 'cron';
+    readonly expr: string;
+};
+/** What a job does with the runs it missed while its process was down or it was paused. */
+export type MissedRunRule = 'catch_up_once' | 'skip' | 'required';
+/** A job as the host defines it in code and registers before `start()`: its name, title, process, schedule and missed-run rule, its bounds, and the function a run calls. */
+export interface JobDefinition {
+    /** The row's key and the page's address: `[a-z][a-z0-9_]{0,63}`. */
+    readonly name: string;
+    /** The title the page shows: "Ticket routing". */
+    readonly title: string;
+    /** The process word of the definition's host: `sweeper`, `web`, `ops-worker`. */
+    readonly process: string;
+    readonly schedule: Schedule;
+    readonly rule: MissedRunRule;
+    /** The gap after which the job counts as stalled; 900_000 by default. */
+    readonly stallAfterMs?: number;
+    /** Safe to run twice, two runs at once included (a lease lost across a cut can overlap a run). Run now is offered only when true. */
+    readonly safeToRepeat: boolean;
+    /** Tries before the job pauses itself; 5 by default. */
+    readonly retries?: number;
+    /** The wait before try n; 30 s doubling to 10 minutes by default. */
+    readonly backoffMs?: (attempt: number) => number;
+    /** A run's bound; 600_000 by default. At it the signal is aborted and the try counts as failed (`timeout`); the lease is renewed each tick until the promise settles. */
+    readonly timeoutMs?: number;
+    /** A timed deletion, a retention or required mail: `rule` must be `required`, and `register` refuses otherwise. */
+    readonly legalDuty?: true;
+    run(context: RunContext): Promise<RunSummary | void>;
+}
+/** What a run is given: the time, the job's view, the try's number, who asked for a hand run, the due times it covers, its id and due time, the signal the timeout aborts and the logger. */
+export interface RunContext {
+    readonly now: number;
+    readonly job: JobView;
+    readonly attempt: number;
+    /** The staff account that asked for a hand run, or null on a scheduled run. */
+    readonly byHand: {
+        readonly accountId: string;
+    } | null;
+    /** The due times this run covers: one on a scheduled run; every missed one on a `required` catch-up. */
+    readonly covers: readonly number[];
+    /** The run's id and the due time it serves (a hand run's: the time it was asked for): the idempotency key a job not safe to repeat writes beside its effects. */
+    readonly runId: string;
+    readonly dueAt: number;
+    readonly signal: AbortSignal;
+    readonly logger: TriggersLogger;
+}
+/** What the page's "Did" column reads: words and integers, never a person's anything. */
+export interface RunSummary {
+    readonly did?: string;
+    readonly counts?: Readonly<Record<string, number>>;
+    /** `failed` counts as a try exactly as a throw does; `skipped` records the run as skipped (another holder, nothing to do); `ok` when left out. */
+    readonly outcome?: 'ok' | 'skipped' | 'failed';
+}
+/** A job's state as the page shows it, read from its row and its newest runs. */
+export type JobState = 'ok' | 'running' | 'failed' | 'missed' | 'stalled' | 'paused' | 'no_run';
+/** A run's outcome: `running` until it settles. */
+export type RunOutcome = 'ok' | 'failed' | 'skipped' | 'running';
+/** A job as the reads answer it: its definition's facts, its state, its pause, its last run, its next due time, its lease, its retries and failure, a hand run asked for, and its missed runs of the last 24 hours. */
+export interface JobView {
+    readonly name: string;
+    readonly title: string;
+    readonly process: string;
+    readonly kind: 'scheduled' | 'reports_only';
+    readonly schedule: Schedule | null;
+    /** "Every 5 minutes", "Every hour at :40", "Daily at 00:20 UTC", "Once, 4 Nov 2026 09:00 UTC": the package's words, which the product may replace. */
+    readonly scheduleWords: string;
+    readonly rule: MissedRunRule;
+    readonly stallAfterMs: number;
+    readonly safeToRepeat: boolean;
+    readonly retries: number;
+    readonly legalDuty: boolean;
+    readonly state: JobState;
+    readonly paused: {
+        readonly by: string;
+        readonly at: number;
+        readonly note: string | null;
+    } | null;
+    readonly lastRun: {
+        readonly at: number;
+        readonly outcome: RunOutcome;
+        readonly ms: number | null;
+        readonly did: string | null;
+    } | null;
+    readonly nextDueAt: number | null;
+    readonly lease: {
+        readonly holder: string;
+        readonly since: number;
+    } | null;
+    readonly failed: {
+        readonly tries: number;
+        readonly lastAt: number;
+        readonly kind: string;
+        readonly alertedAt: number | null;
+    } | null;
+    /** A failed try below the job's retry bound: the tries used, the last try's error kind as a word, the time of the next try. `failed` stays null until the tries are used. */
+    readonly retrying: {
+        readonly tries: number;
+        readonly kind: string;
+        readonly nextAt: number;
+    } | null;
+    /** A hand run asked for and not yet claimed: the staff account that asked and when. */
+    readonly handRun: {
+        readonly by: string;
+        readonly at: number;
+    } | null;
+    readonly missed24h: number;
+}
+/** One run as the reads answer it, newest first. */
+export interface RunView {
+    readonly id: string;
+    readonly job: string;
+    readonly startedAt: number;
+    readonly endedAt: number | null;
+    readonly outcome: RunOutcome;
+    readonly ms: number | null;
+    readonly tries: number;
+    /** The error's kind as the host's `describe` names it (`QueryFailed`, `timeout`, `refused`, `lost`), else `error`. */
+    readonly kind: string | null;
+    readonly did: string | null;
+    readonly byHand: string | null;
+}
+/** One missed due time: why it was missed, whether it was caught up or skipped, and the run that caught it up. */
+export interface MissedView {
+    readonly dueAt: number;
+    readonly cause: 'worker_down' | 'paused';
+    readonly action: 'caught_up' | 'skipped';
+    readonly actedAt: number | null;
+    readonly runId: string | null;
+}
+/** A command's refusal: the reason as a word, the HTTP status a host answers with, and, for `hand_runs_used`, when the next hand run is allowed. */
+export type TriggersRefusal = {
+    readonly refused: 'not_found' | 'not_safe' | 'in_flight' | 'hand_runs_used' | 'reports_only' | 'already';
+    readonly status: number;
+    readonly retryAt?: number;
+};
+/** The record of a staff command, written through the host's hook inside the command's transaction. */
+export interface TriggersAuditEntry {
+    readonly kind: 'job_paused' | 'job_resumed' | 'job_run';
+    readonly staffAccountId: string;
+    /** The job's name. */
+    readonly subject: string;
+    readonly detail: Readonly<Record<string, string | number>>;
+}
+/** The host's logger: three levels, a message and fields. */
+export interface TriggersLogger {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/** How long the runs and missed runs are kept: the newest `runsPerJob` runs a job and those of the last `runDays` days, the same for missed runs. */
+export interface Keep {
+    readonly runsPerJob: number;
+    readonly runDays: number;
+    readonly missedPerJob: number;
+    readonly missedDays: number;
+}
+/** The options `createScheduler` takes: the adapter, the table prefix, the process word, the logger and clock, the tick, the retention, the hand-run bound, and the host's error and audit hooks. */
+export interface TriggersOptions {
+    readonly db: StorageAdapter;
+    /** The table prefix, `trig` by default; the rule the operations package's `requirePrefix` applies. */
+    readonly prefix?: string;
+    readonly process: string;
+    readonly logger: TriggersLogger;
+    readonly now?: () => number;
+    /** 10_000 by default; the smallest `every`. */
+    readonly tickMs?: number;
+    /** The retention of runs and missed runs; each field left out takes its default. */
+    readonly keep?: Partial<Keep>;
+    /** Hand runs an hour on the instance; 20 by default. */
+    readonly handRunsPerHour?: number;
+    /** The error's kind, as the operations `describe` hook answers it. */
+    describe?(error: unknown): {
+        readonly kind: string;
+    } | null;
+    audit?(trx: StorageAdapter, entry: TriggersAuditEntry): Promise<void>;
+}
+/** What `createScheduler` answers: registration and start for the process that runs the jobs, the commands and reads every process may call, the run hooks and the actor's erasure. */
+export interface Scheduler {
+    /** Before `start()`; throws on a duplicate name, a schedule below the tick, or a legal-duty job whose rule is not `required`. */
+    register(definition: JobDefinition): void;
+    /** A job that runs on its own timer and reports its runs here: upserts its `reports_only` row and a run a minute at most. Never throws, never waits. */
+    report(name: string, facts: {
+        readonly title: string;
+        readonly process: string;
+        readonly everyMs: number;
+        readonly stallAfterMs?: number;
+        readonly legalDuty?: true;
+    }, outcome: 'ok' | 'failed' | 'skipped'): void;
+    /** Restores the rows, applies the missed-run rules, arms the tick. */
+    start(): Promise<void>;
+    /** Stops claiming and the tick, waits up to `waitMs` (5 s by default, inside the host's SIGTERM grace) for the runs in flight, then aborts their signals; a run that settles in the wait releases its lease through the fenced settlement, and one that does not stops being renewed when the process exits, so its lease expires within two ticks and the run reads `lost` at the next claim. */
+    stop(options?: {
+        readonly waitMs?: number;
+    }): Promise<void>;
+    pause(name: string, actor: {
+        readonly accountId: string;
+    }, note?: string): Promise<JobView | TriggersRefusal>;
+    resume(name: string, actor: {
+        readonly accountId: string;
+    }): Promise<JobView | TriggersRefusal>;
+    runNow(name: string, actor: {
+        readonly accountId: string;
+    }): Promise<{
+        readonly queued: true;
+    } | TriggersRefusal>;
+    list(filter?: {
+        readonly state?: JobState | 'attention';
+        readonly process?: string;
+        readonly cursor?: string;
+    }): Promise<{
+        readonly jobs: readonly JobView[];
+        readonly cursor: string | null;
+    }>;
+    get(name: string): Promise<JobView | null>;
+    runs(name: string, options?: {
+        readonly limit?: number;
+    }): Promise<readonly RunView[]>;
+    missed(name: string, options?: {
+        readonly sinceMs?: number;
+    }): Promise<readonly MissedView[]>;
+    /** After each run has settled; the operations package writes `ops_beats` here. */
+    onRun(handler: (job: JobView, run: RunView) => void): () => void;
+    /** Once, when a job's tries are used. */
+    onFailed(handler: (job: JobView, run: RunView) => void): () => void;
+    /** Nulls the staff account id on every row that names it (a staff account's deletion). */
+    forgetActor(trx: StorageAdapter, accountId: string): Promise<void>;
+}
+/** The stall watcher's extra duty: a failed job whose `alerted_at` is 24 hours old gets one more alert; the handler is given the day count since it failed. */
+export interface WatcherFailedAgain {
+    onFailedAgain(handler: (job: JobView, days: number) => Promise<void>): () => void;
+}
+/** The stall watcher for a process that runs no jobs (the web): under its own lease row it finds stalled jobs and calls `onStalled` once per stall, and `onRecovered` when the job runs again. */
+export interface Watcher extends WatcherFailedAgain {
+    start(): void;
+    stop(): Promise<void>;
+    /**
+     * The handler answers the host's reference for the stall (the request's id), which the watcher stores on the job's row (`stall_ref`). Paused and failed jobs are never judged stalled.
+     * `since` is the stall's start: the last run's time, or the registration time of a job never run; the host keys its record by `(name, since)`, so a handler called again for one stall finds the record it made.
+     */
+    onStalled(handler: (job: JobView, since: number) => Promise<string | null>): () => void;
+    onRecovered(handler: (job: JobView, stalledSince: number, ref: string | null) => Promise<void>): () => void;
+}
+/** What `migrateTriggers` answers: the adapter runner's own report. */
+export type TriggersMigrationReport = SchemaMigrationReport;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":""}