@fink-andreas/pi-linear-tools 0.4.1 → 0.4.3

package/extensions/pi-linear-tools.js

@@ -1,6 +1,6 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
-import { createLinearClient, checkAndClearRateLimit, markRateLimited } from '../src/linear-client.js';
-import { setQuietMode } from '../src/logger.js';
+import { createLinearClient, checkAndClearRateLimit, markRateLimited, getClientRequestMetrics } from '../src/linear-client.js';
+import { setQuietMode, debug } from '../src/logger.js';
 import {
   resolveProjectRef,
   fetchTeams,
@@ -48,12 +48,25 @@ try {
 import {
   executeIssueList,
   executeIssueView,
+  executeIssueActivity,
   executeIssueCreate,
   executeIssueUpdate,
   executeIssueComment,
   executeIssueStart,
   executeIssueDelete,
   executeProjectList,
+  executeProjectView,
+  executeProjectCreate,
+  executeProjectUpdate,
+  executeProjectDelete,
+  executeProjectArchive,
+  executeProjectUnarchive,
+  executeProjectUpdateList,
+  executeProjectUpdateView,
+  executeProjectUpdateCreate,
+  executeProjectUpdateUpdate,
+  executeProjectUpdateArchive,
+  executeProjectUpdateUnarchive,
   executeTeamList,
   executeMilestoneList,
   executeMilestoneView,
@@ -65,6 +78,7 @@ import { authenticate, getAccessToken, logout } from '../src/auth/index.js';
 import { withMilestoneScopeHint } from '../src/error-hints.js';
 
 let cachedApiKey = null;
+const INCLUDE_USAGE_SUMMARY = String(process.env.PI_LINEAR_TOOLS_USAGE_SUMMARY || '').toLowerCase() === 'true';
 
 async function getLinearAuth() {
   const envKey = process.env.LINEAR_API_KEY;
@@ -106,6 +120,65 @@ async function createAuthenticatedClient() {
   return createLinearClient(await getLinearAuth());
 }
 
+async function withRequestUsageLogging(client, toolName, action, operation) {
+  const before = getClientRequestMetrics(client);
+
+  try {
+    const result = await operation();
+    const after = getClientRequestMetrics(client);
+
+    const usageDelta = {
+      tool: toolName,
+      action,
+      requestsDelta: after.total - before.total,
+      successDelta: after.success - before.success,
+      failedDelta: after.failed - before.failed,
+      rateLimitedDelta: after.rateLimited - before.rateLimited,
+      summary: `Linear API usage: ${after.total - before.total} req (${after.success - before.success} ok, ${after.failed - before.failed} failed, ${after.rateLimited - before.rateLimited} rate-limited)`,
+    };
+
+    debug('[pi-linear-tools] API usage per command', usageDelta);
+
+    if (!INCLUDE_USAGE_SUMMARY || !result || typeof result !== 'object') {
+      return result;
+    }
+
+    const details = (result.details && typeof result.details === 'object') ? result.details : {};
+    const content = Array.isArray(result.content)
+      ? result.content.map((item, idx) => {
+        if (idx !== 0 || item?.type !== 'text' || typeof item.text !== 'string') return item;
+        return {
+          ...item,
+          text: `${item.text}\n\n_${usageDelta.summary}_`,
+        };
+      })
+      : result.content;
+
+    return {
+      ...result,
+      content,
+      details: {
+        ...details,
+        apiUsage: usageDelta,
+      },
+    };
+  } catch (error) {
+    const after = getClientRequestMetrics(client);
+
+    debug('[pi-linear-tools] API usage per command (error)', {
+      tool: toolName,
+      action,
+      requestsDelta: after.total - before.total,
+      successDelta: after.success - before.success,
+      failedDelta: after.failed - before.failed,
+      rateLimitedDelta: after.rateLimited - before.rateLimited,
+      error: String(error?.message || error || 'unknown'),
+    });
+
+    throw error;
+  }
+}
+
 async function resolveDefaultTeam(projectId) {
   const settings = await loadSettings();
 
@@ -418,18 +491,19 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_issue',
     label: 'Linear Issue',
-    description: 'Interact with Linear issues. Actions: list, view, create, update, comment, start, delete',
+    description: 'Interact with Linear issues. Actions: list, view, activity, create, update, comment, start, delete',
+    promptSnippet: 'Interact with Linear issues (list, view, activity, create, update, comment, start, delete)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'view', 'create', 'update', 'comment', 'start', 'delete'],
+          enum: ['list', 'view', 'activity', 'create', 'update', 'comment', 'start', 'delete'],
           description: 'Action to perform on issue(s)',
         },
         issue: {
           type: 'string',
-          description: 'Issue key (ABC-123) or Linear issue ID (for view, update, comment, start, delete)',
+          description: 'Issue key (ABC-123) or Linear issue ID (for view, activity, update, comment, start, delete)',
         },
         project: {
           type: 'string',
@@ -449,8 +523,8 @@ async function registerLinearTools(pi) {
           description: 'Optional explicit assignee ID alias for update/create debugging/compatibility.',
         },
         limit: {
-          type: 'number',
-          description: 'Maximum number of issues to list (default: 50)',
+          type: 'integer',
+          description: 'Maximum number of issues or activity entries to list',
         },
         includeComments: {
           type: 'boolean',
@@ -465,9 +539,13 @@ async function registerLinearTools(pi) {
           description: 'Issue description in markdown (for create, update)',
         },
         priority: {
-          type: 'number',
+          type: 'integer',
           description: 'Priority 0..4 (for create, update)',
         },
+        includeArchived: {
+          type: 'boolean',
+          description: 'Include archived resources when listing activity or project updates',
+        },
         state: {
           type: 'string',
           description: 'Target state name or ID (for create, update)',
@@ -552,28 +630,32 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeIssueList(client, params);
-          case 'view':
-            return await executeIssueView(client, params);
-          case 'create':
-            return await executeIssueCreate(client, params, { resolveDefaultTeam });
-          case 'update':
-            return await executeIssueUpdate(client, params);
-          case 'comment':
-            return await executeIssueComment(client, params);
-          case 'start':
-            return await executeIssueStart(client, params, {
-              gitExecutor: async (branchName, fromRef, onBranchExists) => {
-                return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
-              },
-            });
-          case 'delete':
-            return await executeIssueDelete(client, params);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_issue', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeIssueList(client, params);
+            case 'view':
+              return await executeIssueView(client, params);
+            case 'activity':
+              return await executeIssueActivity(client, params);
+            case 'create':
+              return await executeIssueCreate(client, params, { resolveDefaultTeam });
+            case 'update':
+              return await executeIssueUpdate(client, params);
+            case 'comment':
+              return await executeIssueComment(client, params);
+            case 'start':
+              return await executeIssueStart(client, params, {
+                gitExecutor: async (branchName, fromRef, onBranchExists) => {
+                  return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
+                },
+              });
+            case 'delete':
+              return await executeIssueDelete(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors including SDK's RatelimitedLinearError
         const errorType = error?.type || '';
@@ -630,15 +712,59 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_project',
     label: 'Linear Project',
-    description: 'Interact with Linear projects. Actions: list',
+    description: 'Interact with Linear projects. Actions: list, view, create, update, delete, archive, unarchive',
+    promptSnippet: 'Interact with Linear projects (list, view, create, update, delete, archive, unarchive)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list'],
+          enum: ['list', 'view', 'create', 'update', 'delete', 'archive', 'unarchive'],
           description: 'Action to perform on project(s)',
         },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for view, update, delete)',
+        },
+        name: {
+          type: 'string',
+          description: 'Project name (required for create, optional for update)',
+        },
+        teams: {
+          type: 'string',
+          description: 'Comma-separated team keys or IDs (required for create, optional for update)',
+        },
+        description: {
+          type: 'string',
+          description: 'Project description in markdown',
+        },
+        lead: {
+          type: 'string',
+          description: 'Project lead user ID, "me", or "none" when updating',
+        },
+        priority: {
+          type: 'integer',
+          description: 'Priority 0-4',
+          minimum: 0,
+          maximum: 4,
+          multipleOf: 1,
+        },
+        color: {
+          type: 'string',
+          description: 'Project color (hex)',
+        },
+        icon: {
+          type: 'string',
+          description: 'Project icon',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Planned start date (YYYY-MM-DD)',
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Planned target date (YYYY-MM-DD)',
+        },
       },
       required: ['action'],
       additionalProperties: false,
@@ -648,12 +774,26 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeProjectList(client);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_project', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeProjectList(client);
+            case 'view':
+              return await executeProjectView(client, params);
+            case 'create':
+              return await executeProjectCreate(client, params);
+            case 'update':
+              return await executeProjectUpdate(client, params);
+            case 'delete':
+              return await executeProjectDelete(client, params);
+            case 'archive':
+              return await executeProjectArchive(client, params);
+            case 'unarchive':
+              return await executeProjectUnarchive(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors
         const errorType = error?.type || '';
@@ -675,10 +815,102 @@ async function registerLinearTools(pi) {
     },
   });
 
+  pi.registerTool({
+    name: 'linear_project_update',
+    label: 'Linear Project Update',
+    description: 'Interact with Linear project updates. Actions: list, view, create, update, archive, unarchive',
+    promptSnippet: 'Interact with Linear project updates (list, view, create, update, archive, unarchive)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'view', 'create', 'update', 'archive', 'unarchive'],
+          description: 'Action to perform on project update(s)',
+        },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for list, create)',
+        },
+        projectUpdate: {
+          type: 'string',
+          description: 'Project update ID (for view, update, archive, unarchive)',
+        },
+        body: {
+          type: 'string',
+          description: 'Project update body in markdown',
+        },
+        health: {
+          type: 'string',
+          description: 'Project update health: onTrack, atRisk, or offTrack',
+          enum: ['onTrack', 'atRisk', 'offTrack'],
+        },
+        isDiffHidden: {
+          type: 'boolean',
+          description: 'Whether to hide the diff on the update',
+        },
+        limit: {
+          type: 'integer',
+          description: 'Max updates to list',
+          minimum: 1,
+          multipleOf: 1,
+        },
+        includeArchived: {
+          type: 'boolean',
+          description: 'Whether archived updates should be included when listing',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    renderResult: renderMarkdownResult,
+    async execute(_toolCallId, params) {
+      try {
+        const client = await createAuthenticatedClient();
+
+        return await withRequestUsageLogging(client, 'linear_project_update', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeProjectUpdateList(client, params);
+            case 'view':
+              return await executeProjectUpdateView(client, params);
+            case 'create':
+              return await executeProjectUpdateCreate(client, params);
+            case 'update':
+              return await executeProjectUpdateUpdate(client, params);
+            case 'archive':
+              return await executeProjectUpdateArchive(client, params);
+            case 'unarchive':
+              return await executeProjectUpdateUnarchive(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
+      } catch (error) {
+        const errorType = error?.type || '';
+        const errorMessage = String(error?.message || error || 'Unknown error');
+
+        if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+          const resetAt = error?.requestsResetAt
+            ? new Date(error.requestsResetAt).toLocaleTimeString()
+            : 'approximately 1 hour from now';
+          throw new Error(`Linear API rate limit exceeded. Resets at: ${resetAt}. Please wait before retrying.`);
+        }
+
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
+
+        throw new Error(`Linear project update operation failed: ${errorMessage}`);
+      }
+    },
+  });
+
   pi.registerTool({
     name: 'linear_team',
     label: 'Linear Team',
     description: 'Interact with Linear teams. Actions: list',
+    promptSnippet: 'Interact with Linear teams (list)',
     parameters: {
       type: 'object',
       properties: {
@@ -696,12 +928,14 @@ async function registerLinearTools(pi) {
       try {
         const client = await createAuthenticatedClient();
 
-        switch (params.action) {
-          case 'list':
-            return await executeTeamList(client);
-          default:
-            throw new Error(`Unknown action: ${params.action}`);
-        }
+        return await withRequestUsageLogging(client, 'linear_team', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeTeamList(client);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
       } catch (error) {
         // Comprehensive error handling - catch ALL errors
         const errorType = error?.type || '';
@@ -728,6 +962,7 @@ async function registerLinearTools(pi) {
       name: 'linear_milestone',
       label: 'Linear Milestone',
       description: 'Interact with Linear project milestones. Actions: list, view, create, update, delete',
+      promptSnippet: 'Interact with Linear milestones (list, view, create, update, delete)',
       parameters: {
         type: 'object',
         properties: {
@@ -765,20 +1000,22 @@ async function registerLinearTools(pi) {
         try {
           const client = await createAuthenticatedClient();
 
-          switch (params.action) {
-            case 'list':
-              return await executeMilestoneList(client, params);
-            case 'view':
-              return await executeMilestoneView(client, params);
-            case 'create':
-              return await executeMilestoneCreate(client, params);
-            case 'update':
-              return await executeMilestoneUpdate(client, params);
-            case 'delete':
-              return await executeMilestoneDelete(client, params);
-            default:
-              throw new Error(`Unknown action: ${params.action}`);
-          }
+          return await withRequestUsageLogging(client, 'linear_milestone', params.action, async () => {
+            switch (params.action) {
+              case 'list':
+                return await executeMilestoneList(client, params);
+              case 'view':
+                return await executeMilestoneView(client, params);
+              case 'create':
+                return await executeMilestoneCreate(client, params);
+              case 'update':
+                return await executeMilestoneUpdate(client, params);
+              case 'delete':
+                return await executeMilestoneDelete(client, params);
+              default:
+                throw new Error(`Unknown action: ${params.action}`);
+            }
+          });
         } catch (error) {
           // Apply milestone-specific hint, then wrap with operation context
           const hintError = withMilestoneScopeHint(error);
@@ -915,8 +1152,9 @@ export default async function piLinearToolsExtension(pi) {
       const showMilestoneTool = await shouldExposeMilestoneTool();
       const toolLines = [
         'LLM-callable tools:',
-        '  linear_issue (list/view/create/update/comment/start/delete)',
-        '  linear_project (list)',
+        '  linear_issue (list/view/activity/create/update/comment/start/delete)',
+        '  linear_project (list/view/create/update/delete/archive/unarchive)',
+        '  linear_project_update (list/view/create/update/archive/unarchive)',
         '  linear_team (list)',
       ];