@aivi/tracker-linear 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @aivi/tracker-linear
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Linear module: one app receiving every webhook, the assistant for people,
+workers in git worktrees, and the Linear MCP proxy. Agent sessions run on
+the host's channel machinery — a delegation becomes one bound conversation
+and one worker turn of the lane's agent in its own worktree.
+
+## Exports
+
+| Path | Contents |
+| --- | --- |
+| `@aivi/tracker-linear` | `createLinearModule`, `openLinearStore`, `describeWorkers`, `LINEAR` |
+| `./config` | the `plugin` declaration: module id, config schema, project sections |
+| `./setup` | `aivi add @aivi/tracker-linear`'s setup guide |
+| `./setupProject` | the `tracker`-role project contributor: writes a project's teams and lanes |
+| `./cli` | the `aivi linear` command |
+
+## Model
+
+- **One app, one persona, lanes pick agents.** The primary app carries the
+  workspace's data feed and every agent-session webhook on one route.
+- **A repository is a Linear team.** Routing reads the issue's team only;
+  lanes, branch names, and labels live per team.
+- **Two ids, on purpose.** The module id is this package's short name —
+  `tracker-linear` — and so `plugins.tracker-linear`, the `/status` id, the log
+  category and the project section's key. The *platform* id stays `linear`: the
+  SQLite prefix, the session and message id prefixes, the lease owner, the
+  webhook URL Linear's dashboard holds and the `aivi linear` command. Those say
+  who a conversation is on, not which package speaks for it, and renaming a
+  prefix would orphan every conversation already bound to it.
+- **Stop means stop.** The turn is discarded, capacity released, worktree
+  and session kept; only an unverifiable stop is `blocked`.
+
+## Dependencies
+
+`@aivi/host` as a peer (runs in-process with webhook routes on the same
+listener).
+
+## Docs
+
+[linear](../../docs/linear.md) ·
+[plan (what is left)](../../docs/plans/linear.md)

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/** The Linear module's operator commands, mounted into the server CLI through
+ *  the `./cli` subpath contract (@aivi/plugin's `(ctx) => Command`): status and
+ *  resolve, over the same conversation store the module runs on. */
+import type { PluginCliContext } from '@aivi/plugin';
+import { Command } from 'commander';
+export default _default;
+declare function _default(ctx: PluginCliContext): Command;

package/dist/cli.js

@@ -0,0 +1,34 @@
+import { resolveBlocked } from '@aivi/plugin';
+import { Command } from 'commander';
+const enabled = async (ctx) => {
+    const loaded = await ctx.loaded();
+    const config = loaded.config.plugins['tracker-linear'];
+    if (!config)
+        throw new Error('Linear is not configured in config.json (no plugins.tracker-linear block)');
+    return config;
+};
+export default (ctx) => {
+    const linear = new Command('linear').description('the Linear module');
+    linear
+        .command('status')
+        .description('Inspect Linear conversations (workers and the assistant)')
+        .action(async () => {
+        await enabled(ctx);
+        const { describeWorkers, openLinearStore } = await import('./index.js');
+        await ctx.withStore(store => {
+            const inbox = openLinearStore(store);
+            ctx.print({ conversations: describeWorkers(inbox) });
+        });
+    });
+    linear
+        .command('resolve <id>')
+        .description('Release a blocked worker')
+        .requiredOption('--reason <text>', 'what was found and done')
+        .requiredOption('--confirm-stopped', 'the external side has stopped')
+        .action(async (id, options) => {
+        await enabled(ctx);
+        const { openLinearStore } = await import('./index.js');
+        await resolveBlocked(ctx, id, options.reason, store => openLinearStore(store));
+    });
+    return linear;
+};

package/dist/client.d.ts

@@ -0,0 +1,277 @@
+import type { Logger } from '@aivi/core';
+/** What one Linear app needs to talk to the API: a client-credentials token, nothing persisted. */
+export interface LinearCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+export interface LinearClientOptions {
+    /** `https://api.linear.app` unless a test points elsewhere. */
+    baseUrl?: string | undefined;
+    /** Called with string URLs only; exactly what the setup context can give. */
+    fetch?: ((url: string, init?: RequestInit) => Promise<Response>) | undefined;
+    log?: Logger | undefined;
+    /** Scopes requested with the token; the agent scopes are what make the app delegable and mentionable. */
+    scope?: string | undefined;
+    /** Refresh this long before `expires_in` says the token is gone (default one hour). */
+    refreshSkewMs?: number | undefined;
+}
+/** One of the five activity types an app may emit; `prompt` is what people send and never ours. */
+export type AgentActivityContent = {
+    type: 'thought';
+    body: string;
+} | {
+    type: 'elicitation';
+    body: string;
+} | {
+    type: 'action';
+    action: string;
+    parameter: string;
+    result?: string;
+} | {
+    type: 'response';
+    body: string;
+} | {
+    type: 'error';
+    body: string;
+};
+export interface AgentActivityInput {
+    agentSessionId: string;
+    content: AgentActivityContent;
+    /** Shown until the next activity replaces it; only `thought` and `action` may be ephemeral. */
+    ephemeral?: boolean;
+    signal?: 'auth' | 'select';
+    signalMetadata?: Record<string, unknown>;
+}
+/** The issue fields eligibility and routing read. */
+export interface LinearIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description: string | null;
+    branchName: string;
+    url: string;
+    state: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    team: {
+        id: string;
+        key: string;
+    };
+    labels: {
+        id: string;
+        name: string;
+    }[];
+    delegate: {
+        id: string;
+    } | null;
+    assignee: {
+        id: string;
+        name: string;
+    } | null;
+    /** ISO instant the issue was archived — Linear's delete — null while it
+     *  lives. A dead ticket gets nothing from a session: there is no work. */
+    archivedAt: string | null;
+    /** Issues blocking this one; a blocker not in a finished state holds the listener back. */
+    blockedBy: {
+        id: string;
+        state: {
+            id: string;
+            name: string;
+            type: string;
+        };
+    }[];
+    /** Linear's rank — 1 Urgent through 4 Low, 0 for unranked: what sorts a
+     *  board top to bottom, unranked last. */
+    priority: number;
+    /** ISO instant of creation; the tie-break under priority, oldest first. */
+    createdAt: string;
+}
+export interface LinearAgentSession {
+    id: string;
+    status: string;
+    issue: {
+        id: string;
+    } | null;
+}
+/**
+ * What the delegate mutation answers: whether it worked, and the issue's
+ * agent sessions as Linear sees them in that very moment. Making the app
+ * the delegate creates the session itself, and it appears here — the
+ * listener starts the worker from this answer, not from a webhook.
+ */
+export interface DelegateAnswer {
+    success: boolean;
+    issue?: {
+        identifier: string;
+        agentSessions: {
+            nodes: {
+                id: string;
+                status: string;
+                startedAt: string | null;
+                url: string | null;
+            }[];
+        };
+    } | undefined;
+}
+/** A team in the workspace: the `id` is what aivi's config holds, the `key`
+ * is what Linear's URLs and issue identifiers show. States drive the lane
+ * picker; `type` completed or canceled lanes are never offered for work. */
+export interface LinearTeam {
+    id: string;
+    key: string;
+    name: string;
+    states: {
+        id: string;
+        name: string;
+        type: string;
+    }[];
+}
+export declare class LinearApiError extends Error {
+    readonly status: number;
+    /** 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. */
+    readonly codes: readonly string[];
+    constructor(message: string, status: number, codes?: readonly string[]);
+    /** 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: unknown): boolean;
+}
+export declare class LinearClient {
+    private readonly credentials;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly log;
+    private readonly scope;
+    private readonly skew;
+    private token;
+    private refreshing;
+    constructor(credentials: LinearCredentials, options?: LinearClientOptions);
+    /** A valid token, fetching or refreshing when needed; concurrent callers share one request. */
+    accessToken(force?: boolean): Promise<string>;
+    private fetchToken;
+    /** Run one GraphQL operation; a 401 refreshes the token and retries once. */
+    graphql<T>(query: string, variables?: Record<string, unknown>, retried?: boolean): Promise<T>;
+    /** The app user's own id and its workspace in one round; also proves the
+     *  credentials work. The tracker adapter learns `userId`/`orgId` here. */
+    viewer(): Promise<{
+        id: string;
+        organizationId: string;
+    }>;
+    /** The app user's own id in this workspace; also proves the credentials work. */
+    viewerId(): Promise<string>;
+    /** 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. */
+    listTeams(): Promise<LinearTeam[]>;
+    createActivity(input: AgentActivityInput): Promise<string>;
+    /** 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`.) */
+    transitionIssue(issueId: string, stateId: string): Promise<void>;
+    /** 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:)`.) */
+    labelIdForTeam(teamId: string, name: string): Promise<string>;
+    /** 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!)`.) */
+    addLabel(issueId: string, labelId: string): Promise<void>;
+    /** Take a label off an issue — the lift that lets the walk work a marked
+     *  ticket again. (schema: `issueRemoveLabel(id: String!, labelId: String!)`.) */
+    removeLabel(issueId: string, labelId: string): Promise<void>;
+    /** 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. */
+    createComment(issueId: string, body: string): Promise<void>;
+    /** 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. */
+    issueComments(issueId: string): Promise<{
+        author: string | null;
+        body: string;
+        at: string;
+    }[]>;
+    /** 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. */
+    issueUpdate(issueId: string, changes: {
+        title?: string;
+        description?: string;
+    }): Promise<LinearIssue>;
+    /** The team's label catalogue — the names a worker may add or remove. */
+    teamLabelNames(teamId: string): Promise<string[]>;
+    /** 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. */
+    closingNoteFacts(issueId: string): Promise<{
+        comments: {
+            body: string;
+        }[];
+        sessions: {
+            id: string;
+            url: string | null;
+        }[];
+    }>;
+    /** 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. */
+    agentSessionEnded(agentSessionId: string): Promise<boolean>;
+    /** 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}`. */
+    setPlan(agentSessionId: string, steps: {
+        content: string;
+        status: string;
+    }[]): Promise<void>;
+    /** 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. */
+    issuesIn(teamId: string, stateId: string): Promise<{
+        issues: LinearIssue[];
+        truncated: boolean;
+    }>;
+    issue(id: string): Promise<LinearIssue>;
+    /** 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). */
+    setDelegate(issueId: string, delegateId: string | null): Promise<DelegateAnswer>;
+    /** 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. */
+    createIssue(input: {
+        teamId: string;
+        title: string;
+        description?: string;
+        stateId?: string;
+    }): Promise<LinearIssue>;
+    /** Archive an issue — Linear's delete, off the board. The installer tidies
+     *  its own throwaway ticket with this. */
+    deleteIssue(issueId: string): Promise<void>;
+}
+/**
+ * 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 declare function resolveTeams(teams: LinearTeam[], tokens: string[]): string[];