@trigger.dev/linear 3.3.12 → 4.8.0-webhooks.20261015065339

package/dist/commonjs/index.d.ts

@@ -0,0 +1,370 @@
+import type { ChannelAckCtx, ChannelConnector, ChannelControl, ChannelInbound, ChannelMessage, ChannelPendingToolCall, ChannelReply, ChannelRunSurface, ChannelSeedMessage } from "@trigger.dev/sdk/ai";
+import type { ValidateWebhookFilter, WebhookEndpoint, WebhookSource } from "@trigger.dev/core/v3";
+export type LinearUserRef = {
+    id: string;
+    name?: string;
+    displayName?: string;
+    email?: string;
+    url?: string;
+};
+export type LinearIssueRef = {
+    id: string;
+    identifier?: string;
+    title?: string;
+    description?: string | null;
+    url?: string;
+    teamId?: string;
+};
+export type LinearCommentRef = {
+    id?: string;
+    body?: string;
+    userId?: string | null;
+    createdAt?: string;
+    user?: LinearUserRef | null;
+};
+export type LinearAgentActivityRef = {
+    id: string;
+    agentSessionId?: string;
+    /** `{ type: "prompt", body }` for a user prompt. */
+    content: {
+        type?: string;
+        body?: string;
+        [key: string]: unknown;
+    };
+    /** `"stop"` when the user asked the agent to halt. */
+    signal?: string | null;
+    signalMetadata?: Record<string, unknown> | null;
+    sourceCommentId?: string | null;
+    userId?: string | null;
+    user?: LinearUserRef | null;
+    createdAt?: string;
+};
+export type LinearAgentSessionRef = {
+    id: string;
+    status?: string;
+    appUserId?: string;
+    creatorId?: string | null;
+    creator?: LinearUserRef | null;
+    issueId?: string | null;
+    issue?: LinearIssueRef | null;
+    /** The thread comment the session lives under. Set on both mentions and delegations. */
+    commentId?: string | null;
+    comment?: LinearCommentRef | null;
+    /** The comment that @mentioned the app. Null when the session came from a delegation. */
+    sourceCommentId?: string | null;
+    summary?: string | null;
+    startedAt?: string | null;
+    endedAt?: string | null;
+    url?: string | null;
+};
+/**
+ * A minimal Linear `AgentSessionEvent` webhook envelope (Linear-API `AgentSessionEventWebhookPayload`).
+ * Pass your own type for fuller typing.
+ */
+export type LinearAgentSessionEvent = {
+    /** `"AgentSessionEvent"`; other Linear webhook types are filtered out server-side. */
+    type: string;
+    /** `"created"` (mention or delegation) or `"prompted"` (a new user message on the session). */
+    action: string;
+    createdAt?: string;
+    organizationId?: string;
+    oauthClientId?: string;
+    appUserId?: string;
+    webhookId?: string;
+    webhookTimestamp?: number;
+    agentSession: LinearAgentSessionRef;
+    /** The user's prompt on a `prompted` event. */
+    agentActivity?: LinearAgentActivityRef | null;
+    /** Linear's formatted issue context (identifier, title, description, labels, comments, ...). */
+    promptContext?: string | null;
+    /** Comments in the thread before the mention. */
+    previousComments?: LinearCommentRef[] | null;
+    /** Workspace or team guidance rules for agents. */
+    guidance?: Array<{
+        body?: string;
+        [key: string]: unknown;
+    }> | string | null;
+};
+export type LinearToken<TEvent> = string | ((event: TEvent) => string | Promise<string>);
+/**
+ * The handle `linear()` binds a session to: enough to post activities into the agent session without
+ * an inbound event. A turn that no Linear prompt started (a `chat.event` action that returns
+ * `chat.turn()`) answers into this session.
+ */
+export type LinearSessionHandle = {
+    agentSessionId: string;
+    organizationId?: string;
+    issueId?: string;
+    issueIdentifier?: string;
+};
+/** The Linear agent activity types a connector can post. `prompt` is user-only. */
+export type LinearActivityType = "thought" | "action" | "elicitation" | "response" | "error";
+/**
+ * How a channel message posts into Linear. The default outbound maps a final reply to a `response`,
+ * an error to an `error`, and a non-final stream update to an ephemeral `thought`. A custom `outbound`
+ * or `ack` can set this explicitly.
+ */
+export type LinearActivitySpec = {
+    type: LinearActivityType;
+    /** Only for `thought` and `action`: shown until the next activity arrives. */
+    ephemeral?: boolean;
+    /** `action` only. */
+    action?: string;
+    parameter?: string;
+    result?: string;
+    /** `elicitation` only. */
+    signal?: "select" | "auth";
+    signalMetadata?: Record<string, unknown>;
+    /** Client-supplied UUID v4 for idempotent creation across run retries. */
+    id?: string;
+};
+/** One step of the plan Linear shows on the session. The whole plan is replaced on every update. */
+export type LinearPlanStep = {
+    content: string;
+    status: "pending" | "inProgress" | "completed" | "canceled";
+};
+/**
+ * What `run({ channel })` carries on a Linear turn: the connector's helpers over the agent session,
+ * plus `react`/`unreact` (no-ops on Linear). Cast the `channel` argument to this type.
+ */
+export type LinearRunSurface = ChannelRunSurface<{
+    /** Replace the session's plan. Linear renders it as a checklist that updates in place. */
+    plan: (steps: LinearPlanStep[]) => Promise<void>;
+    /** Post a thought. Ephemeral thoughts disappear when the next activity arrives. */
+    thought: (text: string, options?: {
+        ephemeral?: boolean;
+    }) => Promise<void>;
+    /** Post an action ("Searching docs", "auth timeout"), optionally with its result. */
+    action: (action: string, parameter: string, result?: string) => Promise<void>;
+    /** Add a labelled external link to the session header. */
+    link: (label: string, url: string) => Promise<void>;
+    /**
+     * Set the session's one-line summary from the first usable line of `text` (markdown markers and
+     * control characters stripped, capped at 255 characters). Text with no usable line sets nothing.
+     */
+    summary: (text: string) => Promise<void>;
+    /** The bound agent session and issue. */
+    session: LinearSessionHandle;
+}>;
+/** The name of the tool {@link linearPlanTool} defines; the progress mirror skips it. */
+export declare const LINEAR_PLAN_TOOL_NAME = "updatePlan";
+/**
+ * A tool the model calls to set and update its plan for the issue. Add it to the agent's `tools`
+ * and ask for a plan in the system prompt; Linear renders it as a checklist that updates in place.
+ * The whole list is replaced on every call. On a turn that is not a Linear session the tool
+ * reports that nothing was updated, so the same agent can serve other surfaces unchanged.
+ */
+export declare function linearPlanTool(): import("ai").Tool<{
+    steps: LinearPlanStep[];
+}, {
+    updated: boolean;
+    reason: string;
+    steps?: undefined;
+} | {
+    reason?: undefined;
+    updated: boolean;
+    steps: number;
+}>;
+/** The channel message shape `linear()` posts: text plus how it becomes an activity. */
+export type LinearChannelMessage = ChannelMessage & {
+    activity?: LinearActivitySpec;
+    /** Also set the session summary (1 to 255 characters) after posting. */
+    summary?: string;
+    /** Post several activities in order (used by HITL controls, one elicitation per pending tool). */
+    activities?: Array<LinearActivitySpec & {
+        text: string;
+    }>;
+};
+export type LinearChannelOptions<TEvent, TFilter extends string = string, TStartOn extends string = string> = {
+    id: string;
+    /** The endpoint to subscribe to, declared with `webhooks.endpoint.define({ id, source: webhookSource() })`. */
+    endpoint: WebhookEndpoint<TEvent>;
+    /**
+     * OAuth access token for the workspace the app is installed in (`actor=app`), or a resolver keyed on
+     * the event's `organizationId` for multi-workspace installs.
+     */
+    token: LinearToken<TEvent>;
+    /**
+     * Session key template over `{event.x}`, `{header.x}` and `{webhook.x}` placeholders. Defaults to one
+     * session per Linear agent session.
+     */
+    key?: string;
+    /** Map an event to the turn's message. Defaults to the framing described in the docs. */
+    inbound?: (event: TEvent) => ChannelInbound;
+    /** Map the agent's reply to an activity. Defaults to `response` (final), `error`, or ephemeral `thought`. */
+    outbound?: (reply: ChannelReply) => LinearChannelMessage | null;
+    /**
+     * The first activity, posted as soon as the turn starts (Linear expects one within ten seconds of
+     * `created`). Defaults to an ephemeral thought "Looking into this...". `null` posts nothing.
+     */
+    ack?: ((event: TEvent, ctx: ChannelAckCtx) => LinearChannelMessage | null) | null;
+    /** Extra server-side filter, composed AND with the mandatory agent-session guard. */
+    filter?: ValidateWebhookFilter<TEvent, TFilter>;
+    /** Only start a NEW session when an event matches this filter; existing sessions always resume. */
+    startOn?: ValidateWebhookFilter<TEvent, TStartOn>;
+    /** "final" (default): ack then the response. "stream": debounced ephemeral thoughts while streaming. */
+    delivery?: "final" | "stream";
+    /**
+     * Mirror the turn's tool calls into the session as `action` activities: the call as an ephemeral
+     * action when its input is ready, then the same action with its `result` when the tool returns.
+     * `"off"` posts nothing while the turn runs. Default `"actions"`.
+     */
+    progress?: "actions" | "off";
+    /**
+     * Set the session summary (its title in Linear) from the first line of each final reply. Off by
+     * default: Linear generates a title from the conversation itself, and a reply's first line
+     * overwrites it on every turn.
+     */
+    summarize?: boolean;
+    /**
+     * What from the payload is put in front of the model on the first turn. All default to true.
+     * `guidance` and `promptContext` are prefixed into the triggering message; `previousComments` are
+     * seeded as prior transcript messages.
+     */
+    context?: {
+        guidance?: boolean;
+        promptContext?: boolean;
+        previousComments?: boolean;
+    };
+    /**
+     * How a pending human-decision tool is described on the approval card, per tool name. Return the
+     * card's markdown body (a title line is added when `title` is set); return null or omit a tool to
+     * use the default, which renders the tool input as markdown (lists of items, key and value bullets)
+     * and falls back to JSON for shapes it cannot lay out.
+     */
+    approvals?: Record<string, (input: unknown, call: ChannelPendingToolCall) => {
+        title?: string;
+        body: string;
+    } | null>;
+    /**
+     * Linear UI for tools with no `execute`, keyed by tool name: an elicitation card with a select of
+     * `options`. The chosen option resolves the tool to `{ selected: option }`. A tool without an entry
+     * gets the Approve and Deny card (see `approvals`).
+     */
+    interactions?: Record<string, (call: ChannelPendingToolCall) => {
+        title?: string;
+        body: string;
+        options: string[];
+    } | null>;
+    /**
+     * The thought posted as soon as a prompt arrives while the agent is still working. The prompt is
+     * either folded into the work in progress (`pendingMessages` on the agent) or answered right
+     * after, so the wording should be true either way. Default "Got it, I'll take that into
+     * account."; a function of the event for wording per prompt; null posts nothing.
+     */
+    receivedThought?: string | null | ((event: TEvent) => string | null);
+    /**
+     * Override the Linear GraphQL URL (for testing against a mock). Files on this URL's origin are
+     * also treated as Linear uploads.
+     */
+    apiUrl?: string;
+};
+/**
+ * The Linear source for `webhooks.endpoint.define({ id, source: webhookSource() })`:
+ * `Linear-Signature` HMAC verification, a one minute replay window on the body's
+ * `webhookTimestamp`, dedup on the signed request (the same config as `webhooks.linear()`), and a
+ * setup prompt. Paste the signing secret from the OAuth app's webhook settings as the endpoint
+ * secret. Subscribe `webhook()` tasks to the endpoint, or pass it to `linear({ endpoint })` for an
+ * agent frontend.
+ */
+export declare function webhookSource<TEvent = LinearAgentSessionEvent>(): WebhookSource<TEvent>;
+/**
+ * Linear agent sessions as a chat frontend for an agent. List on `chat.agent({ channels: [linear({...})] })`:
+ * when a user mentions the app or delegates an issue to it, Linear opens an agent session, the connector
+ * routes it to a durable session keyed on the agent session id, runs the prompt as a turn, and posts the
+ * reply back as a `response` activity. Install the OAuth app with `actor=app`, request the
+ * `app:assignable` and `app:mentionable` scopes, enable the "Agent session events" webhook category, and
+ * set the endpoint's signing secret to the webhook signing secret.
+ *
+ * @example
+ * ```ts
+ * const linearEvents = webhooks.endpoint.define({ id: "linear", source: webhookSource() });
+ * export const agent = chat.agent({
+ *   id: "triage",
+ *   channels: [linear({ id: "linear", endpoint: linearEvents, token: process.env.LINEAR_TOKEN! })],
+ *   run: async ({ messages, streamText }) => streamText({ model, messages }),
+ * });
+ * ```
+ */
+export declare function linear<TEvent = LinearAgentSessionEvent, const TFilter extends string = string, const TStartOn extends string = string>(options: LinearChannelOptions<TEvent, TFilter, TStartOn>): ChannelConnector<TEvent, LinearSessionHandle>;
+/** The agent session an event belongs to, for `bind` and for posting. */
+export declare function linearSessionHandle(event: LinearAgentSessionEvent): LinearSessionHandle | null;
+/**
+ * True when the session came from an @mention in a comment. A delegation (the issue assigned to the
+ * app) has no `sourceCommentId`; Linear still attaches a placeholder comment ("This thread is for an
+ * agent session with ...") to it, so `comment` alone does not tell the two apart.
+ */
+export declare function isMention(event: LinearAgentSessionEvent): boolean;
+/**
+ * A Stop pressed in Linear while a turn is running aborts that turn: the partial reply posts as the
+ * response and the stop prompt is consumed. Pressed while idle, the same prompt runs as a turn and
+ * `defaultLinearInbound` turns it into a wind-down instruction. The stop is dated with the
+ * activity's `createdAt`, so one pressed while a turn ran but delivered after it ended is consumed
+ * rather than run as a wind-down.
+ */
+export declare function linearControl(event: LinearAgentSessionEvent): ChannelControl | null;
+/** True when the user asked the agent to halt (`prompted` with the `stop` signal). */
+export declare function isStopSignal(event: LinearAgentSessionEvent): boolean;
+/**
+ * Default inbound: the user's prompt, framed so the model can tell Linear-supplied context from
+ * instructions. `created` carries the issue context and the mention comment (or an assignment notice
+ * when the session came from delegation); `prompted` carries just the new message. A `stop` signal
+ * becomes an instruction to wind down.
+ */
+export declare function defaultLinearInbound(event: LinearAgentSessionEvent, context?: {
+    guidance: boolean;
+    promptContext: boolean;
+    uploadsOrigin?: string;
+}): ChannelInbound;
+/** A file the model can read, from a Linear upload link in markdown. */
+export type LinearFilePart = {
+    type: "file";
+    mediaType: string;
+    url: string;
+    filename: string;
+};
+/**
+ * Images and PDFs a Linear body links to on Linear's upload host, as file parts for the model: a
+ * `<linear-image>` tag (how Linear embeds images in the issue context) or `![alt](url)` as an image,
+ * and `[name.pdf](url)` as a PDF. A signed URL's short-lived `signature` is dropped; `linear()`
+ * downloads the file with the app's token when the model reads it. The default `inbound` adds them
+ * for the prompt, the mention comment and the issue context; use it in a custom `inbound` to keep
+ * that. At most ten per message.
+ */
+export declare function linearFileParts(markdown: string | null | undefined, options?: {
+    uploadsOrigin?: string;
+}): LinearFilePart[];
+/** Prior comments from the payload become transcript messages ahead of the triggering one. */
+export declare function seedFromPreviousComments(event: LinearAgentSessionEvent): ChannelSeedMessage[];
+/**
+ * A reply cut short by Stop: close a code fence the cut left open so the rest of the session renders,
+ * and say it was stopped.
+ */
+export declare function stoppedMarkdown(text: string): string;
+/** Linear renders GitHub-flavored markdown and turns bare Linear URLs into mentions. Trims only. */
+export declare function toLinearMarkdown(text: string): string;
+/**
+ * The first non-empty line of a reply, stripped of markdown markers and control characters, capped at
+ * 255 characters: what Linear accepts as a session summary. Undefined when nothing usable is left.
+ */
+export declare function summaryLine(text: string): string | undefined;
+/** A minimal GraphQL call against Linear's API with the app's OAuth token. */
+export declare function linearGraphql<T>(apiUrl: string, accessToken: string, query: string, variables: Record<string, unknown>): Promise<T>;
+/**
+ * Default HITL controls: one `elicitation` per pending human-decision tool, with a `select` signal
+ * offering Approve and Deny. Linear shows the chosen option's value as the user's message and delivers
+ * it back as a regular `prompted` activity. The value names the tool and the call
+ * ("Approve createSubIssues [call_a]"), so each card resolves exactly the call whose input it shows,
+ * even when an earlier turn left a same-named call pending; `onInteraction` still accepts a bare tool
+ * name typed by hand.
+ */
+type ApprovalRenderer = NonNullable<LinearChannelOptions<unknown>["approvals"]>[string];
+/** The markdown body of one approval card: a custom renderer's output, else the input laid out. */
+export declare function approvalCard(call: ChannelPendingToolCall, custom?: ApprovalRenderer): string;
+/**
+ * Lay a tool input out as markdown for a person to read: an array of objects becomes a numbered list
+ * with a bold title line and the other fields under it, a flat object becomes key and value bullets,
+ * an array of scalars a bullet list. Anything deeper falls back to a JSON block.
+ */
+export declare function inputToMarkdown(input: unknown): string;
+export {};