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

package/dist/watcher.js

@@ -0,0 +1,279 @@
+import { WATCH_ROW } from './names.js';
+import { num, viewOf } from './rows.js';
+import { randomHex } from './store/ids.js';
+import { dialectOf } from './store/migrations.js';
+import { DEFAULT_PREFIX, requireDialectPrefix, requirePrefix, tableName } from './store/prefix.js';
+/** How often the watcher passes when the host gives no interval. */
+export const DEFAULT_WATCH_EVERY_MS = 60_000;
+/** How long a host's handler may run before the watcher gives it up as a throw, when the host gives no bound. */
+export const DEFAULT_HANDLER_TIMEOUT_MS = 30_000;
+const DAY_MS = 86_400_000;
+/**
+ * The stall watcher (spec 4.2 steps 5 and 6): under its own lease row `__watch` it finds stalled jobs and calls `onStalled`
+ * once a stall, storing the handler's reference on the row; `onRecovered` once when the job runs again; `onFailedAgain`
+ * once a day for a job that stays failed. Paused and failed jobs are never judged stalled, and neither is a scheduled job
+ * with nothing owed (a one-shot that ran, or a job whose next due time or retry is still ahead); a scheduled job's quiet is
+ * measured from its last run or the time it became owed, whichever is later. A pass renews the watch lease while it runs and
+ * stops when another holder took it. A handler call that has not settled within `handlerTimeoutMs` is given up as a throw, so
+ * a handler that never settles never holds the pass and its lease. `internals.arm: false` arms no interval: the caller drives `pass()`.
+ */
+export function createWatcher(options, internals = {}) {
+    const db = options.db;
+    const prefix = requireDialectPrefix(requirePrefix(options.prefix ?? DEFAULT_PREFIX), dialectOf(db));
+    const t = (name) => tableName(prefix, name);
+    const now = options.now ?? Date.now;
+    const everyMs = options.everyMs ?? DEFAULT_WATCH_EVERY_MS;
+    if (!(Number.isInteger(everyMs) && everyMs > 0))
+        throw new RangeError('the watcher\'s interval is a whole number of milliseconds above 0');
+    const handlerTimeoutMs = options.handlerTimeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
+    if (!(Number.isInteger(handlerTimeoutMs) && handlerTimeoutMs > 0))
+        throw new RangeError('the watcher\'s handler bound is a whole number of milliseconds above 0');
+    const logger = options.logger;
+    const holder = `${options.process}:${randomHex(4)}`;
+    const stalled = new Set();
+    const recovered = new Set();
+    const failedAgain = new Set();
+    let timer = null;
+    /** The pass in progress, which a second call and `stop()` wait on rather than start another. */
+    let current = null;
+    /**
+     * A host's handler call, rejected once it has run `handlerTimeoutMs` without settling: the caller counts it as a throw, so the
+     * stall, recovery or repeat stays unacknowledged and the next pass calls it again (the handlers are idempotent). A call given up
+     * is one `watch_handler_timed_out` line, and what it answers later is not stored.
+     */
+    function bounded(work, job, handler) {
+        let timer;
+        const limit = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                logger.warn('watch_handler_timed_out', { job, handler });
+                reject(new Error('handler timed out'));
+            }, handlerTimeoutMs);
+        });
+        return Promise.race([work, limit]).finally(() => clearTimeout(timer));
+    }
+    const view = async (row, at) => {
+        const missed = await db.get(`SELECT COUNT(*) AS n FROM ${t('missed')} WHERE job = ? AND due_at >= ?`, [row.name, at - DAY_MS]);
+        return viewOf(row, at, Number(missed?.n ?? 0), null);
+    };
+    /**
+     * Tells the host of a stall and acknowledges it on the row only once every handler settled: `stall_ref` holds the reference
+     * the handlers answered, or '' for "told, no reference"; NULL means "not yet told", and the next pass tells again. The host's
+     * handler is idempotent by `(job.name, since)`, so a second call finds the record the first one made.
+     */
+    async function tell(row, since, at) {
+        const job = await view({ ...row, stall_since: since }, at);
+        let ref = null;
+        let ok = true;
+        for (const handler of stalled) {
+            try {
+                ref = (await bounded(handler(job, since), row.name, 'stalled')) ?? ref;
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (ok)
+            await db.run(`UPDATE ${t('jobs')} SET stall_ref = ?, updated_at = ? WHERE name = ? AND stall_since = ?`, [ref ?? '', at, row.name, since]);
+    }
+    async function ensureRow(at) {
+        await db.run(`INSERT INTO ${t('jobs')} (name, title, process, kind, schedule, schedule_words, rule, stall_after_ms, safe_to_repeat, retries, timeout_ms, legal_duty, enabled, registered_at, updated_at)
+       VALUES (?, 'The stall watcher', ?, 'scheduled', NULL, '', 'skip', 0, 1, 0, 0, 0, 0, ?, ?) ON CONFLICT (name) DO NOTHING`, [WATCH_ROW, options.process, at, at]);
+    }
+    /** One statement claims the watch row for twice the pass interval; one row changed means this pass runs. */
+    async function claim(at) {
+        const token = randomHex(16);
+        const changed = await db.run(`UPDATE ${t('jobs')} SET lease_holder = ?, lease_token = ?, lease_until = ?, updated_at = ? WHERE name = ? AND (lease_until IS NULL OR lease_until < ?)`, [holder, token, at + 2 * everyMs, at, WATCH_ROW, at]);
+        return Number(changed.changes) === 1 ? token : null;
+    }
+    async function release(token) {
+        await db.run(`UPDATE ${t('jobs')} SET lease_holder = NULL, lease_token = NULL, lease_until = NULL WHERE name = ? AND lease_token = ?`, [WATCH_ROW, token]);
+    }
+    /**
+     * The time a job's quiet is measured from, or null when it cannot be stalled: a paused or failed job, a gap of 0, and a
+     * scheduled job with nothing owed (finished, or its next due time or its retry's readiness still ahead). A reports-only job
+     * is measured from its last report. A scheduled job is measured from 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 a backoff are 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.
+     */
+    function quietFrom(row, at) {
+        if (row.paused_by !== null || row.failed_at !== null || Number(row.stall_after_ms) <= 0)
+            return null;
+        const lastAt = num(row.last_run_at) ?? Number(row.registered_at);
+        if (row.kind === 'reports_only')
+            return lastAt;
+        const nextDue = num(row.next_due_at);
+        if (row.enabled !== 1 || nextDue === null)
+            return null;
+        // A retry serves `next_due_at` once `retry_at` comes: until then the job is owed nothing.
+        const retryAt = num(row.retry_at);
+        const owedAt = retryAt === null ? nextDue : Math.max(nextDue, retryAt);
+        return owedAt > at ? null : Math.max(lastAt, owedAt);
+    }
+    async function judge(row, at) {
+        const since = num(row.stall_since);
+        const lastAt = num(row.last_run_at) ?? Number(row.registered_at);
+        if (since === null) {
+            const from = quietFrom(row, at);
+            const gap = Number(row.stall_after_ms);
+            if (from === null || at - from <= gap)
+                return;
+            // The stall is marked first under the watch lease, so a second watcher or a restart never opens a second record for it;
+            // the host is told, and the row acknowledges it only once the handlers settled (`tell`). The mark holds only while the row
+            // still reads stalled: a run that settled, a pause or a failure since the read, or a registration that moved its next due
+            // time ahead or changed its gap, leaves it unmarked. Every time the mark checks is older than `at - gap`, as `quietFrom` judged.
+            const quietBefore = at - gap;
+            const lastRun = row.last_run_at === null ? 'last_run_at IS NULL' : 'last_run_at = ?';
+            const marked = await db.run(`UPDATE ${t('jobs')} SET stall_since = ?, updated_at = ? WHERE name = ? AND stall_since IS NULL AND paused_by IS NULL AND failed_at IS NULL AND stall_after_ms = ? AND ${lastRun}
+           AND (kind = 'reports_only' OR (enabled = 1 AND next_due_at IS NOT NULL AND next_due_at < ? AND (retry_at IS NULL OR retry_at < ?)))`, [lastAt, at, row.name, gap, ...(row.last_run_at === null ? [] : [lastAt]), quietBefore, quietBefore]);
+            if (Number(marked.changes) !== 1)
+                return;
+            logger.warn('job_stalled', { job: row.name, gap_minutes: Math.round((at - from) / 60_000) });
+            await tell(row, lastAt, at);
+            return;
+        }
+        if (lastAt <= since) {
+            // Marked and not yet acknowledged (a throw, or a crash between the mark and the reference): told again.
+            if (row.stall_ref === null)
+                await tell(row, since, at);
+            return;
+        }
+        // Recovered. A stall never acknowledged (the host's handler opened its record, then threw before the reference was
+        // stored) is told again first, so the idempotent handler answers the record it opened and the row stores it; while it
+        // stays unacknowledged the stall is kept and nothing is cleared.
+        let ref = row.stall_ref;
+        if (ref === null) {
+            await tell(row, since, at);
+            // The reference of this stall: a row that holds another stall now (another watcher closed this one and opened the next
+            // while this pass waited) answers nothing, and that stall is its own watcher's to recover.
+            ref = (await db.get(`SELECT stall_ref FROM ${t('jobs')} WHERE name = ? AND stall_since = ?`, [row.name, since]))?.stall_ref ?? null;
+            if (ref === null)
+                return;
+        }
+        // Then the recovery handlers, and the stall is cleared only once every one settled, so a handler that threw is called
+        // again on the next pass with the same reference (idempotent by it).
+        const job = await view({ ...row, stall_since: null, stall_ref: null }, at);
+        let ok = true;
+        for (const handler of recovered) {
+            try {
+                await bounded(handler(job, since, ref === '' ? null : ref), row.name, 'recovered');
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (ok)
+            await db.run(`UPDATE ${t('jobs')} SET stall_since = NULL, stall_ref = NULL, updated_at = ? WHERE name = ? AND stall_since = ?`, [at, row.name, since]);
+    }
+    /**
+     * The daily repeat for a job that stays failed: the handlers first (idempotent by the day count), `alerted_at` moved only once
+     * every one settled. The row is read again at the job's turn, so a job resumed (or failed again) since the pass read it is
+     * judged as it is now, never told from the pass's first read.
+     */
+    async function remind(read, at) {
+        if (read.failed_at === null)
+            return;
+        const row = await db.get(`SELECT * FROM ${t('jobs')} WHERE name = ?`, [read.name]);
+        if (!row)
+            return;
+        const alertedAt = num(row.alerted_at);
+        const failedAt = num(row.failed_at);
+        if (failedAt === null || alertedAt === null || at - alertedAt < DAY_MS)
+            return;
+        const days = Math.floor((at - failedAt) / DAY_MS);
+        const job = await view(row, at);
+        let ok = true;
+        for (const handler of failedAgain) {
+            try {
+                await bounded(handler(job, days), row.name, 'failed_again');
+            }
+            catch {
+                ok = false;
+            }
+        }
+        if (ok)
+            await db.run(`UPDATE ${t('jobs')} SET alerted_at = ?, updated_at = ? WHERE name = ? AND alerted_at = ?`, [at, at, row.name, alertedAt]);
+    }
+    async function passOnce() {
+        const at = now();
+        await ensureRow(at);
+        const token = await claim(at);
+        if (token === null)
+            return;
+        let held = true;
+        /** Renews the watch lease under this pass's token; a renewal that changes no row, or that the database refuses, ends the hold. */
+        const renew = async () => {
+            if (!held)
+                return false;
+            try {
+                const renewedAt = now();
+                const changed = await db.run(`UPDATE ${t('jobs')} SET lease_until = ?, updated_at = ? WHERE name = ? AND lease_token = ?`, [renewedAt + 2 * everyMs, renewedAt, WATCH_ROW, token]);
+                held = Number(changed.changes) === 1;
+            }
+            catch {
+                held = false;
+            }
+            return held;
+        };
+        // The lease is renewed every half interval while the pass runs, a host's handler awaited included, so a slow handler never
+        // lets a second watcher take the row and tell the same stall at once; each handler call is bounded (`bounded`), so the pass
+        // ends and the renewals stop even when a handler never settles.
+        const renewer = setInterval(() => void renew(), Math.max(1, Math.floor(everyMs / 2)));
+        renewer.unref?.();
+        try {
+            const rows = await db.all(`SELECT * FROM ${t('jobs')} WHERE name <> ? ORDER BY name`, [WATCH_ROW]);
+            for (const row of rows) {
+                // Renewed before each job too: a lease another holder took (this process lost the database for two intervals) means
+                // that holder judges from here, so this pass judges no further job.
+                if (!(await renew())) {
+                    logger.warn('watch_lease_lost', {});
+                    break;
+                }
+                await judge(row, at);
+                await remind(row, at);
+            }
+        }
+        finally {
+            clearInterval(renewer);
+            await release(token);
+        }
+    }
+    function pass() {
+        current ??= passOnce().finally(() => { current = null; });
+        return current;
+    }
+    /** A pass the interval began: a failure is one log line, never an unhandled rejection in the host's process. */
+    function timedPass() {
+        pass().catch((error) => {
+            logger.error('watch_failed', { kind: options.describe?.(error)?.kind ?? 'error' });
+        });
+    }
+    const subscribe = (set) => (handler) => {
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    };
+    return {
+        start() {
+            if (timer !== null || internals.arm === false)
+                return;
+            timer = setInterval(timedPass, everyMs);
+            timer.unref?.();
+            timedPass();
+        },
+        async stop() {
+            if (timer !== null) {
+                clearInterval(timer);
+                timer = null;
+            }
+            // The pass in progress finishes and frees the watch lease; its failure was logged where it began.
+            await current?.catch(() => undefined);
+        },
+        onStalled: subscribe(stalled),
+        onRecovered: subscribe(recovered),
+        onFailedAgain: subscribe(failedAgain),
+        pass,
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/watcher.js.map

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

package/dist/words.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview `scheduleWords`: the sentence a schedule reads as on a jobs page, in UTC. A product
+ * may show its own words instead; these are the package's.
+ */
+import type { Schedule } from './contract.js';
+/**
+ * The six forms the Jobs page shows: "Every 5 minutes", "Every hour at :40", "Daily at 00:20 UTC", "Weekly on Monday at 08:23 UTC", "Every 8 days", "Once, 4 Nov 2026 09:00 UTC"; any other cron reads "Cron <expr> UTC".
+ * 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 can still be refused there.
+ */
+export declare function scheduleWords(schedule: Schedule): string;
+//# sourceMappingURL=words.d.ts.map

package/dist/words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"words.d.ts","sourceRoot":"","sources":["../src/words.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAe9C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA8BxD"}

package/dist/words.js

@@ -0,0 +1,57 @@
+import { parseCronExpression } from './cron.js';
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const two = (n) => String(n).padStart(2, '0');
+function everyWords(ms) {
+    if (ms % 86_400_000 === 0)
+        return ms === 86_400_000 ? 'Every day' : `Every ${ms / 86_400_000} days`;
+    if (ms % 3_600_000 === 0)
+        return ms === 3_600_000 ? 'Every hour' : `Every ${ms / 3_600_000} hours`;
+    if (ms % 60_000 === 0)
+        return ms === 60_000 ? 'Every minute' : `Every ${ms / 60_000} minutes`;
+    // The interval as written: 10,500 ms reads 10.5 seconds, never a rounded 11.
+    return ms === 1_000 ? 'Every second' : `Every ${ms / 1_000} seconds`;
+}
+/**
+ * The six forms the Jobs page shows: "Every 5 minutes", "Every hour at :40", "Daily at 00:20 UTC", "Weekly on Monday at 08:23 UTC", "Every 8 days", "Once, 4 Nov 2026 09:00 UTC"; any other cron reads "Cron <expr> UTC".
+ * 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 can still be refused there.
+ */
+export function scheduleWords(schedule) {
+    if (schedule.kind === 'every') {
+        if (!Number.isInteger(schedule.everyMs) || schedule.everyMs <= 0)
+            throw new RangeError('an every schedule needs a whole number of milliseconds above 0');
+        return everyWords(schedule.everyMs);
+    }
+    if (schedule.kind === 'at') {
+        if (!Number.isFinite(schedule.at))
+            throw new RangeError('an at schedule needs a finite time');
+        const d = new Date(schedule.at);
+        return `Once, ${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()} ${two(d.getUTCHours())}:${two(d.getUTCMinutes())} UTC`;
+    }
+    const parts = schedule.expr.trim().split(/\s+/);
+    const fields = parseCronExpression(schedule.expr);
+    const [minute, hour, dom, month, dow] = parts;
+    const one = (field) => (field.size === 1 ? [...field][0] : undefined);
+    const m = one(fields.minutes);
+    const h = one(fields.hours);
+    const all = hour === '*' && dom === '*' && month === '*' && dow === '*';
+    if (minute === '*' && all)
+        return 'Every minute';
+    // A step reads as an interval only when it divides the hour: */7 runs at :56 and again at :00, and */60 once an hour.
+    const step = /^\*\/\d+$/.test(minute) ? Number(minute.slice(2)) : 0;
+    if (all && step > 0 && step < 60 && 60 % step === 0)
+        return step === 1 ? 'Every minute' : `Every ${step} minutes`;
+    if (m !== undefined && hour === '*' && dom === '*' && month === '*' && dow === '*')
+        return `Every hour at :${two(m)}`;
+    if (m !== undefined && h !== undefined && dom === '*' && month === '*' && dow === '*')
+        return `Daily at ${two(h)}:${two(m)} UTC`;
+    if (m !== undefined && h !== undefined && dom === '*' && month === '*' && one(fields.daysOfWeek) !== undefined) {
+        return `Weekly on ${DAYS[one(fields.daysOfWeek)]} at ${two(h)}:${two(m)} UTC`;
+    }
+    if (m !== undefined && h !== undefined && one(fields.daysOfMonth) !== undefined && month === '*' && dow === '*') {
+        return `Monthly on day ${one(fields.daysOfMonth)} at ${two(h)}:${two(m)} UTC`;
+    }
+    return `Cron ${parts.join(' ')} UTC`;
+}
+//# sourceMappingURL=words.js.map

package/dist/words.js.map

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

package/manifest.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
+  "id": "com.framers.system.triggers",
+  "name": "Triggers",
+  "version": "0.1.0",
+  "description": "A scheduler of record over the SQL storage adapter: job rows, a lease with a claim token, runs, missed runs and their rule, pause, resume, a hand run, bounded retries and a failed state, a stall watcher, reports-only jobs and an audit hook, with migrations on PostgreSQL and SQLite.",
+  "author": {
+    "name": "Frame",
+    "email": "team@frame.dev",
+    "url": "https://frame.dev"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["scheduler", "cron", "jobs", "triggers", "operations"],
+  "categories": ["system", "observability"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framerslab/agentos-extensions"
+  },
+  "extensions": [
+    {
+      "kind": "library",
+      "id": "triggers",
+      "displayName": "Triggers",
+      "description": "A scheduler of record over the storage adapter: definitions registered in code, a lease in the store, runs and missed runs, pause, resume and a hand run, retries and a failed state, a stall watcher",
+      "entry": "./dist/index.js"
+    }
+  ],
+  "requiredSecrets": [],
+  "optionalSecrets": [],
+  "features": [
+    "Three tables under a prefix of the product's own, with migrations on PostgreSQL and SQLite, applied through the adapter's runSchemaMigrations under the product's lock",
+    "Schedules of three kinds, at, every and cron (five fields, UTC), with a hardened parser and next-match by epoch arithmetic",
+    "One run per due time across processes: a lease claimed in one statement with a token new for each claim, renewed each tick while the run is pending, and a settlement fenced by the token",
+    "A missed-run rule a schedule (catch up once, skip, required) applied at start and at resume, each missed due time recorded",
+    "Bounded retries with backoff, a failed state that pauses the job for a person, and a hand run for a job marked safe to run twice",
+    "A stall watcher for a process that runs no jobs, under its own lease row, that opens one record a stall and closes it when the job runs again",
+    "Reports-only rows for jobs that run on their own timer and report their beats here"
+  ]
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@framers/agentos-ext-triggers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A scheduler of record in a product's own database through the SQL storage adapter: job rows, a lease with a claim token, runs, missed runs and a missed-run rule a schedule, pause and resume with an actor, a hand run for a job marked safe to run twice, bounded retries and a failed state, a stall watcher, reports-only jobs and an audit hook, under a table prefix of its own",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agentos",
+    "extension",
+    "scheduler",
+    "cron",
+    "jobs",
+    "triggers",
+    "operations"
+  ],
+  "author": {
+    "name": "Frame",
+    "url": "https://frame.dev"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "manifest.json"
+  ],
+  "peerDependencies": {
+    "@framers/sql-storage-adapter": ">=0.7.15"
+  },
+  "peerDependenciesMeta": {
+    "@framers/sql-storage-adapter": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@framers/sql-storage-adapter": "^0.9.3",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/framerslab/agentos-extensions.git",
+    "directory": "registry/curated/system/triggers"
+  },
+  "homepage": "https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/system/triggers#readme",
+  "bugs": {
+    "url": "https://github.com/framerslab/agentos-extensions/issues"
+  },
+  "gitHead": "d4178db7d82adab3cefade4d088a85c53d183818",
+  "scripts": {
+    "build": "tsc --noEmitOnError",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "clean": "rm -rf dist"
+  }
 }