Integrations

Purpose

Integrations are the only way work enters Last Light. Each one authenticates inbound traffic, normalizes the platform-specific payload into an EventEnvelope, and exposes a reply() callback the engine uses to post results back. Agent runtimes, LLM providers, and web-search tools are not integrations — they live inside the Sandbox and never produce inbound events.

There are five sources:

1. GitHub App webhook — issues, PRs, comments, reviews
2. Slack (HTTP Events API webhook, default; Socket Mode dev fallback) — chat threads
3. CLI — ad-hoc dispatch via the running harness
4. Cron — scheduled workflow runs
5. Admin dashboard — operator-initiated dispatch and resume

Cron and CLI are slightly different from the other three: they don’t produce EventEnvelopes — they dispatch workflows directly. They’re still event sources from the system’s perspective, just by-passing the EventEnvelope abstraction.

The connector contract

interface Connector {
  name: string;
  start(): Promise<void>;
  stop(): Promise<void>;
  on(event: "event", handler: (env: EventEnvelope) => Promise<void>): void;
}

Defined in src/connectors/types.ts. The ConnectorRegistry (src/connectors/index.ts) holds the list, wires each connector’s event emitter to a single central handler installed by the harness (src/index.ts:560), and provides startAll() / stopAll() for boot and shutdown.

Messaging connectors (Slack, future Discord) share an additional base — MessagingConnector (src/connectors/messaging/base.ts) — which adds session management, allowlist enforcement, and message chunking.

1. GitHub App webhook

If WEBHOOK_SECRET is empty (allowed but warned during boot), signature verification is disabled. Production deployments must set it.

Which event a settle becomes

A check_suite.completed delivery carries a conclusion of its own, and it is not what picks the event. The suite’s colour says only which check-reporting app happened to finish last; the decision reads the aggregate state of the head SHA. So one completed branch resolves all three outcomes, in this order:

The order is fix outranks review (09 → S2): normalize() returns one envelope per delivery, so the precedence is the shape of the pipeline rather than a policy bolted on later. Deliveries with a cancelled / neutral / skipped / stale conclusion are dropped without an aggregate read at all — nothing happened, and the round trip would buy nothing.

Reading the delivering suite’s colour instead was a live deadlock (nearform/skillspro#1646). The red and green cases were separate branches, each with its own aggregate test, and the green one demanded passing. A PR with one failing job whose sibling suite finished green afterwards landed in the green branch, computed failing, and was dropped — while the failing suite, which the red branch would have taken, had completed while the sibling was still running and read pending. No event ever fired; under review.postsCheck the queued placeholder sat on the PR until it was merged hours later. Nothing about the PR was unusual: the outcome depended purely on the order CI settled in.

Fork PRs and the check payloads

GitHub populates check_suite.pull_requests[] / check_run.pull_requests[] only when the head branch lives on the base repo. A PR opened from a fork carries an empty array, so every route keyed on it — the settle emit and both Re-run buttons — used to drop the delivery outright.

That was invisible until after-checks became the packaged default. Under eager the review fires from pr.opened, a pull_request event that always carries the PR object, so forks never touched the check path at all. Under after-checks a fork PR defers on pr.opened, posts its queued placeholder, and then no settle event can ever conclude it — the check sits there for the life of the PR, and on a repo that made it required the PR is unmergeable (nearform/lastlight#282).

So an empty array falls back to asking the base repo which open PR this commit heads (listPullRequestsAssociatedWithCommit). The base repo is the one the App is installed on, so this needs no access to the fork. Two filters make it a safe substitute for the payload’s own array: head.sha must equal the commit (the endpoint also returns PRs that merely contain it), and the PR must be open. Results are sorted ascending so the rare commit heading two open PRs resolves deterministically.

The lookup is resolved after the “does anyone consume this?” test, so a delivery no route wants still costs nothing, and a same-repo PR never reaches it at all.

The maintainer-approval gate comes for free. GitHub withholds Actions runs on a fork PR from a first-time contributor until a maintainer approves them. No approval means no checks, which means the aggregate is none and never settles, which means no review. Gating on “CI settled” inherits GitHub’s own gate exactly, with no permission logic on our side — and it is why reviewing fork PRs is safe to do by default: the same human decision that lets fork code run in Actions is the one that lets it reach the review sandbox.

Superseded check re-runs

checks.listForRef?filter=latest de-dupes per check suite, not per check name. Re-running a failed job creates a new suite, so its green result comes back alongside the red attempt it replaced — and both keep coming back for the life of the SHA. Every aggregate read therefore collapses the list to the most recent run of each (app, name) before judging it, so a re-run that goes green actually clears the failure. Without that collapse some(conclusion === "failure") pins the SHA at failing permanently and no re-run can ever move it — the other half of #1646, and the reason its aggregate could no longer reach a state any emit branch accepted.

Latest-wins is also what gates the merge: branch protection satisfies a required check from its most recent run, so reading the SHA any other way puts the harness at odds with the gate it exists to feed. Two different apps posting the same check name are not collapsed (the key is (app, name)), and a run carrying no name is passed through untouched — de-duping is an identity claim, and keeping both can only ever report a SHA redder than it is.

The same collapse applies to getCiFailureReport, so the fix agent is never handed a red job that has since been re-run green: discovery and the fix prompt have to agree on what “red” means.

Multi-installation GitHub Apps

A GitHub App is installed per account, and each installation has its own id. A token is minted against exactly one of them (POST /app/installations/{id}/access_tokens), so a token minted against the wrong installation is rejected — GitHub answers 422 There is at least one repository that does not exist or is not accessible to the parent installation, which reads like a repo problem and is not one.

One instance therefore serves every account its App is installed on, and the account is resolved per call. InstallationDirectory (src/engine/github/installations.ts) is the single owner→installation authority. Two feeds:

• Webhook payloads. Every delivery carries payload.installation.id alongside the account login. Authoritative, free, recorded before any filtering.
• GET /app/installations, under an App JWT. Needed by the routes with no webhook behind them — boot discovery, the cron fan-out, CLI/API triggers. Concurrent misses share one request, and a negative is cached briefly, so a fan-out over N repos costs one call rather than N.

Three consumers resolve through it, and nothing else knows an installation id:

An owner with no usable installation — never installed, uninstalled, or suspended — fails the phase immediately, with that sentence: no sandbox, no API call. GITHUB_APP_INSTALLATION_ID is optional and carries no account, so it is used only when the JWT lookup itself fails (network, revoked PEM): a pre-existing single-installation deployment then degrades to exactly its old behaviour. GET /admin/api/managed-repos reports every installation plus uninstalledOwners — any managedRepos account with no installation — so the condition is visible before it becomes a failed run.

Each installation carries an htmlUrl deep link to its GitHub settings page (where the repo grant, suspension and uninstall live), built server-side by installationSettingsUrl() because the path shape depends on the account type and guessing wrong 404s: an org install is /organizations/<login>/settings/installations/<id>, a personal one a viewer-scoped /settings/installations/<id>. It is null when the type isn’t known yet — a record seeded from a webhook that carried no account.type — so a caller renders plain text rather than a link that may not resolve. The response also carries appInstallUrl, the App’s own install page, derived from botName (which is the App slug), so an uninstalledOwners warning can offer the fix rather than just naming the problem.

App permission: Actions: read (optional, recommended)

Checks: read gets the harness the check runs — names, conclusions, and annotations. It does not get it the GitHub Actions job logs behind them. That is a separate App permission, Actions: read, and it is not the same thing as Workflows: write (which only governs pushing files under .github/workflows/).

GitHubClient.getCiFailureReport (src/engine/github/github.ts) attempts three Actions reads per failed check run — downloadJobLogsForWorkflowRun, getJobForWorkflowRun (for the failing step) and getWorkflowRun (for the workflow’s path) — and falls back to check-run annotations when they are denied. Nothing hard-fails without the permission: it is deliberately optional so an existing installation is never broken by not re-consenting.

What the permission changes is the quality of the evidence, and its absence is now stated rather than inferred. When no failed job could supply a real log, the rendered {{ciSection}} is prefixed with:

NOTE: GitHub Actions job logs are unavailable (the App lacks `Actions: read`).
The excerpts below are check-run annotations only, which are usually truncated.
Grant Actions: read for full CI output.

The notice is suppressed when none of the failed checks is a GitHub Actions job (a CircleCI-only repo has no Actions logs to be missing, so blaming the permission there would be wrong). The same permission backs agentic-pi’s github_list_workflow_runs / github_list_workflow_run_jobs / github_get_job_logs tools, which return { ok: false, reason } rather than throwing when it is absent.

App permission: Commit statuses: read (optional, recommended)

The same shape again, one API over: Checks: read gets the harness check runs. It does not get it the classic commit statuses a repo’s CI may post instead (CircleCI, Jenkins, anything using the legacy statuses API). GitHub exposes the two as separate permissions over separate endpoints, and neither implies the other.

GitHubClient.getChecksSummary reads both, because the settle-aware verdict is meant to cover a repo whose CI reports only via statuses — exactly the population the live check_suite webhook never sees. The status leg is repos.getCombinedStatusForRef, which needs Commit statuses: read.

The additive half must not be able to fail the whole read (issue #277). The two calls were a Promise.all, which rejects on the first rejection — so an App holding checks but not statuses 403’d on the status leg and discarded the check-runs result it was permitted to read, losing its entire CI signal rather than the legacy half of it. Nothing surfaced it: statuses is requested by no scoped-token profile, so the token still mints (no 422) and the 403 arrives at call time; the run then completes and records success = true while every CI gate reads blind. It is now a Promise.allSettled — a rejected check-runs leg still throws, a rejected status leg degrades to “no status contexts”, and the ref is judged on check runs alone.

That degradation is stated rather than inferred, and stated once per owner per process: the grant is per installation and the read runs on every pr.synchronize and every check settle, so a line per call buries the finding in tens of identical warnings a day.

App permission: organization Members: read (optional, opt-in)

Required by, and only by, per-repo dashboard visibility (teamVisibility, issue #169). With it, GitHubClient.listUserTeams can run one Organization.teams(userLogins:) GraphQL query to learn which teams a logged-in admin belongs to, and listTeamRepos can read those teams’ repo grants — so the dashboard shows that person their repos rather than the org’s.

Deliberately optional and off in config: an existing installation that never re-consents keeps today’s behaviour exactly, because a denied query resolves to the fail-open sentinel and nothing is filtered. Turning teamVisibility.enabled on without the permission is harmless, just pointless. The matching webhook subscriptions (team, membership, organization) are what keep the cache current; without them the cache still expires on its TTL and POST /admin/api/me/repos/resync still works.

Harness-side writes (GitHubClient)

The three settle-aware check queries — getChecksConclusion, getChecksSummary, getBaseChecksState — take an excludeApp option, and every trigger-side caller passes our own botName. Without it a last-light/review check that is queued (waiting for CI under after-checks) or in_progress pins the aggregate at pending: the settle event never fires, the review never runs, the check never concludes, and a repo that made it a required check has an unmergeable PR forever. See Router.

src/engine/github/github.ts is the harness’s own Octokit client — App-authed, and deliberately not the surface agents use (they get agentic-pi’s github_* tools inside the sandbox, gated per permission profile). Its write surface is small on purpose: comments (postComment / updateComment / deleteComment), reactions, review posting, the last-light/review check run — and one label write, addLabels.

addLabels is the exception that proves the rule. Every other label mutation in the system happens inside a sandbox, driven from a prompt, because the label’s value is an agent’s judgement (dependency-trivial, the impact tiers, the triage vocabulary). The dispatch-time escalation is different in kind: it fires precisely when the gate has decided not to provision a sandbox, so there is no agent to ask — see Router. GitHub’s endpoint creates a label that does not exist yet, so there is no ensureLabels companion, and adding a label already present is a no-op — but idempotency at the API is not what makes the escalation comment once; the persisted escalation row is (see State). It needs no new App permission: writing labels is part of the Issues: write / Pull requests: write grants the App already holds.

2. Slack (HTTP Events API, default; Socket Mode dev fallback)

| Transcript | The connector builds the session and stops there — it records no conversation (that double-wrote every chat turn). The thread’s transcript is written one layer up, by ChatRunner for chat turns and by src/connectors/messaging/thread-transcript.ts for every other messaging path, so a workflow-answered turn is still visible to the next chat turn in the same thread. See Chat. |

The chat skill running on top of Slack messages is not a connector concern — see Chat.

3. CLI

The endpoints live on the Hono app the GitHub webhook connector provides. Without a GitHub App configured there is no HTTP server, so the CLI cannot reach the harness. A pure chat-only deployment runs without the CLI.

4. Cron

The dual webhook/poll model is intentional: with webhooks enabled, the polling crons (cron-triage, cron-review) silently de-register; with webhooks disabled, they kick in to keep parity. The scheduled crons (cron-health, cron-security) run regardless.

Per-repo cron participation (issue #180). WHICH repos a tick fans out over is resolved at tick time, not at registration: a managed repo may opt out of (or into) a cron in its .lastlight/lastlight.yml, and that must take effect without re-registering croner jobs. jobs.ts therefore carries two control keys on every scheduled tick’s context — _cronName (the only channel by which the tick learns which cron it is; several crons can share one workflow) and _cronGloballyEnabled — which resolveCronRepos (src/cron/repo-crons.ts) consumes and the fan-out strips before dispatch, so a dispatched run’s context is byte-for-byte what it was before the feature existed. An empty resolved list is a legitimate no-op tick: no dispatch, no run, no failure. The discovery crons bypass dispatchCronWorkflow (they fan out per PR, not per repo), so src/index.ts narrows their repo list through the same resolveCronRepos before discovering anything. Cost: warm layers come from the in-memory cache, misses are fetched concurrently and conditionally, and one repo’s failure degrades to its inherited behaviour. See Configuration.

Two of the scheduled crons are dependency-PR discovery backstops for the pr.checks_passed / pr.checks_failed webhooks — additive (no unless: webhooksEnabled), so they also run with webhooks on:

• merge-green-dependency-prs (discover: green-dependency-prs, daily 14:00) — finds green (mergeable_state === "clean") dependency PRs and fans out dependabot-pr-merge. With dependencies.requireSettledChecks on (the default) it additionally asks the head SHA’s checks: clean is GitHub’s mergeability verdict, not a CI verdict, and on a repo with no required status checks a PR whose checks are failing still reports clean — so without that second read the cron’s notion of “green” and the webhook’s would differ, and the difference is a merged red PR. Uniquely in this module that read fails closed: a dropped candidate costs one tick.
• fix-red-dependency-prs (discover: red-dependency-prs, daily 15:00) — finds dependency PRs that can’t merge on their own and that dependabot-ci-fix can push toward: a settled-red check conclusion (failing/timed-out via GitHubClient.getChecksConclusion, so it never fires on a mid-flight suite), or a mergeable_state of behind (needs a base merge), dirty (merge conflict), or blocked (a required gate unmet). Failing CI wins the reported reason (checks-failing | behind | dirty | blocked). It fans out dependabot-ci-fix with the PR head branch (pre-clone) and the reason (threaded into the prompt as {{reason}}). clean is the green sweep’s; unstable is covered by the checks conclusion; unknown is left for a later tick.

Both discoverers are candidate finders, not policy. They answer one question — does this PR look like it needs this workflow? — and nothing else. Whether we may act on it (the hold label, the escalation guard, the attempt counter, the cost cap, the per-SHA dedup, the fork guard, the run lock) is decided once, off the resolved PR snapshot, at the dispatchWorkflow choke point the webhook route crosses too: see the dispatch gate.

That split is a correction, not a tidy-up. The requires-human filter used to live in the discoverers and in the dispatcher, and the two disagreed by construction: on the cron side the label was a one-way door with no code path that removed it, while the webhook path cleared it on success. Now there is one answer, and it is stateful rather than label-based — the state is “we escalated at head SHA X” (PrState.escalatedAtSha), so a maintainer’s push re-arms the PR automatically. requires-human itself is read by nothing: it is a notification the bot writes, and the label a human applies to mean “stay off this” is the separate hold label (hold.label, default lastlight-ignore), answered at the same choke point above every other guard. See Router.

The same choke point is why the fan-out no longer bypasses enrichment. A cron dispatch calls dispatchWorkflow directly and never crosses the dispatcher, so every nightly fix-red-dependency-prs run used to carry branch + reason but an empty {{ciSection}}, the repo’s default branch instead of the PR’s real base, and no fork guard at all. One projection at one place makes the webhook and cron dispatches of a pr-fix-shaped workflow identical by construction.

5. Admin dashboard

The retry endpoint’s answers, in full: 200 on dispatch (dispatched: true) or on record-without-dispatch (dispatched: false, recorded: true); 409 when the hold label, the run lock or a degraded read refuses it (nothing recorded); 403 for a repo outside managedRepos; 400 for a non-positive PR number; 503 when github / dispatchWorkflow are not wired (chat-only, CLI-only); 401 unauthenticated, from the same authMiddleware as every other admin route. lastlight pr retry <owner/repo#N> [reason] is a thin client over it and renders exactly those three outcomes (see packages/cli/CLAUDE.md).

Invariants

• One handler in, one envelope out. Every connector’s event emitter feeds the central registry.onEvent() handler in the harness. There is no second path for events.
• Auth before normalize. Both GitHub (HMAC) and Slack (allowlist) check before constructing an envelope. A failed auth never produces one.
• Normalize before route. The router (src/engine/router.ts) only sees fully-normalized envelopes. Platform-specific shape never crosses into it.
• Bot self-loop prevention is in the connector. GitHub events from the bot itself are dropped at the connector layer, not at the router. The exception (bot opening / synchronizing a PR) is also a connector decision — the router doesn’t know the difference.
• CLI, cron, and admin do not produce envelopes. They call dispatchWorkflow() directly, marking the context with _triggerType. This is a deliberate asymmetry: those sources don’t have a platform-payload-to-normalize, they have a workflow name + a context dict.
• No reply guarantees. reply() is fire-and-forget. GitHub doesn’t return the comment URL; Slack doesn’t return the message TS. Callers that need the resulting artifact must fetch it separately.

Current implementation

Rebuild notes

• Define the connector contract first, write integrations second. The asymmetry (some sources normalize to envelopes, others dispatch directly) is workable but only if the entry points are clearly typed. In TypeScript that’s the Connector interface plus the dispatchWorkflow() signature; in Go that would be two interfaces.
• One HTTP server, mounted by the GitHub connector, used by everyone. Resist the urge to give the admin dashboard or CLI endpoints their own listener. One auth surface, one TLS termination, one port to expose. If you don’t run the GitHub integration, you don’t get any HTTP surfaces — chat-only deployments are fine that way.
• Filtering is connector business, not router business. The router should only see events the system actually cares about. Bot self-loops, ignored actions, non-managed repos — drop them at the source.
• Session metadata in raw, not on the envelope. Slack channel, thread, and platform-user IDs stay in envelope.raw so the canonical schema doesn’t bloat with platform-specific fields. The chat skill reads them back when it needs to route a reply to the right thread.
• Cron is just a scheduler over the same dispatch. Don’t build a parallel “cron workflow engine”. The dispatcher signature is the same — cron just calls it on a clock instead of a webhook.
• Auth + allowlist before envelope. A re-implementation that builds the envelope first and then checks auth wastes work and leaks metadata about denied events through traces and logs. Keep the pattern.