@dahrk/linear 0.1.0 → 0.2.0

package/src/linear-client.ts

@@ -0,0 +1,448 @@
+/**
+ * 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. This package has no dependency on the hub, so it cannot reuse the
+ *  hub's `envValue`. The pre-rename legacy twin was dropped: no current host sets it. */
+function reviewStateNameEnv(): string | undefined {
+  return process.env.DAHRK_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;
+    },
+  };
+}