@weavetab/plugin-github 1.0.0 → 1.1.0

package/dist/index.js

@@ -1,95 +1,197 @@
 /**
  * @weavetab/plugin-github
- * Official Weavetab GitHub plugin — repository analysis, raw file reads, issue
- * search/inspection and pull request inspection over the GitHub REST API.
+ * Official Weavetab GitHub plugin — modular GitHub tools with zero-API options.
  *
- * All GitHub data is fetched over HTTP, so no browser turns are consumed and the
- * active tab is never navigated or mutated.
+ * All GitHub data is fetched over HTTP or directly via active tab DOM evaluation,
+ * so browser turns and rate-limited API quotas are minimized.
  *
  * Author: fy2ne
  * License: MIT
  */
 import { definePlugin, defineTool, z } from "@weavetab/sdk";
-import { runGithub } from "./github.js";
+import { githubAnalyze, githubRead, githubIssues, githubPullRequest, githubDiff, githubActiveTab, } from "./github.js";
 export * from "./types.js";
-export { runGithub } from "./github.js";
+export * from "./github.js";
 const DEFAULT_CACHE_TTL_MS = 30 * 60 * 1000;
 const DEFAULT_MAX_READ_LINES = 200;
 const DEFAULT_ISSUE_LIMIT = 5;
-const TOOL_DESCRIPTION = "Interact with GitHub repositories without burning browser turns. " +
-    "Analyze a repo's file tree and README, read raw source files, list/search/inspect issues, " +
-    "and examine pull request details, changed files and comments — all fetched over the GitHub REST API.";
-/** Coerce a possibly-string config value into a positive integer. */
 function positiveInt(value, fallback) {
     const n = typeof value === "string" ? parseInt(value, 10) : value;
     return typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
 }
+function buildRunContext(ctx, session) {
+    return {
+        session: session,
+        store: ctx.storage,
+        cacheTtlMs: positiveInt(ctx.config?.cacheTtlMs, DEFAULT_CACHE_TTL_MS),
+        maxReadLines: positiveInt(ctx.config?.maxReadLines, DEFAULT_MAX_READ_LINES),
+        defaultIssueLimit: positiveInt(ctx.config?.defaultIssueLimit, DEFAULT_ISSUE_LIMIT),
+        token: ctx.config?.token || process.env.GITHUB_TOKEN,
+    };
+}
 export const githubPlugin = definePlugin({
     name: "@weavetab/plugin-github",
-    version: "1.0.0",
-    description: "Official Weavetab GitHub plugin — analyze repositories, read raw source, inspect issues and pull requests over the GitHub API.",
+    version: "1.1.0",
+    description: "Official Weavetab GitHub plugin — modular repository analysis, raw source reads, issues, pull requests, raw diffs, and active-tab DOM inspection.",
     defaultConfig: {
         cacheTtlMs: DEFAULT_CACHE_TTL_MS,
         maxReadLines: DEFAULT_MAX_READ_LINES,
         defaultIssueLimit: DEFAULT_ISSUE_LIMIT,
     },
     async onLoad(ctx) {
-        const cacheTtlMs = positiveInt(ctx.config?.cacheTtlMs, DEFAULT_CACHE_TTL_MS);
-        const maxReadLines = positiveInt(ctx.config?.maxReadLines, DEFAULT_MAX_READ_LINES);
-        const defaultIssueLimit = positiveInt(ctx.config?.defaultIssueLimit, DEFAULT_ISSUE_LIMIT);
+        // 1. github_analyze
         ctx.mcp.registerTool(defineTool({
-            name: "github",
-            description: TOOL_DESCRIPTION,
+            name: "github_analyze",
+            description: "Analyze a GitHub repository's metadata, default branch, recursive file tree, and README snippet over the GitHub REST API without burning browser turns.",
             requiresSession: false,
             schema: {
-                action: z
-                    .enum(["analyze", "read", "issues", "pr"])
-                    .describe("The GitHub operation to perform. 'analyze' = repo metadata, file tree & README; 'read' = raw file contents (needs 'paths'); 'issues' = list/search/inspect issues; 'pr' = list/inspect pull requests."),
                 repo: z
                     .string()
                     .optional()
-                    .describe("Target repository as 'owner/repo' or a full github.com URL. Optional — when omitted, it is inferred from the active browser tab."),
+                    .describe("Target repository as 'owner/repo' or full github.com URL. When omitted, inferred from the active browser tab."),
+            },
+            handler: async (args, session) => {
+                const runCtx = buildRunContext(ctx, session);
+                const result = await githubAnalyze(runCtx, args.repo);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            },
+        }));
+        // 2. github_read
+        ctx.mcp.registerTool(defineTool({
+            name: "github_read",
+            description: "Fetch raw source files from a GitHub repository directly over HTTP without burning browser turns or API search quota.",
+            requiresSession: false,
+            schema: {
                 paths: z
                     .array(z.string())
                     .optional()
-                    .describe("READ: file paths relative to the repo root, e.g. ['src/index.ts', 'README.md']."),
+                    .describe("File paths relative to the repository root, e.g. ['src/index.ts', 'README.md']. When omitted, inferred from active tab if viewing a file blob."),
+                repo: z
+                    .string()
+                    .optional()
+                    .describe("Target repository as 'owner/repo' or full github.com URL. Optional — inferred from active tab if omitted."),
+                branch: z
+                    .string()
+                    .optional()
+                    .describe("Target branch or tag (defaults to 'main' or cached default branch). Avoids API discovery calls."),
                 line_range: z
                     .array(z.number())
                     .length(2)
                     .optional()
-                    .describe("READ: optional [start, end] 1-indexed line range per file."),
+                    .describe("Optional [start, end] 1-indexed line range to return per file."),
+            },
+            handler: async (args, session) => {
+                const runCtx = buildRunContext(ctx, session);
+                const result = await githubRead(runCtx, args);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            },
+        }));
+        // 3. github_issues
+        ctx.mcp.registerTool(defineTool({
+            name: "github_issues",
+            description: "List, search, or inspect issues and comments in a GitHub repository without burning browser turns.",
+            requiresSession: false,
+            schema: {
+                repo: z
+                    .string()
+                    .optional()
+                    .describe("Target repository as 'owner/repo' or full github.com URL."),
                 number: z
                     .number()
                     .optional()
-                    .describe("ISSUES / PR: issue or pull request number to fetch full detail and comments."),
+                    .describe("Specific issue number to fetch full details and timeline comments for."),
                 search: z
                     .string()
                     .optional()
-                    .describe("ISSUES: free-text query to search issues in the target repository."),
-                labels: z.array(z.string()).optional().describe("ISSUES: restrict results to these labels."),
+                    .describe("Free-text query to search issues in the repository."),
+                labels: z.array(z.string()).optional().describe("Restrict results to these labels."),
+                state: z
+                    .enum(["open", "closed", "all"])
+                    .optional()
+                    .describe("Filter by issue state (default 'open')."),
+                limit: z
+                    .number()
+                    .optional()
+                    .describe("Maximum number of issues to return (default 5)."),
+            },
+            handler: async (args, session) => {
+                const runCtx = buildRunContext(ctx, session);
+                const result = await githubIssues(runCtx, args);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            },
+        }));
+        // 4. github_pull_request
+        ctx.mcp.registerTool(defineTool({
+            name: "github_pull_request",
+            description: "Examine pull request details, changed files, diff stats, and comments, or list recent pull requests in a GitHub repository without burning browser turns.",
+            requiresSession: false,
+            schema: {
+                repo: z
+                    .string()
+                    .optional()
+                    .describe("Target repository as 'owner/repo' or full github.com URL."),
+                number: z
+                    .number()
+                    .optional()
+                    .describe("Pull request number to fetch full detail, changed files, and comments for."),
                 state: z
                     .enum(["open", "closed", "all"])
                     .optional()
-                    .describe("ISSUES / PR: filter by state."),
+                    .describe("Filter pull requests by state (default 'all' when listing)."),
                 limit: z
                     .number()
                     .optional()
-                    .describe(`ISSUES / PR: max items to return when listing/searching (default ${DEFAULT_ISSUE_LIMIT} for issues, 10 for pull requests).`),
+                    .describe("Maximum pull requests to return when listing (default 10)."),
+            },
+            handler: async (args, session) => {
+                const runCtx = buildRunContext(ctx, session);
+                const result = await githubPullRequest(runCtx, args);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            },
+        }));
+        // 5. github_diff (Zero API Calls)
+        ctx.mcp.registerTool(defineTool({
+            name: "github_diff",
+            description: "Fetch raw git diffs or patches for pull requests, commits, or branch comparisons directly from github.com without consuming REST API rate limits.",
+            requiresSession: false,
+            schema: {
+                repo: z
+                    .string()
+                    .optional()
+                    .describe("Target repository as 'owner/repo' or full github.com URL."),
+                pull_number: z.number().optional().describe("Pull request number to fetch the diff or patch for."),
+                commit_sha: z.string().optional().describe("Commit SHA to fetch the diff or patch for."),
+                base: z.string().optional().describe("Base branch/commit for compare diff (requires 'head')."),
+                head: z.string().optional().describe("Head branch/commit for compare diff (requires 'base')."),
+                format: z
+                    .enum(["diff", "patch"])
+                    .optional()
+                    .describe("Output format: 'diff' (unified diff) or 'patch' (git patch with metadata). Default 'diff'."),
+            },
+            handler: async (args, session) => {
+                const runCtx = buildRunContext(ctx, session);
+                const result = await githubDiff(runCtx, args);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            },
+        }));
+        // 6. github_active_tab (Zero API Calls, works on private repos via CDP)
+        ctx.mcp.registerTool(defineTool({
+            name: "github_active_tab",
+            description: "Inspect the active browser tab on github.com via local CDP evaluation. Extracts repository overview, open PR/issue discussion, or file content directly from the browser DOM with ZERO API calls. Works on private repositories you are logged into.",
+            requiresSession: true,
+            schema: {
+                scope: z
+                    .enum(["auto", "summary", "files", "comments", "raw"])
+                    .optional()
+                    .describe("Scope of data extraction from the page DOM (default 'auto')."),
             },
             handler: async (args, session) => {
-                const result = await runGithub({
-                    session: session,
-                    store: ctx.storage,
-                    cacheTtlMs,
-                    maxReadLines,
-                    defaultIssueLimit,
-                }, args);
-                return {
-                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-                };
+                const runCtx = buildRunContext(ctx, session);
+                const result = await githubActiveTab(runCtx, args);
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
             },
         }));
-        ctx.logger?.info(`@weavetab/plugin-github ready — tool "github" registered (cacheTtlMs=${cacheTtlMs}, maxReadLines=${maxReadLines}, defaultIssueLimit=${defaultIssueLimit}).`);
+        ctx.logger?.info(`@weavetab/plugin-github ready — registered 6 tools: github_analyze, github_read, github_issues, github_pull_request, github_diff, github_active_tab.`);
     },
     async onUnload(ctx) {
         ctx.logger?.info("@weavetab/plugin-github unloaded.");

package/dist/issues.d.ts

@@ -1,15 +1,6 @@
-import type { GithubRunContext } from "./types.js";
-interface IssueArgs {
-    repo?: string;
-    search?: string;
-    number?: number;
-    labels?: string[];
-    state?: "open" | "closed" | "all";
-    limit?: number;
-}
+import type { GithubRunContext, GithubIssuesArgs } from "./types.js";
 /**
  * `issues` action — inspect a single issue (with comments) when `number` is
- * given, otherwise list or search issues in the target repository.
+ * given or open in the active tab, otherwise list or search issues.
  */
-export declare function githubIssues(ctx: GithubRunContext, args: IssueArgs): Promise<any>;
-export {};
+export declare function githubIssues(ctx: GithubRunContext, args?: GithubIssuesArgs): Promise<any>;

package/dist/issues.js

@@ -1,25 +1,23 @@
-import { getRepoContext, isGithubError } from "./repoContext.js";
-import { canMakeApiCall, handleApiResponse } from "./rateLimiter.js";
-const API_HEADERS = {
-    Accept: "application/vnd.github.v3+json",
-    "User-Agent": "Weavetab-GitHub-Plugin",
-};
+import { getDetailedRepoContext, isGithubError } from "./repoContext.js";
+import { canMakeApiCall, handleApiResponse, getApiHeaders } from "./rateLimiter.js";
 /**
  * `issues` action — inspect a single issue (with comments) when `number` is
- * given, otherwise list or search issues in the target repository.
+ * given or open in the active tab, otherwise list or search issues.
  */
-export async function githubIssues(ctx, args) {
-    const context = await getRepoContext(ctx.session, args.repo);
+export async function githubIssues(ctx, args = {}) {
+    const context = await getDetailedRepoContext(ctx.session, args.repo);
     if (isGithubError(context))
         return context;
     const { owner, repo } = context;
+    const targetNumber = typeof args.number === "number" ? args.number : context.issueNumber;
     const limit = args.limit || ctx.defaultIssueLimit;
+    const apiHeaders = getApiHeaders(ctx.token);
     const rateLimitCheck = canMakeApiCall();
     if (isGithubError(rateLimitCheck))
         return rateLimitCheck;
     // Single issue + comments
-    if (args.number) {
-        const issueRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${args.number}`, { headers: API_HEADERS });
+    if (targetNumber) {
+        const issueRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${targetNumber}`, { headers: apiHeaders });
         const handledIssueRes = handleApiResponse(issueRes);
         if (isGithubError(handledIssueRes))
             return handledIssueRes;
@@ -27,7 +25,7 @@ export async function githubIssues(ctx, args) {
             return {
                 error: "FETCH_FAILED",
                 status: issueRes.status,
-                message: `Failed to fetch issue #${args.number}`,
+                message: `Failed to fetch issue #${targetNumber}`,
             };
         }
         const issueData = await issueRes.json();
@@ -35,7 +33,7 @@ export async function githubIssues(ctx, args) {
         if (issueData.comments > 0) {
             const rateLimitCheck2 = canMakeApiCall();
             if (!isGithubError(rateLimitCheck2)) {
-                const commentsRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${args.number}/comments`, { headers: API_HEADERS });
+                const commentsRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${targetNumber}/comments`, { headers: apiHeaders });
                 const handledCommentsRes = handleApiResponse(commentsRes);
                 if (!isGithubError(handledCommentsRes) && commentsRes.ok) {
                     const commentsData = await commentsRes.json();
@@ -73,7 +71,7 @@ export async function githubIssues(ctx, args) {
             args.labels.forEach((l) => (q += ` label:"${l}"`));
         urlStr = `https://api.github.com/search/issues?q=${encodeURIComponent(q)}&per_page=${limit}`;
     }
-    const listRes = await fetch(urlStr, { headers: API_HEADERS });
+    const listRes = await fetch(urlStr, { headers: apiHeaders });
     const handledListRes = handleApiResponse(listRes);
     if (isGithubError(handledListRes))
         return handledListRes;

package/dist/pr.d.ts

@@ -1,13 +1,7 @@
-import type { GithubRunContext } from "./types.js";
-interface PrArgs {
-    repo?: string;
-    number?: number;
-    state?: "open" | "closed" | "all";
-    limit?: number;
-}
+import type { GithubRunContext, GithubPullRequestArgs } from "./types.js";
 /**
- * `pr` action — inspect a single pull request (changed files, diff stats and
- * comments) when `number` is given, otherwise list recent pull requests.
+ * `pull_request` action — inspect a single pull request (changed files, diff stats and
+ * comments) when `number` is given or active in tab, otherwise list recent pull requests.
  */
-export declare function githubGetPr(ctx: GithubRunContext, args: PrArgs): Promise<any>;
-export {};
+export declare function githubPullRequest(ctx: GithubRunContext, args?: GithubPullRequestArgs): Promise<any>;
+export declare const githubGetPr: typeof githubPullRequest;

package/dist/pr.js

@@ -1,25 +1,23 @@
-import { getRepoContext, isGithubError } from "./repoContext.js";
-import { canMakeApiCall, handleApiResponse } from "./rateLimiter.js";
+import { getDetailedRepoContext, isGithubError } from "./repoContext.js";
+import { canMakeApiCall, handleApiResponse, getApiHeaders } from "./rateLimiter.js";
 const DEFAULT_PR_LIMIT = 10;
-const API_HEADERS = {
-    Accept: "application/vnd.github.v3+json",
-    "User-Agent": "Weavetab-GitHub-Plugin",
-};
 /**
- * `pr` action — inspect a single pull request (changed files, diff stats and
- * comments) when `number` is given, otherwise list recent pull requests.
+ * `pull_request` action — inspect a single pull request (changed files, diff stats and
+ * comments) when `number` is given or active in tab, otherwise list recent pull requests.
  */
-export async function githubGetPr(ctx, args) {
-    const context = await getRepoContext(ctx.session, args.repo);
+export async function githubPullRequest(ctx, args = {}) {
+    const context = await getDetailedRepoContext(ctx.session, args.repo);
     if (isGithubError(context))
         return context;
     const { owner, repo } = context;
+    const targetNumber = typeof args.number === "number" ? args.number : context.pullNumber;
+    const apiHeaders = getApiHeaders(ctx.token);
     const rateLimitCheck = canMakeApiCall();
     if (isGithubError(rateLimitCheck))
         return rateLimitCheck;
-    if (args.number) {
-        const prRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${args.number}`, {
-            headers: API_HEADERS,
+    if (targetNumber) {
+        const prRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${targetNumber}`, {
+            headers: apiHeaders,
         });
         const handledPrRes = handleApiResponse(prRes);
         if (isGithubError(handledPrRes))
@@ -28,14 +26,14 @@ export async function githubGetPr(ctx, args) {
             return {
                 error: "FETCH_FAILED",
                 status: prRes.status,
-                message: `Failed to fetch PR #${args.number}`,
+                message: `Failed to fetch PR #${targetNumber}`,
             };
         }
         const prData = await prRes.json();
         let files_changed = [];
         const rateLimitCheck2 = canMakeApiCall();
         if (!isGithubError(rateLimitCheck2)) {
-            const filesRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${args.number}/files`, { headers: API_HEADERS });
+            const filesRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${targetNumber}/files`, { headers: apiHeaders });
             const handledFilesRes = handleApiResponse(filesRes);
             if (!isGithubError(handledFilesRes) && filesRes.ok) {
                 const filesData = await filesRes.json();
@@ -46,7 +44,7 @@ export async function githubGetPr(ctx, args) {
         if (prData.comments > 0) {
             const rateLimitCheck3 = canMakeApiCall();
             if (!isGithubError(rateLimitCheck3)) {
-                const commentsRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${args.number}/comments`, { headers: API_HEADERS });
+                const commentsRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${targetNumber}/comments`, { headers: apiHeaders });
                 const handledCommentsRes = handleApiResponse(commentsRes);
                 if (!isGithubError(handledCommentsRes) && commentsRes.ok) {
                     const commentsData = await commentsRes.json();
@@ -78,7 +76,7 @@ export async function githubGetPr(ctx, args) {
     // List recent pull requests
     const limit = args.limit && args.limit > 0 ? Math.min(args.limit, 100) : DEFAULT_PR_LIMIT;
     const state = args.state || "all";
-    const listRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls?state=${state}&per_page=${limit}`, { headers: API_HEADERS });
+    const listRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls?state=${state}&per_page=${limit}`, { headers: apiHeaders });
     const handledListRes = handleApiResponse(listRes);
     if (isGithubError(handledListRes))
         return handledListRes;
@@ -95,3 +93,4 @@ export async function githubGetPr(ctx, args) {
         updated_at: pr.updated_at,
     }));
 }
+export const githubGetPr = githubPullRequest;

package/dist/rateLimiter.d.ts

@@ -1,8 +1,14 @@
 import type { GithubError } from "./types.js";
+export declare function getApiHeaders(token?: string): Record<string, string>;
 /**
  * Guard that refuses new API calls once the remaining quota drops below a safety
  * threshold, so we never trip GitHub's hard rate limit mid-flow.
  */
 export declare function canMakeApiCall(): true | GithubError;
 export declare function recordApiCall(headers: Headers): void;
+export declare function getRateLimitStatus(): {
+    remaining: number;
+    resetAt: number | null;
+    limit: number;
+};
 export declare function handleApiResponse(response: Response): Response | GithubError;

package/dist/rateLimiter.js

@@ -1,5 +1,16 @@
 const SAFETY_THRESHOLD = 5;
 const state = { remaining: 60, resetAt: null };
+export function getApiHeaders(token) {
+    const headers = {
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "Weavetab-GitHub-Plugin",
+    };
+    const tok = token || process.env.GITHUB_TOKEN;
+    if (tok) {
+        headers.Authorization = `Bearer ${tok.trim()}`;
+    }
+    return headers;
+}
 /**
  * Guard that refuses new API calls once the remaining quota drops below a safety
  * threshold, so we never trip GitHub's hard rate limit mid-flow.
@@ -7,8 +18,8 @@ const state = { remaining: 60, resetAt: null };
 export function canMakeApiCall() {
     const nowSec = Math.floor(Date.now() / 1000);
     if (state.resetAt && nowSec >= state.resetAt) {
-        // We've passed the reset window, assume quota is restored.
-        state.remaining = 60;
+        const hasToken = Boolean(process.env.GITHUB_TOKEN);
+        state.remaining = hasToken ? 5000 : 60;
         state.resetAt = null;
     }
     if (state.remaining < SAFETY_THRESHOLD) {
@@ -32,6 +43,14 @@ export function recordApiCall(headers) {
         state.resetAt = parseInt(resetStr, 10) || state.resetAt;
     }
 }
+export function getRateLimitStatus() {
+    const hasToken = Boolean(process.env.GITHUB_TOKEN);
+    return {
+        remaining: state.remaining,
+        resetAt: state.resetAt,
+        limit: hasToken ? 5000 : 60,
+    };
+}
 export function handleApiResponse(response) {
     recordApiCall(response.headers);
     if (response.status === 403 || response.status === 429) {

package/dist/read.d.ts

@@ -1,14 +1,8 @@
-import type { GithubRunContext } from "./types.js";
-interface ReadArgs {
-    repo?: string;
-    paths: string[];
-    line_range?: number[];
-}
+import type { GithubRunContext, GithubReadArgs } from "./types.js";
 /**
- * `read` action — fetch raw file contents from the default branch.
+ * `read` action — fetch raw file contents from raw.githubusercontent.com.
  *
- * Ensures an analysis (and thus `default_branch` + `file_tree`) exists first,
- * then fetches each requested path in parallel over raw.githubusercontent.com.
+ * If a branch is explicitly provided, cached, or inferred from the active tab,
+ * reads directly over HTTP without consuming any GitHub API rate-limited quota.
  */
-export declare function githubRead(ctx: GithubRunContext, args: ReadArgs): Promise<any>;
-export {};
+export declare function githubRead(ctx: GithubRunContext, args: GithubReadArgs): Promise<any>;

package/dist/read.js

@@ -1,60 +1,104 @@
-import { getRepoContext, isGithubError } from "./repoContext.js";
+import { getDetailedRepoContext, isGithubError } from "./repoContext.js";
 import { loadRepoCache } from "./cache.js";
-import { githubAnalyze } from "./analyze.js";
+const BINARY_EXTENSIONS = new Set([
+    "png", "jpg", "jpeg", "gif", "webp", "ico", "bmp", "tiff",
+    "pdf", "zip", "tar", "gz", "tgz", "7z", "rar",
+    "wasm", "exe", "dll", "so", "dylib",
+    "mp3", "mp4", "wav", "avi", "mov", "webm",
+    "woff", "woff2", "ttf", "eot", "otf",
+]);
+function isBinaryPath(filePath) {
+    const ext = filePath.split(".").pop()?.toLowerCase();
+    return ext ? BINARY_EXTENSIONS.has(ext) : false;
+}
 /**
- * `read` action — fetch raw file contents from the default branch.
+ * `read` action — fetch raw file contents from raw.githubusercontent.com.
  *
- * Ensures an analysis (and thus `default_branch` + `file_tree`) exists first,
- * then fetches each requested path in parallel over raw.githubusercontent.com.
+ * If a branch is explicitly provided, cached, or inferred from the active tab,
+ * reads directly over HTTP without consuming any GitHub API rate-limited quota.
  */
 export async function githubRead(ctx, args) {
-    const context = await getRepoContext(ctx.session, args.repo);
+    const context = await getDetailedRepoContext(ctx.session, args.repo);
     if (isGithubError(context))
         return context;
     const { owner, repo } = context;
-    let cached = await loadRepoCache(owner, repo, ctx.store, ctx.cacheTtlMs);
-    if (!cached) {
-        const analyzed = await githubAnalyze(ctx, args.repo);
-        if (isGithubError(analyzed))
-            return analyzed;
-        cached = analyzed;
+    // Resolve target paths (explicit paths win, fallback to active tab file)
+    let rawPaths = Array.isArray(args.paths) ? args.paths.filter((p) => typeof p === "string" && p.trim()) : [];
+    if (rawPaths.length === 0 && context.filePath) {
+        rawPaths = [context.filePath];
+    }
+    if (rawPaths.length === 0) {
+        return {
+            error: "MISSING_PATHS",
+            message: "github_read requires a 'paths' array (or open a source file blob in the active browser tab).",
+        };
+    }
+    let branch = args.branch || context.branch;
+    let file_tree = null;
+    if (!branch) {
+        const cached = await loadRepoCache(owner, repo, ctx.store, ctx.cacheTtlMs);
+        if (cached) {
+            branch = cached.default_branch;
+            file_tree = cached.file_tree;
+        }
+        else {
+            branch = "main";
+        }
     }
-    const default_branch = cached.default_branch;
-    const file_tree = cached.file_tree;
     const results = [];
     const warnings = [];
-    const fetchPromises = args.paths.map(async (rawPath) => {
+    const fetchPromises = rawPaths.map(async (rawPath) => {
         const path = rawPath.replace(/\\/g, "/").replace(/^\/+/, "");
         if (path.includes("..") || path.includes("\0")) {
             return { path: rawPath, error: "INVALID_PATH", message: "Path traversal or null bytes detected." };
         }
-        if (!file_tree.some((entry) => entry.path === path)) {
+        if (file_tree && !file_tree.some((entry) => entry.path === path)) {
             warnings.push(`Path '${path}' was not found in the cached file tree. Branch contents may differ.`);
         }
-        const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${default_branch}/${path}`;
+        if (isBinaryPath(path)) {
+            return {
+                path,
+                branch: branch,
+                binary: true,
+                message: "Binary file omitted from text read.",
+            };
+        }
+        let targetBranch = branch;
+        let rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${targetBranch}/${path}`;
         try {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), 10_000);
-            const res = await fetch(rawUrl, { signal: controller.signal });
-            clearTimeout(timeout);
+            let res = await fetchWithTimeout(rawUrl, 10_000);
+            // If branch wasn't pinned and "main" failed, try "master"
+            if (!res.ok && res.status === 404 && !args.branch && !context.branch && branch === "main") {
+                const altUrl = `https://raw.githubusercontent.com/${owner}/${repo}/master/${path}`;
+                const altRes = await fetchWithTimeout(altUrl, 10_000);
+                if (altRes.ok) {
+                    res = altRes;
+                    targetBranch = "master";
+                }
+            }
             if (!res.ok) {
                 return { path, error: "FETCH_FAILED", status: res.status, message: res.statusText };
             }
-            const lines = (await res.text()).split("\n");
+            const text = await res.text();
+            const lines = text.split("\n");
             const total_lines = lines.length;
-            let returnedContent = lines.join("\n");
+            let returnedContent = text;
             let truncated = false;
             if (Array.isArray(args.line_range) && args.line_range.length === 2) {
-                const start = Math.max(0, args.line_range[0] - 1); // 1-indexed -> 0-indexed
-                const end = Math.min(total_lines, args.line_range[1]);
-                returnedContent = lines.slice(start, end).join("\n");
-                truncated = start > 0 || end < total_lines;
+                let start = Math.floor(args.line_range[0]);
+                let end = Math.floor(args.line_range[1]);
+                if (start > end)
+                    [start, end] = [end, start];
+                start = Math.max(1, start);
+                end = Math.min(total_lines, end);
+                returnedContent = lines.slice(start - 1, end).join("\n");
+                truncated = start > 1 || end < total_lines;
             }
             else if (total_lines > ctx.maxReadLines) {
                 returnedContent = lines.slice(0, ctx.maxReadLines).join("\n");
                 truncated = true;
             }
-            return { path, total_lines, truncated, content: returnedContent };
+            return { path, branch: targetBranch, total_lines, truncated, content: returnedContent };
         }
         catch (err) {
             return { path, error: "FETCH_ERROR", message: err?.message };
@@ -67,3 +111,13 @@ export async function githubRead(ctx, args) {
         files: results,
     };
 }
+async function fetchWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}