OpenWikivercel/eve

GitHub and Linear Channels

Purpose and Scope

Issue-tracking channels let an eve agent participate where product and engineering work is already being delegated, discussed, and resolved. In the supplied source, the concrete work-tracking integration is Linear. The channel is designed around Linear Agent Sessions rather than ordinary issue comments, so the agent appears through Linear’s native agent surface and reports progress as Agent Activities. That distinction matters for developers because the integration is not just a webhook that posts text back to an issue; it is a session-oriented bridge between Linear’s agent lifecycle and eve’s durable agent runtime.

Sources: docs/channels/linear.mdx

The Linear channel receives Linear AgentSessionEvent webhooks at /eve/v1/linear, dispatches supported events into eve sessions, and replies with activity types that Linear understands. The documented activity vocabulary includes thought, action, elicitation, response, and error, giving the integration a richer interaction model than a single final comment. Use this page when you want to connect eve to issue-tracking work, understand how Linear delegation maps to eve sessions, or decide where to customize authorization and delivery behavior for a team or project workflow.

Sources: docs/channels/linear.mdx

Relevant Source Files

  • docs/channels/linear.mdx — First-party documentation for the Linear channel, including setup, credential fallback behavior, webhook configuration, dispatch rules, delivery mapping, human-in-the-loop behavior, proactive sessions, attachment support, and the Linear API handle exposed to event handlers.

Add the Linear Channel

Create a channel module under the agent’s channel directory and export the configured Linear channel as the default export. The documented example uses an explicit credentials block, which is useful when you want configuration to be visible in code while still sourcing secrets from environment variables. In a filesystem-first eve project, this follows the same channel convention used by other integrations: the channel file declares how an external surface reaches the agent, while eve owns the runtime session, tool execution, and event stream after dispatch.

Sources: docs/channels/linear.mdx

import { linearChannel } from "eve/channels/linear";
 
export default linearChannel({
  credentials: {
    accessToken: process.env.LINEAR_AGENT_ACCESS_TOKEN,
    webhookSecret: process.env.LINEAR_WEBHOOK_SECRET,
  },
});

The Linear documentation also describes a simpler configuration mode: omit the credentials block and let the channel resolve secrets from environment variables. The access token fallback order is LINEAR_AGENT_ACCESS_TOKEN, LINEAR_ACCESS_TOKEN, LINEAR_API_KEY, then LINEAR_API_TOKEN; the webhook secret falls back to LINEAR_WEBHOOK_SECRET. Both credential fields can also be lazy resolver functions. That gives teams room to fetch secrets from deployment-specific stores without changing the channel’s public shape or duplicating Linear wiring across environments.

Sources: docs/channels/linear.mdx

LINEAR_AGENT_ACCESS_TOKEN=lin_api_...
LINEAR_WEBHOOK_SECRET=...

Configure Linear

On the Linear side, create an OAuth app, enable Agent Session events, and set the webhook URL to the deployed eve route. The documented endpoint is https://<deployment>/eve/v1/linear. For Linear’s agent surface, the OAuth authorize URL must include actor=app, and the app needs scopes that allow it to appear as an agent, including app:assignable and app:mentionable. Subscribe to the AgentSessionEvent webhook category so delegation and follow-up prompts are delivered to eve.

Sources: docs/channels/linear.mdx

https://<deployment>/eve/v1/linear

Webhook verification is part of the channel’s security boundary. Linear sends signatures in the Linear-Signature header, and the documented channel verifies an HMAC over the raw request body. It also rejects stale webhookTimestamp values, which protects the route from replayed events. If your production architecture places a trusted gateway in front of eve and that gateway has already verified Linear requests, the channel can be configured with credentials.webhookVerifier instead of a webhook secret. That option keeps the same route contract while letting platform infrastructure own verification.

Sources: docs/channels/linear.mdx

System-to-Code Mapping

The central mapping is between Linear Agent Sessions and eve durable sessions. When Linear sends a supported event, eve adds a Linear context block that includes the agent session, issue, comment, and organization identifiers. It then continues the same eve session using an identifier shaped like agent-session:<id>. This is the practical bridge between issue-tracking state and agent state: Linear remains the place where work is delegated and discussed, while eve uses a stable session identity to preserve continuity across turns.

Sources: docs/channels/linear.mdx

The default dispatch hook handles created and prompted Agent Session events. A created event represents the moment a user delegates or mentions the agent from Linear, while a prompted event represents a user continuing the session. The default behavior is intentionally narrow: it wakes the agent for the event types that correspond to actual work or follow-up input. Custom hooks can keep that lifecycle but add local policy, such as limiting activity to approved teams, projects, or issue categories before any model work begins.

Sources: docs/channels/linear.mdx

Execution Flow

A typical Linear turn starts when a user delegates work from Linear. Linear sends an Agent Session webhook to eve, the channel verifies the request, the dispatch hook decides whether to proceed, and eve creates or resumes the durable session associated with that Linear agent session. During the turn, runtime events are translated back into Linear Agent Activities. The result is a progress-aware issue-tracking experience: users can see the agent thinking, acting, asking for input, completing work, or failing without leaving the Linear surface.

Sources: docs/channels/linear.mdx

Delivery is mapped to activity semantics rather than raw chat messages. Turn start posts an ephemeral thought, tool calls post ephemeral action activities, final assistant text posts a durable response, and failures post error activities. When the model emits text before a tool call, eve buffers the first non-empty line and uses it as the next ephemeral Linear thought. This mirrors the typing-status style used by chat integrations while preserving Linear’s Agent Activity model for work-tracking progress.

Sources: docs/channels/linear.mdx

Human-in-the-loop input requests use Linear elicitation activities. When the agent needs a decision, approval, clarification, or other user-provided input, the channel renders that request through Linear. When the user replies to the Agent Session, the channel resolves the response back to the pending eve input request and resumes the run with inputResponses. This makes Linear suitable for guarded work where an agent may need authorization or domain context before taking the next step.

Sources: docs/channels/linear.mdx

Hooks and API Components

The documented customization point is onAgentSession. Return an object containing auth to dispatch the event, or return null to acknowledge the webhook without waking the agent. The example imports defaultLinearAuth and applies it only when the event action is created or prompted. This hook is the right place to implement organizational policy because it runs before the agent session proceeds. For example, a team can restrict delegation to selected Linear teams, projects, or other event metadata while preserving default authentication shape.

Sources: docs/channels/linear.mdx

import { defaultLinearAuth, linearChannel } from "eve/channels/linear";
 
export default linearChannel({
  onAgentSession: (_ctx, event) => {
    if (event.action !== "created" && event.action !== "prompted") return null;
    return { auth: defaultLinearAuth(event) };
  },
});

Event handlers also receive a Linear-specific API handle at channel.linear. The documented handle exposes createActivity, listActivities, and updateSession, which allow custom Agent Activity delivery and Agent Session metadata updates. Use these methods when the default delivery mapping is close but not sufficient: for example, a deployment might add extra progress activities, inspect prior activities before posting a summary, or update session metadata after a workflow reaches a specific internal milestone.

Sources: docs/channels/linear.mdx

Operational Notes and Limitations

The Linear channel supports proactive sessions through receive(linear, { target }), allowing an application to start a Linear Agent Session without first receiving an inbound webhook. That is useful for scheduled or backend-initiated work that should still appear in Linear’s agent surface. The same documentation also notes that inbound file attachments are not supported on this channel today. Plan workflows accordingly: pass structured identifiers, issue context, or links through the session rather than relying on uploaded files as inbound agent context.

Sources: docs/channels/linear.mdx

For teams comparing work-tracking integrations, treat Linear as the source-backed example of the channel contract on this page. The important design pattern is that the channel owns platform-specific ingress, verification, dispatch policy, and delivery formatting, while eve owns durable execution after a session is started or resumed. If you need a different work-tracking surface, use the custom channel model and reproduce the same boundaries: verify the incoming platform event, decide authorization before dispatch, map platform state into context, and deliver runtime events back in native platform terms.

Sources: docs/channels/linear.mdx

Next Steps

After wiring Linear, test the full lifecycle rather than only the happy path. Confirm that the webhook endpoint receives created and prompted events, that stale or invalid signatures are rejected, that the default or custom auth policy matches your tenant model, and that tool calls produce understandable activity updates. Then exercise human-in-the-loop prompts, because elicitation handling is where issue-tracking channels become most useful for approvals and clarifications. For broader channel authoring patterns, read the channels overview and custom channel guidance next.

Ask a question...