@dahrk/linear 0.1.0 → 0.1.1

package/README.md

@@ -1,19 +1,31 @@
 # @dahrk/linear
 
-**Confidentiality:** Internal
-**Status:** DRAFT - UNREVIEWED
+The Linear-native control surface used by [Dahrk](https://dahrk.ai), a Linear-native agent-workflow
+harness. Linear is the substrate and the only source; this package is how Dahrk speaks to it.
 
-The Linear-native control surface and webhook verification. Linear is the substrate and the only
-source; this package is how Dahrk speaks to it.
+- **Intake-side:** verify webhook signatures and normalise them to an internal `LinearEvent`.
+- **Session-side:** the Agent Session API - activities, the agent-plan checklist, `elicitation` gates,
+  the `prompted` drive, the `stop` signal, and `externalUrls`.
 
-- **Intake-side:** verify webhook signatures; normalise to the internal `LinearEvent`.
-- **Session-side:** the Agent Session API - activities, the agent-plan checklist, `elicitation`
-  gates, the `prompted` drive, the `stop` signal, `externalUrls`.
+Used by both the hub (intake plus session) and the edge node (session, while a stage runs). Implemented
+against the Linear API directly, on top of the Linear TypeScript SDK.
 
-Used by both `hub` (intake + session) and `edge` (session, while a stage runs). Re-implemented
-against the API directly; cyrus is a reference. Intended runtime dependency: the Linear TypeScript
-SDK. See `../../docs/01-build-spec.md` section 14.
+## Stability
 
-## Sources
+This package is pre-1.0, so **a minor bump can break**. Note that a caret range on a `0.x` version does
+not cross the minor: `^0.1.0` will not resolve `0.2.0`. Pin deliberately.
 
-- `../../docs/01-build-spec.md`, the design's doc 05 (Linear feature coverage).
+## Notes for the curious
+
+**There is deliberately no `repository` field**, which is why npm shows no repository row. This package
+is published from a private repo, so the accurate link would 404 for everyone who can read the package,
+and pointing it at the public `dahrk-node` would send readers to a repo the source is not in. The links
+below are the real front doors.
+
+## Links
+
+- Documentation: [dahrk.ai/docs](https://dahrk.ai/docs)
+- Issues: [github.com/dahrkai/dahrk-node/issues](https://github.com/dahrkai/dahrk-node/issues)
+- Edge client: [github.com/dahrkai/dahrk-node](https://github.com/dahrkai/dahrk-node)
+
+Apache-2.0, © Skakel Labs.

package/dist/comments.d.ts

@@ -0,0 +1,36 @@
+import type { IssueComment } from "@dahrk/contracts";
+/** A comment as returned by Linear before normalisation. */
+export interface RawComment {
+    id: string;
+    body?: string;
+    createdAt?: Date | string;
+    /** Author user id, compared against the app user id to drop the harness's own posts. */
+    authorId?: string;
+    /** Author display name, surfaced to the agent. */
+    authorName?: string;
+}
+/** The read seam the assembly depends on; the live impl wraps GraphQL, tests inject a fake. */
+export interface CommentSource {
+    /** The issue's comments, in whatever order Linear returns them. */
+    issueComments(issueId: string): Promise<RawComment[]>;
+    /** The id of the app user this token authenticates as, or null when it cannot be resolved. */
+    appUserId(): Promise<string | null>;
+}
+/**
+ * Collect an issue's comments from a source: drop the app user's own posts, drop empty bodies, and
+ * order oldest first so the thread reads as a conversation. Pure of any network - the source does the
+ * I/O.
+ *
+ * Comments with no resolvable timestamp sort last rather than being dropped: an unorderable comment is
+ * still content worth showing, and losing it silently would be worse than showing it out of order.
+ */
+export declare function collectIssueComments(source: CommentSource, issueId: string): Promise<IssueComment[]>;
+/** The live `CommentSource`, backed by a Linear bearer token. Uses the typed SDK. */
+export declare function linearCommentSource(token: string): CommentSource;
+/**
+ * Fetch an issue's comment thread as contract `IssueComment`s, ready to snapshot into a run. The
+ * single entry point the hub calls. A hard failure (auth, network) propagates so the caller can log
+ * and proceed with none.
+ */
+export declare function fetchIssueComments(token: string, issueId: string): Promise<IssueComment[]>;
+//# sourceMappingURL=comments.d.ts.map

package/dist/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../src/comments.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACtD,8FAA8F;IAC9F,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACrC;AAYD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,EAAE,CAAC,CAmBzB;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAqChE;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAEhG"}

package/dist/comments.js

@@ -0,0 +1,104 @@
+/**
+ * Fetch the comment thread on a Linear issue, so the hub can snapshot it into a run and surface it to
+ * the agent. Until now nothing in the harness read comment bodies at all: an agent saw only whatever
+ * Linear happened to inline in the webhook's `promptContext`, so the conversation that actually
+ * decided the shape of a ticket was invisible to the stage doing the work.
+ *
+ * The one piece of logic that is not a plain read: the app user's OWN comments are dropped. The
+ * harness posts its stage summaries back through `commentOnIssue`, so without this filter every stage
+ * would read the previous stage's summary as though a human had written it - the run talking to itself,
+ * with the noise compounding on each continuation.
+ *
+ * The `CommentSource` seam keeps the assembly pure and unit-testable: the live source
+ * (`linearCommentSource`) speaks GraphQL, while tests inject a fake.
+ */
+import { LinearClient } from "@linear/sdk";
+/** Normalise a timestamp Linear may hand back as a Date or a string into ISO 8601. */
+function isoOf(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string" && value.trim()) {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? "" : parsed.toISOString();
+    }
+    return "";
+}
+/**
+ * Collect an issue's comments from a source: drop the app user's own posts, drop empty bodies, and
+ * order oldest first so the thread reads as a conversation. Pure of any network - the source does the
+ * I/O.
+ *
+ * Comments with no resolvable timestamp sort last rather than being dropped: an unorderable comment is
+ * still content worth showing, and losing it silently would be worse than showing it out of order.
+ */
+export async function collectIssueComments(source, issueId) {
+    const [raw, appUserId] = await Promise.all([source.issueComments(issueId), source.appUserId()]);
+    const out = [];
+    for (const comment of raw) {
+        if (appUserId && comment.authorId === appUserId)
+            continue;
+        const body = (comment.body ?? "").trim();
+        if (!body)
+            continue;
+        out.push({
+            id: comment.id,
+            author: (comment.authorName ?? "").trim(),
+            createdAt: isoOf(comment.createdAt),
+            body,
+        });
+    }
+    return out.sort((a, b) => {
+        if (!a.createdAt)
+            return 1;
+        if (!b.createdAt)
+            return -1;
+        return a.createdAt.localeCompare(b.createdAt);
+    });
+}
+/** The live `CommentSource`, backed by a Linear bearer token. Uses the typed SDK. */
+export function linearCommentSource(token) {
+    const client = new LinearClient({ accessToken: token });
+    return {
+        async issueComments(issueId) {
+            // Bounded, unpaginated cap, matching `linearDocumentSource.issueDocuments`: a thread longer than
+            // 100 comments silently drops the overflow. Deliberate, not a bug - the prompt inlines only the
+            // most recent few thousand characters anyway. Revisit with cursor pagination if it bites.
+            const issue = await client.issue(issueId);
+            const conn = await issue.comments({ first: 100 });
+            const nodes = await Promise.all(conn.nodes.map(async (c) => {
+                // `user` is a lazy reference on the SDK's Comment; resolving it per comment is what lets us
+                // both filter the app user's posts and name the human author. A comment whose author does not
+                // resolve (a deleted user, an integration post) still rides through, unattributed.
+                const user = await c.user;
+                return {
+                    id: c.id,
+                    body: c.body,
+                    createdAt: c.createdAt,
+                    ...(user?.id ? { authorId: user.id } : {}),
+                    ...(user?.displayName || user?.name ? { authorName: user.displayName ?? user.name } : {}),
+                };
+            }));
+            return nodes;
+        },
+        async appUserId() {
+            try {
+                const viewer = await client.viewer;
+                return viewer?.id ?? null;
+            }
+            catch {
+                // Failing to resolve the app user must not lose the thread. We return null and accept that the
+                // harness's own comments ride through this once, rather than dropping every comment.
+                return null;
+            }
+        },
+    };
+}
+/**
+ * Fetch an issue's comment thread as contract `IssueComment`s, ready to snapshot into a run. The
+ * single entry point the hub calls. A hard failure (auth, network) propagates so the caller can log
+ * and proceed with none.
+ */
+export async function fetchIssueComments(token, issueId) {
+    return collectIssueComments(linearCommentSource(token), issueId);
+}
+//# sourceMappingURL=comments.js.map

package/dist/comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../src/comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsB3C,sFAAsF;AACtF,SAAS,KAAK,CAAC,KAAgC;IAC7C,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;IACpE,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAqB,EACrB,OAAe;IAEf,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAChG,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,OAAO,IAAI,GAAG,EAAE,CAAC;QAC1B,IAAI,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,SAAS;QAC1D,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,MAAM,EAAE,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YACzC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;YACnC,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACvB,IAAI,CAAC,CAAC,CAAC,SAAS;YAAE,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,CAAC,SAAS;YAAE,OAAO,CAAC,CAAC,CAAC;QAC5B,OAAO,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,OAAO;YACzB,iGAAiG;YACjG,gGAAgG;YAChG,0FAA0F;YAC1F,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC1C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YAClD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;gBACzB,4FAA4F;gBAC5F,8FAA8F;gBAC9F,mFAAmF;gBACnF,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC;gBAC1B,OAAO;oBACL,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC1C,GAAG,CAAC,IAAI,EAAE,WAAW,IAAI,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACrE,CAAC;YACzB,CAAC,CAAC,CACH,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,CAAC,SAAS;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;gBACnC,OAAO,MAAM,EAAE,EAAE,IAAI,IAAI,CAAC;YAC5B,CAAC;YAAC,MAAM,CAAC;gBACP,+FAA+F;gBAC/F,qFAAqF;gBACrF,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAAa,EAAE,OAAe;IACrE,OAAO,oBAAoB,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC"}

package/dist/documents.d.ts

@@ -1,17 +1,3 @@
-/**
- * Fetch the Linear Documents attached to an issue, so the hub can snapshot their content into a run
- * and surface it to the agent (the harness was webhook-payload-only before, so a document reached the
- * agent only as a URL, never as content). This is a read against the same per-connection Linear token
- * the hub already uses to post back; fetching content is data assembly, not control flow.
- *
- * Two sources, de-duped by document id:
- *  1. Documents directly associated with the issue (`issue.documents`).
- *  2. Documents linked via the issue's attachments whose `url` is a Linear document URL
- *     (`https://linear.app/<ws>/document/<...>-<slug>`), resolved through `document(id:)`.
- *
- * The `DocumentSource` seam keeps the assembly pure and unit-testable: the live source
- * (`linearDocumentSource`) speaks GraphQL, while tests inject a fake.
- */
 import type { AttachedDocument } from "@dahrk/contracts";
 /** A document as returned by Linear before slug normalisation (slugId is Linear's URL-safe slug). */
 export interface RawDocument {
@@ -44,7 +30,7 @@ export declare function documentSlug(doc: RawDocument): string;
  * attachment whose document does not resolve is skipped, never fatal.
  */
 export declare function collectAttachedDocuments(source: DocumentSource, issueId: string): Promise<AttachedDocument[]>;
-/** The live `DocumentSource`, backed by a Linear bearer token. Plain fetch, no SDK. */
+/** The live `DocumentSource`, backed by a Linear bearer token. Uses the typed SDK. */
 export declare function linearDocumentSource(token: string): DocumentSource;
 /**
  * Fetch the documents attached to a Linear issue as contract `AttachedDocument`s, ready to snapshot

package/dist/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIzD,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACxD,4FAA4F;IAC5F,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,+FAA+F;IAC/F,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC3D;AAED;;;+FAG+F;AAC/F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc9D;AAED;0FAC0F;AAC1F,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAQrD;AAeD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuB7B;AAqBD,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAgClE;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE7B"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,qGAAqG;AACrG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACxD,4FAA4F;IAC5F,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,+FAA+F;IAC/F,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC3D;AAED;;;+FAG+F;AAC/F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc9D;AAED;0FAC0F;AAC1F,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAQrD;AAeD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuB7B;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAiClE;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE7B"}

package/dist/documents.js

@@ -1,4 +1,18 @@
-const GRAPHQL_URL = "https://api.linear.app/graphql";
+/**
+ * Fetch the Linear Documents attached to an issue, so the hub can snapshot their content into a run
+ * and surface it to the agent (the harness was webhook-payload-only before, so a document reached the
+ * agent only as a URL, never as content). This is a read against the same per-connection Linear token
+ * the hub already uses to post back; fetching content is data assembly, not control flow.
+ *
+ * Two sources, de-duped by document id:
+ *  1. Documents directly associated with the issue (`issue.documents`).
+ *  2. Documents linked via the issue's attachments whose `url` is a Linear document URL
+ *     (`https://linear.app/<ws>/document/<...>-<slug>`), resolved through `document(id:)`.
+ *
+ * The `DocumentSource` seam keeps the assembly pure and unit-testable: the live source
+ * (`linearDocumentSource`) speaks GraphQL, while tests inject a fake.
+ */
+import { LinearClient } from "@linear/sdk";
 /** The Linear-document slug from an attachment URL, or null when the URL is not a Linear document
  *  link. Linear document URLs look like `https://linear.app/<ws>/document/<title-slug>-<slugId>`;
  *  the canonical slug Linear's `document(id:)` accepts is the trailing token (the slugId), which is
@@ -76,42 +90,38 @@ export async function collectAttachedDocuments(source, issueId) {
     }
     return out;
 }
-/** Run one GraphQL query against Linear with a bearer token; throws on transport or GraphQL errors. */
-async function gql(token, query, variables) {
-    const res = await fetch(GRAPHQL_URL, {
-        method: "POST",
-        headers: { "content-type": "application/json", authorization: token },
-        body: JSON.stringify({ query, variables }),
-    });
-    if (!res.ok)
-        throw new Error(`linear graphql ${res.status}`);
-    const json = (await res.json().catch(() => ({})));
-    if (json.errors?.length)
-        throw new Error(json.errors.map((e) => e.message).join("; "));
-    if (!json.data)
-        throw new Error("linear graphql: empty response");
-    return json.data;
-}
-const DOC_FIELDS = "id slugId title url content";
-/** The live `DocumentSource`, backed by a Linear bearer token. Plain fetch, no SDK. */
+/** The live `DocumentSource`, backed by a Linear bearer token. Uses the typed SDK. */
 export function linearDocumentSource(token) {
+    const client = new LinearClient({ accessToken: token });
     return {
         async issueDocuments(issueId) {
             // Bounded, unpaginated cap: an issue with more than 50 attached documents (or 100 attachments
             // below) silently drops the overflow. That is a deliberate limit, not a bug; revisit with cursor
             // pagination if real issues approach it.
-            const data = await gql(token, `query($id: String!){ issue(id:$id){ documents(first:50){ nodes{ ${DOC_FIELDS} } } } }`, { id: issueId });
-            return data.issue?.documents?.nodes ?? [];
+            const issue = await client.issue(issueId);
+            const conn = await issue.documents({ first: 50 });
+            return conn.nodes.map((d) => ({
+                id: d.id,
+                slugId: d.slugId,
+                title: d.title,
+                url: d.url,
+                content: d.content ?? undefined,
+            }));
         },
         async issueAttachmentUrls(issueId) {
-            const data = await gql(token, `query($id: String!){ issue(id:$id){ attachments(first:100){ nodes{ url } } } }`, { id: issueId });
-            return (data.issue?.attachments?.nodes ?? [])
-                .map((a) => a.url)
-                .filter((u) => typeof u === "string" && u.length > 0);
+            const issue = await client.issue(issueId);
+            const conn = await issue.attachments({ first: 100 });
+            return conn.nodes.map((a) => a.url).filter((u) => u.length > 0);
         },
         async documentBySlug(slug) {
-            const data = await gql(token, `query($id: String!){ document(id:$id){ ${DOC_FIELDS} } }`, { id: slug });
-            return data.document ?? null;
+            const doc = await client.document(slug);
+            return {
+                id: doc.id,
+                slugId: doc.slugId,
+                title: doc.title,
+                url: doc.url,
+                content: doc.content ?? undefined,
+            };
         },
     };
 }

package/dist/documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"documents.js","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"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"}

package/dist/format-action.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Format a tool call into Linear's action-activity vocabulary (DHK-382): a human verb in
+ * `action` and a clean, humanised input in `parameter`. Linear renders these as
+ * "<action> · <parameter>" (e.g. "Ran · grep -rn ..."), so the agent session reads as a
+ * sequence of verbs instead of a wall of `ToolName {raw JSON args}`.
+ *
+ * `inputText` is the edge's bounded preview of the tool input: normally a JSON object string
+ * (`clip(JSON.stringify(input))`), but it may be TRUNCATED (over the edge's ~500-char cap) or
+ * otherwise malformed. Parsing is defensive: a preview that will not parse never throws and
+ * never falls through to raw JSON. Known single-field tools still salvage their primary field
+ * from a truncated preview; anything unrecoverable degrades to the bare verb.
+ */
+/** A tool call rendered as Linear's `{ action, parameter }` pair. */
+export interface ToolAction {
+    action: string;
+    parameter: string;
+}
+/**
+ * Map a `(toolName, inputPreview)` pair to a verb plus a clean parameter. Total and defensive:
+ * every branch returns a `{ action, parameter }`, and the parameter is only ever a humanised
+ * field value (never the raw JSON), so a malformed or oversized preview degrades to the bare verb.
+ */
+export declare function formatToolAction(tool: string | undefined, inputText: string | undefined): ToolAction;
+export declare function formatToolResult(tool: string | undefined, output: string | undefined): string;
+//# sourceMappingURL=format-action.d.ts.map

package/dist/format-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-action.d.ts","sourceRoot":"","sources":["../src/format-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AA2FD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAgDpG;AAkGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAmB7F"}

package/dist/format-action.js

@@ -0,0 +1,250 @@
+/**
+ * Format a tool call into Linear's action-activity vocabulary (DHK-382): a human verb in
+ * `action` and a clean, humanised input in `parameter`. Linear renders these as
+ * "<action> · <parameter>" (e.g. "Ran · grep -rn ..."), so the agent session reads as a
+ * sequence of verbs instead of a wall of `ToolName {raw JSON args}`.
+ *
+ * `inputText` is the edge's bounded preview of the tool input: normally a JSON object string
+ * (`clip(JSON.stringify(input))`), but it may be TRUNCATED (over the edge's ~500-char cap) or
+ * otherwise malformed. Parsing is defensive: a preview that will not parse never throws and
+ * never falls through to raw JSON. Known single-field tools still salvage their primary field
+ * from a truncated preview; anything unrecoverable degrades to the bare verb.
+ */
+/** Keep a parameter readable on one line; the edge already caps the input at ~500 chars. */
+const MAX_PARAM = 400;
+/** Collapse whitespace to a single line and clip with an ellipsis so the parameter never wraps. */
+function clip(s, max = MAX_PARAM) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length <= max ? t : `${t.slice(0, max - 1).trimEnd()}…`;
+}
+/** The final path segment (e.g. "packages/hub/src/config-server.ts" -> "config-server.ts"). */
+function basename(p) {
+    const trimmed = p.replace(/\/+$/, "");
+    const i = trimmed.lastIndexOf("/");
+    return i >= 0 ? trimmed.slice(i + 1) : trimmed;
+}
+/** Humanise a tool name for display: split separators and camelCase, then Title Case
+ *  (e.g. "WebFetch" -> "Web Fetch", "create_issue" -> "Create Issue"). */
+function humaniseToolName(name) {
+    return (name
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase()) || "Tool");
+}
+/** A parsed tool-input object, or undefined when the preview is missing/truncated/not an object. */
+function parseInput(text) {
+    const t = text?.trim();
+    if (!t || !t.startsWith("{"))
+        return undefined;
+    try {
+        const parsed = JSON.parse(t);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A scalar field as a trimmed string, or undefined when absent/empty/non-scalar. */
+function scalarField(input, key) {
+    const v = input?.[key];
+    const s = typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : undefined;
+    return s && s.trim() !== "" ? s : undefined;
+}
+/** Best-effort extraction of a string field straight from the raw preview, so a TRUNCATED JSON
+ *  (a long command clipped mid-value) still yields its primary field rather than an empty verb. */
+function looseField(text, key) {
+    if (!text)
+        return undefined;
+    const m = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)`).exec(text);
+    if (!m?.[1])
+        return undefined;
+    const decoded = m[1]
+        .replace(/\\"/g, '"')
+        .replace(/\\[nt]/g, " ")
+        .replace(/\\\\/g, "\\")
+        .replace(/\\$/, "");
+    return decoded.trim() !== "" ? decoded : undefined;
+}
+/** A known string field, preferring the parsed value and salvaging a truncated one from the raw text. */
+function stringField(input, text, key) {
+    return scalarField(input, key) ?? looseField(text, key);
+}
+/** The first scalar argument of an unknown tool's input, for a best-guess parameter. */
+function firstScalar(input) {
+    for (const key of Object.keys(input ?? {})) {
+        const s = scalarField(input, key);
+        if (s !== undefined)
+            return s;
+    }
+    return "";
+}
+/** A `Read`/inspection line-range suffix (":440-520" or ":440") from numeric offset/limit. */
+function lineRange(input) {
+    const offset = input?.offset;
+    const limit = input?.limit;
+    if (typeof offset !== "number")
+        return "";
+    return typeof limit === "number" ? `:${offset}-${offset + limit}` : `:${offset}`;
+}
+/**
+ * Map a `(toolName, inputPreview)` pair to a verb plus a clean parameter. Total and defensive:
+ * every branch returns a `{ action, parameter }`, and the parameter is only ever a humanised
+ * field value (never the raw JSON), so a malformed or oversized preview degrades to the bare verb.
+ */
+export function formatToolAction(tool, inputText) {
+    const name = (tool ?? "").trim();
+    const input = parseInput(inputText);
+    const field = (key) => stringField(input, inputText, key);
+    switch (name) {
+        case "Bash":
+            return { action: "Ran", parameter: clip(field("command") ?? "") };
+        case "Read": {
+            const path = field("file_path");
+            return { action: "Read", parameter: path ? clip(basename(path) + lineRange(input)) : "" };
+        }
+        case "Grep": {
+            const pattern = field("pattern");
+            const path = field("path");
+            const where = pattern ? `"${pattern}"${path ? ` in ${path}` : ""}` : "";
+            return { action: "Searched", parameter: clip(where) };
+        }
+        case "Glob": {
+            const pattern = field("pattern");
+            const path = field("path");
+            const where = pattern ? `${pattern}${path ? ` in ${path}` : ""}` : "";
+            return { action: "Searched", parameter: clip(where) };
+        }
+        case "Edit":
+        case "MultiEdit": {
+            const path = field("file_path");
+            return { action: "Edited", parameter: path ? clip(basename(path)) : "" };
+        }
+        case "Write": {
+            const path = field("file_path");
+            return { action: "Wrote", parameter: path ? clip(basename(path)) : "" };
+        }
+        case "ToolSearch":
+            return { action: "Loaded tools", parameter: clip(field("query") ?? "") };
+        default:
+            break;
+    }
+    // MCP tools arrive as `mcp__<server>__<tool>`; show the humanised tool segment.
+    if (name.startsWith("mcp__")) {
+        const segments = name.split("__").filter(Boolean);
+        const toolSegment = segments[segments.length - 1] ?? name;
+        return { action: humaniseToolName(toolSegment), parameter: clip(firstScalar(input)) };
+    }
+    // Unknown tool: a title-cased name plus its first scalar argument.
+    return { action: humaniseToolName(name), parameter: clip(firstScalar(input)) };
+}
+/**
+ * Render a completed tool's output as the markdown `result` of its action activity (DHK-386). This
+ * is the companion to formatToolAction: the verb + parameter describe the call, this shapes the
+ * outcome per tool - `Bash` as a fenced block, `Grep` as a match-count summary, `Edit`/`Write` as a
+ * diff stat, `Read` as how much was read - so the session reads richly instead of dumping raw text.
+ *
+ * `output` is the tool's full (untruncated) observation output. Total and defensive like its
+ * companion: it never throws, bounds every long output with a clear elision so a noisy tool can
+ * never flood the session, and degrades any unrecognised tool or shape to a bounded first line. An
+ * empty output yields an empty string, so no `result` is folded onto the action.
+ */
+/** Caps for a rendered result: keep the outcome glanceable. Long output shows a head and tail with
+ *  a "… (N more lines)" marker between, never the whole wall. */
+const RESULT_MAX_LINES = 12;
+const RESULT_HEAD_LINES = 8;
+const RESULT_TAIL_LINES = 3;
+const RESULT_MAX_CHARS = 1800;
+const RESULT_TOP_HITS = 5;
+/** Clip a multi-line block to a character budget, marking the cut with an ellipsis line. */
+function clipBlock(s, max = RESULT_MAX_CHARS) {
+    return s.length <= max ? s : `${s.slice(0, max).trimEnd()}\n…`;
+}
+/** Bound a block of lines: keep it whole when short, else show the head and tail with a
+ *  "… (N more lines)" elision marker between them so long output never becomes a wall of text. */
+function elideLines(lines) {
+    if (lines.length <= RESULT_MAX_LINES)
+        return lines.join("\n");
+    const head = lines.slice(0, RESULT_HEAD_LINES);
+    const tail = lines.slice(-RESULT_TAIL_LINES);
+    const omitted = lines.length - head.length - tail.length;
+    return [...head, `… (${omitted} more lines)`, ...tail].join("\n");
+}
+/** A fenced code block, the standard rendering for verbatim command/file output. */
+function codeFence(body) {
+    return "```\n" + body + "\n```";
+}
+/** The first non-empty line, collapsed and clipped - the safe fallback for MCP and unknown tools. */
+function firstLine(output) {
+    return clip(output.split("\n").find((l) => l.trim() !== "") ?? "");
+}
+/** English pluralisation for a count, e.g. `plural(2, "match", "matches")`. */
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/** `Bash`: the stdout/stderr in a fenced code block, bounded head + tail. */
+function renderBashResult(output) {
+    return codeFence(clipBlock(elideLines(output.split("\n"))));
+}
+/** A `path:line` grep hit parsed from a `path:line:content` or `path:line` output row. */
+function grepHit(row) {
+    const m = /^(.+?):(\d+)(?::|$)/.exec(row);
+    return m ? { path: m[1], line: m[2] } : undefined;
+}
+/** `Grep`: an "N matches in M files" summary plus the first few ``path:line`` hits. Falls back to a
+ *  plain match count and the first rows when the output is not the `path:line` shape (e.g. a
+ *  files-with-matches listing of bare paths). */
+function renderGrepResult(output) {
+    const rows = output.split("\n").map((r) => r.trim()).filter(Boolean);
+    const hits = rows.map(grepHit).filter((h) => h !== undefined);
+    if (hits.length === 0) {
+        const listed = rows.slice(0, RESULT_TOP_HITS).map((r) => `- ${r}`);
+        const more = rows.length > RESULT_TOP_HITS ? [`… (${rows.length - RESULT_TOP_HITS} more)`] : [];
+        return [plural(rows.length, "match", "matches"), ...listed, ...more].join("\n");
+    }
+    const files = new Set(hits.map((h) => h.path)).size;
+    const summary = `${plural(hits.length, "match", "matches")} in ${plural(files, "file", "files")}`;
+    const top = hits.slice(0, RESULT_TOP_HITS).map((h) => `- \`${h.path}:${h.line}\``);
+    const more = hits.length > RESULT_TOP_HITS ? [`… (${hits.length - RESULT_TOP_HITS} more)`] : [];
+    return [summary, ...top, ...more].join("\n");
+}
+/** `Read`: how much was read; the file content itself is not worth echoing into the session. */
+function renderReadResult(output) {
+    return `Read ${plural(output.split("\n").length, "line", "lines")}.`;
+}
+/** `Edit`/`Write`: a `+added / −removed` diff stat when the output is a unified diff, else the tool's
+ *  one-line confirmation. Ignores the `+++`/`---` file headers so they are not counted as changes. */
+function renderEditResult(output) {
+    let added = 0;
+    let removed = 0;
+    for (const line of output.split("\n")) {
+        if (line.startsWith("+") && !line.startsWith("+++"))
+            added += 1;
+        else if (line.startsWith("-") && !line.startsWith("---"))
+            removed += 1;
+    }
+    return added > 0 || removed > 0 ? `\`+${added} / −${removed}\`` : firstLine(output);
+}
+export function formatToolResult(tool, output) {
+    const text = (output ?? "").trimEnd();
+    if (text.trim() === "")
+        return "";
+    switch ((tool ?? "").trim()) {
+        case "Bash":
+            return renderBashResult(text);
+        case "Grep":
+            return renderGrepResult(text);
+        case "Read":
+            return renderReadResult(text);
+        case "Edit":
+        case "MultiEdit":
+        case "Write":
+            return renderEditResult(text);
+        default:
+            // MCP and unknown tools: a short, safe summary rather than a raw dump.
+            return firstLine(text);
+    }
+}
+//# sourceMappingURL=format-action.js.map