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

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@ericsanchezok/synergy-github-agenda",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.0",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./component": {
+      "types": "./src/component.ts",
+      "bun": "./dist/component.js",
+      "import": "./dist/component.js"
+    },
+    "./github-trigger": {
+      "types": "./src/github-trigger.ts",
+      "bun": "./dist/github-trigger.js",
+      "import": "./dist/github-trigger.js"
+    },
+    "./http": {
+      "types": "./src/http.ts",
+      "bun": "./dist/http.js",
+      "import": "./dist/http.js"
+    },
+    "./preflight": {
+      "types": "./src/preflight.ts",
+      "bun": "./dist/preflight.js",
+      "import": "./dist/preflight.js"
+    },
+    "./register": {
+      "types": "./src/register.ts",
+      "bun": "./dist/register.js",
+      "import": "./dist/register.js"
+    },
+    "./schedule-description.txt": {
+      "types": "./src/schedule-description.txt",
+      "bun": "./dist/schedule-description.txt",
+      "import": "./dist/schedule-description.txt"
+    },
+    "./watch-description.txt": {
+      "types": "./src/watch-description.txt",
+      "bun": "./dist/watch-description.txt",
+      "import": "./dist/watch-description.txt"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "bun": "./dist/worker.js",
+      "import": "./dist/worker.js"
+    },
+    "./features": {
+      "types": "./src/features.ts",
+      "bun": "./dist/features.js",
+      "import": "./dist/features.js"
+    }
+  },
+  "dependencies": {
+    "@ericsanchezok/synergy-agenda": "3.1.0",
+    "@ericsanchezok/synergy-github": "3.1.0",
+    "@ericsanchezok/synergy-harness": "3.1.0"
+  },
+  "synergy": {
+    "formatVersion": 1,
+    "kind": "component",
+    "id": "github-agenda",
+    "version": "3.1.0",
+    "compatibility": {
+      "synergy": "3.1.0"
+    },
+    "apiVersion": 1,
+    "entry": "./dist/component.js",
+    "export": "githubAgenda",
+    "requires": {
+      "github": "3.1.0",
+      "agenda": "3.1.0"
+    },
+    "packages": {
+      "@ericsanchezok/synergy-github": "3.1.0",
+      "@ericsanchezok/synergy-agenda": "3.1.0"
+    },
+    "features": {
+      "kind": "bridge",
+      "definitions": [
+        {
+          "id": "github-agenda",
+          "owner": "github-agenda",
+          "maturity": "stable",
+          "activation": "restart",
+          "name": "Github Agenda",
+          "description": "Provide github agenda capabilities.",
+          "component": "github-agenda"
+        }
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@ericsanchezok/synergy-server": "3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@ericsanchezok/synergy-server": {
+      "optional": true
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "bun": ">=1.4.3"
+  }
+}

package/src/component.ts

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

package/src/features.ts

@@ -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",
+    },
+  ],
+} as const

package/src/github-trigger.ts

@@ -0,0 +1,539 @@
+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 { AgendaTypes } from "@ericsanchezok/synergy-agenda/agenda/types"
+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 namespace 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
+
+  type Handler = (signal: AgendaTypes.FiredSignal, scopeID: string) => Promise<void>
+
+  export interface Entry {
+    itemID: string
+    scopeID: string
+    resource: "pr" | "issue" | "workflow" | "check"
+    repository: string
+    number?: number
+    ref?: string
+    /** Explicit trigger interval; undefined falls back to the configured default. */
+    intervalMs?: number
+    states?: string[]
+    timer?: Timer
+    /** resource key → last observed state */
+    lastStates: Map<string, string>
+    /**
+     * Whether first observations of a targeted state may fire. True for
+     * newly created items; false during the first restore poll of a
+     * previously-run item (so a restart re-baselines silently), then flipped
+     * true after that baseline so genuinely new resources are reported again.
+     */
+    allowInitialMatch: boolean
+    consecutiveFailures: number
+    /** Consecutive polls that found no resolvable GitHub credential. */
+    missingCredentialPolls: number
+    /** Serializes handler dispatch so concurrent transitions run in order
+     *  instead of racing the Agenda inflight guard. */
+    dispatch: Promise<void>
+  }
+
+  const runtimeState = RuntimeContext.state(() => ({
+    entries: new Map<string, Entry[]>(),
+    handler: null as Handler | null,
+    started: false,
+  }))
+
+  export function start(onFire: Handler, items: AgendaTypes.Item[]): void {
+    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() })
+  }
+
+  export function stop(): void {
+    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
+  }
+
+  export function register(
+    itemID: string,
+    scopeID: string,
+    triggers: AgendaTypes.Trigger[],
+    opts: { hasRun?: boolean } = {},
+  ): void {
+    const instanceState = runtimeState()
+
+    unregister(itemID)
+    const created: Entry[] = []
+    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)
+    }
+  }
+
+  export function unregister(itemID: string): void {
+    const instanceState = runtimeState()
+
+    const list = instanceState.entries.get(itemID)
+    if (!list) return
+    for (const entry of list) cancelTimer(entry)
+    instanceState.entries.delete(itemID)
+  }
+
+  export function active(): { items: number; entries: number } {
+    const instanceState = runtimeState()
+
+    return { items: instanceState.entries.size, entries: countEntries() }
+  }
+
+  /** Test/inspection hook: the live poll entries registered for an item. */
+  export function entriesFor(itemID: string): Entry[] {
+    const instanceState = runtimeState()
+
+    return instanceState.entries.get(itemID) ?? []
+  }
+
+  function countEntries(): number {
+    const instanceState = runtimeState()
+
+    let n = 0
+    for (const list of instanceState.entries.values()) n += list.length
+    return n
+  }
+
+  function cancelTimer(entry: Entry) {
+    if (entry.timer) {
+      clearTimeout(entry.timer)
+      entry.timer = undefined
+    }
+  }
+
+  function schedule(entry: Entry, delayMs: number) {
+    cancelTimer(entry)
+    entry.timer = setTimeout(() => void poll(entry), delayMs)
+  }
+
+  function isCurrent(instanceState: ReturnType<typeof runtimeState>, entry: Entry): boolean {
+    return instanceState.entries.get(entry.itemID)?.includes(entry) === true
+  }
+
+  async function watchConfig(): Promise<{ enabled: boolean; defaultIntervalMs?: number }> {
+    return GithubWatchPolicy.read()
+  }
+
+  export async function poll(entry: Entry) {
+    const instanceState = runtimeState()
+    if (!isCurrent(instanceState, entry)) return
+    entry.timer = undefined
+    let configuredDefaultMs: number | undefined
+    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))
+      }
+    }
+  }
+
+  /**
+   * 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: Entry, reason: string): Promise<void> {
+    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: ReturnType<typeof runtimeState>,
+    entry: Entry,
+    snapshot: ResourceSnapshot,
+    previous: string | undefined,
+  ): Promise<void> {
+    const handler = instanceState.handler
+    if (!handler || !isCurrent(instanceState, entry)) return Promise.resolve()
+    const signal: AgendaTypes.FiredSignal = {
+      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.
+   */
+  export function collectChanges(
+    entry: Pick<Entry, "lastStates" | "allowInitialMatch" | "states">,
+    snapshots: ResourceSnapshot[],
+  ): Array<{ snapshot: ResourceSnapshot; previous: string | undefined }> {
+    const pending: Array<{ snapshot: ResourceSnapshot; previous: string | undefined }> = []
+    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
+  }
+
+  /** Baseline key combining run status and conclusion for workflow/check runs. */
+  function snapshotKey(snapshot: ResourceSnapshot): string {
+    return snapshot.conclusion !== undefined ? `${snapshot.state}:${snapshot.conclusion}` : snapshot.state
+  }
+
+  /** Whether a transition matches the configured states filter (status or conclusion). */
+  function matchesStates(states: string[] | undefined, snapshot: ResourceSnapshot): boolean {
+    if (!states) return true
+    return (
+      states.includes(snapshot.state) || (snapshot.conclusion !== undefined && states.includes(snapshot.conclusion))
+    )
+  }
+  // ---------------------------------------------------------------------------
+  // GitHub REST polling
+  // ---------------------------------------------------------------------------
+
+  export interface ResourceSnapshot {
+    resource?: "pr" | "issue" | "workflow" | "check"
+    number: number
+    title?: string
+    state: string
+    url?: string
+    conclusion?: string
+    draft?: boolean
+    mergeable?: boolean
+    updatedAt?: string
+  }
+
+  async function api(path: string, token: string): Promise<any> {
+    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: Entry, token: string): Promise<ResourceSnapshot[]> {
+    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: any) => 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)
+      }
+    }
+  }
+
+  export function prSnapshot(pr: any): ResourceSnapshot {
+    // 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,
+    }
+  }
+
+  export function issueSnapshot(issue: any): ResourceSnapshot {
+    return {
+      resource: "issue",
+      number: issue.number,
+      title: issue.title,
+      state: issue.state,
+      url: issue.html_url,
+      updatedAt: issue.updated_at,
+    }
+  }
+
+  /** Workflow state is the run status; the conclusion is carried separately. */
+  export function workflowSnapshot(run: any): ResourceSnapshot {
+    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,
+    }
+  }
+
+  /** Check state is the check status; the conclusion is carried separately. */
+  export function checkSnapshot(check: any): ResourceSnapshot {
+    return {
+      resource: "check",
+      number: check.id,
+      title: check.name,
+      state: check.status,
+      url: check.html_url,
+      conclusion: check.conclusion ?? undefined,
+      updatedAt: check.started_at,
+    }
+  }
+}

package/src/http.ts

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