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.

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

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.

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.
• 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 sweeps skip any PR carrying the requires-human label — the terminal flag the dependabot prompts apply when Last Light can’t proceed (a functional merge, or a CI fix it couldn’t complete) — so the nightly crons don’t re-attempt what we already know we can’t land. The webhook path now honors it too: the dispatcher applies a pre-sandbox idempotency guard on the two dependency check events (one PR read) that skips a PR carrying requires-human, or one whose current head SHA equals the SHA of the last successful assessment (a re-fired suite / cron overlap). A genuinely new push (new head SHA, no requires-human) still runs once, and an explicit human @bot comment is an intentional override that the guard does not gate.

5. Admin dashboard

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.