@stigmer/react 3.1.1 → 3.1.2

package/src/execution/__tests__/useCreateAgentExecution.test.tsx

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StigmerContext } from "../../context";
+import { useCreateAgentExecution } from "../useCreateAgentExecution";
+
+const mockCreate = vi.fn();
+
+function makeMockClient(): Stigmer {
+  return {
+    agentExecution: { create: mockCreate },
+  } as unknown as Stigmer;
+}
+
+function createWrapper(client: Stigmer) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>;
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockCreate.mockResolvedValue({ metadata: { id: "aex-1" } });
+});
+
+describe("useCreateAgentExecution — executionConfig mapping", () => {
+  it("maps buildFromPlan into executionConfig (the Build-from-plan turn)", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Build from plan",
+        interactionMode: "agent",
+        buildFromPlan: true,
+      });
+    });
+
+    expect(mockCreate).toHaveBeenCalledTimes(1);
+    expect(mockCreate.mock.calls[0][0].executionConfig).toMatchObject({
+      interactionMode: InteractionMode.AGENT,
+      buildFromPlan: true,
+    });
+  });
+
+  it("builds an executionConfig when buildFromPlan is the only config input", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Build from plan",
+        buildFromPlan: true,
+      });
+    });
+
+    expect(mockCreate.mock.calls[0][0].executionConfig).toMatchObject({
+      buildFromPlan: true,
+    });
+  });
+
+  it("omits executionConfig entirely for an ordinary message", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        sessionId: "ses-1",
+        message: "Hello",
+      });
+    });
+
+    expect(mockCreate.mock.calls[0][0].executionConfig).toBeUndefined();
+  });
+});

package/src/execution/index.ts

@@ -41,6 +41,12 @@ export type { PlanCompletionCardProps } from "./PlanCompletionCard.js";
 export { PlanArtifactCard } from "./PlanArtifactCard.js";
 export type { PlanArtifactCardProps } from "./PlanArtifactCard.js";
 
+export { PlanStreamingCard } from "./PlanStreamingCard.js";
+export type { PlanStreamingCardProps } from "./PlanStreamingCard.js";
+
+export { PlanDocumentMessage } from "./PlanDocumentMessage.js";
+export type { PlanDocumentMessageProps } from "./PlanDocumentMessage.js";
+
 export { useExecutionArtifacts } from "./useExecutionArtifacts.js";
 export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts.js";
 
@@ -160,7 +166,7 @@ export { MessageEntry } from "./MessageEntry.js";
 export type { MessageEntryProps } from "./MessageEntry.js";
 
 export { MessageThread } from "./MessageThread.js";
-export type { MessageThreadProps } from "./MessageThread.js";
+export type { MessageThreadProps, ThreadContentColumn } from "./MessageThread.js";
 
 export { ThreadSkeleton } from "./ThreadSkeleton.js";
 export type { ThreadSkeletonProps } from "./ThreadSkeleton.js";

package/src/execution/useCreateAgentExecution.ts

@@ -54,6 +54,16 @@ export interface CreateAgentExecutionInput {
    * Maps to `ExecutionConfig.interaction_mode` in the proto.
    */
   readonly interactionMode?: "agent" | "plan";
+  /**
+   * Marks this execution as a "Build from plan" turn: the user approved a
+   * plan from a prior Plan-mode execution and asked the agent to implement
+   * it. The runner injects the implement-plan directive (pointing at the
+   * attached approved plan when present); the thread renders the turn as a
+   * compact chip instead of the raw message text.
+   *
+   * Maps to `ExecutionConfig.build_from_plan` in the proto.
+   */
+  readonly buildFromPlan?: boolean;
   /**
    * Auto-approve every tool call for this execution.
    *
@@ -158,7 +168,11 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
       setError(null);
 
       try {
-        const hasConfig = input.modelName || input.interactionMode || input.structuredOutputSchema;
+        const hasConfig =
+          input.modelName ||
+          input.interactionMode ||
+          input.structuredOutputSchema ||
+          input.buildFromPlan;
         const executionConfig = hasConfig
           ? {
               ...(input.modelName ? { modelName: input.modelName } : {}),
@@ -168,6 +182,7 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
               ...(input.structuredOutputSchema
                 ? { structuredOutputSchema: input.structuredOutputSchema }
                 : {}),
+              ...(input.buildFromPlan ? { buildFromPlan: true } : {}),
             }
           : undefined;
 

package/src/github/__tests__/decodeGitHubContent.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import {
+  base64ToBytes,
+  detectBinary,
+  bytesToText,
+  normalizeGitHubContent,
+} from "../decodeGitHubContent";
+import { MAX_WORKSPACE_FILE_READ_BYTES } from "../../workspace/WorkspaceFileReader";
+
+function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+describe("base64ToBytes", () => {
+  it("decodes plain base64 to bytes", () => {
+    expect(bytesToText(base64ToBytes("SGVsbG8gV29ybGQh"))).toBe("Hello World!");
+  });
+
+  it("strips the newlines GitHub inserts every 60 chars", () => {
+    // GitHub's Contents API line-wraps its base64; atob would otherwise reject it.
+    const wrapped = "SGVsbG8g\nV29ybGQh\n";
+    expect(bytesToText(base64ToBytes(wrapped))).toBe("Hello World!");
+  });
+});
+
+describe("detectBinary", () => {
+  it("flags a buffer containing a NUL byte", () => {
+    expect(detectBinary(new Uint8Array([0x48, 0x00, 0x49]))).toBe(true);
+  });
+
+  it("treats NUL-free text as non-binary", () => {
+    expect(detectBinary(utf8("just some text"))).toBe(false);
+  });
+
+  it("only sniffs the head — a NUL past the sniff window is not detected", () => {
+    const bytes = new Uint8Array(9000).fill(0x61); // non-zero baseline
+    bytes[8500] = 0; // beyond the 8000-byte sniff window
+    expect(detectBinary(bytes)).toBe(false);
+  });
+});
+
+describe("bytesToText", () => {
+  it("decodes valid UTF-8", () => {
+    expect(bytesToText(utf8("héllo — 世界"))).toBe("héllo — 世界");
+  });
+
+  it("returns null for invalid UTF-8", () => {
+    // 0xFF is never a valid UTF-8 lead byte; the fatal decoder throws → null.
+    expect(bytesToText(new Uint8Array([0xff]))).toBeNull();
+  });
+});
+
+describe("normalizeGitHubContent", () => {
+  it("maps clean text to a utf-8 content record with the full size", () => {
+    const bytes = utf8("hello");
+    expect(normalizeGitHubContent(bytes, bytes.length)).toEqual({
+      text: "hello",
+      isBinary: false,
+      size: bytes.length,
+      encoding: "utf-8",
+    });
+  });
+
+  it("reports binary content with text null", () => {
+    const result = normalizeGitHubContent(new Uint8Array([0x00, 0x01, 0x02]), 3);
+    expect(result).toEqual({
+      text: null,
+      isBinary: true,
+      size: 3,
+      encoding: "base64",
+    });
+  });
+
+  it("marks undecodable (non-binary) bytes as unknown encoding", () => {
+    // 0xC0 is an invalid UTF-8 lead byte but not a NUL, so it is not "binary".
+    const result = normalizeGitHubContent(new Uint8Array([0xc0, 0x41]), 2);
+    expect(result).toEqual({
+      text: null,
+      isBinary: false,
+      size: 2,
+      encoding: "unknown",
+    });
+  });
+
+  it("truncates at the 1 MB cap and flags it, while size reports the full length", () => {
+    const total = MAX_WORKSPACE_FILE_READ_BYTES + 500;
+    const bytes = new Uint8Array(total).fill(0x61); // 'a'
+    const result = normalizeGitHubContent(bytes, total);
+
+    expect(result.truncated).toBe(true);
+    expect(result.size).toBe(total);
+    expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
+    expect(result.encoding).toBe("utf-8");
+  });
+
+  it("does not set truncated when exactly at the cap", () => {
+    const bytes = new Uint8Array(MAX_WORKSPACE_FILE_READ_BYTES).fill(0x61);
+    const result = normalizeGitHubContent(bytes, bytes.length);
+    expect(result.truncated).toBeUndefined();
+    expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
+  });
+});

package/src/github/__tests__/useGitHubFileReader.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useGitHubFileReader } from "../useGitHubFileReader";
+import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
+
+function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: "ws-1",
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+function localEntry(): WorkspaceEntry {
+  return {
+    id: "ws-2",
+    name: "/Users/dev/project",
+    type: "local",
+    localPath: "/Users/dev/project",
+  };
+}
+
+function b64(s: string): string {
+  return Buffer.from(s, "utf-8").toString("base64");
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status });
+}
+
+describe("useGitHubFileReader", () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns undefined when token is null", () => {
+    const { result } = renderHook(() => useGitHubFileReader(null));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns a reader function when a token is provided", () => {
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    expect(typeof result.current).toBe("function");
+  });
+
+  it("returns null for non-git entries without fetching", async () => {
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(localEntry(), "src/index.ts");
+    expect(content).toBeNull();
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns null for non-GitHub git URLs", async () => {
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(
+      gitEntry({ gitUrl: "https://gitlab.com/acme/api" }),
+      "src/index.ts",
+    );
+    expect(content).toBeNull();
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("decodes a base64 text file from the Contents API", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 12, content: b64("Hello World!"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(gitEntry(), "src/index.ts");
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.github.com/repos/acme/api/contents/src/index.ts?ref=main",
+      { headers: { Authorization: "Bearer ghp_abc" } },
+    );
+    expect(content).toEqual({
+      text: "Hello World!",
+      isBinary: false,
+      size: 12,
+      encoding: "utf-8",
+    });
+  });
+
+  it("encodes the path per segment and the branch", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 1, content: b64("x"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await result.current!(
+      gitEntry({ gitBranch: "feat/my branch" }),
+      "src/a b/c#d.ts",
+    );
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.github.com/repos/acme/api/contents/src/a%20b/c%23d.ts?ref=feat%2Fmy%20branch",
+      expect.anything(),
+    );
+  });
+
+  it("defaults to the main branch when gitBranch is undefined", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "base64", size: 1, content: b64("x"), sha: "s1" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await result.current!(gitEntry({ gitBranch: undefined }), "f.ts");
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      expect.stringContaining("?ref=main"),
+      expect.anything(),
+    );
+  });
+
+  it("throws on a non-OK response (404 = failed to load, not unsupported)", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(new Response("nope", { status: 404 }));
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await expect(result.current!(gitEntry(), "missing.ts")).rejects.toThrow("HTTP 404");
+  });
+
+  it("throws when the path is a directory (Contents API returns an array)", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(jsonResponse([{ name: "index.ts" }]));
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    await expect(result.current!(gitEntry(), "src")).rejects.toThrow("is a directory");
+  });
+
+  it("falls back to the Blob API when Contents returns encoding:none", async () => {
+    const big = "x".repeat(2_000_000); // > 1 MB, ≤ 10 MB ceiling
+    vi.mocked(globalThis.fetch)
+      .mockResolvedValueOnce(
+        jsonResponse({ encoding: "none", size: big.length, content: "", sha: "blobsha" }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({ encoding: "base64", size: big.length, content: b64(big) }),
+      );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(gitEntry(), "big.txt");
+
+    expect(vi.mocked(globalThis.fetch).mock.calls[1][0]).toBe(
+      "https://api.github.com/repos/acme/api/git/blobs/blobsha",
+    );
+    expect(content!.size).toBe(big.length);
+    expect(content!.truncated).toBe(true);
+    expect(content!.text).toHaveLength(1_048_576);
+  });
+
+  it("reports files above the blob ceiling as too-large without downloading", async () => {
+    const hugeSize = 50 * 1024 * 1024; // 50 MB > 10 MB ceiling
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      jsonResponse({ encoding: "none", size: hugeSize, content: "", sha: "blobsha" }),
+    );
+
+    const { result } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const content = await result.current!(gitEntry(), "huge.bin");
+
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1); // no blob download
+    expect(content).toEqual({
+      text: null,
+      isBinary: false,
+      size: hugeSize,
+      encoding: "none",
+      truncated: true,
+    });
+  });
+
+  it("returns a stable reader reference across renders", () => {
+    const { result, rerender } = renderHook(() => useGitHubFileReader("ghp_abc"));
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});

package/src/github/decodeGitHubContent.ts

@@ -0,0 +1,83 @@
+// Pure byte/text decode helpers for the GitHub file reader.
+// Kept free of React and fetch so the Slice 0 spike behavior (base64 decode,
+// binary detection, the 1 MB cap) is unit-testable in isolation.
+
+import {
+  MAX_WORKSPACE_FILE_READ_BYTES,
+  type WorkspaceFileContent,
+} from "../workspace/WorkspaceFileReader.js";
+
+// Scan only the head for a NUL byte — git uses the first 8000 bytes as its
+// text/binary heuristic, and scanning the whole buffer buys nothing.
+const BINARY_SNIFF_BYTES = 8000;
+
+/**
+ * Decode a GitHub base64 payload to raw bytes.
+ *
+ * GitHub's Contents API line-wraps its base64 with `\n` every 60 chars, and
+ * `atob` rejects embedded newlines in some engines — strip all ASCII
+ * whitespace first.
+ */
+export function base64ToBytes(b64: string): Uint8Array {
+  const clean = b64.replace(/\s/g, "");
+  const binary = atob(clean);
+  return Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+}
+
+/** Detect binary content via a NUL byte in the head of the buffer. */
+export function detectBinary(bytes: Uint8Array): boolean {
+  const limit = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+  for (let i = 0; i < limit; i++) {
+    if (bytes[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Decode bytes as strict UTF-8, returning `null` when the sequence is invalid.
+ * `{ fatal: true }` makes `TextDecoder` throw rather than emit replacement
+ * characters, so undecodable files degrade to the binary/unknown fallback
+ * instead of silently rendering mojibake.
+ */
+export function bytesToText(bytes: Uint8Array): string | null {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Turn decoded bytes into a {@link WorkspaceFileContent}, applying binary
+ * detection and the shared 1 MB display cap.
+ *
+ * @param bytes    the full decoded bytes as delivered by GitHub
+ * @param fullSize the file's true size in bytes (GitHub's `size` field), which
+ *                 may exceed `bytes.length` when the caller has already capped
+ *                 the download — reported verbatim as `size`.
+ */
+export function normalizeGitHubContent(
+  bytes: Uint8Array,
+  fullSize: number,
+): WorkspaceFileContent {
+  if (detectBinary(bytes)) {
+    return { text: null, isBinary: true, size: fullSize, encoding: "base64" };
+  }
+
+  // Decode the full buffer, then cap the resulting *string* — capping the bytes
+  // first could split a multibyte char at the boundary and make the fatal
+  // decoder reject an otherwise-valid file.
+  const text = bytesToText(bytes);
+  if (text === null) {
+    return { text: null, isBinary: false, size: fullSize, encoding: "unknown" };
+  }
+
+  const truncated = bytes.length > MAX_WORKSPACE_FILE_READ_BYTES;
+  return {
+    text: truncated ? text.slice(0, MAX_WORKSPACE_FILE_READ_BYTES) : text,
+    isBinary: false,
+    size: fullSize,
+    encoding: "utf-8",
+    ...(truncated ? { truncated: true } : {}),
+  };
+}

package/src/github/index.ts

@@ -25,4 +25,5 @@ export {
 } from "./GitHubRepoPicker.js";
 
 export { useGitHubTreeLister } from "./useGitHubTreeLister.js";
+export { useGitHubFileReader } from "./useGitHubFileReader.js";
 export { parseGitUrl, type ParsedGitRepo } from "./parseGitUrl.js";

package/src/github/useGitHubFileReader.ts

@@ -0,0 +1,152 @@
+"use client";
+
+import { useCallback } from "react";
+import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
+import type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "../workspace/WorkspaceFileReader.js";
+import { base64ToBytes, normalizeGitHubContent } from "./decodeGitHubContent.js";
+import { parseGitUrl } from "./parseGitUrl.js";
+
+const GITHUB_API = "https://api.github.com/repos";
+
+/**
+ * Upper bound on files we will pull through the Blob API (Gate 1, Option B).
+ *
+ * The Contents API caps at ~1 MB and signals larger files with
+ * `encoding: "none"`; the Blob API then serves them in full (up to GitHub's own
+ * ~100 MB blob limit). Since we only ever display the first ~1 MB, downloading
+ * a 90 MB blob to show 1 MB is wasteful — so above this ceiling we report the
+ * file as too-large
+ * (`text: null`, `truncated: true`) using the size GitHub already told us,
+ * without downloading anything.
+ */
+const BLOB_FETCH_CEILING_BYTES = 10 * 1024 * 1024; // 10 MiB
+
+/** Single-file shape of `GET /repos/{o}/{r}/contents/{path}`. */
+interface GitHubContentsFile {
+  readonly encoding: "base64" | "none";
+  readonly size: number;
+  readonly content: string;
+  readonly sha: string;
+}
+
+/** Shape of `GET /repos/{o}/{r}/git/blobs/{sha}`. */
+interface GitHubBlob {
+  readonly encoding: "base64";
+  readonly size: number;
+  readonly content: string;
+}
+
+/** Encode a repo-relative path per segment, preserving the slashes. */
+function encodePath(path: string): string {
+  return path.split("/").map(encodeURIComponent).join("/");
+}
+
+/**
+ * Creates a {@link WorkspaceFileReader} backed by the GitHub Contents API,
+ * with a Blob-API fallback for files above the Contents 1 MB cap.
+ *
+ * Uses the same client-side OAuth token as {@link useGitHubTreeLister}
+ * (`Authorization: Bearer`), inheriting its private-repo scope. Returns
+ * `undefined` when no token is present, mirroring the tree lister so callers
+ * can treat "no reader" and "no lister" identically.
+ *
+ * The reader itself:
+ * - Returns `null` when the entry is not a readable GitHub git repo
+ *   (non-git entry, missing/unparseable URL) — the "unsupported here" state.
+ * - **Throws** on a real failure: a non-OK response, or a directory path
+ *   (which the Contents API returns as a JSON array). Consumers surface these
+ *   as an error, distinct from the null "unsupported" state.
+ *
+ * @example
+ * ```tsx
+ * const gitHubConnection = useGitHubConnection(org);
+ * const fileReader = useGitHubFileReader(gitHubConnection.token);
+ * <SessionViewer workspaceFileReader={fileReader} />
+ * ```
+ */
+export function useGitHubFileReader(
+  token: string | null,
+): WorkspaceFileReader | undefined {
+  const reader = useCallback(
+    async (
+      entry: WorkspaceEntry,
+      path: string,
+    ): Promise<WorkspaceFileContent | null> => {
+      if (entry.type !== "git" || !entry.gitUrl || !token) return null;
+
+      const parsed = parseGitUrl(entry.gitUrl);
+      if (!parsed) return null;
+
+      const branch = entry.gitBranch || "main";
+      const url =
+        `${GITHUB_API}/${parsed.owner}/${parsed.repo}/contents/${encodePath(path)}` +
+        `?ref=${encodeURIComponent(branch)}`;
+
+      const resp = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (!resp.ok) {
+        throw new Error(
+          `GitHub content fetch failed for ${path} (HTTP ${resp.status})`,
+        );
+      }
+
+      const data: unknown = await resp.json();
+      // The Contents API returns an array for a directory — a misdirected read,
+      // not an unsupported substrate, so fail loudly rather than return null.
+      if (Array.isArray(data)) {
+        throw new Error(`Cannot read "${path}": path is a directory`);
+      }
+
+      const file = data as GitHubContentsFile;
+      if (file.encoding === "base64") {
+        return normalizeGitHubContent(base64ToBytes(file.content), file.size);
+      }
+
+      // encoding: "none" is GitHub's signal that the file exceeds the Contents
+      // API's ~1 MB cap; the bytes live only behind the Blob API.
+      return readViaBlob(parsed, file, token);
+    },
+    [token],
+  );
+
+  if (!token) return undefined;
+  return reader;
+}
+
+/**
+ * Gate 1 / Option B — size-gated blob fetch for files the Contents API refused
+ * (`encoding: "none"`). Isolated so the large-file policy can change without
+ * touching the reader's control flow.
+ */
+async function readViaBlob(
+  parsed: { owner: string; repo: string },
+  file: GitHubContentsFile,
+  token: string,
+): Promise<WorkspaceFileContent> {
+  // Above the ceiling we never download — GitHub already told us the size, so
+  // report it as too-large-to-preview without spending the bandwidth.
+  if (file.size > BLOB_FETCH_CEILING_BYTES) {
+    return {
+      text: null,
+      isBinary: false,
+      size: file.size,
+      encoding: "none",
+      truncated: true,
+    };
+  }
+
+  const url = `${GITHUB_API}/${parsed.owner}/${parsed.repo}/git/blobs/${file.sha}`;
+  const resp = await fetch(url, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!resp.ok) {
+    throw new Error(`GitHub blob fetch failed for ${file.sha} (HTTP ${resp.status})`);
+  }
+
+  const blob: GitHubBlob = await resp.json();
+  return normalizeGitHubContent(base64ToBytes(blob.content), blob.size);
+}

package/src/github/useGitHubTreeLister.ts

@@ -22,12 +22,16 @@ interface GitHubTreeResponse {
 }
 
 /**
- * Sentinel entry appended to the listing when the GitHub API indicates
- * that the tree was truncated (repository exceeds the API's entry limit).
+ * Advisory entry appended to the listing when the GitHub API indicates that the
+ * tree was truncated (repository exceeds the API's entry limit). Flagged with
+ * `notice: true` so generic consumers treat it as a "results incomplete" banner
+ * rather than an openable file (see `workspaceListingCache`) — never a tree leaf,
+ * never a search hit.
  */
 const TRUNCATION_MARKER: WorkspaceFileEntry = {
   path: "... (tree truncated by GitHub — repository has too many files)",
   isDirectory: false,
+  notice: true,
 };
 
 /**