@aivi/tracker-linear 0.0.0-stage → 1.0.0

package/dist/webhook.d.ts

@@ -0,0 +1,97 @@
+/** How far a webhook's own timestamp may be from now before it is treated as a replay. */
+export declare const WEBHOOK_MAX_SKEW_MS = 60000;
+export type WebhookVerdict = {
+    ok: true;
+    payload: LinearWebhook;
+} | {
+    ok: false;
+    status: number;
+    reason: string;
+};
+/** The parts of an `AgentSessionEvent` payload the module reads. Untrusted input. */
+export interface AgentSessionEventPayload {
+    type: 'AgentSessionEvent';
+    action: 'created' | 'prompted';
+    organizationId: string;
+    oauthClientId?: string;
+    appUserId?: string;
+    webhookTimestamp: number;
+    agentSession: {
+        id: string;
+        status?: string;
+        issue?: {
+            id: string;
+            identifier?: string;
+            title?: string;
+            team?: {
+                id: string;
+                key?: string;
+            };
+        } | null;
+        comment?: {
+            id: string;
+        } | null;
+    };
+    agentActivity?: {
+        id: string;
+        content?: {
+            type?: string;
+            body?: string;
+        };
+        signal?: string | null;
+    };
+    promptContext?: string;
+    guidance?: unknown;
+    previousComments?: unknown;
+}
+/** An issue data-change payload; the listener reads state and label changes. */
+export interface IssueEventPayload {
+    type: 'Issue';
+    action: 'create' | 'update' | 'remove';
+    organizationId: string;
+    webhookTimestamp: number;
+    data: {
+        id: string;
+        identifier?: string;
+        title?: string;
+        stateId?: string;
+        state?: {
+            id: string;
+            name: string;
+            type?: string;
+        };
+        labelIds?: string[];
+        labels?: {
+            id: string;
+            name: string;
+        }[];
+        teamId?: string;
+        delegateId?: string | null;
+        branchName?: string;
+    };
+    updatedFrom?: Record<string, unknown>;
+    url?: string;
+}
+export interface OtherPayload {
+    type: string;
+    action: string;
+    organizationId?: string;
+    webhookTimestamp: number;
+}
+export type LinearWebhook = AgentSessionEventPayload | IssueEventPayload | OtherPayload;
+/**
+ * Verify one delivery the way Linear documents it: HMAC-SHA256 of the raw
+ * body with the app's webhook signing secret, compared in constant time
+ * against `Linear-Signature`, then the payload's own `webhookTimestamp`
+ * within a minute of now. The body is parsed only after both hold.
+ */
+export declare function verifyWebhook(input: {
+    body: Buffer;
+    signature: string | string[] | undefined;
+    secret: string;
+    now?: number;
+}): WebhookVerdict;
+export declare const isAgentSessionEvent: (p: LinearWebhook) => p is AgentSessionEventPayload;
+export declare const isIssueEvent: (p: LinearWebhook) => p is IssueEventPayload;
+/** Sign a body the way Linear does; tests and the live check use it. */
+export declare function signWebhook(body: Buffer | string, secret: string): string;

package/dist/webhook.js

@@ -0,0 +1,40 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** How far a webhook's own timestamp may be from now before it is treated as a replay. */
+export const WEBHOOK_MAX_SKEW_MS = 60_000;
+/**
+ * Verify one delivery the way Linear documents it: HMAC-SHA256 of the raw
+ * body with the app's webhook signing secret, compared in constant time
+ * against `Linear-Signature`, then the payload's own `webhookTimestamp`
+ * within a minute of now. The body is parsed only after both hold.
+ */
+export function verifyWebhook(input) {
+    const header = Array.isArray(input.signature) ? input.signature[0] : input.signature;
+    if (!header)
+        return { ok: false, status: 401, reason: 'missing Linear-Signature' };
+    const expected = createHmac('sha256', input.secret).update(input.body).digest();
+    const provided = Buffer.from(header, 'hex');
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected))
+        return { ok: false, status: 401, reason: 'signature mismatch' };
+    let payload;
+    try {
+        payload = JSON.parse(input.body.toString('utf8'));
+    }
+    catch {
+        return { ok: false, status: 400, reason: 'body is not JSON' };
+    }
+    if (!isRecord(payload) || typeof payload.type !== 'string' || typeof payload.action !== 'string')
+        return { ok: false, status: 400, reason: 'payload has no type/action' };
+    const ts = payload.webhookTimestamp;
+    if (typeof ts !== 'number')
+        return { ok: false, status: 400, reason: 'payload has no webhookTimestamp' };
+    if (Math.abs((input.now ?? Date.now()) - ts) > WEBHOOK_MAX_SKEW_MS)
+        return { ok: false, status: 401, reason: 'webhookTimestamp outside the replay window' };
+    return { ok: true, payload: payload };
+}
+export const isAgentSessionEvent = (p) => p.type === 'AgentSessionEvent' && (p.action === 'created' || p.action === 'prompted');
+export const isIssueEvent = (p) => p.type === 'Issue';
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/** Sign a body the way Linear does; tests and the live check use it. */
+export function signWebhook(body, secret) {
+    return createHmac('sha256', secret).update(body).digest('hex');
+}

package/dist/work.d.ts

@@ -0,0 +1,66 @@
+import type { Logger } from '@aivi/core';
+import type { AiviServices } from '@aivi/plugin';
+import type { LinearClient } from './client.ts';
+import type { LinearConfig } from './config.ts';
+/** The ticket's own words: what it is, what it says. This is the **summary**
+ *  `initWork` hands the orchestrator, and the orchestrator composes the
+ *  worker's first prompt around it — the same dossier for a queue pickup
+ *  and a plain walk claim: the ticket's text does not depend on how the
+ *  worker was reached. */
+export declare const issueDossier: (issue: {
+    identifier: string;
+    title: string;
+    description: string | null;
+}) => string;
+/** What the walk reads and what `initWork` opens through: the Linear board,
+ *  in the installation's own credentials. */
+export interface LinearBoard {
+    projects(): string[];
+    tickets(projectId: string, lane: string): Promise<{
+        id: string;
+        blocked: boolean;
+    }[]>;
+    moveTo(projectId: string, ticketId: string, lane: string): Promise<void>;
+    /** The ticket fresh from the board, or null when a person deleted it. */
+    issue(ticketId: string): Promise<LinearIssueWords | undefined>;
+}
+/** The fields of a listed issue the tracker's stages speak with. */
+export interface LinearIssueWords {
+    identifier: string;
+    title: string;
+    description: string | null;
+    teamId: string;
+    stateName: string;
+    /** Linear's branch name for the issue: what a worktree lane checks out. */
+    branchName: string;
+}
+/**
+ * The Linear board as the orchestrator's eligibility walk reads it
+ * (docs/orchestrator.md, "How work gets picked"): which projects this
+ * installation speaks for, what sits in a lane top-to-bottom, and how a
+ * ticket enters a lane.
+ *
+ * The adapter is conversation-keyed because a webhook arrives through an
+ * agent session; the walk has no session and no conversation, so this reads
+ * with the installation's own credentials — the primary app, the one that
+ * carries workspace data. Reads are one client and one team-and-state
+ * board, both fetched once per module start: the states a walk matches
+ * lanes against change when a person changes them, and a restart is when
+ * aivi learns of that.
+ *
+ * What comes back **is** eligible work: archived tickets, tickets carrying
+ * the human-work label, and tickets that already have a delegate are left
+ * out here, because those are Linear's words for "a person owns this" and
+ * the orchestrator never learns Linear's words. A delegate rules the ticket
+ * out (ruled 2026-10-02): someone already speaks for it, and re-delegating
+ * to the user it already has is a mutation no-op — Linear makes no session
+ * for it, which was seven silent failures; now the walk simply leaves the
+ * ticket alone until a person clears the delegate. A stop is not remembered
+ * here (ruled 2026-10-02): a stopped ticket goes back to the board, and
+ * "not that one again" is the HITL label's job, not a memory in somebody's
+ * database.
+ *
+ * `openClient` is the loader seam the knowledge service also uses: tests
+ * read a fake board with no credentials; production reads the primary app.
+ */
+export declare function linearBoard(config: LinearConfig, services: Pick<AiviServices, 'loaded'>, log: Logger, openClient?: (app: string) => LinearClient): LinearBoard;

package/dist/work.js

@@ -0,0 +1,98 @@
+import { primaryLinearApp } from './config.js';
+import { projectLinear } from './projects.js';
+import { clientFor, isClosed } from './tracker.js';
+/** The ticket's own words: what it is, what it says. This is the **summary**
+ *  `initWork` hands the orchestrator, and the orchestrator composes the
+ *  worker's first prompt around it — the same dossier for a queue pickup
+ *  and a plain walk claim: the ticket's text does not depend on how the
+ *  worker was reached. */
+export const issueDossier = (issue) => `<issue identifier="${issue.identifier}"><title>${issue.title}</title><description>${issue.description ?? ''}</description></issue>`;
+/**
+ * The Linear board as the orchestrator's eligibility walk reads it
+ * (docs/orchestrator.md, "How work gets picked"): which projects this
+ * installation speaks for, what sits in a lane top-to-bottom, and how a
+ * ticket enters a lane.
+ *
+ * The adapter is conversation-keyed because a webhook arrives through an
+ * agent session; the walk has no session and no conversation, so this reads
+ * with the installation's own credentials — the primary app, the one that
+ * carries workspace data. Reads are one client and one team-and-state
+ * board, both fetched once per module start: the states a walk matches
+ * lanes against change when a person changes them, and a restart is when
+ * aivi learns of that.
+ *
+ * What comes back **is** eligible work: archived tickets, tickets carrying
+ * the human-work label, and tickets that already have a delegate are left
+ * out here, because those are Linear's words for "a person owns this" and
+ * the orchestrator never learns Linear's words. A delegate rules the ticket
+ * out (ruled 2026-10-02): someone already speaks for it, and re-delegating
+ * to the user it already has is a mutation no-op — Linear makes no session
+ * for it, which was seven silent failures; now the walk simply leaves the
+ * ticket alone until a person clears the delegate. A stop is not remembered
+ * here (ruled 2026-10-02): a stopped ticket goes back to the board, and
+ * "not that one again" is the HITL label's job, not a memory in somebody's
+ * database.
+ *
+ * `openClient` is the loader seam the knowledge service also uses: tests
+ * read a fake board with no credentials; production reads the primary app.
+ */
+export function linearBoard(config, services, log, openClient = app => clientFor(config, app, log)) {
+    let reader;
+    const read = () => (reader ??= openClient(primaryLinearApp(config) ?? ''));
+    let board;
+    const teams = async () => (board ??= await read().listTeams());
+    /** A ticket the walk may start: not deleted between the listing and this
+     *  breath, not a person's to work, and nobody else already speaks for it —
+     *  not eligible, and never knocked twice. */
+    const walkable = (issue) => !issue.archivedAt && !issue.labels.some(l => l.name === config.humanLabel) && !issue.delegate;
+    return {
+        projects: () => services.loaded.projects.filter(p => !p.removed && projectLinear(services.loaded, p.id)).map(p => p.id),
+        tickets: async (projectId, state) => {
+            const linear = projectLinear(services.loaded, projectId);
+            if (!linear)
+                return [];
+            const out = [];
+            for (const teamId of linear.teams) {
+                const team = (await teams()).find(t => t.id === teamId);
+                const lane = team?.states.find(s => s.name === state);
+                if (!team || !lane)
+                    continue; // this team's workflow has no such lane: nothing sits there
+                const page = await read().issuesIn(team.id, lane.id);
+                if (page.truncated)
+                    log.warn('walk.board.truncated', { project: projectId, lane: state, team: team.key });
+                for (const issue of page.issues) {
+                    if (!walkable(issue))
+                        continue;
+                    out.push({ id: issue.id, blocked: issue.blockedBy.some(b => !isClosed(b.state.type)) });
+                }
+            }
+            return out;
+        },
+        moveTo: async (projectId, ticketId, state) => {
+            const issue = await read().issue(ticketId);
+            const team = (await teams()).find(t => t.id === issue.team.id);
+            const lane = team?.states.find(s => s.name === state);
+            if (!team || !lane)
+                throw new Error(`Linear team ${issue.team.key} has no state "${state}": ${ticketId} cannot enter project ${projectId}`);
+            // Idempotence is the board's promise: the orchestrator re-drives an
+            // owed move after a retry and from the next boot, and a move that
+            // already landed lands here as nothing — no second word to Linear.
+            if (issue.state.name === state)
+                return;
+            await read().transitionIssue(ticketId, lane.id);
+        },
+        issue: async (ticketId) => {
+            const issue = await read().issue(ticketId);
+            if (issue.archivedAt)
+                return undefined; // deleted: not work, and the stage says so
+            return {
+                identifier: issue.identifier,
+                title: issue.title,
+                description: issue.description ?? null,
+                teamId: issue.team.id,
+                stateName: issue.state.name,
+                branchName: issue.branchName,
+            };
+        },
+    };
+}

package/docs/linear.md

@@ -0,0 +1,90 @@
+# Linear — the tracker's configuration
+
+The `plugins.tracker-linear` block is the Linear module's whole setup; the
+module runs when `@aivi/tracker-linear` stands in the `aivi-plugins` list.
+The key is the package name; the database's prefix, the webhook URL Linear's
+dashboard holds and the `aivi linear` command keep the platform's short
+name, since those say who a conversation is on rather than which package
+speaks for it.
+
+```json
+{
+  "plugins": {
+    "tracker-linear": {
+      "agent": "aivi",
+      "primary": "aivi",
+      "apps": { "aivi": {}, "reviewer": {} },
+      "logMisroutes": true,
+      "humanLabel": "needs-human",
+      "pool": "default",
+      "progress": "tools"
+    }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `agent` | The OpenCode agent that answers people on Linear — comment mentions above all: the **assistant**. A hand delegation is never its to answer: those get the fixed refusal. Default: `assistant` |
+| `primary` | The app that carries the workspace's data feed, signs the bare `LINEAR_*` secrets and authorises the Linear MCP. Default: the one app; required once several apps are configured |
+| `apps.<id>` | A Linear OAuth application acting as an app user. The primary does the receiving; every other app is a **face** — a name and icon in Linear's UI with its own credentials, no routing meaning |
+| `logMisroutes` | `true`: log at warn a webhook delivered to the wrong endpoint — a data change on a face's route. It is dropped either way |
+| `humanLabel` | Issues with this label are never worked automatically — the only "not that one again" there is (a stop remembers nothing); a session created on one is refused with an explanation, and a failed closing or an unkillable worker marks the ticket with it |
+| `pool` | Dispatcher pool a worker turn takes a slot in (must exist in `dispatcher.pools` when pools are configured) |
+| `mcp` | On by default: the module serves Linear's hosted MCP on loopback (default port 4101), authorised with the app-actor token, so agents can act in Linear and writes attribute to the app; `false` disables it |
+| `progress` | `silent`, `status` or `tools`: what the ephemeral activities show while a worker runs |
+
+The project entry routes by Linear **team** (a repository may list several
+teams — one checkout, several teams; a team belongs to at most one project;
+Linear *projects* (epics) play no routing part). The workflow itself is not a
+Linear field: it is **core's** lane array on the project,
+`projects.<id>.lanes` — left to right, the order **is** the priority:
+
+```json
+{
+  "projects": {
+    "website": {
+      "tracker-linear": { "teams": ["linear-team-id"] },
+      "lanes": [
+        { "name": "Todo", "queue": true },
+        { "name": "In Progress", "agent": "dev", "pool": "worker", "worktree": true },
+        { "name": "Review", "agent": "reviewer" },
+        { "name": "Release" }
+      ]
+    }
+  }
+}
+```
+
+A lane naming an `agent` is worked; one naming none is worked by humans; a
+tracker state named nowhere in the array is silence. `next` and `previous`
+override where a success and a failure move the ticket — neighbours by
+default, and a stop never moves. `queue: true` marks the workflow's **one**
+queue lane: fresh work waiting for capacity, an extension of the worker lane
+it feeds; the load says so loudly for two queue lanes, a queue lane naming
+an agent, or a queue whose next lane (by order or by `next`) works nothing.
+`pool` names the dispatcher pool the lane's work draws capacity from.
+`worktree: true` gives the worker its own git worktree; default false works
+the project checkout itself, where the agent file's own `edit` deny is the
+only guard. **Every state is asked** (ruled 2026-10-08): the
+wizard asks what kind of lane each state is — Agent, Human, or None. Linear's
+`type` is real API data, so it sets which answer the question starts on (a
+`completed` state starts on Human, `canceled` and `duplicate` on None); the
+person's answer wins. A state answered None is not in the array: aivi never
+reads it and never moves a ticket into it. `aivi projects add` writes the
+array for you — names, kinds, agents, worktrees, and the one queue question.
+`teams` is never defaulted.
+`workspaceId` is optional and only needed when the installation spans Linear
+workspaces; `projectDefaults.tracker-linear.workspaceId` supplies it to every
+project that omits its own. The mapped agent is resolved by OpenCode's
+ordinary discovery for the session's directory; an unknown agent file is
+OpenCode's own error at session start, not a config error.
+
+Credentials are never in JSON. The **primary** app reads the bare
+`LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET` and `LINEAR_WEBHOOK_SECRET` — the
+bare names mean *the one app*. Every other app follows the convention
+`LINEAR_<APP>_CLIENT_ID`, `LINEAR_<APP>_CLIENT_SECRET` and
+`LINEAR_<APP>_WEBHOOK_SECRET` (`<APP>` is the app id upper-cased with `-` as
+`_`, so `dev-app` reads `LINEAR_DEV_APP_CLIENT_ID`). The Linear MCP, when
+enabled (`plugins.tracker-linear.mcp`), is served by the module itself on
+loopback and authorised with the primary's app-actor token.

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@aivi/tracker-linear",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "development": "./src/config.ts",
+      "default": "./dist/config.js"
+    },
+    "./setup": {
+      "development": "./src/setup.ts",
+      "default": "./dist/setup.js"
+    },
+    "./setupProject": {
+      "development": "./src/setup-project.ts",
+      "default": "./dist/setup-project.js"
+    },
+    "./cli": {
+      "development": "./src/cli.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=26.1.0 <27"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aivi-hq/aivi.git",
+    "directory": "packages/tracker-linear"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "tsc -b tsconfig.build.json"
+  },
+  "dependencies": {
+    "@aivi/core": "^1.0.0",
+    "@aivi/plugin": "^1.0.0",
+    "commander": "15.0.0",
+    "zod": "4.1.13"
+  },
+  "peerDependencies": {
+    "@aivi/host": "^1.0.0"
+  },
+  "devDependencies": {
+    "@aivi/host": "^1.0.0"
+  }
+}