@aivi/tracker-linear 0.0.0-stage → 1.0.0

package/dist/client.js

@@ -0,0 +1,362 @@
+import { errorMessage, getLogger } from '@aivi/core';
+import { MODULE_ID } from './config.js';
+export class LinearApiError extends Error {
+    status;
+    /** GraphQL error codes (`extensions.code`), kept apart because the HTTP
+     *  status says nothing about them — Linear answers entity-not-found with a
+     *  200. Empty for transport and token errors. */
+    codes;
+    constructor(message, status, codes = []) {
+        super(message);
+        this.name = 'LinearApiError';
+        this.status = status;
+        this.codes = codes;
+    }
+    /** Linear's word for "that entity is gone", whatever shape it comes in: a
+     *  deleted issue takes its agent session with it, and every later call
+     *  names it. The message is the stable part (`Entity not found: …`); the
+     *  codes only say *how* Linear refused (`INPUT_ERROR` for a lookup of a
+     *  dead session, live 2026-10-06), never *what*, so no code may stand in
+     *  for the words. */
+    static isGone(error) {
+        return error instanceof LinearApiError && /entity not found/i.test(error.message);
+    }
+}
+const DEFAULT_SCOPE = 'read,write,app:assignable,app:mentionable';
+const ISSUE_FIELDS = `
+  id identifier title description branchName url
+  state { id name type }
+  team { id key }
+  labels { nodes { id name } }
+  delegate { id }
+  assignee { id name }
+  archivedAt
+  priority
+  createdAt
+  inverseRelations { nodes { type issue { id state { id name type } } } }
+`;
+const issueOf = ({ labels, inverseRelations, ...rest }) => ({
+    ...rest,
+    labels: labels.nodes,
+    // The live Linear schema has no `blockedBy` on Issue: relations are
+    // directional, and in `inverseRelations` the relation's source (`issue`) is
+    // the blocker of our issue, with `type` the lowercase string `blocks`.
+    blockedBy: inverseRelations.nodes.filter(r => r.type === 'blocks').map(r => r.issue),
+});
+/**
+ * A small GraphQL client for one Linear app. The token is obtained with the
+ * `client_credentials` grant (an `app` actor token valid for 30 days), kept in
+ * memory, refreshed ahead of its expiry and re-fetched once on a 401. There is
+ * no `@linear/sdk`: six operations do not justify it.
+ */
+/** Linear's workflow state groups in board order. `position` is scoped
+ *  **within a type group** (SDL: "States are displayed in ascending order
+ *  of position within their type group"), so sorting by position alone
+ *  interleaves the groups: Done and Canceled each rank near 0 of their own
+ *  group and would sort before a late `started` lane. Group first, then
+ *  position — that is the board. */
+const stateGroupOrder = ['triage', 'backlog', 'unstarted', 'started', 'completed', 'canceled', 'duplicate'];
+const byBoardOrder = (a, b) => {
+    const group = stateGroupOrder.indexOf(a.type) - stateGroupOrder.indexOf(b.type);
+    return group !== 0 ? group : a.position - b.position;
+};
+export class LinearClient {
+    credentials;
+    baseUrl;
+    fetchImpl;
+    log;
+    scope;
+    skew;
+    token = null;
+    refreshing = null;
+    constructor(credentials, options = {}) {
+        this.credentials = credentials;
+        this.baseUrl = (options.baseUrl ?? 'https://api.linear.app').replace(/\/$/, '');
+        this.fetchImpl = options.fetch ?? fetch;
+        this.log = options.log ?? getLogger(['aivi', MODULE_ID]);
+        this.scope = options.scope ?? DEFAULT_SCOPE;
+        this.skew = options.refreshSkewMs ?? 3_600_000;
+    }
+    /** A valid token, fetching or refreshing when needed; concurrent callers share one request. */
+    async accessToken(force = false) {
+        if (!force && this.token && this.token.expiresAt - this.skew > Date.now())
+            return this.token.value;
+        if (!this.refreshing) {
+            this.refreshing = this.fetchToken().finally(() => {
+                this.refreshing = null;
+            });
+        }
+        return this.refreshing;
+    }
+    async fetchToken() {
+        const body = new URLSearchParams({ grant_type: 'client_credentials', scope: this.scope });
+        const basic = Buffer.from(`${this.credentials.clientId}:${this.credentials.clientSecret}`).toString('base64');
+        const response = await this.fetchImpl(`${this.baseUrl}/oauth/token`, {
+            method: 'POST',
+            headers: { authorization: `Basic ${basic}`, 'content-type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new LinearApiError(`Linear token request failed (${response.status}): ${describe(text)}`, response.status);
+        }
+        const parsed = JSON.parse(text);
+        if (!parsed.access_token)
+            throw new LinearApiError('Linear token response had no access_token', 502);
+        this.token = { value: parsed.access_token, expiresAt: Date.now() + (parsed.expires_in ?? 86_400) * 1000 };
+        // A token fetch per API burst is debug-level detail, not something a setup prompt should interleave.
+        this.log.debug('linear.token', { expiresIn: parsed.expires_in ?? null });
+        return this.token.value;
+    }
+    /** Run one GraphQL operation; a 401 refreshes the token and retries once. */
+    async graphql(query, variables = {}, retried = false) {
+        const token = await this.accessToken();
+        const response = await this.fetchImpl(`${this.baseUrl}/graphql`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ query, variables }),
+        });
+        if (response.status === 401 && !retried) {
+            await this.accessToken(true);
+            return this.graphql(query, variables, true);
+        }
+        const text = await response.text();
+        if (!response.ok)
+            throw new LinearApiError(`Linear API ${response.status}: ${describe(text)}`, response.status);
+        const parsed = JSON.parse(text);
+        if (parsed.errors?.length)
+            throw new LinearApiError(parsed.errors.map(e => e.message).join('; '), 200, parsed.errors.map(e => e.extensions?.code ?? ''));
+        if (parsed.data === undefined)
+            throw new LinearApiError('Linear API returned no data', 502);
+        return parsed.data;
+    }
+    /** The app user's own id and its workspace in one round; also proves the
+     *  credentials work. The tracker adapter learns `userId`/`orgId` here. */
+    async viewer() {
+        const data = await this.graphql('query { viewer { id organization { id } } }');
+        return { id: data.viewer.id, organizationId: data.viewer.organization.id };
+    }
+    /** The app user's own id in this workspace; also proves the credentials work. */
+    async viewerId() {
+        return (await this.viewer()).id;
+    }
+    /** The teams this app can see with their workflow states, archived excluded:
+     * the answer to "which id is PEC?" and "which lanes does PEC have?".
+     * Linear returns `states` as a connection; its `nodes` are flattened here. */
+    async listTeams() {
+        const data = await this.graphql('query { teams { nodes { id key name states { nodes { id name type position } } } } }');
+        // The connection's own order is not the board's; the group order and
+        // the per-group `position` are.
+        return data.teams.nodes.map(team => ({
+            id: team.id,
+            key: team.key,
+            name: team.name,
+            states: team.states.nodes.sort(byBoardOrder).map(({ position: _position, ...state }) => state),
+        }));
+    }
+    async createActivity(input) {
+        const data = await this.graphql(`mutation($input: AgentActivityCreateInput!) { agentActivityCreate(input: $input) { success agentActivity { id } } }`, { input });
+        if (!data.agentActivityCreate.success)
+            throw new LinearApiError('agentActivityCreate was not successful', 200);
+        return data.agentActivityCreate.agentActivity.id;
+    }
+    /** Move an issue to a workflow state by its id — how a lane move is
+     *  performed. (schema: `issueUpdate(id: String!, input: IssueUpdateInput!)`,
+     *  the state carried as `input.stateId`.) */
+    async transitionIssue(issueId, stateId) {
+        const data = await this.graphql(`mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success } }`, { id: issueId, input: { stateId } });
+        if (!data.issueUpdate.success)
+            throw new LinearApiError('issueUpdate was not successful', 200);
+    }
+    /** The label id a name stands for on a team: the team's own label wins over
+     *  the workspace's when both carry the name (the API applies any label to
+     *  any issue, so the disambiguation lives here), and a name no label
+     *  answers is **created on the team** — the human label must be applicable
+     *  without a visit to settings first. (schema:
+     *  `issueLabels(filter: {name: {eq}})`, `issueLabelCreate(input:)`.) */
+    async labelIdForTeam(teamId, name) {
+        const data = await this.graphql(`query($name: String!) { issueLabels(filter: { name: { eq: $name } }, first: 25) { nodes { id team { id } } } }`, { name });
+        const eligible = data.issueLabels.nodes.filter(l => l.team === null || l.team.id === teamId);
+        const existing = eligible.find(l => l.team?.id === teamId) ?? eligible[0];
+        if (existing)
+            return existing.id;
+        const created = await this.graphql(`mutation($input: IssueLabelCreateInput!) { issueLabelCreate(input: $input) { success issueLabel { id } } }`, { input: { name, teamId } });
+        if (!created.issueLabelCreate.success)
+            throw new LinearApiError(`label "${name}" was not created`, 200);
+        return created.issueLabelCreate.issueLabel.id;
+    }
+    /** Put a label on an issue — how the human label marks a ticket: a stop,
+     *  a failed closing, a stop the runtime would not answer. (schema:
+     *  `issueAddLabel(id: String!, labelId: String!)`.) */
+    async addLabel(issueId, labelId) {
+        const data = await this.graphql(`mutation($id: String!, $labelId: String!) { issueAddLabel(id: $id, labelId: $labelId) { success } }`, { id: issueId, labelId });
+        if (!data.issueAddLabel.success)
+            throw new LinearApiError('issueAddLabel was not successful', 200);
+    }
+    /** Take a label off an issue — the lift that lets the walk work a marked
+     *  ticket again. (schema: `issueRemoveLabel(id: String!, labelId: String!)`.) */
+    async removeLabel(issueId, labelId) {
+        const data = await this.graphql(`mutation($id: String!, $labelId: String!) { issueRemoveLabel(id: $id, labelId: $labelId) { success } }`, { id: issueId, labelId });
+        if (!data.issueRemoveLabel.success)
+            throw new LinearApiError('issueRemoveLabel was not successful', 200);
+    }
+    /** A comment on the **issue** itself, not the agent session's activity:
+     *  the closing note a person reads without opening the session. Posted
+     *  with the app's token, so it stands as the app's comment. */
+    async createComment(issueId, body) {
+        const data = await this.graphql(`mutation($input: CommentCreateInput!) { commentCreate(input: $input) { success } }`, { input: { issueId, body } });
+        if (!data.commentCreate.success)
+            throw new LinearApiError('commentCreate was not successful', 200);
+    }
+    /** The ticket's comment trail, oldest first — what `aivi_ticket_comments`
+     *  reads back. The author is the writer's display name when Linear gives
+     *  one; the app's own comments carry the app's name like any other. */
+    async issueComments(issueId) {
+        const data = await this.graphql(`query($id: String!) { issue(id: $id) { comments(first: 100) { nodes { body createdAt user { name } } } } }`, {
+            id: issueId,
+        });
+        if (!data.issue)
+            throw new LinearApiError('Entity not found: Issue', 200);
+        return data.issue.comments.nodes
+            .map(c => ({ author: c.user?.name ?? null, body: c.body, at: c.createdAt }))
+            .sort((a, b) => a.at.localeCompare(b.at));
+    }
+    /** Rewrite the ticket's own words — what `aivi_ticket_edit` performs.
+     *  Only the fields named are touched; Linear answers with the ticket as
+     *  it now stands. */
+    async issueUpdate(issueId, changes) {
+        const data = await this.graphql(`mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { ${ISSUE_FIELDS} } } }`, { id: issueId, input: changes });
+        if (!data.issueUpdate.success || !data.issueUpdate.issue)
+            throw new LinearApiError('issueUpdate was not successful', 200);
+        return issueOf(data.issueUpdate.issue);
+    }
+    /** The team's label catalogue — the names a worker may add or remove. */
+    async teamLabelNames(teamId) {
+        const data = await this.graphql(`query($id: String!) { team(id: $id) { labels(first: 50) { nodes { name } } } }`, { id: teamId });
+        if (!data.team)
+            throw new LinearApiError(`team ${teamId} not found`, 200);
+        return data.team.labels.nodes.map(l => l.name);
+    }
+    /** What a closing note asks Linear for in one round: the issue's comment
+     *  bodies (the idempotence check — a note already standing is never
+     *  posted twice) and the agent sessions with their web urls (the note's
+     *  marker and the link a person clicks to read the whole trail). The
+     *  comment page is deliberately wide: the check must see a note older
+     *  than any retry horizon. */
+    async closingNoteFacts(issueId) {
+        const data = await this.graphql(`query($id: String!) { issue(id: $id) { comments(first: 100) { nodes { body } } agentSessions { nodes { id url } } } }`, { id: issueId });
+        if (!data.issue)
+            throw new LinearApiError(`issue ${issueId} not found`, 200);
+        return { comments: data.issue.comments.nodes, sessions: data.issue.agentSessions.nodes };
+    }
+    /** Whether Linear has closed this agent session: `endedAt` is its own word
+     *  for "the result was shown", which is what a follower's retry asks
+     *  before it would render a result twice. */
+    async agentSessionEnded(agentSessionId) {
+        const data = await this.graphql('query($id: String!) { agentSession(id: $id) { endedAt } }', { id: agentSessionId });
+        return data.agentSession.endedAt !== null;
+    }
+    /** Replace the session's plan wholesale — Linear takes the full array
+     *  every time (docs/agent-interaction, Agent Plans: partial updates are
+     *  explicitly not a thing). `plan` is a JSONObject: the steps array as
+     *  `{content, status}`. */
+    async setPlan(agentSessionId, steps) {
+        const data = await this.graphql(`mutation($id: String!, $input: AgentSessionUpdateInput!) { agentSessionUpdate(id: $id, input: $input) { success } }`, { id: agentSessionId, input: { plan: steps } });
+        if (!data.agentSessionUpdate.success)
+            throw new LinearApiError('agentSessionUpdate was not successful', 200);
+    }
+    /** Tickets sitting in one state of one team — the eligibility walk's
+     *  top-to-bottom reading. Linear's public query cannot sort (its `sort`
+     *  parameter is internal), so the board's order is computed here:
+     *  Linear's own priority sort — Urgent first, unranked last — and oldest
+     *  first within a rank. Archived issues never show: the connection
+     *  leaves them out unless asked. `truncated` says more than 100 sit in
+     *  the lane; the walk is told rather than shown a partial board in
+     *  silence. */
+    async issuesIn(teamId, stateId) {
+        const data = await this.graphql(
+        // ID! not String!: Linear's id filters are typed ID and answer a
+        // String variable with a 400 (live, 2026-10-02 — the fake board could
+        // never catch this, so the walk met it first). Direct id arguments
+        // (`issue(id: $id)`) do accept String; filter comparisons do not.
+        `query($teamId: ID!, $stateId: ID!) {
+         issues(
+           filter: { team: { id: { eq: $teamId } }, state: { id: { eq: $stateId } } }
+           orderBy: createdAt
+           first: 100
+         ) { nodes { ${ISSUE_FIELDS} } pageInfo { hasNextPage } }
+       }`, { teamId, stateId });
+        const rank = (priority) => (priority === 0 ? 5 : priority);
+        const issues = data.issues.nodes
+            .map(issueOf)
+            .sort((a, b) => rank(a.priority) - rank(b.priority) || a.createdAt.localeCompare(b.createdAt));
+        return { issues, truncated: data.issues.pageInfo.hasNextPage };
+    }
+    async issue(id) {
+        const data = await this.graphql(`query($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }`, { id });
+        // A deleted issue answers as missing, in words the closing already
+        // knows: without this a null would crash the caller instead of saying
+        // what it means.
+        if (!data.issue)
+            throw new LinearApiError('Entity not found: Issue', 200);
+        return issueOf(data.issue);
+    }
+    /** Make (or unmake, with `null`) this app the issue's delegate; the human
+     *  assignee stays. Making the app the delegate is what creates the agent
+     *  session — Linear returns it in this very answer (live, 2026-09-26). */
+    async setDelegate(issueId, delegateId) {
+        const data = await this.graphql(`mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { identifier agentSessions { nodes { id status startedAt url } } } } }`, { id: issueId, input: { delegateId } });
+        if (!data.issueUpdate.success)
+            throw new LinearApiError('issueUpdate(delegateId) failed', 200);
+        return data.issueUpdate;
+    }
+    /** Create an issue in a team — the installer's throwaway ticket and the
+     *  worker's escape hatch. `stateId` lands it in a named workflow state;
+     *  omitted, Linear's own default (the team's triage) takes it. */
+    async createIssue(input) {
+        const data = await this.graphql(`mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { ${ISSUE_FIELDS} } } }`, { input });
+        if (!data.issueCreate.success)
+            throw new LinearApiError('issueCreate failed', 200);
+        return issueOf(data.issueCreate.issue);
+    }
+    /** Archive an issue — Linear's delete, off the board. The installer tidies
+     *  its own throwaway ticket with this. */
+    async deleteIssue(issueId) {
+        const data = await this.graphql(`mutation($id: String!) { issueDelete(id: $id) { success } }`, { id: issueId });
+        if (!data.issueDelete.success)
+            throw new LinearApiError('issueDelete failed', 200);
+    }
+}
+/**
+ * Turn what an operator pastes — a team key from a Linear URL or a raw team id —
+ * into the ids the config must hold. An exact id matches first, then a key
+ * regardless of case; duplicates collapse and the given order is kept. An
+ * unknown token is an error naming it and listing the teams the app can see:
+ * a private team the app has not joined shows up here as unknown.
+ */
+export function resolveTeams(teams, tokens) {
+    const byId = new Map(teams.map(t => [t.id, t.id]));
+    const byKey = new Map(teams.map(t => [t.key.toLowerCase(), t.id]));
+    const out = [];
+    for (const token of tokens) {
+        const id = byId.get(token) ?? byKey.get(token.toLowerCase());
+        if (!id) {
+            const visible = teams.map(t => `${t.key} (${t.name})`).join(', ') || 'none';
+            throw new Error(`${token} is not a team this app can see (visible: ${visible}). A private team needs the app added to it.`);
+        }
+        if (!out.includes(id))
+            out.push(id);
+    }
+    return out;
+}
+const describe = (text) => {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed.errors?.length)
+            return parsed.errors.map(e => e.message).join('; ');
+        return [parsed.error, parsed.error_description].filter(Boolean).join(': ') || text.slice(0, 200);
+    }
+    catch (error) {
+        return text.slice(0, 200) || errorMessage(error);
+    }
+};

package/dist/config.d.ts

@@ -0,0 +1,94 @@
+import type { AiviPlugin } from '@aivi/plugin';
+import { z } from 'zod';
+/**
+ * The Linear module. One app does the work: it carries the workspace's
+ * **Issues** data feed on its webhook route, receives every agent-session
+ * event, and its token authorises the Linear MCP. Extra apps are *faces* — a
+ * name and icon in Linear's UI, their own credentials (`LINEAR_<APP>_*`) and
+ * webhook route, no routing meaning. Lanes are core's
+ * own (`projects.<id>.lanes`, ordered); this block maps teams to the project. The block
+ * lives at `plugins.tracker-linear` in config.json — the module id is the
+ * package name, ruled 2026-09-30 — and the `aivi-plugins` list in
+ * app/package.json says whether the module runs.
+ */
+/** The module id, and with it the key of this plugin's block in `config.json`
+ *  (`plugins.tracker-linear`), its `/status` id and its log category: the module
+ *  id is the package name (`@aivi/tracker-linear`), ruled 2026-09-30 for every
+ *  plugin, so a person writes the word they already typed into `aivi add` and
+ *  never opens a source file to learn what to call a plugin. What deliberately
+ *  keeps the shorter `linear` is everything naming the **platform** rather than
+ *  this package: the SQLite prefix and session-id prefix (renaming those would
+ *  orphan every conversation in an existing database for no gain), the webhook
+ *  URL Linear's dashboard holds, and the `aivi linear` command.
+ */
+export declare const MODULE_ID = "tracker-linear";
+export declare const linearSchema: z.ZodObject<{
+    agent: z.ZodOptional<z.ZodString>;
+    primary: z.ZodOptional<z.ZodString>;
+    apps: z.ZodRecord<z.ZodString, z.ZodObject<{}, z.core.$strict>>;
+    logMisroutes: z.ZodDefault<z.ZodBoolean>;
+    humanLabel: z.ZodDefault<z.ZodString>;
+    pool: z.ZodDefault<z.ZodString>;
+    mcp: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodLiteral<false>]>>;
+    progress: z.ZodDefault<z.ZodEnum<{
+        silent: "silent";
+        status: "status";
+        tools: "tools";
+    }>>;
+}, z.core.$strict>;
+export type LinearConfig = z.infer<typeof linearSchema>;
+/** The environment names of the one app: the primary's credentials, no app segment. */
+export declare const linearPrimarySecretNames: {
+    readonly clientId: 'LINEAR_CLIENT_ID';
+    readonly clientSecret: 'LINEAR_CLIENT_SECRET';
+    readonly webhookSecret: 'LINEAR_WEBHOOK_SECRET';
+};
+/**
+ * Environment variable names for one app's credentials. The **primary** app
+ * uses the bare `linearPrimarySecretNames`; this prefixed convention is for
+ * every other app (a face) — `<APP>` = the id upper-cased, `-` → `_`.
+ */
+export declare const linearSecretNames: (app: string) => {
+    clientId: string;
+    clientSecret: string;
+    webhookSecret: string;
+};
+/** The app that carries the workspace data feed and the bare secrets: `linear.primary`, else the one configured app. */
+export declare function primaryLinearApp(linear: LinearConfig | undefined): string | undefined;
+/** The assistant's agent name: `linear.agent`, else the one assistant everyone gets. */
+export declare function assistantAgent(linear: LinearConfig | undefined): string;
+/** The plugin's own `linear` section of a project entry (`projects.<id>.linear`),
+ *  contributed to the composed schema the way the `plugins` block contributes
+ *  its own. Core reads none of it. */
+export declare const linearProjectSchema: z.ZodObject<{
+    workspaceId: z.ZodOptional<z.ZodString>;
+    teams: z.ZodArray<z.ZodString>;
+    createLane: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type LinearProjectEntry = z.infer<typeof linearProjectSchema>;
+/** The plugin's own section under `projectDefaults`. */
+export declare const linearProjectDefaultsSchema: z.ZodObject<{
+    workspaceId: z.ZodOptional<z.ZodString>;
+    createLane: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type LinearProjectDefaults = z.infer<typeof linearProjectDefaultsSchema>;
+/** The project's Linear routing as it takes effect: which teams speak for it
+ *  and in which workspace. The lanes are the project's own core fact, read
+ *  from `Project.lanes` — this type stopped carrying them on purpose. */
+export interface ProjectLinear {
+    workspaceId?: string;
+    teams: string[];
+    /** Where `aivi_ticket_create` lands a new ticket, as it takes effect: the
+     *  project's own `createLane`, else `projectDefaults`', else absent — and
+     *  absent means the project's first configured lane, read from the core
+     *  `Project`, not from this section. */
+    createLane?: string;
+}
+/** The registry entry: the block holds no paths (credentials live in the
+ *  environment, lanes name agents), so `home` finds nothing to resolve here;
+ *  the module code loads lazily. The `linear` sections of a project and of
+ *  `projectDefaults` are contributed here — core passes them through and this
+ *  plugin reads them back. */
+export declare const plugin: AiviPlugin<LinearConfig>;

package/dist/config.js

@@ -0,0 +1,171 @@
+/** The Linear plugin's registry declaration, at its `./config` subpath: the
+ *  module id, the block's own schema (with the cross-field rules that belong to
+ *  it), and the bridge to the module code. The CLI imports this for every
+ *  command, so nothing here pulls the Linear client. */
+import { PROJECT_ID } from '@aivi/core';
+import { z } from 'zod';
+const id = z.string().regex(PROJECT_ID);
+/**
+ * The Linear module. One app does the work: it carries the workspace's
+ * **Issues** data feed on its webhook route, receives every agent-session
+ * event, and its token authorises the Linear MCP. Extra apps are *faces* — a
+ * name and icon in Linear's UI, their own credentials (`LINEAR_<APP>_*`) and
+ * webhook route, no routing meaning. Lanes are core's
+ * own (`projects.<id>.lanes`, ordered); this block maps teams to the project. The block
+ * lives at `plugins.tracker-linear` in config.json — the module id is the
+ * package name, ruled 2026-09-30 — and the `aivi-plugins` list in
+ * app/package.json says whether the module runs.
+ */
+/** The module id, and with it the key of this plugin's block in `config.json`
+ *  (`plugins.tracker-linear`), its `/status` id and its log category: the module
+ *  id is the package name (`@aivi/tracker-linear`), ruled 2026-09-30 for every
+ *  plugin, so a person writes the word they already typed into `aivi add` and
+ *  never opens a source file to learn what to call a plugin. What deliberately
+ *  keeps the shorter `linear` is everything naming the **platform** rather than
+ *  this package: the SQLite prefix and session-id prefix (renaming those would
+ *  orphan every conversation in an existing database for no gain), the webhook
+ *  URL Linear's dashboard holds, and the `aivi linear` command.
+ */
+export const MODULE_ID = 'tracker-linear';
+export const linearSchema = z
+    .strictObject({
+    agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The OpenCode agent that answers people on Linear — comment mentions and delegations that no lane claims: the assistant. Default: the aivi name.'),
+    primary: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The app that carries the workspace data feed, signs the bare LINEAR_* secrets and authorises the Linear MCP; default the one app. Required once several apps are configured.'),
+    apps: z
+        .record(id, z
+        .strictObject({})
+        .describe('Empty today: credentials come from the environment; the id is the app identity and its webhook route.'))
+        .describe('Linear apps by id. The primary (see `primary`) carries the data feed; every other app is a face — a name and icon in Linear’s UI with its own credentials, no routing meaning.'),
+    logMisroutes: z
+        .boolean()
+        .default(true)
+        .describe('Log at warn a webhook delivered to the wrong endpoint (a data change on a face’s route); it is dropped either way.'),
+    humanLabel: z
+        .string()
+        .min(1)
+        .default('needs-human')
+        .describe('Issues carrying this label are never worked automatically; a hand delegation is refused with an explanation.'),
+    pool: id.default('default').describe('Dispatcher pool a worker turn takes a slot in.'),
+    mcp: z
+        .union([
+        z.strictObject({
+            port: z.number().int().min(0).max(65535).default(4101),
+        }),
+        z.literal(false),
+    ])
+        .default({ port: 4101 })
+        .describe("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; OpenCode connects as a remote MCP at http://127.0.0.1:<port>/mcp. `false` disables it. Loopback only."),
+    progress: z
+        .enum(['silent', 'status', 'tools'])
+        .default('tools')
+        .describe('What the ephemeral activities in the agent session show while a worker runs.'),
+})
+    .superRefine((config, ctx) => {
+    // Several apps need a named primary, and the primary must be one of the configured apps.
+    const appIds = Object.keys(config.apps);
+    if (appIds.length > 1 && !config.primary)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['primary'],
+            message: 'Required once several apps are configured: which app carries the data feed and the bare LINEAR_* secrets',
+        });
+    if (config.primary && !appIds.includes(config.primary))
+        ctx.addIssue({ code: 'custom', path: ['primary'], message: 'Not a configured app' });
+});
+/** The environment names of the one app: the primary's credentials, no app segment. */
+export const linearPrimarySecretNames = {
+    clientId: 'LINEAR_CLIENT_ID',
+    clientSecret: 'LINEAR_CLIENT_SECRET',
+    webhookSecret: 'LINEAR_WEBHOOK_SECRET',
+};
+/**
+ * Environment variable names for one app's credentials. The **primary** app
+ * uses the bare `linearPrimarySecretNames`; this prefixed convention is for
+ * every other app (a face) — `<APP>` = the id upper-cased, `-` → `_`.
+ */
+export const linearSecretNames = (app) => {
+    const key = app.toUpperCase().replaceAll('-', '_');
+    return {
+        clientId: `LINEAR_${key}_CLIENT_ID`,
+        clientSecret: `LINEAR_${key}_CLIENT_SECRET`,
+        webhookSecret: `LINEAR_${key}_WEBHOOK_SECRET`,
+    };
+};
+/** The app that carries the workspace data feed and the bare secrets: `linear.primary`, else the one configured app. */
+export function primaryLinearApp(linear) {
+    if (!linear)
+        return undefined;
+    if (linear.primary)
+        return linear.primary;
+    const ids = Object.keys(linear.apps);
+    return ids.length === 1 ? ids[0] : undefined;
+}
+/** The assistant's agent name: `linear.agent`, else the one assistant everyone gets. */
+export function assistantAgent(linear) {
+    return linear?.agent ?? 'assistant';
+}
+/*
+ * Lanes used to live here, in Linear's own section. They do not anymore
+ * (ruled 2026-10-01): **lanes are core's concept** — the ordered workflow of
+ * a project, configured at `projects.<id>.lanes` and read by the host
+ * orchestrator, which decides every move from the order and asks a tracker
+ * only to perform one. What remains in this section is Linear's own routing:
+ * which teams feed the project, and which workspace.
+ */
+/** The plugin's own `linear` section of a project entry (`projects.<id>.linear`),
+ *  contributed to the composed schema the way the `plugins` block contributes
+ *  its own. Core reads none of it. */
+export const linearProjectSchema = z.strictObject({
+    workspaceId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Linear organization id; only needed with more than one workspace.'),
+    teams: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Linear team ids whose issues belong to this project; a team maps to at most one project.'),
+    createLane: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Where `aivi_ticket_create` lands a new ticket in this project — a lane name from the team’s states. Default: the project’s first configured lane; with none matching, Linear’s own default state.'),
+});
+/** The plugin's own section under `projectDefaults`. */
+export const linearProjectDefaultsSchema = z.strictObject({
+    workspaceId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Linear organization id every project gets unless it names its own.'),
+    createLane: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Where `aivi_ticket_create` lands a new ticket in every project unless it names its own — a lane name from the team’s states.'),
+});
+/** The registry entry: the block holds no paths (credentials live in the
+ *  environment, lanes name agents), so `home` finds nothing to resolve here;
+ *  the module code loads lazily. The `linear` sections of a project and of
+ *  `projectDefaults` are contributed here — core passes them through and this
+ *  plugin reads them back. */
+export const plugin = {
+    id: MODULE_ID,
+    configSchema: linearSchema,
+    projectSchema: linearProjectSchema,
+    projectDefaultsSchema: linearProjectDefaultsSchema,
+    // The lazy load is the design: the CLI reads this file's schema without
+    // pulling the host's world in, and the module arrives only when the host
+    // actually builds. The cycle back into this file (the module imports its
+    // own schema) is that design, not a tangle.
+    // fallow-ignore-next-line circular-dependency
+    createModule: config => import('./module.js').then(m => m.createLinearModule(config)),
+};

package/dist/desk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Linear's answer to the ticket desk (the `TicketDesk` contract at
+ * `@aivi/plugin/tracker`). The host owns the `aivi_ticket_*` tools and the
+ * ground truth of the call — this file answers what each one *is* on Linear:
+ * which app's feed a plain comment lands on, which team a new ticket is born
+ * in, what the team's label catalogue means. The desk speaks through the
+ * **primary** app: it holds the credentials, and a comment posted there is
+ * the app's own.
+ */
+import type { LoadedConfig } from '@aivi/core';
+import type { Platform, TicketDesk } from '@aivi/plugin/tracker';
+import type { LinearConfig } from './config.ts';
+export declare function createLinearDesk(loaded: LoadedConfig, config: LinearConfig, platform: Platform): TicketDesk;