@dahrk/linear 0.1.0 → 0.1.1

package/dist/recording-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recording-client.d.ts","sourceRoot":"","sources":["../src/recording-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,aAAa,EAAE,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,aAAa,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAEjE,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CAChC;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CAkDvD"}
+{"version":3,"file":"recording-client.d.ts","sourceRoot":"","sources":["../src/recording-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,GACzF;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,aAAa,EAAE,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,YAAY,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,aAAa,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,eAAgB,SAAQ,kBAAkB;IACzD,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CAChC;AAED,0FAA0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;0GAEsG;IACtG,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC,CAAC;CACrD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,sBAA2B,GAAG,eAAe,CAqFxF"}

package/dist/recording-client.js

@@ -1,5 +1,7 @@
-export function createRecordingClient() {
+export function createRecordingClient(opts = {}) {
     const calls = [];
+    const appUserId = opts.appUserId ?? "app-user";
+    const engagement = opts.engagement ?? {};
     return {
         calls,
         async postActivity(sessionId, activity) {
@@ -25,9 +27,13 @@ export function createRecordingClient() {
         },
         async startIssue(sessionId) {
             calls.push({ call: "startIssue", sessionId });
+            // Offline stub: report a successful move so the reporter's no-op surfacing stays quiet.
+            return { moved: true, stateName: "In Progress" };
         },
         async moveIssueToReview(sessionId) {
             calls.push({ call: "moveIssueToReview", sessionId });
+            // Offline stub: report a successful move so the reporter's no-op surfacing stays quiet.
+            return { moved: true, stateName: "In Review" };
         },
         async commentOnIssue(sessionId, body) {
             calls.push({ call: "commentOnIssue", sessionId, body });
@@ -47,6 +53,38 @@ export function createRecordingClient() {
         async setState(sessionId, state) {
             calls.push({ call: "setState", sessionId, state });
         },
+        async readIssueEngagement(issueIds) {
+            calls.push({ call: "readIssueEngagement", issueIds });
+            const out = new Map();
+            for (const id of issueIds) {
+                if (!id)
+                    continue;
+                if (Object.prototype.hasOwnProperty.call(engagement, id)) {
+                    const e = engagement[id];
+                    // null => hard-deleted: leave it out of the result entirely.
+                    if (e)
+                        out.set(id, e);
+                }
+                else {
+                    // Default: fully engaged (delegated + assigned to the app user), so a sweep against an
+                    // unconfigured recording client reads every issue as still-engaged.
+                    out.set(id, { present: true, archived: false, stateType: "started", delegateId: appUserId, assigneeId: appUserId });
+                }
+            }
+            return out;
+        },
+        async appUserId() {
+            return appUserId;
+        },
+        async createSessionOnIssue(issueId) {
+            calls.push({ call: "createSessionOnIssue", issueId });
+            // Deterministic synthetic session id so offline runs and tests have a stable reference.
+            return `sess-${issueId}`;
+        },
+        async createSessionOnComment(commentId) {
+            calls.push({ call: "createSessionOnComment", commentId });
+            return `sess-${commentId}`;
+        },
     };
 }
 //# sourceMappingURL=recording-client.js.map

package/dist/recording-client.js.map

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

package/dist/responding-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * An actively-responding, credential-free AgentSessionClient for the `pnpm dev` offline
+ * environment. It is a superset of the recording client (./recording-client.ts): it keeps
+ * the ordered `calls` log so it is a drop-in wherever the recording client is injected, but
+ * it additionally
+ *
+ *   1. maintains a small, queryable per-session projection of what the hub last pushed
+ *      (latest state, latest plan, appended activities, set external URLs), so a dev can
+ *      observe a run without touching Linear, and
+ *   2. exposes a pure, pre-declared gate-decision policy (`decide`) a dev CLI reads to know
+ *      which answer to fire for a stage.
+ *
+ * The gate policy is a value the dev supplies up front; it NEVER chooses the next stage
+ * (that would cross the determinism boundary). Gate answers remain human-drive: the CLI
+ * uses `decide` only to pick which `prompted` webhook to send.
+ */
+import type { Activity, ElicitOption, ExternalUrl, PlanItem, SessionState } from "./index.js";
+import { type RecordingClient, type RecordingClientOptions } from "./recording-client.js";
+/** A pre-declared gate answer for a stage. Never a control-flow decision (see file header). */
+export type GateDecision = "allow" | "deny";
+/** What the hub last pushed for one session, observable offline without touching Linear. */
+export interface SessionProjection {
+    /** The latest session state the hub mirrored, or undefined if none was set yet. */
+    state?: SessionState;
+    /** The latest plan (agent-plan checklist); replaced wholesale on each `setPlan`. */
+    plan: PlanItem[];
+    /** Every activity posted to the session, in order. */
+    activities: Activity[];
+    /** The latest external-URL set; replaced wholesale on each `setExternalUrls`. */
+    externalUrls: ExternalUrl[];
+    /** The latest elicitation raised on the session, if any. */
+    elicitation?: {
+        prompt: string;
+        options?: ElicitOption[];
+    };
+}
+export interface RespondingClientOptions extends RecordingClientOptions {
+    /** Per-stage gate answers the dev pre-declares. A stage absent here defaults to "allow". */
+    gateDecisions?: Record<string, GateDecision>;
+}
+export interface RespondingClient extends RecordingClient {
+    /** The queryable projection of what the hub last pushed for a session, or undefined if the
+     *  hub has not touched that session. */
+    session(sessionId: string): SessionProjection | undefined;
+    /** The dev's pre-declared gate answer for a stage (default "allow"). Pure. */
+    decide(stageId: string): GateDecision;
+}
+export declare function createRespondingLinearClient(opts?: RespondingClientOptions): RespondingClient;
+//# sourceMappingURL=responding-client.d.ts.map

package/dist/responding-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responding-client.d.ts","sourceRoot":"","sources":["../src/responding-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B,+FAA+F;AAC/F,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5C,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,oFAAoF;IACpF,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,sDAAsD;IACtD,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,iFAAiF;IACjF,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,4DAA4D;IAC5D,WAAW,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;CAC5D;AAED,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD;4CACwC;IACxC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAC1D,8EAA8E;IAC9E,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAAC;CACvC;AAED,wBAAgB,4BAA4B,CAAC,IAAI,GAAE,uBAA4B,GAAG,gBAAgB,CA8CjG"}

package/dist/responding-client.js

@@ -0,0 +1,47 @@
+import { createRecordingClient, } from "./recording-client.js";
+export function createRespondingLinearClient(opts = {}) {
+    // Reuse the recording client wholesale for the ordered call log and the seeded read-side
+    // methods (engagement, appUserId, createDocument), then wrap the mutating methods to also
+    // update a per-session projection.
+    const base = createRecordingClient(opts);
+    const gateDecisions = opts.gateDecisions ?? {};
+    const projections = new Map();
+    const projectionFor = (sessionId) => {
+        let p = projections.get(sessionId);
+        if (!p) {
+            p = { plan: [], activities: [], externalUrls: [] };
+            projections.set(sessionId, p);
+        }
+        return p;
+    };
+    return {
+        ...base,
+        async setPlan(sessionId, items) {
+            await base.setPlan(sessionId, items);
+            projectionFor(sessionId).plan = items;
+        },
+        async postActivity(sessionId, activity) {
+            await base.postActivity(sessionId, activity);
+            projectionFor(sessionId).activities.push(activity);
+        },
+        async raiseElicitation(sessionId, prompt, options) {
+            await base.raiseElicitation(sessionId, prompt, options);
+            projectionFor(sessionId).elicitation = { prompt, ...(options ? { options } : {}) };
+        },
+        async setExternalUrls(sessionId, urls) {
+            await base.setExternalUrls(sessionId, urls);
+            projectionFor(sessionId).externalUrls = urls;
+        },
+        async setState(sessionId, state) {
+            await base.setState(sessionId, state);
+            projectionFor(sessionId).state = state;
+        },
+        session(sessionId) {
+            return projections.get(sessionId);
+        },
+        decide(stageId) {
+            return gateDecisions[stageId] ?? "allow";
+        },
+    };
+}
+//# sourceMappingURL=responding-client.js.map

package/dist/responding-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responding-client.js","sourceRoot":"","sources":["../src/responding-client.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,qBAAqB,GAGtB,MAAM,uBAAuB,CAAC;AAgC/B,MAAM,UAAU,4BAA4B,CAAC,OAAgC,EAAE;IAC7E,yFAAyF;IACzF,0FAA0F;IAC1F,mCAAmC;IACnC,MAAM,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC;IAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEzD,MAAM,aAAa,GAAG,CAAC,SAAiB,EAAqB,EAAE;QAC7D,IAAI,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;YACnD,WAAW,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,IAAI;QACP,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK;YAC5B,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACrC,aAAa,CAAC,SAAS,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC;QACxC,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ;YACpC,MAAM,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC7C,aAAa,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrD,CAAC;QACD,KAAK,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO;YAC/C,MAAM,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YACxD,aAAa,CAAC,SAAS,CAAC,CAAC,WAAW,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QACrF,CAAC;QACD,KAAK,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI;YACnC,MAAM,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAC5C,aAAa,CAAC,SAAS,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC;QAC/C,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK;YAC7B,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACtC,aAAa,CAAC,SAAS,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC;QACzC,CAAC;QACD,OAAO,CAAC,SAAS;YACf,OAAO,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,CAAC,OAAO;YACZ,OAAO,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;QAC3C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/teams.d.ts

@@ -0,0 +1,20 @@
+/** A workspace team, reduced to just what the picker needs. */
+export interface Team {
+    id: string;
+    key: string;
+    name: string;
+}
+/** The injectable seam: list the workspace's teams. */
+export interface TeamsApi {
+    listTeams(): Promise<Team[]>;
+}
+/**
+ * List the workspace's teams via the `TeamsApi` seam, normalised to `{id,key,name}` and sorted by
+ * key so the picker renders in a stable, deterministic order. A thin deterministic transform - no
+ * control flow, no network - so it feeds the portal picker directly.
+ */
+export declare function listWorkspaceTeams(api: TeamsApi): Promise<Team[]>;
+/** The live `TeamsApi` backed by a Linear bearer token (workspace-scoped teams). Paginates
+ *  `client.teams()` exactly as `linearLabelApi` paginates `issueLabels()`. */
+export declare function linearTeamsApi(token: string): TeamsApi;
+//# sourceMappingURL=teams.d.ts.map

package/dist/teams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams.d.ts","sourceRoot":"","sources":["../src/teams.ts"],"names":[],"mappings":"AAQA,+DAA+D;AAC/D,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uDAAuD;AACvD,MAAM,WAAW,QAAQ;IACvB,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAKvE;AAED;8EAC8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAStD"}

package/dist/teams.js

@@ -0,0 +1,32 @@
+/**
+ * Workspace-team listing (DHK-777). A repository routes issues to itself partly by team key
+ * (`Repository.routing.teamKeys`); the portal offers the real keys instead of free text by reading
+ * the linked workspace's teams. The `TeamsApi` seam keeps this pure and unit-testable: the live
+ * adapter (`linearTeamsApi`) wraps `@linear/sdk`, while tests inject a fake - mirroring `LabelApi`.
+ */
+import { LinearClient } from "@linear/sdk";
+/**
+ * List the workspace's teams via the `TeamsApi` seam, normalised to `{id,key,name}` and sorted by
+ * key so the picker renders in a stable, deterministic order. A thin deterministic transform - no
+ * control flow, no network - so it feeds the portal picker directly.
+ */
+export async function listWorkspaceTeams(api) {
+    const teams = await api.listTeams();
+    return teams
+        .map((t) => ({ id: t.id, key: t.key, name: t.name }))
+        .sort((a, b) => a.key.localeCompare(b.key));
+}
+/** The live `TeamsApi` backed by a Linear bearer token (workspace-scoped teams). Paginates
+ *  `client.teams()` exactly as `linearLabelApi` paginates `issueLabels()`. */
+export function linearTeamsApi(token) {
+    const client = new LinearClient({ accessToken: token });
+    return {
+        async listTeams() {
+            const conn = await client.teams();
+            while (conn.pageInfo.hasNextPage)
+                await conn.fetchNext();
+            return conn.nodes.map((t) => ({ id: t.id, key: t.key, name: t.name }));
+        },
+    };
+}
+//# sourceMappingURL=teams.js.map

package/dist/teams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams.js","sourceRoot":"","sources":["../src/teams.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc3C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAa;IACpD,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,SAAS,EAAE,CAAC;IACpC,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;SACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;8EAC8E;AAC9E,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,OAAO;QACL,KAAK,CAAC,SAAS;YACb,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW;gBAAE,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACzE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,16 +1,12 @@
 {
   "name": "@dahrk/linear",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "type": "module",
   "description": "The Linear Agent Session API client and webhook verification. The native control surface: activities, agent-plan checklist, elicitation gates, prompted-drive, stop signal, externalUrls.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/skakel/dahrk.git"
-  },
-  "homepage": "https://github.com/skakel/dahrk#readme",
+  "homepage": "https://dahrk.ai",
   "bugs": {
-    "url": "https://github.com/skakel/dahrk/issues"
+    "url": "https://github.com/dahrkai/dahrk-node/issues"
   },
   "exports": {
     ".": {
@@ -19,14 +15,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@linear/sdk": "^86.0.0",
-    "@dahrk/contracts": "0.1.0"
+    "@dahrk/contracts": "0.11.1"
   },
   "devDependencies": {
     "tsx": "^4.19.0"
@@ -35,7 +32,8 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --import tsx --test test/*.test.ts",
-    "spike/live": "tsx spike/run.ts"
+    "spike/live": "tsx spike/run.ts",
+    "spike/filter": "tsx spike/filter-probe.ts"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"

package/src/comments.ts

@@ -0,0 +1,126 @@
+/**
+ * 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";
+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>;
+}
+
+/** Normalise a timestamp Linear may hand back as a Date or a string into ISO 8601. */
+function isoOf(value: Date | string | undefined): string {
+  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: CommentSource,
+  issueId: string,
+): Promise<IssueComment[]> {
+  const [raw, appUserId] = await Promise.all([source.issueComments(issueId), source.appUserId()]);
+  const out: IssueComment[] = [];
+  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: string): CommentSource {
+  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 } : {}),
+          } satisfies RawComment;
+        }),
+      );
+      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: string, issueId: string): Promise<IssueComment[]> {
+  return collectIssueComments(linearCommentSource(token), issueId);
+}

package/src/documents.ts

@@ -0,0 +1,162 @@
+/**
+ * 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";
+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 {
+  id: string;
+  slugId?: string;
+  title?: string;
+  url?: string;
+  content?: string;
+}
+
+/** The read seam the assembly depends on; the live impl wraps GraphQL, tests inject a fake. */
+export interface DocumentSource {
+  /** Documents directly associated with the issue. */
+  issueDocuments(issueId: string): Promise<RawDocument[]>;
+  /** The issue's attachment URLs (only the `url` is needed to spot Linear document links). */
+  issueAttachmentUrls(issueId: string): Promise<string[]>;
+  /** Resolve a Linear document by the slug taken from its URL; null when it does not resolve. */
+  documentBySlug(slug: string): Promise<RawDocument | null>;
+}
+
+/** 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
+ *  the substring after the final `-`. Falls back to the whole segment when there is no `-`. */
+export function documentSlugFromUrl(url: string): string | null {
+  const m = /\/document\/([^/?#]+)/.exec(url);
+  if (!m?.[1]) return null;
+  // The URL is attacker-influenceable (anyone who can attach a link to the issue). A malformed
+  // percent-escape makes decodeURIComponent throw; swallow it and skip this link rather than let it
+  // abort the whole fetch (which would discard the issue's other documents too).
+  let segment: string;
+  try {
+    segment = decodeURIComponent(m[1]);
+  } catch {
+    return null;
+  }
+  const dash = segment.lastIndexOf("-");
+  return dash >= 0 && dash < segment.length - 1 ? segment.slice(dash + 1) : segment;
+}
+
+/** A filesystem- and URL-safe slug for the scratch filename: prefer Linear's slugId, else slugify the
+ *  title, else the id. Bounded length so a long title cannot produce an unwieldy path. */
+export function documentSlug(doc: RawDocument): string {
+  if (doc.slugId && doc.slugId.trim()) return doc.slugId.trim();
+  const fromTitle = (doc.title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return fromTitle || doc.id;
+}
+
+/** Normalise a RawDocument into the contract shape, dropping ones with no usable content. */
+function toAttached(doc: RawDocument): AttachedDocument | null {
+  const content = doc.content ?? "";
+  if (!content.trim()) return null;
+  return {
+    id: doc.id,
+    slug: documentSlug(doc),
+    title: (doc.title ?? "").trim() || "Untitled document",
+    url: doc.url ?? "",
+    content,
+  };
+}
+
+/**
+ * Collect the issue's attached documents from a source, de-duped by id (issue documents first, then
+ * attachment-linked documents). Pure of any network: the source does the I/O. Best-effort - an
+ * attachment whose document does not resolve is skipped, never fatal.
+ */
+export async function collectAttachedDocuments(
+  source: DocumentSource,
+  issueId: string,
+): Promise<AttachedDocument[]> {
+  const out: AttachedDocument[] = [];
+  const seen = new Set<string>();
+  const add = (doc: RawDocument | null): void => {
+    if (!doc || seen.has(doc.id)) return;
+    const attached = toAttached(doc);
+    if (!attached) return;
+    seen.add(doc.id);
+    out.push(attached);
+  };
+
+  for (const doc of await source.issueDocuments(issueId)) add(doc);
+
+  const urls = await source.issueAttachmentUrls(issueId);
+  const slugs = [...new Set(urls.map(documentSlugFromUrl).filter((s): s is string => s !== null))];
+  for (const slug of slugs) {
+    try {
+      add(await source.documentBySlug(slug));
+    } catch {
+      // best-effort: a deleted/unauthorised document link is skipped, not fatal.
+    }
+  }
+  return out;
+}
+
+/** The live `DocumentSource`, backed by a Linear bearer token. Uses the typed SDK. */
+export function linearDocumentSource(token: string): DocumentSource {
+  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 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 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 doc = await client.document(slug);
+      return {
+        id: doc.id,
+        slugId: doc.slugId,
+        title: doc.title,
+        url: doc.url,
+        content: doc.content ?? undefined,
+      };
+    },
+  };
+}
+
+/**
+ * Fetch the documents attached to a Linear issue as contract `AttachedDocument`s, ready to snapshot
+ * into a run. The single entry point the hub calls; resolves the source from the token and runs the
+ * pure assembly. Never throws on a single bad document link (best-effort), but a hard failure (auth,
+ * network) propagates so the caller can log and proceed with none.
+ */
+export async function fetchAttachedDocuments(
+  token: string,
+  issueId: string,
+): Promise<AttachedDocument[]> {
+  return collectAttachedDocuments(linearDocumentSource(token), issueId);
+}