@dahrk/linear 0.1.0 → 0.1.1

package/src/linear-client.ts

@@ -0,0 +1,449 @@
+/**
+ * The real Agent Session client over `@linear/sdk` (build spec section 14). This is the
+ * LIVE path - it makes authenticated GraphQL calls to Linear - so it is only constructed
+ * when a Connection carries a bearer token; the offline harness uses the recording client.
+ *
+ * Verified against @linear/sdk v86: `createAgentActivity({ agentSessionId, content, signal?,
+ * signalMetadata?, ephemeral? })` (content is an untyped JSONObject - the typed payload shapes
+ * are in Linear's agent-interaction docs), `updateAgentSession(id, { plan, externalUrls })`,
+ * `agentSession(id)` (resolves the issue), `updateIssue(id, { stateId, delegateId })`,
+ * `team(id).states({ filter })`, `viewer`, and `createAttachment({ issueId, url, title, ... })`.
+ * There is no app-settable session `state`: Linear derives it from activities and signals, so
+ * `setState` is a no-op here.
+ */
+import { AgentActivitySignal, AgentActivityType, LinearClient } from "@linear/sdk";
+import { filterExternalUrls } from "./index.js";
+import { formatToolAction } from "./format-action.js";
+import type {
+  Activity,
+  AgentSessionClient,
+  DocumentInput,
+  DocumentRef,
+  ElicitOption,
+  IssueEngagement,
+  IssueStateType,
+  MoveToReviewOutcome,
+  PrAttachment,
+  StartIssueOutcome,
+} from "./index.js";
+
+/** One query, resolving the disengagement ground truth for a batch of issues. `includeArchived`
+ *  keeps soft-deleted issues in the result (so they read as archived, not deleted); an id absent
+ *  from the result was hard-deleted. */
+const ISSUE_ENGAGEMENT_QUERY = /* GraphQL */ `
+  query DahrkIssueEngagement($ids: [ID!]!) {
+    issues(filter: { id: { in: $ids } }, includeArchived: true, first: 250) {
+      nodes {
+        id
+        archivedAt
+        delegateId
+        assignee { id }
+        state { type }
+      }
+    }
+  }
+`;
+
+/** DHK-63: proactively open an agent session on an issue / a comment. Returns the new session id off
+ *  the AgentSessionPayload so the hub can bind a pre-brief run to it. */
+const SESSION_CREATE_ON_ISSUE = /* GraphQL */ `
+  mutation DahrkAgentSessionCreateOnIssue($input: AgentSessionCreateOnIssue!) {
+    agentSessionCreateOnIssue(input: $input) {
+      agentSession { id }
+    }
+  }
+`;
+
+const SESSION_CREATE_ON_COMMENT = /* GraphQL */ `
+  mutation DahrkAgentSessionCreateOnComment($input: AgentSessionCreateOnComment!) {
+    agentSessionCreateOnComment(input: $input) {
+      agentSession { id }
+    }
+  }
+`;
+
+interface IssueEngagementRow {
+  id: string;
+  archivedAt?: string | null;
+  delegateId?: string | null;
+  assignee?: { id?: string | null } | null;
+  state?: { type?: string | null } | null;
+}
+
+/** The subset of a Linear workflow state that state-selection needs. Kept structural so the live
+ *  SDK's `WorkflowState` nodes satisfy it and the pure selectors are unit-testable without the SDK. */
+export interface StateLike {
+  id: string;
+  name: string;
+  position: number;
+  type: string;
+}
+
+/** The configured review-state name. `DAHRK_` is the name; the legacy `SKAKEL_` prefix is still
+ *  honoured so a host provisioned before the rename keeps working (DHK-440). This package has no
+ *  dependency on the hub, so it cannot reuse the hub's `envRenamed`. */
+function reviewStateNameEnv(): string | undefined {
+  return process.env.DAHRK_REVIEW_STATE_NAME ?? process.env.SKAKEL_REVIEW_STATE_NAME;
+}
+
+/** Find the review-target state the way `moveIssueToReview` does, so `startIssue` can EXCLUDE it.
+ *  Linear has no "review" state type, so it is matched by name: an explicit configured name
+ *  (`DAHRK_REVIEW_STATE_NAME`) when set, else the first review-ish name. */
+export function findReviewState<T extends StateLike>(states: readonly T[], reviewName?: string): T | undefined {
+  const wanted = (reviewName ?? "").trim().toLowerCase();
+  return wanted
+    ? states.find((s) => s.name.toLowerCase() === wanted)
+    : states.find((s) => /review|in review|qa/i.test(s.name));
+}
+
+/**
+ * Pick the team's working ("In Progress") state for a just-started run. A team can have MORE THAN
+ * ONE `started`-typed state (e.g. both "In Progress" and "In Review" are typed `started`), so the
+ * naive "lowest-position started state" is ambiguous and can wrongly land the ticket in In Review.
+ * Prefer an explicit working-name match (`/in progress|doing|started/i`), else the lowest-position
+ * `started` state that is NOT the review state. Returns `undefined` when there is no usable working
+ * state (so the caller reports a no-op rather than moving the ticket to review).
+ */
+export function selectStartState<T extends StateLike>(states: readonly T[], reviewName?: string): T | undefined {
+  const started = states.filter((s) => s.type === "started").sort((a, b) => a.position - b.position);
+  if (started.length === 0) return undefined;
+  const review = findReviewState(states, reviewName);
+  const candidates = started.filter((s) => !review || s.id !== review.id);
+  if (candidates.length === 0) return undefined;
+  return candidates.find((s) => /in progress|doing|started/i.test(s.name)) ?? candidates[0];
+}
+
+/** Returns true when `delegateId` should be written on the issue.
+ *  Skipping when already equal avoids the "assigned to you" notification on every re-run (DHK-263). */
+export function shouldSetDelegate(issueDelegateId: string | undefined, viewerId: string): boolean {
+  return issueDelegateId !== viewerId;
+}
+
+/** A document as the issue-documents lookup sees it. Structural, so `findDocumentByTitle` is unit
+ *  testable without standing up the SDK. */
+export interface DocumentLike {
+  id: string;
+  /** Optional so the live SDK's non-null `title` is assignable and a null from the API cannot throw. */
+  title?: string;
+  url?: string;
+}
+
+/** The slice of a Linear issue the document lookup needs. */
+export interface IssueDocuments {
+  documents(args: { first: number }): Promise<{ nodes: DocumentLike[] }>;
+}
+
+/**
+ * The document already attached to this issue under `title`, or null when there is none. This is
+ * what gives `createDocument` its upsert: Linear keys documents by id only, so a title match on the
+ * issue is our stand-in.
+ *
+ * Titles are compared trimmed and case-insensitively, so a human who lightly re-cases the title does
+ * not cause the next run to fork a second copy. The read is bounded and unpaginated at 50, matching
+ * `linearDocumentSource.issueDocuments` in `documents.ts`: an issue carrying more than 50 documents
+ * silently drops the overflow, which is a deliberate limit rather than a bug.
+ */
+export async function findDocumentByTitle(issue: IssueDocuments, title: string): Promise<DocumentLike | null> {
+  const wanted = title.trim().toLowerCase();
+  if (!wanted) return null;
+  const conn = await issue.documents({ first: 50 });
+  return conn.nodes.find((d) => (d.title ?? "").trim().toLowerCase() === wanted) ?? null;
+}
+
+/** Build the (untyped) activity content payload Linear expects for each activity type. */
+function contentOf(a: Activity): Record<string, unknown> {
+  switch (a.type) {
+    case "thought":
+      return { type: AgentActivityType.Thought, body: a.text };
+    case "response":
+      return { type: AgentActivityType.Response, body: a.text };
+    case "error":
+      return { type: AgentActivityType.Error, body: a.text };
+    case "action": {
+      // DHK-382: render as a human verb + humanised parameter ("Ran · grep ...") instead of the
+      // tool name plus raw JSON. formatToolAction is total and defensive: a malformed/truncated
+      // preview degrades to the bare verb rather than throwing or posting raw JSON.
+      const { action, parameter } = formatToolAction(a.tool, a.text);
+      // DHK-385: fold the tool's outcome under the call as the action's `result` (markdown) when the
+      // observation has arrived, so the step is one self-contained activity instead of a call plus a
+      // separate observation row. Omitted while the action is still in flight (no result yet).
+      return { type: AgentActivityType.Action, action, parameter, ...(a.result ? { result: a.result } : {}) };
+    }
+  }
+}
+
+/** Normalise an elicitation option into Linear's `{ label?, value }` shape. */
+function optionOf(o: ElicitOption): { label?: string; value: string } {
+  return typeof o === "string" ? { value: o } : { ...(o.label ? { label: o.label } : {}), value: o.value };
+}
+
+export function createLinearClient(token: string): AgentSessionClient {
+  const client = new LinearClient({ accessToken: token });
+  // viewer.id is stable for the life of a Connection token; resolve it once and reuse.
+  let cachedAppUserId: string | undefined;
+  return {
+    async postActivity(sessionId, activity) {
+      await client.createAgentActivity({
+        agentSessionId: sessionId,
+        content: contentOf(activity),
+        // Only thought/action may be ephemeral; the caller guarantees this, Linear ignores it otherwise.
+        ...(activity.ephemeral ? { ephemeral: true } : {}),
+      });
+    },
+    async raiseElicitation(sessionId, prompt, options) {
+      await client.createAgentActivity({
+        agentSessionId: sessionId,
+        content: { type: AgentActivityType.Elicitation, body: prompt },
+        signal: AgentActivitySignal.Select,
+        ...(options ? { signalMetadata: { options: options.map(optionOf) } } : {}),
+      });
+    },
+    async suggestRepositories(issueId, candidates) {
+      // Linear ranks the candidates we already have access to; we keep its order and never re-sort by
+      // confidence ourselves (ordering only - the human picks). `hostname` is required by the API.
+      const payload = await client.issueRepositorySuggestions(
+        candidates.map((c) => ({ hostname: c.hostname ?? "", repositoryFullName: c.repositoryFullName })),
+        issueId,
+      );
+      return payload.suggestions.map((s) => ({
+        repositoryFullName: s.repositoryFullName,
+        ...(s.hostname ? { hostname: s.hostname } : {}),
+        confidence: s.confidence,
+      }));
+    },
+    async addIssueLabel(issueId, name) {
+      // Get-or-create the label by name (issueAddLabel needs an id), then attach it. Idempotent:
+      // createIssueLabel only runs when the name is absent, and issueAddLabel no-ops on a label the
+      // issue already carries, so a repeat stamp is a safe no-op.
+      const labels = await client.issueLabels();
+      while (labels.pageInfo.hasNextPage) await labels.fetchNext();
+      let labelId = labels.nodes.find((l) => l.name === name)?.id;
+      if (!labelId) {
+        const created = await client.createIssueLabel({ name });
+        labelId = (await created.issueLabel)?.id;
+      }
+      if (labelId) await client.issueAddLabel(issueId, labelId);
+    },
+    async requestAuth(sessionId, prompt, auth) {
+      // The `auth` signal renders Linear's native account-linking UI from an elicitation; the user
+      // completes the link at `auth.url`, then the agent resumes on the follow-up `prompted` webhook.
+      await client.createAgentActivity({
+        agentSessionId: sessionId,
+        content: { type: AgentActivityType.Elicitation, body: prompt },
+        signal: AgentActivitySignal.Auth,
+        signalMetadata: {
+          url: auth.url,
+          ...(auth.userId ? { userId: auth.userId } : {}),
+          ...(auth.providerName ? { providerName: auth.providerName } : {}),
+        },
+      });
+    },
+    async startIssue(sessionId): Promise<StartIssueOutcome> {
+      // Resolve the issue from the session itself, so no issue id has to be threaded through the engine.
+      const session = await client.agentSession(sessionId);
+      const issue = await session.issue;
+      if (!issue) return { moved: false, reason: "no-issue" };
+      // Self-delegate (idempotent: assignment already sets the app as delegate; @mention does not).
+      // Split from the state move below so a failure of one does not sink the other (a rejected
+      // delegate write must not block moving the ticket to In Progress, and vice-versa).
+      const me = await client.viewer;
+      // DHK-263: only write delegateId when not already delegated to us. Re-writing when equal
+      // regenerates the "assigned to you" notification on every re-run of an already-delegated issue.
+      if (shouldSetDelegate(issue.delegateId, me.id)) {
+        await client.updateIssue(issue.id, { delegateId: me.id }).catch((e: unknown) => {
+          console.warn(`startIssue self-delegate failed for ${sessionId}: ${e instanceof Error ? e.message : String(e)}`);
+        });
+      }
+      // Move to the team's working state, but only from a not-yet-started status.
+      const current = await issue.state;
+      if (!current || current.type === "started" || current.type === "completed" || current.type === "canceled") {
+        return { moved: false, reason: "already-active" };
+      }
+      const team = await issue.team;
+      if (!team) return { moved: false, reason: "no-team" };
+      // Fetch states UNFILTERED and disambiguate in JS. This is a SEMANTIC need, not an SDK-filter
+      // workaround: the team has TWO `started`-typed states (In Progress AND In Review), so even a
+      // working server-side `filter: { type: { eq: "started" } }` returns both - the wrong answer.
+      // (Verified on @linear/sdk 86.0.0, DHK-579: that filter now returns both `In Progress` and
+      // `In Review`.) selectStartState excludes the review state and prefers the working one
+      // (DHK-258). Do NOT "simplify" this to a server-side filter - it would re-introduce the bug.
+      const states = [...(await team.states()).nodes];
+      const pick = selectStartState(states, reviewStateNameEnv());
+      if (!pick) return { moved: false, reason: "no-started-state" };
+      try {
+        await client.updateIssue(issue.id, { stateId: pick.id });
+      } catch (e: unknown) {
+        console.warn(`startIssue state move failed for ${sessionId}: ${e instanceof Error ? e.message : String(e)}`);
+        return { moved: false, reason: "update-failed" };
+      }
+      return { moved: true, stateName: pick.name };
+    },
+    async moveIssueToReview(sessionId): Promise<MoveToReviewOutcome> {
+      const session = await client.agentSession(sessionId);
+      const issue = await session.issue;
+      if (!issue) return { moved: false, reason: "no-issue" };
+      // Never disturb a closed issue.
+      const current = await issue.state;
+      if (current && (current.type === "completed" || current.type === "canceled")) {
+        return { moved: false, reason: "already-there" };
+      }
+      const team = await issue.team;
+      if (!team) return { moved: false, reason: "no-team" };
+      // Linear has no "review" state TYPE, so match by name (shared with `startIssue`'s exclusion via
+      // `findReviewState`): an explicit configured name, else the first review-ish name. No match =
+      // leave the issue in `started` (never auto-complete), so a human keeps iterating and can
+      // re-summon @Dahrk on the same PR. DHK-283: a no-match is now RETURNED as `no-review-state`
+      // (not a silent void) so the caller can surface it, since a team with no review-ish state would
+      // otherwise sit In Progress unremarked.
+      const states = [...(await team.states()).nodes].sort((a, b) => a.position - b.position);
+      const pick = findReviewState(states, reviewStateNameEnv());
+      if (!pick) return { moved: false, reason: "no-review-state" };
+      // Already in the review state: nothing to do, and benign (a re-run of an already-reviewed issue).
+      if (current && pick.id === current.id) return { moved: false, reason: "already-there" };
+      try {
+        await client.updateIssue(issue.id, { stateId: pick.id });
+      } catch (e: unknown) {
+        console.warn(`moveIssueToReview state move failed for ${sessionId}: ${e instanceof Error ? e.message : String(e)}`);
+        return { moved: false, reason: "update-failed" };
+      }
+      return { moved: true, stateName: pick.name };
+    },
+    async commentOnIssue(sessionId, body) {
+      // A normal top-level issue comment (not an agent activity), so a run summary lands in the
+      // issue's comment thread where a human reads it, rather than only in the agent session panel.
+      const session = await client.agentSession(sessionId);
+      const issue = await session.issue;
+      if (!issue) return;
+      await client.createComment({ issueId: issue.id, body });
+    },
+    async attachPr(sessionId, pr: PrAttachment) {
+      // Idempotent by URL: Linear's `attachmentCreate` upserts on (issueId, url) - a second call with
+      // the same `pr.url` on the same issue UPDATES the existing attachment rather than creating a
+      // duplicate. This is what lets the host loop retry `open-pr` (e.g. after a crash/replay) without
+      // littering the issue with duplicate PR attachments; the reporter relies on the same invariant.
+      const session = await client.agentSession(sessionId);
+      const issue = await session.issue;
+      if (!issue) return;
+      await client.createAttachment({
+        issueId: issue.id,
+        url: pr.url,
+        title: pr.title,
+        ...(pr.subtitle ? { subtitle: pr.subtitle } : {}),
+        ...(pr.iconUrl ? { iconUrl: pr.iconUrl } : {}),
+      });
+    },
+    async createDocument(sessionId, doc: DocumentInput): Promise<DocumentRef> {
+      // Resolve the issue from the session so no issue id has to be threaded through the engine,
+      // mirroring attachPr. `documentCreate` with an issueId links the document to the issue.
+      const session = await client.agentSession(sessionId);
+      const issue = await session.issue;
+
+      // Idempotent by (issueId, title). Unlike `attachmentCreate`, Linear's `documentCreate` has NO
+      // upsert semantics - title is not a key - so we emulate one: look for a document already on
+      // this issue with the same title and UPDATE it rather than creating a second. Without this, a
+      // continuation run (which re-runs the workflow from stage 0 with a fresh runId, and so a fresh
+      // `attach-document:<runId>` journal key) stacks another copy of the same report on the issue.
+      // The caveat this buys: a human-authored document on the same issue that happens to carry the
+      // workflow's title is overwritten. Title collision on one issue is the accepted trade for not
+      // littering the issue with near-duplicate reports; Linear keeps document history either way.
+      if (issue) {
+        const existing = await findDocumentByTitle(issue, doc.title);
+        if (existing) {
+          await client.updateDocument(existing.id, { title: doc.title, content: doc.content });
+          return { id: existing.id, url: existing.url ?? "" };
+        }
+      }
+
+      const payload = await client.createDocument({
+        title: doc.title,
+        content: doc.content,
+        ...(issue ? { issueId: issue.id } : {}),
+      });
+      const created = await payload.document;
+      return { id: created?.id ?? payload.documentId ?? "", url: created?.url ?? "" };
+    },
+    async setPlan(sessionId, items) {
+      // Linear expects the plan as a full array of { content, status } steps (replaced wholesale),
+      // NOT a wrapper object. Our PlanItem.status values (pending|inProgress|completed|canceled)
+      // already match Linear's enum; show the human title (falling back to the stage id) as content.
+      await client.updateAgentSession(sessionId, {
+        plan: items.map((i) => ({ content: i.title ?? i.stageId, status: i.status })),
+      });
+    },
+    async setExternalUrls(sessionId, urls) {
+      // Linear rejects non-http(s) URLs (e.g. internal skakel:// run refs) and requires each URL to be
+      // unique; filterExternalUrls drops the rest. The array is replaced wholesale, so no-op on empty
+      // rather than clobber any existing links with nothing.
+      const valid = filterExternalUrls(urls);
+      if (valid.length === 0) return;
+      await client.updateAgentSession(sessionId, { externalUrls: valid });
+    },
+    async setState() {
+      // Linear derives the agent-session state from activities/signals; not app-settable.
+    },
+    async readIssueEngagement(issueIds): Promise<Map<string, IssueEngagement>> {
+      const out = new Map<string, IssueEngagement>();
+      const ids = [...new Set(issueIds.filter((id) => id))];
+      if (ids.length === 0) return out;
+      // One rawRequest per <=100-id chunk (a single query per chunk, not per issue), so a sweep over
+      // many in-flight runs stays rate-limit friendly. An id that Linear does not return is left out
+      // of the map, which the caller reads as "deleted".
+      for (let i = 0; i < ids.length; i += 100) {
+        const chunk = ids.slice(i, i + 100);
+        const res = await client.client.rawRequest<
+          { issues?: { nodes?: IssueEngagementRow[] } },
+          { ids: string[] }
+        >(ISSUE_ENGAGEMENT_QUERY, { ids: chunk });
+        // A GraphQL error that did not throw must NOT be read as "no issues" (which the caller would
+        // treat as every issue deleted). Surface it so the sweep skips this connection this tick.
+        if (!res.data && res.errors?.length) {
+          throw new Error(`readIssueEngagement: ${res.errors.map((e) => e?.message ?? "error").join("; ")}`);
+        }
+        for (const n of res.data?.issues?.nodes ?? []) {
+          if (!n.id) continue;
+          out.set(n.id, {
+            present: true,
+            archived: Boolean(n.archivedAt),
+            ...(n.state?.type ? { stateType: n.state.type as IssueStateType } : {}),
+            ...(n.assignee?.id ? { assigneeId: n.assignee.id } : {}),
+            ...(n.delegateId ? { delegateId: n.delegateId } : {}),
+          });
+        }
+      }
+      return out;
+    },
+    async appUserId(): Promise<string> {
+      if (cachedAppUserId === undefined) cachedAppUserId = (await client.viewer).id;
+      return cachedAppUserId;
+    },
+    async createSessionOnIssue(issueId): Promise<string> {
+      // DHK-63: proactively open an agent session on an issue (not delegated/@mentioned). The typed SDK
+      // does not surface these mutations, so raw GraphQL, selecting the new session id off the returned
+      // AgentSessionPayload. Surface a GraphQL error rather than returning a blank id.
+      const res = await client.client.rawRequest<
+        { agentSessionCreateOnIssue?: { agentSession?: { id?: string } } },
+        { input: { issueId: string } }
+      >(SESSION_CREATE_ON_ISSUE, { input: { issueId } });
+      const id = res.data?.agentSessionCreateOnIssue?.agentSession?.id;
+      if (!id) {
+        throw new Error(
+          `agentSessionCreateOnIssue: ${res.errors?.map((e) => e?.message ?? "error").join("; ") ?? "no session id returned"}`,
+        );
+      }
+      return id;
+    },
+    async createSessionOnComment(commentId): Promise<string> {
+      const res = await client.client.rawRequest<
+        { agentSessionCreateOnComment?: { agentSession?: { id?: string } } },
+        { input: { commentId: string } }
+      >(SESSION_CREATE_ON_COMMENT, { input: { commentId } });
+      const id = res.data?.agentSessionCreateOnComment?.agentSession?.id;
+      if (!id) {
+        throw new Error(
+          `agentSessionCreateOnComment: ${res.errors?.map((e) => e?.message ?? "error").join("; ") ?? "no session id returned"}`,
+        );
+      }
+      return id;
+    },
+  };
+}

package/src/oauth.ts

@@ -0,0 +1,194 @@
+/**
+ * Linear OAuth 2.0 helpers for the agent install + token rotation (build spec section 14).
+ *
+ * An agent becomes assignable/mentionable in a workspace only while the app is INSTALLED via
+ * the authorization-code flow with `actor=app` and the `app:assignable` / `app:mentionable`
+ * scopes (admin consent). That flow also yields the access + refresh tokens the hub posts with.
+ * Access tokens last ~24h, so the hub refreshes them with the refresh token (see the hub's
+ * `resolveClient`). Token grants use plain `fetch`; post-token reads use the typed LinearClient.
+ */
+import { LinearClient } from "@linear/sdk";
+
+const AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+const TOKEN_URL = "https://api.linear.app/oauth/token";
+
+/** The agent scopes: read/write plus the two that make the app assignable + mentionable. */
+export const DEFAULT_AGENT_SCOPES = ["read", "write", "app:assignable", "app:mentionable"] as const;
+
+export interface LinearTokens {
+  accessToken: string;
+  /** Absent on some refresh responses; callers keep the prior refresh token when so. */
+  refreshToken?: string;
+  /** When the access token expires (computed from `expires_in`). */
+  expiresAt: Date;
+  scope?: string;
+}
+
+/**
+ * Build the Linear consent URL. The admin opens this; approving installs the agent (with
+ * `actor=app`) and redirects to `redirectUri?code=...&state=...`. `state` is opaque here - the
+ * caller signs it (CSRF) and recovers the connection from it in the callback.
+ */
+export function authorizeUrl(params: {
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  scopes?: readonly string[];
+  actor?: "app" | "user";
+  /** `"consent"` (default) forces Linear's consent screen every time - right for the `actor=app`
+   *  install (re-grants and re-issues a refresh token, and lets an admin connect another workspace).
+   *  `"auto"` omits the `prompt` param so Linear only prompts when scopes are not already granted -
+   *  right for the `actor=user` sign-in, so a returning user is not made to re-authorise on every login. */
+  prompt?: "consent" | "auto";
+}): string {
+  const u = new URL(AUTHORIZE_URL);
+  u.searchParams.set("client_id", params.clientId);
+  u.searchParams.set("redirect_uri", params.redirectUri);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("scope", (params.scopes ?? DEFAULT_AGENT_SCOPES).join(","));
+  u.searchParams.set("state", params.state);
+  u.searchParams.set("actor", params.actor ?? "app");
+  if ((params.prompt ?? "consent") === "consent") u.searchParams.set("prompt", "consent");
+  return u.toString();
+}
+
+interface TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+  error?: string;
+  error_description?: string;
+}
+
+async function postToken(body: Record<string, string>, now: () => Date): Promise<LinearTokens> {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(body).toString(),
+  });
+  const json = (await res.json().catch(() => ({}))) as TokenResponse;
+  if (!res.ok || !json.access_token) {
+    const detail = json.error_description || json.error || `${res.status}`;
+    throw new Error(`linear token endpoint failed: ${detail}`);
+  }
+  const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 86_399;
+  return {
+    accessToken: json.access_token,
+    ...(json.refresh_token ? { refreshToken: json.refresh_token } : {}),
+    expiresAt: new Date(now().getTime() + expiresIn * 1000),
+    ...(json.scope ? { scope: json.scope } : {}),
+  };
+}
+
+/** Exchange the callback `code` for access + refresh tokens (one-time, at install). */
+export function exchangeCode(
+  params: { clientId: string; clientSecret: string; code: string; redirectUri: string },
+  now: () => Date = () => new Date(),
+): Promise<LinearTokens> {
+  return postToken(
+    {
+      grant_type: "authorization_code",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      code: params.code,
+      redirect_uri: params.redirectUri,
+    },
+    now,
+  );
+}
+
+/**
+ * Personal API keys start with `lin_api_` and must be sent as `apiKey` (not Bearer accessToken).
+ * OAuth access tokens use `accessToken` so LinearClient adds the Bearer prefix automatically.
+ */
+function makeLinearClient(token: string): LinearClient {
+  return token.startsWith("lin_api_")
+    ? new LinearClient({ apiKey: token })
+    : new LinearClient({ accessToken: token });
+}
+
+/**
+ * Resolve the workspace (organization) id the access token belongs to. Used at install to backfill
+ * a connection's `workspaceIds` from the token, so an operator need not paste the org id by hand and
+ * intake can match the workspace on the very first webhook.
+ */
+export async function fetchOrganizationId(accessToken: string): Promise<string> {
+  const client = makeLinearClient(accessToken);
+  const org = await client.organization;
+  return org.id;
+}
+
+/** The agent identity + bound workspace a token resolves to, for the connection Probe. */
+export interface LinearProbe {
+  /** `email` (verified, owned by Linear) is the cross-provider account join key; `admin` is captured
+   *  now for later permission gating (unused at launch). Both are non-null on Linear's `User` type but
+   *  optional here so a partial/legacy probe response never throws. */
+  viewer?: { id: string; name?: string; email?: string; admin?: boolean };
+  organization?: { id: string; name?: string; urlKey?: string };
+}
+
+/**
+ * Probe a stored access token: query `viewer` (the app/agent user) and `organization` (the bound
+ * workspace) so the portal can confirm a connection's token is valid and show which workspace it
+ * binds to. Throws on an auth failure / GraphQL error, which the caller renders as "token invalid".
+ */
+export async function probeToken(accessToken: string): Promise<LinearProbe> {
+  const client = makeLinearClient(accessToken);
+  const [viewer, org] = await Promise.all([client.viewer, client.organization]);
+  const probe: LinearProbe = {};
+  if (viewer?.id) {
+    probe.viewer = {
+      id: viewer.id,
+      ...(viewer.name ? { name: viewer.name } : {}),
+      ...(viewer.email ? { email: viewer.email } : {}),
+      ...(typeof viewer.admin === "boolean" ? { admin: viewer.admin } : {}),
+    };
+  }
+  if (org?.id) {
+    probe.organization = {
+      id: org.id,
+      ...(org.name ? { name: org.name } : {}),
+      ...(org.urlKey ? { urlKey: org.urlKey } : {}),
+    };
+  }
+  return probe;
+}
+
+/** Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401). */
+export function refreshTokens(
+  params: { clientId: string; clientSecret: string; refreshToken: string },
+  now: () => Date = () => new Date(),
+): Promise<LinearTokens> {
+  return postToken(
+    {
+      grant_type: "refresh_token",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      refresh_token: params.refreshToken,
+    },
+    now,
+  );
+}
+
+/**
+ * Mint an `app` actor token via the `client_credentials` grant: headless (no user, no redirect, no
+ * callback, no refresh token), scoped to the app's workspace, valid ~30 days. Linear's documented
+ * renewal is simply to mint a fresh one on a 401/expiry. Requires the app's "Client credentials"
+ * toggle to be enabled. This is the durable token path for a headless agent, vs the interactive
+ * authorization-code flow (24h token + fragile refresh + "already installed" install UX).
+ */
+export function mintAppToken(
+  params: { clientId: string; clientSecret: string; scopes?: readonly string[] },
+  now: () => Date = () => new Date(),
+): Promise<LinearTokens> {
+  return postToken(
+    {
+      grant_type: "client_credentials",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      scope: (params.scopes ?? DEFAULT_AGENT_SCOPES).join(","),
+    },
+    now,
+  );
+}