@dahrk/linear 0.1.0 → 0.2.0

package/src/index.ts

@@ -0,0 +1,617 @@
+/**
+ * @dahrk/linear - the Linear-native control surface (build spec section 14).
+ *
+ * Two responsibilities:
+ *  1. Intake-side (used by the hub): verify the webhook signature, and normalise a
+ *     raw Linear webhook into the internal LinearEvent. tenantId/workspaceId are
+ *     resolved from the authenticated connection, never from the payload.
+ *  2. Session-side (used by hub + edge): drive the Agent Session API natively -
+ *     post activities (thought/action/response), render the stage graph as the
+ *     agent-plan checklist, raise elicitation gates, take prompted-drive turns,
+ *     handle the stop signal, set externalUrls.
+ *
+ * Re-implemented directly against the Agent Session API; cyrus's posting code is a
+ * reference, not a dependency. Intended runtime dep: the Linear TypeScript SDK
+ * (added at M2/M5).
+ */
+import type { LinearEvent } from "@dahrk/contracts";
+import { LinearWebhookClient } from "@linear/sdk/webhooks";
+import type {
+  LinearWebhookPayload,
+  AgentSessionEventWebhookPayload,
+  AppUserNotificationWebhookPayloadWithNotification,
+  EntityWebhookPayloadWithIssueData,
+} from "@linear/sdk/webhooks";
+
+/**
+ * Verify a Linear webhook signature and timestamp freshness, then return the parsed
+ * payload, or throw. Delegates to LinearWebhookClient.parseData which uses
+ * HMAC-SHA256 + timingSafeEqual. The webhookTimestamp field is extracted from the
+ * raw body so the SDK's built-in ±60 s replay window applies; a missing or
+ * non-numeric timestamp skips the freshness check. Throws "Invalid webhook
+ * signature" on bad HMAC and "Invalid webhook timestamp" on a stale delivery.
+ */
+export function verifyWebhook(rawBody: Buffer, signature: string, secret: string): unknown {
+  // Extract webhookTimestamp so parseData can enforce the ±60 s replay window.
+  // If the body is not valid JSON or the field is absent, we omit the argument and
+  // parseData skips the check (same as a missing timestamp in the old hand-rolled path).
+  let ts: number | undefined;
+  try {
+    const raw = (JSON.parse(rawBody.toString("utf8")) as { webhookTimestamp?: unknown }).webhookTimestamp;
+    if (typeof raw === "number") ts = raw;
+    else if (typeof raw === "string") {
+      const n = Number(raw);
+      if (Number.isFinite(n)) ts = n;
+    }
+  } catch {
+    /* non-JSON body – parseData will re-parse and also throw */
+  }
+  return new LinearWebhookClient(secret).parseData(rawBody, signature, ts);
+}
+
+/**
+ * Strip a leading @mention token from a triggering comment body (DHK-322), returning the bare
+ * instruction (trimmed). Two spellings are handled: a plain-text `@name` prefix (the structured
+ * `agentSession.comment.body` form) and a leading Linear `<user id="...">name</user>` element (the
+ * `promptContext` primary-directive-thread form). A body that is only the mention yields "". Pure, so
+ * the instruction parsing is unit-testable and free of an LLM.
+ */
+function stripLeadingMention(body: string): string {
+  let text = body.replace(/^\s+/, "");
+  const userMatch = /^<user\b[^>]*>[\s\S]*?<\/user>/.exec(text);
+  if (userMatch) text = text.slice(userMatch[0].length);
+  else text = text.replace(/^@\S+/, "");
+  return text.trim();
+}
+
+/**
+ * Parse the triggering comment out of a `promptContext` primary-directive-thread (DHK-322): the
+ * `comment-id` attribute plus the last `<comment>` body (the triggering message), with its leading
+ * mention stripped. The fallback path when the webhook carries no structured `agentSession.comment`.
+ * Pure.
+ */
+function directiveFromPromptContext(promptContext: string): { commentId?: string; instruction?: string } {
+  const block = /<primary-directive-thread\b([^>]*)>([\s\S]*?)<\/primary-directive-thread>/.exec(promptContext);
+  if (!block) return {};
+  const commentId = /\bcomment-id="([^"]*)"/.exec(block[1] ?? "")?.[1]?.trim();
+  const comments = [...(block[2] ?? "").matchAll(/<comment\b[^>]*>([\s\S]*?)<\/comment>/g)];
+  const lastBody = comments.at(-1)?.[1];
+  const instruction = lastBody !== undefined ? stripLeadingMention(lastBody) : undefined;
+  return {
+    ...(commentId ? { commentId } : {}),
+    ...(instruction ? { instruction } : {}),
+  };
+}
+
+/**
+ * Compute the NAMES of the labels newly added by an `Issue`/`update` webhook (DHK-93). Positive
+ * evidence only: `updatedFrom` must carry a `labelIds` array (the pre-change set) - a title/description
+ * edit that never touched labels carries none, so it yields []. The new set is read from `data.labelIds`
+ * (falling back to the ids on `data.labels`), the added ids are the new-set minus the old-set, and each
+ * added id is resolved to a name via `data.labels` (`[{id,name}]`). An added id with no resolvable name
+ * is dropped, so a payload we cannot name from produces no false trigger. Pure; no LLM.
+ */
+function addedLabelNames(
+  data: Record<string, unknown> | undefined,
+  updatedFrom: Record<string, unknown> | null | undefined,
+): string[] {
+  if (!data || !updatedFrom) return [];
+  const oldIds = updatedFrom.labelIds;
+  if (!Array.isArray(oldIds)) return []; // labels were not part of this change
+  const oldSet = new Set(oldIds.filter((v): v is string => typeof v === "string"));
+  const labels = Array.isArray(data.labels)
+    ? (data.labels as unknown[]).filter(
+        (l): l is { id?: string; name?: string } => !!l && typeof l === "object",
+      )
+    : [];
+  const nameById = new Map<string, string>();
+  for (const l of labels) {
+    if (typeof l.id === "string" && typeof l.name === "string") nameById.set(l.id, l.name);
+  }
+  const newIds = Array.isArray(data.labelIds)
+    ? (data.labelIds as unknown[]).filter((v): v is string => typeof v === "string")
+    : labels.map((l) => l.id).filter((v): v is string => typeof v === "string");
+  const names: string[] = [];
+  for (const id of newIds) {
+    if (oldSet.has(id)) continue; // pre-existing, not part of the delta
+    const name = nameById.get(id);
+    if (name !== undefined) names.push(name);
+  }
+  return names;
+}
+
+/** Fixed 👍/👎 -> sentiment lookup. A reaction's sentiment comes from this table, never an LLM, so the
+ *  determinism boundary holds. Returns undefined for any emoji we do not treat as feedback. */
+function reactionSentiment(emoji: string | undefined): "positive" | "negative" | undefined {
+  if (!emoji) return undefined;
+  if (emoji === "👍" || emoji === "+1" || emoji === "thumbsup") return "positive";
+  if (emoji === "👎" || emoji === "-1" || emoji === "thumbsdown") return "negative";
+  return undefined;
+}
+
+/**
+ * Normalise a verified webhook into the internal LinearEvent. `workspaceId` is read
+ * from the payload but only trusted once `authenticate` checks it against the
+ * connection's registered set. `tenantId` is supplied by the caller from the owning
+ * Connection (the single source of truth for a workspace's tenant), never inferred here.
+ */
+export function normalise(payload: LinearWebhookPayload, connectionId: string, tenantId: string): LinearEvent {
+  const ts = new Date(payload.webhookTimestamp).toISOString();
+  const base = {
+    tenantId,
+    connectionId,
+    workspaceId: payload.organizationId,
+    linearPayload: payload,
+    ts,
+  } as const;
+
+  if (payload.type === "AgentSessionEvent" || payload.type === "AgentSession") {
+    // Narrow to the AgentSessionEvent shape; "AgentSession" is a legacy alias Linear still emits.
+    const p = payload as AgentSessionEventWebhookPayload;
+    // Linear's webhook body nests the issue under `agentSession.issue.id`; the SDK type models it
+    // flattened as `agentSession.issueId`. Tolerate both so the issue id survives for routing.
+    const agentSession = p.agentSession as {
+      id: string;
+      issueId?: string | null;
+      issue?: { id?: string; delegateId?: string | null; delegate?: { id?: string } | null } | null;
+      appUser?: { id?: string } | null;
+      comment?: { id?: string; body?: string } | null;
+    };
+    const agentSessionId = agentSession.id;
+    const issueId = agentSession.issueId ?? agentSession.issue?.id ?? undefined;
+    if (p.action === "created") {
+      // DHK-322: classify the trigger modality deterministically from the payload alone. An @mention
+      // leaves the issue delegated to someone other than the app; a delegate/assign delegates it to the
+      // app itself (mirrors `shouldSetDelegate`). When the app user id cannot be resolved, default to
+      // `delegate` - the safe default is today's labelled pipeline, never mis-routing a real assignment
+      // to converse. No LLM: this is a pure id comparison.
+      const appUserId = agentSession.appUser?.id ?? undefined;
+      const issueDelegateId = agentSession.issue?.delegateId ?? agentSession.issue?.delegate?.id ?? undefined;
+      const trigger: "delegate" | "mention" =
+        appUserId !== undefined && issueDelegateId !== appUserId ? "mention" : "delegate";
+      // The instruction rides the triggering comment: prefer the structured `agentSession.comment`,
+      // else parse it out of the promptContext primary-directive-thread. The leading @mention is
+      // stripped so a bare mention yields no instruction.
+      const structured = agentSession.comment;
+      const promptContext = (payload as { promptContext?: unknown }).promptContext;
+      const directive = typeof promptContext === "string" ? directiveFromPromptContext(promptContext) : {};
+      const structuredInstruction =
+        structured?.body !== undefined ? stripLeadingMention(structured.body) : undefined;
+      const instruction =
+        (structuredInstruction && structuredInstruction.length > 0 ? structuredInstruction : undefined) ??
+        directive.instruction;
+      const commentId = structured?.id ?? directive.commentId;
+      // Carry the issue id so the hub can map issue -> run (for later Inbox-notification routing).
+      return {
+        ...base,
+        type: "agent-session-created",
+        trigger,
+        subject: { agentSessionId, ...(issueId ? { issueId } : {}), ...(commentId ? { commentId } : {}) },
+        ...(instruction ? { instruction } : {}),
+      };
+    }
+    if (p.action === "prompted") {
+      return { ...base, type: "agent-session-prompted", subject: { agentSessionId } };
+    }
+    if (p.action === "stopped" || p.action === "stop") {
+      return { ...base, type: "signal-stop", subject: { agentSessionId } };
+    }
+    // The session was archived or deleted (the human tore the agent off the issue). Linear does not
+    // guarantee an Inbox notification for this, but when it sends the raw AgentSession action we can
+    // stop the run it drives directly. Carry the issue id when present so the run can also be found by
+    // issue if the session map is stale.
+    if (p.action === "archived" || p.action === "deleted") {
+      return {
+        ...base,
+        type: "session-archived",
+        subject: { agentSessionId, ...(issueId ? { issueId } : {}) },
+      };
+    }
+  }
+
+  if (payload.type === "AppUserNotification") {
+    const p = payload as AppUserNotificationWebhookPayloadWithNotification;
+    // The notification-kind discriminator is carried at the top-level `action` on the real webhook
+    // body (the SDK only models it as `notification.type`, which the live payload omits). Read from
+    // `action`, and tolerate the alternate field spellings the live body uses for issue id, reaction
+    // emoji, and status type.
+    const action = p.action;
+    const n = p.notification as {
+      type?: string;
+      issueId?: string;
+      issue?: { id?: string; state?: { type?: string } } | null;
+      issueStatusType?: string;
+      reactionEmoji?: string;
+      reaction?: { emoji?: string } | null;
+      emoji?: string;
+    };
+    const issueId = n.issueId ?? n.issue?.id ?? "";
+
+    // Inbox notification: the agent was unassigned from an issue -> disengage (stop its run).
+    if (action === "issueUnassignedFromYou") {
+      return { ...base, type: "issue-unassigned", subject: { issueId } };
+    }
+    // Inbox notification: the issue's status changed. A move to a *canceled* or *completed* workflow-state
+    // type is a disengagement signal (stop its run); any other status change falls through to ignored.
+    // (A completed move only settles a run parked at a gate; that gate-open rule lives on the hub side.)
+    if (action === "issueStatusChanged") {
+      const stateType = n.issue?.state?.type ?? n.issueStatusType;
+      if (stateType === "canceled") {
+        return { ...base, type: "issue-canceled", subject: { issueId } };
+      }
+      if (stateType === "completed") {
+        return { ...base, type: "issue-completed", subject: { issueId } };
+      }
+    }
+    // Inbox notification: a 👍/👎 reaction on a Dahrk response -> a feedback signal. A non-thumb emoji
+    // falls through to ignored (never mis-dispatched).
+    if (action === "issueEmojiReaction" || action === "issueCommentReaction") {
+      const reaction = reactionSentiment(n.reactionEmoji ?? n.reaction?.emoji ?? n.emoji);
+      if (reaction) {
+        return { ...base, type: "issue-reaction", subject: { issueId }, reaction };
+      }
+    }
+  }
+
+  // The OAuth app install was revoked: the connection is dead, deactivate it. No subject needed.
+  if (payload.type === "OAuthApp" && payload.action === "revoked") {
+    return { ...base, type: "oauth-revoked", subject: {} };
+  }
+
+  // Permission Changes webhook: the Connection's set of accessible teams changed. Like `oauth-revoked`
+  // it is about the Connection, not an issue/session, so the subject is empty; the added/removed team
+  // deltas ride on `teamAccess` for the hub to merge into the Connection's tracked set. The SDK's
+  // webhook union does not model `PermissionChange`, so cast the payload (same pattern as the
+  // AppUserNotification branch above). Defensive: default missing deltas to [] and the flag to false.
+  if (payload.type === "PermissionChange" && payload.action === "teamAccessChanged") {
+    const p = payload as unknown as {
+      addedTeamIds?: string[];
+      removedTeamIds?: string[];
+      canAccessAllPublicTeams?: boolean;
+    };
+    return {
+      ...base,
+      type: "team-access-changed",
+      subject: {},
+      teamAccess: {
+        addedTeamIds: p.addedTeamIds ?? [],
+        removedTeamIds: p.removedTeamIds ?? [],
+        canAccessAllPublicTeams: p.canAccessAllPublicTeams ?? false,
+      },
+    };
+  }
+
+  // Issue SLA webhook (DHK-63): a proactive trigger. Only `breached` is actionable (a pre-brief
+  // enrichment worth running); `set`/`highRisk` are lifecycle noise and fall through to the throw so
+  // they never spawn a session. The SDK's webhook union does not model `IssueSLA`, so cast to read the
+  // serialised issue (`issueData`), tolerating the field spellings the live body may use for the id.
+  if (payload.type === "IssueSLA" || payload.type === "Issue SLA") {
+    const p = payload as unknown as {
+      action?: string;
+      issueData?: { id?: string } | null;
+      issueId?: string;
+      issue?: { id?: string } | null;
+      data?: { id?: string } | null;
+    };
+    if (p.action === "breached") {
+      const issueId = p.issueData?.id ?? p.issueId ?? p.issue?.id ?? p.data?.id ?? "";
+      return { ...base, type: "sla-breach", subject: { issueId } };
+    }
+  }
+
+  if (payload.type === "Issue") {
+    const p = payload as EntityWebhookPayloadWithIssueData & {
+      issue?: { id?: string } | null;
+      data?: (Record<string, unknown> & { state?: { type?: string } | null }) | null;
+      updatedFrom?: Record<string, unknown> | null;
+    };
+    // Live "Issue" entity webhooks carry the issue under `data`; tolerate a top-level `issue` too.
+    const issueId = p.data?.id ?? p.issue?.id ?? "";
+    // An archive is a soft-delete (`archivedAt` set, or an explicit `archived`/`remove` action): treat
+    // it as disengagement so any run parked on the issue is stopped. Any other Issue action is a
+    // create/update we currently only route as `issue-created`.
+    if (p.action === "archived" || p.action === "remove" || p.data?.archivedAt) {
+      return { ...base, type: "issue-archived", subject: { issueId } };
+    }
+    // Triage entry (DHK-63): the issue just MOVED into a triage-typed state - a proactive trigger for
+    // pre-brief enrichment. Conservative on purpose: emit only on positive evidence of an entry (the
+    // current state is `triage` AND `updatedFrom` shows the state changed, i.e. carries `stateId`), so
+    // an ordinary edit on a ticket already in triage still normalises to `issue-created`.
+    if (p.data?.state?.type === "triage" && p.updatedFrom && "stateId" in p.updatedFrom) {
+      return { ...base, type: "triage-entry", subject: { issueId } };
+    }
+    // Label add (DHK-93): a workflow-trigger label was applied. Emit a distinct `label-added` only on
+    // positive evidence - `updatedFrom` carries `labelIds` and at least one added label name resolves -
+    // so a pure removal, or any edit that never touched labels, still falls through to `issue-created`.
+    const addedLabels = addedLabelNames(p.data ?? undefined, p.updatedFrom);
+    if (addedLabels.length > 0) {
+      return { ...base, type: "label-added", subject: { issueId }, addedLabels };
+    }
+    return { ...base, type: "issue-created", subject: { issueId } };
+  }
+
+  throw new Error(`unsupported Linear webhook: type=${payload.type} action=${payload.action}`);
+}
+
+/** A Linear agent-session state, mirrored from the engine's run-state (build spec section 14). */
+export type SessionState = "active" | "awaitingInput" | "complete" | "error";
+
+/** An activity kind posted to the session. `error` rides the same surface as a thought. */
+export type ActivityType = "thought" | "action" | "response" | "error";
+
+/** The result of `startIssue`, so a caller can SEE a no-op/failed state move rather than have it
+ *  silently swallowed (a silent no-op is why the ticket sat in Backlog for a whole run). `moved`
+ *  is true only when the issue was actually transitioned into a working state; otherwise `reason`
+ *  says why not (a benign skip like `already-active` vs a real failure like `no-started-state`). */
+export type StartIssueOutcome =
+  | { moved: true; stateName: string }
+  | { moved: false; reason: StartIssueSkip };
+
+/** Why `startIssue` did not move the issue. The first two are benign (nothing to do); the rest are
+ *  failures a caller should surface. */
+export type StartIssueSkip =
+  | "no-issue"
+  | "already-active"
+  | "no-team"
+  | "no-started-state"
+  | "update-failed";
+
+/** The result of `moveIssueToReview` (DHK-283), so a caller can SEE a no-op instead of the ticket
+ *  silently sitting In Progress. `moved` is true only when the issue was actually transitioned into a
+ *  review state; otherwise `reason` says why not - benign (`already-there`, e.g. a closed issue or one
+ *  already in the review state) vs a real gap (`no-review-state`: this team has no state named
+ *  review/in review/qa and `DAHRK_REVIEW_STATE_NAME` is unset/unmatched). */
+export type MoveToReviewOutcome =
+  | { moved: true; stateName: string }
+  | { moved: false; reason: MoveToReviewSkip };
+
+/** Why `moveIssueToReview` did not move the issue. `no-issue`/`already-there` are benign; the rest are
+ *  gaps a caller should surface as a visible thought. */
+export type MoveToReviewSkip =
+  | "no-issue"
+  | "already-there"
+  | "no-team"
+  | "no-review-state"
+  | "update-failed";
+
+export interface Activity {
+  type: ActivityType;
+  text: string;
+  /** For `action` activities, the tool name. */
+  tool?: string;
+  /** For `action` activities, the tool's outcome folded under the call (markdown, DHK-385). Set once
+   *  the call completes so the step reads as one self-contained activity: verb + parameter on top,
+   *  result underneath. Ignored for non-action types. */
+  result?: string;
+  /** thought/action only: a transient state, replaced in the UI by the next activity. */
+  ephemeral?: boolean;
+}
+
+export interface PlanItem {
+  stageId: string;
+  status: "pending" | "inProgress" | "completed" | "canceled";
+  /** Human-readable label shown in Linear's checklist; falls back to `stageId` when absent. */
+  title?: string;
+}
+
+/** An elicitation choice: a bare value, or a labelled value (the label is what the user sees). */
+export type ElicitOption = string | { label?: string; value: string };
+
+/** A candidate repository the agent already has access to, handed to Linear's
+ *  `issueRepositorySuggestions` so it can rank them. `hostname` is the git host
+ *  (e.g. "github.com"); `repositoryFullName` is "owner/name". */
+export interface RepoCandidate {
+  hostname?: string;
+  repositoryFullName: string;
+}
+
+/** One ranked suggestion Linear returns for an issue: a candidate plus a confidence score. The order
+ *  (and the score) is advisory only - it orders a human pick-list and NEVER decides routing. */
+export interface RepoSuggestion {
+  repositoryFullName: string;
+  hostname?: string;
+  confidence: number;
+}
+
+/** Account-linking parameters for the `auth` signal (the credential-plane seam). */
+export interface AuthRequest {
+  url: string;
+  userId?: string;
+  providerName?: string;
+}
+
+/** A Linear workflow-state category. Mirrors the `type` field on a `WorkflowState`. */
+export type IssueStateType =
+  | "triage"
+  | "backlog"
+  | "unstarted"
+  | "started"
+  | "completed"
+  | "canceled";
+
+/** The disengagement ground truth for one Linear issue, read live off the API (DHK-*: stuck
+ *  awaitingInput backstop). Only the fields the disengagement predicate needs are carried; an issue
+ *  ABSENT from a `readIssueEngagement` result (hard-deleted) is represented by the map having no
+ *  entry, not by a value here, so `present` is always true when an `IssueEngagement` exists. */
+export interface IssueEngagement {
+  /** Always true for a returned issue; the "not present" (deleted) case is a missing map entry. */
+  present: boolean;
+  /** The issue has been archived (soft-deleted). Read from `archivedAt`; archived issues are still
+   *  returned because the read requests `includeArchived`. */
+  archived: boolean;
+  /** The issue's current workflow-state category (`state.type`), when known. */
+  stateType?: IssueStateType;
+  /** The current assignee's user id, when set. */
+  assigneeId?: string;
+  /** The current delegated agent-user id (`delegateId`), when set. For an agent, engagement is
+   *  delegation, not assignment, so this is the primary identity to test against the app user. */
+  delegateId?: string;
+}
+
+/** A pull request to attach to the session's issue (idempotent by `url`). */
+export interface PrAttachment {
+  url: string;
+  title: string;
+  subtitle?: string;
+  iconUrl?: string;
+}
+
+/** A Linear Document to create and link to the session's issue (the `attach-document` action). */
+export interface DocumentInput {
+  title: string;
+  /** The document body as markdown. */
+  content: string;
+}
+
+/** The created Linear Document, returned so the caller can surface its link. */
+export interface DocumentRef {
+  id: string;
+  url: string;
+}
+
+/** A labelled external link on a session (the run dashboard, the eventual PR, a document). The label
+ *  is what Linear shows on the "Open" affordance; the URL must be unique within the session's array. */
+export interface ExternalUrl {
+  url: string;
+  label: string;
+}
+
+/** Keep only the externalUrls Linear accepts: http(s) URLs (internal `skakel://` refs are dropped),
+ *  with empty/blank URLs removed and duplicates collapsed by `url` (first wins, since Linear requires
+ *  each URL to be unique within the array). Pure, so it is unit-tested directly. */
+export function filterExternalUrls(urls: ExternalUrl[]): ExternalUrl[] {
+  const seen = new Set<string>();
+  const kept: ExternalUrl[] = [];
+  for (const u of urls) {
+    const url = u.url?.trim();
+    if (!url || !/^https?:\/\//.test(url) || seen.has(url)) continue;
+    seen.add(url);
+    kept.push({ url, label: u.label });
+  }
+  return kept;
+}
+
+/**
+ * The session-side control surface: drive one Linear agent session. The hub holds the
+ * Connection's token and calls this; the edge never does. Two implementations: a
+ * credential-free recording client (tests + the offline harness) and the real
+ * `@linear/sdk`-backed client (live). See ./recording-client.ts and ./linear-client.ts.
+ */
+export interface AgentSessionClient {
+  /** Post a progress activity (thought / action / response / error). */
+  postActivity(sessionId: string, activity: Activity): Promise<void>;
+  /** Render or update the agent-plan checklist (the workflow stage graph). */
+  setPlan(sessionId: string, items: PlanItem[]): Promise<void>;
+  /** Raise an elicitation gate (optionally with `select` choices; labels render in the UI). */
+  raiseElicitation(sessionId: string, prompt: string, options?: ElicitOption[]): Promise<void>;
+  /** Rank candidate repositories for an issue via Linear's `issueRepositorySuggestions`. The returned
+   *  order is advisory: it only orders the repo pick-list, and never decides routing (the determinism
+   *  boundary). Returns `[]` when Linear has no opinion, so the caller falls back to registry order. */
+  suggestRepositories(issueId: string, candidates: RepoCandidate[]): Promise<RepoSuggestion[]>;
+  /** Idempotently stamp an issue with a label by NAME (get-or-create the label, then attach it). Used
+   *  to record the chosen `repo:<name>` so future events for the issue route deterministically. */
+  addIssueLabel(issueId: string, name: string): Promise<void>;
+  /** Raise an account-linking elicitation carrying the `auth` signal (credential-plane seam). */
+  requestAuth(sessionId: string, prompt: string, auth: AuthRequest): Promise<void>;
+  /** Move the session's issue into its team's working (`started`, non-review) state and self-delegate
+   *  (best practice on delegation). Returns an outcome so a caller can surface a no-op/failed move
+   *  instead of it vanishing (see `StartIssueOutcome`). */
+  startIssue(sessionId: string): Promise<StartIssueOutcome>;
+  /** Move the session's issue to a review-named state on run completion (configurable via
+   *  `DAHRK_REVIEW_STATE_NAME`). Leaves it unchanged when no such state exists - never
+   *  auto-completes, so a human keeps iterating and can re-summon @Dahrk on the same PR. Returns an
+   *  outcome so a caller can surface a no-op (no matching state) rather than have the ticket silently
+   *  stay In Progress (see `MoveToReviewOutcome`). */
+  moveIssueToReview(sessionId: string): Promise<MoveToReviewOutcome>;
+  /** Post a normal top-level comment on the session's issue (not an agent activity), so a run
+   *  summary lands in the issue's comment thread rather than only in the agent session panel. */
+  commentOnIssue(sessionId: string, body: string): Promise<void>;
+  /** Attach a pull request to the session's issue (idempotent by URL) in addition to externalUrls. */
+  attachPr(sessionId: string, pr: PrAttachment): Promise<void>;
+  /** Create a Linear Document linked to the session's issue (the `attach-document` action's output),
+   *  returning its id and URL. The deterministic engine calls this; the LLM never does. */
+  createDocument(sessionId: string, doc: DocumentInput): Promise<DocumentRef>;
+  /** Set external links on the session (run logs/dashboard, the eventual PR), each with a label. The
+   *  full array is replaced wholesale, so the caller passes the complete desired set; non-http(s)
+   *  URLs are filtered out before the call. */
+  setExternalUrls(sessionId: string, urls: ExternalUrl[]): Promise<void>;
+  /** Mirror the run-state to the Linear session state. */
+  setState(sessionId: string, state: SessionState): Promise<void>;
+  /** Read disengagement ground truth for a batch of issues in one query (rate-limit friendly; the
+   *  read includes archived issues). The result maps issue id -> `IssueEngagement`; an issue id that
+   *  is absent from the result was not returned by Linear (hard-deleted). Used by the disengagement
+   *  sweep and webhook path to decide whether @Dahrk is still engaged on an issue. */
+  readIssueEngagement(issueIds: string[]): Promise<Map<string, IssueEngagement>>;
+  /** The app user's own id (`viewer.id`) - the id @Dahrk self-delegates to on `startIssue`. Cached.
+   *  This is the identity a run's issue must still delegate/assign to for the agent to be "engaged". */
+  appUserId(): Promise<string>;
+  /** Proactively create an agent session ON an issue (DHK-63): the hub was neither delegated nor
+   *  @mentioned but has useful work to do (a triage/SLA pre-brief). Returns the new session id so the
+   *  caller can bind a run to it. Wraps Linear's `agentSessionCreateOnIssue`. */
+  createSessionOnIssue(issueId: string): Promise<string>;
+  /** Proactively create an agent session ON a comment (DHK-63): the comment analogue of
+   *  `createSessionOnIssue`. Returns the new session id. Wraps `agentSessionCreateOnComment`. */
+  createSessionOnComment(commentId: string): Promise<string>;
+}
+
+export type { LinearWebhookPayload } from "@linear/sdk/webhooks";
+export { createRecordingClient } from "./recording-client.js";
+export type { RecordingClient, RecordedCall, RecordingClientOptions } from "./recording-client.js";
+export { createRespondingLinearClient } from "./responding-client.js";
+export type {
+  RespondingClient,
+  RespondingClientOptions,
+  SessionProjection,
+  GateDecision,
+} from "./responding-client.js";
+export { createLinearClient } from "./linear-client.js";
+export { formatToolAction, formatToolResult, type ToolAction } from "./format-action.js";
+export { authorizeUrl, exchangeCode, refreshTokens, revokeToken, mintAppToken, fetchOrganizationId, probeToken, DEFAULT_AGENT_SCOPES } from "./oauth.js";
+export type { LinearTokens, LinearProbe } from "./oauth.js";
+export {
+  provisionLabels,
+  provisionWorkflowLabels,
+  provisionRepoLabels,
+  linearLabelApi,
+  projectLabelApi,
+  fetchIssueProjectRepoLabels,
+  fetchIssueChildCount,
+  fetchOpenBlockers,
+  isBlockerSettled,
+  REPO_LABEL_GROUP,
+} from "./labels.js";
+export type { LabelApi, ProvisionOptions, OpenBlocker } from "./labels.js";
+export { linearTeamsApi, listWorkspaceTeams } from "./teams.js";
+export type { Team, TeamsApi } from "./teams.js";
+export { linearTriageApi, linearClientAuth, linearCaptureApi } from "./issues.js";
+export type { TriageApi, CaptureLinearApi, CaptureIssueResult } from "./issues.js";
+export {
+  fetchAttachedDocuments,
+  collectAttachedDocuments,
+  linearDocumentSource,
+  documentSlugFromUrl,
+  documentSlug,
+} from "./documents.js";
+export type { DocumentSource, RawDocument } from "./documents.js";
+export { fetchIssueComments, collectIssueComments, linearCommentSource } from "./comments.js";
+export type { CommentSource, RawComment } from "./comments.js";
+export {
+  fetchRelatedIssues,
+  collectRelatedIssues,
+  linearIssueGraphSource,
+  MAX_RELATED_ISSUES,
+} from "./issue-graph.js";
+export type { IssueGraphSource, RawEdge, RawRelatedIssue } from "./issue-graph.js";
+export {
+  fetchParentBatchSource,
+  collectParentBatchSource,
+  linearParentBatchSource,
+  MAX_BATCH_CHILDREN,
+} from "./batch-source.js";
+export type {
+  ParentBatchSource,
+  ParentBatchSnapshot,
+  RawChild,
+  RawBlocker,
+  ExternalBlocker,
+} from "./batch-source.js";