feat: forward live progress from research and get_example

changes/mcp-tool-progress.added.md

@@ -0,0 +1,6 @@
+---
+"githits": minor
+"@githits/mcp": minor
+---
+
+- **Live progress for `research` and `get_example`** - When an MCP host requests progress, the local MCP server now forwards GitHits status updates as `notifications/progress` while these long-running tools work; hosts that display them (such as Claude Code) show the current stage under the running call. Progress is best effort and authorized by the caller's own token: if it is unavailable, calls run exactly as before and the final result is unchanged. `@githits/mcp` adds an optional `progress` server option and a credential-free `RelayReceiver`, and now depends on `ws`.

changes/project-key-token-refresh.fixed.md

@@ -0,0 +1,6 @@
+---
+"githits": patch
+"@githits/mcp": patch
+---
+
+- **No refresh attempt for project API keys** - Authentication failures with a `gh-proj-` project API key no longer trigger a credential refresh, matching personal `ghi-` API tokens; only signed-in sessions refresh.

package.json

@@ -116,13 +116,15 @@
     "semver": "7.8.5",
     "smol-toml": "^1.9.0",
     "undici": "7.30.0",
+    "ws": "^8.22.0",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
     "@types/bun": "1.4.2",
     "@types/semver": "^7.8.0",
+    "@types/ws": "^8.18.2",
     "braintrust": "3.37.0",
     "bunup": "^0.16.32",
     "husky": "^9.1.7",

packages/core-internal/src/index.ts

@@ -9,6 +9,7 @@ export * from "./services/grep-service.js";
 export * from "./services/indexing-estimates.js";
 export * from "./services/list-service.js";
 export * from "./services/package-intelligence-service.js";
+export * from "./services/progress-request.js";
 export * from "./services/promote-version-not-found.js";
 export * from "./services/read-service.js";
 export * from "./services/read-target.js";

packages/core-internal/src/services/agentic-ask-service.ts

@@ -7,6 +7,11 @@ import {
   isTokenRefreshableError,
   parseRetryAfterSeconds,
 } from "./githits-service.js";
+import {
+  discardResponseBody,
+  type ProgressRequest,
+  readProgressRejection,
+} from "./progress-request.js";
 import {
   type ServiceDiagnostics,
   withServiceDiagnostics,
@@ -50,6 +55,8 @@ export type AgenticAskRequest = AgenticAskQuestion &
 
 export interface AgenticAskRequestOptions {
   signal?: AbortSignal;
+  /** Optional best-effort progress correlation; never changes the result. */
+  progress?: ProgressRequest;
 }
 
 /** Expected backend envelope; successful JSON is deliberately not runtime-validated. */
@@ -181,7 +188,7 @@ export class AgenticAskServiceImpl implements AgenticAskService {
                   error.code === "AUTH_REQUIRED") ||
                 isTokenRefreshableError(error),
               executeWithToken: (token) =>
-                this.executeAsk(token, request, signal),
+                this.executeAsk(token, request, signal, options.progress),
             }),
           options.signal,
           this.runtime.timeoutMs ?? AGENTIC_ASK_REQUEST_TIMEOUT_MS,
@@ -193,6 +200,7 @@ export class AgenticAskServiceImpl implements AgenticAskService {
     token: string,
     request: AgenticAskRequest,
     signal: AbortSignal,
+    progress?: ProgressRequest,
   ): Promise<AgenticAskResponse> {
     const apiUrl = validateServiceUrl(this.apiUrl, "GITHITS_API_URL");
     let response: Response;
@@ -201,6 +209,7 @@ export class AgenticAskServiceImpl implements AgenticAskService {
         method: "POST",
         headers: {
           ...this.runtime.clientHeaders?.(),
+          ...progress?.headers,
           Authorization: `Bearer ${token}`,
           "Content-Type": "application/json",
           "User-Agent": this.runtime.userAgent ?? "githits-cli",
@@ -222,6 +231,14 @@ export class AgenticAskServiceImpl implements AgenticAskService {
       throw cause;
     }
 
+    const progressRejection = progress && readProgressRejection(response);
+    if (progressRejection) {
+      // Rejected before admission: nothing ran, so resend without progress.
+      progress.rejected(progressRejection);
+      await discardResponseBody(response);
+      return this.executeAsk(token, request, signal);
+    }
+
     const toolCallId = readAgenticAskResponseId(
       response.headers.get("X-GitHits-Tool-Call-Id"),
     );

packages/core-internal/src/services/execute-with-token-refresh.test.ts

@@ -6,24 +6,27 @@ import {
 } from "./githits-service.js";
 
 describe("executeWithTokenRefresh", () => {
-  it("never calls the refresh hook for an opaque ghi-* token", async () => {
-    const forceRefresh = mock(() => Promise.resolve("unexpected-token"));
-    const executeWithToken = mock(() =>
-      Promise.reject(new TermsAcceptanceRequiredError()),
-    );
-
-    await expect(
-      executeWithTokenRefresh({
-        getToken: mock(() => Promise.resolve("ghi-static-token")),
-        forceRefresh,
-        executeWithToken,
-        shouldRefresh: () => true,
-      }),
-    ).rejects.toBeInstanceOf(TermsAcceptanceRequiredError);
-
-    expect(forceRefresh).not.toHaveBeenCalled();
-    expect(executeWithToken).toHaveBeenCalledTimes(1);
-  });
+  it.each(["ghi-static-token", "gh-proj-static-token"])(
+    "never calls the refresh hook for opaque API token %s",
+    async (token) => {
+      const forceRefresh = mock(() => Promise.resolve("unexpected-token"));
+      const executeWithToken = mock(() =>
+        Promise.reject(new TermsAcceptanceRequiredError()),
+      );
+
+      await expect(
+        executeWithTokenRefresh({
+          getToken: mock(() => Promise.resolve(token)),
+          forceRefresh,
+          executeWithToken,
+          shouldRefresh: () => true,
+        }),
+      ).rejects.toBeInstanceOf(TermsAcceptanceRequiredError);
+
+      expect(forceRefresh).not.toHaveBeenCalled();
+      expect(executeWithToken).toHaveBeenCalledTimes(1);
+    },
+  );
   it("rejects with an already-aborted caller reason before reading a token", async () => {
     const controller = new AbortController();
     const reason = new Error("already cancelled");

packages/core-internal/src/services/execute-with-token-refresh.ts

@@ -39,9 +39,9 @@ export async function executeWithTokenRefresh<T>(
     // A cancelled caller no longer wants the result; surface the caller's
     // reason instead of refreshing credentials for a retry.
     signal?.throwIfAborted();
-    // Opaque ghi-* credentials are re-evaluated server-side and have no local
-    // refresh flow. Do not invoke the provider's refresh hook for them.
-    if (token.startsWith("ghi-") || !options.shouldRefresh(error)) {
+    // Opaque API tokens (personal ghi-*, project gh-proj-*) are re-evaluated
+    // server-side and have no local refresh flow; only Supabase JWTs refresh.
+    if (isOpaqueApiToken(token) || !options.shouldRefresh(error)) {
       throw error;
     }
 
@@ -72,3 +72,7 @@ async function callerFirst<T>(
     throw error;
   }
 }
+
+function isOpaqueApiToken(token: string): boolean {
+  return token.startsWith("ghi-") || token.startsWith("gh-proj-");
+}

packages/core-internal/src/services/githits-service.ts

@@ -16,6 +16,10 @@ import {
   AuthenticationError,
   SERVER_AUTHENTICATION_REJECTED_MESSAGE,
 } from "./githits-service-errors.js";
+import {
+  type ProgressRequest,
+  readProgressRejection,
+} from "./progress-request.js";
 import {
   type ServiceDiagnostics,
   withServiceDiagnostics,
@@ -107,6 +111,8 @@ export interface SearchParams {
 /** Optional browser-standard controls for a GitHits service request. */
 export interface GitHitsServiceRequestOptions {
   signal?: AbortSignal;
+  /** Optional best-effort progress correlation; never changes the result. */
+  progress?: ProgressRequest;
 }
 
 export interface GitHitsServiceRuntimeOptions {
@@ -148,23 +154,32 @@ export class GitHitsServiceImpl implements GitHitsService {
       this.runtime.diagnostics,
       "githits.search.request",
       async () => {
-        const { response, body } = await this.request(
-          "/search",
-          {
-            method: "POST",
-            headers: this.headers(),
-            body: JSON.stringify({
-              query: params.query,
-              source_format: params.sourceFormat,
-              language: params.language,
-              license_mode: params.licenseMode ?? "strict",
-              include_explanation: params.includeExplanation ?? false,
-            }),
-            ...(options?.signal ? { signal: options.signal } : {}),
-          },
-          this.runtime.exampleRequestTimeoutMs ??
-            DEFAULT_EXAMPLE_REQUEST_TIMEOUT_MS,
-        );
+        const send = (progress?: ProgressRequest) =>
+          this.request(
+            "/search",
+            {
+              method: "POST",
+              headers: this.headers(progress?.headers),
+              body: JSON.stringify({
+                query: params.query,
+                source_format: params.sourceFormat,
+                language: params.language,
+                license_mode: params.licenseMode ?? "strict",
+                include_explanation: params.includeExplanation ?? false,
+              }),
+              ...(options?.signal ? { signal: options.signal } : {}),
+            },
+            this.runtime.exampleRequestTimeoutMs ??
+              DEFAULT_EXAMPLE_REQUEST_TIMEOUT_MS,
+          );
+        let { response, body } = await send(options?.progress);
+        const progressRejection =
+          options?.progress && readProgressRejection(response);
+        if (progressRejection) {
+          // Rejected before admission: nothing ran, so resend without progress.
+          options.progress?.rejected(progressRejection);
+          ({ response, body } = await send());
+        }
 
         if (!response.ok) {
           throw this.createError(response, body);
@@ -175,9 +190,12 @@ export class GitHitsServiceImpl implements GitHitsService {
     );
   }
 
-  private headers(): Record<string, string> {
+  private headers(
+    extra?: Readonly<Record<string, string>>,
+  ): Record<string, string> {
     return {
       ...this.runtime.clientHeaders?.(),
+      ...extra,
       Authorization: `Bearer ${this.token}`,
       "Content-Type": "application/json",
       "User-Agent": this.runtime.userAgent ?? "githits-cli",