@ericsanchezok/synergy-github-agenda 0.0.0-stage → 3.1.1

package/AGENTS.md

@@ -0,0 +1,9 @@
+# github-agenda Package
+
+GitHub Agenda polling, watch preflight and selected trigger guidance. Required components: GitHub and Agenda. See [owning architecture](../../docs/architecture/workflows.md).
+
+Register the named Agenda source explicitly. Only selected bridges add GitHub trigger inputs and instructions; native Agenda scheduling remains independent.
+
+Expose selection through `./component`; imports are inert. Keep factory requirements, published `synergy` metadata, worker roles and production dependencies aligned. Register owner schemas, events, tools and HTTP features before Runtime composition closes.
+
+Tests under `test/` select this owner and its real requirements. Run `bun run typecheck` and focused `bun test test/<file>.test.ts` with the package preload; then run the root dependency and installed-composition checks.

package/dist/component.js

@@ -0,0 +1,17 @@
+import { componentFeatures } from "./features.js";
+import { version } from "../package.json" with { type: "json" };
+import { registerBridge } from "./register.js";
+export function githubAgenda() {
+    return {
+        id: "github-agenda",
+        features: componentFeatures,
+        apiVersion: 1,
+        version,
+        requires: { github: version, agenda: version },
+        adapters: { http: new URL("./http.js", import.meta.url) },
+        workers: { agent: new URL("./worker.js", import.meta.url) },
+        register() {
+            registerBridge();
+        },
+    };
+}

package/dist/features.js

@@ -0,0 +1,14 @@
+export const componentFeatures = {
+    kind: "bridge",
+    definitions: [
+        {
+            id: "github-agenda",
+            owner: "github-agenda",
+            maturity: "stable",
+            activation: "restart",
+            name: "Github Agenda",
+            description: "Provide github agenda capabilities.",
+            component: "github-agenda",
+        },
+    ],
+};

package/dist/github-trigger.js

@@ -0,0 +1,476 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context";
+import { GithubWatchPolicy } from "@ericsanchezok/synergy-agenda/agenda/github-watch-policy";
+import { AgendaSessionWakeup } from "@ericsanchezok/synergy-agenda/agenda/session-wakeup";
+import { AgendaStore } from "@ericsanchezok/synergy-agenda/agenda/store";
+import { Log } from "@ericsanchezok/synergy-harness/util/log";
+import { GitHubProvider } from "@ericsanchezok/synergy-harness/provider/github";
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage";
+/**
+ * GitHub agenda trigger — polls the GitHub REST API on a per-trigger interval
+ * and fires agenda items when a watched PR / issue / workflow / check run
+ * changes state.
+ *
+ * Mirrors the other agenda trigger sources: registrations are keyed by item,
+ * each entry runs its own polling loop, and matches are forwarded to the
+ * shared Agenda handler as a FiredSignal whose payload carries the resource
+ * snapshot (number, state, URL, and resource-specific fields).
+ *
+ * - Zero-cost when idle: entries with no resolved GitHub credential make no
+ *   API call, and the whole source goes quiet when `github.watch.enabled` is
+ *   false in config (default: enabled).
+ * - Triggers without an explicit `interval` fall back to the configured
+ *   `github.watch.defaultIntervalMs` (default 5 minutes, floor 30 seconds).
+ * - Multiple transitions observed in one poll are dispatched sequentially so
+ *   the Agenda inflight guard cannot drop later transitions.
+ * - Repeated poll failures (unreachable repo, invalid token) auto-pause the
+ *   item instead of retrying forever, and a credential that stays missing
+ *   across consecutive polls (account disconnected after creation) pauses
+ *   the item too instead of holding a wait silently.
+ */
+export var AgendaGithubTrigger;
+(function (AgendaGithubTrigger) {
+    const log = Log.create({ service: "agenda.github-trigger" });
+    const DEFAULT_INTERVAL_MS = 5 * 60_000;
+    const MIN_INTERVAL_MS = 30_000;
+    const MAX_CONSECUTIVE_FAILURES = 5;
+    /** Bounded recent baseline: repository-wide watches must not accumulate
+     *  every observed resource ID for the lifetime of the trigger. */
+    const MAX_BASELINE_ENTRIES = 256;
+    const runtimeState = RuntimeContext.state(() => ({
+        entries: new Map(),
+        handler: null,
+        started: false,
+    }));
+    function start(onFire, items) {
+        const instanceState = runtimeState();
+        instanceState.handler = onFire;
+        // Arm before registering: register() only schedules while started, and
+        // items restored from storage at startup must begin polling immediately.
+        instanceState.started = true;
+        for (const item of items) {
+            register(item.id, item.origin.scope.id, item.triggers, { hasRun: item.state.runCount > 0 });
+        }
+        log.info("started", { entries: countEntries() });
+    }
+    AgendaGithubTrigger.start = start;
+    function stop() {
+        const instanceState = runtimeState();
+        for (const list of instanceState.entries.values()) {
+            for (const entry of list)
+                cancelTimer(entry);
+        }
+        instanceState.entries.clear();
+        instanceState.started = false;
+        instanceState.handler = null;
+    }
+    AgendaGithubTrigger.stop = stop;
+    function register(itemID, scopeID, triggers, opts = {}) {
+        const instanceState = runtimeState();
+        unregister(itemID);
+        const created = [];
+        for (const trigger of triggers) {
+            if (trigger.type !== "github")
+                continue;
+            created.push({
+                itemID,
+                scopeID,
+                resource: trigger.resource,
+                repository: trigger.repository,
+                number: trigger.number,
+                ref: trigger.ref,
+                intervalMs: trigger.interval ? AgendaStore.parseDuration(trigger.interval) : undefined,
+                states: trigger.states,
+                lastStates: new Map(),
+                // Only items that have never run may report an already-satisfied
+                // target state on first observation; restored items re-baseline
+                // silently so restarts do not re-notify.
+                allowInitialMatch: opts.hasRun !== true,
+                consecutiveFailures: 0,
+                missingCredentialPolls: 0,
+                dispatch: Promise.resolve(),
+            });
+        }
+        if (created.length > 0) {
+            instanceState.entries.set(itemID, created);
+            log.info("github trigger registered", {
+                itemID,
+                entries: created.length,
+                resource: created[0]?.resource,
+                repository: created[0]?.repository,
+                started: instanceState.started,
+            });
+            if (instanceState.started)
+                for (const entry of created)
+                    schedule(entry, 0);
+        }
+    }
+    AgendaGithubTrigger.register = register;
+    function unregister(itemID) {
+        const instanceState = runtimeState();
+        const list = instanceState.entries.get(itemID);
+        if (!list)
+            return;
+        for (const entry of list)
+            cancelTimer(entry);
+        instanceState.entries.delete(itemID);
+    }
+    AgendaGithubTrigger.unregister = unregister;
+    function active() {
+        const instanceState = runtimeState();
+        return { items: instanceState.entries.size, entries: countEntries() };
+    }
+    AgendaGithubTrigger.active = active;
+    /** Test/inspection hook: the live poll entries registered for an item. */
+    function entriesFor(itemID) {
+        const instanceState = runtimeState();
+        return instanceState.entries.get(itemID) ?? [];
+    }
+    AgendaGithubTrigger.entriesFor = entriesFor;
+    function countEntries() {
+        const instanceState = runtimeState();
+        let n = 0;
+        for (const list of instanceState.entries.values())
+            n += list.length;
+        return n;
+    }
+    function cancelTimer(entry) {
+        if (entry.timer) {
+            clearTimeout(entry.timer);
+            entry.timer = undefined;
+        }
+    }
+    function schedule(entry, delayMs) {
+        cancelTimer(entry);
+        entry.timer = setTimeout(() => void poll(entry), delayMs);
+    }
+    function isCurrent(instanceState, entry) {
+        return instanceState.entries.get(entry.itemID)?.includes(entry) === true;
+    }
+    async function watchConfig() {
+        return GithubWatchPolicy.read();
+    }
+    async function poll(entry) {
+        const instanceState = runtimeState();
+        if (!isCurrent(instanceState, entry))
+            return;
+        entry.timer = undefined;
+        let configuredDefaultMs;
+        let abandoned = false;
+        try {
+            const watch = await watchConfig();
+            if (!isCurrent(instanceState, entry))
+                return;
+            configuredDefaultMs = watch.defaultIntervalMs;
+            if (!watch.enabled) {
+                // Polling was switched off after this item was created: pause it now
+                // (releasing any continuation holding it) instead of idling forever.
+                abandoned = true;
+                await pauseEntry(entry, "github.watch.enabled=false");
+                return;
+            }
+            const resolved = await GitHubProvider.resolveToken();
+            if (!isCurrent(instanceState, entry))
+                return;
+            if (!resolved?.token) {
+                // Credential vanished after creation (account disconnected, env
+                // removed): poll silently a few times, then pause the item — the
+                // same release path as the other pauses — so a waiting session is
+                // not held forever by a watch that can never fire.
+                entry.missingCredentialPolls++;
+                if (entry.missingCredentialPolls >= MAX_CONSECUTIVE_FAILURES) {
+                    abandoned = true;
+                    await pauseEntry(entry, "no GitHub credential resolves");
+                }
+                return;
+            }
+            entry.missingCredentialPolls = 0;
+            const snapshots = await fetchSnapshots(entry, resolved.token);
+            if (!isCurrent(instanceState, entry))
+                return;
+            const changes = collectChanges(entry, snapshots);
+            // The first poll after a restart is the restore baseline: it must not
+            // fire for already-satisfied states, but after it completes, first
+            // observations of genuinely new resources may fire again.
+            entry.allowInitialMatch = true;
+            for (const change of changes) {
+                entry.dispatch = entry.dispatch.then(() => fire(instanceState, entry, change.snapshot, change.previous));
+            }
+            entry.consecutiveFailures = 0;
+        }
+        catch (error) {
+            if (!isCurrent(instanceState, entry))
+                return;
+            entry.consecutiveFailures++;
+            log.warn("github poll failed", {
+                itemID: entry.itemID,
+                repository: entry.repository,
+                consecutiveFailures: entry.consecutiveFailures,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (entry.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                abandoned = true;
+                await pauseEntry(entry, "repeated poll failures");
+            }
+        }
+        finally {
+            // Never reschedule a detached entry: unregister()/stop() may have run
+            // while the poll request was in flight.
+            if (!abandoned && instanceState.started && isCurrent(instanceState, entry)) {
+                const intervalMs = entry.intervalMs ?? configuredDefaultMs ?? DEFAULT_INTERVAL_MS;
+                schedule(entry, Math.max(MIN_INTERVAL_MS, intervalMs));
+            }
+        }
+    }
+    AgendaGithubTrigger.poll = poll;
+    /**
+     * Pause an item and release any continuation it holds (Light Loop /
+     * BlueprintLoop) — the same release hook Agenda pause/cancel use — or the
+     * session stays stopped forever.
+     */
+    async function pauseEntry(entry, reason) {
+        const instanceState = runtimeState();
+        try {
+            const transition = await Storage.transaction(async () => {
+                const instanceState = runtimeState();
+                if (!instanceState.entries.get(entry.itemID)?.includes(entry))
+                    return;
+                const before = await AgendaStore.get(entry.scopeID, entry.itemID);
+                if (before.status !== "active" || !instanceState.entries.get(entry.itemID)?.includes(entry))
+                    return;
+                const after = await AgendaStore.update(entry.scopeID, entry.itemID, { status: "paused" });
+                return { before, after };
+            });
+            if (!transition)
+                return;
+            if (instanceState.entries.get(entry.itemID)?.includes(entry))
+                unregister(entry.itemID);
+            await AgendaSessionWakeup.resumeIfReleased(transition);
+        }
+        catch (err) {
+            log.error("failed to pause github trigger", {
+                itemID: entry.itemID,
+                reason,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+            return;
+        }
+        log.warn(`github trigger paused: ${reason}`, {
+            itemID: entry.itemID,
+            repository: entry.repository,
+        });
+    }
+    function fire(instanceState, entry, snapshot, previous) {
+        const handler = instanceState.handler;
+        if (!handler || !isCurrent(instanceState, entry))
+            return Promise.resolve();
+        const signal = {
+            type: "github",
+            source: entry.itemID,
+            payload: {
+                resource: entry.resource,
+                repository: entry.repository,
+                number: snapshot.number,
+                title: snapshot.title,
+                state: snapshot.state,
+                previousState: previous,
+                url: snapshot.url,
+                ...(snapshot.conclusion !== undefined ? { conclusion: snapshot.conclusion } : {}),
+                ...(snapshot.draft !== undefined ? { draft: snapshot.draft } : {}),
+                ...(snapshot.mergeable !== undefined ? { mergeable: snapshot.mergeable } : {}),
+                ...(snapshot.updatedAt !== undefined ? { updatedAt: snapshot.updatedAt } : {}),
+            },
+            timestamp: Date.now(),
+        };
+        return handler(signal, entry.scopeID).catch((err) => {
+            log.error("github trigger handler failed", {
+                itemID: entry.itemID,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        });
+    }
+    /**
+     * Diff snapshots against the entry baseline and return the transitions that
+     * should fire, in observation order. The baseline always advances (even for
+     * filtered-out transitions) so `previousState` reflects the last seen state.
+     *
+     * The baseline key is `state` for PR/issue watches and `state:conclusion`
+     * for workflow/check watches, so a run finishing (`completed` →
+     * `completed:failure`) counts as a transition and the states filter can
+     * match both the run status ("completed") and the conclusion ("success",
+     * "failure") as documented.
+     *
+     * First observation of a resource (`previous === undefined`): a
+     * state-targeted watch reports immediately when the resource already sits
+     * in a targeted state — covering watches created for an already-satisfied
+     * condition and races where the state changed between item creation and the
+     * first poll. Watches without a states filter stay silent on first
+     * observation so repository-wide watchers do not fire on creation.
+     * `allowInitialMatch` gates this to items that have never run, so a
+     * restart re-baselines silently instead of re-notifying.
+     */
+    function collectChanges(entry, snapshots) {
+        const pending = [];
+        for (const snapshot of snapshots) {
+            const key = `${snapshot.resource ?? ""}:${snapshot.number}`;
+            const filterKey = snapshotKey(snapshot);
+            const previous = entry.lastStates.get(key);
+            // Refresh insertion order on every observation (Map.set keeps the
+            // original position for existing keys) so eviction approximates LRU:
+            // resources still inside the observation window are never evicted,
+            // only ones that left it long ago. Without the refresh, a busy
+            // repository could evict an actively observed resource and re-fire it
+            // as a duplicate first observation.
+            entry.lastStates.delete(key);
+            entry.lastStates.set(key, filterKey);
+            // Bound the baseline: repository-wide watches observe new resource IDs
+            // every poll; drop the least recently observed entry once the cap is
+            // exceeded so long-running servers do not accumulate unbounded memory.
+            if (entry.lastStates.size > MAX_BASELINE_ENTRIES) {
+                const oldest = entry.lastStates.keys().next().value;
+                if (oldest !== undefined)
+                    entry.lastStates.delete(oldest);
+            }
+            if (previous === undefined) {
+                // First observation: only a state-targeted watch may report an
+                // already-satisfied condition; unfiltered watches baseline silently.
+                if (entry.allowInitialMatch && entry.states !== undefined && matchesStates(entry.states, snapshot)) {
+                    pending.push({ snapshot, previous: undefined });
+                }
+                continue;
+            }
+            if (previous === filterKey)
+                continue;
+            if (!matchesStates(entry.states, snapshot))
+                continue;
+            pending.push({ snapshot, previous });
+        }
+        return pending;
+    }
+    AgendaGithubTrigger.collectChanges = collectChanges;
+    /** Baseline key combining run status and conclusion for workflow/check runs. */
+    function snapshotKey(snapshot) {
+        return snapshot.conclusion !== undefined ? `${snapshot.state}:${snapshot.conclusion}` : snapshot.state;
+    }
+    /** Whether a transition matches the configured states filter (status or conclusion). */
+    function matchesStates(states, snapshot) {
+        if (!states)
+            return true;
+        return (states.includes(snapshot.state) || (snapshot.conclusion !== undefined && states.includes(snapshot.conclusion)));
+    }
+    async function api(path, token) {
+        const response = await fetch(`https://api.github.com${path}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": GitHubProvider.USER_AGENT,
+            },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok) {
+            throw new Error(`GitHub API ${path} failed with status ${response.status}`);
+        }
+        return response.json();
+    }
+    async function fetchSnapshots(entry, token) {
+        const [owner, repo] = entry.repository.split("/");
+        switch (entry.resource) {
+            case "pr": {
+                if (entry.number !== undefined) {
+                    const pr = await api(`/repos/${owner}/${repo}/pulls/${entry.number}`, token);
+                    return [prSnapshot(pr)];
+                }
+                const list = await api(`/repos/${owner}/${repo}/pulls?state=all&per_page=10&sort=updated&direction=desc`, token);
+                return (Array.isArray(list) ? list : []).map(prSnapshot);
+            }
+            case "issue": {
+                if (entry.number !== undefined) {
+                    const issue = await api(`/repos/${owner}/${repo}/issues/${entry.number}`, token);
+                    return [issueSnapshot(issue)];
+                }
+                // The issues list mixes PRs into the newest page; fetch several pages
+                // so filtering PRs out still leaves the intended issue window even in
+                // PR-heavy repositories.
+                const pages = await Promise.all([1, 2, 3].map((page) => api(`/repos/${owner}/${repo}/issues?state=all&per_page=30&sort=updated&direction=desc&page=${page}`, token)));
+                return pages
+                    .flatMap((page) => (Array.isArray(page) ? page : []))
+                    .filter((i) => i.pull_request === undefined)
+                    .slice(0, 10)
+                    .map(issueSnapshot);
+            }
+            case "workflow": {
+                if (entry.number !== undefined) {
+                    const run = await api(`/repos/${owner}/${repo}/actions/runs/${entry.number}`, token);
+                    const payload = run.workflow_run ?? run;
+                    return [workflowSnapshot(payload)];
+                }
+                const branch = entry.ref ? `&branch=${encodeURIComponent(entry.ref)}` : "";
+                const list = await api(`/repos/${owner}/${repo}/actions/runs?per_page=10${branch}`, token);
+                return (Array.isArray(list.workflow_runs) ? list.workflow_runs : []).map(workflowSnapshot);
+            }
+            case "check": {
+                const ref = encodeURIComponent(entry.ref ?? "HEAD");
+                const list = await api(`/repos/${owner}/${repo}/commits/${ref}/check-runs?per_page=20`, token);
+                return (Array.isArray(list.check_runs) ? list.check_runs : []).map(checkSnapshot);
+            }
+        }
+    }
+    function prSnapshot(pr) {
+        // List responses expose merge completion via merged_at; the single-PR
+        // response additionally carries a merged boolean. A draft PR closed
+        // without being marked ready still reports draft:true alongside
+        // state:"closed" — the terminal closed state must win over draft.
+        const merged = pr.merged === true || typeof pr.merged_at === "string";
+        const state = merged ? "merged" : pr.state === "closed" ? "closed" : pr.draft ? "draft" : pr.state;
+        return {
+            resource: "pr",
+            number: pr.number,
+            title: pr.title,
+            state,
+            url: pr.html_url,
+            draft: pr.draft === true,
+            mergeable: pr.mergeable === null ? undefined : pr.mergeable,
+            updatedAt: pr.updated_at,
+        };
+    }
+    AgendaGithubTrigger.prSnapshot = prSnapshot;
+    function issueSnapshot(issue) {
+        return {
+            resource: "issue",
+            number: issue.number,
+            title: issue.title,
+            state: issue.state,
+            url: issue.html_url,
+            updatedAt: issue.updated_at,
+        };
+    }
+    AgendaGithubTrigger.issueSnapshot = issueSnapshot;
+    /** Workflow state is the run status; the conclusion is carried separately. */
+    function workflowSnapshot(run) {
+        return {
+            resource: "workflow",
+            number: run.id,
+            title: run.name,
+            state: run.status,
+            url: run.html_url,
+            // GitHub returns null for in-progress runs; normalize to undefined so
+            // baseline keys and payloads treat "no conclusion yet" consistently.
+            conclusion: run.conclusion ?? undefined,
+            updatedAt: run.updated_at,
+        };
+    }
+    AgendaGithubTrigger.workflowSnapshot = workflowSnapshot;
+    /** Check state is the check status; the conclusion is carried separately. */
+    function checkSnapshot(check) {
+        return {
+            resource: "check",
+            number: check.id,
+            title: check.name,
+            state: check.status,
+            url: check.html_url,
+            conclusion: check.conclusion ?? undefined,
+            updatedAt: check.started_at,
+        };
+    }
+    AgendaGithubTrigger.checkSnapshot = checkSnapshot;
+})(AgendaGithubTrigger || (AgendaGithubTrigger = {}));

package/dist/http.js

@@ -0,0 +1,4 @@
+import { Server } from "@ericsanchezok/synergy-server/server/server";
+export function registerHttp() {
+    Server.registerContributions({ features: ["github-agenda"] }, "github-agenda");
+}

package/dist/preflight.js

@@ -0,0 +1,48 @@
+import { GitHubProvider } from "@ericsanchezok/synergy-harness/provider/github";
+import { GithubWatchPolicy } from "@ericsanchezok/synergy-agenda/agenda/github-watch-policy";
+/**
+ * Creation-time gate for agenda items with GitHub triggers.
+ *
+ * A GitHub watch without a resolvable credential polls silently forever and
+ * never fires — and an `agenda_watch` with `onGithub` is a continuation
+ * blocker, so the origin session would wait indefinitely with no feedback.
+ * Reject at creation with concrete connection steps instead of persisting an
+ * item that can never fire. Token validity is deliberately not checked here
+ * (that needs a live API call); an invalid token surfaces through the existing
+ * consecutive-failure auto-pause in the poll loop.
+ */
+export var GithubWatchPreflight;
+(function (GithubWatchPreflight) {
+    async function check(toolName) {
+        const watch = await GithubWatchPolicy.read();
+        if (watch?.enabled === false) {
+            return {
+                title: `${toolName} rejected`,
+                output: [
+                    `GitHub triggers are disabled (github.watch.enabled=false in config).`,
+                    ``,
+                    `Ask the user to enable them in Settings → GitHub → "Allow GitHub agenda triggers", or set github.watch.enabled=true in 115-github.jsonc.`,
+                ].join("\n"),
+                metadata: { blocked: true, reason: "github_watch_disabled" },
+            };
+        }
+        const resolved = await GitHubProvider.resolveToken();
+        if (!resolved?.token) {
+            return {
+                title: `${toolName} rejected`,
+                output: [
+                    `No connected GitHub credential — this GitHub watch would poll silently forever and never fire.`,
+                    ``,
+                    `Connect one first, then retry this exact call:`,
+                    `1. Ask the user to connect GitHub in Settings → GitHub (device login, import gh auth token, or paste a token).`,
+                    `2. Or ensure GH_TOKEN / GITHUB_TOKEN is exported in the Synergy server environment.`,
+                    ``,
+                    `Do not substitute a timed delay loop that shell-checks GitHub — that is the approximation this connection replaces. If the user declines to connect, tell them GitHub watches need a credential.`,
+                ].join("\n"),
+                metadata: { blocked: true, reason: "github_credential_missing" },
+            };
+        }
+        return undefined;
+    }
+    GithubWatchPreflight.check = check;
+})(GithubWatchPreflight || (GithubWatchPreflight = {}));

package/dist/register.js

@@ -0,0 +1,18 @@
+import watchDescription from "./watch-description.txt";
+import scheduleDescription from "./schedule-description.txt";
+import { AgendaGithubSource } from "@ericsanchezok/synergy-agenda/agenda/github-source";
+import { AgendaGithubTrigger } from "./github-trigger.js";
+import { GithubWatchPreflight } from "./preflight.js";
+import { GithubWatchPolicy } from "@ericsanchezok/synergy-agenda/agenda/github-watch-policy";
+import { readConfig } from "@ericsanchezok/synergy-github/config-schema";
+export function registerBridge() {
+    AgendaGithubSource.registerSource({
+        ...AgendaGithubTrigger,
+        descriptions: { watch: watchDescription, schedule: scheduleDescription },
+        check: GithubWatchPreflight.check,
+    });
+    GithubWatchPolicy.register(async () => {
+        const watch = (await readConfig()).github?.watch;
+        return { enabled: watch?.enabled !== false, defaultIntervalMs: watch?.defaultIntervalMs };
+    });
+}

package/dist/schedule-description.txt

@@ -0,0 +1,3 @@
+- `{type:"github", resource:"pr"|"issue"|"workflow"|"check", repository:"owner/repo", number?, ref?, interval?, states?}` — fires when the watched GitHub resource changes state, polled on an interval (default 5m). `number` targets one PR/issue or workflow run id; `ref` targets a branch/tag/commit for workflow/check watches; `states` filters transitions (e.g. ["merged"], ["failure"]). Requires a connected GitHub credential — creation is rejected with connection steps when none resolves; do not substitute a generic `every` interval that shell-checks GitHub.
+
+For "wait until a GitHub resource reaches a state" requests, the github trigger IS the right schedule — prefer it over a generic `every` interval plus manual shell checks.

package/dist/watch-description.txt

@@ -0,0 +1,5 @@
+Pass exactly one of `delay`, `onSessionEnd`, or `onGithub`.
+
+**Prefer managed GitHub watches over repeated shell polling.** When the condition you are waiting for is a GitHub event (PR merged/closed, issue closed, workflow or check run finishing), pass `onGithub: {resource, repository, number?, ref?, states?}` instead of a `delay` plus repeated shell checks. The trigger polls the GitHub REST API with the connected credential on an interval (default 5 minutes, minimum 30 seconds) and wakes you when it next observes a matching state. Intermediate transitions between polls may be missed. `resource` is "pr" | "issue" | "workflow" | "check"; `repository` is owner/repo; `number` targets one PR/issue or workflow run id (omit for the repository's recent ites); `ref` targets a branch/tag/commit for workflow/check watches; `states` filters which new state should wake you (e.g. ["merged"], ["failure"], ["completed"]). Requires a connected GitHub credential — without one the watch is rejected with connection steps; ask the user to connect GitHub in Settings → GitHub rather than substituting timed shell polling.
+
+Repo-wide watches (no `number`) fire for transitions of the 10 most recently updated items. A states-filtered watch reports new items first observed already in a targeted state; an unfiltered watch baselines first observations silently, so an item created and merged entirely between two polls is not reported. Point watches (`number`) always see transitions.

package/dist/worker.js

@@ -0,0 +1,6 @@
+import { version } from "../package.json" with { type: "json" };
+import { githubAgenda } from "./component.js";
+export const metadata = { id: "github-agenda", version, apiVersion: 1 };
+export function registerWorker() {
+    githubAgenda().register();
+}