@aivi/tracker-linear 0.0.0-stage → 1.0.0

package/dist/desk.js

@@ -0,0 +1,70 @@
+import { ToolError } from '@aivi/plugin';
+import { primaryLinearApp } from './config.js';
+import { projectLinear } from './projects.js';
+export function createLinearDesk(loaded, config, platform) {
+    const app = primaryLinearApp(config);
+    if (!app)
+        throw new ToolError(409, 'the tracker has no primary Linear app; the ticket desk is not available.');
+    const ticket = (run) => platform.issue(app, run.ticketId);
+    /** Where a new ticket is born: the project's teams, the create lane as it
+     *  takes effect (project's `createLane`, defaults', else the project's
+     *  first configured lane). An explicit create lane must exist in a team —
+     *  a wrong name is said, never guessed past; the fallback lane lands where
+     *  Linear's own default sends new issues when no team carries its name. */
+    const createTarget = async (projectId) => {
+        const linear = projectLinear(loaded, projectId);
+        if (!linear?.teams.length)
+            throw new ToolError(409, 'this project has no Linear teams; aivi_ticket_create has nowhere to create.');
+        const explicit = linear.createLane;
+        const lane = explicit ?? loaded.projects.find(p => p.id === projectId)?.lanes?.[0]?.name;
+        if (lane)
+            for (const teamId of linear.teams) {
+                const states = await platform.laneStates(app, teamId);
+                if (states.some(s => s.name === lane))
+                    return { teamId, lane };
+            }
+        if (explicit)
+            throw new ToolError(409, `createLane "${explicit}" names no state in this project's Linear teams — fix createLane in config.`);
+        return { teamId: linear.teams[0] };
+    };
+    return {
+        async read(run) {
+            const issue = await ticket(run);
+            return {
+                identifier: issue.identifier,
+                title: issue.title,
+                description: issue.description,
+                lane: issue.state.name,
+                labels: issue.labels.map(l => l.name),
+                url: issue.url,
+            };
+        },
+        comments(run) {
+            return platform.ticketComments(app, run.ticketId);
+        },
+        async labels(run) {
+            const issue = await ticket(run);
+            return { team: await platform.teamLabels(app, issue.teamId), on: issue.labels.map(l => l.name) };
+        },
+        async edit(run, changes) {
+            const issue = await platform.editIssue(app, run.ticketId, changes);
+            return { identifier: issue.identifier, title: issue.title, url: issue.url };
+        },
+        comment(run, text) {
+            return platform.addComment(app, run.ticketId, text);
+        },
+        async create(run, input) {
+            const target = await createTarget(run.projectId);
+            const issue = await platform.createIssue(app, {
+                teamId: target.teamId,
+                title: input.title,
+                description: input.description,
+                ...(target.lane ? { lane: target.lane } : {}),
+            });
+            return { identifier: issue.identifier, url: issue.url, lane: issue.state.name };
+        },
+        async label(run, label, on) {
+            await platform.apply(app, run.ticketId, { kind: 'label', label, on });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type { AgentActivityContent, AgentActivityInput, LinearAgentSession, LinearClientOptions, LinearCredentials, LinearIssue, LinearTeam, } from './client.ts';
+export { LinearApiError, LinearClient, resolveTeams } from './client.ts';
+export type { LinearConfig, LinearProjectDefaults, LinearProjectEntry, ProjectLinear, } from './config.ts';
+export { assistantAgent, linearPrimarySecretNames, linearProjectDefaultsSchema, linearProjectSchema, linearSchema, linearSecretNames, plugin, primaryLinearApp, } from './config.ts';
+export type { LinearMcpOptions } from './mcp.ts';
+export { LinearMcp } from './mcp.ts';
+export { createLinearModule, describeWorkers, LINEAR, openLinearStore } from './module.ts';
+export type { RoutedProject } from './projects.ts';
+export { linearTeamCollisions, projectForIssue, projectLinear, writeProjectLinear, } from './projects.ts';
+export type { WebhookApp } from './routes.ts';
+export { appWebhookPath, registerWebhookRoutes } from './routes.ts';
+export type { LinearAppRuntime } from './tracker.ts';
+export { clientFor, createLinearPlatform, LinearPlatform, neutralIssue, requireLinearSecrets } from './tracker.ts';
+export type { AgentSessionEventPayload, IssueEventPayload, LinearWebhook, OtherPayload, WebhookVerdict, } from './webhook.ts';
+export { isAgentSessionEvent, isIssueEvent, signWebhook, verifyWebhook, WEBHOOK_MAX_SKEW_MS } from './webhook.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { LinearApiError, LinearClient, resolveTeams } from './client.js';
+export { assistantAgent, linearPrimarySecretNames, linearProjectDefaultsSchema, linearProjectSchema, linearSchema, linearSecretNames, plugin, primaryLinearApp, } from './config.js';
+export { LinearMcp } from './mcp.js';
+export { createLinearModule, describeWorkers, LINEAR, openLinearStore } from './module.js';
+export { linearTeamCollisions, projectForIssue, projectLinear, writeProjectLinear, } from './projects.js';
+export { appWebhookPath, registerWebhookRoutes } from './routes.js';
+export { clientFor, createLinearPlatform, LinearPlatform, neutralIssue, requireLinearSecrets } from './tracker.js';
+export { isAgentSessionEvent, isIssueEvent, signWebhook, verifyWebhook, WEBHOOK_MAX_SKEW_MS } from './webhook.js';

package/dist/links.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Linear's own durable pair: the agent session ↔ the OpenCode session ↔ the
+ * ticket. The orchestrator does not know what an agent session is, so the
+ * follower keeps that join itself — it is the whole reason a webhook naming
+ * an agent session can find its worker's OpenCode session without asking
+ * anybody, and the list a boot pass reconciles against Linear.
+ *
+ * Its own namespace, its own table (the `Store.migrate` contract every module
+ * has: namespaced tables, never host tables).
+ */
+import type { Store } from '@aivi/plugin';
+export interface RunLink {
+    agentSession: string;
+    ticketId: string;
+    opencodeSession?: string;
+    /** When the closing landed — the pair is settled and boot asks Linear
+     *  about it no more. Absent means the closing is still owed. */
+    endedAt?: number;
+}
+export declare class RunLinks {
+    private readonly store;
+    constructor(store: Store);
+    /** The delegation happened: record the agent session and its ticket. The
+     *  OpenCode session joins when the orchestrator's `started` event names
+     *  this ticket's run. */
+    bind(agentSession: string, ticketId: string, now?: number): void;
+    /** The run's session exists: attach it to the newest unattached pair for
+     *  the ticket. Absent means the pair was already recorded (a replay). */
+    attach(ticketId: string, opencodeSession: string): boolean;
+    byAgentSession(agentSession: string): RunLink | undefined;
+    byOpencodeSession(opencodeSession: string): RunLink | undefined;
+    /** Every pair whose closing has not landed: the boot pass reads the run
+     *  state for each and catches Linear up wherever the run has ended. A
+     *  settled pair is absent — its closing spoke Linear's own state once, and
+     *  asking again forever was the bug (live, 2026-10-06). Follow-up routing
+     *  never comes through here: it asks `byAgentSession` directly, settled or
+     *  not. The lane move is not this list's business: it is the orchestrator's
+     *  own debt in its own ledger. */
+    owed(): RunLink[];
+    /** The closing landed: settle the pair. The row stays — it is still the
+     *  route a person's later message finds its run through. */
+    closingLanded(agentSession: string, now?: number): void;
+    /** Retire a pair for good. Its use today is the gone-closing: Linear
+     *  answers the agent session with `Entity not found` — the ticket was
+     *  deleted — so there is nothing left to pay and no reason for the next
+     *  boot to ask again. */
+    drop(agentSession: string): void;
+}

package/dist/links.js

@@ -0,0 +1,83 @@
+const map = (r) => ({
+    agentSession: String(r.agent_session),
+    ticketId: String(r.ticket_id),
+    ...(r.opencode_session === null ? {} : { opencodeSession: String(r.opencode_session) }),
+    ...(r.ended_at === null || r.ended_at === undefined ? {} : { endedAt: Number(r.ended_at) }),
+});
+const migrations = [
+    `CREATE TABLE tracker_linear_run_links(
+     agent_session TEXT PRIMARY KEY, ticket_id TEXT NOT NULL, opencode_session TEXT UNIQUE,
+     created_at INTEGER NOT NULL);
+   CREATE INDEX tracker_linear_run_links_ticket ON tracker_linear_run_links(ticket_id);`,
+    // The boot pass reads only the pairs whose closing has not landed, so the
+    // index is **partial**: it holds the owed rows and nothing else, and the
+    // settled history never weighs on a boot.
+    `ALTER TABLE tracker_linear_run_links ADD COLUMN ended_at INTEGER;
+   CREATE INDEX tracker_linear_run_links_owed ON tracker_linear_run_links(created_at) WHERE ended_at IS NULL;`,
+];
+export class RunLinks {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.migrate('tracker-linear', migrations);
+    }
+    /** The delegation happened: record the agent session and its ticket. The
+     *  OpenCode session joins when the orchestrator's `started` event names
+     *  this ticket's run. */
+    bind(agentSession, ticketId, now = Date.now()) {
+        this.store.db
+            .prepare(`INSERT INTO tracker_linear_run_links(agent_session, ticket_id, created_at) VALUES(?,?,?)
+         ON CONFLICT(agent_session) DO UPDATE SET ticket_id=excluded.ticket_id`)
+            .run(agentSession, ticketId, now);
+    }
+    /** The run's session exists: attach it to the newest unattached pair for
+     *  the ticket. Absent means the pair was already recorded (a replay). */
+    attach(ticketId, opencodeSession) {
+        const changed = this.store.db
+            .prepare(`UPDATE tracker_linear_run_links SET opencode_session=?
+         WHERE agent_session = (
+           SELECT agent_session FROM tracker_linear_run_links
+           WHERE ticket_id=? AND opencode_session IS NULL ORDER BY created_at DESC LIMIT 1)
+           AND opencode_session IS NULL`)
+            .run(opencodeSession, ticketId);
+        return changed.changes > 0;
+    }
+    byAgentSession(agentSession) {
+        const row = this.store.db
+            .prepare('SELECT * FROM tracker_linear_run_links WHERE agent_session=?')
+            .get(agentSession);
+        return row && map(row);
+    }
+    byOpencodeSession(opencodeSession) {
+        const row = this.store.db
+            .prepare('SELECT * FROM tracker_linear_run_links WHERE opencode_session=?')
+            .get(opencodeSession);
+        return row && map(row);
+    }
+    /** Every pair whose closing has not landed: the boot pass reads the run
+     *  state for each and catches Linear up wherever the run has ended. A
+     *  settled pair is absent — its closing spoke Linear's own state once, and
+     *  asking again forever was the bug (live, 2026-10-06). Follow-up routing
+     *  never comes through here: it asks `byAgentSession` directly, settled or
+     *  not. The lane move is not this list's business: it is the orchestrator's
+     *  own debt in its own ledger. */
+    owed() {
+        return this.store.db
+            .prepare('SELECT * FROM tracker_linear_run_links WHERE opencode_session IS NOT NULL AND ended_at IS NULL ORDER BY created_at')
+            .all().map(map);
+    }
+    /** The closing landed: settle the pair. The row stays — it is still the
+     *  route a person's later message finds its run through. */
+    closingLanded(agentSession, now = Date.now()) {
+        this.store.db
+            .prepare('UPDATE tracker_linear_run_links SET ended_at=? WHERE agent_session=?')
+            .run(now, agentSession);
+    }
+    /** Retire a pair for good. Its use today is the gone-closing: Linear
+     *  answers the agent session with `Entity not found` — the ticket was
+     *  deleted — so there is nothing left to pay and no reason for the next
+     *  boot to ask again. */
+    drop(agentSession) {
+        this.store.db.prepare('DELETE FROM tracker_linear_run_links WHERE agent_session=?').run(agentSession);
+    }
+}

package/dist/mcp.d.ts

@@ -0,0 +1,32 @@
+import type { Logger } from '@aivi/core';
+import type { LinearClient } from './client.ts';
+export interface LinearMcpOptions {
+    /** Loopback port to bind; `0` lets the OS pick one. */
+    port: number;
+    /** Upstream MCP endpoint; Linear's hosted server by default. */
+    upstream?: string;
+    log?: Logger;
+}
+/**
+ * The Linear MCP: a loopback-only HTTP server, hosted by the linear module
+ * itself, that bridges OpenCode's remote MCP connection to Linear's hosted
+ * MCP. It forwards every request verbatim, rewriting only the authorization
+ * header to the app-actor token minted by the module's own client — writes
+ * attribute to the app, never a human. The token is re-minted once on a 401
+ * (the app token lives 30 days with no refresh token; Linear's documented
+ * pattern). Loopback only: the MCP can write to Linear as the app, so it is
+ * never exposed beyond the machine.
+ */
+export declare class LinearMcp {
+    private readonly client;
+    private readonly port;
+    private readonly upstream;
+    private readonly log;
+    private server;
+    constructor(client: LinearClient, options: LinearMcpOptions);
+    /** Bind loopback; resolves with the actual port. */
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    private handle;
+    private forward;
+}

package/dist/mcp.js

@@ -0,0 +1,126 @@
+import { createServer, request as httpRequest, } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { getLogger } from '@aivi/core';
+import { MODULE_ID } from './config.js';
+const DEFAULT_UPSTREAM = 'https://mcp.linear.app/mcp';
+/** Hop-by-hop and endpoint-local headers that must not travel upstream. */
+const HOP_HEADERS = new Set(['host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade', 'proxy-connection']);
+/**
+ * The Linear MCP: a loopback-only HTTP server, hosted by the linear module
+ * itself, that bridges OpenCode's remote MCP connection to Linear's hosted
+ * MCP. It forwards every request verbatim, rewriting only the authorization
+ * header to the app-actor token minted by the module's own client — writes
+ * attribute to the app, never a human. The token is re-minted once on a 401
+ * (the app token lives 30 days with no refresh token; Linear's documented
+ * pattern). Loopback only: the MCP can write to Linear as the app, so it is
+ * never exposed beyond the machine.
+ */
+export class LinearMcp {
+    client;
+    port;
+    upstream;
+    log;
+    server = null;
+    constructor(client, options) {
+        this.client = client;
+        this.port = options.port;
+        this.upstream = new URL(options.upstream ?? DEFAULT_UPSTREAM);
+        this.log = options.log ?? getLogger(['aivi', MODULE_ID, 'mcp']);
+    }
+    /** Bind loopback; resolves with the actual port. */
+    start() {
+        return new Promise((resolve, reject) => {
+            const server = createServer((request, response) => {
+                this.handle(request, response).catch(error => {
+                    this.log.warn('linear.mcp.request_failed', { error });
+                    if (!response.headersSent)
+                        response.writeHead(502, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32603, message: 'Upstream unreachable' } }));
+                });
+            });
+            this.server = server;
+            server.on('error', reject);
+            server.listen(this.port, '127.0.0.1', () => resolve(server.address().port));
+        });
+    }
+    stop() {
+        const server = this.server;
+        this.server = null;
+        if (!server)
+            return Promise.resolve();
+        return new Promise(resolve => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        });
+    }
+    async handle(request, response) {
+        // The request body is an MCP message: small JSON, buffered so a 401 retry can replay it.
+        const body = await readBody(request);
+        if (!body) {
+            // Over the cap: said in the protocol's own shape, the way every
+            // other body reader in aivi refuses what is too big to hold.
+            response.writeHead(413, { 'content-type': 'application/json' });
+            response.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32001, message: 'Request body over the cap' } }));
+            return;
+        }
+        await this.forward(request, response, body, false);
+    }
+    async forward(request, response, body, retried) {
+        // `retried` re-mints: the cached token was just refused upstream.
+        const token = await this.client.accessToken(retried);
+        const headers = {};
+        for (const [name, value] of Object.entries(request.headers)) {
+            if (!HOP_HEADERS.has(name) && typeof value === 'string')
+                headers[name] = value;
+        }
+        headers.authorization = `Bearer ${token}`;
+        headers.host = this.upstream.host;
+        const incoming = new URL(request.url ?? '/', 'http://127.0.0.1');
+        await new Promise((resolve, reject) => {
+            const upstreamRequest = this.upstream.protocol === 'https:' ? httpsRequest : httpRequest;
+            const upstream = upstreamRequest({
+                hostname: this.upstream.hostname,
+                port: this.upstream.port,
+                path: `${this.upstream.pathname}${incoming.search}`,
+                method: request.method,
+                headers,
+            }, upstreamResponse => {
+                if (upstreamResponse.statusCode === 401 && !retried) {
+                    upstreamResponse.resume();
+                    this.forward(request, response, body, true).then(() => resolve(), reject);
+                    return;
+                }
+                response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+                upstreamResponse.pipe(response);
+                upstreamResponse.on('end', () => resolve());
+                upstreamResponse.on('error', reject);
+            });
+            upstream.on('error', reject);
+            if (body.length)
+                upstream.end(body);
+            else
+                upstream.end();
+        });
+    }
+}
+/** What one MCP message may weigh: every other body reader in aivi caps
+ *  (`readCapped`, `MAX_PUBLIC_BODY`, `MAX_DIARY_BODY`); loopback is the
+ *  threat model, so this is consistency, and the cap costs nothing. */
+const MAX_MCP_BODY = 1024 * 1024;
+/** The body, buffered whole — or `undefined` when it passes the cap and
+ *  the stream is dropped rather than accumulated without end. */
+const readBody = (request) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    request.on('data', chunk => {
+        bytes += chunk.length;
+        if (bytes > MAX_MCP_BODY) {
+            request.destroy();
+            resolve(undefined);
+            return;
+        }
+        chunks.push(chunk);
+    });
+    request.on('end', () => resolve(Buffer.concat(chunks)));
+    request.on('error', reject);
+});

package/dist/module.d.ts

@@ -0,0 +1,38 @@
+import { ConversationStore } from '@aivi/host';
+import type { AiviModule, AiviServices, Store } from '@aivi/plugin';
+import type { ChannelPlatform, Turn } from '@aivi/plugin/channel';
+import type { Platform } from '@aivi/plugin/tracker';
+import type { LinearConfig } from './config.ts';
+import type { LinearBoard } from './work.ts';
+/**
+ * The platform: an agent session is a conversation. Its id is `<app>:<agent session id>`
+ * so a turn always knows which app's token speaks for it, restarts included. Assistant
+ * turns have effects beyond their reply, so a restart mid-turn blocks instead of discarding.
+ */
+export declare const LINEAR: ChannelPlatform;
+export declare function openLinearStore(store: Store): ConversationStore;
+/** The `<issue>` block that accompanies every start when the event brought
+ *  no context of its own. */
+/** Where the module's tracker comes from: Linear's adapter by default, a
+ *  fake tracker in a test of the decisions below. */
+export type MakeTracker = (services: AiviServices) => Promise<Platform>;
+/**
+ * The module, built on a tracker. What lives here is routing and Linear's
+ * voice — the `Tracker` contract decides what a question and an outcome look
+ * like on Linear; the run itself — its record, session, tools and exits — is
+ * the host orchestrator's, and Linear is one follower among any number it
+ * will never know about.
+ */
+/** The board, pull-shaped, for the orchestrator's walk; a test hands its own
+ *  lanes the way it hands its own tracker. */
+export type MakeBoard = (services: AiviServices) => LinearBoard;
+export declare function createLinearModule(config: LinearConfig, makeTracker?: MakeTracker, makeBoard?: MakeBoard): AiviModule;
+/** For `aivi linear status`: what each assistant conversation is doing.
+ *  Workers live in the orchestrator's ledger now; their lines join this view
+ *  when the status command is formalized with the extraction. */
+export declare function describeWorkers(store: ConversationStore): {
+    conversation: string;
+    agent: string | null;
+    issue: string | null;
+    turn: Turn;
+}[];