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 (Bolt + Socket Mode) — 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 (Bolt + Socket Mode)

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.

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.