pi-mono-linear 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# pi-mono-linear
+
+## 0.1.1
+
+### Patch Changes
+
+### Enhanced: auth setup
+
+- Added `/linear-auth` command and `linear_configure_auth` tool for masked local API-key capture.
+- Linear tools now prompt for a fresh key and retry once when auth is missing, invalid, or expired.
+- Key setup writes to `~/.pi/agent/auth.json` without returning the key to the model.
+
+## 0.1.0
+
+### Minor Changes
+
+### New Extension: linear
+
+- Added native Linear GraphQL tools for workspace metadata, teams, issues, projects, workflow states, labels, users, comments, cycles, and documents.
+- Added mutation tools for creating issues, updating issues, and creating comments.
+- Added bundled `linear` skill that explains when and how to use the native `linear_*` tools.
+- Added authentication support via `LINEAR_API_KEY` and `~/.pi/agent/auth.json` at `.linear.key`.
+- Added README documentation for API key creation, required Linear read/write permissions, and setup/troubleshooting.

package/LICENCE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Emanuel Casco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# pi-mono-linear
+
+A pi extension and skill package that exposes native Linear GraphQL tools for issue, project, team, user, comment, cycle, label, workflow-state, and document workflows.
+
+## Tools
+
+### Workspace and users
+
+- `linear_whoami`
+- `linear_workspace_metadata`
+- `linear_list_teams`
+- `linear_get_team`
+- `linear_list_users`
+- `linear_get_user`
+
+### Issues
+
+- `linear_list_issues`
+- `linear_get_issue`
+- `linear_search_issues`
+- `linear_list_my_issues`
+- `linear_create_issue`
+- `linear_update_issue`
+
+### Metadata and related records
+
+- `linear_list_projects`
+- `linear_get_project`
+- `linear_list_issue_statuses`
+- `linear_get_issue_status`
+- `linear_list_labels`
+- `linear_list_cycles`
+- `linear_list_documents`
+- `linear_get_document`
+
+### Comments
+
+- `linear_list_comments`
+- `linear_create_comment`
+- `linear_configure_auth`
+
+The package also bundles the `linear` skill under `skills/linear/SKILL.md`.
+
+## Authentication
+
+The extension looks for a Linear API key in this order:
+
+1. in-memory key override created by `/linear-auth --force` or `linear_configure_auth`
+2. `LINEAR_API_KEY` environment variable
+3. `~/.pi/agent/auth.json` at `.linear.key`
+
+If no key is found, or if Linear rejects the key as invalid/expired, the native tools can prompt you with a masked local dialog and store the replacement key without returning it to the model.
+
+Do **not** paste API keys into an LLM chat.
+
+### Recommended: native auth command
+
+Run this in pi:
+
+```text
+/linear-auth --force
+```
+
+The command shows the Linear API-key URL and required permissions, prompts for the key with masked input, and writes it to `~/.pi/agent/auth.json` at `.linear.key`.
+
+The same flow is available to the agent through the `linear_configure_auth` tool. That tool returns only metadata such as `stored: true`; it never returns the key.
+
+If a normal `linear_*` request fails because the key is missing, invalid, or expired, the extension retries once after prompting you for a fresh key.
+
+### Option A: environment variable
+
+For the current shell session:
+
+```bash
+export LINEAR_API_KEY="lin_api_xxx"
+```
+
+To persist it, add that export to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or your preferred secrets manager.
+
+### Option B: pi auth file
+
+Create or update `~/.pi/agent/auth.json`:
+
+```json
+{
+  "linear": {
+    "key": "lin_api_xxx"
+  }
+}
+```
+
+Recommended file permissions:
+
+```bash
+mkdir -p ~/.pi/agent
+chmod 700 ~/.pi/agent
+chmod 600 ~/.pi/agent/auth.json
+```
+
+If the file already contains other credentials, merge the `linear.key` entry instead of overwriting the file.
+
+## Creating a Linear API key
+
+1. Open Linear.
+2. Go to **Settings → Account → Security & Access**.
+3. Under **Personal API keys**, click **Create key**.
+4. Name it something recognizable, for example `pi-agent`.
+5. Choose the minimum access level needed for your workflow.
+6. If your workspace supports team restrictions, restrict the key to only the teams pi needs.
+7. Copy the key once and store it via `LINEAR_API_KEY` or `~/.pi/agent/auth.json`.
+
+## Required scopes / permissions
+
+Use the least privilege that supports the tools you need:
+
+- **Read** is enough for read-only tools such as `linear_workspace_metadata`, `linear_search_issues`, `linear_get_issue`, list tools, and document/comment reads.
+- **Write** is required for mutation tools: `linear_create_issue`, `linear_update_issue`, and `linear_create_comment`.
+- **Admin** is not required for this extension's tools.
+
+If you restrict the key to specific teams, the key must include the teams/projects/issues you want to query or mutate.
+
+Linear API keys are sent in the `Authorization` header as the raw key value; do not prefix them with `Bearer`.
+
+## Usage tips
+
+- Use `linear_workspace_metadata` first when team/project/state/label/user IDs are unknown.
+- Use `linear_search_issues` for keyword lookup.
+- Use `linear_get_issue` before updating an issue or creating a comment.
+- Use `linear_list_issues` for filtered issue lists by team, assignee, status, and limit.
+
+## Troubleshooting
+
+### Missing auth key
+
+Set `LINEAR_API_KEY` or add `.linear.key` to `~/.pi/agent/auth.json`.
+
+### Permission errors
+
+Confirm the key has the right access level:
+
+- Read-only workflows need **Read**.
+- Create/update/comment workflows need **Write**.
+- Team-restricted keys must include the relevant team.
+
+### Custom Linear endpoint
+
+By default, the extension uses `https://api.linear.app/graphql`. Override it with:
+
+```bash
+export LINEAR_GRAPHQL_URL="https://api.linear.app/graphql"
+```

package/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerLinearTools } from "./src/linear-tools.js";
+
+export default function linearExtension(pi: ExtensionAPI): void {
+	registerLinearTools(pi);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pi-mono-linear",
+  "version": "0.1.1",
+  "description": "Pi extension and skill for Linear GraphQL tools",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-skill",
+    "linear"
+  ],
+  "dependencies": {
+    "pi-common": "0.1.1"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/linear/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: linear
+description: Access Linear project management data using native pi tools — issues, projects, teams, users, comments, cycles, labels, workflow states, and documents. Requires a Linear personal API key.
+---
+
+# Linear Integration
+
+Use the native `linear_*` tools to read and write Linear data through the Linear GraphQL API.
+
+## Critical Rules
+
+- Never ask the user to paste a Linear API key in chat.
+- Never expose the API key inline in shell commands.
+- Before updating an issue or commenting, use `linear_get_issue` to verify the target.
+- When IDs are unknown, use `linear_workspace_metadata` first.
+
+## Authentication
+
+The tools read the key from an in-memory override, `LINEAR_API_KEY`, or `~/.pi/agent/auth.json` at `.linear.key`.
+
+If auth is missing, invalid, or expired, do **not** ask the user to paste the key in chat. Use the native `linear_configure_auth` tool or ask the user to run `/linear-auth --force`. The prompt is masked and the key is stored by the extension without returning it to the model.
+
+## Tool Workflow
+
+- Use `linear_configure_auth` only when auth is missing, invalid, expired, or the user asks to update the key.
+- Use `linear_workspace_metadata` first when team/project/state/label/user IDs are unknown.
+- Use `linear_search_issues` for keyword lookup.
+- Use `linear_get_issue` before updating or commenting.
+- Use `linear_list_issues` for filtered issue lists by team, assignee, status, or limit.
+- Use `linear_create_issue` to create issues once the team ID is known.
+- Use `linear_update_issue` to change title, description, priority, state, or assignee.
+- Use `linear_create_comment` to add Markdown context to an issue.
+
+## Available Tool Groups
+
+### Workspace and users
+
+- `linear_whoami`
+- `linear_workspace_metadata`
+- `linear_list_teams`
+- `linear_get_team`
+- `linear_list_users`
+- `linear_get_user`
+
+### Issues
+
+- `linear_list_issues`
+- `linear_search_issues`
+- `linear_get_issue`
+- `linear_list_my_issues`
+- `linear_create_issue`
+- `linear_update_issue`
+
+### Projects, states, labels, cycles, documents
+
+- `linear_list_projects`
+- `linear_get_project`
+- `linear_list_issue_statuses`
+- `linear_get_issue_status`
+- `linear_list_labels`
+- `linear_list_cycles`
+- `linear_list_documents`
+- `linear_get_document`
+
+### Comments
+
+- `linear_list_comments`
+- `linear_create_comment`
+- `linear_configure_auth`
+
+## Priority Values
+
+| Value | Label       |
+| ----- | ----------- |
+| 0     | No priority |
+| 1     | Urgent      |
+| 2     | High        |
+| 3     | Medium      |
+| 4     | Low         |
+
+## Issue Status Types
+
+| Type        | Meaning                     |
+| ----------- | --------------------------- |
+| `backlog`   | Not yet started, in backlog |
+| `triage`    | Needs triage                |
+| `unstarted` | Not yet started             |
+| `started`   | In progress                 |
+| `completed` | Done                        |
+| `canceled`  | Won't do                    |

package/src/linear-client.ts

@@ -0,0 +1,190 @@
+import { readAuthToken } from "pi-common/auth";
+import { createTtlCache } from "pi-common/cache";
+import { ApiError } from "pi-common/errors";
+import { createHttpClient, type HttpClient } from "pi-common/http-client";
+import { createRateLimiter, type RateLimiter } from "pi-common/rate-limiter";
+import * as queries from "./linear-queries.js";
+
+export interface LinearClientOptions {
+	endpoint?: string;
+	timeoutMs?: number;
+}
+
+export interface ListIssuesOptions {
+	teamId?: string;
+	assigneeId?: string;
+	statusName?: string;
+	limit?: number;
+}
+
+export interface CreateIssueInput {
+	teamId: string;
+	title: string;
+	description?: string;
+	priority?: number;
+	assigneeId?: string;
+	labelIds?: string[];
+	projectId?: string;
+	stateId?: string;
+}
+
+export interface UpdateIssueInput {
+	title?: string;
+	description?: string;
+	priority?: number;
+	stateId?: string;
+	assigneeId?: string;
+}
+
+type Variables = Record<string, unknown>;
+
+interface GraphQlResponse<T> {
+	data?: T;
+	errors?: Array<{ message?: string; extensions?: unknown }>;
+}
+
+const cache = createTtlCache<unknown>({ defaultTtlMs: 60_000, maxEntries: 100 });
+
+export class LinearClient {
+	private readonly http: HttpClient;
+	private readonly limiter: RateLimiter;
+
+	constructor(options: LinearClientOptions = {}) {
+		this.http = createHttpClient({
+			baseUrl: options.endpoint ?? process.env.LINEAR_GRAPHQL_URL ?? "https://api.linear.app/graphql",
+			timeoutMs: options.timeoutMs ?? 30_000,
+			service: "Linear",
+			headers: async () => ({ Authorization: await readLinearToken(), "Content-Type": "application/json" }),
+		});
+		this.limiter = createRateLimiter({ minIntervalMs: 250 });
+	}
+
+	whoami(): Promise<unknown> {
+		return this.cached("whoami", () => this.graphql(queries.WHOAMI));
+	}
+
+	workspaceMetadata(): Promise<unknown> {
+		return this.cached("workspaceMetadata", () => this.graphql(queries.WORKSPACE_METADATA));
+	}
+
+	listTeams(): Promise<unknown> {
+		return this.cached("teams", () => this.graphql(queries.LIST_TEAMS));
+	}
+
+	getTeam(teamId: string): Promise<unknown> {
+		return this.cached(`team:${teamId}`, () => this.graphql(queries.GET_TEAM, { id: teamId }));
+	}
+
+	listIssues(options: ListIssuesOptions): Promise<unknown> {
+		const variables = { filter: buildIssueFilter(options), first: options.limit ?? 50 };
+		return this.cached(`issues:${JSON.stringify(variables)}`, () => this.graphql(queries.LIST_ISSUES, variables));
+	}
+
+	getIssue(issueId: string): Promise<unknown> {
+		return this.cached(`issue:${issueId}`, () => this.graphql(queries.GET_ISSUE, { id: issueId }));
+	}
+
+	searchIssues(query: string, limit = 20): Promise<unknown> {
+		return this.cached(`search:${query}:${limit}`, () => this.graphql(queries.SEARCH_ISSUES, { term: query, first: limit }));
+	}
+
+	listMyIssues(limit = 50): Promise<unknown> {
+		return this.cached(`myIssues:${limit}`, () => this.graphql(queries.LIST_MY_ISSUES, { first: limit }));
+	}
+
+	createIssue(input: CreateIssueInput): Promise<unknown> {
+		return this.graphql(queries.CREATE_ISSUE, { input: compact(input) });
+	}
+
+	updateIssue(issueId: string, input: UpdateIssueInput): Promise<unknown> {
+		return this.graphql(queries.UPDATE_ISSUE, { id: issueId, input: compact(input) });
+	}
+
+	listProjects(teamId?: string): Promise<unknown> {
+		return teamId
+			? this.cached(`teamProjects:${teamId}`, () => this.graphql(queries.LIST_TEAM_PROJECTS, { id: teamId }))
+			: this.cached("projects", () => this.graphql(queries.LIST_PROJECTS));
+	}
+
+	getProject(projectId: string): Promise<unknown> {
+		return this.cached(`project:${projectId}`, () => this.graphql(queries.GET_PROJECT, { id: projectId }));
+	}
+
+	listIssueStatuses(teamId?: string): Promise<unknown> {
+		return teamId
+			? this.cached(`teamStatuses:${teamId}`, () => this.graphql(queries.LIST_TEAM_STATUSES, { id: teamId }))
+			: this.cached("statuses", () => this.graphql(queries.LIST_STATUSES));
+	}
+
+	getIssueStatus(stateId: string): Promise<unknown> {
+		return this.cached(`status:${stateId}`, () => this.graphql(queries.GET_STATUS, { id: stateId }));
+	}
+
+	listLabels(teamId?: string): Promise<unknown> {
+		return teamId
+			? this.cached(`teamLabels:${teamId}`, () => this.graphql(queries.LIST_TEAM_LABELS, { id: teamId }))
+			: this.cached("labels", () => this.graphql(queries.LIST_LABELS));
+	}
+
+	listUsers(): Promise<unknown> {
+		return this.cached("users", () => this.graphql(queries.LIST_USERS));
+	}
+
+	getUser(userId: string): Promise<unknown> {
+		return this.cached(`user:${userId}`, () => this.graphql(queries.GET_USER, { id: userId }));
+	}
+
+	listComments(issueId: string): Promise<unknown> {
+		return this.cached(`comments:${issueId}`, () => this.graphql(queries.LIST_COMMENTS, { id: issueId }));
+	}
+
+	createComment(issueId: string, body: string): Promise<unknown> {
+		return this.graphql(queries.CREATE_COMMENT, { input: { issueId, body } });
+	}
+
+	listCycles(teamId?: string): Promise<unknown> {
+		return teamId
+			? this.cached(`teamCycles:${teamId}`, () => this.graphql(queries.LIST_TEAM_CYCLES, { id: teamId }))
+			: this.cached("cycles", () => this.graphql(queries.LIST_CYCLES));
+	}
+
+	listDocuments(projectId?: string): Promise<unknown> {
+		return projectId
+			? this.cached(`projectDocuments:${projectId}`, () => this.graphql(queries.LIST_PROJECT_DOCUMENTS, { id: projectId }))
+			: this.cached("documents", () => this.graphql(queries.LIST_DOCUMENTS));
+	}
+
+	getDocument(documentId: string): Promise<unknown> {
+		return this.cached(`document:${documentId}`, () => this.graphql(queries.GET_DOCUMENT, { id: documentId }));
+	}
+
+	private async graphql<T = unknown>(query: string, variables: Variables = {}): Promise<T> {
+		return this.limiter.schedule(async () => {
+			const response = await this.http.post<GraphQlResponse<T>>("", { query, variables });
+			if (response.errors?.length) {
+				throw new ApiError(response.errors[0]?.message ?? "Linear GraphQL error", 200, response.errors, "Linear");
+			}
+			return response.data as T;
+		});
+	}
+
+	private cached<T>(key: string, load: () => Promise<T>): Promise<T> {
+		return cache.getOrSet(key, load) as Promise<T>;
+	}
+}
+
+export function readLinearToken(): Promise<string> {
+	return readAuthToken({ envName: "LINEAR_API_KEY", authPath: ["linear", "key"] });
+}
+
+function buildIssueFilter(options: ListIssuesOptions): Variables {
+	const filter: Variables = {};
+	if (options.teamId) filter.team = { id: { eq: options.teamId } };
+	if (options.assigneeId) filter.assignee = { id: { eq: options.assigneeId } };
+	if (options.statusName) filter.state = { name: { eqIgnoreCase: options.statusName } };
+	return filter;
+}
+
+function compact<T extends object>(input: T): Partial<T> {
+	return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== null && value !== "")) as Partial<T>;
+}

package/src/linear-queries.ts

@@ -0,0 +1,86 @@
+export const WHOAMI = `query { viewer { id name email displayName } }`;
+
+export const LIST_TEAMS = `query { teams { nodes { id name key description } } }`;
+
+export const GET_TEAM = `query($id: String!) { team(id: $id) { id name key description organization { id name } } }`;
+
+export const LIST_ISSUES = `query($filter: IssueFilter, $first: Int) {
+  issues(filter: $filter, first: $first, orderBy: updatedAt) {
+    nodes { id identifier title description priority url state { id name type } assignee { id name } team { id name key } labels { nodes { id name } } createdAt updatedAt }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+export const GET_ISSUE = `query($id: String!) {
+  issue(id: $id) {
+    id identifier title description priority url
+    state { id name type }
+    assignee { id name email }
+    team { id name key }
+    project { id name }
+    labels { nodes { id name } }
+    parent { id identifier title }
+    children { nodes { id identifier title } }
+    comments { nodes { id body user { id name } createdAt } }
+    createdAt updatedAt
+  }
+}`;
+
+export const SEARCH_ISSUES = `query($term: String!, $first: Int) {
+  searchIssues(term: $term, first: $first) {
+    nodes { id identifier title description priority url state { id name type } assignee { id name } team { id name key } labels { nodes { id name } } createdAt }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+export const LIST_MY_ISSUES = `query($first: Int) {
+  viewer {
+    id name
+    assignedIssues(first: $first, orderBy: updatedAt, filter: { state: { type: { neq: "completed" } } }) {
+      nodes { id identifier title priority url state { id name type } team { id name key } createdAt }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}`;
+
+export const CREATE_ISSUE = `mutation($input: IssueCreateInput!) {
+  issueCreate(input: $input) { success issue { id identifier title url priority state { id name } } }
+}`;
+
+export const UPDATE_ISSUE = `mutation($id: String!, $input: IssueUpdateInput!) {
+  issueUpdate(id: $id, input: $input) { success issue { id identifier title priority state { id name } } }
+}`;
+
+export const LIST_PROJECTS = `query { projects { nodes { id name description state team { id name key } } } }`;
+export const LIST_TEAM_PROJECTS = `query($id: String!) { team(id: $id) { id name projects { nodes { id name description state } } } }`;
+export const GET_PROJECT = `query($id: String!) { project(id: $id) { id name description state url team { id name key } lead { id name } } }`;
+
+export const LIST_STATUSES = `query { workflowStates { nodes { id name type color position team { id name key } } } }`;
+export const LIST_TEAM_STATUSES = `query($id: String!) { team(id: $id) { id name states { nodes { id name type color position } } } }`;
+export const GET_STATUS = `query($id: String!) { workflowState(id: $id) { id name type color position team { id name key } } }`;
+
+export const LIST_LABELS = `query { issueLabels { nodes { id name color team { id name key } } } }`;
+export const LIST_TEAM_LABELS = `query($id: String!) { team(id: $id) { id name labels { nodes { id name color } } } }`;
+
+export const LIST_USERS = `query { users { nodes { id name email displayName } } }`;
+export const GET_USER = `query($id: String!) { user(id: $id) { id name email displayName } }`;
+
+export const LIST_COMMENTS = `query($id: String!) { issue(id: $id) { id identifier comments { nodes { id body user { id name } createdAt } } } }`;
+export const CREATE_COMMENT = `mutation($input: CommentCreateInput!) {
+  commentCreate(input: $input) { success comment { id body user { id name } createdAt } }
+}`;
+
+export const LIST_CYCLES = `query { cycles(first: 50, orderBy: createdAt) { nodes { id name number startDate endDate completedAt team { id name key } } } }`;
+export const LIST_TEAM_CYCLES = `query($id: String!) { team(id: $id) { id name cycles { nodes { id name number startDate endDate completedAt } } } }`;
+
+export const LIST_DOCUMENTS = `query { documents(first: 50, orderBy: updatedAt) { nodes { id title updatedAt project { id name } } } }`;
+export const LIST_PROJECT_DOCUMENTS = `query($id: String!) { project(id: $id) { id name documents { nodes { id title updatedAt } } } }`;
+export const GET_DOCUMENT = `query($id: String!) { document(id: $id) { id title content contentIcon project { id name } updatedAt } }`;
+
+export const WORKSPACE_METADATA = `query {
+  teams { nodes { id name key } }
+  projects { nodes { id name description state team { id name } } }
+  workflowStates { nodes { id name type color position team { id name key } } }
+  issueLabels { nodes { id name color team { id name key } } }
+  users { nodes { id name email displayName } }
+}`;

package/src/linear-schemas.ts

@@ -0,0 +1,69 @@
+import { Type } from "@sinclair/typebox";
+
+export const MaxResponseCharsSchema = Type.Optional(
+	Type.Number({ description: "Maximum characters returned to the model before truncation", minimum: 1 }),
+);
+
+export const LimitSchema = Type.Optional(Type.Number({ description: "Maximum number of records to fetch", minimum: 1, maximum: 250 }));
+export const TeamIdSchema = Type.String({ description: "Linear team UUID or key where accepted by Linear" });
+export const IssueIdSchema = Type.String({ description: "Linear issue UUID or identifier such as ENG-123" });
+export const UserIdSchema = Type.String({ description: "Linear user UUID" });
+export const ProjectIdSchema = Type.String({ description: "Linear project UUID" });
+
+export const EmptyParams = Type.Object({ maxResponseChars: MaxResponseCharsSchema });
+export const OptionalTeamParams = Type.Object({ teamId: Type.Optional(TeamIdSchema), maxResponseChars: MaxResponseCharsSchema });
+export const IdParams = Type.Object({ id: Type.String({ description: "Linear object ID" }), maxResponseChars: MaxResponseCharsSchema });
+
+export const LinearGetTeamParams = Type.Object({ teamId: TeamIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetIssueParams = Type.Object({ issueId: IssueIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetProjectParams = Type.Object({ projectId: ProjectIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetUserParams = Type.Object({ userId: UserIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetDocumentParams = Type.Object({ documentId: Type.String({ description: "Linear document UUID" }), maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetStatusParams = Type.Object({ stateId: Type.String({ description: "Linear workflow state UUID" }), maxResponseChars: MaxResponseCharsSchema });
+
+export const LinearListIssuesParams = Type.Object({
+	teamId: Type.Optional(TeamIdSchema),
+	assigneeId: Type.Optional(UserIdSchema),
+	statusName: Type.Optional(Type.String({ description: "Workflow status name, case-insensitive" })),
+	limit: LimitSchema,
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const LinearSearchIssuesParams = Type.Object({
+	query: Type.String({ description: "Search term" }),
+	limit: LimitSchema,
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const LinearListMyIssuesParams = Type.Object({ limit: LimitSchema, maxResponseChars: MaxResponseCharsSchema });
+
+export const LinearCreateIssueParams = Type.Object({
+	teamId: TeamIdSchema,
+	title: Type.String({ description: "Issue title" }),
+	description: Type.Optional(Type.String({ description: "Issue description in Markdown" })),
+	priority: Type.Optional(Type.Number({ description: "0 No priority, 1 Urgent, 2 High, 3 Medium, 4 Low", minimum: 0, maximum: 4 })),
+	assigneeId: Type.Optional(UserIdSchema),
+	labelIds: Type.Optional(Type.Array(Type.String({ description: "Linear label UUID" }))),
+	projectId: Type.Optional(ProjectIdSchema),
+	stateId: Type.Optional(Type.String({ description: "Workflow state UUID" })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const LinearUpdateIssueParams = Type.Object({
+	issueId: IssueIdSchema,
+	title: Type.Optional(Type.String()),
+	description: Type.Optional(Type.String({ description: "Issue description in Markdown" })),
+	priority: Type.Optional(Type.Number({ description: "0 No priority, 1 Urgent, 2 High, 3 Medium, 4 Low", minimum: 0, maximum: 4 })),
+	stateId: Type.Optional(Type.String({ description: "Workflow state UUID" })),
+	assigneeId: Type.Optional(UserIdSchema),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const LinearCommentsParams = Type.Object({ issueId: IssueIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearCreateCommentParams = Type.Object({
+	issueId: IssueIdSchema,
+	body: Type.String({ description: "Comment body in Markdown" }),
+	maxResponseChars: MaxResponseCharsSchema,
+});
+
+export const LinearDocumentsParams = Type.Object({ projectId: Type.Optional(ProjectIdSchema), maxResponseChars: MaxResponseCharsSchema });

package/src/linear-tools.ts

@@ -0,0 +1,296 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { registerAuthConfigurator, runWithAuthRetry, type AuthConfiguratorOptions } from "pi-common/auth-config";
+import { jsonToolResult } from "pi-common/tool-result";
+import { LinearClient } from "./linear-client.js";
+import {
+	EmptyParams,
+	LinearCommentsParams,
+	LinearCreateCommentParams,
+	LinearCreateIssueParams,
+	LinearDocumentsParams,
+	LinearGetDocumentParams,
+	LinearGetIssueParams,
+	LinearGetProjectParams,
+	LinearGetStatusParams,
+	LinearGetTeamParams,
+	LinearGetUserParams,
+	LinearListIssuesParams,
+	LinearListMyIssuesParams,
+	LinearSearchIssuesParams,
+	LinearUpdateIssueParams,
+	OptionalTeamParams,
+} from "./linear-schemas.js";
+
+const LINEAR_AUTH: AuthConfiguratorOptions = {
+	service: "linear",
+	displayName: "Linear",
+	envName: "LINEAR_API_KEY",
+	authPath: ["linear", "key"],
+	commandName: "linear-auth",
+	toolName: "linear_configure_auth",
+	tokenUrl: "https://linear.app/settings/account/security",
+	scopeInstructions: [
+		"Read access is enough for lookup/list/get tools.",
+		"Write access is required for creating issues, updating issues, and creating comments.",
+		"Admin access is not required.",
+	],
+};
+
+function withLinearAuth<T>(ctx: ExtensionContext, operation: () => Promise<T>): Promise<T> {
+	return runWithAuthRetry(ctx, LINEAR_AUTH, operation);
+}
+
+export function registerLinearTools(pi: ExtensionAPI): void {
+	const client = new LinearClient();
+	registerAuthConfigurator(pi, LINEAR_AUTH);
+
+	pi.registerTool({
+		name: "linear_whoami",
+		label: "Linear Whoami",
+		description: "Get the authenticated Linear user.",
+		parameters: EmptyParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.whoami()), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_workspace_metadata",
+		label: "Linear Workspace Metadata",
+		description: "Get teams, projects, workflow states, labels, and users in one Linear call.",
+		promptSnippet: "Fetch Linear workspace teams, projects, states, labels, and users.",
+		promptGuidelines: [
+			"Use linear_configure_auth only when Linear auth is missing, invalid, expired, or the user asks to update the key; never ask the user to paste API keys in chat.",
+			"Use linear_workspace_metadata first when Linear team, project, state, label, or user IDs are unknown.",
+			"Use linear_search_issues for Linear keyword lookup.",
+			"Use linear_get_issue before updating or commenting on a Linear issue.",
+		],
+		parameters: EmptyParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.workspaceMetadata()), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_teams",
+		label: "Linear List Teams",
+		description: "List Linear teams.",
+		parameters: EmptyParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listTeams()), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_get_team",
+		label: "Linear Get Team",
+		description: "Get a Linear team by ID.",
+		parameters: LinearGetTeamParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.getTeam(params.teamId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_issues",
+		label: "Linear List Issues",
+		description: "List Linear issues with optional team, assignee, status, and limit filters.",
+		parameters: LinearListIssuesParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = await withLinearAuth(ctx, () => client.listIssues({
+				teamId: params.teamId,
+				assigneeId: params.assigneeId,
+				statusName: params.statusName,
+				limit: params.limit,
+			}));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_get_issue",
+		label: "Linear Get Issue",
+		description: "Get full Linear issue details by UUID or identifier like ENG-123.",
+		parameters: LinearGetIssueParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.getIssue(params.issueId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_search_issues",
+		label: "Linear Search Issues",
+		description: "Search Linear issues by keyword.",
+		parameters: LinearSearchIssuesParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.searchIssues(params.query, params.limit)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_my_issues",
+		label: "Linear My Issues",
+		description: "List open Linear issues assigned to the authenticated user.",
+		parameters: LinearListMyIssuesParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listMyIssues(params.limit)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_create_issue",
+		label: "Linear Create Issue",
+		description: "Create a Linear issue. Use linear_workspace_metadata first if team/state/user/project IDs are unknown.",
+		parameters: LinearCreateIssueParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = await withLinearAuth(ctx, () => client.createIssue({
+				teamId: params.teamId,
+				title: params.title,
+				description: params.description,
+				priority: params.priority,
+				assigneeId: params.assigneeId,
+				labelIds: params.labelIds,
+				projectId: params.projectId,
+				stateId: params.stateId,
+			}));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_update_issue",
+		label: "Linear Update Issue",
+		description: "Update a Linear issue title, description, priority, state, or assignee. Call linear_get_issue first.",
+		parameters: LinearUpdateIssueParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = await withLinearAuth(ctx, () => client.updateIssue(params.issueId, {
+				title: params.title,
+				description: params.description,
+				priority: params.priority,
+				stateId: params.stateId,
+				assigneeId: params.assigneeId,
+			}));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_projects",
+		label: "Linear List Projects",
+		description: "List Linear projects, optionally for a team.",
+		parameters: OptionalTeamParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listProjects(params.teamId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_get_project",
+		label: "Linear Get Project",
+		description: "Get a Linear project by ID.",
+		parameters: LinearGetProjectParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.getProject(params.projectId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_issue_statuses",
+		label: "Linear List Issue Statuses",
+		description: "List Linear workflow states, optionally for a team.",
+		parameters: OptionalTeamParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listIssueStatuses(params.teamId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_get_issue_status",
+		label: "Linear Get Issue Status",
+		description: "Get a Linear workflow state by ID.",
+		parameters: LinearGetStatusParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.getIssueStatus(params.stateId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_labels",
+		label: "Linear List Labels",
+		description: "List Linear labels, optionally for a team.",
+		parameters: OptionalTeamParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listLabels(params.teamId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_users",
+		label: "Linear List Users",
+		description: "List Linear users.",
+		parameters: EmptyParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listUsers()), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_get_user",
+		label: "Linear Get User",
+		description: "Get a Linear user by ID.",
+		parameters: LinearGetUserParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.getUser(params.userId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_comments",
+		label: "Linear List Comments",
+		description: "List comments for a Linear issue.",
+		parameters: LinearCommentsParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listComments(params.issueId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_create_comment",
+		label: "Linear Create Comment",
+		description: "Create a comment on a Linear issue. Call linear_get_issue first.",
+		parameters: LinearCreateCommentParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.createComment(params.issueId, params.body)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_cycles",
+		label: "Linear List Cycles",
+		description: "List Linear cycles, optionally for a team.",
+		parameters: OptionalTeamParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listCycles(params.teamId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_list_documents",
+		label: "Linear List Documents",
+		description: "List Linear documents, optionally for a project.",
+		parameters: LinearDocumentsParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.listDocuments(params.projectId)), { maxChars: params.maxResponseChars });
+		},
+	});
+
+	pi.registerTool({
+		name: "linear_get_document",
+		label: "Linear Get Document",
+		description: "Get a Linear document by ID.",
+		parameters: LinearGetDocumentParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return jsonToolResult(await withLinearAuth(ctx, () => client.getDocument(params.documentId)), { maxChars: params.maxResponseChars });
+		},
+	});
+}